@ansonlai/docx-redline-js 0.5.3 → 0.6.0

package/docs/TESTING.md

@@ -22,7 +22,10 @@ fixtures rarely contain.
 | Multimodal LLM visual spot check | On-demand / sampled | Evaluates rendered real-document pages with vision models for layout, table alignment, and typography regressions | Full-corpus automated coverage (intentionally decoupled and sampled due to cost/time) |
 | XSD and LibreOffice | See [Release validation and independent oracles](#release-validation-and-independent-oracles) | Schema conformance and acceptance by a second consumer | Word-specific revision semantics |
 | Agent inspection and package facade | `node tests/document_inspection_tests.mjs`, `node tests/docx_package_facade_tests.mjs` | Canonical text, comment/list resolution, package-scoped IDs, untouched-part preservation, and atomic rollback | Desktop Word rendering |
-| Agent CLI | `node tests/agent_cli_tests.mjs` | JSON contracts, exact-text extraction, author requirements, safe output behavior, all command families, and operation-schema readability | Cross-platform CI beyond the current runner |
+| Agent CLI | `node tests/agent_cli_tests.mjs`, `node tests/agent_cli_protocol_tests.mjs` | JSON contracts, exact-text extraction, stdin operations, named agent-profile defaults, UTF-8 fidelity, complete-success exits, source safety, all command families, and operation-schema readability | Cross-platform CI beyond the current runner |
+| Example agent session | `node tests/agent_session_example_tests.mjs`, `node tests/localized_edit_example_tests.mjs` | A non-package sample wrapper delegates to the Node facade, binds and refreshes opaque handles across package revisions, returns context windows, compiles exact localized edits, preserves accepted/rejected lifecycle and atomic rollback, and supports review resolution | LLM/provider latency or a production tool-server transport |
+| Batch compilation and recovery | `node tests/batch_source_binding_tests.mjs`, `node tests/error_recovery_contract_tests.mjs`, `node tests/capture_dependency_graph_tests.mjs` | Batch-start source identity survives structural index drift and savepoint restoration; true overlap and capture fan-out fail before mutation; recovery envelopes, retry bases, bounded CLI diagnostics, and complete-success exits remain stable | Whether a model follows the returned recovery action correctly |
+| Agent documentation contract | `node tests/agent_documentation_contract_tests.mjs` | The ordinary fast start stays within its 40–60 line/600-word budget, retains required safety contracts, and the launch card routes to detailed sources while the development wrapper stays outside package files | Whether a particular model reads or follows the instructions |
 | Agent edge cases | `node tests/canonical_paragraph_text_tests.mjs`, `node tests/document_inspection_edge_tests.mjs`, `node tests/docx_package_transaction_edge_tests.mjs`, `node tests/node_zip_archive_tests.mjs`, `node tests/agent_cli_edge_tests.mjs` | Revision-view semantics, cross-paragraph anchors, nested numbering, transaction reuse, multi-author cleanup, malformed ZIP handling, and destructive CLI safeguards | Desktop Word rendering and non-Windows CI |
 | Performance boundary regression | `node tests/performance_phase2_boundary_tests.mjs` | Stable facade re-exports, leaf imports, session rollback, isolated context commit, and comment-first scheduling | The Phase 1 one-parse/one-serialize performance target |
 | Live-session accuracy and instrumentation | `node tests/performance_phase1_session_tests.mjs` | One full parse/serialization, sequential semantic equivalence, exact accepted/rejected text, valid revisions, list/table/comment/highlight preservation, savepoint no-ops, and zero-serialization rollback | Desktop Word rendering |
@@ -79,6 +82,22 @@ not correctness gates. Per-operation DOM savepoints are retained because
 redline accuracy, no-op isolation, and rollback fidelity take precedence over
 the aspirational speed target.
 
+Run the observational agent-protocol benchmark with:
+
+```powershell
+npm run benchmark:agent
+```
+
+It writes `tmp/benchmarks/agent-workflow-latest.json` and compares canonical
+stateless Node, legacy file-based CLI, compact stdin/profile CLI, and the
+development-only session example. It records native/in-process CLI time, heap,
+serialized request bytes, protocol calls, instruction words/bytes, exact
+accepted/rejected text, comment preservation, ordering, recovery, and
+cross-author attribution. It does not measure or estimate LLM reasoning, exact
+tokens, tool transport, Claude, or OpenCode wall time; collect those separately
+in the calling harness. The checked WP-07 results are summarized in the
+[agent protocol rollout audit](validation-reports/2026-09-12-agent-protocol-rollout.md).
+
 ## Cross-author revision slicing test suite
 
 The cross-author revision slicing subsystem introduces six complementary test lanes:

package/docs/schemas/document-operations.schema.json

@@ -28,6 +28,16 @@
       "additionalProperties": false
     },
     "operationArray": { "type": "array", "items": { "$ref": "#/$defs/operation" } },
+    "rejectedTextInsertionAnchor": {
+      "type": "object",
+      "required": ["exactText", "offset"],
+      "properties": {
+        "exactText": { "type": "string", "minLength": 1 },
+        "occurrence": { "type": "integer", "minimum": 1 },
+        "offset": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": false
+    },
     "target": {
       "oneOf": [
         { "type": "string", "minLength": 1 },
@@ -38,7 +48,11 @@
             "index": { "type": ["integer", "string"] }, "paragraphIndex": { "type": ["integer", "string"] },
             "paragraphId": { "type": "string" }, "occurrence": { "type": "integer", "minimum": 1 },
             "inTable": { "type": "boolean" }, "fingerprint": { "type": "string" }, "sourceFingerprint": { "type": "string" },
-            "revisionView": { "type": "string", "enum": ["accepted", "rejected"] },
+            "revisionView": {
+              "type": "string",
+              "enum": ["accepted", "rejected"],
+              "description": "Defaults to rejected for restore operations and accepted for other operation types."
+            },
             "captureRef": { "type": "string", "minLength": 1, "maxLength": 256 },
             "select": { "type": "string", "minLength": 1 }
           },
@@ -86,7 +100,7 @@
           "additionalProperties": false
         },
         {
-          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["modified"], "properties": { "type": { "enum": ["redline", "replace", "format", "list-change", "table-reconciliation", "insert"] }, "modified": { "type": "string" }, "structuredContent": { "type": "boolean" }, "targetEnd": { "$ref": "#/$defs/target" }, "targetEndRef": { "type": ["integer", "string", "null"] } } } ]
+          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["modified"], "properties": { "type": { "enum": ["redline", "replace", "format", "list-change", "table-reconciliation", "insert"] }, "modified": { "type": "string" }, "structuredContent": { "type": "boolean" }, "targetEnd": { "$ref": "#/$defs/target" }, "targetEndRef": { "type": ["integer", "string", "null"] }, "anchor": { "$ref": "#/$defs/rejectedTextInsertionAnchor" } } } ]
         },
         {
           "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["modified"], "properties": { "type": { "const": "restore" }, "modified": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } } ] }, "targetEnd": { "$ref": "#/$defs/target" }, "targetEndRef": { "type": ["integer", "string", "null"] } } } ]

package/docs/validation-reports/2026-09-12-agent-protocol-rollout.md

@@ -0,0 +1,82 @@
+# Agent Protocol Rollout Audit
+
+**Date:** 2026-09-12  
+**Scope:** WP-06 shell/documentation work and WP-07 repository-level rollout  
+**Benchmark:** `npm run benchmark:agent` on Node v24.11.1 / Windows x64,
+7 measured iterations after 2 warmups
+
+## Outcome
+
+The compact shell path removes the operations-file tool turn, and the
+development session example removes repeated target/policy payload. All measured
+paths produced the requested accepted view, restored the exact source text in
+the rejected view, passed package/revision validation, and preserved comment
+content. These are protocol and native-runtime measurements; no LLM/provider
+latency or token count was estimated.
+
+| Measure | Legacy | WP-06/07 result |
+|---|---:|---:|
+| Ordinary agent instructions | 2,023 words | 349 words (82.75% reduction) |
+| Repository launch card | 2,023 words | 527 words |
+| Shell workflow calls | extract + file write + apply (3) | extract + stdin apply (2; 33.33% reduction) |
+| Independent early-split permutations | one previously order-sensitive direction | both directions succeed |
+
+## Measured workflow results
+
+Median wall time includes the in-process CLI file/stdin transport for CLI rows.
+It does not include process startup, a model, provider tokenization, or tool
+transport.
+
+| Case | Legacy CLI | Compact stdin CLI | Session example | Session request bytes vs legacy |
+|---|---:|---:|---:|---:|
+| Terminal punctuation | 49.63 ms | 46.05 ms | 49.50 ms | 125 vs 255 (50.98% fewer) |
+| Term-duration phrase | 55.50 ms | 51.30 ms | 56.05 ms | 128 vs 630 (79.68% fewer) |
+| Simple mutuality | 62.82 ms | 50.22 ms | 58.45 ms | 281 vs 935 (69.95% fewer) |
+| Full-clause rewrite | 50.55 ms | 50.31 ms | 53.81 ms | 223 vs 407 (45.21% fewer) |
+| Comment + redline | 71.94 ms | 62.11 ms | 63.81 ms | 290 vs 724 (59.94% fewer) |
+
+Compared with the canonical stateless Node request envelope, localized session
+requests remained 86.11% smaller for punctuation, 89.96% smaller for a duration
+change, and 82.22% smaller for deterministic mutuality. A complete clause
+rewrite is naturally less compressible and is not presented as a localized-edit
+win.
+
+## Fidelity and recovery audit
+
+- The benchmark validates accepted and rejected paragraph text for every text
+  edit and verifies the mixed-batch comment definition remains present.
+- Both ten-edit permutations around an early paragraph split complete without
+  target errors.
+- An ambiguous target returns two candidates without auto-selection.
+- A stale session handle returns `STALE_TARGET_HANDLE` with recovery action
+  `reinspect`.
+- The default cross-author policy refuses the edit with `EXISTING_REVISIONS`.
+  `slice-cross-author` succeeds while retaining both original authors (Anson
+  Lai and John Doe), and rejecting the benchmark author's work still retains
+  those authors.
+- The CLI protocol regression proves UTF-8 stdin transport, package-revision
+  enforcement, source immutability, agent-profile defaults, atomic rollback,
+  progressive exit code 3, and rejected-view restoration.
+
+## Configuration decision
+
+No project or auto-discovered configuration file was added. The CLI already
+defaults author, strict targeting, validation, tracked changes, revision safety,
+and output naming. The explicit `--profile agent` flag captures the remaining
+atomic/complete-success policy and reports `effectiveOptions`. Removing that one
+flag would not justify hidden configuration discovery or precedence reasoning.
+
+## Remaining external measurement
+
+Claude/OpenCode wall time, prompt tokens, generated tokens, and provider tool
+latency must be captured by those calling harnesses. The repository benchmark
+records bytes, words, calls, native time, failure behavior, and document
+fidelity so those external observations can be compared without conflating the
+library with model reasoning.
+
+## Automated verification
+
+- `npm test`: 107 passed, 0 failed.
+- `npm run check:types`: 123 runtime exports have declarations.
+- `npm run test:isolation`: core dependency and Word-API isolation passed.
+- Focused ESLint for all WP-06/07 source, benchmark, and test files passed.

package/engine/oxml-engine.js

@@ -28,7 +28,8 @@ import { applySurgicalMode } from './surgical-mode.js';
 import { applyReconstructionMode } from './reconstruction-mode.js';
 import { applyTableReconciliation, applyTextToTableTransformation } from './table-mode.js';
 import { getDefaultAuthor } from '../adapters/config.js';
-import { containsTrackedChanges, getTrackedChangeAuthors, withOoxmlSourceType } from '../core/word-xml.js';
+import { containsTrackedChanges, createWordElement, getTrackedChangeAuthors, withOoxmlSourceType } from '../core/word-xml.js';
+import { clonePropertiesWithoutRevisionHistory } from '../core/revision-cloning.js';
 import {
     NS_W,
     RevisionIdAllocator,
@@ -52,6 +53,62 @@ function getCommentIdsInOoxml(node) {
     }
     return [...ids].sort((a, b) => Number(a) - Number(b) || a.localeCompare(b));
 }
+
+function directWordChild(node, localName) {
+    return Array.from(node?.childNodes || []).find(child => (
+        child?.nodeType === 1
+        && child.namespaceURI === NS_W
+        && child.localName === localName
+    )) || null;
+}
+
+function insertedParagraphMarkMetadata(paragraph, author) {
+    const marker = directWordChild(directWordChild(directWordChild(paragraph, 'pPr'), 'rPr'), 'ins');
+    if (!marker) return null;
+    const markerAuthor = marker.getAttribute('w:author') || marker.getAttributeNS(NS_W, 'author') || '';
+    if (markerAuthor.trim().toLowerCase() !== String(author || '').trim().toLowerCase()) return null;
+    return {
+        id: marker.getAttribute('w:id') || marker.getAttributeNS(NS_W, 'id') || '',
+        author: markerAuthor,
+        date: marker.getAttribute('w:date') || marker.getAttributeNS(NS_W, 'date') || ''
+    };
+}
+
+function emptyParagraphBaseline(paragraph, serializer) {
+    const clone = paragraph.cloneNode(false);
+    const pPr = directWordChild(paragraph, 'pPr');
+    if (pPr) clone.appendChild(clonePropertiesWithoutRevisionHistory(pPr));
+    return serializer.serializeToString(clone);
+}
+
+function restoreInsertedParagraphMark(oxml, metadata) {
+    if (!metadata || typeof oxml !== 'string' || !oxml.trim()) return oxml;
+    const parsed = parseOoxmlSafe(oxml, 'text/xml');
+    if (!parsed.doc || parsed.error) return oxml;
+    const paragraph = parsed.doc.documentElement?.localName === 'p'
+        ? parsed.doc.documentElement
+        : getDocumentParagraphs(parsed.doc)[0];
+    if (!paragraph) return oxml;
+
+    let pPr = directWordChild(paragraph, 'pPr');
+    if (!pPr) {
+        pPr = createWordElement(parsed.doc, 'w:pPr');
+        paragraph.insertBefore(pPr, paragraph.firstChild);
+    }
+    let rPr = directWordChild(pPr, 'rPr');
+    if (!rPr) {
+        rPr = createWordElement(parsed.doc, 'w:rPr');
+        pPr.appendChild(rPr);
+    }
+    if (!directWordChild(rPr, 'ins')) {
+        const marker = createWordElement(parsed.doc, 'w:ins');
+        if (metadata.id) marker.setAttribute('w:id', metadata.id);
+        marker.setAttribute('w:author', metadata.author);
+        if (metadata.date) marker.setAttribute('w:date', metadata.date);
+        rPr.appendChild(marker);
+    }
+    return serializeXml(parsed.doc);
+}
 
 /**
  * Applies redline track changes to OOXML by modifying the DOM in-place.
@@ -77,11 +134,12 @@ export async function applyRedlineToOxml(oxml, originalText, modifiedText, optio
     const serializer = createSerializer();
     let parseWarnings = [];
     const operationWarnings = [];
-    let normalizedExistingRevisions = false;
+    let normalizedExistingRevisions = false;
+    let preservedInsertedParagraphMark = null;
     const existingRevisionsPolicy = options.existingRevisions || 'merge-same-author';
     const keepNormalizedNoOp = existingRevisionsPolicy === 'accept-all-first-keep-normalized';
-    const finalize = result => {
-        const withStatus = { ...result };
+    const finalize = result => {
+        const withStatus = { ...result };
         if (normalizedExistingRevisions && withStatus.hasChanges === false && withStatus.status !== 'error') {
             if (existingRevisionsPolicy === 'merge-same-author' || existingRevisionsPolicy === 'slice-cross-author') {
                 withStatus.oxml = workingOoxml;
@@ -105,10 +163,13 @@ export async function applyRedlineToOxml(oxml, originalText, modifiedText, optio
         if (warnings.length > 0) {
             withStatus.warnings = [...new Set(warnings)];
         }
-        if (!withStatus.status) {
-            withStatus.status = withStatus.hasChanges ? 'ok' : 'no-op';
-        }
-        return withOoxmlSourceType(withStatus);
+        if (!withStatus.status) {
+            withStatus.status = withStatus.hasChanges ? 'ok' : 'no-op';
+        }
+        if (preservedInsertedParagraphMark && withStatus.hasChanges && typeof withStatus.oxml === 'string') {
+            withStatus.oxml = restoreInsertedParagraphMark(withStatus.oxml, preservedInsertedParagraphMark);
+        }
+        return withOoxmlSourceType(withStatus);
     };
     const finalizeUnchanged = () => {
         if (normalizedExistingRevisions && keepNormalizedNoOp) {
@@ -181,9 +242,13 @@ export async function applyRedlineToOxml(oxml, originalText, modifiedText, optio
                     });
                 }
                 log('[OxmlEngine] Existing revisions from same author detected; rejecting previous changes to merge against baseline');
-                const rejected = rejectTrackedChangesInOoxml(inputOoxml, { author });
-                if (rejected.status === 'error') return finalize(rejected);
-                workingOoxml = rejected.oxml;
+                const soleParagraph = inputParagraphs.length === 1 ? inputParagraphs[0] : null;
+                preservedInsertedParagraphMark = insertedParagraphMarkMetadata(soleParagraph, author);
+                const rejected = rejectTrackedChangesInOoxml(inputOoxml, { author });
+                if (rejected.status === 'error') return finalize(rejected);
+                workingOoxml = preservedInsertedParagraphMark && !String(rejected.oxml || '').trim()
+                    ? emptyParagraphBaseline(soleParagraph, serializer)
+                    : rejected.oxml;
                 normalizedExistingRevisions = true;
                 const rejectedParsed = parseOoxmlSafe(workingOoxml, 'text/xml');
                 parseWarnings.push(...rejectedParsed.warnings);
@@ -230,8 +295,10 @@ export async function applyRedlineToOxml(oxml, originalText, modifiedText, optio
                     hasChanges: false,
                     status: 'error',
                     error: {
-                        code: 'EXISTING_REVISIONS',
-                        message: `Input OOXML contains tracked changes from another author (${authors.length ? authors.join(', ') : 'unattributed'}). Pass existingRevisions: "accept-all-first" or resolve revisions first.`
+                        code: 'EXISTING_REVISIONS',
+                        message: `Input OOXML contains tracked changes from another author (${authors.length ? authors.join(', ') : 'unattributed'}). Use existingRevisions: "slice-cross-author" for a surgical edit that preserves reviewer history; accepting or rejecting revisions requires separate authorization.`,
+                        revisionAuthors: authors,
+                        currentPolicy: existingRevisionsPolicy
                     }
                 });
             } else {

package/engine/run-builders.js

@@ -9,6 +9,7 @@ import { extractFormatFromRPr, RPR_SCHEMA_ORDER } from './rpr-helpers.js';
 import { createRevisionMetadata } from '../core/types.js';
 import { getFirstElementByTag } from '../core/xml-query.js';
 import { createWordElement } from '../core/word-xml.js';
+import { clonePropertiesWithoutRevisionHistory } from '../core/revision-cloning.js';
 
 /**
  * Creates an insertion/deletion wrapper.
@@ -319,14 +320,9 @@ export function snapshotAndAttachRPrChange(xmlDoc, rPr, author, dateStr, sourceN
     rPrChange.setAttribute('w:author', metadata.author);
     rPrChange.setAttribute('w:date', dateStr || metadata.date);
 
-    const previousRPr = createWordElement(xmlDoc, 'w:rPr');
     const source = sourceNode || rPr;
-
-    Array.from(source.childNodes).forEach(child => {
-        if (child.nodeName !== 'w:rPrChange') {
-            previousRPr.appendChild(child.cloneNode(true));
-        }
-    });
+    const previousRPr = clonePropertiesWithoutRevisionHistory(source)
+        || createWordElement(xmlDoc, 'w:rPr');
 
     rPrChange.appendChild(previousRPr);
 
@@ -369,14 +365,9 @@ export function snapshotAndAttachPPrChange(xmlDoc, pPr, author, dateStr, sourceN
     pPrChange.setAttribute('w:author', metadata.author);
     pPrChange.setAttribute('w:date', dateStr || metadata.date);
 
-    const previousPPr = createWordElement(xmlDoc, 'w:pPr');
     const source = sourceNode || pPr;
-
-    Array.from(source.childNodes).forEach(child => {
-        if (child.nodeType === 1 && child.nodeName !== 'w:pPrChange' && child.localName !== 'pPrChange') {
-            previousPPr.appendChild(child.cloneNode(true));
-        }
-    });
+    const previousPPr = clonePropertiesWithoutRevisionHistory(source)
+        || createWordElement(xmlDoc, 'w:pPr');
 
     pPrChange.appendChild(previousPPr);
 
@@ -390,4 +381,3 @@ export function snapshotAndAttachPPrChange(xmlDoc, pPr, author, dateStr, sourceN
     pPr.appendChild(pPrChange);
     return pPrChange;
 }
-

package/engine/surgical-mode.js

@@ -6,7 +6,7 @@
  */
 
 import { getApplicableFormatHints } from '../pipeline/markdown-processor.js';
-import { computeInsertionOnlyDiffs, computeWordDiffs } from '../pipeline/diff-engine.js';
+import { computeCharacterDiffs, computeInsertionOnlyDiffs, computeWordDiffs } from '../pipeline/diff-engine.js';
 import { getDocumentParagraphs } from './format-extraction.js';
 import { buildSpanIndex, buildSurgicalTextSpans, forEachOverlappingSpan } from './surgical-spans.js';
 import {
@@ -115,7 +115,10 @@ export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer
     const insertionOnlyDiffs = options.existingRevisions === 'slice-cross-author'
         ? computeInsertionOnlyDiffs(fullText, modifiedText)
         : null;
-    const diffs = insertionOnlyDiffs || computeWordDiffs(fullText, modifiedText, diffOptions);
+    const diffs = insertionOnlyDiffs || refineSpaceEquivalentReplacements(
+        computeWordDiffs(fullText, modifiedText, diffOptions),
+        diffOptions
+    );
     const spanIndex = buildSpanIndex(textSpans);
     const pairReplacements = options.pairReplacements === true;
     const warnings = [];
@@ -157,6 +160,84 @@ export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer
             }
             if (insertResult === true) hasChanges = true;
         }
+    } else if (formatHints.length === 0) {
+        const editOperations = collectTextEditOperations(diffs);
+        for (const operation of editOperations.reverse()) {
+            const liveSpanIndex = buildSpanIndex(buildSurgicalTextSpans(allParagraphs).textSpans);
+            if (operation.type === 'insert') {
+                const inserted = processInsert(
+                    xmlDoc,
+                    liveSpanIndex,
+                    operation.start,
+                    operation.text.replace(/\n/g, ' '),
+                    author,
+                    formatHints,
+                    operation.newPos,
+                    generateRedlines,
+                    allParagraphs[0] || null,
+                    null,
+                    options?.insertionAffinity || null,
+                    options?.existingRevisions || 'merge-same-author'
+                );
+                if (inserted && typeof inserted === 'object' && inserted.error) {
+                    return withOoxmlSourceType({
+                        oxml: serializer.serializeToString(xmlDoc),
+                        hasChanges: false,
+                        status: 'error',
+                        error: inserted.error
+                    });
+                }
+                if (inserted === true) hasChanges = true;
+                continue;
+            }
+
+            let delMetadata = null;
+            let insMetadata = null;
+            if (operation.type === 'replace' && pairReplacements && generateRedlines && operation.text.replace(/\n/g, ' ')) {
+                const checkResult = checkSafeAdjacencyForPairing(
+                    liveSpanIndex,
+                    operation.start,
+                    operation.end,
+                    options?.existingRevisions === 'slice-cross-author'
+                );
+                if (checkResult.safe) {
+                    const event = createReplacementRevisionEvent(author, xmlDoc);
+                    delMetadata = { id: event.deletionId, author: event.author, date: event.date };
+                    insMetadata = { id: event.insertionId, author: event.author, date: event.date };
+                } else if (checkResult.structuralBoundary) {
+                    warnings.push('PAIRING_SKIPPED_STRUCTURAL_BOUNDARY');
+                }
+            }
+
+            if (processDelete(xmlDoc, liveSpanIndex, operation.start, operation.end, author, generateRedlines, delMetadata)) {
+                hasChanges = true;
+            }
+            if (operation.type === 'replace') {
+                const inserted = processInsert(
+                    xmlDoc,
+                    liveSpanIndex,
+                    operation.end,
+                    operation.text.replace(/\n/g, ' '),
+                    author,
+                    formatHints,
+                    operation.newPos,
+                    generateRedlines,
+                    allParagraphs[0] || null,
+                    insMetadata,
+                    options?.insertionAffinity || null,
+                    options?.existingRevisions || 'merge-same-author'
+                );
+                if (inserted && typeof inserted === 'object' && inserted.error) {
+                    return withOoxmlSourceType({
+                        oxml: serializer.serializeToString(xmlDoc),
+                        hasChanges: false,
+                        status: 'error',
+                        error: inserted.error
+                    });
+                }
+                if (inserted === true) hasChanges = true;
+            }
+        }
     } else {
 
       for (let i = 0; i < diffs.length; i++) {
@@ -267,7 +348,9 @@ export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer
                 message: 'Generated OOXML accepted-view text does not match the requested modified text; the mutation was rejected.',
                 mismatchOffset,
                 expectedExcerpt: excerptAt(expectedText, mismatchOffset),
-                actualExcerpt: excerptAt(actualText, mismatchOffset)
+                actualExcerpt: excerptAt(actualText, mismatchOffset),
+                expectedCodePoint: codePointAtOffset(expectedText, mismatchOffset),
+                actualCodePoint: codePointAtOffset(actualText, mismatchOffset)
             },
             ...(warnings.length > 0 ? { warnings: [...new Set(warnings)] } : {})
         });
@@ -294,6 +377,68 @@ function excerptAt(text, offset, radius = 40) {
     return text.slice(start, end);
 }
 
+function codePointAtOffset(text, offset) {
+    if (offset >= text.length) return 'END';
+    return `U+${text.codePointAt(offset).toString(16).toUpperCase().padStart(4, '0')}`;
+}
+
+function refineSpaceEquivalentReplacements(diffs, diffOptions) {
+    const refined = [];
+    for (let index = 0; index < diffs.length; index++) {
+        const [op, text] = diffs[index];
+        const next = diffs[index + 1];
+        if (
+            op === -1
+            && next?.[0] === 1
+            && text !== next[1]
+            && text.length === next[1].length
+            && text.replace(/\u00a0/g, ' ') === next[1].replace(/\u00a0/g, ' ')
+        ) {
+            refined.push(...computeCharacterDiffs(text, next[1], diffOptions));
+            index++;
+            continue;
+        }
+        refined.push([op, text]);
+    }
+    return refined;
+}
+
+function collectTextEditOperations(diffs) {
+    const operations = [];
+    let originalPos = 0;
+    let newPos = 0;
+    for (let index = 0; index < diffs.length; index++) {
+        const [op, text] = diffs[index];
+        if (op === 0) {
+            originalPos += text.length;
+            newPos += text.length;
+            continue;
+        }
+        if (op === -1) {
+            const next = diffs[index + 1];
+            if (next?.[0] === 1) {
+                operations.push({
+                    type: 'replace',
+                    start: originalPos,
+                    end: originalPos + text.length,
+                    newPos,
+                    text: next[1]
+                });
+                originalPos += text.length;
+                newPos += next[1].length;
+                index++;
+            } else {
+                operations.push({ type: 'delete', start: originalPos, end: originalPos + text.length, newPos, text: '' });
+                originalPos += text.length;
+            }
+            continue;
+        }
+        operations.push({ type: 'insert', start: originalPos, end: originalPos, newPos, text });
+        newPos += text.length;
+    }
+    return operations;
+}
+
 function collectInsertionOperations(diffs) {
     const operations = [];
     let originalPos = 0;

package/engine/surgical-run-splitting.js

@@ -8,7 +8,7 @@ import {
 import { refreshRunPropertyChangeIds } from '../core/revision-cloning.js';
 import { getRunChildText, isTextLikeRunChild } from './surgical-spans.js';
 
-const TRACK_CHANGE_CARRIERS = new Set(['ins']);
+const TRACK_CHANGE_CARRIERS = new Set(['ins', 'del']);
 
 export function getRunContentPieces(runElement) {
     const pieces = [];
@@ -72,7 +72,7 @@ export function insertRunPiecesBefore(xmlDoc, parent, referenceNode, pieces, rPr
 }
 
 /**
- * Splits a run-level tracked-change carrier at an accepted-view character
+ * Splits a run-level tracked-change carrier at its visible-view character
  * offset without mutating the source carrier. The original revision ID stays
  * with the leading fragment; an interior trailing fragment receives a fresh,
  * document-scoped ID while all other carrier metadata remains unchanged.
@@ -86,7 +86,7 @@ export function insertRunPiecesBefore(xmlDoc, parent, referenceNode, pieces, rPr
 export function splitTrackChangeCarrier(xmlDoc, carrierElement, splitOffset, allocator = null) {
     const carrierName = getLocalName(carrierElement);
     if (!TRACK_CHANGE_CARRIERS.has(carrierName)) {
-        throw new TypeError('splitTrackChangeCarrier requires a w:ins carrier.');
+        throw new TypeError('splitTrackChangeCarrier requires a w:ins or w:del carrier.');
     }
     if (!Number.isInteger(splitOffset) || splitOffset < 0) {
         throw new RangeError('splitOffset must be a non-negative integer.');
@@ -129,17 +129,18 @@ export function splitTrackChangeCarrier(xmlDoc, carrierElement, splitOffset, all
         } else {
             const localOffset = splitOffset - offset;
             const rPr = Array.from(child.childNodes || []).find(node => isWordElement(node, 'rPr')) || null;
-            const leftPieces = sliceRunPieces(xmlDoc, pieces, 0, localOffset, false);
-            const rightPieces = sliceRunPieces(xmlDoc, pieces, localOffset, runLength, false);
+            const asDeletedText = carrierName === 'del';
+            const leftPieces = sliceRunPieces(xmlDoc, pieces, 0, localOffset, asDeletedText);
+            const rightPieces = sliceRunPieces(xmlDoc, pieces, localOffset, runLength, asDeletedText);
             leftCarrier.appendChild(createRunFromPieces(xmlDoc, leftPieces, rPr));
             const rightRun = createRunFromPieces(xmlDoc, rightPieces, rPr);
-            refreshRunPropertyChangeIds(rightRun, resolveAllocator(xmlDoc, allocator));
             rightCarrier.appendChild(rightRun);
         }
         offset = runEnd;
     }
 
     const resolvedAllocator = resolveAllocator(xmlDoc, allocator);
+    refreshRunPropertyChangeIds(rightCarrier, resolvedAllocator);
     const nextId = resolvedAllocator.next();
     setWordAttribute(rightCarrier, 'id', String(nextId));
     resolvedAllocator._receiptCollector?.recordRevision(nextId, carrierName);
@@ -166,7 +167,7 @@ function getLocalName(element) {
 }
 
 function cloneRunPiece(xmlDoc, sourceNode, text, asDeletedText) {
-    if (asDeletedText) {
+    if (asDeletedText && (isWordElement(sourceNode, 'delText') || isWordElement(sourceNode, 't'))) {
         const delText = createWordElement(xmlDoc, 'w:delText');
         delText.setAttribute('xml:space', 'preserve');
         delText.textContent = text;
@@ -192,6 +193,17 @@ function cloneRunPiece(xmlDoc, sourceNode, text, asDeletedText) {
         return sourceNode.cloneNode(true);
     }
 
+    if (text === '\u00ad' && isWordElement(sourceNode, 'softHyphen')) {
+        return sourceNode.cloneNode(true);
+    }
+
+    if (asDeletedText) {
+        const delText = createWordElement(xmlDoc, 'w:delText');
+        delText.setAttribute('xml:space', 'preserve');
+        delText.textContent = text;
+        return delText;
+    }
+
     const textNode = createWordElement(xmlDoc, 'w:t');
     textNode.setAttribute('xml:space', 'preserve');
     textNode.textContent = text;

package/engine/surgical-spans.js

@@ -3,7 +3,7 @@ import { getFirstElementByTag } from '../core/xml-query.js';
 import { isWordElement } from '../core/word-xml.js';
 
 export function getRunChildText(child) {
-    if (isWordElement(child, 't')) return child.textContent || '';
+    if (isWordElement(child, 't') || isWordElement(child, 'delText')) return child.textContent || '';
     if (isWordElement(child, 'br') || isWordElement(child, 'cr')) return '\n';
     if (isWordElement(child, 'tab')) return '\t';
     if (isWordElement(child, 'noBreakHyphen')) return '\u2011';
@@ -13,6 +13,7 @@ export function getRunChildText(child) {
 
 export function isTextLikeRunChild(child) {
     return isWordElement(child, 't')
+        || isWordElement(child, 'delText')
         || isWordElement(child, 'br')
         || isWordElement(child, 'cr')
         || isWordElement(child, 'tab')

package/index.d.ts

@@ -1,5 +1,5 @@
 export type OoxmlSourceType = 'package' | 'document' | 'fragment';
-export type RedlineStatus = 'ok' | 'no-op' | 'error';
+export type RedlineStatus = 'ok' | 'no-op' | 'partial' | 'error';
 export type ExistingRevisionsPolicy = 'merge-same-author' | 'slice-cross-author' | 'reject-input' | 'accept-all-first' | 'accept-all-first-keep-normalized';
 export type RevisionView = 'accepted' | 'rejected';
 
@@ -68,6 +68,22 @@ export interface RedlineError {
   actual?: unknown;
   commentIds?: string[];
   comments?: Array<{ id: string; author: string; text: string }>;
+  recoveryVersion?: number;
+  category?: 'request_fixable' | 'target_refresh_required' | 'candidate_selection_required' | 'policy_choice_required' | 'user_authorization_required' | 'source_conflict' | 'library_or_builder_failure' | 'manual_document_resolution' | string;
+  context?: Record<string, unknown>;
+  recovery?: {
+    action: string;
+    sameArgumentsSafe: boolean;
+    requiresReinspection: boolean;
+    requiresUserAuthorization: boolean;
+    field?: string;
+    recommendedValue?: unknown;
+  };
+  expectedRevision?: RevisionToken;
+  currentRevision?: RevisionToken;
+  issueSummary?: { total: number; byCode: Array<{ code: string; count: number }> };
+  candidates?: unknown[];
+  [key: string]: unknown;
 }
 
 export interface RedlineOptions {