bun-docx 0.16.0 → 0.17.0

package/README.md

@@ -184,17 +184,19 @@ docx edit   FILE --at LOCATOR <content>                   # LOCATOR = pN | pN:S-
 docx delete FILE --at LOCATOR                             # LOCATOR = pN | pN-pM | tN | sN | tN:rRcC:pK (cell paragraph)
 docx sections FILE [--at LOCATOR] [--columns N] [--type T] [--orientation O] [--size SIZE] [--margins M]   # LOCATOR = pN-pM | pN (wrap a range in N columns) | sN (edit one section's columns/type/page geometry). Multi-column layout AND page setup live HERE. PAGE GEOMETRY (margins/orientation/size) with NO --at applies to the WHOLE document (every section); --at sN targets one. Columns/type need --at.
 docx styles set-default-font FILE "Font Name" [--size N] [--all]   # document-wide font: sets styles.xml docDefaults + theme major/minor; --all also repoints styles/runs that pin their own font
-docx replace FILE PATTERN REPLACEMENT [--regex] [--ignore-case] [--all] [--limit N] [--current | --baseline] [--exact] [--track] [--dry-run]
+docx replace FILE PATTERN REPLACEMENT [--at pN] [--regex] [--ignore-case] [--all] [--limit N] [--current | --baseline] [--exact] [--track] [--dry-run]
 #   Keeps the run's formatting (bold/font) and any tabs — the no-rebuild way to fill a
 #   formatted/tabbed template line (e.g. "**Org Name**⇥Date"); don't hand-build --runs to refill it.
-#   A span edit (find → edit --at pN:S-E --text NEW) does the same by locator.
+#   --at pN (or a cell paragraph tT:rRcC:pN) CONFINES the replace to one paragraph — use it when the
+#   SAME placeholder repeats across the doc (a résumé's "City, State" in every entry) and you want THE
+#   one in a specific paragraph, instead of find → edit --at pN:S-E span surgery. Batch entries take "at" too.
 
 # Batch — apply many changes from ONE read (no re-reading between edits). Keys
 # on each JSONL line mirror the command's flags; all locators address the doc as
 # read. insert/edit also accept --batch - to read JSONL from stdin.
 docx edit    FILE --batch fills.jsonl       # { at, <one of: text|clear|markdown|runs|code|task>, style?, … }
 docx insert  FILE --batch additions.jsonl   # { after|before, <content>, style?, color?, … }
-docx replace FILE --batch script.jsonl      # { pattern, replacement, regex?, all?, limit?, … } applied in order
+docx replace FILE --batch script.jsonl      # { pattern, replacement, at?, regex?, all?, limit?, … } applied in order ("at" scopes that entry to one paragraph)
 docx delete  FILE --batch drop.jsonl        # { at } per line — whole blocks (pN/tN/cell), resolved live-first
 
 # All four of insert/edit/delete/replace accept --track to record that one
@@ -283,14 +285,22 @@ docx tables unmerge       FILE --at tN:rRcC
 docx tables borders       FILE --at tN [--style single|double|none] [--size N] [--color HEX]
 
 docx track-changes on|off FILE
+docx track-changes list   FILE [--json]
 docx track-changes accept FILE (--at tcN [--at tcM ...] | --at revN | --all)
 docx track-changes reject FILE (--at tcN [--at tcM ...] | --at revN | --all)
-# A del+ins REPLACE pair shares a "group": "revN" in `list`; `--at revN` accepts/rejects
-# both halves in one call (no re-list between them — tcN ids renumber after each accept).
+docx track-changes apply  FILE [--accept H ...] [--reject H ...]
+# `list` defaults to a text table, one LOGICAL change per line (revN collapses a del+ins
+# pair onto one line); `--json` for the raw array. A del+ins REPLACE pair shares a
+# "group": "revN"; `--at revN` accepts/rejects both halves in one call.
+# To FINALIZE a review (accept some, reject the rest), use `apply` — it takes both decision
+# lists in ONE call, resolved against the original ids, so nothing renumbers mid-operation
+# and the file is never left half-finalized. Doing it as separate accept then reject calls
+# renumbers the ids between them. After a subset accept/reject/apply, the confirmation
+# re-lists what remains with its renumbered handles.
 ```
 
 > **One rule to memorize: addressing an existing thing is always `--at`.**
-> `comments reply/resolve/delete`, `footnotes/endnotes edit/delete`, `images extract/replace/delete`, `hyperlinks replace/delete`, `tables *`, `track-changes accept/reject`, `edit`, and `delete` all take `--at LOCATOR`. The exceptions are positional or directional by nature: `insert` uses `--after`/`--before LOCATOR` (or `--at-start`/`--at-end` for the document boundaries, no locator); `read` slices with `--from`/`--to LOCATOR`; `wc` takes a positional `[LOCATOR]`; `find`/`replace` take a positional `QUERY`/`PATTERN`. `images extract --to DIR` is an *output directory*, not a locator.
+> `comments reply/resolve/delete`, `footnotes/endnotes edit/delete`, `images extract/replace/delete`, `hyperlinks replace/delete`, `tables *`, `track-changes accept/reject`, `edit`, and `delete` all take `--at LOCATOR`. The exceptions are positional or directional by nature: `insert` uses `--after`/`--before LOCATOR` (or `--at-start`/`--at-end` for the document boundaries, no locator); `read` slices with `--from`/`--to LOCATOR`; `wc` takes a positional `[LOCATOR]`; `find`/`replace` take a positional `QUERY`/`PATTERN` (and `replace` accepts an optional `--at pN` to *confine* the substitution to one paragraph). `images extract --to DIR` is an *output directory*, not a locator.
 
 ## Output contract
 

package/dist/index.js

@@ -18088,9 +18088,25 @@ function previewTrackedChanges(document2, target, verb) {
 }
 function applyTrackedChanges(document2, target, verb) {
   const targets = resolveTargets(document2, target);
-  const records = targets.map((found) => recordFor(found, verb));
-  const affectedNotes = collectAffectedNotes(targets);
-  for (const found of [...targets].reverse()) {
+  return applyResolvedTargets(document2, targets.map((found) => ({ found, verb })));
+}
+function applyTrackedDecisions(document2, accepts, rejects) {
+  const acceptTargets = resolveTargets(document2, accepts).map((found) => ({
+    found,
+    verb: "accept"
+  }));
+  const rejectTargets = resolveTargets(document2, rejects).map((found) => ({
+    found,
+    verb: "reject"
+  }));
+  return applyResolvedTargets(document2, [...acceptTargets, ...rejectTargets]);
+}
+function applyResolvedTargets(document2, decisions) {
+  const order = collectTrackedChanges(document2);
+  const sorted = [...decisions].sort((left, right) => indexOfFound(order, left.found) - indexOfFound(order, right.found));
+  const records = sorted.map(({ found, verb }) => recordFor(found, verb));
+  const affectedNotes = collectAffectedNotes(sorted.map(({ found }) => found));
+  for (const { found, verb } of [...sorted].reverse()) {
     if (verb === "accept")
       applyAccept(found);
     else
@@ -18100,6 +18116,9 @@ function applyTrackedChanges(document2, target, verb) {
   applyNotePairing(document2, affectedNotes);
   return records;
 }
+function indexOfFound(inventory, found) {
+  return inventory.findIndex((change) => change.node === found.node);
+}
 function resolveTargets(document2, target) {
   const allChanges = collectTrackedChanges(document2);
   if (target === "all")
@@ -18602,6 +18621,9 @@ class TrackChanges {
   reject(target) {
     return applyTrackedChanges(this.document, target, "reject");
   }
+  apply(accepts, rejects) {
+    return applyTrackedDecisions(this.document, accepts, rejects);
+  }
   applyInsertion(paragraph, authorFlag, allocator) {
     const mintMeta = this.metaMinter(authorFlag, allocator);
     paragraph.children = wrapContiguousTrackable(paragraph.children, (runs) => /* @__PURE__ */ jsxDEV(Ins, {
@@ -33807,6 +33829,13 @@ function NormalStyle() {
     ]
   }, undefined, true, undefined, this);
 }
+function HeadingThemeFonts() {
+  return /* @__PURE__ */ jsxDEV(w.rFonts, {
+    "w-asciiTheme": "majorHAnsi",
+    "w-hAnsiTheme": "majorHAnsi",
+    "w-cstheme": "majorBidi"
+  }, undefined, false, undefined, this);
+}
 function TitleStyle() {
   return /* @__PURE__ */ jsxDEV(w.style, {
     "w-type": "paragraph",
@@ -33829,10 +33858,7 @@ function TitleStyle() {
       }, undefined, false, undefined, this),
       /* @__PURE__ */ jsxDEV(w.rPr, {
         children: [
-          /* @__PURE__ */ jsxDEV(w.rFonts, {
-            "w-ascii": "Calibri Light",
-            "w-hAnsi": "Calibri Light"
-          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV(HeadingThemeFonts, {}, undefined, false, undefined, this),
           /* @__PURE__ */ jsxDEV(w.color, {
             "w-val": "1F3864"
           }, undefined, false, undefined, this),
@@ -33866,10 +33892,7 @@ function SubtitleStyle() {
       }, undefined, false, undefined, this),
       /* @__PURE__ */ jsxDEV(w.rPr, {
         children: [
-          /* @__PURE__ */ jsxDEV(w.rFonts, {
-            "w-ascii": "Calibri Light",
-            "w-hAnsi": "Calibri Light"
-          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV(HeadingThemeFonts, {}, undefined, false, undefined, this),
           /* @__PURE__ */ jsxDEV(w.color, {
             "w-val": "5A5A5A"
           }, undefined, false, undefined, this),
@@ -33919,10 +33942,7 @@ function HeadingStyle({
       }, undefined, true, undefined, this),
       /* @__PURE__ */ jsxDEV(w.rPr, {
         children: [
-          /* @__PURE__ */ jsxDEV(w.rFonts, {
-            "w-ascii": "Calibri Light",
-            "w-hAnsi": "Calibri Light"
-          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV(HeadingThemeFonts, {}, undefined, false, undefined, this),
           bold2 && /* @__PURE__ */ jsxDEV(w.b, {}, undefined, false, undefined, this),
           italic && /* @__PURE__ */ jsxDEV(w.i, {}, undefined, false, undefined, this),
           color && /* @__PURE__ */ jsxDEV(w.color, {
@@ -90938,8 +90958,7 @@ function computeSectionStarts(blocks) {
       continue;
     const entry = {
       block: blocks[index2],
-      breakIndex: index2,
-      isTrailing: index2 === blocks.length - 1
+      breakIndex: index2
     };
     const group = starts.get(sectionStart) ?? [];
     group.push(entry);
@@ -90949,12 +90968,7 @@ function computeSectionStarts(blocks) {
   return starts;
 }
 function renderSectionStart(entry, blocks, ctx) {
-  const marginalLines = ctx.marginalsBySection.get(entry.block.id);
-  if (entry.isTrailing) {
-    return marginalLines && marginalLines.length > 0 ? marginalLines.join(`
-`) : null;
-  }
-  return renderSectionBreak(entry.block, governedRange(blocks, entry.breakIndex), marginalLines);
+  return renderSectionBreak(entry.block, governedRange(blocks, entry.breakIndex), ctx.marginalsBySection.get(entry.block.id));
 }
 function computeGoverningColumns(blocks) {
   const map3 = new Map;
@@ -92148,6 +92162,55 @@ var init_render2 = __esm(() => {
   };
 });
 
+// src/cli/replace/scope.ts
+function validateScopeShape(at) {
+  let parsed;
+  try {
+    parsed = parseLocator(at);
+  } catch (error) {
+    if (error instanceof LocatorParseError) {
+      throw new ScopeError("INVALID_LOCATOR", error.message);
+    }
+    throw error;
+  }
+  if (!isParagraphLocator(parsed)) {
+    throw new ScopeError("INVALID_LOCATOR", `--at scope must be a single paragraph (pN) or cell paragraph (tT:rRcC:pN), got "${at}" \u2014 replace targets text within one paragraph`);
+  }
+  return at;
+}
+function isParagraphLocator(parsed) {
+  if (parsed.kind === "block")
+    return parsed.blockId[0] === "p";
+  let inner2 = parsed;
+  while (inner2?.kind === "cell")
+    inner2 = inner2.inner;
+  return inner2?.kind === "block" && inner2.blockId[0] === "p";
+}
+function resolveReplaceScope(document4, at) {
+  const blockId = validateScopeShape(at);
+  try {
+    document4.body.resolveBlock(at);
+  } catch (error) {
+    throw new ScopeError("BLOCK_NOT_FOUND", error.message);
+  }
+  return blockId;
+}
+function matchesInScope(matches, blockId) {
+  return matches.filter((match) => match.blockId === blockId);
+}
+var ScopeError;
+var init_scope = __esm(() => {
+  init_core2();
+  ScopeError = class ScopeError extends Error {
+    code;
+    constructor(code3, message) {
+      super(message);
+      this.code = code3;
+      this.name = "ScopeError";
+    }
+  };
+});
+
 // src/cli/replace/batch.ts
 async function runReplaceBatch(filePath, batchSource, values2) {
   const authorFlag = values2.author;
@@ -92181,6 +92244,13 @@ async function runReplaceBatch(filePath, batchSource, values2) {
     const spec = specs[index2];
     if (!spec)
       continue;
+    if (spec.at !== undefined) {
+      try {
+        document4.body.resolveBlock(spec.at);
+      } catch {
+        return fail("BLOCK_NOT_FOUND", `entry ${index2}: scope "${spec.at}" not found`);
+      }
+    }
     let findResult;
     try {
       findResult = findTextSpans(document4.body, spec.pattern, {
@@ -92193,7 +92263,7 @@ async function runReplaceBatch(filePath, batchSource, values2) {
       const message = matcherError instanceof Error ? matcherError.message : String(matcherError);
       return fail("USAGE", `entry ${index2}: invalid pattern: ${message}`);
     }
-    const all2 = findResult.matches;
+    const all2 = spec.at !== undefined ? matchesInScope(findResult.matches, spec.at) : findResult.matches;
     const selected = spec.limit !== undefined ? all2.slice(0, spec.limit) : spec.all ? all2 : all2.slice(0, 1);
     const tracked = allocator ? {
       meta: {
@@ -92265,6 +92335,20 @@ function validateSpec(raw, index2) {
     }
     limit = value;
   }
+  let at;
+  if (raw.at !== undefined) {
+    if (typeof raw.at !== "string") {
+      throw new EntryError3("USAGE", `entry ${index2}: "at" must be a string`);
+    }
+    try {
+      at = validateScopeShape(raw.at);
+    } catch (error) {
+      if (error instanceof ScopeError) {
+        throw new EntryError3(error.code, `entry ${index2}: ${error.message}`);
+      }
+      throw error;
+    }
+  }
   return {
     pattern: raw.pattern,
     replacement: raw.replacement,
@@ -92274,7 +92358,8 @@ function validateSpec(raw, index2) {
     all: Boolean(raw.all),
     ...limit !== undefined ? { limit } : {},
     view: wantCurrent ? "current" : wantBaseline ? "baseline" : "accepted",
-    ...typeof raw.author === "string" ? { author: raw.author } : {}
+    ...typeof raw.author === "string" ? { author: raw.author } : {},
+    ...at !== undefined ? { at } : {}
   };
 }
 var EntryError3;
@@ -92283,6 +92368,7 @@ var init_batch4 = __esm(() => {
   init_find();
   init_parse_helpers();
   init_respond();
+  init_scope();
   EntryError3 = class EntryError3 extends Error {
     code;
     hint;
@@ -92303,6 +92389,7 @@ __export(exports_replace3, {
 async function run37(args) {
   const parsed = await tryParseArgs(args, {
     batch: { type: "string" },
+    at: { type: "string" },
     regex: { type: "boolean" },
     "ignore-case": { type: "boolean" },
     all: { type: "boolean" },
@@ -92329,6 +92416,9 @@ async function run37(args) {
     if (parsed.positionals.length > 1) {
       return fail("USAGE", "--batch reads pattern/replacement from the JSONL file; don't also pass them as positionals", HELP33);
     }
+    if (parsed.values.at !== undefined) {
+      return fail("USAGE", '--at is per-entry in batch mode: put "at" on each JSONL line, not on the command', HELP33);
+    }
     return runReplaceBatch(path2, batchInput, parsed.values);
   }
   const pattern = parsed.positionals[1];
@@ -92366,7 +92456,19 @@ async function run37(args) {
     const message = matcherError instanceof Error ? matcherError.message : String(matcherError);
     return fail("USAGE", `Invalid pattern: ${message}`);
   }
-  const allMatches = findResult.matches;
+  const atScope = parsed.values.at;
+  let allMatches = findResult.matches;
+  if (atScope !== undefined) {
+    try {
+      const blockId = resolveReplaceScope(document4, atScope);
+      allMatches = matchesInScope(allMatches, blockId);
+    } catch (scopeError) {
+      if (scopeError instanceof ScopeError) {
+        return fail(scopeError.code, scopeError.message);
+      }
+      throw scopeError;
+    }
+  }
   const normalizationFields = findResult.normalizedQuery !== undefined ? {
     normalizedPattern: findResult.normalizedQuery,
     normalizationApplied: findResult.normalizationApplied
@@ -92397,6 +92499,7 @@ async function run37(args) {
       regex: useRegex,
       ignoreCase,
       view: findView,
+      ...atScope ? { at: atScope } : {},
       totalMatches: allMatches.length,
       replaced: selected.length,
       matches: matchesPayload,
@@ -92415,6 +92518,7 @@ async function run37(args) {
       regex: useRegex,
       ignoreCase,
       view: findView,
+      ...atScope ? { at: atScope } : {},
       totalMatches: 0,
       replaced: 0,
       matches: [],
@@ -92451,6 +92555,7 @@ async function run37(args) {
     regex: useRegex,
     ignoreCase,
     view: findView,
+    ...atScope ? { at: atScope } : {},
     totalMatches: allMatches.length,
     replaced: selected.length,
     matches: matchesPayload,
@@ -92466,9 +92571,16 @@ Usage:
   docx replace FILE --batch -          [options]   # read JSONL from stdin
 
 Options:
+  --at LOCATOR      confine the replace to ONE paragraph: a body pN or a cell
+                    paragraph tT:rRcC:pN. Use this when the same placeholder
+                    repeats across the document (a r\xE9sum\xE9's "City, State" /
+                    "Position Title" in every entry) and you want THE one in a
+                    specific paragraph \u2014 no find + offset-span edit needed:
+                      docx replace doc.docx --at p20 "City, State" "San Francisco, CA"
   --regex           treat PATTERN as a JavaScript regular expression
   --ignore-case     case-insensitive match
-  --all             replace every match (default: just the first)
+  --all             replace every match (default: just the first; with --at,
+                    scoped to that paragraph)
   --limit N         replace at most N matches (in document order)
   --author NAME     author for tracked changes (default: $DOCX_AUTHOR)
   --track           record substitutions as tracked changes even when the
@@ -92539,6 +92651,7 @@ var init_replace4 = __esm(() => {
   init_parse_helpers();
   init_respond();
   init_batch4();
+  init_scope();
 });
 
 // src/cli/sections/index.tsx
@@ -93663,6 +93776,11 @@ theme-following headings adopt the font. Styles/runs that pin their OWN font
 (e.g. a code block's monospace, a deliberately-Arial run) are preserved; pass
 --all to repoint those too.
 
+Theme-following headings only adopt the font if the document HAS a theme part
+(every doc this CLI creates does; Word docs do too). The ack's "themeUpdated"
+is false for the rare theme-less doc \u2014 there the body changes but headings keep
+their fallback font; run with --all to force the headings onto the new font.
+
 Options:
   --size N           Also set the default font size, in points (e.g. 12).
   --all              Repoint EVERY explicit font \u2014 styles, body runs, and notes \u2014
@@ -95232,42 +95350,23 @@ var init_groups = __esm(() => {
   };
 });
 
-// src/cli/track-changes/list.ts
-var exports_list5 = {};
-__export(exports_list5, {
-  run: () => run49
-});
-async function run49(args) {
-  const parsed = await tryParseArgs(args, {
-    help: { type: "boolean", short: "h" }
-  }, HELP45);
-  if (typeof parsed === "number")
-    return parsed;
-  if (parsed.values.help) {
-    await writeStdout(HELP45);
-    return EXIT2.OK;
-  }
-  const path2 = parsed.positionals[0];
-  if (!path2)
-    return fail("USAGE", "Missing FILE argument", HELP45);
-  const document4 = await openOrFail(path2);
-  if (typeof document4 === "number")
-    return document4;
+// src/cli/track-changes/list-view.ts
+function collectTrackedChangeRecords(document4) {
   const byId = new Map;
   for (const paragraph2 of flattenParagraphs(document4.body.blocks)) {
-    for (const run50 of paragraph2.runs) {
-      if (run50.type !== "text" || !run50.trackedChange)
+    for (const run49 of paragraph2.runs) {
+      if (run49.type !== "text" || !run49.trackedChange)
         continue;
-      const change = run50.trackedChange;
+      const change = run49.trackedChange;
       const existing = byId.get(change.id);
       if (existing) {
-        existing.text += run50.text;
+        existing.text += run49.text;
         continue;
       }
       byId.set(change.id, {
         ...change,
         blockId: paragraph2.id,
-        text: run50.text
+        text: run49.text
       });
     }
   }
@@ -95304,8 +95403,154 @@ async function run49(args) {
     if (group)
       record.group = group;
   }
-  await respond(sorted);
-  return EXIT2.OK;
+  return sorted;
+}
+function renderTrackedChangeTable(records) {
+  if (records.length === 0)
+    return `no tracked changes
+`;
+  const byGroup = new Map;
+  for (const record of records) {
+    if (!record.group)
+      continue;
+    const members = byGroup.get(record.group) ?? [];
+    members.push(record);
+    byGroup.set(record.group, members);
+  }
+  const rows = [];
+  const consumed = new Set;
+  for (const record of records) {
+    if (record.group) {
+      if (consumed.has(record.group))
+        continue;
+      consumed.add(record.group);
+      const members = byGroup.get(record.group) ?? [record];
+      const del = members.find((member) => member.kind === "del");
+      const ins = members.find((member) => member.kind === "ins");
+      rows.push({
+        handle: record.group,
+        verb: "replace",
+        block: record.blockId,
+        desc: `${quote(del?.text ?? "")} \u2192 ${quote(ins?.text ?? "")}`
+      });
+      continue;
+    }
+    rows.push({
+      handle: record.id,
+      verb: verbLabel(record.kind),
+      block: record.blockId,
+      desc: describeSolo(record)
+    });
+  }
+  const handleWidth = Math.max(...rows.map((row) => row.handle.length));
+  const verbWidth = Math.max(...rows.map((row) => row.verb.length));
+  const blockWidth = Math.max(...rows.map((row) => row.block.length));
+  const body = rows.map((row) => `  ${row.handle.padEnd(handleWidth)}  ${row.verb.padEnd(verbWidth)}  ${row.block.padEnd(blockWidth)}  ${row.desc}`).join(`
+`);
+  const total = records.length;
+  const header = `${total} tracked change${total === 1 ? "" : "s"}${rows.length === total ? "" : ` (${rows.length} logical)`}:`;
+  const footer = `Address by the leftmost handle: accept/reject --at <handle> (repeatable).
+` + "A revN handle resolves both halves of a replace in one call; --json for full detail.";
+  return `${header}
+
+${body}
+
+${footer}
+`;
+}
+async function remainingTrackedChangesBlock(path2, verb) {
+  let document4;
+  try {
+    document4 = await Document.open(path2);
+  } catch {
+    return "";
+  }
+  const remaining = collectTrackedChangeRecords(document4);
+  if (remaining.length === 0)
+    return "";
+  return `
+Remaining (ids renumbered after this ${verb}):
+
+${renderTrackedChangeTable(remaining)}`;
+}
+function quote(text6, max = 44) {
+  const collapsed = text6.replace(/\s+/g, " ").trim();
+  if (collapsed === "")
+    return "\xB6";
+  const clipped = collapsed.length > max ? `${collapsed.slice(0, max - 1)}\u2026` : collapsed;
+  return `"${clipped}"`;
+}
+function verbLabel(kind) {
+  const labels = {
+    ins: "insert",
+    del: "delete",
+    moveFrom: "move-from",
+    moveTo: "move-to",
+    sectPrChange: "section",
+    pPrChange: "format",
+    rowIns: "row-insert",
+    rowDel: "row-delete",
+    cellIns: "cell-insert",
+    cellDel: "cell-delete",
+    tblGridChange: "grid",
+    tblPrChange: "table-fmt",
+    tcPrChange: "cell-fmt",
+    checkboxToggle: "checkbox"
+  };
+  return labels[kind] ?? kind;
+}
+function describeSolo(record) {
+  if (record.kind === "ins" || record.kind === "del" || record.kind === "moveFrom" || record.kind === "moveTo") {
+    return record.text === "" ? "\xB6 paragraph mark" : quote(record.text);
+  }
+  if (record.kind === "pPrChange" || record.kind === "sectPrChange") {
+    const diff2 = propDiff(record.prior, record.current);
+    return diff2 || (record.kind === "pPrChange" ? "paragraph format" : "layout");
+  }
+  const notes = {
+    rowIns: "row inserted",
+    rowDel: "row deleted",
+    cellIns: "cell inserted",
+    cellDel: "cell deleted",
+    tblGridChange: "grid widths",
+    tblPrChange: "table properties",
+    tcPrChange: "cell properties",
+    checkboxToggle: "checkbox toggled"
+  };
+  return notes[record.kind] ?? "";
+}
+function propDiff(prior, current) {
+  const before = flattenProps(prior);
+  const after = flattenProps(current);
+  const keys = new Set([...before.keys(), ...after.keys()]);
+  const parts = [];
+  for (const key of keys) {
+    const from = before.get(key);
+    const to = after.get(key);
+    if (from === to)
+      continue;
+    parts.push(`${key} ${from ?? "\xB7"}\u2192${to ?? "\xB7"}`);
+  }
+  if (parts.length === 0)
+    return "";
+  if (parts.length > 3)
+    return `${parts.slice(0, 3).join(", ")}, \u2026`;
+  return parts.join(", ");
+}
+function flattenProps(obj, prefix = "") {
+  const out = new Map;
+  if (obj === null || typeof obj !== "object")
+    return out;
+  for (const [key, value] of Object.entries(obj)) {
+    const path2 = prefix ? `${prefix}.${key}` : key;
+    if (value !== null && typeof value === "object") {
+      for (const [k, v] of flattenProps(value, path2))
+        out.set(k, v);
+    } else if (typeof value === "string" || typeof value === "number") {
+      out.set(path2, value);
+    }
+  }
+  return out;
 }
 function trackedChangeIndex(id) {
   const match = id.match(/^tc(\d+)$/);
@@ -95355,12 +95600,50 @@ function readParagraphPropsSummary(children) {
   }
   return out;
 }
+var init_list_view = __esm(() => {
+  init_core2();
+  init_track_changes();
+  init_groups();
+});
+
+// src/cli/track-changes/list.ts
+var exports_list5 = {};
+__export(exports_list5, {
+  run: () => run49
+});
+async function run49(args) {
+  const parsed = await tryParseArgs(args, {
+    help: { type: "boolean", short: "h" },
+    json: { type: "boolean" }
+  }, HELP45);
+  if (typeof parsed === "number")
+    return parsed;
+  if (parsed.values.help) {
+    await writeStdout(HELP45);
+    return EXIT2.OK;
+  }
+  const path2 = parsed.positionals[0];
+  if (!path2)
+    return fail("USAGE", "Missing FILE argument", HELP45);
+  const document4 = await openOrFail(path2);
+  if (typeof document4 === "number")
+    return document4;
+  const records = collectTrackedChangeRecords(document4);
+  if (parsed.values.json) {
+    await respond(records);
+    return EXIT2.OK;
+  }
+  await writeStdout(renderTrackedChangeTable(records));
+  return EXIT2.OK;
+}
 var HELP45 = `docx track-changes list \u2014 inventory every revision wrapper
 
 Usage:
   docx track-changes list FILE [options]
 
 Options:
+  --json        Emit the full revision objects as a JSON array (default: a
+                text table, one LOGICAL change per line)
   -h, --help    Show this help
 
 Lists every revision wrapper with stable tcN ids \u2014 run-level <w:ins>, <w:del>,
@@ -95370,25 +95653,35 @@ paragraph-mark <w:ins>/<w:del> markers (a self-closing element inside
 of the same logical move appear as separate entries; their kind tells them
 apart.
 
-Output: a bare JSON array of { id, kind, author, date, revisionId, blockId,
-text } sorted by id (document order). Each item's "id" (e.g. tc0) is its
-addressable handle \u2014 pass it to \`accept\`/\`reject --at tcN\`. When a del and an
-ins are an adjacent REPLACE pair on the same paragraph, BOTH carry a shared
-"group": "revN" \u2014 accept/reject the whole logical change in one call with
-\`--at revN\` instead of accepting each half separately (tcN ids renumber after
-each single accept, so the revN handle avoids the re-list ping-pong). Errors print
-{code, error, hint?} with a nonzero exit. kind is one of: "ins", "del", "moveFrom",
-"moveTo", "sectPrChange", "pPrChange", "rowIns", "rowDel", "cellIns", "cellDel",
-"tblGridChange", "tblPrChange", "tcPrChange", "checkboxToggle". Paragraph-mark
-entries have kind "ins"/"del" with text "" \u2014 their blockId is the owning
-paragraph's pN. Table-structural entries (rowIns/rowDel/cellIns/cellDel and
-the property revisions tblGridChange/tblPrChange/tcPrChange) have text "" and
-blockId set to the owning table's tN. checkboxToggle entries surface a Word
-checkbox content control's tracked toggle (\u2610\u2194\u2612): metadata comes from the
-inner <w:ins> (the new glyph); reject restores the prior glyph and flips
-the w14:checked attribute back. Structural inserts/deletes of a checkbox
-(Word emits <w:customXmlDel/InsRangeStart/End> around the SDT) round-trip
-through the XmlNode tree but aren't yet enumerated as a dedicated kind.
+Output: a text table, ONE LOGICAL CHANGE per line \u2014
+
+  rev0  replace  p7   "Net 90 from the Company" \u2192 "Net 30 from the Company"
+  tc4   format   p22  spacing.line \u2192360
+  tc7   delete   p27  "Personal Guarantee."
+
+The leftmost token is the handle you pass to \`accept\`/\`reject --at\` (repeatable,
+e.g. \`--at rev0 --at tc4\`). A del+ins REPLACE pair on the same paragraph is
+collapsed onto ONE line under its shared revN handle, so accepting/rejecting the
+whole logical change is a single call \u2014 addressing the two tcN halves separately
+forces a re-list, because tcN ids renumber after each accept. All --at targets in
+one call resolve against the pre-mutation tree, so the renumbering never bites a
+batch.
+
+--json gives a bare JSON array of { id, kind, author, date, revisionId, blockId,
+text } sorted by id (document order). Each item's "id" (e.g. tc0) is its granular
+handle; paired halves additionally carry "group": "revN". kind is one of: "ins",
+"del", "moveFrom", "moveTo", "sectPrChange", "pPrChange", "rowIns", "rowDel",
+"cellIns", "cellDel", "tblGridChange", "tblPrChange", "tcPrChange",
+"checkboxToggle". Paragraph-mark entries have kind "ins"/"del" with text "" \u2014
+their blockId is the owning paragraph's pN. Table-structural entries
+(rowIns/rowDel/cellIns/cellDel and the property revisions
+tblGridChange/tblPrChange/tcPrChange) have text "" and blockId set to the owning
+table's tN. checkboxToggle entries surface a Word checkbox content control's
+tracked toggle (\u2610\u2194\u2612): metadata comes from the inner <w:ins> (the new glyph);
+reject restores the prior glyph and flips the w14:checked attribute back.
+Structural inserts/deletes of a checkbox (Word emits
+<w:customXmlDel/InsRangeStart/End> around the SDT) round-trip through the
+XmlNode tree but aren't yet enumerated as a dedicated kind.
 
 Property revisions (kind="sectPrChange" or "pPrChange") additionally include
 { prior, current } objects from before and after the tracked edit, so agents
@@ -95398,19 +95691,17 @@ style/alignment/spacing/indent.
 
 Examples:
   docx track-changes list doc.docx
-  docx track-changes list doc.docx | jq '.[] | select(.kind == "del")'
-  docx track-changes list doc.docx | jq '.[] | select(.kind | test("move"))'
-  docx track-changes list doc.docx | jq '.[] | select(.kind == "sectPrChange") | .prior, .current'
-  docx track-changes list doc.docx | jq '.[] | select(.kind == "pPrChange") | .prior, .current'
+  docx track-changes accept doc.docx --at rev0 --at tc4
+  docx track-changes list doc.docx --json | jq '.[] | select(.kind == "del")'
+  docx track-changes list doc.docx --json | jq '.[] | select(.kind | test("move"))'
+  docx track-changes list doc.docx --json | jq '.[] | select(.kind == "pPrChange") | .prior, .current'
 `;
 var init_list8 = __esm(() => {
-  init_core2();
-  init_track_changes();
   init_respond();
-  init_groups();
+  init_list_view();
 });
 
-// src/cli/track-changes/apply.ts
+// src/cli/track-changes/run-apply.ts
 async function runApply(args, verb, help) {
   const parsed = await tryParseArgs(args, {
     at: { type: "string", multiple: true },
@@ -95472,6 +95763,11 @@ async function runApply(args, verb, help) {
       path: outputPath ?? path2,
       applied
     });
+    if (!all2 && !parsed.values.verbose) {
+      const remaining = await remainingTrackedChangesBlock(outputPath ?? path2, verb);
+      if (remaining)
+        await writeStdout(remaining);
+    }
     return EXIT2.OK;
   } catch (error) {
     if (error instanceof TrackedChangeNotFoundError) {
@@ -95480,10 +95776,11 @@ async function runApply(args, verb, help) {
     throw error;
   }
 }
-var init_apply2 = __esm(() => {
+var init_run_apply = __esm(() => {
   init_track_changes();
   init_respond();
   init_groups();
+  init_list_view();
 });
 
 // src/cli/track-changes/accept.ts
@@ -95497,7 +95794,7 @@ async function run50(args) {
 var AT_FORMS14, HELP46;
 var init_accept = __esm(() => {
   init_core2();
-  init_apply2();
+  init_run_apply();
   AT_FORMS14 = describeForms(["trackedChange"], "                    ");
   HELP46 = `docx track-changes accept \u2014 accept tracked changes (incorporate into the doc)
 
@@ -95568,7 +95865,7 @@ async function run51(args) {
 var AT_FORMS15, HELP47;
 var init_reject = __esm(() => {
   init_core2();
-  init_apply2();
+  init_run_apply();
   AT_FORMS15 = describeForms(["trackedChange"], "                    ");
   HELP47 = `docx track-changes reject \u2014 reject tracked changes (revert to pre-change state)
 
@@ -95636,13 +95933,15 @@ Examples:
 `;
 });
 
-// src/cli/track-changes/toggle.tsx
-var exports_toggle = {};
-__export(exports_toggle, {
+// src/cli/track-changes/apply.ts
+var exports_apply = {};
+__export(exports_apply, {
   run: () => run52
 });
 async function run52(args) {
   const parsed = await tryParseArgs(args, {
+    accept: { type: "string", multiple: true },
+    reject: { type: "string", multiple: true },
     ...SAVE_FLAGS
   }, HELP48);
   if (typeof parsed === "number")
@@ -95652,15 +95951,151 @@ async function run52(args) {
     return EXIT2.OK;
   }
   setVerboseAck(Boolean(parsed.values.verbose));
+  const path2 = parsed.positionals[0];
+  if (!path2)
+    return fail("USAGE", "Missing FILE argument", HELP48);
+  const acceptRaw = parsed.values.accept ?? [];
+  const rejectRaw = parsed.values.reject ?? [];
+  if (acceptRaw.length === 0 && rejectRaw.length === 0) {
+    return fail("USAGE", "Specify --accept and/or --reject (handle)", HELP48);
+  }
+  const document4 = await openOrFail(path2);
+  if (typeof document4 === "number")
+    return document4;
+  const trackChanges = new TrackChanges(document4);
+  const groups = revisionGroups(trackChanges.list());
+  let accepts;
+  let rejects;
+  try {
+    accepts = expandRevisionTargets(acceptRaw, groups);
+    rejects = expandRevisionTargets(rejectRaw, groups);
+  } catch (error) {
+    if (error instanceof UnknownRevisionError) {
+      return fail("TRACKED_CHANGE_NOT_FOUND", error.message, "Run 'docx track-changes list FILE' \u2014 revN handles appear as the `group` field on paired changes.");
+    }
+    throw error;
+  }
+  const rejectSet = new Set(rejects);
+  const conflict = accepts.find((id) => rejectSet.has(id));
+  if (conflict) {
+    return fail("USAGE", `${conflict} is named in both --accept and --reject`, HELP48);
+  }
+  const outputPath = parsed.values.output;
+  try {
+    if (parsed.values["dry-run"]) {
+      const previewApplied = [
+        ...trackChanges.preview(accepts, "accept"),
+        ...trackChanges.preview(rejects, "reject")
+      ].sort((a2, b) => trackedChangeIndex2(a2.id) - trackedChangeIndex2(b.id));
+      await respond({
+        operation: "track-changes.apply",
+        dryRun: true,
+        path: path2,
+        ...outputPath ? { output: outputPath } : {},
+        applied: previewApplied
+      });
+      return EXIT2.OK;
+    }
+    const applied = trackChanges.apply(accepts, rejects);
+    await document4.save(outputPath);
+    await respondAck({
+      ok: true,
+      operation: "track-changes.apply",
+      path: outputPath ?? path2,
+      applied
+    });
+    if (!parsed.values.verbose) {
+      const remaining = await remainingTrackedChangesBlock(outputPath ?? path2, "apply");
+      if (remaining)
+        await writeStdout(remaining);
+    }
+    return EXIT2.OK;
+  } catch (error) {
+    if (error instanceof TrackedChangeNotFoundError) {
+      return fail("TRACKED_CHANGE_NOT_FOUND", error.message, "Run 'docx track-changes list FILE' to see available handles.");
+    }
+    throw error;
+  }
+}
+function trackedChangeIndex2(id) {
+  const match = id.match(/^tc(\d+)$/);
+  return match?.[1] ? Number(match[1]) : 0;
+}
+var HELP48 = `docx track-changes apply \u2014 finalize: accept AND reject in one atomic call
+
+Usage:
+  docx track-changes apply FILE (--accept H ... | --reject H ...) [options]
+
+A document review ends in a finalize: accept the changes you want, reject the
+rest. Doing that as separate \`accept\` and \`reject\` calls is a trap \u2014 tcN/revN
+ids renumber after every accept/reject, so the SECOND command addresses a
+moved target ("tc5 not found", or worse, silently the wrong change). \`apply\`
+takes BOTH decisions at once and resolves EVERY handle against the original
+pre-mutation tree, so nothing renumbers mid-operation and the file is never
+left half-finalized (there is no undo).
+
+Handles are the same ones \`track-changes list\` prints: a tcN, or a revN that
+covers both halves of a del+ins replace pair. Both flags repeat.
+
+Targets (at least one required):
+  --accept H        A handle (tcN or revN) to accept. Repeat for several
+                    (--accept rev0 --accept rev1 --accept tc4).
+  --reject H        A handle (tcN or revN) to reject. Repeat for several.
+
+A handle may not appear in both lists. Unknown handles error before anything is
+written. Leftover changes you name in neither list stay tracked (apply finalizes
+only what you address); the confirmation re-lists them so you can see what's left.
+
+Options:
+  -o, --output PATH Write to PATH instead of overwriting FILE
+  --dry-run         Print what would change; do not write the file
+  -v, --verbose     Print the success ack JSON (default: a one-line confirmation)
+  -h, --help        Show this help
+
+Output:
+  Prints a one-line confirmation on success (exit 0); when changes remain it
+  also re-lists them with their renumbered handles. --verbose prints
+  {ok:true, operation, path, applied}. --dry-run previews. Errors print
+  {code, error, hint?} with a nonzero exit. Discover handles with
+  \`docx track-changes list FILE\`.
+
+Examples:
+  docx track-changes apply doc.docx --accept rev0 --accept rev1 --accept tc4 \\
+                                    --reject rev2 --reject tc7
+  docx track-changes apply doc.docx --reject rev0 --dry-run
+`;
+var init_apply2 = __esm(() => {
+  init_track_changes();
+  init_respond();
+  init_groups();
+  init_list_view();
+});
+
+// src/cli/track-changes/toggle.tsx
+var exports_toggle = {};
+__export(exports_toggle, {
+  run: () => run53
+});
+async function run53(args) {
+  const parsed = await tryParseArgs(args, {
+    ...SAVE_FLAGS
+  }, HELP49);
+  if (typeof parsed === "number")
+    return parsed;
+  if (parsed.values.help) {
+    await writeStdout(HELP49);
+    return EXIT2.OK;
+  }
+  setVerboseAck(Boolean(parsed.values.verbose));
   const [first, second] = parsed.positionals;
   const modeFirst = first === "on" || first === "off";
   const mode = modeFirst ? first : second;
   const path2 = modeFirst ? second : first;
   if (mode !== "on" && mode !== "off") {
-    return fail("USAGE", `Expected "on" or "off" (e.g. \`docx track-changes on FILE\`), got: ${parsed.positionals.join(" ") || "<nothing>"}`, HELP48);
+    return fail("USAGE", `Expected "on" or "off" (e.g. \`docx track-changes on FILE\`), got: ${parsed.positionals.join(" ") || "<nothing>"}`, HELP49);
   }
   if (!path2)
-    return fail("USAGE", "Missing FILE argument", HELP48);
+    return fail("USAGE", "Missing FILE argument", HELP49);
   const document4 = await openOrFail(path2);
   if (typeof document4 === "number")
     return document4;
@@ -95690,7 +96125,7 @@ async function run52(args) {
   });
   return EXIT2.OK;
 }
-var HELP48 = `docx track-changes \u2014 toggle the document's tracked-changes mode
+var HELP49 = `docx track-changes \u2014 toggle the document's tracked-changes mode
 
 Usage:
   docx track-changes on|off FILE [options]
@@ -95728,16 +96163,16 @@ var init_toggle2 = __esm(() => {
 // src/cli/track-changes/index.ts
 var exports_track_changes = {};
 __export(exports_track_changes, {
-  run: () => run53
+  run: () => run54
 });
-async function run53(args) {
+async function run54(args) {
   const first = args[0];
   if (first === "--help" || first === "-h" || first === "help") {
-    await writeStdout(HELP49);
+    await writeStdout(HELP50);
     return 0;
   }
   if (!first) {
-    return fail("USAGE", "Missing arguments", HELP49);
+    return fail("USAGE", "Missing arguments", HELP50);
   }
   if (first === "list") {
     const module_2 = await Promise.resolve().then(() => (init_list8(), exports_list5));
@@ -95751,16 +96186,21 @@ async function run53(args) {
     const module_2 = await Promise.resolve().then(() => (init_reject(), exports_reject));
     return module_2.run(args.slice(1));
   }
+  if (first === "apply") {
+    const module_2 = await Promise.resolve().then(() => (init_apply2(), exports_apply));
+    return module_2.run(args.slice(1));
+  }
   const module_ = await Promise.resolve().then(() => (init_toggle2(), exports_toggle));
   return module_.run(args);
 }
-var HELP49 = `docx track-changes \u2014 manage tracked-changes
+var HELP50 = `docx track-changes \u2014 manage tracked-changes
 
 Usage:
   docx track-changes on|off FILE [options]
   docx track-changes list FILE [options]
   docx track-changes accept FILE (--at tcN | --all) [options]
   docx track-changes reject FILE (--at tcN | --all) [options]
+  docx track-changes apply  FILE (--accept H ... | --reject H ...) [options]
 
 Verbs:
   on        Set <w:trackChanges/> in word/settings.xml
@@ -95775,9 +96215,14 @@ Verbs:
             paragraph-mark ins the entire paragraph is removed); del/moveFrom
             unwrap (with <w:delText> \u2192 <w:t> rename); sectPrChange restores
             its snapshot
+  apply     Finalize: accept AND reject in ONE atomic call, every handle
+            resolved against the original tree \u2014 the safe way to apply a
+            review, since separate accept/reject calls renumber ids between
+            them
 
 Exact-change addressing is always --at tcN (repeatable); --all targets every
-change. Discover ids with "docx track-changes list FILE".
+change; \`apply\` takes --accept/--reject handle lists. Discover ids with
+"docx track-changes list FILE".
 
 When tracking is on, the SUBSEQUENT insert/edit/delete/replace commands emit
 <w:ins>/<w:del> markers (attributed via --author or $DOCX_AUTHOR on those
@@ -95894,29 +96339,29 @@ var init_count = __esm(() => {
 // src/cli/wc/index.ts
 var exports_wc = {};
 __export(exports_wc, {
-  run: () => run54
+  run: () => run55
 });
-async function run54(args) {
+async function run55(args) {
   const parsed = await tryParseArgs(args, {
     accepted: { type: "boolean" },
     baseline: { type: "boolean" },
     current: { type: "boolean" },
     json: { type: "boolean" },
     help: { type: "boolean", short: "h" }
-  }, HELP50);
+  }, HELP51);
   if (typeof parsed === "number")
     return parsed;
   if (parsed.values.help) {
-    await writeStdout(HELP50);
+    await writeStdout(HELP51);
     return EXIT2.OK;
   }
   const path2 = parsed.positionals[0];
   const locatorInput = parsed.positionals[1];
   if (!path2)
-    return fail("USAGE", "Missing FILE argument", HELP50);
+    return fail("USAGE", "Missing FILE argument", HELP51);
   const view = resolveView(parsed.values);
   if (!view) {
-    return fail("USAGE", "--accepted, --baseline, and --current are mutually exclusive", HELP50);
+    return fail("USAGE", "--accepted, --baseline, and --current are mutually exclusive", HELP51);
   }
   const json2 = Boolean(parsed.values.json);
   const pickText = paragraphTextFor(view);
@@ -96094,13 +96539,13 @@ function paragraphTextFor(view) {
     return paragraphTextBaseline;
   return paragraphText2;
 }
-var HELP50;
+var HELP51;
 var init_wc = __esm(() => {
   init_core2();
   init_parse_helpers();
   init_respond();
   init_count();
-  HELP50 = `docx wc \u2014 count words in a document or a locator-addressed slice
+  HELP51 = `docx wc \u2014 count words in a document or a locator-addressed slice
 
 Usage:
   docx wc FILE [LOCATOR] [options]
@@ -96164,7 +96609,7 @@ Examples:
 // package.json
 var package_default = {
   name: "bun-docx",
-  version: "0.16.0",
+  version: "0.17.0",
   description: "CLI for AI agents (Claude, Codex) to read, edit, and comment on .docx files with full format fidelity.",
   keywords: [
     "docx",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bun-docx",
-	"version": "0.16.0",
+	"version": "0.17.0",
 	"description": "CLI for AI agents (Claude, Codex) to read, edit, and comment on .docx files with full format fidelity.",
 	"keywords": [
 		"docx",