@ansonlai/docx-redline-js 0.4.0 → 0.5.0

package/services/table-reconciliation.js

@@ -19,8 +19,13 @@ import { preprocessMarkdown } from '../pipeline/markdown-processor.js';
  * @returns {string} Complete w:tbl OOXML
  */
 export function generateTableOoxml(tableData, options = {}) {
-    const { generateRedlines = false, author = 'AI', revisionIdAllocator = null } = options;
-    const tableInsertMeta = generateRedlines ? createRevisionMetadata(author, revisionIdAllocator) : null;
+    const {
+        generateRedlines = false,
+        author = 'AI',
+        revisionIdAllocator = null,
+        trackAsBlock = false
+    } = options;
+    const tableInsertMeta = generateRedlines && trackAsBlock ? createRevisionMetadata(author, revisionIdAllocator) : null;
 
     // Determine number of columns
     const numCols = tableData.headers?.length || (tableData.rows?.[0]?.length || 1);
@@ -60,7 +65,7 @@ export function generateTableOoxml(tableData, options = {}) {
 
             // Build run model for the cell
             const runModel = [{
-                kind: generateRedlines ? RunKind.INSERTION : RunKind.TEXT,
+                kind: generateRedlines && !trackAsBlock ? RunKind.INSERTION : RunKind.TEXT,
                 text: cleanText,
                 rPrXml: isHeaderRow ? '<w:rPr><w:b/></w:rPr>' : '',
                 author,
@@ -80,9 +85,13 @@ export function generateTableOoxml(tableData, options = {}) {
             cellsXml += `<w:tc>${tcPr}${runsOoxml}</w:tc>`;
         }
 
-        // Row properties
-        const trPr = '<w:trPr/>';
-        rowsXml += `<w:tr>${trPr}${cellsXml}</w:tr>`;
+        // Keep each logical record intact across page boundaries. When a
+        // Markdown header is present, also mark it as a repeating Word table
+        // header so continuation pages retain their column labels.
+        const trPr = isHeaderRow
+            ? '<w:trPr><w:tblHeader/><w:cantSplit/></w:trPr>'
+            : '<w:trPr><w:cantSplit/></w:trPr>';
+        rowsXml += `<w:tr>${trPr}${cellsXml}</w:tr>`;
     }
 
     // Build the table

package/docs/VALIDATION.md

@@ -1,183 +0,0 @@
-# Validation
-
-This document is the release-validation reference. For the testing model and
-step-by-step instructions for adding cases, see [TESTING.md](./TESTING.md).
-
-This package works on OOXML strings and intentionally leaves `.docx` zip
-packaging to consumers (release *tooling* assembles minimal `.docx` fixtures
-with a script-local zip writer; the published library still has no zip
-dependency).
-
-The test suite verifies the accept/reject round-trip invariant using the
-library's own transforms. Because a shared misconception between the
-generator and the resolver would pass those tests silently, release
-validation adds **independent oracles**: Microsoft Word, LibreOffice, and
-the ECMA-376 schemas.
-
-## Automated Checks (every `npm test`)
-
-```bash
-npm test              # includes tests/roundtrip_fuzz_tests.mjs (seeded, deterministic)
-npm run test:isolation
-npm run check:types
-```
-
-The fuzz harness generates random paragraph structures and edits, then
-asserts the round-trip invariant plus `validateRedlineOoxml` on each case.
-Tune or reproduce with:
-
-```bash
-FUZZ_SEED=<seed> FUZZ_ITERATIONS=<n> node tests/roundtrip_fuzz_tests.mjs
-```
-
-A failing case prints its exact reproduction command.
-
-## Runtime Guardrail
-
-`validateRedlineOoxml(oxml)` (exported from `index.js`) runs the structural
-invariants at runtime and returns `{ valid, issues }`. Downstream packagers
-should call it before writing engine output into `word/document.xml`.
-
-## Export Fixtures
-
-```bash
-node scripts/export-validation-fixtures.mjs
-```
-
-Writes to `tmp/validation-docx/`, per case:
-
-- `<name>.document.xml` — generated `word/document.xml` payload
-- `<name>.docx` — minimal assembled package
-- `<name>.expected.json` — expected accept-all / reject-all plain text,
-  derived from edit *intent* (not from this library's transforms), so
-  external consumers act as independent oracles
-
-## Word Differential Check (Windows, desktop Word)
-
-```bash
-npm run test:word
-```
-
-For each fixture, desktop Word opens the `.docx`, confirms revisions are
-visible, runs **AcceptAllRevisions**, and compares the document text to the
-expected modified text; then reopens and runs **RejectAllRevisions** and
-compares to the original text. This is the strongest check available: Word
-itself resolves the revisions this library generated.
-
-`npm run test:word` exports the current English legal/administrative task
-catalogue to `tmp/word-validation/` before running the differential. Expected
-text is compared exactly by default; only Word's paragraph terminators are
-normalized. The 33-case catalogue includes reliability regressions for literal
-dollar/escape content, inline assistant-like text, leading whitespace,
-multi-paragraph replacement, preserving prior revisions on no-op, and atomic
-batch rollback after a later target failure. It also verifies that a document
-with a near-limit prior revision ID produces safe low-range IDs, and exercises
-bookmark/hyperlink adjacency, mixed formatted runs, content controls, table
-cells, structural tabs, locked complex fields, comments, footnotes/endnotes,
-headers/footers, and external hyperlinks with explicit structural-preservation
-assertions. The
-lower-level `npm run smoke:word:diff` remains available for an
-already-exported fixture directory.
-
-The older `npm run smoke:word -- path/to/file.docx` open-only smoke check
-remains available for ad-hoc files.
-
-## Schema Validation (ECMA-376 transitional XSD)
-
-```bash
-node scripts/export-validation-fixtures.mjs
-bash scripts/validate-fixtures-xsd.sh
-```
-
-Downloads (and caches in `.cache/ooxml-schemas/`) the transitional
-wordprocessingml schemas from ECMA-376 Part 4, patches the `xml:` namespace
-import to resolve offline, and validates every `*.document.xml` fixture with
-`xmllint`. Requires `curl`, `unzip`, and `xmllint` (`libxml2-utils` on
-Debian/Ubuntu; available on Windows via conda/msys).
-
-## LibreOffice Consumer Check
-
-```bash
-cd tmp/validation-docx
-soffice --headless --convert-to pdf --outdir converted *.docx
-```
-
-A second independent OOXML consumer parsing the fixtures without error.
-
-## Continuous Validation
-
-`.github/workflows/validation.yml` runs nightly (and on demand via
-`workflow_dispatch`):
-
-1. **xsd-schema** — exports fixtures and validates them against the
-   ECMA-376 transitional `wml.xsd`.
-2. **libreoffice** — exports fixtures and converts them with headless
-   LibreOffice.
-3. **fuzz-extended** — 20,000 fuzz round-trip cases with a date-derived
-   seed, so every night explores new inputs. A failure log includes the
-   exact `FUZZ_SEED` reproduction command.
-
-The Word differential check stays manual because it requires desktop Word;
-run it before tagging a release.
-
-## JavaScript Coverage Baseline
-
-```bash
-npm run test:coverage
-```
-
-The command runs the complete JavaScript test suite under c8 and prints a
-per-file report. Coverage answers “which implementation paths did the automated
-JavaScript tests execute?” It does not prove that executed paths are correct,
-that generated OOXML opens in Word, or that the real-document corpus is broad
-enough. Treat it as a map for finding thinly tested code; Word, schema,
-LibreOffice, fuzz, and corpus checks provide different evidence.
-
-The initial Phase 7 baseline recorded on 2026-08-29 was:
-
-| Metric | Coverage |
-|---|---:|
-| Lines / statements | 79.57% |
-| Functions | 80.07% |
-| Branches | 69.22% |
-
-This is a visibility baseline, not a CI threshold. Notable opportunities from
-the baseline are `services/numbering-helpers.js` (23.55% lines),
-`orchestration/route-plan.js` (23.75%), and
-`orchestration/list-structural-fallback.js` (57.19%).
-
-The post-Phase-5 snapshot recorded on 2026-08-30 is 79.96% lines/statements,
-80.95% functions, and 69.52% branches. Preserve both snapshots so changes are
-visible over time rather than presenting coverage as a pass/fail quality score.
-
-## Pinned SuperDoc Corpus References
-
-The real-document lane uses explicitly selected references from
-[SuperDoc's docx-corpus](https://docxcorp.us/) (ODC-By 1.0). It does not consume
-a floating or bulk manifest. The reviewed reference set contains 10 English
-legal and 10 English administrative documents. Run the complete local lane on
-Windows with desktop Word installed:
-
-```bash
-npm run test:corpus:word
-```
-
-To fetch only particular reviewed sources:
-
-```bash
-npm run corpus:fetch:superdoc -- --id <pinned-sha256>
-```
-
-Valid IDs and provenance are recorded in
-`tests/corpus/superdoc-english-legal-administrative.json`. The fetcher refuses
-unknown IDs, verifies downloaded bytes against a separately pinned observed
-SHA-256, and writes `.docx` plus attribution metadata under
-`tmp/superdoc-corpus/`. The separate digest is intentional: on 2026-08-29 the
-service returned valid DOCX bytes that did not hash to its advertised corpus
-IDs. Deterministic reviewed operations live in
-`tests/corpus/superdoc-word-scenarios.json`.
-
-The corpus suite replaces only `word/document.xml`, proves that the uncompressed
-bytes of every untouched package part remain identical, opens each result in
-Word without a repair dialog, and checks both Accept All and Reject All. Do not
-commit downloaded documents.

package/docs/WORD-MANUAL-REVIEW.md

@@ -1,138 +0,0 @@
-# Microsoft Word Manual Review
-
-This checklist is the human visual companion to `npm run test:word` and
-`npm run test:corpus:word`. The automated differential proves Word revision
-semantics by comparing text after Accept All and Reject All. This review checks
-the layout and interaction details that `Document.Content.Text` cannot see.
-
-An AI agent may use this same checklist as a visual preflight by controlling the
-local Word UI and inspecting screenshots. Mark that report **AI visual
-preflight**; it helps select and triage cases but does not replace the human
-release sign-off described below.
-
-## Prepare the review set
-
-Run the automated lane first:
-
-```powershell
-npm run test:word
-npm run test:corpus:word
-npm run report:word:coverage
-npm run review:word:prepare -- --cycle=0
-```
-
-The last command writes a pending review manifest under ignored
-`tmp/word-manual-review/` containing changed catalogue families, the rotating
-20% synthetic release sample, and legal/administrative corpus representatives.
-It only prepares the selection: it never records a visual pass or human
-sign-off. Use a new cycle number for each release rotation.
-
-Synthetic documents are generated under `tmp/word-validation/`; reviewed
-SuperDoc results are under `tmp/superdoc-word-fixtures/`. Do not commit generated
-or downloaded `.docx` files.
-
-Select:
-
-- every new or changed case;
-- every case required by the triggers in `docs/TESTING.md`;
-- at least 20% of unchanged synthetic cases, rotating from the prior release;
-- at least one legal and one administrative SuperDoc result; and
-- representative list, table, formatted-run, and anchor/field/content-control
-  structures.
-
-Record the installed Word version and build from **File → Account → About
-Word**. Differences in rendering can be version-specific.
-
-## Configure Word
-
-For the tracked-change inspection:
-
-1. Open the generated fixture directly in desktop Word.
-2. On **Review**, select **All Markup**.
-3. Under **Show Markup**, enable insertions/deletions, formatting, comments, and
-   all reviewers relevant to the case.
-4. Use the expected balloons/inline display for the document and enable
-   paragraph marks when checking whitespace, tabs, breaks, lists, and empty
-   paragraphs.
-5. Do not overwrite the generated fixture. Work on disposable copies if a
-   saved accepted or rejected view is useful.
-
-## Inspect each case
-
-### Tracked-change view
-
-- The document opens without a repair, conversion, or unreadable-content prompt.
-- Word shows the expected revision count and author attribution.
-- Insertions and deletions are anchored at the intended words or paragraph
-  marks; a small edit has not become an unexplained whole-paragraph rewrite.
-- Untargeted text and surrounding revisions remain unchanged.
-- Existing bold, italic, underline, highlighting, fonts, styles, and language
-  settings remain visually consistent.
-- Spaces, tabs, manual breaks, paragraph spacing, indentation, and alignment
-  look intentional with formatting marks visible.
-- Lists retain numbering, levels, continuation, indentation, and marker style.
-- Tables retain widths, borders, merged cells, row heights, and alignment.
-- Bookmarks, hyperlinks, fields, content controls, comments, and note references
-  remain in the correct visible location and still behave when activated.
-- Headers, footers, section boundaries, page breaks, and pagination remain
-  stable around the edit.
-- Revision balloons and comment balloons point to the correct content and do
-  not obscure or displace unrelated layout unexpectedly.
-
-### Accept All view
-
-On a disposable copy, choose **Accept All Changes** and verify:
-
-- the resulting visible text expresses the intended edit;
-- no deletion residue, empty revision wrapper, unexpected blank line, or stale
-  formatting remains;
-- lists, tables, fields, links, comments, notes, and page layout still work; and
-- untargeted content is visually unchanged.
-
-Close the copy without replacing the generated fixture.
-
-### Reject All view
-
-Reopen a fresh copy, choose **Reject All Changes**, and verify:
-
-- the original visible text and formatting are restored;
-- original list numbering, table layout, fields, anchors, and pagination return;
-  and
-- no content introduced by the edit remains.
-
-## Record the result
-
-Keep the review report with the release-validation artifacts. Screenshots may be
-stored under ignored `tmp/word-manual-review/<date>/` when useful, but do not
-commit corpus document images or document contents without checking their
-rights and sensitivity.
-
-Suggested report:
-
-```markdown
-# Word visual review — <release/date>
-
-- Reviewer:
-- Review date:
-- Word version/build:
-- Automated synthetic result:
-- Automated corpus result:
-- Review type: Human sign-off | AI visual preflight
-
-| Case | Why selected | All Markup | Accept All | Reject All | Result | Notes |
-|---|---|---|---|---|---|---|
-| example-case | New table structure | Pass | Pass | Pass | Pass | No layout shift |
-
-## Failures or follow-ups
-
-- None.
-```
-
-A **Pass** requires all three views to pass. Record **Fail** if the rendering or
-interaction is wrong even when automated text comparison passes. Turn a failure
-into a fixed regression case when possible; otherwise record the exact harness
-or Word-version limitation in the active reliability plan.
-
-For an AI preflight, also record screenshot paths and confidence/uncertainty in
-the notes. A human reviewer should revisit every AI failure or uncertain result
-and must still complete the release sample independently.

package/docs/plans/2026-09-01-performance-and-complexity-reduction.md

@@ -1,210 +0,0 @@
-# Performance and Complexity Reduction Plan
-
-**Status:** Proposed  
-**Date:** 2026-09-01  
-
-This plan outlines opportunities to reduce architectural complexity, eliminate redundant diffing engines, and resolve critical performance bottlenecks across `@ansonlai/docx-redline-js`.
-
----
-
-## 1. Context & Motivation
-
-Following the completion of reliability improvements (Rounds 1–3), the library has achieved strong correctness invariants (38/38 test suites passing, Word COM differential parity, and round-trip invariant checks).
-
-However, feature additions over time (tables, lists, comments, formatting removal, and batch operation orchestration) have introduced structural debt:
-1. **Three competing diff-and-patch paradigms**: [Reconstruction Mode](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/engine/reconstruction-mode.js), [Surgical Mode](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/engine/surgical-mode.js), and [Pipeline Mode](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/pipeline/pipeline.js) each maintain distinct run models and patching strategies.
-2. **Monolithic Coordination**: [`services/standalone-operation-runner.js`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/services/standalone-operation-runner.js) has expanded to 1,451 lines (63 KB), entangling batch scheduling, atomic rollback, DOM mutation, range resolution, and ad-hoc heuristics.
-3. **Parse $\leftrightarrow$ Serialize Thrashing in Batches**: In multi-operation document turns, full-document XML is repeatedly parsed and serialized for each operation ($O(N \times \text{document size})$), consuming seconds of CPU time.
-4. **Scattered Domain Logic**: List markers, list parsing, numbering fallback, and list targeting are fragmented across 6+ separate files.
-5. **Hot Path Inefficiencies**: Linear scans in target detection, universal element traversal (`getElementsByTagName('*')`) during revision ID seeding, and excessive heap allocations (`Array.from`) in tree-traversal loops.
-
----
-
-## 2. Guiding Principles
-
-This plan strictly follows the project's core philosophy:
-> **"Readability and Order > Speed and Complex Interconnections"**
-> This project prioritizes maintainability and clarity over clever, hyper-optimized code. Even if a solution is slightly less performant but significantly easier to read, choose the readable one (within reason).
-
-- **SOLID & DRY**: Each module should have one clear responsibility. Avoid maintaining duplicate diff/patch representations.
-- **KISS**: Favor simple, direct DOM operations over multi-layered abstractions.
-- **Strict Backward Compatibility**: Public APIs exported from [`index.js`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/index.js) and the package `exports` map must remain intact. All structural invariants verified by [`validateRedlineOoxml`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/core/redline-validation.js) and the round-trip tests must continue to pass.
-
----
-
-## 3. Baseline Metrics
-
-As of 2026-09-01:
-- `npm test`: 38/38 test files pass (~6.0s execution time due to sequential process spawning).
-- Core package exports remain centralized in [`index.js`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/index.js).
-- For an $N$-operation batch on `word/document.xml`, the runner currently performs up to $3N$ full-document XML parses and $N$ full-document XML serializations using `@xmldom/xmldom`.
-- Four divergent text-extraction functions exist across targeting, engine, and ingestion modules.
-
----
-
-## 4. Production API Compatibility
-
-| Phase | Expected Impact |
-|---|---|
-| **Phase 1: In-Memory Batch DOM & Hot Path Optimization** | **Non-breaking.** Pure internal performance optimization for [`applyOperationsToDocumentXml`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/services/standalone-operation-runner.js#L1356), target searches, and revision ID allocation. Output OOXML remains identical. |
-| **Phase 2: Decomposing `standalone-operation-runner.js`** | **Non-breaking.** Public exports preserved through [`index.js`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/index.js) and package exports; internal subroutines refactored into focused single-responsibility modules. |
-| **Phase 3: Diff Engine Consolidation & Pipeline Retirement** | **Non-breaking.** Unifies paragraph and list generation onto Reconstruction mode; deprecates/retires redundant AST patching in [`pipeline/pipeline.js`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/pipeline/pipeline.js). |
-| **Phase 4: Consolidating Lists & Canonical Text Extraction** | **Non-breaking.** Centralizes list markers/heuristics into `services/list-service.js` and creates an authoritative canonical text extractor in [`core/word-xml.js`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/core/word-xml.js). |
-| **Phase 5: Developer Ergonomics & Fast Test Runner** | **Development-only.** In-process test execution cuts test suite run time from ~6.0s down to <1.0s. |
-
----
-
-## Phase 1 — In-Memory Batch DOM & Hot Path Optimization
-
-### Problem
-1. In [`applyOperationsToDocumentXml`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/services/standalone-operation-runner.js#L1356-L1449), every scheduled operation causes a full serialize-and-reparse cycle:
-   - `parseOoxmlSafe(documentXml)` parses the document.
-   - `applyOperationToDocumentXml` parses it again.
-   - `applyToParagraphByExactText` parses it a third time.
-   - The scoped paragraph is serialized to a string, passed to `applyRedlineToOxml`, and parsed again.
-   - The result is serialized to a string, parsed again by `extractReplacementNodesFromOoxml`, imported back into `xmlDoc`, and the **entire document** is serialized back to string.
-   - In `@xmldom/xmldom` (pure JS DOM implementation), this creates massive CPU overhead for multi-operation turns.
-2. In [`oxml-engine.js`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/engine/oxml-engine.js#L183-L198), target detection uses an $O(\text{lines} \times \text{paragraphs} \times \text{spans})$ nested loop (`textSpans.filter(...)` inside `paragraphs.some(...)` for every line).
-3. In [`RevisionIdAllocator.prototype.seed`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/core/types.js#L203-L222), `getElementsByTagName('*')` copies every single element in the document into an array to find revision IDs, even though only 9 revision tags can carry `w:id`.
-
-### Implementation Steps
-1. **In-Memory Batch Execution**:
-   - Parse `documentXml` once at the beginning of `applyOperationsToDocumentXml`.
-   - Maintain a live `xmlDoc` reference across operations.
-   - Apply operations directly to `xmlDoc` without intermediate full-document string serialization.
-   - Serialize `xmlDoc` once at the end.
-   - Retain the initial `documentXml` string for atomic rollback; if any operation fails when `atomic: true`, simply return the untouched original string.
-2. **Pre-Group Spans in Target Check**:
-   - In `oxml-engine.js`, pre-aggregate text by paragraph into a `Map<Element, string>` in a single $O(\text{spans})$ pass (or reuse [`buildParagraphInfos`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/engine/format-paragraph-targeting.js#L27)), eliminating the quadratic scan.
-3. **Targeted Revision Tag Query**:
-   - In `RevisionIdAllocator.seed`, replace `getElementsByTagName('*')` with targeted queries for known revision element names (`w:ins`, `w:del`, `w:moveFrom`, `w:moveTo`, `w:rPrChange`, `w:pPrChange`, `w:cellIns`, `w:cellDel`, `w:comment`).
-4. **Common Prefix/Suffix Diff Short-Circuit**:
-   - In [`diff-engine.js`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/pipeline/diff-engine.js#L206), add a fast character-level common prefix/suffix trim before DMP tokenization to short-circuit edits that only touch a few words in a large paragraph.
-
-### Acceptance
-- Multi-operation batch benchmarks demonstrate a **5x–15x speedup** on documents with 10+ operations.
-- All 38 existing test suites pass with zero regressions.
-
----
-
-## Phase 2 — Modularizing `standalone-operation-runner.js`
-
-### Problem
-[`standalone-operation-runner.js`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/services/standalone-operation-runner.js) is 1,451 lines long. It acts as an orchestrator, batch scheduler, DOM updater, and heuristic router all at once, making navigation and maintenance difficult.
-
-### Implementation Steps
-1. Extract batch scheduling, priority sorting, dependency tracking, and atomic rollback into `services/batch-operation-orchestrator.js`:
-   - `applyOperationsToDocumentXml`
-   - `operationTargetPriority`
-   - Context cloning and commit helpers (`cloneBatchRuntimeContext`, `commitBatchRuntimeContext`)
-2. Extract single-operation execution and target paragraph scoping into `services/document-operation-applier.js`:
-   - `applyOperationToDocumentXml`
-   - `applyToParagraphByExactText`
-   - `applyHighlightToParagraphByExactText`
-   - `applyCommentToParagraphByExactText`
-3. Extract ad-hoc structural heuristics into `services/operation-heuristics.js`:
-   - Adjacency insertion heuristics (`deriveSingleParagraphListAdjacencyInsertion`, `deriveSingleParagraphPlainAdjacencyInsertion`, `buildInsertedListParagraph`, `buildInsertedPlainParagraph`)
-   - Insertion-only heuristics (`planListInsertionOnlyEdit`, `buildExplicitRangeInsertionEntries`, `applyExplicitRangeListInsertions`)
-   - Scope expansion (`synthesizeExpandedListScopeEdit`, `synthesizeTableMarkdownFromMultilineCellEdit`)
-4. Keep [`services/standalone-operation-runner.js`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/services/standalone-operation-runner.js) as a clean façade re-exporting the public contract.
-
-### Acceptance
-- No single file exceeds 500 lines.
-- Each module has a single, testable responsibility.
-- Existing tests in `tests/standalone_operation_runner_tests.mjs` pass without modification.
-
----
-
-## Phase 3 — Diff Engine Consolidation & Pipeline Retirement
-
-### Problem
-The codebase currently supports three reconciliation execution engines:
-- **Reconstruction Mode**: Maps characters to runs, properties, and sentinels; rebuilds OOXML structure. (Primary, actively maintained, tab/field safe).
-- **Surgical Mode**: In-place mutation of runs in existing DOM. (Required for tables).
-- **Pipeline Mode** ([`pipeline/pipeline.js`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/pipeline/pipeline.js)): Converts OOXML to an AST (`runModel`), splits runs at diff boundaries, and patches via string templates. It is now only invoked when `isTargetList` is true.
-
-Maintaining three diffing and patching engines increases maintenance burden and means bug fixes (such as `w:tab`, complex fields, or namespace handling) must be replicated across separate systems.
-
-### Implementation Steps
-1. Enhance Reconstruction Mode to handle list structural conversions natively:
-   - When marker-prefixed list text is detected, emit Word list properties (`w:numPr`) directly during reconstruction writing.
-2. Route `isTargetList` operations in [`oxml-engine.js`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/engine/oxml-engine.js#L371) through Reconstruction Mode instead of `ReconciliationPipeline`.
-3. Deprecate and remove redundant AST patching modules:
-   - [`pipeline/patching.js`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/pipeline/patching.js)
-   - [`pipeline/serialization.js`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/pipeline/serialization.js) (retaining only document fragment wrapping helpers)
-   - [`pipeline/pipeline.js`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/pipeline/pipeline.js)
-4. Standardize on **Reconstruction Mode** for paragraphs/lists and **Surgical Mode** for tables.
-
-### Acceptance
-- ~3,000 lines of redundant code removed.
-- All list generation and list fallback tests (`tests/list_tests.mjs`, `tests/phase3_list_structural_fallback_tests.mjs`) pass with equal or better fidelity.
-- Output validity confirmed via `validateRedlineOoxml`.
-
----
-
-## Phase 4 — Domain Consolidation: Lists & Canonical Text Extraction
-
-### Problem
-1. List logic is currently dispersed across 6+ separate files:
-   - [`pipeline/list-generation.js`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/pipeline/list-generation.js)
-   - [`pipeline/list-markers.js`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/pipeline/list-markers.js)
-   - [`orchestration/list-parsing.js`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/orchestration/list-parsing.js)
-   - [`orchestration/list-markdown.js`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/orchestration/list-markdown.js)
-   - [`orchestration/list-structural-fallback.js`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/orchestration/list-structural-fallback.js)
-   - [`core/list-targeting.js`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/core/list-targeting.js)
-2. Four distinct visible-text extraction functions exist across targeting, engine, and ingestion modules, creating risk of subtle behavioral differences around `w:tab`, `w:br`, `w:noBreakHyphen`, and `w:del`.
-3. Frequent `Array.from(nodeList)` calls inside recursive DOM traversals generate heavy GC pressure.
-
-### Implementation Steps
-1. **Canonical Text Extractor**:
-   - Establish a single, authoritative `getParagraphVisibleText(pElement)` in [`core/word-xml.js`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/core/word-xml.js).
-   - Standardize handling for `w:t`, `w:tab` (`\t`), `w:br`/`w:cr` (`\n`), `w:noBreakHyphen` (`\u2011`), and exclusion of `w:delText` / deleted runs.
-   - Refactor `paragraph-targeting.js`, `oxml-engine.js`, and `ingestion-paragraph.js` to use this canonical helper.
-2. **Consolidate List Domain Modules**:
-   - Combine list marker matching and markdown list parsing into `services/list-service.js`.
-   - Simplify fallback orchestration so single-line structural fallback shares the same list definitions as multi-line lists.
-3. **Reduce DOM Traversal Allocations**:
-   - Replace `Array.from(node.childNodes)` in hot traversal loops with pointer iteration (`for (let child = node.firstChild; child; child = child.nextSibling)`).
-   - Use `node.getAttributeNS(NS_W, 'author')` directly instead of iterating through `Array.from(node.attributes)`.
-
-### Acceptance
-- Single source of truth for paragraph text extraction across all modules.
-- List parsing and numbering fallback unified under a cohesive domain service.
-- Reduced memory churn during large document traversals.
-
----
-
-## Phase 5 — Developer Ergonomics & Fast Test Runner
-
-### Problem
-[`scripts/run-tests.mjs`](file:///c:/Users/Phara/Desktop/Projects/Docx%20Redline%20JS/scripts/run-tests.mjs#L21) currently runs 38 test files by invoking `execSync('node "${filePath}"')` sequentially. On Windows, spawning 38 separate Node.js processes accounts for ~5 seconds of the 6-second test run.
-
-### Implementation Steps
-1. Update `scripts/run-tests.mjs` to dynamically import and execute test files in-process (`await import(filePath)`), or leverage Node's native test runner (`node --test tests/*.mjs`).
-2. Retain process isolation checks in `npm run test:isolation`.
-
-### Acceptance
-- `npm test` execution time reduced from ~6.0s down to <1.0s.
-- Contributor iteration speed significantly improved.
-
----
-
-## 5. Execution Roadmap & Prioritization
-
-```mermaid
-graph TD
-    P1[Phase 1: In-Memory Batch DOM & Hot Paths] --> P2[Phase 2: Modularize standalone-operation-runner]
-    P1 --> P5[Phase 5: Fast Test Runner]
-    P2 --> P3[Phase 3: Unify Diff Engines & Retire Pipeline]
-    P3 --> P4[Phase 4: List & Text Extraction Consolidation]
-```
-
-1. **Sprint 1 (Immediate Performance Wins)**:
-   - Phase 1 (In-memory DOM batch execution + target search optimization + revision allocator query).
-   - Phase 5 (In-process test runner).
-2. **Sprint 2 (Architecture Cleanliness & Maintainability)**:
-   - Phase 2 (Decompose `standalone-operation-runner.js`).
-   - Phase 4 (Canonical visible text extractor).
-3. **Sprint 3 (Structural Unification)**:
-   - Phase 3 (Retire legacy pipeline; unify on Reconstruction & Surgical modes).
-   - Complete list logic consolidation.