proposal: cross-boundary text operations

AGENTS.md

@@ -0,0 +1,18 @@
+<!-- OPENSPEC:START -->
+# OpenSpec Instructions
+
+These instructions are for AI assistants working in this project.
+
+Always open `@/openspec/AGENTS.md` when the request:
+- Mentions planning or proposals (words like proposal, spec, change, plan)
+- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
+- Sounds ambiguous and you need the authoritative spec before coding
+
+Use `@/openspec/AGENTS.md` to learn:
+- How to create and apply change proposals
+- Spec format and conventions
+- Project structure and guidelines
+
+Keep this managed block so 'openspec update' can refresh the instructions.
+
+<!-- OPENSPEC:END -->

CLAUDE.md

@@ -1,3 +1,22 @@
+<!-- OPENSPEC:START -->
+# OpenSpec Instructions
+
+These instructions are for AI assistants working in this project.
+
+Always open `@/openspec/AGENTS.md` when the request:
+- Mentions planning or proposals (words like proposal, spec, change, plan)
+- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
+- Sounds ambiguous and you need the authoritative spec before coding
+
+Use `@/openspec/AGENTS.md` to learn:
+- How to create and apply change proposals
+- Spec format and conventions
+- Project structure and guidelines
+
+Keep this managed block so 'openspec update' can refresh the instructions.
+
+<!-- OPENSPEC:END -->
+
 # Claude Instructions for docx-editor
 
 ## Quick Reference

Makefile

@@ -16,7 +16,7 @@ check: ## Run code quality tools.
 .PHONY: test
 test: ## Test the code with pytest
 	@echo "🚀 Testing code: Running pytest"
-	@uv run python -m pytest --cov --cov-config=pyproject.toml --cov-report=xml
+	@uv run python -m pytest tests -n auto --cov --cov-config=pyproject.toml --cov-report=xml
 
 .PHONY: build
 build: clean-build ## Build wheel file

README.md

@@ -16,6 +16,8 @@ Pure Python library for Word document track changes and comments, without requir
 ## Features
 
 - **Track Changes**: Replace, delete, and insert text with revision tracking
+- **Cross-Boundary Editing**: Find and replace text spanning multiple XML elements and revision boundaries
+- **Mixed-State Editing**: Atomic decomposition for text spanning `<w:ins>`/`<w:del>` boundaries
 - **Comments**: Add, reply, resolve, and delete comments
 - **Revision Management**: List, accept, and reject tracked changes
 - **Cross-Platform**: Works on Linux, macOS, and Windows
@@ -48,6 +50,28 @@ with Document.open("contract.docx") as doc:
     doc.save()
 ```
 
+### Cross-Boundary Text Operations
+
+Text in Word documents with tracked changes can span revision boundaries. `docx-editor` handles this transparently:
+
+```python
+from docx_editor import Document
+
+with Document.open("reviewed.docx") as doc:
+    # Get visible text (inserted text included, deleted excluded)
+    text = doc.get_visible_text()
+
+    # Find text across element boundaries
+    match = doc.find_text("Aim: To")
+    if match and match.spans_boundary:
+        print("Text spans a revision boundary")
+
+    # Replace works even across revision boundaries
+    doc.replace("Aim: To", "Goal: To")
+
+    doc.save()
+```
+
 ## Claude Code Skill
 
 This repo includes a skill for [Claude Code](https://claude.ai/claude-code) that enables AI-assisted Word document editing.

docx_editor/__init__.py

@@ -45,6 +45,7 @@
     XMLError,
 )
 from .track_changes import Revision
+from .xml_editor import TextMap, TextMapMatch, TextPosition, build_text_map, find_in_text_map
 
 __all__ = [
     # Main classes
@@ -64,4 +65,10 @@
     "RevisionError",
     "CommentError",
     "TextNotFoundError",
+    # Text map
+    "TextPosition",
+    "TextMap",
+    "TextMapMatch",
+    "build_text_map",
+    "find_in_text_map",
 ]

docx_editor/document.py

@@ -12,7 +12,7 @@
 from .exceptions import WorkspaceSyncError
 from .track_changes import Revision, RevisionManager
 from .workspace import Workspace
-from .xml_editor import DocxXMLEditor
+from .xml_editor import DocxXMLEditor, build_text_map
 
 
 class Document:
@@ -117,6 +117,14 @@ def source_path(self) -> Path:
 
     # ==================== Track Changes API ====================
 
+    def find_text(self, text: str, occurrence: int = 0):
+        """Find text in the document, including across element boundaries.
+
+        Returns match info or None if not found.
+        """
+        self._ensure_open()
+        return self._revision_manager._find_across_boundaries(text, occurrence)
+
     def count_matches(self, text: str) -> int:
         """Count how many times a text string appears in the document.
 
@@ -137,6 +145,23 @@ def count_matches(self, text: str) -> int:
         self._ensure_open()
         return self._revision_manager.count_matches(text)
 
+    def get_visible_text(self) -> str:
+        """Get the visible text of the document.
+
+        Returns flattened text with paragraphs separated by newlines.
+        Inserted text is included, deleted text is excluded.
+
+        Returns:
+            The visible text content
+        """
+        self._ensure_open()
+        paragraphs = self._document_editor.dom.getElementsByTagName("w:p")
+        parts = []
+        for p in paragraphs:
+            tm = build_text_map(p)
+            parts.append(tm.text)
+        return "\n".join(parts)
+
     def replace(self, find: str, replace_with: str, occurrence: int = 0) -> int:
         """Replace text with tracked changes.