@ansonlai/docx-redline-js 0.6.2 → 0.7.1

package/AGENTS.md

@@ -21,16 +21,31 @@ specific advanced operation, API, or recovery topic you need.
 
 ## Ordinary document edits
 
-Use one focused extraction and one apply call. With a structured wrapper, use
-its revision-bound target handles. Follow `selection.hint` when a search for
-restorable text yields 0 matches in accepted view. For shell-only work, use a
-UTF-8 operations file or serializer-backed stdin and the explicit agent profile:
+For a literal mechanical edit with known old and new text, try one fail-closed
+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 "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:
 
 ```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
 ```
 
+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
@@ -39,10 +54,13 @@ 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. Follow `error.recovery.action` and `retryPlan`; never retry
-unchanged failed arguments. 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.
+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
+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
@@ -64,7 +82,10 @@ 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.
+`contractVersion`/capabilities they use. The 0.7.0 localized fast path requires
+contract 8 and its localized replacement, speculative apply, and change-summary
+capabilities; the narrow restore shortcut additionally requires
+`restore-shortcuts-v1`.
 
 ## Code map
 

package/CHANGELOG.md

@@ -2,6 +2,64 @@
 
 ## 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
+
+- **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.

package/README.md

@@ -15,9 +15,26 @@ Converts AI-generated or programmatic text/markdown edits into valid Office Open
 - Comment management: delete comments by author or for all authors
 - Highlights: apply highlight colors to runs
 - Markdown and OOXML conversion in both directions
-- Status/error result fields for parse, targeting, and existing-revision failures
-- 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
+- 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
+- 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. 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
+`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).
 ## Documentation Index
 
 | Document | Description |
@@ -151,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.
@@ -215,9 +239,23 @@ benchmark explicitly does not claim to measure LLM reasoning or provider/tool
 latency. Checked comparative results are in the
 [agent protocol rollout audit](./docs/validation-reports/2026-09-12-agent-protocol-rollout.md).
 
+> **Pre-1.0 integration warning:** Agent skills, MCP servers, and harnesses
+> should pin the exact `@ansonlai/docx-redline-js` release they were tested
+> against and declare the CLI contract version/capabilities they require. Do
+> not treat a newly installed release or contract as verified until the
+> integration's compatibility tests pass. See the
+> [skill-authoring contract](./docs/SKILL_AUTHORING.md#runtime-negotiation).
+
 ### 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 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
 docx-redline preflight contract.docx --operations operations.json --author "Editor"
 docx-redline apply contract.docx --operations operations.json --author "Editor" --output reviewed.docx
@@ -252,6 +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 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
@@ -266,12 +305,15 @@ marker. Machine `index` and `ref` fields are for targeting and pagination, not
 user-facing Word locations; use `humanReference`, `provision`, or
 `nearestHeading` in reports.
 
-`docx-redline version` reports contract version 7 and the additive
+`docx-redline version` reports contract version 8 and the additive
 `command-help-v1`, `inspection-context-v1`, `bounded-inspection-v1`,
 `human-document-references-v1`, `batch-start-source-binding`,
 `recovery-envelope-v1`, `require-complete-exit`, `operations-stdin`,
 `agent-safety-profile-v2`, `deduplicated-cli-receipts`, and
-`compact-cli-json-v1` capabilities. Wrappers should negotiate only the
+`compact-cli-json-v1`, `localized-replacements-v1`,
+`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.6.2 — 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)) {