@ansonlai/docx-redline-js 0.7.0 → 0.7.2

package/AGENTS.md

@@ -21,43 +21,39 @@ 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:
-
-```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
-```
-
-For semantic drafting, inspect once and apply once. With a structured wrapper,
-use revision-bound handles. For shell-only work, use serializer-backed stdin:
+Use one focused extraction and one apply call. With a structured wrapper, use
+its revision-bound target handles. For shell-only work, use serializer-backed
+stdin and the explicit agent profile:
 
 ```bash
 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
 ```
 
-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
-batch-start document, so do not manually sort around structural edits.
-Consolidate incompatible writes to the same source; use captures for intentional
-created-content dependencies.
+Retain inspected `exactText` for drafting and target with its compact
+`paragraphId` plus `fingerprint`. Use complete `modified` text for a broad
+semantic revision; for a small literal change, use `replacements` so the apply
+payload need not repeat the whole paragraph. Independent strong targets bind to the batch start, so do
+not manually sort around structural edits. Consolidate incompatible writes to
+one source; use captures only for intentional created-content dependencies.
+
+If the user requests restoration, search `--view rejected` directly. Otherwise
+follow `selection.hint` if extraction identifies an alternate revision view.
+Restore only the inspected strong target; do not infer adjacent content.
 
-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
+Require `completion: true` and a non-null output path. 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
-source is never overwritten unless `--in-place` is explicit.
+Do not accept/reject another reviewer's work or remove comments without explicit
+user authorization. The source is never overwritten unless `--in-place` is
+explicit.
 
 The agent profile preserves progressive execution and the ordinary revision
 policy. Add `--atomic` or `--existing-revisions slice-cross-author` only when
 that policy is intended, and confirm the resolved `effectiveOptions`.
 
-Advanced restore, rejected-view insertion, list, table, formatting, comments,
-revision policies, and failure examples live in the
+Speculative apply, directional search ranges, advanced restore, rejected-view
+insertion, list, table, formatting, comments, revision policies, and failure
+examples live in the
 [knowledge base](docs/AGENT_KNOWLEDGE_BASE.md#agent-document-workflow-cli) and
 [operation schema](docs/schemas/document-operations.schema.json).
 
@@ -72,9 +68,8 @@ targeting, revision allocation, comments, numbering, validation, or rollback.
 The stateful wrapper in `examples/agent-session-wrapper.mjs` is a testable
 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.
+`contractVersion` and capabilities they actually use. Optional capabilities do
+not belong in an ordinary editing prompt merely because the CLI supports them.
 
 ## Code map
 

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+- 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
@@ -14,7 +32,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

@@ -16,17 +16,16 @@ Converts AI-generated or programmatic text/markdown edits into valid Office Open
 - Highlights: apply highlight colors to runs
 - Markdown and OOXML conversion in both directions
 - Status/error result fields for parse, targeting, and existing-revision failures
-- Localized exact replacements and fail-closed one-turn CLI edits with verified before/after evidence
+- Localized exact replacements against inspected targets, plus optional fail-closed speculative CLI edits
 - 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 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`.
+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
@@ -167,6 +166,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.
@@ -241,18 +247,10 @@ latency. Checked comparative results are in the
 ### Agent CLI
 
 ```bash
-# 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
-
-# Semantic drafting still starts with focused context
+# Default agent workflow: inspect once, then apply once
 docx-redline extract contract.docx --search "termination" --around 3
-docx-redline preflight contract.docx --operations operations.json --author "Editor"
-docx-redline apply contract.docx --operations operations.json --author "Editor" --output reviewed.docx
-docx-redline validate reviewed.docx
-```
+node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --compact --output reviewed.docx
+```
 
 ```bash
 # Inline one-liner edit (no operations file needed)
@@ -267,9 +265,9 @@ docx-redline apply contract.docx --target "Another author's clause" --modified "
 # High-assurance atomic batch with nonzero exit on any incomplete result
 docx-redline apply contract.docx --operations operations.json --atomic --require-complete --output reviewed.docx
 
-# Agent shell path: JSON is emitted by a serializer, not interpolated by the shell
-node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --compact --output reviewed.docx
-```
+# Optional read-only audit before a deliberately staged batch
+docx-redline preflight contract.docx --operations operations.json --author "Editor"
+```
 
 All commands emit JSON on stdout. `apply` defaults:
 - **Author**: Defaults to `'AI Redliner'` (or `DOCX_REDLINE_AUTHOR` environment variable).
@@ -282,7 +280,8 @@ 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**: After extraction, use `replacements` with the inspected `paragraphId` plus `fingerprint` to avoid restating a long paragraph. Retain `exactText` locally for drafting. Targetless `--find`/`--replace` is an optional speculative path described below.
+- **Invisible spaces**: Localized matching is case-sensitive and tries exact text first. If no exact span exists, ordinary spaces may match DOCX non-breaking spaces; ambiguous equivalent matches still fail closed, and `change.replacements[i].matchMode` reports `space_equivalent` when used.
 - **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,10 +302,32 @@ 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`, plus `localized-space-equivalence-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.
+
+#### Optional speculative CLI path
+
+Harnesses with a measured confidence policy may attempt a targetless localized
+edit. This is not the default agent workflow:
+
+```bash
+# Globally unique literal
+docx-redline apply contract.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+
+# Optional directional scope using a longer, fairly unique nearby phrase
+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 can widen the unioned scope until multiple
+paragraphs contain `find`, causing a safe `AMBIGUOUS_TARGET` failure and a
+recovery turn. `--around 3` is symmetric. On success,
+`change.context.anchorMatchCount > 1` signals a repeated anchor; confirm the
+returned location and bounded evidence. Matching remains case-sensitive and
+exact-first, with a narrow ordinary-space/NBSP fallback that still refuses
+ambiguity.
 
 See the [compact agent fast start](./docs/AGENT_FAST_START.md), the
 [skill/harness authoring contract](./docs/SKILL_AUTHORING.md), and the

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.2 — 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)) {