@ansonlai/docx-redline-js 0.8.2 → 0.8.4

package/CHANGELOG.md

@@ -1,6 +1,80 @@
 # Changelog
 
-## Unreleased
+## 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
 

package/README.md

@@ -20,19 +20,34 @@ Converts AI-generated or programmatic text/markdown edits into valid Office Open
 - Package plumbing helpers for numbering.xml, comments.xml, content types, and relationships
 - Zero host dependencies: works in Node.js, browsers, Deno, and similar JS runtimes with DOM parsing support
 
-## What's New in 0.7.0
-
-Version 0.7.0 adds contract-8 localized edits. Agents can send a small
-`find`/`replace` request against an inspected target instead of reproducing a
-complete paragraph. An optional speculative form may omit the strong target
-when the source literal resolves uniquely; advanced scoping is described below.
-
-Speculative edits fail without writing when the anchor, paragraph, or source
-span is missing or ambiguous. Successful localized results include a committed
-`change` object with the selected legal location, bounded before/after excerpts,
-and actual accepted-view verification. Existing full-paragraph operations,
-tracked-change semantics, validation, rollback, and review policies remain
-available unchanged. See the [complete 0.7.0 release notes](./docs/releases/0.7.0.md).
+## What's New in 0.8.x
+
+The current release is 0.8.4. The CLI contract remains version 8 throughout the 0.8 line.
+
+- **0.8.0, universal document facade:** `openDocx` and `DocxDocument` are exported from the primary entry point and work
+  on `Uint8Array` input in any JavaScript runtime. ZIP handling uses `fflate` and SHA-256 is pure JavaScript, so there are no
+  Node built-in dependencies. The XML provider falls back to `@xmldom/xmldom` automatically, and the
+  `@ansonlai/docx-redline-js/bundle` export provides zero-dependency single-file bundles for sandboxes such as n8n Code
+  nodes. The `/node` entry point keeps its existing API. See the [0.8.0 release notes](./docs/releases/0.8.0.md).
+- **0.8.1, headers, footers and comment threads:** an operation's `part` field edits headers and footers;
+  `inspect().headersFooters` lists them. Comment threads can be resolved or reopened with `doc.resolveComment` or the
+  `comment_resolve` operation, and comments can be deleted by id with `doc.deleteComments({ ids })` or
+  `docx-redline delete-comments --comment-id`. See the [0.8.1 release notes](./docs/releases/0.8.1.md).
+- **0.8.2, fixes:** a replacement beside a hyperlink no longer pulls adjacent plain text into the link, and Reject All no
+  longer reorders text around a manual line break. See the [0.8.2 release notes](./docs/releases/0.8.2.md).
+- **0.8.3, list fixes:** Reject All now restores list edits exactly (no extra empty paragraph after an inserted
+  paragraph, no merged source paragraphs after a list-range replacement, original list numbering kept through `openDocx`),
+  and inspection no longer reports tracked historical list, style or heading properties as current. See the
+  [0.8.3 release notes](./docs/releases/0.8.3.md).
+- **0.8.4, fixes:** localized replacements and list conversion work in paragraphs with soft line breaks, generated
+  bullets get their own numbering IDs, `format` accepts `textOccurrence` to format a later match, and tracked tables use
+  Word's row-level markup, so Word's Reject All removes them and an appended table keeps the paragraph's formatting. See
+  the [0.8.4 release notes](./docs/releases/0.8.4.md).
+
+Version 0.7.0 introduced contract-8 localized edits: a small `find`/`replace` request against an inspected target instead
+of a complete paragraph, plus an optional speculative form that fails without writing when the anchor is missing or
+ambiguous. They remain available unchanged; see the [0.7.0 release notes](./docs/releases/0.7.0.md).
+
 ## Documentation Index
 
 | Document | Description |

package/core/list-targeting.js

@@ -9,12 +9,13 @@ import {
 } from './paragraph-targeting.js';
 import { parseListItem, stripListMarker } from '../pipeline/list-markers.js';
 
-function getFirstDescendantByLocalName(node, localName) {
-    if (!node || typeof node.getElementsByTagNameNS !== 'function') return null;
-    const namespaced = node.getElementsByTagNameNS(WORD_MAIN_NS, localName);
-    if (namespaced.length > 0) return namespaced[0];
-    const anyNs = node.getElementsByTagNameNS('*', localName);
-    return anyNs.length > 0 ? anyNs[0] : null;
+/** Direct element child by local name; never crosses w:pPrChange / w:rPrChange boundaries. */
+function getDirectChildByLocalName(node, localName) {
+    if (!node) return null;
+    for (const child of Array.from(node.childNodes || [])) {
+        if (child?.nodeType === 1 && child.localName === localName) return child;
+    }
+    return null;
 }
 
 function readValAttribute(element) {
@@ -178,17 +179,18 @@ function buildListEntriesForInsertion(parsedItems, normalizedTargetText, anchorL
 export function getParagraphListInfo(paragraph) {
     if (!paragraph) return null;
 
-    const pPr = getFirstDescendantByLocalName(paragraph, 'pPr');
+    // Current properties only: direct w:pPr/w:numPr, never historical w:pPrChange/w:pPr.
+    const pPr = getDirectChildByLocalName(paragraph, 'pPr');
     if (!pPr) return null;
-    const numPr = getFirstDescendantByLocalName(pPr, 'numPr');
+    const numPr = getDirectChildByLocalName(pPr, 'numPr');
     if (!numPr) return null;
-    const numIdEl = getFirstDescendantByLocalName(numPr, 'numId');
+    const numIdEl = getDirectChildByLocalName(numPr, 'numId');
     if (!numIdEl) return null;
 
     const numId = readValAttribute(numIdEl);
     if (!numId || numId === '0') return null;
 
-    const ilvlEl = getFirstDescendantByLocalName(numPr, 'ilvl');
+    const ilvlEl = getDirectChildByLocalName(numPr, 'ilvl');
     const ilvlRaw = readValAttribute(ilvlEl);
     const ilvl = Number.parseInt(ilvlRaw || '0', 10);