@ansonlai/docx-redline-js 0.8.4 → 0.10.0

package/docs/TESTING.md

@@ -1,1059 +1,1146 @@
-# Testing Guide
-
-This project uses several test lanes because no single oracle can prove that a
-tracked-change document is correct. JavaScript assertions can verify exact XML
-and return contracts; Microsoft Word can verify what the primary consumer
-actually accepts and rejects; real documents expose structures that small
-fixtures rarely contain.
-
-## Test lanes at a glance
-
-| Lane | Command | What it proves | What it does not prove |
-|---|---|---|---|
-| Automated regression suite | `npm test` | API behavior, exact text invariants, OOXML structure, deterministic fuzz cases, and catalogue integrity | That desktop Word accepts the generated package |
-| Isolation, types, and lint | `npm run test:isolation`, `npm run check:types`, `npm run lint` | Runtime boundaries, declaration alignment, and static repository rules | Document correctness |
-| JavaScript coverage | `npm run test:coverage` | Which source lines, functions, and branches the automated suite executes | That an executed path is correct |
-| Synthetic Word differential | `npm run test:word` | Word opens generated packages, sees revisions, and produces the intended text after Accept All and Reject All | The diversity of real-world packages |
-| Word visual evidence | `npm run test:word:visual` | Word renders layout-sensitive fixtures in All Markup, Accept All, and Reject All views and writes a pending review manifest | That the rendered pages are visually correct until a reviewer inspects them |
-| SuperDoc Word corpus | `npm run test:corpus:word` | The same Word differential on 60 scenarios drawn from 23 reviewed, pinned real English legal/administrative documents while untouched package parts remain byte-identical | Every possible DOCX producer or document type |
-| SuperDoc visual evidence | `npm run test:corpus:word:visual` | Word renders 40 focused list, table, long-document, and page-header scenarios in All Markup, Accept All, and Reject All views | Human visual sign-off |
-| Visual evidence inspection | `npm run test:visual:inspect` | Automated inspection of rendered Word PDFs across synthetic and SuperDoc suites (page counts, PDF integrity, anomaly detection) | Human visual sign-off |
-| Visual failure regressions | `node tests/visual_failure_regression_tests.mjs` | Semantic OOXML guards against visual failures (formatting leaks, font resets, ghost bullets, table cell destruction) | Visual rendering proof in Word |
-| 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`, `node tests/agent_cli_protocol_tests.mjs`, `node tests/agent_cli_help_tests.mjs`, `node tests/agent_cli_inspection_context_tests.mjs`, `node tests/agent_cli_output_budget_tests.mjs` | JSON contracts, command-specific help, contextual pagination, composable progressive/atomic profiles, deduplicated receipts, compact stdout, file/stdin Unicode fidelity, complete-success exits, source safety, command families, and 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, examples lead with scoped contextual extraction, and packaged skill-authoring guidance separates invariants, policies, transports, recovery, and presentation 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 |
-| Target hot-path parity | `node tests/performance_phase3_target_hot_paths_tests.mjs` | Cached and uncached resolution metadata parity, duplicate safety, snapshots, session invalidation, and pointer-based revision-ID seeding | Machine-independent latency thresholds |
-| List and text-walker parity | `node tests/performance_phase4_list_and_text_parity_tests.mjs` | One shared marker vocabulary and canonical/specialized visible-text agreement across structural characters and revision views | That all specialized mappings are interchangeable |
-| Universal document facade & ZIP | `node tests/universal_docx_document_tests.mjs`, `node tests/universal_zip_archive_tests.mjs`, `node tests/universal_facade_edge_cases_tests.mjs` | Universal `Uint8Array` binary handling, `fflate` compression/decompression, optimistic concurrency, and complete-DOCX operations without Node built-ins | Desktop Word rendering |
-| Sandbox bundle isolation | `node tests/sandbox_bundle_isolation_tests.mjs` | Zero-dependency standalone ESM/CJS bundles execute in restricted VM sandboxes without `process`, `Buffer`, or `require`, with zero Node built-in imports | Web Worker latency |
-| Cross-author revision slicing | `node tests/cross_author_slicing_fixtures_tests.mjs`, `node tests/cross_author_carrier_splitting_tests.mjs`, `node tests/cross_author_slicing_synthetic_tests.mjs`, `node tests/cross_author_slicing_real_tests.mjs`, `node tests/cross_author_slicing_hyperlink_roundtrip_tests.mjs`, `node tests/cross_author_slicing_insertion_stress_tests.mjs` | Word-native `<w:ins>` splitting, `<w:del>` nesting, multi-author stacking, straddle boundaries, synthetic matrix (SYN-01..12d), strict package differential replay (PKG-01..06), exact hyperlink/NBSP round trips, and 76 insertion stress scenarios | Non-Word consumers beyond OpenXML XSD validation |
-
-The package-facade regression opens a real ZIP buffer, adds a comment beside an
-existing high ID, validates OPC wiring, and checks an unrelated binary part is
-unchanged after extraction. Its failure case requires byte-exact rollback. The
-inspection regression covers revisions, structural characters, heading
-context, comment joining, and a numbering start override.
-
-The CLI regression executes the recommended extract → preflight → apply →
-validate flow and also covers accept, reject, comment deletion, output collision
-refusal, and source-byte preservation. CLI stdout is captured and parsed as one
-JSON value so diagnostic logging cannot corrupt agent output.
-
-The edge suites deliberately use structures omitted from the basic happy-path
-fixtures: `w:moveFrom`/`w:moveTo`, deleted text, structural breaks and hyphens,
-comments crossing paragraph boundaries, orphan definitions, outline headings,
-footnote/endnote references, nested Roman/alphabetic numbering, sequential
-commit-then-rollback calls, selective comment authors, existing high anchor
-IDs, encrypted/unsupported ZIP entries, `--force`, and `--in-place`.
-
-The Phase 2 boundary regression is intentionally structural as well as
-behavioral. It prevents the public runner from accumulating implementation
-logic again, verifies that internal operation code does not import the root
-entry point, and checks that failed atomic work can retain the exact source
-string while working maps and sets remain isolated until commit.
-
-The checked post-Phase-5 2026-09-04 coverage run reports 89.81%
-statements/lines, 77.34% branches, and 93.04% functions repository-wide; this
-is above every recorded pre-refactor dimension. Targeting performance can be
-measured in Node with `npm run benchmark:targeting` and against the native DOM
-by serving the repository locally and opening
-`scripts/benchmark-targeting-browser.html`; its `paragraphs`, `operations`, and
-`iterations` query parameters reproduce the checked fixture sizes.
-The Node surface reports 99.61% statements/lines; `document-inspection.js`
-reports 97.64% statements/lines and 100% functions; `paragraph-text.js` reports
-100% statements/lines/functions.
-
-Run the observational live-session benchmark with:
-
-```powershell
-npm run benchmark:session
-```
-
-It writes `tmp/benchmarks/operation-session-latest.json`. The checked
-1,000-paragraph/10-operation run reduced full-document parse/serialization from
-10/10 to 1/1 and measured a 1.58x median speedup. Timing and heap figures are
-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).
-
-Run the CLI discovery/output benchmark with:
-
-```powershell
-npm run benchmark:agent-cli
-```
-
-It records command-specific help size, broad inspect/search response size,
-context-window call count, pagination metadata, case-insensitive match parity,
-and native elapsed time in `tmp/benchmarks/agent-cli-discovery-latest.json`.
-The checked WP-00 through WP-02 before/after measurements are in the
-[agent CLI discovery baseline](validation-reports/2026-09-12-agent-cli-discovery-baseline.md).
-WP-03 through WP-05 profile, output-size, workflow, documentation, and package
-results are in the
-[agent CLI efficiency rollout audit](validation-reports/2026-09-13-agent-cli-efficiency-rollout.md).
-
-## Cross-author revision slicing test suite
-
-The cross-author revision slicing subsystem introduces six complementary test lanes:
-
-1. **Native Word Desktop Fixtures (`tests/cross_author_slicing_fixtures_tests.mjs`)**:
-   Verifies 36 reference `.docx` and `.xml` files generated via Microsoft Word Desktop 365 COM automation across 6 golden scenarios (`insert-interior`, `delete-interior`, `delete-boundary-start`, `delete-boundary-end`, `delete-straddle-baseline-insertion`, and `multi-author-stacked`) in pending, accepted, and rejected states. Proves Word-native OOXML patterns (carrier `<w:ins>` splitting for insertions, direct `<w:del>` nesting inside `<w:ins>` for deletions) and lifecycle parity under `acceptTrackedChangesInOoxml` and `rejectTrackedChangesInOoxml`.
-2. **Carrier Splitting Unit Suite (`tests/cross_author_carrier_splitting_tests.mjs`)**:
-   Tests `splitTrackChangeCarrier` across interior and boundary cuts, multi-run formatting preservation, stable metadata cloning, independent revision ID allocation via `RevisionIdAllocator`, and immutable input handling.
-3. **Synthetic Boundary Matrix (`tests/cross_author_slicing_synthetic_tests.mjs`)**:
-   Executes the full SYN-01 through SYN-12d test matrix covering pure interior inserts, pure interior deletes, boundary start/end cuts, full-content annihilation, baseline/insertion straddles, multi-carrier straddles, formatting preservation, paired replacements, 3-author stacked revisions, and selective author accept/reject lifecycle oracles.
-4. **Checked-In Word Package Differential Suite (`tests/cross_author_slicing_real_tests.mjs`)**:
-   Reconstructs the pre-mutation document packages, applies `slice-cross-author` via the strict `openDocx` package facade, enforces atomic package validation, and compares engine `AcceptAll` and `RejectAll` output against Word Desktop-generated golden packages (PKG-01 through PKG-06).
-5. **Hyperlink and Exact-Text Regression (`tests/cross_author_slicing_hyperlink_roundtrip_tests.mjs`)**:
-   Reproduces the repeated-phrase, hyperlink-boundary, and NBSP-to-space failure through both the low-level engine and document operation runner. It requires exact accepted-view equality, preserves both hyperlink relationship containers, and proves that an unreconstructable slicing mutation returns `PATCH_ROUNDTRIP_MISMATCH` with the original OOXML unchanged.
-6. **Insertion Stress Matrix (`tests/cross_author_slicing_insertion_stress_tests.mjs`)**:
-   Runs 76 deterministic scenarios across carrier start/end/interior positions, repeated phrases, multi-run and formatted carriers, spaces/tabs/NBSP, XML-sensitive characters, emoji/combining Unicode, hyperlink interiors and boundaries, bookmarks, comments, nested deletions, adjacent authors, mixed same/foreign-author carriers, multiple structural containers, consecutive reviewer rounds, and the atomic document runner. Every supported case requires exact current-view, Accept-All, Reject-Current, schema, metadata, and non-empty-wrapper invariants; unsupported nested structures must fail without throwing or returning changed output.
-
-## Coverage matrix and test selection
-
-Run the deterministic task-by-structure report before choosing the next Word
-case:
-
-```powershell
-npm run report:word:coverage
-npm run report:word:coverage -- --json
-npm run report:test:dashboard
-```
-
-The dashboard command writes a self-contained interactive report to
-`docs/test-comparison-dashboard.html`. It compares task/structure cells,
-synthetic and real-document coverage, independent oracles, visual-render
-eligibility, and planned high-priority gaps from the live catalogues. It also
-embeds source, tracked, accepted, and rejected packages for every synthetic
-fixture and, when the pinned corpus is downloaded, all 60 reviewed real legal
-and administrative scenarios. Its `docx-preview` workbench supports arbitrary left/right states,
-comparison presets, synchronized scrolling, revision metadata, expected text,
-and local downloads; no fixture upload or file picker is required. Real cases
-are labeled in the document selector and selected by default when available.
-Use **Hide sidebar** beside the dashboard filters to remove the coverage-detail
-column and expand the comparison workbench to the full browser width. The
-button becomes **Show sidebar**, and the preference is stored locally so the
-wide document view survives a reload.
-Without the local corpus, generation remains offline-safe and embeds only the
-synthetic previews.
-
-The report combines all synthetic and reviewed SuperDoc scenarios. Synthetic
-metadata is declared in `tests/fixtures/word-task-coverage.mjs`; SuperDoc
-metadata is declared in `tests/corpus/superdoc-word-coverage.json`. Descriptive
-`task`, `shape`, and `coverage` labels remain on the original cases as review
-notes, while the matrix uses shared task, structure, and oracle vocabularies.
-
-Catalogue tests reject unknown vocabulary labels, missing oracle or manual-review
-metadata, duplicate identities, structural claims unsupported by fixture XML or
-reviewed corpus labels, and uncovered high-priority cells without a recorded
-plan or exclusion. The dispositions live in
-`tests/fixtures/coverage-matrix-priorities.json` and require both a reason and a
-dependency.
-
-Choose new cases from uncovered high-priority cells first, then prefer a new
-task/structure combination over another case in a dense cell. A higher count is
-not itself a reason to add a fixture. Adding a catalogue case automatically
-changes the report because it reads the live metadata.
-
-## Reliability improvement process used for this test expansion
-
-The current corpus, visual runners, and comparison dashboard were built as one
-feedback loop rather than as separate test features. The working sequence is:
-
-1. inventory the claimed behavior and existing test lanes;
-2. add realistic cases that expose weak structures;
-3. assert the smallest machine-checkable invariant at the engine level;
-4. package the result into the original real document without changing
-   unrelated parts;
-5. ask Word to accept and reject the revisions;
-6. render All Markup, Accept All, and Reject All views;
-7. inspect the actual pages at both contact-sheet and full-page scale; and
-8. turn every visual defect into a focused regression plus a corpus assertion.
-
-This ordering matters. A valid `<w:ins>` or `<w:del>` tree does not establish
-that the inserted run inherited the correct font, list indentation, hyperlink
-wrapper, table-cell formatting, or header styling. Conversely, a good-looking
-PDF does not prove that Reject All restores the exact source. Each stage answers
-a different question, and a case is useful only when its intended claim is
-explicit.
-
-### Start from coverage claims, not fixture count
-
-Read the task-by-structure matrix and select a real document that adds a missing
-or weak combination. The expansion deliberately favored bullets, nested lists,
-table cells, headers, long documents, and atomic multi-change batches because
-these structures cross more OOXML boundaries than a single plain paragraph.
-Several scenarios reuse a pinned source when a new batch exercises a genuinely
-different structure; this increases behavioral coverage without pretending
-that another copy of the same document is a new source.
-
-For long real documents, record structural minimums such as word count, table
-count, list-paragraph count, section count, and related header/footer parts.
-`scripts/prepare-superdoc-word-corpus.mjs` checks these declarations against the
-source package. This prevents a scenario description such as “table-heavy” or
-“multi-section” from silently drifting away from the actual fixture.
-
-### Use multi-change batches to exercise interaction effects
-
-Single replacements remain valuable for isolating engine behavior, but real
-editing sessions usually contain several changes. The larger corpus scenarios
-therefore use `operations` to apply independent edits atomically across one
-document. Targets are chosen from different list items or table cells when
-possible. This catches failures caused by earlier replacements shifting later
-anchors, revision-ID allocation across a batch, and formatting state leaking
-between operations.
-
-The batch runner must either produce all requested revisions or roll back the
-document. Word then checks the complete accepted and rejected story, not merely
-the first target. Untouched ZIP parts are hashed and compared with the pinned
-source, so success cannot come from rebuilding or normalizing the rest of the
-package.
-
-### Expand weak list and table cells with structural operations
-
-The list/table expansion was driven directly by the task-by-structure matrix;
-it did not add more plain replacement cases. The current catalogue contains 109
-Word cases: 49 synthetic fixtures and 60 reviewed real-document scenarios. The
-`List Change × List` cell now contains 27 cases; the
-`Table Reconciliation × Table` cell contains 11 cases.
-
-The added synthetic cases isolate one structural decision at a time:
-
-- append one list item;
-- append several adjacent items;
-- add a nested child;
-- insert into the middle of an explicit list range;
-- preserve upper- and lower-Roman numbering;
-- preserve upper-letter, parenthesized lower-letter, dash, and symbol bullets;
-- expand a manually numbered heading whose `w:numId="0"` suppresses numbering
-  into separate, positively numbered list paragraphs;
-- update one table cell;
-- insert a table row;
-- delete a table row; and
-- update several cells in one reconciliation.
-
-The mixed-attachment fixture replaces one anchor with explicit headings,
-ordinary paragraphs, a Markdown table, and a numbered list. It verifies real
-`w:pStyle`, `w:tbl`, and positive-numbering structures plus independent Word
-Accept All and Reject All results; literal table pipes are forbidden.
-
-The real-document cases repeat those claims against native numbering and table
-markup from municipal notices, board agendas, a long zoning ordinance, PPG
-minutes, action tables, and invoice tables. They include consecutive and nested
-list insertions, a long-document definition insertion, single- and multi-cell
-updates, row insertion/deletion, and invoice row changes. Reusing a reviewed,
-hash-pinned source is intentional when the scenario exercises a different
-operation; the unit of coverage is the behavioral claim, not the download.
-
-These cases declare `operation.type` as `list-change` or
-`table-reconciliation`. Their accepted/rejected expectations use explicit
-contains/absent assertions when a Markdown table payload or a structural list
-edit cannot be compared meaningfully to the raw Word source as one exact text
-string. Structural expectations still verify real properties such as native
-list paragraphs, tables, headers/footers, sections, and minimum document size.
-The catalogue tests require these expectations and reject unknown operation or
-coverage labels.
-
-List-style cases do not infer their claim from visible text alone. Synthetic
-fixtures declare the required `w:numFmt` values and use complete, schema-ordered
-numbering parts: every `w:abstractNum` must precede the first concrete `w:num`
-mapping. That ordering is regression-tested because Word otherwise opens the
-package but silently substitutes its fallback bullet. Real scenarios declare a
-`listStyleExpectation` with the source level, number format, and, where useful,
-the exact `w:lvlText`. Corpus preparation resolves the target paragraph's
-`w:numId` through `word/numbering.xml` and fails before editing if the pinned
-source no longer has that native style. The current real cases exercise upper
-and lower Roman, upper and lower letter, parenthesized lower letter, dash, and
-symbol bullets across bylaws, agendas, healthcare minutes, and long council
-minutes.
-
-### Diagnose visual failures in the generated OOXML first
-
-When a page looks wrong, compare the relevant source and tracked
-`word/document.xml` or related part before changing the renderer. Locate the
-visible text, inspect its nearest `w:r`, `w:rPr`, wrapper, paragraph properties,
-and neighboring runs, then compare those properties with the source. This
-separates an engine defect from a Word, PDF, or `docx-preview` display issue.
-
-Three defects illustrate the approach:
-
-- The council header date replacement inherited `w:vertAlign="superscript"`
-  from the trailing ordinal suffix. The fix anchors replacement formatting at
-  the beginning of the deleted range, and the regression explicitly forbids
-  `vertAlign` on the inserted runs.
-- The prospectus filing-date replacement crossed normal runs and a hyperlink.
-  A forward-only property lookup had already moved past the beginning of the
-  deletion when the insertion asked for its formatting, so the new run had no
-  `w:rPr`. Word and SuperDoc correctly fell back from the surrounding 10 pt to
-  the document default of 12 pt. The lookup now supports that deliberate
-  backward query. The focused regression requires `w:sz="20"` and
-  `w:szCs="20"`, and the real prospectus scenario requires those values on
-  every inserted text run.
-- A wholly inserted list item originally tracked only its text run. Accept All
-  looked correct and text-only Reject All assertions passed, but Word retained
-  the untracked paragraph mark as an empty bullet or number. Inserted list
-  paragraphs now track both their text and paragraph mark. The regression
-  rejects the change and asserts the exact original paragraph count, text, and
-  numbering, while the real Word PDFs confirm that no ghost marker remains.
-
-These assertions test the semantic cause rather than a screenshot pixel. The
-visual render remains necessary to confirm that the corrected properties
-produce the intended page. The automated test suite in
-`tests/visual_failure_regression_tests.mjs` codifies these guards directly in
-the regression test pipeline (`npm test`) to prevent regressions before DOCX
-packages reach Word.
-
-### Regenerate packages; do not reason from stale outputs
-
-Source downloads are content-addressed and may be reused. Generated tracked,
-accepted, rejected, PDF, and dashboard artifacts are outputs and must be
-rebuilt after an engine or scenario change. A `Verified cached ...` line from
-the corpus fetcher means only that the pinned source `.docx` already matches its
-recorded hash; it does not mean the edited package was reused.
-
-Use this sequence for a corpus-affecting engine change:
-
-```powershell
-npm test
-npm run check:types
-npm run lint
-npm run test:isolation
-npm run test:corpus:word
-npm run test:corpus:word:visual
-npm run report:test:dashboard
-```
-
-For faster iteration, `prepare-superdoc-word-corpus.mjs` accepts
-`--input-dir` and `--output-dir`, and the visual PowerShell runner accepts
-`-Case <scenario-key>` plus custom fixture/output directories. Run the complete
-lane before handoff even when a focused render passed.
-
-### Treat Word COM cleanup separately from render success
-
-Word sometimes disconnects a COM document proxy after successfully exporting
-a PDF and raises `RPC_E_DISCONNECTED` during `Document.Close()`. The visual
-runner uses safe close/quit helpers: a disconnect during post-export cleanup is
-reported but does not discard a valid, non-empty PDF; a disconnect during the
-actual render causes Word to restart and the case to retry once. Other COM
-exceptions still fail the run. This distinction avoids both false failures and
-false passes.
-
-Each visual invocation uses a process-specific fixture directory. That keeps a
-Word process left behind by an earlier disconnect from locking or contaminating
-the next set of generated DOCX files.
-
-### Review both the whole document and the changed page
-
-For a long document, create low-resolution contact sheets for every page in all
-three revision states and inspect them for pagination changes, blank pages,
-clipping, table displacement, or large typography shifts. Then inspect every
-changed page at full resolution. Contact sheets are good at document-wide
-layout; they are not reliable for a 10 pt versus 12 pt difference or a leaked
-superscript flag.
-
-Record the exact scenario, Word version/build, revision view, page, observed
-fact, and whether the judgment is certain. The visual manifest remains pending
-until a reviewer makes that judgment; successful PDF export alone is not a
-visual pass.
-
-### Keep the dashboard generated and test its controls
-
-`scripts/generate-test-dashboard.mjs` owns the dashboard markup, styles, and
-behavior. Do not hand-edit `docs/test-comparison-dashboard.html`; rebuild it
-with `npm run report:test:dashboard`. The report embeds the four DOCX states so
-it remains self-contained and can show the exact generated packages without a
-file picker or server.
-
-Dashboard changes require generator-level assertions in
-`tests/test_dashboard_report_tests.mjs`. The sidebar-width control, for
-example, is checked for its accessible relationship, full-width CSS state, and
-persisted preference. DOCX package parsing remains covered separately by
-`tests/docxjs_dashboard_rendering_tests.mjs`. When browser control is available,
-also click the control in the generated page and verify that the sidebar is
-hidden, both document panes widen, the label changes, and reloading preserves
-the selected state.
-
-### Definition of done for a discovered real-document defect
-
-A visual defect is complete only when all of the following are true:
-
-- the source and faulty generated OOXML have been compared;
-- the engine cause is understood rather than masked in CSS or the renderer;
-- a minimal automated regression reproduces the structural boundary;
-- Accept All yields the requested text and Reject All restores the source;
-- the affected real corpus scenario has an appropriate structural or
-  formatting assertion;
-- its source, tracked, accepted, and rejected packages have been regenerated;
-- desktop Word differential passes;
-- the changed page and the document-wide three-view render have been inspected;
-- the self-contained comparison dashboard has been rebuilt; and
-- the full automated, isolation, type, lint, and whitespace checks pass.
-
-Prepare, but do not approve, a human review sample with:
-
-```powershell
-npm run review:word:prepare -- --cycle=0
-```
-
-The ignored `tmp/word-manual-review/review-manifest-cycle-0.json` selects all
-catalogue families changed in the worktree, a rotating 20% synthetic sample,
-and one legal plus one administrative SuperDoc case. Every All Markup, Accept
-All, Reject All, and human sign-off field starts as `pending`; the helper cannot
-turn them into passes. Increment `--cycle` between releases to rotate the
-unchanged sample.
-
-## Automated JavaScript tests
-
-Files matching `tests/*.mjs` are discovered by `scripts/run-tests.mjs`. Tests
-use `assert/strict` and each runs in a separate Node process. The runner uses up
-to four workers by default while preserving filename-sorted reporting. Set
-`DOCX_TEST_CONCURRENCY=1` for deterministic serial reproduction, or another
-positive integer for an explicit worker bound. Word, visual, and corpus lanes
-remain separate serial commands. Shared OOXML assertions belong in
-`tests/helpers/ooxml-assertions.mjs`; XML-provider setup belongs in
-`tests/setup-xml-provider.mjs`.
-
-Measure serial and parallel execution on the same machine with:
-
-```powershell
-npm run benchmark:tests
-```
-
-The benchmark performs paired warmups/runs and writes its JSON result to
-`tmp/benchmarks/test-runner-latest.json`. The checked Node 24/Windows x64 run
-reduced median time from 18.02 seconds to 7.96 seconds (55.80%). Twenty
-consecutive four-worker runs completed without a failure.
-
-For function-level gap work, run:
-
-```powershell
-npm run test:coverage
-npm run coverage:gaps
-npm run coverage:gaps -- --json
-```
-
-The coverage command emits both the text summary and detailed Istanbul JSON.
-The gap report includes only runtime production roots, lists each uncovered
-function with its file and declaration line, assigns the Phase 3 P0/P1/P2
-priority, and fails if a targeted file drops below the checked covered-function
-or covered-branch baseline in `tests/coverage-data/phase3-baseline.json`. Because V8
-discovers new branch sites when a formerly cold function first executes, review
-covered counts and behavior assertions alongside percentages. Do not add ignore
-annotations or call private code merely to improve a score; classify a retained
-gap with a reachability or environment reason.
-
-For an engine regression:
-
-1. Add the smallest fixed case that reproduces the bug and asserts the exact
-   result or structured error.
-2. Assert both sides of tracked changes: accepting must produce the requested
-   text and rejecting must restore the original text exactly.
-3. Assert structural invariants with `validateRedlineOoxml` and the shared OOXML
-   helpers. Do not use a whitespace-collapsing reader as the oracle.
-4. If engine behavior changed, add the same shape to the deterministic fuzz
-   corpus so nearby inputs are exercised too.
-5. Run `npm test`, isolation, types, and lint.
-
-For a mixed attachment regression, also run the content through
-`planStructuredReplacement(...)`. Assert the declared block sequence, reject
-malformed table grammar, and verify that the result contains real `w:tbl`,
-heading styles, positive list numbering IDs, valid non-nested revisions, and
-independent Accept/Reject outcomes. Do not treat absence of literal pipe text as
-sufficient proof of a table.
-
-## Synthetic Microsoft Word tests
-
-The runtime library contains no COM or Word dependency. Word automation exists
-only in Windows development scripts and is intentionally excluded from package
-runtime paths.
-
-The synthetic catalogue is `tests/fixtures/word-task-cases.mjs`. During
-`npm run test:word`:
-
-1. `scripts/export-validation-fixtures.mjs` applies each operation, runs the
-   library's structural validator, checks any case-specific `requiredElements`,
-   and builds a minimal `.docx` under ignored `tmp/word-validation/` storage.
-2. Expected Accept All and Reject All text is derived from the test's edit
-   intent, not from the library's own revision-management functions.
-3. `scripts/word-com-differential.ps1` opens each fixture through desktop Word
-   without a repair dialog and confirms Word sees at least one revision.
-4. Word accepts every revision in one fresh document and rejects every revision
-   in another. Both resulting texts are compared with the intent-derived
-   expectations.
-
-To add a synthetic Word case:
-
-1. Add a unique lowercase-hyphenated entry to `WORD_TASK_CASES` with
-   `category: 'legal'` or `'administrative'`, a distinct `task`, and `original`
-   and `modified` text.
-2. Use `sourceDocumentXml` when the case needs bookmarks, hyperlinks, tables,
-   content controls, prior revisions, or another deliberate structure.
-3. Add `requiredElements`, such as `{ bookmarkStart: 1, bookmarkEnd: 1 }`, when
-   retaining a structure is part of the claim. These are minimum namespace-aware
-   element counts checked before Word runs.
-4. Supply `expectedAcceptedText` and `expectedRejectedText` when the source is a
-   multi-paragraph document or Word exposes structural separators such as table
-   row boundaries. Exact comparison is the default.
-5. Run `node tests/word_task_catalog_tests.mjs`, then `npm run test:word` on a
-   Windows machine with desktop Word installed.
-
-### Related-part fixture schema
-
-The script-only packager supports optional numbering plus comments, footnotes,
-endnotes, headers, footers, and external hyperlinks. Add them to a catalogue
-case through `packageParts`:
-
-```js
-{
-  sourceDocumentXml,
-  packageParts: {
-    commentsXml,
-    footnotesXml,
-    endnotesXml,
-    headers: [{
-      partName: 'header1.xml',
-      relationshipId: 'rIdHeader1',
-      xml: headerXml
-    }],
-    footers: [{
-      partName: 'footer1.xml',
-      relationshipId: 'rIdFooter1',
-      xml: footerXml
-    }],
-    externalHyperlinks: [{
-      relationshipId: 'rIdPolicy',
-      target: 'https://example.com/policy'
-    }]
-  }
-}
-```
-
-`createCommentsPart`, `createNotesPart`, and `createHeaderFooterPart` in
-`tests/fixtures/word-package-parts.mjs` provide small escaped constructors for
-the common XML parts. Header/footer `partName` and `relationshipId` values have
-deterministic defaults, but explicit values make the corresponding
-`w:headerReference`, `w:footerReference`, or `w:hyperlink` easier to audit.
-
-Before ZIP emission, the packager rejects malformed XML, duplicate relationship
-IDs or part names, missing relationship targets, undefined comment/note IDs,
-and note parts without separator IDs `-1` and `0`. It generates the required
-content-type overrides and document relationships. Every supplied related part
-is compared byte-for-byte with the packaged entry, recorded as SHA-256 in the
-case sidecar, and rechecked by the Word differential before opening the DOCX.
-These helpers remain under `scripts/` and `tests/`; none are shipped through the
-runtime entry point.
-
-### What the automated Word differential proves
-
-The Word process is real desktop Microsoft Word, but it is driven invisibly
-through COM. For each fixture, the script:
-
-1. starts `Word.Application` with alerts and the window disabled;
-2. opens the generated package with `OpenNoRepairDialog`;
-3. fails if Word cannot open it or sees zero tracked revisions;
-4. accepts all revisions and reads `Document.Content.Text`;
-5. closes without saving, reopens the untouched fixture, rejects all revisions,
-   and reads the text again; and
-6. compares both results with expectations that were not calculated by this
-   library's own accept/reject implementation.
-
-Exact comparison is the default. The harness removes Word's terminal paragraph
-mark, normalizes CR/LF representation, and removes the characters Word exposes
-as table-cell and footnote/endnote reference boundaries; case-specific normalized comparison requires an
-explicit reason. Documents are never saved by the automated differential.
-
-For synthetic fixtures, expectations come directly from `original`, `modified`,
-and any explicit full-document expectations in the case. For SuperDoc fixtures,
-Word first reads the declared story from the original pinned source document;
-every target in a single or multi-change scenario must occur exactly once, and
-the accepted expectation is formed by applying those replacements to Word's own
-source text. Header scenarios use Word's header stories rather than body text.
-The corpus packager hashes every package part other than the one intentionally
-replaced by the scenario.
-
-This proves that Word can consume the package, recognizes the revision markup,
-and resolves Accept All and Reject All to the intended text. It does **not**
-prove that the document looks right on the page. `Content.Text` cannot detect
-bad pagination, awkward revision balloons, shifted table widths, broken tab
-alignment, font substitution, changed list indentation, clipped headers,
-visually stale fields, or a comment/footnote marker that is technically present
-but poorly placed.
-
-### Microsoft Word visual review guide
-
-Human visual review complements—not replaces—the automated differential. The
-automated differential proves Word revision semantics by comparing text after
-Accept All and Reject All, but this review checks the layout, typography, and
-interaction details that `Document.Content.Text` cannot see.
-
-Review is required for:
-
-- every new or materially changed synthetic Word case;
-- the first case for a new structure, operation type, or related package part;
-- any engine change affecting reconstruction, formatting, lists, tables,
-  fields, tabs/breaks, comments, notes, headers/footers, or revision metadata;
-- any case that needs normalized rather than exact text comparison; and
-- any automated Word failure whose cause is not immediately textual.
-
-#### Prepare the review set
-
-Run the automated lanes 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.
-
-Selection rules:
-- every new or changed case;
-- every case required by the triggers above;
-- at least 20% of unchanged synthetic cases, rotating from the prior release (so
-  every retained synthetic case receives a human review over five release cycles);
-- at least one legal and one administrative SuperDoc result; and
-- representative list, table, formatted-run, and anchor/field/content-control
-  structures.
-
-A major release or a change to package assembly requires a full visual sweep of
-affected structure families.
-
-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 (3-view checklist)
-
-##### 1. 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.
-
-##### 2. 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.
-- Untargeted content is visually unchanged.
-
-Close the copy without replacing the generated fixture.
-
-##### 3. 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.
-- No content introduced by the edit remains.
-
-#### Record the visual review result
-
-Keep the review report with 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 rights and
-sensitivity.
-
-Suggested report template:
-
-```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 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.
-
-
-### AI-assisted Word visual preflight
-
-Generate repeatable three-view PDF evidence for every layout-sensitive
-synthetic fixture with:
-
-```powershell
-npm run test:word:visual
-```
-
-The command writes PDFs and `manifest.json` under ignored
-`tmp/word-visual-review/rendered/` storage. It verifies that Word opened each
-fixture and produced a non-empty, paginated rendering, but leaves the manifest
-certification and every visual judgment pending. To render only named cases,
-invoke `scripts/word-com-visual-suite.ps1 -Case case-one,case-two` directly.
-
-An AI agent with Windows computer control may also open the generated fixtures
-in the installed desktop Word application, switch among All Markup, Accept All,
-and Reject All views, capture screenshots, and inspect them for visible
-regressions. This is a useful intermediate oracle because it exercises the same
-real UI a person sees rather than only `Document.Content.Text`.
-
-Run an AI visual preflight:
-
-- after a phase that changes reconstruction, formatting, list/table behavior,
-  package assembly, or revision display;
-- after every five to ten new Word fixtures;
-- for all newly introduced structure families;
-- when automated Word passes but the XML change is unusually broad; and
-- before asking a human to perform the release sample, so obvious failures are
-  found first.
-
-For the focused real-document additions, run:
-
-```powershell
-npm run test:corpus:word:visual
-```
-
-This first runs the exact Word differential, then writes 120 PDFs and a pending
-manifest under ignored `tmp/superdoc-word-visual-review/rendered/` storage: three
-views for 22 list-focused cases, 16 table-focused cases, and two page-header
-cases. The long-document set includes 6,000+ word council minutes,
-an 8,000+ word zoning resolution, and a 59,000+ word prospectus with 180 tables.
-Each invocation packages its fixtures in a process-specific directory so
-a Word process left behind by an RPC disconnect cannot lock the next run's
-inputs. The runner ignores `RPC_E_DISCONNECTED` during post-export cleanup and
-restarts Word once when a disconnect interrupts an actual render. After Word
-finishes, the command rebuilds `docs/test-comparison-dashboard.html` from that
-exact process-specific fixture directory. The `Verified cached ...` messages
-refer only to the pinned source-document downloads; edited comparison DOCX
-files are regenerated on every run.
-
-The AI should use the same selection rules and checklist as a human, inspect at
-least the changed cases plus representative legal and administrative samples,
-and save screenshots under ignored `tmp/word-manual-review/<date>/` storage.
-Its report must identify itself as **AI visual preflight**, record the Word
-version/build when available, list the exact cases and views inspected, and
-separate observed facts from uncertain visual judgments.
-
-AI visual review is advisory. It can catch missing or misplaced revisions,
-unexpected whole-paragraph markup, obvious pagination shifts, broken tables,
-lost indentation, clipped headers, and visibly misplaced anchors. It may miss
-subtle font metrics, accessibility issues, field behavior that requires domain
-knowledge, or a legally meaningful formatting distinction. An AI pass does not
-satisfy the human release sign-off, and sensitive/private documents must not be
-opened for AI review without explicit authorization.
-
-### Multimodal LLM visual inspection (real-document spot checks)
-
-Evaluating subtle visual defects—such as shifted table borders, unnatural run
-breaks, font substitution, clipping headers, or awkward revision balloons—requires
-interpreting rendered document pages visually rather than relying solely on
-string assertions or raw XML checks. A multimodal Large Language Model (MLLM)
-with vision capabilities can review rendered page images across the three
-revision views (`allMarkup`, `acceptAll`, and `rejectAll`) and detect regressions
-that are invisible to plain-text diffs.
-
-#### Why multimodal inspection is kept separate
-
-Passing high-resolution, multi-page document images through a vision-capable LLM
-is **expensive, computationally intensive, and time-consuming**:
-
-- Each document scenario produces three full-document rendering views (often 1
-  to 20+ pages per view).
-- Sending dozens of high-resolution page images consumes significant token
-  budgets and model context.
-- Latency per case is orders of magnitude higher than programmatic XML parsing
-  or COM automation.
-
-For these reasons, multimodal visual inspection **forms a separate check from the
-rest of the test suite**. It is never executed on every commit, local test run, or
-full batch pipeline.
-
-#### Sampling strategy: Random real-document spot checks
-
-Instead of exhaustive or continuous execution, multimodal visual inspection is
-conducted as a **random spot check of real documents here and there only**:
-
-1. **Focus on authentic real documents:** Spot checks prioritize the
-   [SuperDoc real-document corpus](#superdoc-real-document-word-tests) rather than
-   simple synthetic fixtures. Real documents contain organic complexities—such
-   as multi-column headers, nested bullet styles, non-uniform table borders, and
-   mixed-font legal numbering—where visual layout errors are most likely to hide.
-2. **Small random sampling:** A typical visual spot-check run selects a random
-   sample of **2 to 5 real document scenarios** (for example, one administrative
-   board agenda, one municipal minutes multi-table document, and one complex
-   zoning ordinance).
-3. **Execution cadence:** Spot checks are run on-demand:
-   - periodically during active engine refactoring;
-   - when introducing major changes to run splitting, table reconciliation, or
-     list reconstruction; or
-   - as an advisory audit prior to a release cycle.
-
-#### Multimodal inspection workflow
-
-When performing a multimodal visual spot check:
-
-1. **Render target pages to images:** Render the selected scenario in Word to
-   PDFs using `scripts/word-com-corpus-visual-suite.ps1 -Case <scenario-name>`,
-   then convert the relevant pages (or contact sheets) to PNG images using the
-   visual inspection helper:
-   ```powershell
-   node scripts/inspect-visual-evidence.mjs --contact-sheets
-   ```
-2. **Submit to the multimodal model:** Provide the vision model with the side-by-side
-   page renders of `allMarkup`, `acceptAll`, and `rejectAll` along with the target
-   diff and context.
-3. **Targeted visual checklist:** Prompt the model to evaluate specific layout risks:
-   - **Table cell integrity:** Did column widths shift? Are table borders intact?
-     Did multi-line cell text collapse or overlap?
-   - **Typography & Font metrics:** Did any run revert to default font size (e.g.
-     dropping from 14pt Georgia to 12pt Normal)? Did bold, italic, or underline
-     bleed into neighboring text?
-   - **List alignment:** Are bullet indents consistent with existing items? Are
-     there ghost markers or blank list rows?
-   - **Page apparatus:** Are headers, footers, and page numbers in their expected
-     margins without clipping or wrapping anomalies?
-4. **Triaging findings:** If the multimodal model flags a visual abnormality,
-   treat it as an advisory signal:
-   - Verify the defect manually in Microsoft Word.
-   - Trace the visual defect to its underlying OOXML cause (per the
-     [visual failure diagnosis guidelines](#diagnose-visual-failures-in-the-generated-ooxml-first)).
-   - Add a minimal semantic regression test in
-     `tests/visual_failure_regression_tests.mjs` to ensure the issue is permanently
-     prevented in the automated suite (`npm test`).
-
-## SuperDoc real-document Word tests
-
-The corpus lane references selected documents from SuperDoc's
-[docx-corpus](https://docxcorp.us/) under ODC-By 1.0. Source documents are never
-committed. `tests/corpus/superdoc-english-legal-administrative.json` pins each
-reviewed source and observed SHA-256; `tests/corpus/superdoc-word-scenarios.json`
-defines named deterministic scenarios and records the structural coverage they
-add. A source may support multiple scenarios when each one adds a distinct
-behavioral claim.
-
-To add a corpus case:
-
-1. Select an English legal or administrative document that adds a structure or
-   task not already represented. Review its content and record why it is
-   suitable.
-2. Add an explicit pinned reference and observed hash to the manifest. Do not
-   use a floating or bulk corpus download.
-3. Fetch only that reference with
-   `npm run corpus:fetch:superdoc -- --id <pinned-id>`.
-4. Inspect the document in Word and choose a target that occurs exactly once in
-   Word's source text.
-5. Add the deterministic operation, shape, coverage labels, and review note to
-   `superdoc-word-scenarios.json`. Use `key` plus `sourceId` when adding another
-   scenario for an already pinned source. Use `operations` for a multi-change
-   atomic batch, or `part: "word/header<N>.xml"` for a page-header revision.
-6. Run `npm test` for manifest/catalogue checks and `npm run test:corpus:word`
-   for package hashing plus the Word Accept All/Reject All differential.
-
-The corpus packager starts from the original `.docx`, replaces only the declared
-revision part (`word/document.xml` by default, or a named header part), and
-verifies every untouched ZIP part byte-for-byte before Word opens the result.
-The Word oracle derives multi-change expectations by applying each independently
-declared replacement to Word's source text and reads header-story text separately
-## Release validation and independent oracles
-
-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 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.
-
-### Pre-release automated check sequence
-
-```bash
-npm test              # includes tests/roundtrip_fuzz_tests.mjs (seeded, deterministic)
-npm run test:isolation
-npm run check:types
-npm run lint
-```
-
-The fuzz harness generates random paragraph structures and edits, asserting 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 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.
-
-### 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
-```
-
-Verifies that a second independent OOXML consumer parses and converts 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 baselines
-
-```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.
-
-Historical reference snapshots:
-
-- **Initial Phase 7 baseline (2026-08-29)**:
-  | Metric | Coverage |
-  |---|---:|
-  | Lines / statements | 79.57% |
-  | Functions | 80.07% |
-  | Branches | 69.22% |
-
-- **Post-Phase-5 snapshot (2026-08-30)**:
-  79.96% lines/statements, 80.95% functions, and 69.52% branches.
-
-- **Post-Phase-5 snapshot (2026-09-04)**:
-  89.81% statements/lines, 93.04% functions, and 77.34% branches repo-wide.
-  The Node surface reports 99.61% statements/lines; `document-inspection.js`
-  reports 97.64% statements/lines and 100% functions; `paragraph-text.js` reports
-  100% statements/lines/functions.
-
-Preserve snapshots so progress is visible over time rather than presenting
-coverage as a single pass/fail quality score.
-
-## Choosing where a new test belongs
-
-- A fixed bug always gets an automated regression.
-- A broad engine rule also gets deterministic fuzz coverage.
-- A claim about what Word renders or accepts gets a synthetic Word case.
-- A claim involving package complexity or realistic authoring structures gets
-  a reviewed corpus case.
-- A structural XML rule should be checked by runtime validation and, where
-  practical, the ECMA-376 XSD lane.
-
-Keep expectations independent of the code under test. In particular, never use
-this library's Accept/Reject helpers to calculate the expected result for the
-Word differential.
+# Testing Guide
+
+This project uses several test lanes because no single oracle can prove that a
+tracked-change document is correct. JavaScript assertions can verify exact XML
+and return contracts; Microsoft Word can verify what the primary consumer
+actually accepts and rejects; real documents expose structures that small
+fixtures rarely contain.
+
+## Test lanes at a glance
+
+| Lane | Command | What it proves | What it does not prove |
+|---|---|---|---|
+| Automated regression suite | `npm test` | API behavior, exact text invariants, OOXML structure, deterministic fuzz cases, and catalogue integrity | That desktop Word accepts the generated package |
+| Isolation, types, and lint | `npm run test:isolation`, `npm run check:types`, `npm run lint` | Runtime boundaries, declaration alignment, and static repository rules | Document correctness |
+| JavaScript coverage | `npm run test:coverage` | Which source lines, functions, and branches the automated suite executes | That an executed path is correct |
+| Synthetic Word differential | `npm run test:word` | Word opens generated packages, sees revisions, and produces the intended text after Accept All and Reject All | The diversity of real-world packages |
+| Word visual evidence | `npm run test:word:visual` | Word renders layout-sensitive fixtures in All Markup, Accept All, and Reject All views and writes a pending review manifest | That the rendered pages are visually correct until a reviewer inspects them |
+| SuperDoc Word corpus | `npm run test:corpus:word` | The same Word differential on 60 scenarios drawn from 23 reviewed, pinned real English legal/administrative documents while untouched package parts remain byte-identical | Every possible DOCX producer or document type |
+| SuperDoc visual evidence | `npm run test:corpus:word:visual` | Word renders 40 focused list, table, long-document, and page-header scenarios in All Markup, Accept All, and Reject All views | Human visual sign-off |
+| Visual evidence inspection | `npm run test:visual:inspect` | Automated inspection of rendered Word PDFs across synthetic and SuperDoc suites (page counts, PDF integrity, anomaly detection) | Human visual sign-off |
+| Visual failure regressions | `node tests/visual_failure_regression_tests.mjs` | Semantic OOXML guards against visual failures (formatting leaks, font resets, ghost bullets, table cell destruction) | Visual rendering proof in Word |
+| 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 (see the Word revision semantics row) |
+| Word revision semantics | `node tests/word_revision_semantics_tests.mjs` | The Reject All / Accept All projection in `core/word-revision-semantics.js` and the library's reject/accept agree with recorded desktop Word 16 results for each paragraph-mark revision shape (inserted/deleted marks mid-document, last paragraph, table cells, rows, lists, `w:pPrChange`, mixed authors); no Word needed to run | That Word still behaves as recorded (regenerate the expectations) |
+| Revision fidelity verifier | `node tests/revision_fidelity_verifier_tests.mjs` | Post-apply Reject All invariants (`REJECT_*`), `ACCEPT_NEIGHBORS` locality and `UNTRACKED_CREATED_REVISION` for untracked edits, accept-first scoping, modes, baseline cache, and the `REVISION_FIDELITY_VIOLATION` payload through the bare runner and `openDocx` | Desktop Word behavior beyond the recorded semantics |
+| Revision fidelity view cache | `node tests/revision_fidelity_view_cache_tests.mjs` | Session reuse of verified projections as the next baseline: an untracked edit between tracked ones, a refused operation and an unverified commit verify exactly like uncached single operations | Performance numbers (see `scripts/benchmark-operation-session.mjs`) |
+| Paragraph-mark and property layering | `node tests/paragraph_mark_single_site_tests.mjs`, `node tests/current_properties_usage_tests.mjs` | Tracked paragraph-mark `w:ins`/`w:del` is constructed only in `engine/paragraph-mark-revisions.js`; current properties are read only through `core/current-properties.js` (allowlists carry written reasons) | Behavior of the allowed sites |
+| 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`, `node tests/agent_cli_protocol_tests.mjs`, `node tests/agent_cli_help_tests.mjs`, `node tests/agent_cli_inspection_context_tests.mjs`, `node tests/agent_cli_output_budget_tests.mjs` | JSON contracts, command-specific help, contextual pagination, composable progressive/atomic profiles, deduplicated receipts, compact stdout, file/stdin Unicode fidelity, complete-success exits, source safety, command families, and 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, examples lead with scoped contextual extraction, and packaged skill-authoring guidance separates invariants, policies, transports, recovery, and presentation 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 |
+| Target hot-path parity | `node tests/performance_phase3_target_hot_paths_tests.mjs` | Cached and uncached resolution metadata parity, duplicate safety, snapshots, session invalidation, and pointer-based revision-ID seeding | Machine-independent latency thresholds |
+| List and text-walker parity | `node tests/performance_phase4_list_and_text_parity_tests.mjs` | One shared marker vocabulary and canonical/specialized visible-text agreement across structural characters and revision views | That all specialized mappings are interchangeable |
+| Universal document facade & ZIP | `node tests/universal_docx_document_tests.mjs`, `node tests/universal_zip_archive_tests.mjs`, `node tests/universal_facade_edge_cases_tests.mjs` | Universal `Uint8Array` binary handling, `fflate` compression/decompression, optimistic concurrency, and complete-DOCX operations without Node built-ins | Desktop Word rendering |
+| Sandbox bundle isolation | `node tests/sandbox_bundle_isolation_tests.mjs` | Zero-dependency standalone ESM/CJS bundles execute in restricted VM sandboxes without `process`, `Buffer`, or `require`, with zero Node built-in imports | Web Worker latency |
+| Existing-revision policy `auto` | `node tests/existing_revisions_auto_tests.mjs`, `node tests/existing_revisions_auto_paths_tests.mjs` | Per-target resolution to `merge-same-author` or `slice-cross-author` (mixed, unattributed and deletion-only history, whole `targetEnd` ranges, table cells), equivalence with the explicit policy through `applyRedlineToOxml` and the runner, preflight reporting, untracked edits, `openDocx`, `--existing-revisions auto`, schema and the CLI capability | Desktop Word rendering |
+| Comment reply paraIds | `node tests/comment_reply_para_id_tests.mjs` | A reply's `w14:paraId` avoids body paragraph ids (case-insensitive) and stays deterministic without a collision | Word's own id allocation |
+| Inspection comparison | `node tests/inspection_comparison_tests.mjs` | `compareDocumentInspections` ignores ids, dates, comment order and run splits and reports text, review-segment (author, kind, position), table, list-label and comment (text, author, anchor, resolved, thread) differences, capped at 10; works on `openDocx` inspections | A host's own write path |
+| Literal underscores and plain text | `node tests/literal_underscore_text_tests.mjs` | Signature lines and `snake_case` survive table reconciliation and rewrites; CommonMark underscore flanking; a caller's `structuredContent: false` keeps inline Markdown literal | Desktop Word rendering |
+| Cross-author revision slicing | `node tests/cross_author_slicing_fixtures_tests.mjs`, `node tests/cross_author_carrier_splitting_tests.mjs`, `node tests/cross_author_slicing_synthetic_tests.mjs`, `node tests/cross_author_slicing_real_tests.mjs`, `node tests/cross_author_slicing_hyperlink_roundtrip_tests.mjs`, `node tests/cross_author_slicing_insertion_stress_tests.mjs` | Word-native `<w:ins>` splitting, `<w:del>` nesting, multi-author stacking, straddle boundaries, synthetic matrix (SYN-01..12d), strict package differential replay (PKG-01..06), exact hyperlink/NBSP round trips, and 76 insertion stress scenarios | Non-Word consumers beyond OpenXML XSD validation |
+
+The package-facade regression opens a real ZIP buffer, adds a comment beside an
+existing high ID, validates OPC wiring, and checks an unrelated binary part is
+unchanged after extraction. Its failure case requires byte-exact rollback. The
+inspection regression covers revisions, structural characters, heading
+context, comment joining, and a numbering start override.
+
+The CLI regression executes the recommended extract → preflight → apply →
+validate flow and also covers accept, reject, comment deletion, output collision
+refusal, and source-byte preservation. CLI stdout is captured and parsed as one
+JSON value so diagnostic logging cannot corrupt agent output.
+
+The edge suites deliberately use structures omitted from the basic happy-path
+fixtures: `w:moveFrom`/`w:moveTo`, deleted text, structural breaks and hyphens,
+comments crossing paragraph boundaries, orphan definitions, outline headings,
+footnote/endnote references, nested Roman/alphabetic numbering, sequential
+commit-then-rollback calls, selective comment authors, existing high anchor
+IDs, encrypted/unsupported ZIP entries, `--force`, and `--in-place`.
+
+The Phase 2 boundary regression is intentionally structural as well as
+behavioral. It prevents the public runner from accumulating implementation
+logic again, verifies that internal operation code does not import the root
+entry point, and checks that failed atomic work can retain the exact source
+string while working maps and sets remain isolated until commit.
+
+The checked post-Phase-5 2026-09-04 coverage run reports 89.81%
+statements/lines, 77.34% branches, and 93.04% functions repository-wide; this
+is above every recorded pre-refactor dimension. Targeting performance can be
+measured in Node with `npm run benchmark:targeting` and against the native DOM
+by serving the repository locally and opening
+`scripts/benchmark-targeting-browser.html`; its `paragraphs`, `operations`, and
+`iterations` query parameters reproduce the checked fixture sizes.
+The Node surface reports 99.61% statements/lines; `document-inspection.js`
+reports 97.64% statements/lines and 100% functions; `paragraph-text.js` reports
+100% statements/lines/functions.
+
+Run the observational live-session benchmark with:
+
+```powershell
+npm run benchmark:session
+```
+
+It writes `tmp/benchmarks/operation-session-latest.json`. The checked
+1,000-paragraph/10-operation run reduced full-document parse/serialization from
+10/10 to 1/1 and measured a 1.58x median speedup. Timing and heap figures are
+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).
+
+Run the CLI discovery/output benchmark with:
+
+```powershell
+npm run benchmark:agent-cli
+```
+
+It records command-specific help size, broad inspect/search response size,
+context-window call count, pagination metadata, case-insensitive match parity,
+and native elapsed time in `tmp/benchmarks/agent-cli-discovery-latest.json`.
+The checked WP-00 through WP-02 before/after measurements are in the
+[agent CLI discovery baseline](validation-reports/2026-09-12-agent-cli-discovery-baseline.md).
+WP-03 through WP-05 profile, output-size, workflow, documentation, and package
+results are in the
+[agent CLI efficiency rollout audit](validation-reports/2026-09-13-agent-cli-efficiency-rollout.md).
+
+## Cross-author revision slicing test suite
+
+The cross-author revision slicing subsystem introduces six complementary test lanes:
+
+1. **Native Word Desktop Fixtures (`tests/cross_author_slicing_fixtures_tests.mjs`)**:
+   Verifies 36 reference `.docx` and `.xml` files generated via Microsoft Word Desktop 365 COM automation across 6 golden scenarios (`insert-interior`, `delete-interior`, `delete-boundary-start`, `delete-boundary-end`, `delete-straddle-baseline-insertion`, and `multi-author-stacked`) in pending, accepted, and rejected states. Proves Word-native OOXML patterns (carrier `<w:ins>` splitting for insertions, direct `<w:del>` nesting inside `<w:ins>` for deletions) and lifecycle parity under `acceptTrackedChangesInOoxml` and `rejectTrackedChangesInOoxml`.
+2. **Carrier Splitting Unit Suite (`tests/cross_author_carrier_splitting_tests.mjs`)**:
+   Tests `splitTrackChangeCarrier` across interior and boundary cuts, multi-run formatting preservation, stable metadata cloning, independent revision ID allocation via `RevisionIdAllocator`, and immutable input handling.
+3. **Synthetic Boundary Matrix (`tests/cross_author_slicing_synthetic_tests.mjs`)**:
+   Executes the full SYN-01 through SYN-12d test matrix covering pure interior inserts, pure interior deletes, boundary start/end cuts, full-content annihilation, baseline/insertion straddles, multi-carrier straddles, formatting preservation, paired replacements, 3-author stacked revisions, and selective author accept/reject lifecycle oracles.
+4. **Checked-In Word Package Differential Suite (`tests/cross_author_slicing_real_tests.mjs`)**:
+   Reconstructs the pre-mutation document packages, applies `slice-cross-author` via the strict `openDocx` package facade, enforces atomic package validation, and compares engine `AcceptAll` and `RejectAll` output against Word Desktop-generated golden packages (PKG-01 through PKG-06).
+5. **Hyperlink and Exact-Text Regression (`tests/cross_author_slicing_hyperlink_roundtrip_tests.mjs`)**:
+   Reproduces the repeated-phrase, hyperlink-boundary, and NBSP-to-space failure through both the low-level engine and document operation runner. It requires exact accepted-view equality, preserves both hyperlink relationship containers, and proves that an unreconstructable slicing mutation returns `PATCH_ROUNDTRIP_MISMATCH` with the original OOXML unchanged.
+6. **Insertion Stress Matrix (`tests/cross_author_slicing_insertion_stress_tests.mjs`)**:
+   Runs 76 deterministic scenarios across carrier start/end/interior positions, repeated phrases, multi-run and formatted carriers, spaces/tabs/NBSP, XML-sensitive characters, emoji/combining Unicode, hyperlink interiors and boundaries, bookmarks, comments, nested deletions, adjacent authors, mixed same/foreign-author carriers, multiple structural containers, consecutive reviewer rounds, and the atomic document runner. Every supported case requires exact current-view, Accept-All, Reject-Current, schema, metadata, and non-empty-wrapper invariants; unsupported nested structures must fail without throwing or returning changed output.
+
+## Coverage matrix and test selection
+
+Run the deterministic task-by-structure report before choosing the next Word
+case:
+
+```powershell
+npm run report:word:coverage
+npm run report:word:coverage -- --json
+npm run report:test:dashboard
+```
+
+The dashboard command writes a self-contained interactive report to
+`docs/test-comparison-dashboard.html`. It compares task/structure cells,
+synthetic and real-document coverage, independent oracles, visual-render
+eligibility, and planned high-priority gaps from the live catalogues. It also
+embeds source, tracked, accepted, and rejected packages for every synthetic
+fixture and, when the pinned corpus is downloaded, all 60 reviewed real legal
+and administrative scenarios. Its `docx-preview` workbench supports arbitrary left/right states,
+comparison presets, synchronized scrolling, revision metadata, expected text,
+and local downloads; no fixture upload or file picker is required. Real cases
+are labeled in the document selector and selected by default when available.
+Use **Hide sidebar** beside the dashboard filters to remove the coverage-detail
+column and expand the comparison workbench to the full browser width. The
+button becomes **Show sidebar**, and the preference is stored locally so the
+wide document view survives a reload.
+Without the local corpus, generation remains offline-safe and embeds only the
+synthetic previews.
+
+The report combines all synthetic and reviewed SuperDoc scenarios. Synthetic
+metadata is declared in `tests/fixtures/word-task-coverage.mjs`; SuperDoc
+metadata is declared in `tests/corpus/superdoc-word-coverage.json`. Descriptive
+`task`, `shape`, and `coverage` labels remain on the original cases as review
+notes, while the matrix uses shared task, structure, and oracle vocabularies.
+
+Catalogue tests reject unknown vocabulary labels, missing oracle or manual-review
+metadata, duplicate identities, structural claims unsupported by fixture XML or
+reviewed corpus labels, and uncovered high-priority cells without a recorded
+plan or exclusion. The dispositions live in
+`tests/fixtures/coverage-matrix-priorities.json` and require both a reason and a
+dependency.
+
+Choose new cases from uncovered high-priority cells first, then prefer a new
+task/structure combination over another case in a dense cell. A higher count is
+not itself a reason to add a fixture. Adding a catalogue case automatically
+changes the report because it reads the live metadata.
+
+## Reliability improvement process used for this test expansion
+
+The current corpus, visual runners, and comparison dashboard were built as one
+feedback loop rather than as separate test features. The working sequence is:
+
+1. inventory the claimed behavior and existing test lanes;
+2. add realistic cases that expose weak structures;
+3. assert the smallest machine-checkable invariant at the engine level;
+4. package the result into the original real document without changing
+   unrelated parts;
+5. ask Word to accept and reject the revisions;
+6. render All Markup, Accept All, and Reject All views;
+7. inspect the actual pages at both contact-sheet and full-page scale; and
+8. turn every visual defect into a focused regression plus a corpus assertion.
+
+This ordering matters. A valid `<w:ins>` or `<w:del>` tree does not establish
+that the inserted run inherited the correct font, list indentation, hyperlink
+wrapper, table-cell formatting, or header styling. Conversely, a good-looking
+PDF does not prove that Reject All restores the exact source. Each stage answers
+a different question, and a case is useful only when its intended claim is
+explicit.
+
+### Start from coverage claims, not fixture count
+
+Read the task-by-structure matrix and select a real document that adds a missing
+or weak combination. The expansion deliberately favored bullets, nested lists,
+table cells, headers, long documents, and atomic multi-change batches because
+these structures cross more OOXML boundaries than a single plain paragraph.
+Several scenarios reuse a pinned source when a new batch exercises a genuinely
+different structure; this increases behavioral coverage without pretending
+that another copy of the same document is a new source.
+
+For long real documents, record structural minimums such as word count, table
+count, list-paragraph count, section count, and related header/footer parts.
+`scripts/prepare-superdoc-word-corpus.mjs` checks these declarations against the
+source package. This prevents a scenario description such as “table-heavy” or
+“multi-section” from silently drifting away from the actual fixture.
+
+### Use multi-change batches to exercise interaction effects
+
+Single replacements remain valuable for isolating engine behavior, but real
+editing sessions usually contain several changes. The larger corpus scenarios
+therefore use `operations` to apply independent edits atomically across one
+document. Targets are chosen from different list items or table cells when
+possible. This catches failures caused by earlier replacements shifting later
+anchors, revision-ID allocation across a batch, and formatting state leaking
+between operations.
+
+The batch runner must either produce all requested revisions or roll back the
+document. Word then checks the complete accepted and rejected story, not merely
+the first target. Untouched ZIP parts are hashed and compared with the pinned
+source, so success cannot come from rebuilding or normalizing the rest of the
+package.
+
+### Expand weak list and table cells with structural operations
+
+The list/table expansion was driven directly by the task-by-structure matrix;
+it did not add more plain replacement cases. The current catalogue contains 125
+Word cases: 65 synthetic fixtures and 60 reviewed real-document scenarios. The
+`List Change × List` cell now contains 27 cases; the
+`Table Reconciliation × Table` cell contains 11 cases.
+
+The added synthetic cases isolate one structural decision at a time:
+
+- append one list item;
+- append several adjacent items;
+- add a nested child;
+- insert into the middle of an explicit list range;
+- preserve upper- and lower-Roman numbering;
+- preserve upper-letter, parenthesized lower-letter, dash, and symbol bullets;
+- expand a manually numbered heading whose `w:numId="0"` suppresses numbering
+  into separate, positively numbered list paragraphs;
+- update one table cell;
+- insert a table row;
+- delete a table row; and
+- update several cells in one reconciliation.
+
+The mixed-attachment fixture replaces one anchor with explicit headings,
+ordinary paragraphs, a Markdown table, and a numbered list. It verifies real
+`w:pStyle`, `w:tbl`, and positive-numbering structures plus independent Word
+Accept All and Reject All results; literal table pipes are forbidden.
+
+The real-document cases repeat those claims against native numbering and table
+markup from municipal notices, board agendas, a long zoning ordinance, PPG
+minutes, action tables, and invoice tables. They include consecutive and nested
+list insertions, a long-document definition insertion, single- and multi-cell
+updates, row insertion/deletion, and invoice row changes. Reusing a reviewed,
+hash-pinned source is intentional when the scenario exercises a different
+operation; the unit of coverage is the behavioral claim, not the download.
+
+These cases declare `operation.type` as `list-change` or
+`table-reconciliation`. Their accepted/rejected expectations use explicit
+contains/absent assertions when a Markdown table payload or a structural list
+edit cannot be compared meaningfully to the raw Word source as one exact text
+string. Structural expectations still verify real properties such as native
+list paragraphs, tables, headers/footers, sections, and minimum document size.
+The catalogue tests require these expectations and reject unknown operation or
+coverage labels.
+
+List-style cases do not infer their claim from visible text alone. Synthetic
+fixtures declare the required `w:numFmt` values and use complete, schema-ordered
+numbering parts: every `w:abstractNum` must precede the first concrete `w:num`
+mapping. That ordering is regression-tested because Word otherwise opens the
+package but silently substitutes its fallback bullet. Real scenarios declare a
+`listStyleExpectation` with the source level, number format, and, where useful,
+the exact `w:lvlText`. Corpus preparation resolves the target paragraph's
+`w:numId` through `word/numbering.xml` and fails before editing if the pinned
+source no longer has that native style. The current real cases exercise upper
+and lower Roman, upper and lower letter, parenthesized lower letter, dash, and
+symbol bullets across bylaws, agendas, healthcare minutes, and long council
+minutes.
+
+### Diagnose visual failures in the generated OOXML first
+
+When a page looks wrong, compare the relevant source and tracked
+`word/document.xml` or related part before changing the renderer. Locate the
+visible text, inspect its nearest `w:r`, `w:rPr`, wrapper, paragraph properties,
+and neighboring runs, then compare those properties with the source. This
+separates an engine defect from a Word, PDF, or `docx-preview` display issue.
+
+Three defects illustrate the approach:
+
+- The council header date replacement inherited `w:vertAlign="superscript"`
+  from the trailing ordinal suffix. The fix anchors replacement formatting at
+  the beginning of the deleted range, and the regression explicitly forbids
+  `vertAlign` on the inserted runs.
+- The prospectus filing-date replacement crossed normal runs and a hyperlink.
+  A forward-only property lookup had already moved past the beginning of the
+  deletion when the insertion asked for its formatting, so the new run had no
+  `w:rPr`. Word and SuperDoc correctly fell back from the surrounding 10 pt to
+  the document default of 12 pt. The lookup now supports that deliberate
+  backward query. The focused regression requires `w:sz="20"` and
+  `w:szCs="20"`, and the real prospectus scenario requires those values on
+  every inserted text run.
+- A wholly inserted list item originally tracked only its text run. Accept All
+  looked correct and text-only Reject All assertions passed, but Word retained
+  the untracked paragraph mark as an empty bullet or number. Inserted list
+  paragraphs now track both their text and paragraph mark. The regression
+  rejects the change and asserts the exact original paragraph count, text, and
+  numbering, while the real Word PDFs confirm that no ghost marker remains.
+
+These assertions test the semantic cause rather than a screenshot pixel. The
+visual render remains necessary to confirm that the corrected properties
+produce the intended page. The automated test suite in
+`tests/visual_failure_regression_tests.mjs` codifies these guards directly in
+the regression test pipeline (`npm test`) to prevent regressions before DOCX
+packages reach Word.
+
+### Regenerate packages; do not reason from stale outputs
+
+Source downloads are content-addressed and may be reused. Generated tracked,
+accepted, rejected, PDF, and dashboard artifacts are outputs and must be
+rebuilt after an engine or scenario change. A `Verified cached ...` line from
+the corpus fetcher means only that the pinned source `.docx` already matches its
+recorded hash; it does not mean the edited package was reused.
+
+Use this sequence for a corpus-affecting engine change:
+
+```powershell
+npm test
+npm run check:types
+npm run lint
+npm run test:isolation
+npm run test:corpus:word
+npm run test:corpus:word:visual
+npm run report:test:dashboard
+```
+
+For faster iteration, `prepare-superdoc-word-corpus.mjs` accepts
+`--input-dir` and `--output-dir`, and the visual PowerShell runner accepts
+`-Case <scenario-key>` plus custom fixture/output directories. Run the complete
+lane before handoff even when a focused render passed.
+
+### Treat Word COM cleanup separately from render success
+
+Word sometimes disconnects a COM document proxy after successfully exporting
+a PDF and raises `RPC_E_DISCONNECTED` during `Document.Close()`. The visual
+runner uses safe close/quit helpers: a disconnect during post-export cleanup is
+reported but does not discard a valid, non-empty PDF; a disconnect during the
+actual render causes Word to restart and the case to retry once. Other COM
+exceptions still fail the run. This distinction avoids both false failures and
+false passes.
+
+Each visual invocation uses a process-specific fixture directory. That keeps a
+Word process left behind by an earlier disconnect from locking or contaminating
+the next set of generated DOCX files.
+
+### Review both the whole document and the changed page
+
+For a long document, create low-resolution contact sheets for every page in all
+three revision states and inspect them for pagination changes, blank pages,
+clipping, table displacement, or large typography shifts. Then inspect every
+changed page at full resolution. Contact sheets are good at document-wide
+layout; they are not reliable for a 10 pt versus 12 pt difference or a leaked
+superscript flag.
+
+Record the exact scenario, Word version/build, revision view, page, observed
+fact, and whether the judgment is certain. The visual manifest remains pending
+until a reviewer makes that judgment; successful PDF export alone is not a
+visual pass.
+
+### Keep the dashboard generated and test its controls
+
+`scripts/generate-test-dashboard.mjs` owns the dashboard markup, styles, and
+behavior. Do not hand-edit `docs/test-comparison-dashboard.html`; rebuild it
+with `npm run report:test:dashboard`. The report embeds the four DOCX states so
+it remains self-contained and can show the exact generated packages without a
+file picker or server.
+
+Dashboard changes require generator-level assertions in
+`tests/test_dashboard_report_tests.mjs`. The sidebar-width control, for
+example, is checked for its accessible relationship, full-width CSS state, and
+persisted preference. DOCX package parsing remains covered separately by
+`tests/docxjs_dashboard_rendering_tests.mjs`. When browser control is available,
+also click the control in the generated page and verify that the sidebar is
+hidden, both document panes widen, the label changes, and reloading preserves
+the selected state.
+
+### Definition of done for a discovered real-document defect
+
+A visual defect is complete only when all of the following are true:
+
+- the source and faulty generated OOXML have been compared;
+- the engine cause is understood rather than masked in CSS or the renderer;
+- a minimal automated regression reproduces the structural boundary;
+- Accept All yields the requested text and Reject All restores the source;
+- the affected real corpus scenario has an appropriate structural or
+  formatting assertion;
+- its source, tracked, accepted, and rejected packages have been regenerated;
+- desktop Word differential passes;
+- the changed page and the document-wide three-view render have been inspected;
+- the self-contained comparison dashboard has been rebuilt; and
+- the full automated, isolation, type, lint, and whitespace checks pass.
+
+Prepare, but do not approve, a human review sample with:
+
+```powershell
+npm run review:word:prepare -- --cycle=0
+```
+
+The ignored `tmp/word-manual-review/review-manifest-cycle-0.json` selects all
+catalogue families changed in the worktree, a rotating 20% synthetic sample,
+and one legal plus one administrative SuperDoc case. Every All Markup, Accept
+All, Reject All, and human sign-off field starts as `pending`; the helper cannot
+turn them into passes. Increment `--cycle` between releases to rotate the
+unchanged sample.
+
+## Automated JavaScript tests
+
+Files matching `tests/*.mjs` are discovered by `scripts/run-tests.mjs`. Tests
+use `assert/strict` and each runs in a separate Node process. The runner uses up
+to four workers by default while preserving filename-sorted reporting. Set
+`DOCX_TEST_CONCURRENCY=1` for deterministic serial reproduction, or another
+positive integer for an explicit worker bound. Word, visual, and corpus lanes
+remain separate serial commands. Shared OOXML assertions belong in
+`tests/helpers/ooxml-assertions.mjs`; XML-provider setup belongs in
+`tests/setup-xml-provider.mjs`.
+
+Measure serial and parallel execution on the same machine with:
+
+```powershell
+npm run benchmark:tests
+```
+
+The benchmark performs paired warmups/runs and writes its JSON result to
+`tmp/benchmarks/test-runner-latest.json`. The checked Node 24/Windows x64 run
+reduced median time from 18.02 seconds to 7.96 seconds (55.80%). Twenty
+consecutive four-worker runs completed without a failure.
+
+For function-level gap work, run:
+
+```powershell
+npm run test:coverage
+npm run coverage:gaps
+npm run coverage:gaps -- --json
+```
+
+The coverage command emits both the text summary and detailed Istanbul JSON.
+The gap report includes only runtime production roots, lists each uncovered
+function with its file and declaration line, assigns the Phase 3 P0/P1/P2
+priority, and fails if a targeted file drops below the checked covered-function
+or covered-branch baseline in `tests/coverage-data/phase3-baseline.json`. Because V8
+discovers new branch sites when a formerly cold function first executes, review
+covered counts and behavior assertions alongside percentages. Do not add ignore
+annotations or call private code merely to improve a score; classify a retained
+gap with a reachability or environment reason.
+
+For an engine regression:
+
+1. Add the smallest fixed case that reproduces the bug and asserts the exact
+   result or structured error.
+2. Assert both sides of tracked changes: accepting must produce the requested
+   text and rejecting must restore the original text exactly.
+3. Assert structural invariants with `validateRedlineOoxml` and the shared OOXML
+   helpers. Do not use a whitespace-collapsing reader as the oracle.
+4. If engine behavior changed, add the same shape to the deterministic fuzz
+   corpus so nearby inputs are exercised too.
+5. Run `npm test`, isolation, types, and lint.
+
+For a mixed attachment regression, also run the content through
+`planStructuredReplacement(...)`. Assert the declared block sequence, reject
+malformed table grammar, and verify that the result contains real `w:tbl`,
+heading styles, positive list numbering IDs, valid non-nested revisions, and
+independent Accept/Reject outcomes. Do not treat absence of literal pipe text as
+sufficient proof of a table.
+
+## Synthetic Microsoft Word tests
+
+Run only one Word job at a time. `scripts/word-com-suite.ps1` and
+`scripts/word-com-corpus-suite.ps1` begin by force-killing every windowless
+`WINWORD` process to clear orphans from aborted runs, which also kills the
+invisible Word instance of any other COM job running concurrently.
+
+The runtime library contains no COM or Word dependency. Word automation exists
+only in Windows development scripts and is intentionally excluded from package
+runtime paths.
+
+The synthetic catalogue is `tests/fixtures/word-task-cases.mjs`. During
+`npm run test:word`:
+
+1. `scripts/export-validation-fixtures.mjs` applies each operation, runs the
+   library's structural validator, checks any case-specific `requiredElements`,
+   and builds a minimal `.docx` under ignored `tmp/word-validation/` storage.
+2. Expected Accept All and Reject All text is derived from the test's edit
+   intent, not from the library's own revision-management functions.
+3. `scripts/word-com-differential.ps1` opens each fixture through desktop Word
+   without a repair dialog and confirms Word sees at least one revision.
+4. Word accepts every revision in one fresh document and rejects every revision
+   in another. Both resulting texts are compared with the intent-derived
+   expectations.
+
+To add a synthetic Word case:
+
+1. Add a unique lowercase-hyphenated entry to `WORD_TASK_CASES` with
+   `category: 'legal'` or `'administrative'`, a distinct `task`, and `original`
+   and `modified` text.
+2. Use `sourceDocumentXml` when the case needs bookmarks, hyperlinks, tables,
+   content controls, prior revisions, or another deliberate structure.
+3. Add `requiredElements`, such as `{ bookmarkStart: 1, bookmarkEnd: 1 }`, when
+   retaining a structure is part of the claim. These are minimum namespace-aware
+   element counts checked before Word runs.
+4. Supply `expectedAcceptedText` and `expectedRejectedText` when the source is a
+   multi-paragraph document or Word exposes structural separators such as table
+   row boundaries.
+5. Run `node tests/word_task_catalog_tests.mjs`, then `npm run test:word` on a
+   Windows machine with desktop Word installed.
+
+### Related-part fixture schema
+
+The script-only packager supports optional numbering plus comments, footnotes,
+endnotes, headers, footers, and external hyperlinks. Add them to a catalogue
+case through `packageParts`:
+
+```js
+{
+  sourceDocumentXml,
+  packageParts: {
+    commentsXml,
+    footnotesXml,
+    endnotesXml,
+    headers: [{
+      partName: 'header1.xml',
+      relationshipId: 'rIdHeader1',
+      xml: headerXml
+    }],
+    footers: [{
+      partName: 'footer1.xml',
+      relationshipId: 'rIdFooter1',
+      xml: footerXml
+    }],
+    externalHyperlinks: [{
+      relationshipId: 'rIdPolicy',
+      target: 'https://example.com/policy'
+    }]
+  }
+}
+```
+
+`createCommentsPart`, `createNotesPart`, and `createHeaderFooterPart` in
+`tests/fixtures/word-package-parts.mjs` provide small escaped constructors for
+the common XML parts. Header/footer `partName` and `relationshipId` values have
+deterministic defaults, but explicit values make the corresponding
+`w:headerReference`, `w:footerReference`, or `w:hyperlink` easier to audit.
+
+Before ZIP emission, the packager rejects malformed XML, duplicate relationship
+IDs or part names, missing relationship targets, undefined comment/note IDs,
+and note parts without separator IDs `-1` and `0`. It generates the required
+content-type overrides and document relationships. Every supplied related part
+is compared byte-for-byte with the packaged entry, recorded as SHA-256 in the
+case sidecar, and rechecked by the Word differential before opening the DOCX.
+These helpers remain under `scripts/` and `tests/`; none are shipped through the
+runtime entry point.
+
+List cases may declare `expectedAcceptedListStrings` / `expectedRejectedListStrings` (per-paragraph
+`ListFormat.ListString`) and `expectedAcceptedListGroupSizes` (per-paragraph
+`ListFormat.List.ListParagraphs.Count`, 0 for a non-list paragraph). The group sizes tell one list from two lists
+that merely read `A.` and `B.` through start values (R2).
+
+### What the automated Word differential proves
+
+The Word process is real desktop Microsoft Word, but it is driven invisibly
+through COM. For each fixture, the script:
+
+1. starts `Word.Application` with alerts and the window disabled;
+2. opens the generated package with `OpenNoRepairDialog`;
+3. fails if Word cannot open it or sees zero tracked revisions;
+4. accepts all revisions and reads `Document.Content.Text`;
+5. closes without saving, reopens the untouched fixture, rejects all revisions,
+   and reads the text again; and
+6. compares both results with expectations that were not calculated by this
+   library's own accept/reject implementation.
+
+Where the case has a source package the script also compares the paragraph count after
+Reject All with the source package's paragraph count and fails on a mismatch, so
+a leftover or extra paragraph mark is caught even when the text matches.
+
+Accept All and Reject All are issued through `Document.Revisions.AcceptAll()` /
+`RejectAll()` (per-range `Revisions` for header stories). Do not use
+`Document.AcceptAllRevisions()` / `RejectAllRevisions()` in COM scripts: when
+the last body paragraph has a tracked-inserted mark they can leave that mark and
+an extra empty paragraph behind, unlike the ribbon command and Word users.
+
+Exact comparison is the default. The harness removes Word's terminal paragraph
+mark, normalizes CR/LF representation, and removes the characters Word exposes
+as table-cell and footnote/endnote reference boundaries; case-specific normalized comparison requires an
+explicit reason. Documents are never saved by the automated differential.
+
+For synthetic fixtures, expectations come directly from `original`, `modified`,
+and any explicit full-document expectations in the case. For SuperDoc fixtures,
+Word first reads the declared story from the original pinned source document;
+every target in a single or multi-change scenario must occur exactly once, and
+the accepted expectation is formed by applying those replacements to Word's own
+source text. Header scenarios use Word's header stories rather than body text.
+The corpus packager hashes every package part other than the one intentionally
+replaced by the scenario.
+
+This proves that Word can consume the package, recognizes the revision markup,
+and resolves Accept All and Reject All to the intended text. It does **not**
+prove that the document looks right on the page. `Content.Text` cannot detect
+bad pagination, awkward revision balloons, shifted table widths, broken tab
+alignment, font substitution, changed list indentation, clipped headers,
+visually stale fields, or a comment/footnote marker that is technically present
+but poorly placed.
+
+### Microsoft Word visual review guide
+
+Human visual review complements—not replaces—the automated differential. The
+automated differential proves Word revision semantics by comparing text after
+Accept All and Reject All, but this review checks the layout, typography, and
+interaction details that `Document.Content.Text` cannot see.
+
+Review is required for:
+
+- every new or materially changed synthetic Word case;
+- the first case for a new structure, operation type, or related package part;
+- any engine change affecting reconstruction, formatting, lists, tables,
+  fields, tabs/breaks, comments, notes, headers/footers, or revision metadata;
+- any case that needs normalized rather than exact text comparison; and
+- any automated Word failure whose cause is not immediately textual.
+
+#### Prepare the review set
+
+Run the automated lanes 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.
+
+Selection rules:
+- every new or changed case;
+- every case required by the triggers above;
+- at least 20% of unchanged synthetic cases, rotating from the prior release (so
+  every retained synthetic case receives a human review over five release cycles);
+- at least one legal and one administrative SuperDoc result; and
+- representative list, table, formatted-run, and anchor/field/content-control
+  structures.
+
+A major release or a change to package assembly requires a full visual sweep of
+affected structure families.
+
+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 (3-view checklist)
+
+##### 1. 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.
+
+##### 2. 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.
+- Untargeted content is visually unchanged.
+
+Close the copy without replacing the generated fixture.
+
+##### 3. 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.
+- No content introduced by the edit remains.
+
+#### Record the visual review result
+
+Keep the review report with 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 rights and
+sensitivity.
+
+Suggested report template:
+
+```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 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.
+
+
+### AI-assisted Word visual preflight
+
+Generate repeatable three-view PDF evidence for every layout-sensitive
+synthetic fixture with:
+
+```powershell
+npm run test:word:visual
+```
+
+The command writes PDFs and `manifest.json` under ignored
+`tmp/word-visual-review/rendered/` storage. It verifies that Word opened each
+fixture and produced a non-empty, paginated rendering, but leaves the manifest
+certification and every visual judgment pending. To render only named cases,
+invoke `scripts/word-com-visual-suite.ps1 -Case case-one,case-two` directly.
+
+An AI agent with Windows computer control may also open the generated fixtures
+in the installed desktop Word application, switch among All Markup, Accept All,
+and Reject All views, capture screenshots, and inspect them for visible
+regressions. This is a useful intermediate oracle because it exercises the same
+real UI a person sees rather than only `Document.Content.Text`.
+
+Run an AI visual preflight:
+
+- after a phase that changes reconstruction, formatting, list/table behavior,
+  package assembly, or revision display;
+- after every five to ten new Word fixtures;
+- for all newly introduced structure families;
+- when automated Word passes but the XML change is unusually broad; and
+- before asking a human to perform the release sample, so obvious failures are
+  found first.
+
+For the focused real-document additions, run:
+
+```powershell
+npm run test:corpus:word:visual
+```
+
+This first runs the exact Word differential, then writes 120 PDFs and a pending
+manifest under ignored `tmp/superdoc-word-visual-review/rendered/` storage: three
+views for 22 list-focused cases, 16 table-focused cases, and two page-header
+cases. The long-document set includes 6,000+ word council minutes,
+an 8,000+ word zoning resolution, and a 59,000+ word prospectus with 180 tables.
+Each invocation packages its fixtures in a process-specific directory so
+a Word process left behind by an RPC disconnect cannot lock the next run's
+inputs. The runner ignores `RPC_E_DISCONNECTED` during post-export cleanup and
+restarts Word once when a disconnect interrupts an actual render. After Word
+finishes, the command rebuilds `docs/test-comparison-dashboard.html` from that
+exact process-specific fixture directory. The `Verified cached ...` messages
+refer only to the pinned source-document downloads; edited comparison DOCX
+files are regenerated on every run.
+
+The AI should use the same selection rules and checklist as a human, inspect at
+least the changed cases plus representative legal and administrative samples,
+and save screenshots under ignored `tmp/word-manual-review/<date>/` storage.
+Its report must identify itself as **AI visual preflight**, record the Word
+version/build when available, list the exact cases and views inspected, and
+separate observed facts from uncertain visual judgments.
+
+AI visual review is advisory. It can catch missing or misplaced revisions,
+unexpected whole-paragraph markup, obvious pagination shifts, broken tables,
+lost indentation, clipped headers, and visibly misplaced anchors. It may miss
+subtle font metrics, accessibility issues, field behavior that requires domain
+knowledge, or a legally meaningful formatting distinction. An AI pass does not
+satisfy the human release sign-off, and sensitive/private documents must not be
+opened for AI review without explicit authorization.
+
+### Multimodal LLM visual inspection (real-document spot checks)
+
+Evaluating subtle visual defects—such as shifted table borders, unnatural run
+breaks, font substitution, clipping headers, or awkward revision balloons—requires
+interpreting rendered document pages visually rather than relying solely on
+string assertions or raw XML checks. A multimodal Large Language Model (MLLM)
+with vision capabilities can review rendered page images across the three
+revision views (`allMarkup`, `acceptAll`, and `rejectAll`) and detect regressions
+that are invisible to plain-text diffs.
+
+#### Why multimodal inspection is kept separate
+
+Passing high-resolution, multi-page document images through a vision-capable LLM
+is **expensive, computationally intensive, and time-consuming**:
+
+- Each document scenario produces three full-document rendering views (often 1
+  to 20+ pages per view).
+- Sending dozens of high-resolution page images consumes significant token
+  budgets and model context.
+- Latency per case is orders of magnitude higher than programmatic XML parsing
+  or COM automation.
+
+For these reasons, multimodal visual inspection **forms a separate check from the
+rest of the test suite**. It is never executed on every commit, local test run, or
+full batch pipeline.
+
+#### Sampling strategy: Random real-document spot checks
+
+Instead of exhaustive or continuous execution, multimodal visual inspection is
+conducted as a **random spot check of real documents here and there only**:
+
+1. **Focus on authentic real documents:** Spot checks prioritize the
+   [SuperDoc real-document corpus](#superdoc-real-document-word-tests) rather than
+   simple synthetic fixtures. Real documents contain organic complexities—such
+   as multi-column headers, nested bullet styles, non-uniform table borders, and
+   mixed-font legal numbering—where visual layout errors are most likely to hide.
+2. **Small random sampling:** A typical visual spot-check run selects a random
+   sample of **2 to 5 real document scenarios** (for example, one administrative
+   board agenda, one municipal minutes multi-table document, and one complex
+   zoning ordinance).
+3. **Execution cadence:** Spot checks are run on-demand:
+   - periodically during active engine refactoring;
+   - when introducing major changes to run splitting, table reconciliation, or
+     list reconstruction; or
+   - as an advisory audit prior to a release cycle.
+
+#### Multimodal inspection workflow
+
+When performing a multimodal visual spot check:
+
+1. **Render target pages to images:** Render the selected scenario in Word to
+   PDFs using `scripts/word-com-corpus-visual-suite.ps1 -Case <scenario-name>`,
+   then convert the relevant pages (or contact sheets) to PNG images using the
+   visual inspection helper:
+   ```powershell
+   node scripts/inspect-visual-evidence.mjs --contact-sheets
+   ```
+2. **Submit to the multimodal model:** Provide the vision model with the side-by-side
+   page renders of `allMarkup`, `acceptAll`, and `rejectAll` along with the target
+   diff and context.
+3. **Targeted visual checklist:** Prompt the model to evaluate specific layout risks:
+   - **Table cell integrity:** Did column widths shift? Are table borders intact?
+     Did multi-line cell text collapse or overlap?
+   - **Typography & Font metrics:** Did any run revert to default font size (e.g.
+     dropping from 14pt Georgia to 12pt Normal)? Did bold, italic, or underline
+     bleed into neighboring text?
+   - **List alignment:** Are bullet indents consistent with existing items? Are
+     there ghost markers or blank list rows?
+   - **Page apparatus:** Are headers, footers, and page numbers in their expected
+     margins without clipping or wrapping anomalies?
+4. **Triaging findings:** If the multimodal model flags a visual abnormality,
+   treat it as an advisory signal:
+   - Verify the defect manually in Microsoft Word.
+   - Trace the visual defect to its underlying OOXML cause (per the
+     [visual failure diagnosis guidelines](#diagnose-visual-failures-in-the-generated-ooxml-first)).
+   - Add a minimal semantic regression test in
+     `tests/visual_failure_regression_tests.mjs` to ensure the issue is permanently
+     prevented in the automated suite (`npm test`).
+
+## SuperDoc real-document Word tests
+
+The corpus lane references selected documents from SuperDoc's
+[docx-corpus](https://docxcorp.us/) under ODC-By 1.0. Source documents are never
+committed. `tests/corpus/superdoc-english-legal-administrative.json` pins each
+reviewed source and observed SHA-256; `tests/corpus/superdoc-word-scenarios.json`
+defines named deterministic scenarios and records the structural coverage they
+add. A source may support multiple scenarios when each one adds a distinct
+behavioral claim.
+
+To add a corpus case:
+
+1. Select an English legal or administrative document that adds a structure or
+   task not already represented. Review its content and record why it is
+   suitable.
+2. Add an explicit pinned reference and observed hash to the manifest. Do not
+   use a floating or bulk corpus download.
+3. Fetch only that reference with
+   `npm run corpus:fetch:superdoc -- --id <pinned-id>`.
+4. Inspect the document in Word and choose a target that occurs exactly once in
+   Word's source text.
+5. Add the deterministic operation, shape, coverage labels, and review note to
+   `superdoc-word-scenarios.json`. Use `key` plus `sourceId` when adding another
+   scenario for an already pinned source. Use `operations` for a multi-change
+   atomic batch, or `part: "word/header<N>.xml"` for a page-header revision.
+6. Run `npm test` for manifest/catalogue checks and `npm run test:corpus:word`
+   for package hashing plus the Word Accept All/Reject All differential.
+
+The corpus packager starts from the original `.docx`, replaces only the declared
+revision part (`word/document.xml` by default, or a named header part), and
+verifies every untouched ZIP part byte-for-byte before Word opens the result.
+The Word oracle derives multi-change expectations by applying each independently
+declared replacement to Word's source text and reads header-story text separately
+## Release validation and independent oracles
+
+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 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.
+
+### Pre-release automated check sequence
+
+```bash
+npm test              # includes tests/roundtrip_fuzz_tests.mjs (seeded, deterministic)
+npm run test:isolation
+npm run check:types
+npm run lint
+```
+
+The fuzz harness generates random paragraph structures and edits, asserting 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.
+
+### Reject-roundtrip matrix
+
+`tests/reject_roundtrip_matrix_tests.mjs` (generators in
+`tests/helpers/operation-generators.mjs`, fixtures in
+`tests/helpers/reject-roundtrip-fixtures.mjs`) applies seeded, generated
+operations (word/sentence/paragraph/range replace, insert-after, delete,
+`replacements`, format, paragraph-format, plain-to-list, last-paragraph) to the
+nested-lists fixture and synthetic documents (hyperlinks, breaks/tabs, simple
+fields, tables, multi-author revisions, empty list items). Each case runs
+through both `applyOperationsToDocumentXml` and `openDocx` with default options.
+A `REVISION_FIDELITY_VIOLATION` refusal, a rejected view that differs from the
+source, a missing intended accepted text, or bare/packaged divergence fails the
+run; other refusals are counted as skipped. The default run (fixed seed, 150
+cases, about 3 s) is part of `npm test`. Extended lane and replay:
+
+```bash
+FUZZ_SEED=<seed> MATRIX_ITERATIONS=<n> node tests/reject_roundtrip_matrix_tests.mjs
+```
+
+`MATRIX_VERBOSE=1` prints each skipped refusal; `MATRIX_MAX_REPORTED=<n>` raises
+the failure print limit. Known unfixable cases go in
+`tests/fixtures/reject-roundtrip-allowlist.json` (`{"entries":[{"fixture","kind","path","reason"}]}`);
+the file does not exist while the allowlist is empty.
+
+The nightly `matrix-extended` job in `.github/workflows/validation.yml` runs 1000 cases with a date-derived `FUZZ_SEED`;
+a failure prints the seed, fixture, kind, operation and verifier violations. `tests/list_parser_diagnostics_tests.mjs` asserts that the
+list conversion paths emit no `console.warn`/`console.error` parser diagnostics under the pure-JS fallback and the explicit xmldom provider.
+
+### Word revision semantics matrix
+
+`tests/fixtures/word-revision-semantics/` holds small packages (`cases.json`
+lists them) covering each paragraph-mark revision shape, and
+`expectations.json`, what desktop Word 16 produced on Reject All and Accept All
+for each. `tests/word_revision_semantics_tests.mjs` checks the projection and
+the library's reject/accept against those recorded results and needs no Word.
+`KNOWN_DIVERGENCES` in that test lists current differences from Word; the suite
+fails when a listed divergence disappears or an unlisted one appears.
+
+Regenerate the packages and re-record expectations after changing the case list
+or when Word's behavior may have changed (requires desktop Word; use `pwsh`,
+PowerShell 7, because Windows PowerShell 5.1 hangs in `SaveAs2` over COM here):
+
+```bash
+node scripts/generate-word-revision-semantics-matrix.mjs
+pwsh -NoProfile -ExecutionPolicy Bypass -File scripts/word-revision-semantics-matrix.ps1
+```
+
+Review the `expectations.json` diff before committing it.
+
+### Revision fidelity verification in tests
+
+Every tracked operation is verified after it is applied (default `enforce`).
+Diagnostic lanes may override the default without code changes by setting
+`DOCX_REDLINE_REVISION_FIDELITY=warn` (apply and report) or `off`. An explicit
+`verifyRevisionFidelity` option or CLI `--revision-fidelity` flag wins over the
+environment variable. Use it only to investigate a refusal; the reject
+round-trip matrix and `tests/revision_fidelity_verifier_tests.mjs` run with the
+default.
+
+### Runtime guardrail
+
+`validateRedlineOoxml(oxml)` (exported from `index.js`) runs 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.
+
+### 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
+```
+
+Verifies that a second independent OOXML consumer parses and converts 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 baselines
+
+```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.
+
+Historical reference snapshots:
+
+- **Initial Phase 7 baseline (2026-08-29)**:
+  | Metric | Coverage |
+  |---|---:|
+  | Lines / statements | 79.57% |
+  | Functions | 80.07% |
+  | Branches | 69.22% |
+
+- **Post-Phase-5 snapshot (2026-08-30)**:
+  79.96% lines/statements, 80.95% functions, and 69.52% branches.
+
+- **Post-Phase-5 snapshot (2026-09-04)**:
+  89.81% statements/lines, 93.04% functions, and 77.34% branches repo-wide.
+  The Node surface reports 99.61% statements/lines; `document-inspection.js`
+  reports 97.64% statements/lines and 100% functions; `paragraph-text.js` reports
+  100% statements/lines/functions.
+
+Preserve snapshots so progress is visible over time rather than presenting
+coverage as a single pass/fail quality score.
+
+## Choosing where a new test belongs
+
+- A fixed bug always gets an automated regression.
+- A broad engine rule also gets deterministic fuzz coverage.
+- A claim about what Word renders or accepts gets a synthetic Word case.
+- A claim involving package complexity or realistic authoring structures gets
+  a reviewed corpus case.
+- A structural XML rule should be checked by runtime validation and, where
+  practical, the ECMA-376 XSD lane.
+
+Keep expectations independent of the code under test. In particular, never use
+this library's Accept/Reject helpers to calculate the expected result for the
+Word differential.