@ansonlai/docx-redline-js 0.7.0 → 0.7.1

package/AGENTS.md

@@ -22,13 +22,18 @@ specific advanced operation, API, or recovery topic you need.
 ## Ordinary document edits
 
 For a literal mechanical edit with known old and new text, try one fail-closed
-apply call. Use a visible heading plus a directional range when global matching
-is too broad:
+apply call. When global matching is too broad, use a longer, fairly unique
+nearby phrase plus a directional range:
 
 ```bash
-docx-redline apply contract.docx --search "Section 4.1" --context-range 1:3 --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+docx-redline apply contract.docx --search "distinctive nearby heading or phrase" --context-range 1:3 --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
 ```
 
+Generic or repeated anchors widen the unioned scope and may return
+`AMBIGUOUS_TARGET`, costing a recovery turn. On success, treat
+`results[i].change.context.anchorMatchCount > 1` as a signal to confirm the
+returned location and excerpts.
+
 For semantic drafting, inspect once and apply once. With a structured wrapper,
 use revision-bound handles. For shell-only work, use serializer-backed stdin:
 
@@ -37,6 +42,10 @@ docx-redline extract contract.docx --search "termination" --around 3
 node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --compact --output reviewed.docx
 ```
 
+A single deleted paragraph found in rejected view can be restored verbatim with
+`apply --restore --target-id ID`; add one `--find`/`--replace` pair for a small
+exact correction. This shortcut does not infer ranges or companion paragraphs.
+
 For every ordinary text operation, `modified` is the complete desired
 accepted-view content. Copy inspected `exactText` verbatim and include
 `paragraphId` or `fingerprint`. Independent strong targets are bound against the
@@ -45,8 +54,9 @@ Consolidate incompatible writes to the same source; use captures for intentional
 created-content dependencies.
 
 Require `completion: true`, `written: true`, a non-null output path, and no
-per-operation errors. Localized edits also require `change.committed: true` and
-`change.verification.acceptedViewMatchesCompiledText: true`. Follow
+per-operation errors. Localized edits also require
+`results[i].change.committed: true`, `finalDisposition: "applied"`, and
+`verification.acceptedViewMatchesCompiledText: true`. Follow
 `error.recovery.action` and `retryPlan`; never retry unchanged failed arguments.
 Follow `selection.hint` for restorable text. Do not accept/reject another
 reviewer's work or remove comments without explicit user authorization. The
@@ -74,7 +84,8 @@ development demonstration only. It is excluded from package files and exports.
 Production harnesses own their transport and negotiate the minimum CLI
 `contractVersion`/capabilities they use. The 0.7.0 localized fast path requires
 contract 8 and its localized replacement, speculative apply, and change-summary
-capabilities.
+capabilities; the narrow restore shortcut additionally requires
+`restore-shortcuts-v1`.
 
 ## Code map
 

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+- 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
@@ -14,7 +27,9 @@
 - **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
-  multi-paragraph provisions; `--around N` is symmetric shorthand.
+  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

package/README.md

@@ -25,8 +25,9 @@ Converts AI-generated or programmatic text/markdown edits into valid Office Open
 Version 0.7.0 adds a contract-8 fast path for exact mechanical edits. Agents can
 send a small `find`/`replace` request instead of reproducing a complete legal
 paragraph, and may omit a strong target when the source literal resolves to one
-accepted-view paragraph. Visible headings can narrow the attempt with a signed
-directional window such as `--search "Section 4.1" --context-range 1:3`.
+accepted-view paragraph. A longer, fairly unique nearby phrase can narrow the
+attempt with a signed directional window. Generic or repeated anchors widen the
+unioned scope and may cause a safe ambiguity failure and another tool turn.
 
 Speculative edits fail without writing when the anchor, paragraph, or source
 span is missing or ambiguous. Successful localized results include a committed
@@ -167,6 +168,13 @@ limit output. Search is a case-insensitive substring match; `around` adds nearby
 context, while `limit` and `after` page direct hits. When a search yields 0
 matches in the active view, `selection.hint` provides guidance if matches exist
 in the alternate revision view (such as searching for deleted text to restore).
+Compact `extract --revised` output retains revision authors and marks paragraphs
+whose content is wholly hidden in the selected view as `deleted` or `inserted`.
+One such paragraph can be restored without restating it:
+`docx-redline apply input.docx --restore --target-id ID --output reviewed.docx`.
+Add one exact `--find`/`--replace` pair to make a localized correction while
+restoring. The shortcut requires a strong rejected-view paragraph ID and does
+not infer a range or adjacent content.
 `revisionView` accepts `accepted`, `rejected`, or `current`. Returned
 paragraphs identify matches versus context and include `humanReference` for
 user-facing summaries.
@@ -244,8 +252,8 @@ latency. Checked comparative results are in the
 # One-turn exact mechanical edit; fails closed unless one paragraph matches
 docx-redline apply contract.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
 
-# Directional context after a visible heading; repeated cross-references are safe
-docx-redline apply contract.docx --search "Section 4.1" --context-range 1:3 --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+# Directional context using a longer phrase with a higher chance of uniqueness
+docx-redline apply contract.docx --search "distinctive nearby heading or phrase" --context-range 1:3 --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
 
 # Semantic drafting still starts with focused context
 docx-redline extract contract.docx --search "termination" --around 3
@@ -282,7 +290,7 @@ All commands emit JSON on stdout. `apply` defaults:
 - **Compact stdout**: `--compact` emits one-line mutation JSON. It changes serialization only, not operation semantics.
 - **Tracked changes**: Defaults to `generateRedlines: true`. Pass `--no-redlines` when clean direct text edits are desired.
 - **Inline edits**: Use `--target <text>` with `--modified <text>` or `--comment <text>` for quick one-liners without creating a JSON file.
-- **Localized edits**: Use `--find`/`--replace` with a known strong target, or omit the target for fail-closed global resolution. Add `--search` with `--context-range 1:3` for text strictly after a visible heading; `--around 3` is symmetric. Successful localized results include bounded before/after excerpts and post-mutation accepted-view verification in `results[i].change`.
+- **Localized edits**: Use `--find`/`--replace` with a known strong target, or omit the target for fail-closed global resolution. Add a longer, fairly unique `--search` phrase with `--context-range 1:3` for directional scope; `--around 3` is symmetric. Generic or repeated anchors can widen the unioned scope until multiple paragraphs contain `find`, producing a safe `AMBIGUOUS_TARGET` failure and an extra recovery turn. On success, `results[i].change.context.anchorMatchCount > 1` signals a non-unique anchor; confirm the returned location and bounded before/after evidence.
 - **Compact mutation results**: `apply`, `accept`, `reject`, and `delete-comments` omit full OOXML/package payloads and inspection text from stdout. CLI operation results omit duplicate nested receipt bodies; the ordered top-level `receipts` array is authoritative. Successful exact target-match diagnostics are omitted and equivalent-whitespace matches retain only mode/count. Node and standalone-runner results remain unchanged. Use `validate` when full issue arrays are needed.
 
 Inspection commands default to 20 direct matches and a 48 KiB soft response
@@ -303,7 +311,8 @@ user-facing Word locations; use `humanReference`, `provision`, or
 `recovery-envelope-v1`, `require-complete-exit`, `operations-stdin`,
 `agent-safety-profile-v2`, `deduplicated-cli-receipts`, and
 `compact-cli-json-v1`, `localized-replacements-v1`,
-`speculative-search-apply-v1`, and `localized-change-summary-v1` capabilities.
+`speculative-search-apply-v1`, `localized-change-summary-v1`, and
+`restore-shortcuts-v1` capabilities.
 Wrappers should negotiate only the
 capabilities they use. Run `docx-redline <command> --help` for that command's
 machine-readable options, behavior, exit codes, canonical GitHub documentation links, and compact examples.

package/dist/docx-redline-js.esm.js

@@ -1,4 +1,4 @@
-// @ansonlai/docx-redline-js v0.7.0 — https://github.com/AnsonLai/docx-redline-js
+// @ansonlai/docx-redline-js v0.7.1 — https://github.com/AnsonLai/docx-redline-js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -11609,9 +11609,8 @@ function inspectDocumentParts(parts, options = {}) {
       if (options.range && (index < rangeStart || index > rangeEnd)) continue;
       if (Array.isArray(options.indexes) && !options.indexes.includes(index)) continue;
       const pNode = paragraphNodes[i];
-      if (options.table && !hasAncestor(pNode, "tc")) continue;
-      if (options.body && hasAncestor(pNode, "tc")) continue;
-      if (options.revised && revisionAuthors(pNode).length === 0) continue;
+      if (options.inTable != null && hasAncestor(pNode, "tc") !== !!options.inTable) continue;
+      if (options.revisedOnly && revisionAuthors(pNode).length === 0) continue;
       const altText = extractCanonicalParagraphText(pNode, { revisionView: alternateView });
       if (options.skipEmpty && altText.length === 0) continue;
       if (altText.toLowerCase().includes(needle)) {