bun-docx 0.20.0 → 0.20.1

package/README.md

@@ -18,7 +18,7 @@ We measured it — a controlled A/B bake-off: **six real document tasks** (fill
 | :------------------------ | ------------------: | --------------------: | --------------: | --------------------: |
 |                           |        **docx-cli** |         default skill |    **docx-cli** |         default skill |
 | Tasks solved (of 6)       |       **4.3** (4–5) |             0.7 (0–1) |   **6.0** (6–6) |             4.0 (4–4) |
-| Rendered correctly (of 6) |                 5.7 |                   3.7 |             6.0 |                   4.7 |
+| Rendered correctly (of 6) |                 6 |                   3.7 |             6.0 |                   4.7 |
 | Outright-broken documents |               **0** |      ~1/run (up to 2) |           **0** |                     0 |
 | Input tokens              |            **2.4M** |           6.1M (2.6×) |        **1.6M** |           3.6M (2.2×) |
 | Wall-clock                |           **924 s** | 1,882 s (2.0× slower) |     **1,175 s** | 2,029 s (1.7× slower) |

package/dist/index.js

@@ -82676,7 +82676,7 @@ async function resolveBlockOrFail(document4, locator) {
     return document4.body.resolveBlock(locator);
   } catch (err) {
     if (err instanceof LocatorResolveError) {
-      return await fail("BLOCK_NOT_FOUND", err.message);
+      return await fail("BLOCK_NOT_FOUND", err.message, STALE_LOCATOR_HINT);
     }
     throw err;
   }
@@ -82726,7 +82726,7 @@ async function resolveBlockRangeOrFail(document4, locator) {
       return await fail("INVALID_LOCATOR", err.message);
     }
     if (err instanceof LocatorResolveError) {
-      return await fail("BLOCK_NOT_FOUND", err.message);
+      return await fail("BLOCK_NOT_FOUND", err.message, STALE_LOCATOR_HINT);
     }
     throw err;
   }
@@ -82735,7 +82735,7 @@ var EXIT2, stdout = async (text6) => {
   await Bun.stdout.write(text6);
 }, stderr = async (text6) => {
   await Bun.stderr.write(text6);
-}, sinks, verboseAck = false, SAVE_FLAGS;
+}, sinks, verboseAck = false, STALE_LOCATOR_HINT = "Locator ids are positional and shift after structural edits (insert/delete/section changes) \u2014 an id from an earlier read may now point elsewhere or be gone. Re-read the file to get current ids, then retry. Applying several changes? Do them from ONE read with --batch (edit/insert/delete/replace/comments) so ids never go stale mid-run.", SAVE_FLAGS;
 var init_respond = __esm(() => {
   init_core2();
   EXIT2 = {
@@ -86241,9 +86241,12 @@ General options:
   -h, --help        Show this help
 
 Output:
-  Prints a one-line confirmation on success (exit 0) \u2014 the edited locator is unchanged, so there's
-  nothing to mint. --verbose prints {ok:true, operation, path, locator}.
-  Errors print {code, error, hint?} with a nonzero exit. Discover ids with
+  Prints a one-line confirmation on success (exit 0) \u2014 an in-place edit shifts nothing, so the
+  edited locator is unchanged and there's nothing to mint. --verbose prints {ok:true, operation,
+  path, locator}. Errors print {code, error, hint?} with a nonzero exit.
+  Heads up: a locator you hold from BEFORE a structural edit (an insert/delete elsewhere renumbers
+  ids) is stale \u2014 it lands on the wrong block or errors BLOCK_NOT_FOUND. Re-read after any
+  insert/delete, or apply the whole set from one read with --batch (above). Discover ids with
   \`docx read FILE --ast\` (equation ids appear on EquationRun nodes).
 
 Examples:
@@ -98014,7 +98017,7 @@ Examples:
 // package.json
 var package_default = {
   name: "bun-docx",
-  version: "0.20.0",
+  version: "0.20.1",
   description: "Read, edit, redline, and comment on Microsoft Word .docx files from the command line \u2014 built for AI agents.",
   keywords: [
     "docx",
@@ -98137,11 +98140,13 @@ Commands (each one-liner names capabilities you'd otherwise miss; see <command>
 It is highly recommended to run "docx info locators" and "docx info schema" (neither needs a FILE) to understand the addressing model and AST.
 Run "docx <command> --help" for command-specific help.
 
-BATCH MANY CHANGES IN ONE READ: filling a form or applying many edits? Don't go
-one-at-a-time \u2014 edit / insert / replace / delete and comments (add/resolve/delete)
-all take --batch FILE.jsonl (one JSON change per line; "-" reads stdin). Every locator
-addresses the document AS READ, so ids stay valid across the whole batch \u2014 one
-read, one write, no re-reading between changes. See "<command> --help".
+BATCH MANY CHANGES IN ONE READ: locator ids are positional and shift after structural
+edits (insert/delete/section changes), so going one-at-a-time forces a re-read to refresh
+ids after each. Miss the change and the next command lands on the wrong block or errors
+BLOCK_NOT_FOUND. Skip all that: edit / insert / replace / delete and comments
+(add/resolve/delete) all take --batch FILE.jsonl (one JSON change per line; "-" reads
+stdin). Every locator addresses the document AS READ, so ids stay valid across the whole
+batch \u2014 one read, one write, no re-reading between changes. See "<command> --help".
 
 FILL FORMATTED / TABBED LINES WITHOUT REBUILDING RUNS: to fill a template line that
 carries formatting (bold/font) or tab stops \u2014 e.g. "**Org Name**\u21E5Date" \u2014 replace just

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bun-docx",
-	"version": "0.20.0",
+	"version": "0.20.1",
 	"description": "Read, edit, redline, and comment on Microsoft Word .docx files from the command line — built for AI agents.",
 	"keywords": [
 		"docx",