@ansonlai/docx-redline-js 0.8.3 → 0.8.4

package/CHANGELOG.md

@@ -1,586 +1,627 @@
-# Changelog
-
-## 0.8.3
-
-### Fixed
-
-- **Reject All no longer leaves an empty paragraph after an inserted paragraph:** `modified: "<original>\n<new>"` on a plain
-  paragraph did not track the new paragraph's mark as inserted. It now does.
-- **Reject All no longer merges source paragraphs after a list range replacement:** replacing a multi-paragraph list range
-  (`target` + `targetEnd`) collapsed the sources into one deleted paragraph, so Reject All gave results such as
-  `Bullet Root ABullet Insertion Anchor`, `AlphaGamma` for an empty middle paragraph, and lost both paragraphs of an
-  all-empty range. Each source paragraph, empty ones included, now keeps its own tracked-deleted paragraph. Confirmed in Word.
-- **Inspection no longer reports historical paragraph properties as current:** `list`, `styleId` and `headingLevel` (and list
-  targeting) could read `numPr`, `pStyle` or `outlineLvl` stored under `w:pPrChange`. Only the paragraph's direct `w:pPr`
-  is read now.
-- **`openDocx` list range replacement no longer renumbers or re-points lists:** deleted source paragraphs were remapped to a
-  new generic `numId` (Reject All restored them with the wrong list type), new items started a separate list (untouched
-  following items restarted at 1), and unused numbering definitions were added. Deleted source paragraphs now keep their
-  `numPr`, and a same-kind replacement reuses the source `numId`, leaving `numbering.xml` unchanged. Reuse applies when the
-  range uses one `numId` and the generated level formats match; format-changing edits still allocate new definitions, and
-  definitions created earlier in the same batch are not reused. Confirmed in Word.
-- **Explicit list start values are applied:** generated list fragments without `xmlns:w` failed to parse in
-  `orchestration/list-structural-fallback.js`, so `7. Header` lost its `startOverride` and xmldom logged parse warnings.
-
-### Tests
-
-- New `tests/list_reject_fidelity_tests.mjs` and `tests/facade_list_numbering_tests.mjs`, with the Word-authored fixture
-  `tests/fixtures/agentic-lists/nested-lists-source.docx`; extended inspection and list structural fallback suites.
-
-### Known limitations
-
-- Plain paragraph to list conversion and list format changes are not yet supported canonically; see
-  `docs/plans/2026-09-30-canonical-list-operations.md`.
-- `1. Header` to `1. Header` on a bare `document.xml` (not a packaged `.docx`) can fail with `RECEIPT_RECONCILIATION_FAILED`.
-
-## 0.8.2
-
-### Fixed
-
-- **Replacement next to a hyperlink no longer pulls adjacent plain text into the link** ([#3](https://github.com/AnsonLai/docx-redline-js/issues/3)):
-  replacing `example.org` with `example.net` (localized `replacements` or full `modified`) in a hyperlink followed by a
-  plain `.` run produced a link showing `example.net.` after Accept All. The reconstruction-mode word diff treated
-  `example.org.` as one token spanning the hyperlink edge. Where a replacement's shared prefix or suffix reaches a wrapper
-  boundary inside the deleted text, it is now kept unchanged.
-- **Reject All no longer reorders text around a manual line break** ([#4](https://github.com/AnsonLai/docx-redline-js/issues/4)):
-  replacing `tabbed` with `aligned` in `<tab>tabbed<w:br/>Line with ` rejected to `<tab>tabbedLine<break> with `, moving
-  deleted text across the break. Break and note-reference placeholders are now standalone word-diff tokens (new internal
-  `atomicChars` option), and change groups are split at references present on both sides. Covered by `tests/reconstruction_boundary_fidelity_tests.mjs`.
-
-## 0.8.1
-
-### Added
-
-- **Header and footer editing:** add `part` to an operation (a selector `{ kind, type?, section? }` or a part path) to edit a
-  header or footer; `inspect().headersFooters` lists the parts with their text, the sections they apply to (including
-  inherited ones) and whether they contain fields. Body edits are unchanged and headers/footers are opt-in. Fields such as
-  PAGE are atomic (`FIELD_EDIT_REFUSED`), comments are refused (`COMMENT_IN_HEADER_FOOTER`), bad selectors fail closed
-  (`PART_NOT_FOUND`, `PART_AMBIGUOUS`), atomic batches roll back across body and parts, revision ids stay unique across the
-  package, receipts name the part, `accept`/`reject` also resolve revisions inside headers and footers, and
-  `validateDocxPackage` checks header/footer references, relationships and content types.
-- **Resolve and reopen comment threads:** `doc.resolveComment(id, { resolved })` and the batch operation
-  `{ "type": "comment_resolve", "commentId": "0", "resolved": true }`, so the CLI can resolve through `apply --operations`.
-  Word resolves whole threads, so the root and every reply change together, whichever id is given. Only
-  `word/commentsExtended.xml` changes; `document.xml` stays byte-identical. Unknown ids fail with `COMMENT_NOT_FOUND`
-  (also in `preflight`).
-- **Delete comments by id:** `doc.deleteComments({ ids })` and `docx-redline delete-comments --comment-id 3,4`. Deleting a
-  thread root also deletes its replies; unknown ids fail closed with `COMMENT_NOT_FOUND`.
-- CLI capabilities `comment-resolve-operation-v1`, `delete-comments-by-id-v1` and `header-footer-parts-v1` (additive; the
-  contract version is unchanged).
-- `services/package-parts.js`, a registry of package part paths, content types and relationship types checked against
-  Word-saved fixtures (`tests/fixtures/word-authored/`), and `npm run test:word:package`, which opens generated outputs in
-  real Word with repair disabled and checks comment counts, thread parents, resolved state and header/footer revisions
-  through Word's object model.
-
-### Fixed
-
-- **Word "unreadable content" prompt on commented documents:** `word/commentsExtended.xml` was relabeled
-  `application/vnd.ms-word.commentsExtended+xml` on every save of any document that already had comments.
-  Word expects `application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtended+xml` and
-  offered to repair the file. The constant is corrected, an edit that does not change comment threading no
-  longer rewrites the extended part or its content type/relationship, and files already damaged by earlier
-  versions are repaired on the next save (`repairKnownContentTypes`, also exported). `validateDocxPackage`
-  now rejects the wrong type instead of accepting it. `tests/package_content_type_contract_tests.mjs` checks this
-  against a Word-authored content-type table on every OS.
-- **Comment threads keyed on the last paragraph:** Word joins `comments.xml` to `commentsExtended.xml` and
-  `commentsIds.xml` through the `w14:paraId` of a comment's LAST paragraph. Inspection, package validation,
-  replies and delete-cascade used the first, so Word's own multi-paragraph threaded documents failed
-  validation and replies to them attached to the wrong key.
-- **Edits no longer drop comment anchors:** a mid-paragraph edit of a commented paragraph dropped the trailing
-  `commentRangeEnd` and `commentReference` (markers at the very end of the paragraph text were only emitted when the
-  last diff part was an insert), leaving the comment unanchored and failing package validation. Found by
-  opening our output in real Word; covered by `tests/comment_marker_preservation_tests.mjs`.
-- **Replies are now visible in Word:** `comment_reply` only wrote `comments.xml`/`commentsExtended.xml`, and Word
-  does not show a reply that has no body markers. Replies now get their own `commentRangeStart`/`commentRangeEnd`/
-  `commentReference` next to the thread's, laid out like Word writes them. A reply to a reply joins the root thread.
-  A parent with no body anchor fails with `PARENT_ANCHOR_NOT_FOUND`.
-- **Replies to a resolved thread are resolved too**, as Word writes them (`reply-to-resolved.docx` fixture). They were
-  written open, leaving a thread that was half resolved.
-- `commentsIds.xml` and `commentsExtensible.xml` are kept consistent with `comments.xml` on add/delete when present.
-- `deleteComments` and `resolveRevisions` report `artifactsChanged` from a real diff of the package (they listed a fixed
-  set of parts and missed `commentsIds.xml`, `commentsExtensible.xml` and `[Content_Types].xml`).
-
-## 0.8.0
-
-### Universal Document Facade & Zero-Node Architecture
-
-- **Universal `DocxDocument` & `openDocx`:** Implemented complete-DOCX lifecycle operations
-  (`openDocx`, `doc.inspect()`, `doc.applyOperations()`, `doc.resolveRevisions()`, `doc.deleteComments()`,
-  `doc.toUint8Array()`, `doc.getRevisionToken()`) on standard `Uint8Array` in `document/docx-document.js`,
-  re-exported directly from `index.js`. Enables complete-document redline workflows in any JavaScript
-  runtime without Node.js dependencies.
-- **Pure-JS ZIP container (`fflate`):** Replaced `node:zlib` with lightweight, zero-dependency `fflate`
-  in `document/zip-archive.js`, providing cross-runtime raw DEFLATE / INFLATE compression and decompression
-  with full OOXML archive compatibility.
-- **Pure-JS FIPS 180-4 SHA-256:** Created zero-dependency, synchronous SHA-256 implementation in
-  `core/sha256.js`, removing `node:crypto` from package revision token calculations while retaining
-  exact deterministic hash parity with standard NIST vectors.
-- **Transparent XML DOM fallback:** Added `resolveDomParserConstructor()` and
-  `resolveXmlSerializerConstructor()` in `adapters/xml-adapter.js`, automatically utilizing native
-  `globalThis.DOMParser`/`globalThis.XMLSerializer` when present and falling back transparently to
-  `@xmldom/xmldom` in headless, server, edge, and sandbox environments without requiring manual provider setup.
-- **Zero-dependency sandbox bundles:** Configured `scripts/build.mjs` with `esbuild` (`platform: 'neutral'`)
-  to produce single-file, zero-dependency standalone bundles in both ESM (`dist/docx-redline.bundle.js`)
-  and CommonJS (`dist/docx-redline.bundle.cjs`), exported as `@ansonlai/docx-redline-js/bundle` for direct
-  use in workflow engines (e.g., n8n Code nodes), Cloudflare Workers, AWS Lambda, Deno, and QuickJS sandboxes.
-- **Strict runtime boundary enforcement:** Removed `node:zlib` and `node:crypto` from allowed external
-  imports in `tests/no_word_api_index_check.mjs`. Automated sandbox isolation tests
-  (`tests/sandbox_bundle_isolation_tests.mjs`) verify zero Node built-in imports and full document
-  reconciliation in restricted VM contexts without `process`, `Buffer`, or `require`.
-- **Backward compatibility:** Preserved full API and `Buffer` compatibility for `@ansonlai/docx-redline-js/node`
-  consumers and `doc.toBuffer()`.
-
-## 0.7.2
-
-### Agent Surface Simplification
-
-- **Extraction-first golden path:** Re-established the single deterministic two-turn
-  "extract-then-apply" sequence as the default agent workflow across `AGENTS.md`,
-  `docs/AGENT_FAST_START.md`, and `docs/SKILL_AUTHORING.md`. Eliminates the
-  upfront "choice tax" and model deliberation overhead.
-- **Localized replacements after inspection:** Decoupled localized patching from
-  speculation. Agents inspect the target paragraph first, then supply compact
-  `replacements` instructions, achieving 60.6%–90.8% payload reductions without
-  speculative ambiguity risk.
-- **Computed success gate:** Consolidated standard success verification onto
-  `completion: true` and non-null `outputPath`, removing multi-field verification
-  checklists from primary prompts while retaining full `change` audit evidence.
-- **Advanced features relocated:** Speculative 1-turn apply, directional context
-  windows (`--context-range`), and anchor diagnostics are relocated to
-  `docs/AGENT_KNOWLEDGE_BASE.md` and CLI help as opt-in harness policies.
-- **Observed-state restoration:** Restructured restoration as a clean request-
-  or hint-driven branch (`--view rejected` or `selection.hint`) rather than an
-  upfront classification decision.
-- **Empirical surface evaluation:** Added synthetic replay benchmark
-  (`npm run benchmark:agent-surface`) and validation report documenting 100%
-  first-attempt task correctness and payload savings across three workflow policies.
-
-## 0.7.1
-
-### Reliability and Discovery Refinements
-
-- Localized replacement matching now tries exact case-sensitive text first,
-  then a narrow ASCII-space/non-breaking-space equivalent match. Ambiguous
-  equivalent matches still fail closed, and unchanged boundary NBSPs are
-  retained to avoid incidental whitespace redlines.
-- Added a narrow single-paragraph restore shortcut. A restore with a strong
-  rejected-view target may omit `modified` for verbatim restoration or provide
-  exact `replacements`; the CLI exposes the same path through `apply --restore
-  --target-id ID`. Ranges, captures, weak targets, and inferred companion
-  content remain excluded.
-- Fixed rejected-view restore receipts so `resolvedTarget` text, fingerprint,
-  revision view, and match diagnostics describe the view actually used to
-  resolve the target.
-- Fixed alternate-view search hints to honor `--revised`, `--table`, and
-  `--body`, and retained compact revision authors plus `deleted`/`inserted` cues
-  in `extract` output so empty revision-view paragraphs are self-explanatory.
-
-## 0.7.0
-
-### Agent Performance and Localized Editing
-
-- **Localized exact replacements:** `redline`/`replace` operations may provide
-  `replacements: [{ find, replace, occurrence? }]` instead of a complete
-  `modified` paragraph. The compiler resolves the accepted-view source once,
-  applies non-overlapping exact replacements simultaneously, synthesizes the
-  canonical desired paragraph, and delegates to the unchanged OOXML engine.
-- **One-turn speculative apply:** `docx-redline apply --find ... --replace ...`
-  can resolve a globally unique source literal without preliminary extraction.
-  `--search` plus signed `--context-range START:END` scopes visible headings and
-  nearby content; `--around N` is symmetric shorthand. Longer, distinctive
-  anchors are recommended because generic or repeated phrases widen the unioned
-  scope and may cost an ambiguity-recovery turn.
-- **Fail-closed selection:** Missing anchors and patch sources, multiple eligible
-  paragraphs, ambiguous occurrences, overlaps, conflicts, and unsupported
-  localized shapes refuse mutation. A failed speculative command never writes
-  or truncates its output path.
-- **Verified change evidence:** Localized operation results include a compact
-  `change` object with target location, contextual anchor/range, exact
-  replacement entries, bounded before/after excerpts, commit disposition, and
-  post-mutation accepted-view verification. Atomic rollback marks the evidence
-  non-committed and `rolled_back`.
-- **CLI contract version 8:** Adds `localized-replacements-v1`,
-  `speculative-search-apply-v1`, and `localized-change-summary-v1`. Skills and
-  harnesses should pin version 0.7.0 and negotiate only the capabilities used.
-- **Measured workflow reduction:** The checked benchmark records 50% fewer tool
-  turns and a 64.77%–78.98% smaller deterministic request-token proxy across
-  three literal-edit cases. Median native engine/I/O time remained effectively
-  neutral; provider reasoning and network latency were not estimated.
-
-### Compatibility
-
-- Existing `modified` operations, strong targets, operations files/stdin,
-  tracked-change generation, package validation, rollback, comments,
-  Accept/Reject, and revision policies remain supported.
-- Localized replacement fields and successful `change` evidence are additive.
-  Wrappers that adopt them must require CLI contract 8; integrations using only
-  earlier capabilities can continue using their existing operation shapes.
-- The implementation remains OOXML-only and adds no runtime dependency or Word,
-  Office automation, COM, or proprietary document API requirement.
-
-## 0.6.0–0.6.2
-
-### Safety Fixes
-
-- **Foreign deleted-paragraph resurrection guard**: Refuses non-empty same-paragraph edits when another author owns the paragraph-mark deletion and all existing paragraph content is deleted. The operation now returns `FOREIGN_PARAGRAPH_MARK_DELETION` with the owning author instead of emitting lifecycle-unsafe OOXML; atomic document operations roll back byte-for-byte. `validateRedlineOoxml` reports already-authored instances as warnings.
-- **Source-truth whitespace replacement alignment (WP09a)**: Strict target resolution may equate ordinary spaces with NBSPs, but mutation offsets now always come from the resolved paragraph's exact accepted view. Space-equivalent word replacement hunks are refined to character-local edits, and multiple plain-text edits are applied right-to-left against refreshed live spans. This tracks NBSP-to-space substitutions exactly while preserving unchanged hyperlinks and prevents earlier run splits from invalidating later anchors.
-- **Exact mismatch diagnostics**: `PATCH_ROUNDTRIP_MISMATCH` now includes the expected and actual code points at the first mismatch. Document-operation results also report bounded `targetTextMatch` diagnostics when target selection used equivalent whitespace.
-- **Baseline-delta validation (WP09c)**: Restoration, operation, and package validation now compare issue multisets against the source. Unchanged legacy defects remain visible without blocking safe work, while any added occurrence or mutation-envelope error fails closed with `GENERATED_OOXML_INVALID` before an operation is reported as applied.
-- **Revision identity sanitation (WP09d)**: New paragraph/list builders inherit effective `pPr`/`rPr` formatting without cloning historical revision descendants. Operation-level whole-document validation catches duplicate revision IDs and rolls back the operation savepoint before committing its receipt.
-- **View-consistent restore targeting**: `restore` targets now default to the rejected view, where a wholly deleted paragraph's source text exists. Rejected-view inspection now computes fingerprints from rejected-view text and reports the view beside each paragraph. Explicit cross-view text or fingerprint mistakes retain strict refusal while returning an actionable view hint.
-
-### New Features
-
-- **Self-describing and bounded agent discovery (WP-00–WP-02)**: CLI contract version 6 adds command-specific JSON help, canonical redline/comment/restore examples, case-insensitive contextual search with `--around`/`--context`/`-C`, direct-hit pagination through `--limit` and `--after`, and deliberate `--all` opt-out. Unscoped inspection is capped at 20 direct records and a 48 KiB soft budget without truncating any returned `exactText`; extraction now distinguishes matches from context and prioritizes human-facing provision/heading references over machine paragraph ordinals.
-- **Composable agent safety and compact output (WP-03–WP-04)**: CLI contract version 7 replaces the atomic-coupled agent profile capability with `agent-safety-profile-v2`. `--profile agent` now enforces complete-success exits while preserving progressive execution and the ordinary revision policy; `--atomic` and `--existing-revisions` compose explicitly. Compact CLI JSON keeps receipts only in the authoritative top-level array, omits exact-match diagnostics, summarizes successful equivalent-whitespace matches, and supports one-line `--compact` output without changing Node or standalone-runner results.
-- **Packaged skill-authoring contract (WP-05)**: `docs/SKILL_AUTHORING.md` separates automation invariants from transaction/revision policy, file-versus-stdin transport, reviewer preferences, recovery-envelope behavior, and human-facing presentation. It requires contract/capability negotiation, focused contextual extraction, and library delegation while retaining the visible `AI Redliner` fallback without a new author guard.
-- **Batch-start source binding (WP-04)**: Strong document-operation targets are compiled once against the immutable source DOM and carried through structural index/fingerprint drift with rollback-aware session identities. Independent edits no longer need manual bottom-up sorting; same-source writes, incompatible revision/format combinations, and unsafe capture fan-out fail before mutation with causal conflict codes. Unique references to paragraph text created elsewhere in the same batch become explicit internal capture dependencies.
-- **Machine-actionable recovery (WP-05)**: Operation, package-facade, example-session, and compact CLI failures now carry recovery envelope version 1 with stable stage/category/action metadata, bounded corrective context, and authorization flags. Failed and partial mutation results include an explicit original-vs-output retry plan and operation indexes. `apply --require-complete` exits with code 3 for partial work while preserving legacy behavior without the flag.
-- **Compact shell-agent protocol (WP-06)**: CLI contract version 5 adds `operations-stdin` and `agent-profile-v1`. `--operations -` accepts UTF-8 operation arrays/envelopes without a temporary operations file, while explicit `--profile agent` combines atomic rollback and complete-success exit behavior and reports its effective settings. `AGENTS.md` is now a 527-word routing card, and the 349-word `docs/AGENT_FAST_START.md` carries the ordinary edit contract. Ambient project configuration was deliberately deferred because it would save only the profile flag while adding hidden state.
-- **Agent rollout audit (WP-07)**: The observational benchmark now compares canonical Node, legacy file-based CLI, compact stdin/profile CLI, and the development session example while verifying accepted/rejected text, comment preservation, independent batch permutations, recovery behavior, and cross-author attribution. The checked run records 82.75% fewer ordinary instruction words, one fewer shell tool turn (33.33%), and 82.22–89.96% smaller localized session requests than canonical Node envelopes without claiming unmeasured provider/model latency.
-- **Explicit paragraph restoration (`type: 'restore'`)**: Restores or counterproposes another reviewer's pending whole-paragraph deletion as a separately tracked sibling paragraph. The source deletion remains untouched; the restored paragraph receives its own inserted paragraph mark, content insertion, sanitized paragraph properties, and fresh `w14:paraId`. Single paragraphs and contiguous ranges are supported, with full Accept/Reject lifecycle verification and structured refusals at unsafe table-row, move, section-break, and terminal-paragraph boundaries.
-- **Compact mutation CLI contract (WP09b)**: CLI contract version 3 removes `documentXml`, OOXML/package artifacts, full inspection data, and full validation issue arrays from normal `apply`, `accept`, `reject`, and `delete-comments` stdout. Mutation responses retain actionable errors, per-operation receipts, output durability fields, code/count validation summaries, and a derived `completion` flag that cannot report success for failed, partial, or unwritten work.
-- **Word-native deleted-section editing (WP09e)**: An explicit rejected-view `insert` operation can split a foreign deletion at an exact anchor-relative offset into sibling `del(A) / ins(B) / del(A)` carriers. Contiguous paragraph restorations now follow their untouched deleted source block, matching Microsoft Word's ordering. Ambiguous anchors and unsupported structural split boundaries remain fail-closed.
-
-## 0.5.1
-
-### Highlights & New Features
-
-- **Cross-Author Revision Slicing (`existingRevisions: 'slice-cross-author'`)**: Adds native support for editing text inside another reviewer's pending tracked insertion without erasing their attribution or requiring prior acceptance.
-  - **Word-Native Insertion Slicing**: When inserting text inside another author's pending `<w:ins>`, the engine splits the outer carrier into sibling `<w:ins>` elements at the paragraph level (`[ins(A), ins(B), ins(A)]`), ensuring strict ECMA-376 schema compliance without illegal `ins/ins` nesting.
-  - **Word-Native Deletion Slicing**: When deleting text inside another author's pending `<w:ins>`, the engine nests `<w:del>` directly inside `<w:ins>` per ECMA-376 Part 1 `CT_RunTrackChange` Section 17.13.5.21 and Microsoft Word Desktop 365 native behavior.
-  - **Boundary & Straddle Deletions**: Deletions straddling baseline text and pending insertions cleanly partition into separate top-level and nested `<w:del>` containers while sharing unified event/author attribution.
-  - **Multi-Author Stacked Revisions**: Multiple reviewers can independently delete or insert content within the same carrier insertion without cross-author interference.
-  - **Cascading & Coalescing Lifecycles**: Full round-trip lifecycle parity with Microsoft Word Desktop:
-    - Rejecting Author A cleanly discards Author A's insertion and any dependent nested deletions by Author B.
-    - Accepting Author A unwraps the insertion into baseline text while leaving Author B's deletions pending against the baseline.
-    - Rejecting Author B restores Author B's deleted text within Author A's insertion, and coalesces adjacent split `<w:ins>` fragments back into a single continuous carrier.
-  - **CLI & Facade Integration**: Fully exposed via the `docx-redline` CLI (`--existing-revisions slice-cross-author`), Node facade (`openDocx`), and batch operation runner.
-
-### Non-breaking Changes & Improvements
-
-- **Validation Update (`validateRedlineOoxml`)**: Refined `NESTED_REVISION` checks to permit direct `<w:ins><w:del>...</w:del></w:ins>` nesting (standard ECMA-376 and Word Desktop behavior), while continuing to strictly reject `ins/ins`, `del/del`, and `del/ins` nesting.
-- **Slicing Round-Trip Guard**: Cross-author surgical edits now preserve whitespace-only insertions (including ordinary-space replacements for NBSP characters beside hyperlinks) and verify the exact accepted-view text before reporting success. A mismatch fails closed with `PATCH_ROUNDTRIP_MISMATCH` and returns the original OOXML unchanged.
-- **Hyperlink-Adjacent Replacement Anchoring**: Paired replacements immediately before or after a hyperlink now retain a stable insertion point after the deletion run is split, preventing qualifiers from being relocated past the hyperlink or following formatted runs.
-- **Multiple Same-Run Insertions**: Insertion-only slicing operations with multiple edit points now apply from right to left against a refreshed live span index, preventing an earlier run split from relocating later insertions.
-- **Insertion Stress Hardening**: Slicing now detects edge whitespace changes exactly, uses a character-local insertion-only diff when the original text is an exact subsequence of the modified text, and coalesces new text into an existing same-author carrier when foreign revisions are also present. This prevents repeated phrases from relocating insertions and prevents invalid `w:ins/w:ins` nesting in mixed-author paragraphs.
-- **Preflight Inspection**: `preflightOperations` now inspects and validates `slice-cross-author` batches, reporting pending foreign-author carrier targets as `ready` instead of `EXISTING_REVISIONS`.
-- **Test Suite Expansion**: Added 7 new test suites covering 36 Word Desktop COM golden fixtures, carrier splitting invariants, the SYN-01..12d synthetic test matrix, PKG-01..06 strict package differential replay, the repeated-text/hyperlink whitespace regression, 76 deterministic insertion stress scenarios, and 12 replacement-anchor lifecycle scenarios (expanding the suite from 88 to 95 passing suites).
-
-## 0.5.0
-
-### ⚠️ Breaking changes
-
-The following changes can require caller or contributor updates. No public
-export or valid existing function signature was removed.
-
-#### Runtime and result-contract changes
-
-- **Canonical paragraph text:** `getParagraphText(...)` now returns the
-  accepted/current view instead of the earlier simplified `w:t`/`w:tab`
-  concatenation. It excludes deleted and `w:moveFrom` content and includes
-  structural breaks, soft hyphens, and non-breaking hyphens.
-  **Migration:** regenerate compared/cached text with the upgraded library. Use
-  `extractCanonicalParagraphText(...)` when accepted/rejected-view semantics
-  are intended; integrations that require the former raw traversal must retain
-  their own legacy extractor before upgrading.
-- **Paragraph fingerprints:** fingerprints now incorporate canonical paragraph
-  text. Stored fingerprints can become stale for paragraphs containing
-  revisions, moves, breaks, soft hyphens, or non-breaking hyphens.
-  **Migration:** do not carry fingerprints across this upgrade; re-extract the
-  document and regenerate target descriptors.
-- **Invalid operations:** malformed or field-incompatible document-operation
-  objects now return a structured `INVALID_OPERATION` error at the runner
-  boundary instead of reaching later failure/no-op paths.
-  **Migration:** validate operation files against the published schema and
-  handle `status === 'error'` plus `error.code === 'INVALID_OPERATION'`.
-- **Commented paragraph deletion:** deleting a complete paragraph that contains
-  an existing comment now fails with `COMMENTED_CONTENT_DELETE` instead of
-  producing OOXML with dangling comment references.
-  **Migration:** preserve or deliberately remove/relocate the comment before
-  deleting the paragraph, and handle the structured error. Atomic callers keep
-  the original document unchanged.
-- **Comment anchor failures:** missing or ambiguous comment anchors now return
-  `ANCHOR_NOT_FOUND` or `AMBIGUOUS_ANCHOR` and fail/roll back an atomic batch;
-  they are no longer reported as successful `no_change` operations.
-  **Migration:** treat these codes as failed operations and use a unique exact
-  anchor or stricter target descriptor before retrying.
-- **Stricter package validation:** DOCX package validation now rejects
-  unbalanced comment ranges, dangling references/usages, orphan definitions,
-  and duplicate comment-definition IDs that earlier validation could allow.
-  **Migration:** repair the comment anchors and `word/comments.xml` definitions
-  before applying or validating further changes.
-
-#### Development workflow change
-
-- **Parallel tests by default:** `npm test` now runs up to four isolated child
-  processes concurrently. This does not change the published runtime API, but
-  contributor automation that depends on test execution order or shared files
-  must be updated. **Migration:** make tests independent or set
-  `DOCX_TEST_CONCURRENCY=1` for the previous serial scheduling behavior.
-
-Strict targeting remains opt-in on existing low-level mutation APIs; it is the
-default only on the newly added Node facade and CLI.
-
-### Deprecations and future breaking changes
-
-- Replacing an existing numbering part without a merge callback now emits a
-  deprecation warning. The Node facade and CLI already merge safely by default.
-  **This remains supported in this release but will become an error in the next
-  major version.** Migrate low-level callers to
-  `mergeNumberingXmlBySchemaOrder` before that release.
-- **Permissive target resolution deprecation (`AMBIGUOUS_TARGET_HEURISTIC_USED`):**
-  Lower-level document operation runners currently default to permissive targeting.
-  In v1.0.0, application will default to `strictTargets: true`. In this release,
-  when permissive resolution encounters multiple identical candidate paragraphs and
-  heuristically chooses the first candidate, it emits an `AMBIGUOUS_TARGET_HEURISTIC_USED`
-  warning with candidate count and migration guidance.
-  **Migration:** Disambiguate operations using `paragraphId`, `index`, `occurrence`,
-  or `fingerprint` and pass `{ strictTargets: true }`.
-
-### ℹ️ Noteworthy Default & Usability Changes (Non-breaking)
-
-The following improvements update default behaviors to maximize agent speed, reduce friction, and eliminate unnecessary errors during iterative editing. These changes are **not technically breaking changes** (no public APIs or exports were removed, and all existing options remain configurable), but represent important behavioral refinements that callers should note:
-
-- **Fallback Author Default (`'AI Redliner'`):** `setDefaultAuthor`, `node/cli.js`, and `openDocx` now default to `'AI Redliner'` (configurable via the `DOCX_REDLINE_AUTHOR` environment variable or `--author`). The CLI `apply` command and core APIs no longer error with `AUTHOR_REQUIRED` when operations omit an author.
-- **Output Overwrite by Default:** Destination files provided via `--output` now overwrite by default instead of failing with `OUTPUT_EXISTS`. Callers wanting protection against accidental overwrites can pass `--no-overwrite` or `--no-clobber`. The source document remains protected and is never overwritten unless `--in-place` is explicitly passed.
-- **Replacement Event Pairing (`pairReplacements: true` by default):** Adjacent `<w:del>` and `<w:ins>` revisions now default to sharing linked revision metadata and identical timestamps so Microsoft Word groups them as a single replacement in the Reviewing Pane. Pass `pairReplacements: false` for independent revision timestamps.
-- **Structured Content Auto-Detection (`structuredContent: true` by default):** Markdown tables, headings (`#`), and lists in replacement text automatically render as native Word elements (`w:tbl`, `w:pStyle`, `w:numPr`). Single outline-numbered legal clauses (e.g. `13.2.1.1`) continue to be treated as ordinary paragraphs without spurious list conversion. Pass `structuredContent: false` to treat replacement text strictly as plain text.
-- **Progressive Batch Mode (`atomic: false` default, `atomic: true` opt-in):** Batch operations and CLI `apply` now apply edits progressively by default (`atomic: false`): valid edits commit directly, while failing edits report structured errors in `results` for faster debugging. Pass `{ atomic: true }` (or `--atomic` on the CLI) for all-or-nothing rollback when any operation fails.
-- **Clean Direct Edits (`generateRedlines: false` / `--no-redlines`):** Prominently documented that tracked redlines are not always the preferred method. Callers can pass `generateRedlines: false` (or `--no-redlines` on the CLI) for clean execution drafts, document restructuring, or minor typo fixes without tracked changes markup.
-- **Existing Revisions Policy (`existingRevisions: 'merge-same-author'` by default):** When editing a paragraph that already contains tracked changes from the same author, prior revisions by that author are merged against the pre-revision baseline (prior changes by that author are reverted and re-diffed to the new modified text), avoiding revision accumulation and nested markup. If a paragraph contains tracked changes from another reviewer, the operation fails closed with `EXISTING_REVISIONS` to protect third-party review marks. Commented revision content fails closed with `COMMENTED_CONTENT_MERGE` so comment anchors cannot be removed or orphaned. Callers can explicitly pass `'accept-all-first'` to normalize prior revisions or `'reject-input'` to refuse editing any revised paragraph.
-- **Inline One-Liner CLI Edits:** Added `--target <text>` with `--modified <text>` or `--comment <text>` on `docx-redline apply` for fast 1–2 edit workflows without creating a JSON operations file.
-
-### Added
-
-- Added **Mutation Receipts** (`receipt` on `DocumentOperationResult` and `receipts`
-  on `BatchOperationResult`). Every operation execution returns structured,
-  commit-aware telemetry capturing durable revision IDs (with kind and target part),
-  comment IDs, numbering IDs, relationship IDs, affected targets, and warnings.
-  Supports `not_attempted`, `applied`, `refused`, `no_change`, and `rolled_back`
-  dispositions.
-- Added **Commit-Aware Output Reconciliation Oracle** (`reconcileReceiptsAgainstOutput`).
-  Before completing any transaction, reported durable IDs are checked against a
-  fresh parse of the generated output OOXML parts. Any reconciliation discrepancy
-  immediately fails the transaction and triggers atomic rollback.
-- Exported receipt primitives: `ReceiptCollector`, `createEmptyReceipt`, and
-  `reconcileReceiptsAgainstOutput` along with `MutationReceipt` and
-  `MutationReceiptRevisionItem` TypeScript declarations.
-- Added **Paragraph Mark Revisions** (`w:pPrChange`, `markParagraphMarkInserted`,
-  `markParagraphMarkDeleted`) ensuring whole-paragraph deletions and insertions
-  cleanly track paragraph mark lifecycles for full Accept All / Reject All symmetry.
-- Added **Paragraph Boundary Mutation Validation** (`validateParagraphBoundaryMutation`)
-  guarding against invalid cross-paragraph boundary merges.
-
-- Added `analyzeStructuredContent(...)` and `planStructuredReplacement(...)`
-  for agent-authored attachments and schedules containing mixed headings,
-  paragraphs, lists, and tables. The planner returns typed blocks and produces
-  one atomic `structuredContent` operation only when the Markdown is valid.
-
-- Added session-scoped paragraph metadata indexing for canonical text,
-  normalized text, paragraph IDs, fingerprints, table context, and document
-  indexes, plus deterministic targeting and route-profiling benchmarks.
-- Added a shared list-marker grammar and parsed list-item vocabulary used by
-  pipeline analysis, orchestration, normalization, and list targeting.
-- Added an internal reconciliation capability matrix and opt-in route
-  instrumentation. Public reconciliation result shapes and route selection
-  policy remain unchanged.
-
-- Added `scripts/extract_text.mjs` and `scripts/apply_changes.mjs` as thin
-  compatibility entrypoints for legacy skill installations. They delegate to
-  the supported CLI, retain strict atomic validated writes, and accept legacy
-  operation files with a top-level `changes` array.
-- Added typed operations, per-operation authors, strict target descriptors,
-  deterministic preflight diagnostics, and auditable resolution metadata.
-- Added `inspectDocumentParts(...)`, a structured document inventory using the
-  same canonical text extractor as targeting and ingestion.
-- Added `@ansonlai/docx-redline-js/node`. `openDocx(...)` applies batches to
-  complete DOCX buffers transactionally and validates before commit.
-- Added the cross-platform `docx-redline` CLI with JSON `inspect`, `extract`,
-  `preflight`, `apply`, `accept`, `reject`, `delete-comments`, and `validate`
-  commands, plus a published operation-file JSON Schema.
-
-### Behavior and reliability
-
-- Explicit structured replacements now reject missing Markdown table separator
-- Generated Markdown tables repeat their header row and prevent logical data rows from splitting across pages.
-  rows, missing data rows, and inconsistent column counts with
-  `STRUCTURED_CONTENT_INVALID` instead of inserting literal pipe-delimited text.
-- Tables created inside mixed replacements are tracked once at block scope,
-  avoiding nested revisions while keeping Accept All and Reject All symmetric.
-
-- Target preflight and live mutation reuse one document-scoped paragraph index;
-  strict duplicate detection and resolution metadata retain their prior
-  semantics while avoiding repeated whole-document text traversal.
-- Revision-ID seeding now walks the DOM with child/sibling pointers instead of
-  allocating an array containing every element.
-- Single-source-paragraph list expansion uses the focused list generator
-  directly. Multi-paragraph marked-list edits deliberately retain the legacy
-  run-aware reconciliation pipeline for structural parity.
-- Fixed paragraph-to-list expansion when a manually numbered heading carries
-  `w:numId w:val="0"`. Numbering suppression is no longer reused as a generated
-  list ID, so inserted bullet and numbered items receive valid positive IDs.
-- Tracked heading-to-list replacements now keep the deleted source heading in
-  its own paragraph and track the paragraph marks of every inserted list item.
-  This prevents deleted heading text from joining the first item and preserves
-  exact Accept/Reject structure without adding a full-document sentinel
-  paragraph.
-- Inserted list items now inherit source font family, size, language, and
-  related script typography without inheriting heading-only bold, underline,
-  italic, or strike formatting unless requested by the replacement markdown.
-- Canonical-only table-cell targeting now consumes the shared paragraph-text
-  extractor, while offset- and sentinel-producing walkers remain specialized.
-  Their accepted visible projections now agree on soft hyphens as well as tabs,
-  breaks, hyperlinks, and non-breaking hyphens.
-
-- Comment preflight and application now share one anchor resolver. Exact
-  matches take priority, unique ordinary-space/NBSP differences preserve raw
-  offsets, and missing or repeated anchors return structured
-  `ANCHOR_NOT_FOUND` or `AMBIGUOUS_ANCHOR` errors.
-- Full-document operation batches now share one live DOM and revision-ID
-  allocator, reducing complete-document parsing and serialization from once per
-  operation to once per changed batch. Scoped reconciliation engines and their
-  targeting decisions are unchanged.
-- Each live-session operation uses a DOM and allocator savepoint. Errors and
-  reported no-ops restore the savepoint; atomic failures and all-no-op batches
-  still return the exact original XML without serializing it.
-- Decomposed the standalone document-operation runner into a stable 13-line
-  compatibility facade plus focused session, applier, batch-orchestrator,
-  heuristic, and OOXML-mutation modules. Runtime exports and declarations are
-  unchanged, and operation internals now use leaf imports instead of importing
-  the root entry point.
-- Package comment IDs are seeded from existing anchors and definitions, and
-  the Node facade merges numbering without discarding prior definitions.
-- Canonical paragraph text consistently handles revisions, moves, tabs,
-  breaks, soft hyphens, and non-breaking hyphens; see the breaking-change note
-  above for `getParagraphText(...)` and fingerprint compatibility.
-- Structured inspection now explicitly supports the `current` view as the
-  accepted/current document view and resolves comment ranges spanning multiple
-  paragraphs as one exact anchor string.
-- Transactional no-op results preserve the original DOCX bytes exactly,
-  including when the same facade instance has already committed an edit.
-
-### Testing and development
-
-- Added focused and semantic visual-failure regressions for suppressed
-  numbering, paragraph separation, paragraph-mark revisions, selective
-  typography inheritance, and exact accepted/rejected paragraph sequences,
-  plus seeded fuzz variants across list length, marker, font, and size.
-  Added the independently specified
-  `legal-suppressed-heading-to-bullet-list` and
-  `legal-structured-attachment-mixed-blocks` Microsoft Word differential
-  fixtures; the synthetic catalogue now contains 49 cases and 49 task types.
-
-- The JavaScript test runner now uses bounded asynchronous subprocess workers,
-  capped at four by default, while retaining one fresh Node process per file,
-  sorted reporting, timeouts, captured diagnostics, and failure-marker checks.
-  Set `DOCX_TEST_CONCURRENCY=1` for serial reproduction.
-- Added `npm run benchmark:tests` and a Phase 6 runner regression. The checked
-  benchmark reduced median suite time from 18.02 seconds to 7.96 seconds
-  (55.80%); 20 consecutive parallel runs and a separate serial run passed all
-  63 files. Parallel c8 collection remains valid at 89.90% statements/lines,
-  77.40% branches, and 93.10% functions.
-
-- Added Phase 3 targeting/traversal, Phase 4 list/text parity, and Phase 5 route
-  compatibility regressions. Together with the Phase 6 runner regression, the
-  suite now contains 63 passing test files.
-- Added `npm run benchmark:targeting` and `npm run profile:routes`. The checked
-  10,000-paragraph benchmark showed no single-operation regression and a 47.16x
-  Node median improvement for 100 cached resolutions. The equivalent native
-  Chrome benchmark showed no single-operation regression and a 36.45x batch
-  improvement. All 47 Microsoft Word differential fixtures and all 60 real-
-  document Word corpus scenarios passed after the routing changes.
-
-- Added subprocess coverage for legacy wrapper selection, operation-file
-  compatibility, successful output, atomic anchor failure, source-byte
-  preservation, and protection of pre-existing output files.
-- Added a live-session accuracy and instrumentation suite covering accepted and
-  rejected text, structural validity, sequential equivalence, comments, lists,
-  tables, highlights, one-parse/one-serialize execution, exact no-ops, and
-  atomic rollback. Added `npm run benchmark:session`; the checked accuracy-first
-  benchmark reduced parse/serialize counts from 10/10 to 1/1 and measured a
-  1.58x median speedup with per-operation savepoints retained.
-- Added a Phase 2 architecture regression covering facade export identity,
-  direct leaf imports, exact session rollback, isolated context commit, and
-  stable comment-first scheduling.
-- Added five edge-case suites for canonical text views, cross-paragraph comment
-  inspection, table/list/reference context, sequential package transactions,
-  selective multi-author cleanup, ZIP rejection behavior, CLI filters, JSON
-  exit contracts, and destructive-output safeguards. Together with the Phase 2
-  Phase 1 and Phase 2 regressions, these established the earlier 57-file
-  baseline expanded by the subsequent performance phases.
-
-## 0.3.0
-
-### Breaking changes
-
-- Malformed OOXML no longer escapes public transform APIs as a raw parser
-  exception. In particular, revision accept/reject and comment-deletion callers
-  that previously used `try`/`catch` must now inspect `status === 'error'` and
-  `error.code === 'PARSE_ERROR'` on the returned result.
-- Caller content is no longer sanitized by default. Pass `sanitizeInput: true`
-  to remove a standalone leading assistant-preface line. Dollar-delimited text
-  and literal `\\n` / `\\r\\n` sequences are never removed implicitly.
-- The exported `sanitizeAiResponse` helper no longer removes dollar-delimited
-  spans or converts literal `\\n` / `\\r\\n` sequences. Direct callers that
-  relied on those transformations must perform them explicitly.
-- `applyOperationsToDocumentXml` is atomic by default. Failed batches return
-  the original document with `rolledBack: true`; pass `atomic: false` to retain
-  partial-result behavior.
-- Missing multi-line targets now return `TARGET_NOT_FOUND` instead of being
-  indistinguishable from a no-op. Stale batch anchors also return
-  `TARGET_NOT_FOUND` instead of falling back to a visibly different paragraph.
-
-### Behavior changes and fixes
-
-- Revision IDs are now allocated per document. Near-limit prior IDs restart in
-  a safe low range, and unrelated bookmark/relationship IDs no longer seed the
-  revision counter.
-- Concurrent calls with explicit authors keep their revision attribution
-  isolated from process-global defaults.
-- `existingRevisions: 'accept-all-first'` now preserves the original OOXML when
-  the requested edit is a no-op.
-- Added `existingRevisions: 'accept-all-first-keep-normalized'` for callers that
-  explicitly want accepted existing revisions returned even when no redline is
-  added.
-- Diff output is deterministic by default. Inputs exceeding 262,144 unique
-  tokens return `DIFF_TOKEN_LIMIT` with the original OOXML unchanged instead of
-  risking truncated text; leading whitespace is preserved exactly.
-- Reconstruction preserves structural line breaks and body section-property
-  placement. A target that names only part of a reconstruction range now
-  returns `PARTIAL_TARGET` instead of risking deletion of untargeted content.
-- Paragraph targeting and reconstruction now preserve leading, middle, and
-  trailing `w:tab` elements as literal tab characters instead of omitting or
-  trimming them.
-- Adjacent redline edits now preserve complex-field instructions, begin/
-  separate/end markers, and unchanged cached display results in their original
-  field boundary. Field instructions remain inert and are not evaluated.
-- Added structured XML parse results and result-returning ingestion helpers.
-- Hardened deterministic diff token handling and leading-whitespace fidelity.
-
-### Testing and development
-
-- Expanded the desktop Word differential from 20 to 25 cases, adding structural
-  checks for bookmarks, internal hyperlinks, mixed formatting, content
-  controls, and tables.
-- Expanded the desktop Word differential from 25 to 28 cases with structural
-  tabs and a locked PAGE field, and added tab/field shapes to focused and fuzz
-  regression testing.
-- Expanded the desktop Word differential from 28 to 33 cases with comments,
-  footnotes, endnotes, headers/footers, and an external hyperlink.
-- Extended the deterministic script-only DOCX packager with opt-in related
-  parts, relationship/content-type validation, reusable fixture constructors,
-  and SHA-256 verification that supplied parts remain byte-identical. Runtime
-  library code and dependencies are unchanged.
-- Added validated task, structure, oracle, and manual-review metadata across the
-  33 synthetic and 20 SuperDoc Word cases. `npm run report:word:coverage`
-  produces a deterministic coverage matrix with explicit high-priority gap
-  dispositions, while `npm run review:word:prepare` creates a pending rotating
-  human-review manifest without self-certifying visual results.
-- Added detailed production-function coverage reporting and a checked per-file
-  regression baseline. Five behavior-focused Phase 3 suites exercise numbering
-  collisions/remapping, every reconciliation route, list construction and
-  fallback, patch/format boundaries, table decisions, pipeline modes, and
-  standalone rollback/highlight paths. Production function coverage moved from
-  437/540 to 496/542 and all reachable P0 functions are covered; no runtime
-  behavior or compatibility contract changed.
+# Changelog
+
+## 0.8.4
+
+### Added
+
+- **`textOccurrence` on `format` / `character-format`:** a 1-based match of `textToFormat` inside the resolved paragraph,
+  independent of `target.occurrence` (which selects the paragraph). Out of range fails with `PATCH_SOURCE_NOT_FOUND`;
+  calls without it still read `target.occurrence`. CLI capability `format-text-occurrence-v1`; contract stays version 8.
+- **`applyRedlineToOxml` numbering options:** `numberingXml` and `numberingIdState` remap generated list definitions to
+  IDs that do not collide with the source numbering.
+
+### Fixed
+
+- **Soft-break text can be converted to a list:** a paragraph whose `A. …`, `B. …` items are separated by `<w:br/>` was
+  refused with `TARGET_NOT_FOUND`, and an explicit list request identical to typed markers was a no-op. In-run `\n`/`\t`
+  now serialize back to `<w:br/>`/`<w:tab/>`, including inside `w:delText`, so Reject All restores the breaks.
+- **Localized `replacements` work in paragraphs with soft line breaks:** they were refused with `INVALID_OPERATION`.
+  A `find` within one line now applies and keeps the breaks; a `find` or `replace` that spans or adds a break is refused.
+- **Generated bullets no longer reuse existing numbering IDs:** bullets generated into a document that already defined
+  `numId 1` continued an existing decimal list in Word. The bare runner and `applyRedlineToOxml` now allocate new IDs
+  from the supplied `numberingXml`, as `openDocx` already did.
+- **Appending a table after a paragraph keeps its underline:** the paragraph was tracked as deleted and re-inserted as
+  plain text, so a prior same-author underline, or a `++underline++` sent with the table, was lost on Accept All. The
+  source paragraph is now kept in place.
+- **Word's Reject All removes generated tables:** tracked tables were wrapped in one `w:ins` around `w:tbl`, which Word
+  does not recognize. Reject All left an empty table, and a table at the end of a document could hang Word. Tables now
+  use row-level `w:trPr/w:ins` with inserted cell content and marks, and `rejectTrackedChangesInOoxml` removes a table
+  once all of its rows are rejected. Confirmed in Word.
+
+### Tests
+
+- New `tests/soft_break_list_conversion_tests.mjs`, `tests/soft_break_localized_replacements_tests.mjs`,
+  `tests/generated_bullet_numbering_collision_tests.mjs`, `tests/format_text_occurrence_tests.mjs` and
+  `tests/table_append_fidelity_tests.mjs`.
+
+### Known limitations
+
+- Localized restore in the rejected view still refuses paragraphs with line breaks.
+- The table-append path covers one paragraph followed by one table.
+- Under `merge-same-author`, editing the text of a paragraph that carries your own pending formatting change still drops
+  that formatting on Accept All.
+
+## 0.8.3
+
+### Fixed
+
+- **Reject All no longer leaves an empty paragraph after an inserted paragraph:** `modified: "<original>\n<new>"` on a plain
+  paragraph did not track the new paragraph's mark as inserted. It now does.
+- **Reject All no longer merges source paragraphs after a list range replacement:** replacing a multi-paragraph list range
+  (`target` + `targetEnd`) collapsed the sources into one deleted paragraph, so Reject All gave results such as
+  `Bullet Root ABullet Insertion Anchor`, `AlphaGamma` for an empty middle paragraph, and lost both paragraphs of an
+  all-empty range. Each source paragraph, empty ones included, now keeps its own tracked-deleted paragraph. Confirmed in Word.
+- **Inspection no longer reports historical paragraph properties as current:** `list`, `styleId` and `headingLevel` (and list
+  targeting) could read `numPr`, `pStyle` or `outlineLvl` stored under `w:pPrChange`. Only the paragraph's direct `w:pPr`
+  is read now.
+- **`openDocx` list range replacement no longer renumbers or re-points lists:** deleted source paragraphs were remapped to a
+  new generic `numId` (Reject All restored them with the wrong list type), new items started a separate list (untouched
+  following items restarted at 1), and unused numbering definitions were added. Deleted source paragraphs now keep their
+  `numPr`, and a same-kind replacement reuses the source `numId`, leaving `numbering.xml` unchanged. Reuse applies when the
+  range uses one `numId` and the generated level formats match; format-changing edits still allocate new definitions, and
+  definitions created earlier in the same batch are not reused. Confirmed in Word.
+- **Explicit list start values are applied:** generated list fragments without `xmlns:w` failed to parse in
+  `orchestration/list-structural-fallback.js`, so `7. Header` lost its `startOverride` and xmldom logged parse warnings.
+
+### Tests
+
+- New `tests/list_reject_fidelity_tests.mjs` and `tests/facade_list_numbering_tests.mjs`, with the Word-authored fixture
+  `tests/fixtures/agentic-lists/nested-lists-source.docx`; extended inspection and list structural fallback suites.
+
+### Known limitations
+
+- Plain paragraph to list conversion and list format changes are not yet supported canonically; see
+  `docs/plans/2026-09-30-canonical-list-operations.md`.
+- `1. Header` to `1. Header` on a bare `document.xml` (not a packaged `.docx`) can fail with `RECEIPT_RECONCILIATION_FAILED`.
+
+## 0.8.2
+
+### Fixed
+
+- **Replacement next to a hyperlink no longer pulls adjacent plain text into the link** ([#3](https://github.com/AnsonLai/docx-redline-js/issues/3)):
+  replacing `example.org` with `example.net` (localized `replacements` or full `modified`) in a hyperlink followed by a
+  plain `.` run produced a link showing `example.net.` after Accept All. The reconstruction-mode word diff treated
+  `example.org.` as one token spanning the hyperlink edge. Where a replacement's shared prefix or suffix reaches a wrapper
+  boundary inside the deleted text, it is now kept unchanged.
+- **Reject All no longer reorders text around a manual line break** ([#4](https://github.com/AnsonLai/docx-redline-js/issues/4)):
+  replacing `tabbed` with `aligned` in `<tab>tabbed<w:br/>Line with ` rejected to `<tab>tabbedLine<break> with `, moving
+  deleted text across the break. Break and note-reference placeholders are now standalone word-diff tokens (new internal
+  `atomicChars` option), and change groups are split at references present on both sides. Covered by `tests/reconstruction_boundary_fidelity_tests.mjs`.
+
+## 0.8.1
+
+### Added
+
+- **Header and footer editing:** add `part` to an operation (a selector `{ kind, type?, section? }` or a part path) to edit a
+  header or footer; `inspect().headersFooters` lists the parts with their text, the sections they apply to (including
+  inherited ones) and whether they contain fields. Body edits are unchanged and headers/footers are opt-in. Fields such as
+  PAGE are atomic (`FIELD_EDIT_REFUSED`), comments are refused (`COMMENT_IN_HEADER_FOOTER`), bad selectors fail closed
+  (`PART_NOT_FOUND`, `PART_AMBIGUOUS`), atomic batches roll back across body and parts, revision ids stay unique across the
+  package, receipts name the part, `accept`/`reject` also resolve revisions inside headers and footers, and
+  `validateDocxPackage` checks header/footer references, relationships and content types.
+- **Resolve and reopen comment threads:** `doc.resolveComment(id, { resolved })` and the batch operation
+  `{ "type": "comment_resolve", "commentId": "0", "resolved": true }`, so the CLI can resolve through `apply --operations`.
+  Word resolves whole threads, so the root and every reply change together, whichever id is given. Only
+  `word/commentsExtended.xml` changes; `document.xml` stays byte-identical. Unknown ids fail with `COMMENT_NOT_FOUND`
+  (also in `preflight`).
+- **Delete comments by id:** `doc.deleteComments({ ids })` and `docx-redline delete-comments --comment-id 3,4`. Deleting a
+  thread root also deletes its replies; unknown ids fail closed with `COMMENT_NOT_FOUND`.
+- CLI capabilities `comment-resolve-operation-v1`, `delete-comments-by-id-v1` and `header-footer-parts-v1` (additive; the
+  contract version is unchanged).
+- `services/package-parts.js`, a registry of package part paths, content types and relationship types checked against
+  Word-saved fixtures (`tests/fixtures/word-authored/`), and `npm run test:word:package`, which opens generated outputs in
+  real Word with repair disabled and checks comment counts, thread parents, resolved state and header/footer revisions
+  through Word's object model.
+
+### Fixed
+
+- **Word "unreadable content" prompt on commented documents:** `word/commentsExtended.xml` was relabeled
+  `application/vnd.ms-word.commentsExtended+xml` on every save of any document that already had comments.
+  Word expects `application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtended+xml` and
+  offered to repair the file. The constant is corrected, an edit that does not change comment threading no
+  longer rewrites the extended part or its content type/relationship, and files already damaged by earlier
+  versions are repaired on the next save (`repairKnownContentTypes`, also exported). `validateDocxPackage`
+  now rejects the wrong type instead of accepting it. `tests/package_content_type_contract_tests.mjs` checks this
+  against a Word-authored content-type table on every OS.
+- **Comment threads keyed on the last paragraph:** Word joins `comments.xml` to `commentsExtended.xml` and
+  `commentsIds.xml` through the `w14:paraId` of a comment's LAST paragraph. Inspection, package validation,
+  replies and delete-cascade used the first, so Word's own multi-paragraph threaded documents failed
+  validation and replies to them attached to the wrong key.
+- **Edits no longer drop comment anchors:** a mid-paragraph edit of a commented paragraph dropped the trailing
+  `commentRangeEnd` and `commentReference` (markers at the very end of the paragraph text were only emitted when the
+  last diff part was an insert), leaving the comment unanchored and failing package validation. Found by
+  opening our output in real Word; covered by `tests/comment_marker_preservation_tests.mjs`.
+- **Replies are now visible in Word:** `comment_reply` only wrote `comments.xml`/`commentsExtended.xml`, and Word
+  does not show a reply that has no body markers. Replies now get their own `commentRangeStart`/`commentRangeEnd`/
+  `commentReference` next to the thread's, laid out like Word writes them. A reply to a reply joins the root thread.
+  A parent with no body anchor fails with `PARENT_ANCHOR_NOT_FOUND`.
+- **Replies to a resolved thread are resolved too**, as Word writes them (`reply-to-resolved.docx` fixture). They were
+  written open, leaving a thread that was half resolved.
+- `commentsIds.xml` and `commentsExtensible.xml` are kept consistent with `comments.xml` on add/delete when present.
+- `deleteComments` and `resolveRevisions` report `artifactsChanged` from a real diff of the package (they listed a fixed
+  set of parts and missed `commentsIds.xml`, `commentsExtensible.xml` and `[Content_Types].xml`).
+
+## 0.8.0
+
+### Universal Document Facade & Zero-Node Architecture
+
+- **Universal `DocxDocument` & `openDocx`:** Implemented complete-DOCX lifecycle operations
+  (`openDocx`, `doc.inspect()`, `doc.applyOperations()`, `doc.resolveRevisions()`, `doc.deleteComments()`,
+  `doc.toUint8Array()`, `doc.getRevisionToken()`) on standard `Uint8Array` in `document/docx-document.js`,
+  re-exported directly from `index.js`. Enables complete-document redline workflows in any JavaScript
+  runtime without Node.js dependencies.
+- **Pure-JS ZIP container (`fflate`):** Replaced `node:zlib` with lightweight, zero-dependency `fflate`
+  in `document/zip-archive.js`, providing cross-runtime raw DEFLATE / INFLATE compression and decompression
+  with full OOXML archive compatibility.
+- **Pure-JS FIPS 180-4 SHA-256:** Created zero-dependency, synchronous SHA-256 implementation in
+  `core/sha256.js`, removing `node:crypto` from package revision token calculations while retaining
+  exact deterministic hash parity with standard NIST vectors.
+- **Transparent XML DOM fallback:** Added `resolveDomParserConstructor()` and
+  `resolveXmlSerializerConstructor()` in `adapters/xml-adapter.js`, automatically utilizing native
+  `globalThis.DOMParser`/`globalThis.XMLSerializer` when present and falling back transparently to
+  `@xmldom/xmldom` in headless, server, edge, and sandbox environments without requiring manual provider setup.
+- **Zero-dependency sandbox bundles:** Configured `scripts/build.mjs` with `esbuild` (`platform: 'neutral'`)
+  to produce single-file, zero-dependency standalone bundles in both ESM (`dist/docx-redline.bundle.js`)
+  and CommonJS (`dist/docx-redline.bundle.cjs`), exported as `@ansonlai/docx-redline-js/bundle` for direct
+  use in workflow engines (e.g., n8n Code nodes), Cloudflare Workers, AWS Lambda, Deno, and QuickJS sandboxes.
+- **Strict runtime boundary enforcement:** Removed `node:zlib` and `node:crypto` from allowed external
+  imports in `tests/no_word_api_index_check.mjs`. Automated sandbox isolation tests
+  (`tests/sandbox_bundle_isolation_tests.mjs`) verify zero Node built-in imports and full document
+  reconciliation in restricted VM contexts without `process`, `Buffer`, or `require`.
+- **Backward compatibility:** Preserved full API and `Buffer` compatibility for `@ansonlai/docx-redline-js/node`
+  consumers and `doc.toBuffer()`.
+
+## 0.7.2
+
+### Agent Surface Simplification
+
+- **Extraction-first golden path:** Re-established the single deterministic two-turn
+  "extract-then-apply" sequence as the default agent workflow across `AGENTS.md`,
+  `docs/AGENT_FAST_START.md`, and `docs/SKILL_AUTHORING.md`. Eliminates the
+  upfront "choice tax" and model deliberation overhead.
+- **Localized replacements after inspection:** Decoupled localized patching from
+  speculation. Agents inspect the target paragraph first, then supply compact
+  `replacements` instructions, achieving 60.6%–90.8% payload reductions without
+  speculative ambiguity risk.
+- **Computed success gate:** Consolidated standard success verification onto
+  `completion: true` and non-null `outputPath`, removing multi-field verification
+  checklists from primary prompts while retaining full `change` audit evidence.
+- **Advanced features relocated:** Speculative 1-turn apply, directional context
+  windows (`--context-range`), and anchor diagnostics are relocated to
+  `docs/AGENT_KNOWLEDGE_BASE.md` and CLI help as opt-in harness policies.
+- **Observed-state restoration:** Restructured restoration as a clean request-
+  or hint-driven branch (`--view rejected` or `selection.hint`) rather than an
+  upfront classification decision.
+- **Empirical surface evaluation:** Added synthetic replay benchmark
+  (`npm run benchmark:agent-surface`) and validation report documenting 100%
+  first-attempt task correctness and payload savings across three workflow policies.
+
+## 0.7.1
+
+### Reliability and Discovery Refinements
+
+- Localized replacement matching now tries exact case-sensitive text first,
+  then a narrow ASCII-space/non-breaking-space equivalent match. Ambiguous
+  equivalent matches still fail closed, and unchanged boundary NBSPs are
+  retained to avoid incidental whitespace redlines.
+- Added a narrow single-paragraph restore shortcut. A restore with a strong
+  rejected-view target may omit `modified` for verbatim restoration or provide
+  exact `replacements`; the CLI exposes the same path through `apply --restore
+  --target-id ID`. Ranges, captures, weak targets, and inferred companion
+  content remain excluded.
+- Fixed rejected-view restore receipts so `resolvedTarget` text, fingerprint,
+  revision view, and match diagnostics describe the view actually used to
+  resolve the target.
+- Fixed alternate-view search hints to honor `--revised`, `--table`, and
+  `--body`, and retained compact revision authors plus `deleted`/`inserted` cues
+  in `extract` output so empty revision-view paragraphs are self-explanatory.
+
+## 0.7.0
+
+### Agent Performance and Localized Editing
+
+- **Localized exact replacements:** `redline`/`replace` operations may provide
+  `replacements: [{ find, replace, occurrence? }]` instead of a complete
+  `modified` paragraph. The compiler resolves the accepted-view source once,
+  applies non-overlapping exact replacements simultaneously, synthesizes the
+  canonical desired paragraph, and delegates to the unchanged OOXML engine.
+- **One-turn speculative apply:** `docx-redline apply --find ... --replace ...`
+  can resolve a globally unique source literal without preliminary extraction.
+  `--search` plus signed `--context-range START:END` scopes visible headings and
+  nearby content; `--around N` is symmetric shorthand. Longer, distinctive
+  anchors are recommended because generic or repeated phrases widen the unioned
+  scope and may cost an ambiguity-recovery turn.
+- **Fail-closed selection:** Missing anchors and patch sources, multiple eligible
+  paragraphs, ambiguous occurrences, overlaps, conflicts, and unsupported
+  localized shapes refuse mutation. A failed speculative command never writes
+  or truncates its output path.
+- **Verified change evidence:** Localized operation results include a compact
+  `change` object with target location, contextual anchor/range, exact
+  replacement entries, bounded before/after excerpts, commit disposition, and
+  post-mutation accepted-view verification. Atomic rollback marks the evidence
+  non-committed and `rolled_back`.
+- **CLI contract version 8:** Adds `localized-replacements-v1`,
+  `speculative-search-apply-v1`, and `localized-change-summary-v1`. Skills and
+  harnesses should pin version 0.7.0 and negotiate only the capabilities used.
+- **Measured workflow reduction:** The checked benchmark records 50% fewer tool
+  turns and a 64.77%–78.98% smaller deterministic request-token proxy across
+  three literal-edit cases. Median native engine/I/O time remained effectively
+  neutral; provider reasoning and network latency were not estimated.
+
+### Compatibility
+
+- Existing `modified` operations, strong targets, operations files/stdin,
+  tracked-change generation, package validation, rollback, comments,
+  Accept/Reject, and revision policies remain supported.
+- Localized replacement fields and successful `change` evidence are additive.
+  Wrappers that adopt them must require CLI contract 8; integrations using only
+  earlier capabilities can continue using their existing operation shapes.
+- The implementation remains OOXML-only and adds no runtime dependency or Word,
+  Office automation, COM, or proprietary document API requirement.
+
+## 0.6.0–0.6.2
+
+### Safety Fixes
+
+- **Foreign deleted-paragraph resurrection guard**: Refuses non-empty same-paragraph edits when another author owns the paragraph-mark deletion and all existing paragraph content is deleted. The operation now returns `FOREIGN_PARAGRAPH_MARK_DELETION` with the owning author instead of emitting lifecycle-unsafe OOXML; atomic document operations roll back byte-for-byte. `validateRedlineOoxml` reports already-authored instances as warnings.
+- **Source-truth whitespace replacement alignment (WP09a)**: Strict target resolution may equate ordinary spaces with NBSPs, but mutation offsets now always come from the resolved paragraph's exact accepted view. Space-equivalent word replacement hunks are refined to character-local edits, and multiple plain-text edits are applied right-to-left against refreshed live spans. This tracks NBSP-to-space substitutions exactly while preserving unchanged hyperlinks and prevents earlier run splits from invalidating later anchors.
+- **Exact mismatch diagnostics**: `PATCH_ROUNDTRIP_MISMATCH` now includes the expected and actual code points at the first mismatch. Document-operation results also report bounded `targetTextMatch` diagnostics when target selection used equivalent whitespace.
+- **Baseline-delta validation (WP09c)**: Restoration, operation, and package validation now compare issue multisets against the source. Unchanged legacy defects remain visible without blocking safe work, while any added occurrence or mutation-envelope error fails closed with `GENERATED_OOXML_INVALID` before an operation is reported as applied.
+- **Revision identity sanitation (WP09d)**: New paragraph/list builders inherit effective `pPr`/`rPr` formatting without cloning historical revision descendants. Operation-level whole-document validation catches duplicate revision IDs and rolls back the operation savepoint before committing its receipt.
+- **View-consistent restore targeting**: `restore` targets now default to the rejected view, where a wholly deleted paragraph's source text exists. Rejected-view inspection now computes fingerprints from rejected-view text and reports the view beside each paragraph. Explicit cross-view text or fingerprint mistakes retain strict refusal while returning an actionable view hint.
+
+### New Features
+
+- **Self-describing and bounded agent discovery (WP-00–WP-02)**: CLI contract version 6 adds command-specific JSON help, canonical redline/comment/restore examples, case-insensitive contextual search with `--around`/`--context`/`-C`, direct-hit pagination through `--limit` and `--after`, and deliberate `--all` opt-out. Unscoped inspection is capped at 20 direct records and a 48 KiB soft budget without truncating any returned `exactText`; extraction now distinguishes matches from context and prioritizes human-facing provision/heading references over machine paragraph ordinals.
+- **Composable agent safety and compact output (WP-03–WP-04)**: CLI contract version 7 replaces the atomic-coupled agent profile capability with `agent-safety-profile-v2`. `--profile agent` now enforces complete-success exits while preserving progressive execution and the ordinary revision policy; `--atomic` and `--existing-revisions` compose explicitly. Compact CLI JSON keeps receipts only in the authoritative top-level array, omits exact-match diagnostics, summarizes successful equivalent-whitespace matches, and supports one-line `--compact` output without changing Node or standalone-runner results.
+- **Packaged skill-authoring contract (WP-05)**: `docs/SKILL_AUTHORING.md` separates automation invariants from transaction/revision policy, file-versus-stdin transport, reviewer preferences, recovery-envelope behavior, and human-facing presentation. It requires contract/capability negotiation, focused contextual extraction, and library delegation while retaining the visible `AI Redliner` fallback without a new author guard.
+- **Batch-start source binding (WP-04)**: Strong document-operation targets are compiled once against the immutable source DOM and carried through structural index/fingerprint drift with rollback-aware session identities. Independent edits no longer need manual bottom-up sorting; same-source writes, incompatible revision/format combinations, and unsafe capture fan-out fail before mutation with causal conflict codes. Unique references to paragraph text created elsewhere in the same batch become explicit internal capture dependencies.
+- **Machine-actionable recovery (WP-05)**: Operation, package-facade, example-session, and compact CLI failures now carry recovery envelope version 1 with stable stage/category/action metadata, bounded corrective context, and authorization flags. Failed and partial mutation results include an explicit original-vs-output retry plan and operation indexes. `apply --require-complete` exits with code 3 for partial work while preserving legacy behavior without the flag.
+- **Compact shell-agent protocol (WP-06)**: CLI contract version 5 adds `operations-stdin` and `agent-profile-v1`. `--operations -` accepts UTF-8 operation arrays/envelopes without a temporary operations file, while explicit `--profile agent` combines atomic rollback and complete-success exit behavior and reports its effective settings. `AGENTS.md` is now a 527-word routing card, and the 349-word `docs/AGENT_FAST_START.md` carries the ordinary edit contract. Ambient project configuration was deliberately deferred because it would save only the profile flag while adding hidden state.
+- **Agent rollout audit (WP-07)**: The observational benchmark now compares canonical Node, legacy file-based CLI, compact stdin/profile CLI, and the development session example while verifying accepted/rejected text, comment preservation, independent batch permutations, recovery behavior, and cross-author attribution. The checked run records 82.75% fewer ordinary instruction words, one fewer shell tool turn (33.33%), and 82.22–89.96% smaller localized session requests than canonical Node envelopes without claiming unmeasured provider/model latency.
+- **Explicit paragraph restoration (`type: 'restore'`)**: Restores or counterproposes another reviewer's pending whole-paragraph deletion as a separately tracked sibling paragraph. The source deletion remains untouched; the restored paragraph receives its own inserted paragraph mark, content insertion, sanitized paragraph properties, and fresh `w14:paraId`. Single paragraphs and contiguous ranges are supported, with full Accept/Reject lifecycle verification and structured refusals at unsafe table-row, move, section-break, and terminal-paragraph boundaries.
+- **Compact mutation CLI contract (WP09b)**: CLI contract version 3 removes `documentXml`, OOXML/package artifacts, full inspection data, and full validation issue arrays from normal `apply`, `accept`, `reject`, and `delete-comments` stdout. Mutation responses retain actionable errors, per-operation receipts, output durability fields, code/count validation summaries, and a derived `completion` flag that cannot report success for failed, partial, or unwritten work.
+- **Word-native deleted-section editing (WP09e)**: An explicit rejected-view `insert` operation can split a foreign deletion at an exact anchor-relative offset into sibling `del(A) / ins(B) / del(A)` carriers. Contiguous paragraph restorations now follow their untouched deleted source block, matching Microsoft Word's ordering. Ambiguous anchors and unsupported structural split boundaries remain fail-closed.
+
+## 0.5.1
+
+### Highlights & New Features
+
+- **Cross-Author Revision Slicing (`existingRevisions: 'slice-cross-author'`)**: Adds native support for editing text inside another reviewer's pending tracked insertion without erasing their attribution or requiring prior acceptance.
+  - **Word-Native Insertion Slicing**: When inserting text inside another author's pending `<w:ins>`, the engine splits the outer carrier into sibling `<w:ins>` elements at the paragraph level (`[ins(A), ins(B), ins(A)]`), ensuring strict ECMA-376 schema compliance without illegal `ins/ins` nesting.
+  - **Word-Native Deletion Slicing**: When deleting text inside another author's pending `<w:ins>`, the engine nests `<w:del>` directly inside `<w:ins>` per ECMA-376 Part 1 `CT_RunTrackChange` Section 17.13.5.21 and Microsoft Word Desktop 365 native behavior.
+  - **Boundary & Straddle Deletions**: Deletions straddling baseline text and pending insertions cleanly partition into separate top-level and nested `<w:del>` containers while sharing unified event/author attribution.
+  - **Multi-Author Stacked Revisions**: Multiple reviewers can independently delete or insert content within the same carrier insertion without cross-author interference.
+  - **Cascading & Coalescing Lifecycles**: Full round-trip lifecycle parity with Microsoft Word Desktop:
+    - Rejecting Author A cleanly discards Author A's insertion and any dependent nested deletions by Author B.
+    - Accepting Author A unwraps the insertion into baseline text while leaving Author B's deletions pending against the baseline.
+    - Rejecting Author B restores Author B's deleted text within Author A's insertion, and coalesces adjacent split `<w:ins>` fragments back into a single continuous carrier.
+  - **CLI & Facade Integration**: Fully exposed via the `docx-redline` CLI (`--existing-revisions slice-cross-author`), Node facade (`openDocx`), and batch operation runner.
+
+### Non-breaking Changes & Improvements
+
+- **Validation Update (`validateRedlineOoxml`)**: Refined `NESTED_REVISION` checks to permit direct `<w:ins><w:del>...</w:del></w:ins>` nesting (standard ECMA-376 and Word Desktop behavior), while continuing to strictly reject `ins/ins`, `del/del`, and `del/ins` nesting.
+- **Slicing Round-Trip Guard**: Cross-author surgical edits now preserve whitespace-only insertions (including ordinary-space replacements for NBSP characters beside hyperlinks) and verify the exact accepted-view text before reporting success. A mismatch fails closed with `PATCH_ROUNDTRIP_MISMATCH` and returns the original OOXML unchanged.
+- **Hyperlink-Adjacent Replacement Anchoring**: Paired replacements immediately before or after a hyperlink now retain a stable insertion point after the deletion run is split, preventing qualifiers from being relocated past the hyperlink or following formatted runs.
+- **Multiple Same-Run Insertions**: Insertion-only slicing operations with multiple edit points now apply from right to left against a refreshed live span index, preventing an earlier run split from relocating later insertions.
+- **Insertion Stress Hardening**: Slicing now detects edge whitespace changes exactly, uses a character-local insertion-only diff when the original text is an exact subsequence of the modified text, and coalesces new text into an existing same-author carrier when foreign revisions are also present. This prevents repeated phrases from relocating insertions and prevents invalid `w:ins/w:ins` nesting in mixed-author paragraphs.
+- **Preflight Inspection**: `preflightOperations` now inspects and validates `slice-cross-author` batches, reporting pending foreign-author carrier targets as `ready` instead of `EXISTING_REVISIONS`.
+- **Test Suite Expansion**: Added 7 new test suites covering 36 Word Desktop COM golden fixtures, carrier splitting invariants, the SYN-01..12d synthetic test matrix, PKG-01..06 strict package differential replay, the repeated-text/hyperlink whitespace regression, 76 deterministic insertion stress scenarios, and 12 replacement-anchor lifecycle scenarios (expanding the suite from 88 to 95 passing suites).
+
+## 0.5.0
+
+### ⚠️ Breaking changes
+
+The following changes can require caller or contributor updates. No public
+export or valid existing function signature was removed.
+
+#### Runtime and result-contract changes
+
+- **Canonical paragraph text:** `getParagraphText(...)` now returns the
+  accepted/current view instead of the earlier simplified `w:t`/`w:tab`
+  concatenation. It excludes deleted and `w:moveFrom` content and includes
+  structural breaks, soft hyphens, and non-breaking hyphens.
+  **Migration:** regenerate compared/cached text with the upgraded library. Use
+  `extractCanonicalParagraphText(...)` when accepted/rejected-view semantics
+  are intended; integrations that require the former raw traversal must retain
+  their own legacy extractor before upgrading.
+- **Paragraph fingerprints:** fingerprints now incorporate canonical paragraph
+  text. Stored fingerprints can become stale for paragraphs containing
+  revisions, moves, breaks, soft hyphens, or non-breaking hyphens.
+  **Migration:** do not carry fingerprints across this upgrade; re-extract the
+  document and regenerate target descriptors.
+- **Invalid operations:** malformed or field-incompatible document-operation
+  objects now return a structured `INVALID_OPERATION` error at the runner
+  boundary instead of reaching later failure/no-op paths.
+  **Migration:** validate operation files against the published schema and
+  handle `status === 'error'` plus `error.code === 'INVALID_OPERATION'`.
+- **Commented paragraph deletion:** deleting a complete paragraph that contains
+  an existing comment now fails with `COMMENTED_CONTENT_DELETE` instead of
+  producing OOXML with dangling comment references.
+  **Migration:** preserve or deliberately remove/relocate the comment before
+  deleting the paragraph, and handle the structured error. Atomic callers keep
+  the original document unchanged.
+- **Comment anchor failures:** missing or ambiguous comment anchors now return
+  `ANCHOR_NOT_FOUND` or `AMBIGUOUS_ANCHOR` and fail/roll back an atomic batch;
+  they are no longer reported as successful `no_change` operations.
+  **Migration:** treat these codes as failed operations and use a unique exact
+  anchor or stricter target descriptor before retrying.
+- **Stricter package validation:** DOCX package validation now rejects
+  unbalanced comment ranges, dangling references/usages, orphan definitions,
+  and duplicate comment-definition IDs that earlier validation could allow.
+  **Migration:** repair the comment anchors and `word/comments.xml` definitions
+  before applying or validating further changes.
+
+#### Development workflow change
+
+- **Parallel tests by default:** `npm test` now runs up to four isolated child
+  processes concurrently. This does not change the published runtime API, but
+  contributor automation that depends on test execution order or shared files
+  must be updated. **Migration:** make tests independent or set
+  `DOCX_TEST_CONCURRENCY=1` for the previous serial scheduling behavior.
+
+Strict targeting remains opt-in on existing low-level mutation APIs; it is the
+default only on the newly added Node facade and CLI.
+
+### Deprecations and future breaking changes
+
+- Replacing an existing numbering part without a merge callback now emits a
+  deprecation warning. The Node facade and CLI already merge safely by default.
+  **This remains supported in this release but will become an error in the next
+  major version.** Migrate low-level callers to
+  `mergeNumberingXmlBySchemaOrder` before that release.
+- **Permissive target resolution deprecation (`AMBIGUOUS_TARGET_HEURISTIC_USED`):**
+  Lower-level document operation runners currently default to permissive targeting.
+  In v1.0.0, application will default to `strictTargets: true`. In this release,
+  when permissive resolution encounters multiple identical candidate paragraphs and
+  heuristically chooses the first candidate, it emits an `AMBIGUOUS_TARGET_HEURISTIC_USED`
+  warning with candidate count and migration guidance.
+  **Migration:** Disambiguate operations using `paragraphId`, `index`, `occurrence`,
+  or `fingerprint` and pass `{ strictTargets: true }`.
+
+### ℹ️ Noteworthy Default & Usability Changes (Non-breaking)
+
+The following improvements update default behaviors to maximize agent speed, reduce friction, and eliminate unnecessary errors during iterative editing. These changes are **not technically breaking changes** (no public APIs or exports were removed, and all existing options remain configurable), but represent important behavioral refinements that callers should note:
+
+- **Fallback Author Default (`'AI Redliner'`):** `setDefaultAuthor`, `node/cli.js`, and `openDocx` now default to `'AI Redliner'` (configurable via the `DOCX_REDLINE_AUTHOR` environment variable or `--author`). The CLI `apply` command and core APIs no longer error with `AUTHOR_REQUIRED` when operations omit an author.
+- **Output Overwrite by Default:** Destination files provided via `--output` now overwrite by default instead of failing with `OUTPUT_EXISTS`. Callers wanting protection against accidental overwrites can pass `--no-overwrite` or `--no-clobber`. The source document remains protected and is never overwritten unless `--in-place` is explicitly passed.
+- **Replacement Event Pairing (`pairReplacements: true` by default):** Adjacent `<w:del>` and `<w:ins>` revisions now default to sharing linked revision metadata and identical timestamps so Microsoft Word groups them as a single replacement in the Reviewing Pane. Pass `pairReplacements: false` for independent revision timestamps.
+- **Structured Content Auto-Detection (`structuredContent: true` by default):** Markdown tables, headings (`#`), and lists in replacement text automatically render as native Word elements (`w:tbl`, `w:pStyle`, `w:numPr`). Single outline-numbered legal clauses (e.g. `13.2.1.1`) continue to be treated as ordinary paragraphs without spurious list conversion. Pass `structuredContent: false` to treat replacement text strictly as plain text.
+- **Progressive Batch Mode (`atomic: false` default, `atomic: true` opt-in):** Batch operations and CLI `apply` now apply edits progressively by default (`atomic: false`): valid edits commit directly, while failing edits report structured errors in `results` for faster debugging. Pass `{ atomic: true }` (or `--atomic` on the CLI) for all-or-nothing rollback when any operation fails.
+- **Clean Direct Edits (`generateRedlines: false` / `--no-redlines`):** Prominently documented that tracked redlines are not always the preferred method. Callers can pass `generateRedlines: false` (or `--no-redlines` on the CLI) for clean execution drafts, document restructuring, or minor typo fixes without tracked changes markup.
+- **Existing Revisions Policy (`existingRevisions: 'merge-same-author'` by default):** When editing a paragraph that already contains tracked changes from the same author, prior revisions by that author are merged against the pre-revision baseline (prior changes by that author are reverted and re-diffed to the new modified text), avoiding revision accumulation and nested markup. If a paragraph contains tracked changes from another reviewer, the operation fails closed with `EXISTING_REVISIONS` to protect third-party review marks. Commented revision content fails closed with `COMMENTED_CONTENT_MERGE` so comment anchors cannot be removed or orphaned. Callers can explicitly pass `'accept-all-first'` to normalize prior revisions or `'reject-input'` to refuse editing any revised paragraph.
+- **Inline One-Liner CLI Edits:** Added `--target <text>` with `--modified <text>` or `--comment <text>` on `docx-redline apply` for fast 1–2 edit workflows without creating a JSON operations file.
+
+### Added
+
+- Added **Mutation Receipts** (`receipt` on `DocumentOperationResult` and `receipts`
+  on `BatchOperationResult`). Every operation execution returns structured,
+  commit-aware telemetry capturing durable revision IDs (with kind and target part),
+  comment IDs, numbering IDs, relationship IDs, affected targets, and warnings.
+  Supports `not_attempted`, `applied`, `refused`, `no_change`, and `rolled_back`
+  dispositions.
+- Added **Commit-Aware Output Reconciliation Oracle** (`reconcileReceiptsAgainstOutput`).
+  Before completing any transaction, reported durable IDs are checked against a
+  fresh parse of the generated output OOXML parts. Any reconciliation discrepancy
+  immediately fails the transaction and triggers atomic rollback.
+- Exported receipt primitives: `ReceiptCollector`, `createEmptyReceipt`, and
+  `reconcileReceiptsAgainstOutput` along with `MutationReceipt` and
+  `MutationReceiptRevisionItem` TypeScript declarations.
+- Added **Paragraph Mark Revisions** (`w:pPrChange`, `markParagraphMarkInserted`,
+  `markParagraphMarkDeleted`) ensuring whole-paragraph deletions and insertions
+  cleanly track paragraph mark lifecycles for full Accept All / Reject All symmetry.
+- Added **Paragraph Boundary Mutation Validation** (`validateParagraphBoundaryMutation`)
+  guarding against invalid cross-paragraph boundary merges.
+
+- Added `analyzeStructuredContent(...)` and `planStructuredReplacement(...)`
+  for agent-authored attachments and schedules containing mixed headings,
+  paragraphs, lists, and tables. The planner returns typed blocks and produces
+  one atomic `structuredContent` operation only when the Markdown is valid.
+
+- Added session-scoped paragraph metadata indexing for canonical text,
+  normalized text, paragraph IDs, fingerprints, table context, and document
+  indexes, plus deterministic targeting and route-profiling benchmarks.
+- Added a shared list-marker grammar and parsed list-item vocabulary used by
+  pipeline analysis, orchestration, normalization, and list targeting.
+- Added an internal reconciliation capability matrix and opt-in route
+  instrumentation. Public reconciliation result shapes and route selection
+  policy remain unchanged.
+
+- Added `scripts/extract_text.mjs` and `scripts/apply_changes.mjs` as thin
+  compatibility entrypoints for legacy skill installations. They delegate to
+  the supported CLI, retain strict atomic validated writes, and accept legacy
+  operation files with a top-level `changes` array.
+- Added typed operations, per-operation authors, strict target descriptors,
+  deterministic preflight diagnostics, and auditable resolution metadata.
+- Added `inspectDocumentParts(...)`, a structured document inventory using the
+  same canonical text extractor as targeting and ingestion.
+- Added `@ansonlai/docx-redline-js/node`. `openDocx(...)` applies batches to
+  complete DOCX buffers transactionally and validates before commit.
+- Added the cross-platform `docx-redline` CLI with JSON `inspect`, `extract`,
+  `preflight`, `apply`, `accept`, `reject`, `delete-comments`, and `validate`
+  commands, plus a published operation-file JSON Schema.
+
+### Behavior and reliability
+
+- Explicit structured replacements now reject missing Markdown table separator
+- Generated Markdown tables repeat their header row and prevent logical data rows from splitting across pages.
+  rows, missing data rows, and inconsistent column counts with
+  `STRUCTURED_CONTENT_INVALID` instead of inserting literal pipe-delimited text.
+- Tables created inside mixed replacements are tracked once at block scope,
+  avoiding nested revisions while keeping Accept All and Reject All symmetric.
+
+- Target preflight and live mutation reuse one document-scoped paragraph index;
+  strict duplicate detection and resolution metadata retain their prior
+  semantics while avoiding repeated whole-document text traversal.
+- Revision-ID seeding now walks the DOM with child/sibling pointers instead of
+  allocating an array containing every element.
+- Single-source-paragraph list expansion uses the focused list generator
+  directly. Multi-paragraph marked-list edits deliberately retain the legacy
+  run-aware reconciliation pipeline for structural parity.
+- Fixed paragraph-to-list expansion when a manually numbered heading carries
+  `w:numId w:val="0"`. Numbering suppression is no longer reused as a generated
+  list ID, so inserted bullet and numbered items receive valid positive IDs.
+- Tracked heading-to-list replacements now keep the deleted source heading in
+  its own paragraph and track the paragraph marks of every inserted list item.
+  This prevents deleted heading text from joining the first item and preserves
+  exact Accept/Reject structure without adding a full-document sentinel
+  paragraph.
+- Inserted list items now inherit source font family, size, language, and
+  related script typography without inheriting heading-only bold, underline,
+  italic, or strike formatting unless requested by the replacement markdown.
+- Canonical-only table-cell targeting now consumes the shared paragraph-text
+  extractor, while offset- and sentinel-producing walkers remain specialized.
+  Their accepted visible projections now agree on soft hyphens as well as tabs,
+  breaks, hyperlinks, and non-breaking hyphens.
+
+- Comment preflight and application now share one anchor resolver. Exact
+  matches take priority, unique ordinary-space/NBSP differences preserve raw
+  offsets, and missing or repeated anchors return structured
+  `ANCHOR_NOT_FOUND` or `AMBIGUOUS_ANCHOR` errors.
+- Full-document operation batches now share one live DOM and revision-ID
+  allocator, reducing complete-document parsing and serialization from once per
+  operation to once per changed batch. Scoped reconciliation engines and their
+  targeting decisions are unchanged.
+- Each live-session operation uses a DOM and allocator savepoint. Errors and
+  reported no-ops restore the savepoint; atomic failures and all-no-op batches
+  still return the exact original XML without serializing it.
+- Decomposed the standalone document-operation runner into a stable 13-line
+  compatibility facade plus focused session, applier, batch-orchestrator,
+  heuristic, and OOXML-mutation modules. Runtime exports and declarations are
+  unchanged, and operation internals now use leaf imports instead of importing
+  the root entry point.
+- Package comment IDs are seeded from existing anchors and definitions, and
+  the Node facade merges numbering without discarding prior definitions.
+- Canonical paragraph text consistently handles revisions, moves, tabs,
+  breaks, soft hyphens, and non-breaking hyphens; see the breaking-change note
+  above for `getParagraphText(...)` and fingerprint compatibility.
+- Structured inspection now explicitly supports the `current` view as the
+  accepted/current document view and resolves comment ranges spanning multiple
+  paragraphs as one exact anchor string.
+- Transactional no-op results preserve the original DOCX bytes exactly,
+  including when the same facade instance has already committed an edit.
+
+### Testing and development
+
+- Added focused and semantic visual-failure regressions for suppressed
+  numbering, paragraph separation, paragraph-mark revisions, selective
+  typography inheritance, and exact accepted/rejected paragraph sequences,
+  plus seeded fuzz variants across list length, marker, font, and size.
+  Added the independently specified
+  `legal-suppressed-heading-to-bullet-list` and
+  `legal-structured-attachment-mixed-blocks` Microsoft Word differential
+  fixtures; the synthetic catalogue now contains 49 cases and 49 task types.
+
+- The JavaScript test runner now uses bounded asynchronous subprocess workers,
+  capped at four by default, while retaining one fresh Node process per file,
+  sorted reporting, timeouts, captured diagnostics, and failure-marker checks.
+  Set `DOCX_TEST_CONCURRENCY=1` for serial reproduction.
+- Added `npm run benchmark:tests` and a Phase 6 runner regression. The checked
+  benchmark reduced median suite time from 18.02 seconds to 7.96 seconds
+  (55.80%); 20 consecutive parallel runs and a separate serial run passed all
+  63 files. Parallel c8 collection remains valid at 89.90% statements/lines,
+  77.40% branches, and 93.10% functions.
+
+- Added Phase 3 targeting/traversal, Phase 4 list/text parity, and Phase 5 route
+  compatibility regressions. Together with the Phase 6 runner regression, the
+  suite now contains 63 passing test files.
+- Added `npm run benchmark:targeting` and `npm run profile:routes`. The checked
+  10,000-paragraph benchmark showed no single-operation regression and a 47.16x
+  Node median improvement for 100 cached resolutions. The equivalent native
+  Chrome benchmark showed no single-operation regression and a 36.45x batch
+  improvement. All 47 Microsoft Word differential fixtures and all 60 real-
+  document Word corpus scenarios passed after the routing changes.
+
+- Added subprocess coverage for legacy wrapper selection, operation-file
+  compatibility, successful output, atomic anchor failure, source-byte
+  preservation, and protection of pre-existing output files.
+- Added a live-session accuracy and instrumentation suite covering accepted and
+  rejected text, structural validity, sequential equivalence, comments, lists,
+  tables, highlights, one-parse/one-serialize execution, exact no-ops, and
+  atomic rollback. Added `npm run benchmark:session`; the checked accuracy-first
+  benchmark reduced parse/serialize counts from 10/10 to 1/1 and measured a
+  1.58x median speedup with per-operation savepoints retained.
+- Added a Phase 2 architecture regression covering facade export identity,
+  direct leaf imports, exact session rollback, isolated context commit, and
+  stable comment-first scheduling.
+- Added five edge-case suites for canonical text views, cross-paragraph comment
+  inspection, table/list/reference context, sequential package transactions,
+  selective multi-author cleanup, ZIP rejection behavior, CLI filters, JSON
+  exit contracts, and destructive-output safeguards. Together with the Phase 2
+  Phase 1 and Phase 2 regressions, these established the earlier 57-file
+  baseline expanded by the subsequent performance phases.
+
+## 0.3.0
+
+### Breaking changes
+
+- Malformed OOXML no longer escapes public transform APIs as a raw parser
+  exception. In particular, revision accept/reject and comment-deletion callers
+  that previously used `try`/`catch` must now inspect `status === 'error'` and
+  `error.code === 'PARSE_ERROR'` on the returned result.
+- Caller content is no longer sanitized by default. Pass `sanitizeInput: true`
+  to remove a standalone leading assistant-preface line. Dollar-delimited text
+  and literal `\\n` / `\\r\\n` sequences are never removed implicitly.
+- The exported `sanitizeAiResponse` helper no longer removes dollar-delimited
+  spans or converts literal `\\n` / `\\r\\n` sequences. Direct callers that
+  relied on those transformations must perform them explicitly.
+- `applyOperationsToDocumentXml` is atomic by default. Failed batches return
+  the original document with `rolledBack: true`; pass `atomic: false` to retain
+  partial-result behavior.
+- Missing multi-line targets now return `TARGET_NOT_FOUND` instead of being
+  indistinguishable from a no-op. Stale batch anchors also return
+  `TARGET_NOT_FOUND` instead of falling back to a visibly different paragraph.
+
+### Behavior changes and fixes
+
+- Revision IDs are now allocated per document. Near-limit prior IDs restart in
+  a safe low range, and unrelated bookmark/relationship IDs no longer seed the
+  revision counter.
+- Concurrent calls with explicit authors keep their revision attribution
+  isolated from process-global defaults.
+- `existingRevisions: 'accept-all-first'` now preserves the original OOXML when
+  the requested edit is a no-op.
+- Added `existingRevisions: 'accept-all-first-keep-normalized'` for callers that
+  explicitly want accepted existing revisions returned even when no redline is
+  added.
+- Diff output is deterministic by default. Inputs exceeding 262,144 unique
+  tokens return `DIFF_TOKEN_LIMIT` with the original OOXML unchanged instead of
+  risking truncated text; leading whitespace is preserved exactly.
+- Reconstruction preserves structural line breaks and body section-property
+  placement. A target that names only part of a reconstruction range now
+  returns `PARTIAL_TARGET` instead of risking deletion of untargeted content.
+- Paragraph targeting and reconstruction now preserve leading, middle, and
+  trailing `w:tab` elements as literal tab characters instead of omitting or
+  trimming them.
+- Adjacent redline edits now preserve complex-field instructions, begin/
+  separate/end markers, and unchanged cached display results in their original
+  field boundary. Field instructions remain inert and are not evaluated.
+- Added structured XML parse results and result-returning ingestion helpers.
+- Hardened deterministic diff token handling and leading-whitespace fidelity.
+
+### Testing and development
+
+- Expanded the desktop Word differential from 20 to 25 cases, adding structural
+  checks for bookmarks, internal hyperlinks, mixed formatting, content
+  controls, and tables.
+- Expanded the desktop Word differential from 25 to 28 cases with structural
+  tabs and a locked PAGE field, and added tab/field shapes to focused and fuzz
+  regression testing.
+- Expanded the desktop Word differential from 28 to 33 cases with comments,
+  footnotes, endnotes, headers/footers, and an external hyperlink.
+- Extended the deterministic script-only DOCX packager with opt-in related
+  parts, relationship/content-type validation, reusable fixture constructors,
+  and SHA-256 verification that supplied parts remain byte-identical. Runtime
+  library code and dependencies are unchanged.
+- Added validated task, structure, oracle, and manual-review metadata across the
+  33 synthetic and 20 SuperDoc Word cases. `npm run report:word:coverage`
+  produces a deterministic coverage matrix with explicit high-priority gap
+  dispositions, while `npm run review:word:prepare` creates a pending rotating
+  human-review manifest without self-certifying visual results.
+- Added detailed production-function coverage reporting and a checked per-file
+  regression baseline. Five behavior-focused Phase 3 suites exercise numbering
+  collisions/remapping, every reconciliation route, list construction and
+  fallback, patch/format boundaries, table decisions, pipeline modes, and
+  standalone rollback/highlight paths. Production function coverage moved from
+  437/540 to 496/542 and all reachable P0 functions are covered; no runtime
+  behavior or compatibility contract changed.