bun-docx 0.1.1 → 0.3.0

package/dist/index.js

@@ -47,57 +47,6 @@ var __export = (target, all) => {
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __require = import.meta.require;
 
-// src/cli/respond.ts
-async function respond(payload) {
-  await Bun.write(Bun.stdout, `${JSON.stringify(payload)}
-`);
-}
-async function writeStdout(text) {
-  await Bun.write(Bun.stdout, text);
-}
-async function fail(code, message, hint) {
-  const payload = {
-    ok: false,
-    code,
-    error: message
-  };
-  if (hint)
-    payload.hint = hint;
-  await respond(payload);
-  return exitCodeFor(code);
-}
-function exitCodeFor(code) {
-  switch (code) {
-    case "USAGE":
-    case "INVALID_LOCATOR":
-      return EXIT.USAGE_ERROR;
-    case "FILE_NOT_FOUND":
-    case "PART_NOT_FOUND":
-    case "BLOCK_NOT_FOUND":
-    case "COMMENT_NOT_FOUND":
-    case "IMAGE_NOT_FOUND":
-      return EXIT.NOT_FOUND;
-    case "PERMISSION_DENIED":
-      return EXIT.PERMISSION_DENIED;
-    case "ALREADY_APPLIED":
-      return EXIT.ALREADY_APPLIED;
-    case "NOT_A_ZIP":
-    case "UNHANDLED":
-      return EXIT.GENERAL_ERROR;
-  }
-}
-var EXIT;
-var init_respond = __esm(() => {
-  EXIT = {
-    OK: 0,
-    GENERAL_ERROR: 1,
-    USAGE_ERROR: 2,
-    NOT_FOUND: 3,
-    PERMISSION_DENIED: 4,
-    ALREADY_APPLIED: 5
-  };
-});
-
 // node_modules/process-nextick-args/index.js
 var require_process_nextick_args = __commonJS((exports, module) => {
   if (typeof process === "undefined" || !process.version || process.version.indexOf("v0.") === 0 || process.version.indexOf("v1.") === 0 && process.version.indexOf("v1.8.") !== 0) {
@@ -9177,92 +9126,6 @@ var require_lib3 = __commonJS((exports, module) => {
   module.exports = JSZip;
 });
 
-// src/core/package/index.ts
-class Pkg {
-  zip;
-  path;
-  constructor(zip, path) {
-    this.zip = zip;
-    this.path = path;
-  }
-  static async open(path) {
-    const file = Bun.file(path);
-    if (!await file.exists()) {
-      throw new PkgError("FILE_NOT_FOUND", `File not found: ${path}`);
-    }
-    const buf = await file.arrayBuffer();
-    let zip;
-    try {
-      zip = await import_jszip.default.loadAsync(buf);
-    } catch (err) {
-      const reason = err instanceof Error ? err.message : String(err);
-      throw new PkgError("NOT_A_ZIP", `Not a valid .docx (zip): ${reason}`);
-    }
-    return new Pkg(zip, path);
-  }
-  hasPart(name) {
-    return this.zip.file(name) !== null;
-  }
-  listParts() {
-    const names = [];
-    this.zip.forEach((p) => {
-      names.push(p);
-    });
-    return names;
-  }
-  async readText(name) {
-    const entry = this.zip.file(name);
-    if (!entry) {
-      throw new PkgError("PART_NOT_FOUND", `Part not found: ${name}`);
-    }
-    return entry.async("string");
-  }
-  async readBytes(name) {
-    const entry = this.zip.file(name);
-    if (!entry) {
-      throw new PkgError("PART_NOT_FOUND", `Part not found: ${name}`);
-    }
-    return entry.async("uint8array");
-  }
-  writeText(name, content) {
-    this.zip.file(name, content);
-  }
-  writeBytes(name, content) {
-    this.zip.file(name, content);
-  }
-  deletePart(name) {
-    this.zip.remove(name);
-  }
-  async save(path) {
-    const target = path ?? this.path;
-    const buf = await this.zip.generateAsync({
-      type: "uint8array",
-      compression: "DEFLATE",
-      compressionOptions: { level: 6 }
-    });
-    await Bun.write(target, buf);
-  }
-  async toBytes() {
-    return this.zip.generateAsync({
-      type: "uint8array",
-      compression: "DEFLATE",
-      compressionOptions: { level: 6 }
-    });
-  }
-}
-var import_jszip, PkgError;
-var init_package = __esm(() => {
-  import_jszip = __toESM(require_lib3(), 1);
-  PkgError = class PkgError extends Error {
-    code;
-    constructor(code, message) {
-      super(message);
-      this.code = code;
-      this.name = "PkgError";
-    }
-  };
-});
-
 // node_modules/path-expression-matcher/src/Expression.js
 class Expression {
   constructor(pattern, options = {}, data) {
@@ -13559,10 +13422,8 @@ class XmlNode2 {
   }
   static serialize(tree) {
     const builder = new Builder(BUILD_OPTIONS);
-    const flat = [];
-    flattenFragments(tree, flat);
     const pojo = [];
-    for (const node of flat) {
+    for (const node of tree) {
       pojo.push(node.toObject());
     }
     return builder.build(pojo);
@@ -13653,6 +13514,15 @@ class XmlNode2 {
     }
     return out;
   }
+  clone() {
+    const cloned = new XmlNode2(this.tag, { ...this.attributes });
+    if (this.text !== undefined)
+      cloned.text = this.text;
+    for (const child of this.children) {
+      cloned.children.push(child.clone());
+    }
+    return cloned;
+  }
   toObject() {
     if (this.isText) {
       return { "#text": this.text ?? "" };
@@ -13676,16 +13546,7 @@ class XmlNode2 {
     return result;
   }
 }
-function flattenFragments(tree, out) {
-  for (const node of tree) {
-    if (node.tag === FRAGMENT_TAG) {
-      flattenFragments(node.children, out);
-      continue;
-    }
-    out.push(node);
-  }
-}
-var PARSE_OPTIONS, BUILD_OPTIONS, FRAGMENT_TAG = "#fragment";
+var PARSE_OPTIONS, BUILD_OPTIONS;
 var init_xml_node = __esm(() => {
   init_fxb();
   init_fxp();
@@ -13708,66 +13569,252 @@ var init_xml_node = __esm(() => {
   };
 });
 
+// src/core/parser/run-ops.ts
+function runTextLength(run) {
+  let total = 0;
+  for (const child of run.children) {
+    if (child.tag === "w:t")
+      total += child.collectText().length;
+  }
+  return total;
+}
+function sliceRun(run, start, end) {
+  const sliced = new XmlNode2("w:r", { ...run.attributes });
+  let consumed = 0;
+  for (const child of run.children) {
+    if (child.tag === "w:t") {
+      const text = child.collectText();
+      const localStart = Math.max(0, start - consumed);
+      const localEnd = Math.min(text.length, end - consumed);
+      if (localStart < localEnd) {
+        const slicedText = new XmlNode2("w:t", { "xml:space": "preserve" });
+        slicedText.children.push(XmlNode2.textNode(text.slice(localStart, localEnd)));
+        sliced.children.push(slicedText);
+      }
+      consumed += text.length;
+      continue;
+    }
+    sliced.children.push(child.clone());
+  }
+  return sliced;
+}
+var init_run_ops = __esm(() => {
+  init_xml_node();
+});
+
 // src/core/parser/index.ts
 var init_parser = __esm(() => {
+  init_run_ops();
   init_xml_node();
 });
 
-// src/core/ast/read.ts
-function buildDoc(view, path) {
-  readImageRelationships(view);
-  const properties = readDocProperties(view);
-  const documentRoot = XmlNode2.findRoot(view.documentTree, "w:document");
-  if (!documentRoot) {
-    throw new Error("Invalid .docx: missing <w:document>");
-  }
-  const body = documentRoot.findChild("w:body");
-  if (!body) {
-    throw new Error("Invalid .docx: missing <w:body>");
-  }
-  const state = {
-    imageIndex: 0,
-    commentAnchors: new Map,
-    openComments: new Map
-  };
-  const blocks = readBlocks(view, body, state);
-  const comments = readComments(view, state.commentAnchors);
-  return { schemaVersion: 1, path, properties, blocks, comments };
-}
-function readBlocks(view, body, state) {
-  const blocks = [];
-  let paragraphIndex = 0;
-  let tableIndex = 0;
-  let sectionIndex = 0;
-  for (const child of body.children) {
-    if (child.tag === "w:p") {
-      const id = `p${paragraphIndex++}`;
-      blocks.push(readParagraph(view, child, id, state));
-      view.blockReferences.set(id, { node: child, parent: body.children });
+// src/core/package/parts.ts
+function nextRelationshipId(relationships) {
+  let highest = 0;
+  for (const child of relationships.children) {
+    if (child.tag !== "Relationship")
       continue;
-    }
-    if (child.tag === "w:tbl") {
-      const id = `t${tableIndex++}`;
-      blocks.push(readTable(view, child, id, state));
-      view.blockReferences.set(id, { node: child, parent: body.children });
+    const id = child.getAttribute("Id");
+    if (!id)
+      continue;
+    const match = id.match(/^rId(\d+)$/);
+    if (!match)
       continue;
+    const numeric = Number(match[1]);
+    if (Number.isFinite(numeric) && numeric > highest)
+      highest = numeric;
+  }
+  return `rId${highest + 1}`;
+}
+function registerPart(relationshipsTree, contentTypesTree, part) {
+  const relationships = XmlNode2.findRoot(relationshipsTree, "Relationships");
+  if (relationships) {
+    const alreadyLinked = relationships.children.some((child) => child.tag === "Relationship" && child.getAttribute("Type") === part.relationshipType);
+    if (!alreadyLinked) {
+      relationships.children.push(new XmlNode2("Relationship", {
+        Id: nextRelationshipId(relationships),
+        Type: part.relationshipType,
+        Target: part.target
+      }));
     }
-    if (child.tag === "w:sectPr") {
-      const id = `s${sectionIndex++}`;
-      blocks.push({ id, type: "sectionBreak" });
-      view.blockReferences.set(id, { node: child, parent: body.children });
+  }
+  const types = XmlNode2.findRoot(contentTypesTree, "Types");
+  if (types) {
+    const overrideExists = types.children.some((child) => child.tag === "Override" && child.getAttribute("PartName") === `/${part.partName}`);
+    if (!overrideExists) {
+      types.children.push(new XmlNode2("Override", {
+        PartName: `/${part.partName}`,
+        ContentType: part.contentType
+      }));
     }
   }
-  return blocks;
 }
-function readParagraph(view, node, id, state) {
-  const paragraph = { id, type: "paragraph", runs: [] };
-  const paragraphProperties = node.findChild("w:pPr");
-  if (paragraphProperties) {
-    applyParagraphProperties(paragraph, paragraphProperties);
+var init_parts = __esm(() => {
+  init_parser();
+});
+
+// src/core/package/index.ts
+import { lstat, rename, unlink } from "fs/promises";
+async function writeAtomic(target, buf) {
+  let isSymlink = false;
+  try {
+    isSymlink = (await lstat(target)).isSymbolicLink();
+  } catch {}
+  if (isSymlink) {
+    await Bun.write(target, buf);
+    return;
   }
-  const activeComments = new Set;
-  let offset = 0;
+  const tmp = `${target}.docx-cli-tmp-${process.pid}-${Date.now()}`;
+  try {
+    await Bun.write(tmp, buf);
+    await rename(tmp, target);
+  } catch (err) {
+    await unlink(tmp).catch(() => {});
+    throw err;
+  }
+}
+
+class Pkg {
+  zip;
+  path;
+  constructor(zip, path) {
+    this.zip = zip;
+    this.path = path;
+  }
+  static async open(path) {
+    const file = Bun.file(path);
+    if (!await file.exists()) {
+      throw new PkgError("FILE_NOT_FOUND", `File not found: ${path}`);
+    }
+    const buf = await file.arrayBuffer();
+    let zip;
+    try {
+      zip = await import_jszip.default.loadAsync(buf);
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      throw new PkgError("NOT_A_ZIP", `Not a valid .docx (zip): ${reason}`);
+    }
+    return new Pkg(zip, path);
+  }
+  hasPart(name) {
+    return this.zip.file(name) !== null;
+  }
+  listParts() {
+    const names = [];
+    this.zip.forEach((p) => {
+      names.push(p);
+    });
+    return names;
+  }
+  async readText(name) {
+    const entry = this.zip.file(name);
+    if (!entry) {
+      throw new PkgError("PART_NOT_FOUND", `Part not found: ${name}`);
+    }
+    return entry.async("string");
+  }
+  async readBytes(name) {
+    const entry = this.zip.file(name);
+    if (!entry) {
+      throw new PkgError("PART_NOT_FOUND", `Part not found: ${name}`);
+    }
+    return entry.async("uint8array");
+  }
+  writeText(name, content) {
+    this.zip.file(name, content);
+  }
+  writeBytes(name, content) {
+    this.zip.file(name, content);
+  }
+  deletePart(name) {
+    this.zip.remove(name);
+  }
+  async save(path) {
+    const target = path ?? this.path;
+    const buf = await this.zip.generateAsync({
+      type: "uint8array",
+      compression: "DEFLATE",
+      compressionOptions: { level: 6 }
+    });
+    await writeAtomic(target, buf);
+  }
+  async toBytes() {
+    return this.zip.generateAsync({
+      type: "uint8array",
+      compression: "DEFLATE",
+      compressionOptions: { level: 6 }
+    });
+  }
+}
+var import_jszip, PkgError;
+var init_package = __esm(() => {
+  init_parts();
+  import_jszip = __toESM(require_lib3(), 1);
+  PkgError = class PkgError extends Error {
+    code;
+    constructor(code, message) {
+      super(message);
+      this.code = code;
+      this.name = "PkgError";
+    }
+  };
+});
+
+// src/core/ast/read.ts
+function buildDoc(view, path) {
+  readImageRelationships(view);
+  const properties = readDocProperties(view);
+  const documentRoot = XmlNode2.findRoot(view.documentTree, "w:document");
+  if (!documentRoot) {
+    throw new Error("Invalid .docx: missing <w:document>");
+  }
+  const body = documentRoot.findChild("w:body");
+  if (!body) {
+    throw new Error("Invalid .docx: missing <w:body>");
+  }
+  const state = {
+    imageIndex: 0,
+    commentAnchors: new Map,
+    openComments: new Map
+  };
+  const blocks = readBlocks(view, body, state);
+  const comments = readComments(view, state.commentAnchors);
+  return { schemaVersion: 1, path, properties, blocks, comments };
+}
+function readBlocks(view, body, state) {
+  const blocks = [];
+  let paragraphIndex = 0;
+  let tableIndex = 0;
+  let sectionIndex = 0;
+  for (const child of body.children) {
+    if (child.tag === "w:p") {
+      const id = `p${paragraphIndex++}`;
+      blocks.push(readParagraph(view, child, id, state));
+      view.blockReferences.set(id, { node: child, parent: body.children });
+      continue;
+    }
+    if (child.tag === "w:tbl") {
+      const id = `t${tableIndex++}`;
+      blocks.push(readTable(view, child, id, state));
+      view.blockReferences.set(id, { node: child, parent: body.children });
+      continue;
+    }
+    if (child.tag === "w:sectPr") {
+      const id = `s${sectionIndex++}`;
+      blocks.push({ id, type: "sectionBreak" });
+      view.blockReferences.set(id, { node: child, parent: body.children });
+    }
+  }
+  return blocks;
+}
+function readParagraph(view, node, id, state) {
+  const paragraph = { id, type: "paragraph", runs: [] };
+  const paragraphProperties = node.findChild("w:pPr");
+  if (paragraphProperties) {
+    applyParagraphProperties(paragraph, paragraphProperties);
+  }
+  const activeComments = new Set;
+  let offset = 0;
   for (const child of node.children) {
     if (child.tag === "w:pPr")
       continue;
@@ -13815,6 +13862,33 @@ function readParagraph(view, node, id, state) {
         revisionId: child.getAttribute("w:id") ?? ""
       };
       for (const inner of child.children) {
+        if (inner.tag === "w:commentRangeStart") {
+          const commentId = inner.getAttribute("w:id");
+          if (commentId) {
+            const key = `c${commentId}`;
+            activeComments.add(key);
+            state.openComments.set(key, { blockId: id, offset });
+          }
+          continue;
+        }
+        if (inner.tag === "w:commentRangeEnd") {
+          const commentId = inner.getAttribute("w:id");
+          if (commentId) {
+            const key = `c${commentId}`;
+            activeComments.delete(key);
+            const opened = state.openComments.get(key);
+            if (opened) {
+              state.commentAnchors.set(key, {
+                startBlockId: opened.blockId,
+                startOffset: opened.offset,
+                endBlockId: id,
+                endOffset: offset
+              });
+              state.openComments.delete(key);
+            }
+          }
+          continue;
+        }
         if (inner.tag !== "w:r")
           continue;
         const run = readRun(view, inner, activeComments, change, state);
@@ -13869,8 +13943,9 @@ function readRun(view, node, activeComments, trackedChange, state) {
   }
   let combinedText = "";
   for (const child of node.children) {
-    if (child.tag === "w:t")
+    if (child.tag === "w:t" || child.tag === "w:delText") {
       combinedText += child.collectText();
+    }
   }
   if (combinedText.length === 0)
     return null;
@@ -13954,26 +14029,33 @@ function readImageFromDrawing(view, drawing, state) {
 }
 function readTable(view, node, id, state) {
   const rows = [];
+  let rowIndex = 0;
   for (const child of node.children) {
     if (child.tag !== "w:tr")
       continue;
     const cells = [];
+    let columnIndex = 0;
     for (const cellNode of child.children) {
       if (cellNode.tag !== "w:tc")
         continue;
-      cells.push({ blocks: readCellBlocks(view, cellNode, state) });
+      cells.push({
+        blocks: readCellBlocks(view, cellNode, id, rowIndex, columnIndex, state)
+      });
+      columnIndex++;
     }
     rows.push({ cells });
+    rowIndex++;
   }
   return { id, type: "table", rows };
 }
-function readCellBlocks(view, cell, state) {
+function readCellBlocks(view, cell, tableId, rowIndex, columnIndex, state) {
   const blocks = [];
   let paragraphIndex = 0;
   for (const child of cell.children) {
     if (child.tag === "w:p") {
-      const id = `cellp${paragraphIndex++}`;
+      const id = `${tableId}:r${rowIndex}c${columnIndex}:p${paragraphIndex++}`;
       blocks.push(readParagraph(view, child, id, state));
+      view.blockReferences.set(id, { node: child, parent: cell.children });
     }
   }
   return blocks;
@@ -14136,6 +14218,7 @@ async function openDocView(path) {
   const commentsTree = pkg.hasPart("word/comments.xml") ? XmlNode2.parse(await pkg.readText("word/comments.xml")) : undefined;
   const commentsExtTree = pkg.hasPart("word/commentsExtended.xml") ? XmlNode2.parse(await pkg.readText("word/commentsExtended.xml")) : undefined;
   const corePropertiesTree = pkg.hasPart("docProps/core.xml") ? XmlNode2.parse(await pkg.readText("docProps/core.xml")) : undefined;
+  const settingsTree = pkg.hasPart("word/settings.xml") ? XmlNode2.parse(await pkg.readText("word/settings.xml")) : undefined;
   const view = {
     pkg,
     documentTree,
@@ -14144,6 +14227,7 @@ async function openDocView(path) {
     relationshipsTree,
     contentTypesTree,
     corePropertiesTree,
+    settingsTree,
     doc: undefined,
     blockReferences: new Map,
     commentReferences: new Map,
@@ -14163,6 +14247,9 @@ async function saveDocView(view, path) {
   if (view.commentsExtTree) {
     view.pkg.writeText("word/commentsExtended.xml", XmlNode2.serialize(view.commentsExtTree));
   }
+  if (view.settingsTree) {
+    view.pkg.writeText("word/settings.xml", XmlNode2.serialize(view.settingsTree));
+  }
   await view.pkg.save(path);
 }
 async function enrichImageHashes(view) {
@@ -14290,7 +14377,7 @@ var init_parse = __esm(() => {
       this.name = "LocatorParseError";
     }
   };
-  BLOCK_RE = /^(p|t|s|cellp)(\d+)$/;
+  BLOCK_RE = /^(p|t|s)(\d+)$/;
   SPAN_RE = /^p(\d+):(\d+)-(\d+)$/;
   RANGE_RE = /^p(\d+):(\d+)-p(\d+):(\d+)$/;
   COMMENT_RE = /^c(\d+)$/;
@@ -14299,6 +14386,26 @@ var init_parse = __esm(() => {
 });
 
 // src/core/locators/resolve.ts
+function locatorToBlockTarget(locator) {
+  if (locator.kind === "block")
+    return { blockId: locator.blockId };
+  if (locator.kind === "blockSpan") {
+    return {
+      blockId: locator.blockId,
+      span: { start: locator.start, end: locator.end }
+    };
+  }
+  if (locator.kind === "cell" && locator.inner) {
+    const inner = locatorToBlockTarget(locator.inner);
+    if (!inner)
+      return null;
+    return {
+      blockId: `${locator.tableId}:r${locator.row}c${locator.col}:${inner.blockId}`,
+      span: inner.span
+    };
+  }
+  return null;
+}
 function resolveBlock(view, blockId) {
   const reference = view.blockReferences.get(blockId);
   if (!reference) {
@@ -14324,15 +14431,82 @@ var init_locators = __esm(() => {
   init_resolve();
 });
 
-// src/core/index.ts
-var init_core = __esm(() => {
-  init_ast();
-  init_locators();
-  init_package();
+// src/core/track-changes/index.ts
+function isTrackChangesEnabled(view) {
+  if (!view.settingsTree)
+    return false;
+  const settingsRoot = XmlNode2.findRoot(view.settingsTree, "w:settings");
+  if (!settingsRoot)
+    return false;
+  return settingsRoot.children.some((child) => child.tag === "w:trackChanges");
+}
+function createRevisionAllocator(view) {
+  let nextId = computeMaxRevisionId(view) + 1;
+  return {
+    next() {
+      const id = nextId;
+      nextId += 1;
+      return id;
+    }
+  };
+}
+function resolveAuthor(authorFlag) {
+  if (authorFlag)
+    return authorFlag;
+  if (Bun.env.DOCX_AUTHOR)
+    return Bun.env.DOCX_AUTHOR;
+  if (Bun.env.DOCX_CLI_AUTHOR)
+    return Bun.env.DOCX_CLI_AUTHOR;
+  return "docx-cli";
+}
+function resolveDate() {
+  return Bun.env.DOCX_CLI_NOW ?? new Date().toISOString();
+}
+function convertTextToDelText(node) {
+  const cloned = node.clone();
+  mutateTextToDelText([cloned]);
+  return cloned;
+}
+function computeMaxRevisionId(view) {
+  let max = -1;
+  walkXml(view.documentTree, (node) => {
+    if (node.tag !== "w:ins" && node.tag !== "w:del")
+      return;
+    const idAttr = node.getAttribute("w:id");
+    if (!idAttr)
+      return;
+    const value = Number(idAttr);
+    if (Number.isFinite(value) && value > max)
+      max = value;
+  });
+  return max;
+}
+function walkXml(nodes, visit) {
+  for (const node of nodes) {
+    visit(node);
+    if (node.children.length > 0)
+      walkXml(node.children, visit);
+  }
+}
+function mutateTextToDelText(nodes) {
+  for (const node of nodes) {
+    if (node.tag === "w:t")
+      node.tag = "w:delText";
+    mutateTextToDelText(node.children);
+  }
+}
+var init_track_changes = __esm(() => {
   init_parser();
 });
 
 // src/core/jsx/index.ts
+function normalizeChildren(children) {
+  if (children === undefined || children === null)
+    return [];
+  if (Array.isArray(children))
+    return children;
+  return [children];
+}
 function namespace(prefix, tags) {
   const result = {};
   for (const tagName of tags) {
@@ -14341,19 +14515,22 @@ function namespace(prefix, tags) {
   return result;
 }
 function makeTag(qualifiedName) {
-  return (props, ...children) => {
+  return (props) => {
     const attributes = {};
+    let childrenProp;
     if (props) {
       for (const [key, value] of Object.entries(props)) {
-        if (key === "children")
+        if (key === "children") {
+          childrenProp = value;
           continue;
+        }
         if (value === false || value == null)
           continue;
         attributes[mapAttributeName(key)] = String(value);
       }
     }
     const childNodes = [];
-    flatten(children, childNodes);
+    flatten(normalizeChildren(childrenProp), childNodes);
     return new XmlNode2(qualifiedName, attributes, childNodes);
   };
 }
@@ -14366,7 +14543,7 @@ function flatten(items, out) {
       continue;
     }
     if (item instanceof XmlNode2) {
-      if (item.tag === FRAGMENT_TAG2) {
+      if (item.tag === FRAGMENT_TAG) {
         for (const child of item.children)
           out.push(child);
         continue;
@@ -14385,7 +14562,7 @@ function mapAttributeName(name) {
     return name;
   return `${name.slice(0, dashIndex)}:${name.slice(dashIndex + 1)}`;
 }
-var FRAGMENT_TAG2 = "#fragment", W_TAGS, R_TAGS, A_TAGS, WP_TAGS, PIC_TAGS, CP_TAGS, DC_TAGS, DCTERMS_TAGS, W14_TAGS, W15_TAGS, w, r, a, wp, pic, cp, dc, dcterms, w14, w15;
+var FRAGMENT_TAG = "#fragment", W_TAGS, R_TAGS, A_TAGS, WP_TAGS, PIC_TAGS, CP_TAGS, DC_TAGS, DCTERMS_TAGS, W14_TAGS, W15_TAGS, w, r, a, wp, pic, cp, dc, dcterms, w14, w15;
 var init_jsx = __esm(() => {
   init_parser();
   W_TAGS = [
@@ -14423,6 +14600,7 @@ var init_jsx = __esm(() => {
     "tcPr",
     "ins",
     "del",
+    "delText",
     "commentRangeStart",
     "commentRangeEnd",
     "commentReference",
@@ -14477,18 +14655,9 @@ var init_jsx = __esm(() => {
 
 // src/core/jsx/jsx-runtime.ts
 function jsx(type, props, _key) {
-  const { children, ...rest } = props ?? {};
-  const childArgs = normalizeChildren(children);
-  const result = type(rest, ...childArgs);
+  const result = type(props);
   return result ?? new XmlNode2("#fragment");
 }
-function normalizeChildren(children) {
-  if (children === undefined)
-    return [];
-  if (Array.isArray(children))
-    return children;
-  return [children];
-}
 var jsxDEV;
 var init_jsx_runtime = __esm(() => {
   init_parser();
@@ -14501,63 +14670,191 @@ var init_jsx_dev_runtime = __esm(() => {
   init_jsx_runtime();
 });
 
-// src/cli/comments/helpers.tsx
-function nextCommentId(view) {
-  if (!view.commentsTree)
-    return "0";
-  const root = XmlNode2.findRoot(view.commentsTree, "w:comments");
-  if (!root)
-    return "0";
-  let highest = -1;
-  for (const child of root.children) {
-    if (child.tag !== "w:comment")
-      continue;
-    const idAttribute = child.getAttribute("w:id");
-    if (idAttribute == null)
-      continue;
-    const numeric = Number(idAttribute);
-    if (Number.isFinite(numeric) && numeric > highest)
-      highest = numeric;
-  }
-  return String(highest + 1);
-}
-function generateParaId() {
-  const bytes = new Uint8Array(4);
-  crypto.getRandomValues(bytes);
-  let hex = "";
-  for (const byte of bytes)
-    hex += byte.toString(16).padStart(2, "0");
-  return hex.toUpperCase();
+// src/core/track-changes/emit.tsx
+function Ins({
+  meta,
+  children
+}) {
+  return /* @__PURE__ */ jsxDEV(w.ins, {
+    "w-id": String(meta.revisionId),
+    "w-author": meta.author,
+    "w-date": meta.date,
+    children
+  }, undefined, false, undefined, this);
 }
-function authorInitials(author) {
-  const parts = author.trim().split(/\s+/).filter(Boolean);
-  if (parts.length === 0)
-    return "?";
-  const first = parts[0]?.charAt(0) ?? "";
-  const last = parts.length > 1 ? parts[parts.length - 1]?.charAt(0) ?? "" : "";
-  return (first + last).toUpperCase() || "?";
+function Del({
+  meta,
+  children
+}) {
+  return /* @__PURE__ */ jsxDEV(w.del, {
+    "w-id": String(meta.revisionId),
+    "w-author": meta.author,
+    "w-date": meta.date,
+    children
+  }, undefined, false, undefined, this);
 }
-function ensureCommentsPart(view) {
-  if (view.commentsTree) {
-    const existing = XmlNode2.findRoot(view.commentsTree, "w:comments");
-    if (existing)
-      return existing;
-  }
-  const root = /* @__PURE__ */ jsxDEV(w.comments, {
-    "xmlns:w": NS_W,
-    "xmlns:w14": NS_W14
+function markParagraphMarkAs(paragraph, kind, meta) {
+  let pPr = paragraph.findChild("w:pPr");
+  if (!pPr) {
+    pPr = /* @__PURE__ */ jsxDEV(w.pPr, {}, undefined, false, undefined, this);
+    paragraph.children.unshift(pPr);
+  }
+  let rPr = pPr.findChild("w:rPr");
+  if (!rPr) {
+    rPr = /* @__PURE__ */ jsxDEV(w.rPr, {}, undefined, false, undefined, this);
+    pPr.children.push(rPr);
+  }
+  const marker = kind === "ins" ? /* @__PURE__ */ jsxDEV(Ins, {
+    meta
+  }, undefined, false, undefined, this) : /* @__PURE__ */ jsxDEV(Del, {
+    meta
   }, undefined, false, undefined, this);
-  view.commentsTree = [root];
-  registerPart(view, {
-    partName: "word/comments.xml",
-    contentType: COMMENTS_CONTENT_TYPE,
-    relationshipType: COMMENTS_REL_TYPE,
-    target: "comments.xml"
-  });
-  return root;
+  rPr.children.push(marker);
 }
-function ensureCommentsExtPart(view) {
-  if (view.commentsExtTree) {
+var init_emit = __esm(() => {
+  init_jsx();
+  init_jsx_dev_runtime();
+});
+
+// src/core/index.ts
+var init_core = __esm(() => {
+  init_ast();
+  init_locators();
+  init_package();
+  init_parser();
+  init_track_changes();
+  init_emit();
+});
+
+// src/cli/respond.ts
+async function respond(payload) {
+  await Bun.write(Bun.stdout, `${JSON.stringify(payload)}
+`);
+}
+async function writeStdout(text) {
+  await Bun.write(Bun.stdout, text);
+}
+async function fail(code, message, hint) {
+  const payload = {
+    ok: false,
+    code,
+    error: message
+  };
+  if (hint)
+    payload.hint = hint;
+  await respond(payload);
+  return exitCodeFor(code);
+}
+function exitCodeFor(code) {
+  switch (code) {
+    case "USAGE":
+    case "INVALID_LOCATOR":
+      return EXIT.USAGE_ERROR;
+    case "FILE_NOT_FOUND":
+    case "PART_NOT_FOUND":
+    case "BLOCK_NOT_FOUND":
+    case "COMMENT_NOT_FOUND":
+    case "IMAGE_NOT_FOUND":
+    case "MATCH_NOT_FOUND":
+      return EXIT.NOT_FOUND;
+    case "NOT_A_ZIP":
+    case "TRACKED_CHANGE_CONFLICT":
+    case "UNHANDLED":
+      return EXIT.GENERAL_ERROR;
+  }
+}
+async function openOrFail(path) {
+  try {
+    return await openDocView(path);
+  } catch (err) {
+    if (err instanceof PkgError) {
+      if (err.code === "FILE_NOT_FOUND") {
+        return await fail("FILE_NOT_FOUND", err.message);
+      }
+      if (err.code === "NOT_A_ZIP")
+        return await fail("NOT_A_ZIP", err.message);
+    }
+    throw err;
+  }
+}
+async function resolveBlockOrFail(view, locator) {
+  try {
+    return resolveBlock(view, locator);
+  } catch (err) {
+    if (err instanceof LocatorResolveError) {
+      return await fail("BLOCK_NOT_FOUND", err.message);
+    }
+    throw err;
+  }
+}
+var EXIT;
+var init_respond = __esm(() => {
+  init_core();
+  EXIT = {
+    OK: 0,
+    GENERAL_ERROR: 1,
+    USAGE_ERROR: 2,
+    NOT_FOUND: 3
+  };
+});
+
+// src/cli/comments/helpers.tsx
+function nextCommentId(view) {
+  if (!view.commentsTree)
+    return "0";
+  const root = XmlNode2.findRoot(view.commentsTree, "w:comments");
+  if (!root)
+    return "0";
+  let highest = -1;
+  for (const child of root.children) {
+    if (child.tag !== "w:comment")
+      continue;
+    const idAttribute = child.getAttribute("w:id");
+    if (idAttribute == null)
+      continue;
+    const numeric = Number(idAttribute);
+    if (Number.isFinite(numeric) && numeric > highest)
+      highest = numeric;
+  }
+  return String(highest + 1);
+}
+function generateParaId() {
+  const bytes = new Uint8Array(4);
+  crypto.getRandomValues(bytes);
+  let hex = "";
+  for (const byte of bytes)
+    hex += byte.toString(16).padStart(2, "0");
+  return hex.toUpperCase();
+}
+function authorInitials(author) {
+  const parts = author.trim().split(/\s+/).filter(Boolean);
+  if (parts.length === 0)
+    return "?";
+  const first = parts[0]?.charAt(0) ?? "";
+  const last = parts.length > 1 ? parts[parts.length - 1]?.charAt(0) ?? "" : "";
+  return (first + last).toUpperCase() || "?";
+}
+function ensureCommentsPart(view) {
+  if (view.commentsTree) {
+    const existing = XmlNode2.findRoot(view.commentsTree, "w:comments");
+    if (existing)
+      return existing;
+  }
+  const root = /* @__PURE__ */ jsxDEV(w.comments, {
+    "xmlns:w": NS_W,
+    "xmlns:w14": NS_W14
+  }, undefined, false, undefined, this);
+  view.commentsTree = [root];
+  registerPart(view.relationshipsTree, view.contentTypesTree, {
+    partName: "word/comments.xml",
+    contentType: COMMENTS_CONTENT_TYPE,
+    relationshipType: COMMENTS_REL_TYPE,
+    target: "comments.xml"
+  });
+  return root;
+}
+function ensureCommentsExtPart(view) {
+  if (view.commentsExtTree) {
     const existing = XmlNode2.findRoot(view.commentsExtTree, "w15:commentsEx");
     if (existing)
       return existing;
@@ -14568,7 +14865,7 @@ function ensureCommentsExtPart(view) {
     "mc:Ignorable": "w15"
   }, undefined, false, undefined, this);
   view.commentsExtTree = [root];
-  registerPart(view, {
+  registerPart(view.relationshipsTree, view.contentTypesTree, {
     partName: "word/commentsExtended.xml",
     contentType: COMMENTS_EXT_CONTENT_TYPE,
     relationshipType: COMMENTS_EXT_REL_TYPE,
@@ -14576,46 +14873,6 @@ function ensureCommentsExtPart(view) {
   });
   return root;
 }
-function registerPart(view, part) {
-  const relationships = XmlNode2.findRoot(view.relationshipsTree, "Relationships");
-  if (relationships) {
-    const alreadyLinked = relationships.children.some((child) => child.tag === "Relationship" && child.getAttribute("Type") === part.relationshipType);
-    if (!alreadyLinked) {
-      relationships.children.push(new XmlNode2("Relationship", {
-        Id: nextRelationshipId(relationships),
-        Type: part.relationshipType,
-        Target: part.target
-      }));
-    }
-  }
-  const types = XmlNode2.findRoot(view.contentTypesTree, "Types");
-  if (types) {
-    const overrideExists = types.children.some((child) => child.tag === "Override" && child.getAttribute("PartName") === `/${part.partName}`);
-    if (!overrideExists) {
-      types.children.push(new XmlNode2("Override", {
-        PartName: `/${part.partName}`,
-        ContentType: part.contentType
-      }));
-    }
-  }
-}
-function nextRelationshipId(relationships) {
-  let highest = 0;
-  for (const child of relationships.children) {
-    if (child.tag !== "Relationship")
-      continue;
-    const id = child.getAttribute("Id");
-    if (!id)
-      continue;
-    const match = id.match(/^rId(\d+)$/);
-    if (!match)
-      continue;
-    const numeric = Number(match[1]);
-    if (Number.isFinite(numeric) && numeric > highest)
-      highest = numeric;
-  }
-  return `rId${highest + 1}`;
-}
 function paragraphTextLength(paragraph) {
   let total = 0;
   for (const child of paragraph.children) {
@@ -14636,17 +14893,46 @@ function addCommentMarkersToParagraph(paragraph, commentId, span) {
   if (range.start < 0 || range.end > total || range.start > range.end) {
     throw new SpanOutOfRangeError(`Span ${range.start}-${range.end} out of paragraph length ${total}`);
   }
-  const newChildren = [];
-  let offset = 0;
-  let placedStart = false;
-  let placedEnd = false;
-  const startMarker = /* @__PURE__ */ jsxDEV(w.commentRangeStart, {
+  placeMarkersInParagraph(paragraph, [
+    { offset: range.start, node: commentRangeStartMarker(commentId) },
+    {
+      offset: range.end,
+      node: commentRangeEndMarker(commentId),
+      follower: commentReferenceRun(commentId)
+    }
+  ]);
+}
+function addCommentRangeMarkers(startParagraph, startOffset, endParagraph, endOffset, commentId) {
+  if (startParagraph === endParagraph) {
+    addCommentMarkersToParagraph(startParagraph, commentId, {
+      start: startOffset,
+      end: endOffset
+    });
+    return;
+  }
+  placeMarkersInParagraph(startParagraph, [
+    { offset: startOffset, node: commentRangeStartMarker(commentId) }
+  ]);
+  placeMarkersInParagraph(endParagraph, [
+    {
+      offset: endOffset,
+      node: commentRangeEndMarker(commentId),
+      follower: commentReferenceRun(commentId)
+    }
+  ]);
+}
+function commentRangeStartMarker(commentId) {
+  return /* @__PURE__ */ jsxDEV(w.commentRangeStart, {
     "w-id": commentId
   }, undefined, false, undefined, this);
-  const endMarker = /* @__PURE__ */ jsxDEV(w.commentRangeEnd, {
+}
+function commentRangeEndMarker(commentId) {
+  return /* @__PURE__ */ jsxDEV(w.commentRangeEnd, {
     "w-id": commentId
   }, undefined, false, undefined, this);
-  const referenceRun = /* @__PURE__ */ jsxDEV(w.r, {
+}
+function commentReferenceRun(commentId) {
+  return /* @__PURE__ */ jsxDEV(w.r, {
     children: [
       /* @__PURE__ */ jsxDEV(w.rPr, {
         children: /* @__PURE__ */ jsxDEV(w.rStyle, {
@@ -14658,108 +14944,97 @@ function addCommentMarkersToParagraph(paragraph, commentId, span) {
       }, undefined, false, undefined, this)
     ]
   }, undefined, true, undefined, this);
-  for (const child of paragraph.children) {
-    if (child.tag !== "w:r") {
-      if (!placedStart && offset === range.start) {
-        placedStart = true;
-        if (child.tag === "w:pPr") {
-          newChildren.push(child);
-          newChildren.push(startMarker);
+}
+function placeMarkersInParagraph(paragraph, markers) {
+  if (markers.length === 0)
+    return;
+  const total = paragraphTextLength(paragraph);
+  for (const marker of markers) {
+    if (marker.offset < 0 || marker.offset > total) {
+      throw new SpanOutOfRangeError(`Marker offset ${marker.offset} out of paragraph length ${total}`);
+    }
+  }
+  const pending = markers.slice();
+  const state = { offset: 0, placedCount: 0 };
+  paragraph.children = walkAndPlace(paragraph.children, pending, true, state);
+  flushAtCurrentOffset(paragraph.children, pending, state);
+  if (state.placedCount !== markers.length) {
+    throw new SpanOutOfRangeError(`Could not place comment markers (placed ${state.placedCount} of ${markers.length})`);
+  }
+}
+function walkAndPlace(children, pending, isParagraphLevel, state) {
+  const result = [];
+  for (const child of children) {
+    if (child.tag === "w:r") {
+      const length = runTextLength(child);
+      const runStart = state.offset;
+      const runEnd = state.offset + length;
+      const splits = [];
+      for (let i = 0;i < pending.length; i++) {
+        const marker = pending[i];
+        if (!marker)
           continue;
+        if (runStart <= marker.offset && marker.offset <= runEnd) {
+          splits.push({ at: marker.offset - runStart, index: i });
         }
-        newChildren.push(startMarker);
       }
-      if (!placedEnd && offset === range.end && placedStart) {
-        placedEnd = true;
-        newChildren.push(endMarker);
-        newChildren.push(referenceRun);
+      splits.sort((left, right) => left.at - right.at || left.index - right.index);
+      if (splits.length === 0) {
+        result.push(child);
+      } else {
+        let cursor = 0;
+        for (const split of splits) {
+          if (split.at > cursor) {
+            result.push(sliceRun(child, cursor, split.at));
+          }
+          const marker = pending[split.index];
+          if (!marker)
+            continue;
+          result.push(marker.node);
+          if (marker.follower)
+            result.push(marker.follower);
+          pending[split.index] = null;
+          state.placedCount++;
+          cursor = split.at;
+        }
+        if (cursor < length) {
+          result.push(sliceRun(child, cursor, length));
+        }
       }
-      newChildren.push(child);
+      state.offset = runEnd;
       continue;
     }
-    const length = runTextLength(child);
-    const runStart = offset;
-    const runEnd = offset + length;
-    const splits = [];
-    if (!placedStart && runStart <= range.start && range.start <= runEnd) {
-      splits.push({ at: range.start - runStart, node: startMarker });
-      placedStart = true;
-    }
-    if (!placedEnd && runStart <= range.end && range.end <= runEnd) {
-      splits.push({ at: range.end - runStart, node: endMarker });
-      placedEnd = true;
-    }
-    splits.sort((leftSplit, rightSplit) => leftSplit.at - rightSplit.at);
-    if (splits.length === 0) {
-      newChildren.push(child);
-    } else {
-      let cursor = 0;
-      for (const split of splits) {
-        if (split.at > cursor) {
-          newChildren.push(sliceRun(child, cursor, split.at));
-        }
-        newChildren.push(split.node);
-        cursor = split.at;
-      }
-      if (cursor < length) {
-        newChildren.push(sliceRun(child, cursor, length));
-      }
-      if (splits.some((split) => split.node === endMarker)) {
-        newChildren.push(referenceRun);
-      }
+    if (isParagraphLevel && (child.tag === "w:ins" || child.tag === "w:del")) {
+      flushAtCurrentOffset(result, pending, state);
+      const innerChildren = walkAndPlace(child.children, pending, false, state);
+      const wrapper = new XmlNode2(child.tag, { ...child.attributes });
+      wrapper.children = innerChildren;
+      result.push(wrapper);
+      continue;
     }
-    offset = runEnd;
-  }
-  if (!placedStart && offset === range.start) {
-    newChildren.push(startMarker);
-    placedStart = true;
-  }
-  if (!placedEnd && offset === range.end) {
-    newChildren.push(endMarker);
-    newChildren.push(referenceRun);
-    placedEnd = true;
-  }
-  if (!placedStart || !placedEnd) {
-    throw new SpanOutOfRangeError(`Could not place comment markers (start placed: ${placedStart}, end placed: ${placedEnd})`);
-  }
-  paragraph.children = newChildren;
-}
-function runTextLength(run) {
-  let total = 0;
-  for (const child of run.children) {
-    if (child.tag === "w:t")
-      total += child.collectText().length;
-  }
-  return total;
-}
-function sliceRun(run, start, end) {
-  const sliced = new XmlNode2("w:r", { ...run.attributes });
-  let consumed = 0;
-  for (const child of run.children) {
-    if (child.tag === "w:t") {
-      const text = child.collectText();
-      const localStart = Math.max(0, start - consumed);
-      const localEnd = Math.min(text.length, end - consumed);
-      if (localStart < localEnd) {
-        const slicedText = new XmlNode2("w:t", { "xml:space": "preserve" });
-        slicedText.children.push(XmlNode2.textNode(text.slice(localStart, localEnd)));
-        sliced.children.push(slicedText);
-      }
-      consumed += text.length;
+    if (child.tag === "w:pPr") {
+      result.push(child);
+      flushAtCurrentOffset(result, pending, state);
       continue;
     }
-    sliced.children.push(deepCloneNode(child));
+    flushAtCurrentOffset(result, pending, state);
+    result.push(child);
   }
-  return sliced;
+  return result;
 }
-function deepCloneNode(node) {
-  const clone = new XmlNode2(node.tag, { ...node.attributes });
-  if (node.text !== undefined)
-    clone.text = node.text;
-  for (const child of node.children) {
-    clone.children.push(deepCloneNode(child));
+function flushAtCurrentOffset(out, pending, state) {
+  for (let i = 0;i < pending.length; i++) {
+    const marker = pending[i];
+    if (!marker)
+      continue;
+    if (marker.offset !== state.offset)
+      continue;
+    out.push(marker.node);
+    if (marker.follower)
+      out.push(marker.follower);
+    pending[i] = null;
+    state.placedCount++;
   }
-  return clone;
 }
 function CommentBody({
   options
@@ -14871,6 +15146,7 @@ function containsCommentReference(run, numericId) {
 var COMMENTS_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments", COMMENTS_EXT_REL_TYPE = "http://schemas.microsoft.com/office/2011/relationships/commentsExtended", COMMENTS_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml", COMMENTS_EXT_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtended+xml", NS_W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main", NS_W14 = "http://schemas.microsoft.com/office/word/2010/wordml", NS_W15 = "http://schemas.microsoft.com/office/word/2012/wordml", SpanOutOfRangeError;
 var init_helpers = __esm(() => {
   init_jsx();
+  init_package();
   init_parser();
   init_jsx_dev_runtime();
   SpanOutOfRangeError = class SpanOutOfRangeError extends Error {
@@ -14897,6 +15173,7 @@ async function run(args) {
         range: { type: "string" },
         text: { type: "string" },
         author: { type: "string" },
+        output: { type: "string", short: "o" },
         "dry-run": { type: "boolean" },
         help: { type: "boolean", short: "h" }
       }
@@ -14927,38 +15204,26 @@ async function run(args) {
     }
     throw error;
   }
-  const blockId = locator.kind === "block" ? locator.blockId : locator.kind === "blockSpan" ? locator.blockId : null;
-  if (!blockId?.startsWith("p")) {
-    return fail("INVALID_LOCATOR", "comments add supports paragraph locators only (pN or pN:start-end)", "Cross-block ranges and table-cell anchors are not yet supported.");
-  }
-  let view;
-  try {
-    view = await openDocView(path);
-  } catch (openError) {
-    if (openError instanceof PkgError) {
-      if (openError.code === "FILE_NOT_FOUND") {
-        return fail("FILE_NOT_FOUND", openError.message);
-      }
-      if (openError.code === "NOT_A_ZIP") {
-        return fail("NOT_A_ZIP", openError.message);
-      }
-    }
-    throw openError;
-  }
-  let paragraphRef;
-  try {
-    paragraphRef = resolveBlock(view, blockId);
-  } catch (error) {
-    if (error instanceof LocatorResolveError) {
-      return fail("BLOCK_NOT_FOUND", error.message);
-    }
-    throw error;
-  }
-  const span = locator.kind === "blockSpan" ? { start: locator.start, end: locator.end } : undefined;
+  if (locator.kind === "range") {
+    return runCrossBlock(parsed, path, rangeInput, locator, text);
+  }
+  const target = locatorToBlockTarget(locator);
+  if (!target) {
+    return fail("INVALID_LOCATOR", "comments add supports paragraph locators only (pN, pN:start-end, pN:S-pM:E, or tT:rRcC:pK[:start-end])", "Comments and images are not valid anchors.");
+  }
+  const blockId = target.blockId;
+  const view = await openOrFail(path);
+  if (typeof view === "number")
+    return view;
+  const paragraphRef = await resolveBlockOrFail(view, blockId);
+  if (typeof paragraphRef === "number")
+    return paragraphRef;
+  const span = target.span;
   const author = parsed.values.author ?? Bun.env.DOCX_AUTHOR ?? "";
   const date = new Date().toISOString();
   const numericId = nextCommentId(view);
   const paraId = generateParaId();
+  const outputPath = parsed.values.output;
   if (parsed.values["dry-run"]) {
     await respond({
       ok: true,
@@ -14966,7 +15231,8 @@ async function run(args) {
       dryRun: true,
       path,
       commentId: `c${numericId}`,
-      locator: rangeInput
+      locator: rangeInput,
+      ...outputPath ? { output: outputPath } : {}
     });
     return EXIT.OK;
   }
@@ -14989,34 +15255,96 @@ async function run(args) {
       text
     }
   }, undefined, false, undefined, this));
-  await saveDocView(view);
+  await saveDocView(view, outputPath);
   await respond({
     ok: true,
     operation: "comments.add",
-    path,
+    path: outputPath ?? path,
     commentId: `c${numericId}`,
     locator: rangeInput
   });
   return EXIT.OK;
 }
-var HELP = `docx comments add \u2014 anchor a new comment to a locator
-
-Usage:
-  docx comments add FILE [options]
-
-Required:
-  --range LOCATOR   Where to anchor (e.g., p3 for the whole paragraph,
-                    p3:5-20 to comment on chars 5..20 of p3)
-  --text TEXT       Comment body
-
+async function runCrossBlock(parsed, path, rangeInput, locator, text) {
+  const view = await openOrFail(path);
+  if (typeof view === "number")
+    return view;
+  const startRef = await resolveBlockOrFail(view, locator.start.blockId);
+  if (typeof startRef === "number")
+    return startRef;
+  const endRef = await resolveBlockOrFail(view, locator.end.blockId);
+  if (typeof endRef === "number")
+    return endRef;
+  const author = parsed.values.author ?? Bun.env.DOCX_AUTHOR ?? "";
+  const date = new Date().toISOString();
+  const numericId = nextCommentId(view);
+  const paraId = generateParaId();
+  const outputPath = parsed.values.output;
+  if (parsed.values["dry-run"]) {
+    await respond({
+      ok: true,
+      operation: "comments.add",
+      dryRun: true,
+      path,
+      commentId: `c${numericId}`,
+      locator: rangeInput,
+      ...outputPath ? { output: outputPath } : {}
+    });
+    return EXIT.OK;
+  }
+  try {
+    addCommentRangeMarkers(startRef.node, locator.start.offset, endRef.node, locator.end.offset, numericId);
+  } catch (error) {
+    if (error instanceof SpanOutOfRangeError) {
+      return fail("INVALID_LOCATOR", error.message);
+    }
+    throw error;
+  }
+  const commentsRoot = ensureCommentsPart(view);
+  commentsRoot.children.push(/* @__PURE__ */ jsxDEV(CommentBody, {
+    options: {
+      id: numericId,
+      author,
+      date,
+      initials: authorInitials(author),
+      paraId,
+      text
+    }
+  }, undefined, false, undefined, this));
+  await saveDocView(view, outputPath);
+  await respond({
+    ok: true,
+    operation: "comments.add",
+    path: outputPath ?? path,
+    commentId: `c${numericId}`,
+    locator: rangeInput
+  });
+  return EXIT.OK;
+}
+var HELP = `docx comments add \u2014 anchor a new comment to a locator
+
+Usage:
+  docx comments add FILE [options]
+
+Required:
+  --range LOCATOR   Where to anchor. Supports:
+                      pN              whole paragraph
+                      pN:S-E          chars S..E of pN
+                      pN:S-pM:E       chars S of pN through char E of pM (cross-paragraph)
+                      tT:rRcC:pK      whole cell paragraph
+                      tT:rRcC:pK:S-E  chars S..E of cell paragraph
+  --text TEXT       Comment body
+
 Optional:
   --author NAME     Author name (default: $DOCX_AUTHOR)
+  -o, --output PATH Write to PATH instead of overwriting FILE
   --dry-run         Print what would be added; do not write the file
   -h, --help        Show this help
 
 Examples:
   docx comments add doc.docx --range p3 --text "Reconsider this paragraph"
   docx comments add doc.docx --range p3:5-20 --text "Sharper wording?" --author "Jane"
+  docx comments add doc.docx --range p3:5-p5:10 --text "Whole section?" --author "Reviewer"
 `;
 var init_add = __esm(() => {
   init_core();
@@ -15025,53 +15353,6 @@ var init_add = __esm(() => {
   init_jsx_dev_runtime();
 });
 
-// src/cli/comments/trash.ts
-import { dirname, join } from "path";
-function trashPathFor(docPath) {
-  return join(dirname(docPath), TRASH_DIR, TRASH_FILE);
-}
-async function readTrash(docPath) {
-  const path = trashPathFor(docPath);
-  const file = Bun.file(path);
-  if (!await file.exists()) {
-    return { version: TRASH_VERSION, entries: [] };
-  }
-  const parsed = await file.json();
-  if (parsed.version !== TRASH_VERSION) {
-    return { version: TRASH_VERSION, entries: [] };
-  }
-  return parsed;
-}
-async function writeTrash(docPath, trash) {
-  const path = trashPathFor(docPath);
-  await Bun.write(path, `${JSON.stringify(trash, null, 2)}
-`);
-}
-async function pushTrashEntry(docPath, entry) {
-  const trash = await readTrash(docPath);
-  trash.entries.push(entry);
-  await writeTrash(docPath, trash);
-}
-async function popTrashEntry(docPath, commentId) {
-  const trash = await readTrash(docPath);
-  const fileName = docPath.split("/").pop() ?? docPath;
-  for (let index = trash.entries.length - 1;index >= 0; index--) {
-    const entry = trash.entries[index];
-    if (!entry)
-      continue;
-    if (entry.file !== fileName)
-      continue;
-    if (entry.commentId !== commentId)
-      continue;
-    trash.entries.splice(index, 1);
-    await writeTrash(docPath, trash);
-    return entry;
-  }
-  return;
-}
-var TRASH_VERSION = 1, TRASH_DIR = ".docx-cli", TRASH_FILE = "trash.json";
-var init_trash = () => {};
-
 // src/cli/comments/delete.ts
 var exports_delete = {};
 __export(exports_delete, {
@@ -15086,6 +15367,7 @@ async function run2(args) {
       allowPositionals: true,
       options: {
         id: { type: "string" },
+        output: { type: "string", short: "o" },
         "dry-run": { type: "boolean" },
         help: { type: "boolean", short: "h" }
       }
@@ -15106,49 +15388,26 @@ async function run2(args) {
     return fail("USAGE", "Missing --id COMMENT_ID", HELP2);
   const numericId = idInput.startsWith("c") ? idInput.slice(1) : idInput;
   const commentId = `c${numericId}`;
-  let view;
-  try {
-    view = await openDocView(path);
-  } catch (openError) {
-    if (openError instanceof PkgError) {
-      if (openError.code === "FILE_NOT_FOUND") {
-        return fail("FILE_NOT_FOUND", openError.message);
-      }
-      if (openError.code === "NOT_A_ZIP") {
-        return fail("NOT_A_ZIP", openError.message);
-      }
-    }
-    throw openError;
-  }
+  const view = await openOrFail(path);
+  if (typeof view === "number")
+    return view;
   const commentReference = findCommentByNumericId(view, numericId);
   if (!commentReference) {
     return fail("COMMENT_NOT_FOUND", `Comment not found: ${commentId}`);
   }
-  const anchor = view.doc.comments.find((c) => c.id === commentId)?.anchor;
-  if (!anchor) {
-    return fail("COMMENT_NOT_FOUND", `Anchor not found for ${commentId}`);
-  }
+  const outputPath = parsed.values.output;
   if (parsed.values["dry-run"]) {
     await respond({
       ok: true,
       operation: "comments.delete",
       dryRun: true,
       path,
-      commentId
+      commentId,
+      ...outputPath ? { output: outputPath } : {}
     });
     return EXIT.OK;
   }
-  const commentXml = XmlNode2.serialize([commentReference.node]);
   const paraId = findCommentParaId(view, commentId);
-  const extXml = paraId ? extractExtEntryXml(view, paraId) : null;
-  await pushTrashEntry(path, {
-    file: path.split("/").pop() ?? path,
-    deletedAt: new Date().toISOString(),
-    commentId,
-    anchor,
-    commentXml,
-    extXml
-  });
   const commentIndex = commentReference.parent.indexOf(commentReference.node);
   if (commentIndex !== -1)
     commentReference.parent.splice(commentIndex, 1);
@@ -15159,28 +15418,15 @@ async function run2(args) {
     }
   }
   removeCommentMarkers(view.documentTree, numericId);
-  await saveDocView(view);
+  await saveDocView(view, outputPath);
   await respond({
     ok: true,
     operation: "comments.delete",
-    path,
+    path: outputPath ?? path,
     commentId
   });
   return EXIT.OK;
 }
-function extractExtEntryXml(view, paraId) {
-  if (!view.commentsExtTree)
-    return null;
-  const root = XmlNode2.findRoot(view.commentsExtTree, "w15:commentsEx");
-  if (!root)
-    return null;
-  for (const child of root.children) {
-    if (child.tag === "w15:commentEx" && child.getAttribute("w15:paraId") === paraId) {
-      return XmlNode2.serialize([child]);
-    }
-  }
-  return null;
-}
 var HELP2 = `docx comments delete \u2014 remove a comment
 
 Usage:
@@ -15190,12 +15436,10 @@ Required:
   --id ID           Comment id (e.g., c0)
 
 Optional:
+  -o, --output PATH Write to PATH instead of overwriting FILE
   --dry-run         Print what would be removed; do not write the file
   -h, --help        Show this help
 
-The deleted comment is journaled to <dir>/.docx-cli/trash.json so it can
-be brought back via "docx comments restore".
-
 Examples:
   docx comments delete doc.docx --id c2
 `;
@@ -15204,7 +15448,6 @@ var init_delete = __esm(() => {
   init_parser();
   init_respond();
   init_helpers();
-  init_trash();
 });
 
 // src/cli/comments/list.ts
@@ -15236,20 +15479,9 @@ async function run3(args) {
   const path = parsed.positionals[0];
   if (!path)
     return fail("USAGE", "Missing FILE argument", HELP3);
-  let view;
-  try {
-    view = await openDocView(path);
-  } catch (openError) {
-    if (openError instanceof PkgError) {
-      if (openError.code === "FILE_NOT_FOUND") {
-        return fail("FILE_NOT_FOUND", openError.message);
-      }
-      if (openError.code === "NOT_A_ZIP") {
-        return fail("NOT_A_ZIP", openError.message);
-      }
-    }
-    throw openError;
-  }
+  const view = await openOrFail(path);
+  if (typeof view === "number")
+    return view;
   let comments = view.doc.comments;
   if (!parsed.values["include-resolved"]) {
     comments = comments.filter((comment) => !comment.resolved);
@@ -15293,7 +15525,6 @@ Examples:
   docx comments list doc.docx --include-resolved | jq '.[] | select(.author == "Jane")'
 `;
 var init_list = __esm(() => {
-  init_core();
   init_respond();
 });
 
@@ -15313,6 +15544,7 @@ async function run4(args) {
         to: { type: "string" },
         text: { type: "string" },
         author: { type: "string" },
+        output: { type: "string", short: "o" },
         "dry-run": { type: "boolean" },
         help: { type: "boolean", short: "h" }
       }
@@ -15335,20 +15567,9 @@ async function run4(args) {
   if (!text)
     return fail("USAGE", "Missing --text TEXT", HELP4);
   const parentNumericId = parentInput.startsWith("c") ? parentInput.slice(1) : parentInput;
-  let view;
-  try {
-    view = await openDocView(path);
-  } catch (openError) {
-    if (openError instanceof PkgError) {
-      if (openError.code === "FILE_NOT_FOUND") {
-        return fail("FILE_NOT_FOUND", openError.message);
-      }
-      if (openError.code === "NOT_A_ZIP") {
-        return fail("NOT_A_ZIP", openError.message);
-      }
-    }
-    throw openError;
-  }
+  const view = await openOrFail(path);
+  if (typeof view === "number")
+    return view;
   const parentReference = findCommentByNumericId(view, parentNumericId);
   if (!parentReference) {
     return fail("COMMENT_NOT_FOUND", `Parent comment not found: c${parentNumericId}`);
@@ -15361,6 +15582,7 @@ async function run4(args) {
   const date = new Date().toISOString();
   const numericId = nextCommentId(view);
   const replyParaId = generateParaId();
+  const outputPath = parsed.values.output;
   if (parsed.values["dry-run"]) {
     await respond({
       ok: true,
@@ -15368,7 +15590,8 @@ async function run4(args) {
       dryRun: true,
       path,
       commentId: `c${numericId}`,
-      parentId: `c${parentNumericId}`
+      parentId: `c${parentNumericId}`,
+      ...outputPath ? { output: outputPath } : {}
     });
     return EXIT.OK;
   }
@@ -15389,11 +15612,11 @@ async function run4(args) {
     "w15:paraIdParent": parentParaId,
     "w15:done": "0"
   }));
-  await saveDocView(view);
+  await saveDocView(view, outputPath);
   await respond({
     ok: true,
     operation: "comments.reply",
-    path,
+    path: outputPath ?? path,
     commentId: `c${numericId}`,
     parentId: `c${parentNumericId}`
   });
@@ -15410,6 +15633,7 @@ Required:
 
 Optional:
   --author NAME     Author name (default: $DOCX_AUTHOR)
+  -o, --output PATH Write to PATH instead of overwriting FILE
   --dry-run         Print what would be added; do not write the file
   -h, --help        Show this help
 
@@ -15439,6 +15663,7 @@ async function run5(args) {
       options: {
         id: { type: "string" },
         unset: { type: "boolean" },
+        output: { type: "string", short: "o" },
         "dry-run": { type: "boolean" },
         help: { type: "boolean", short: "h" }
       }
@@ -15459,20 +15684,9 @@ async function run5(args) {
     return fail("USAGE", "Missing --id COMMENT_ID", HELP5);
   const numericId = idInput.startsWith("c") ? idInput.slice(1) : idInput;
   const resolved = !parsed.values.unset;
-  let view;
-  try {
-    view = await openDocView(path);
-  } catch (openError) {
-    if (openError instanceof PkgError) {
-      if (openError.code === "FILE_NOT_FOUND") {
-        return fail("FILE_NOT_FOUND", openError.message);
-      }
-      if (openError.code === "NOT_A_ZIP") {
-        return fail("NOT_A_ZIP", openError.message);
-      }
-    }
-    throw openError;
-  }
+  const view = await openOrFail(path);
+  if (typeof view === "number")
+    return view;
   const commentReference = findCommentByNumericId(view, numericId);
   if (!commentReference) {
     return fail("COMMENT_NOT_FOUND", `Comment not found: c${numericId}`);
@@ -15481,6 +15695,7 @@ async function run5(args) {
   if (!paraId) {
     return fail("COMMENT_NOT_FOUND", `Comment c${numericId} could not be assigned a w14:paraId.`);
   }
+  const outputPath = parsed.values.output;
   if (parsed.values["dry-run"]) {
     await respond({
       ok: true,
@@ -15488,7 +15703,8 @@ async function run5(args) {
       dryRun: true,
       path,
       commentId: `c${numericId}`,
-      resolved
+      resolved,
+      ...outputPath ? { output: outputPath } : {}
     });
     return EXIT.OK;
   }
@@ -15502,11 +15718,11 @@ async function run5(args) {
     entry.setAttribute("w15:done", "1");
   else
     delete entry.attributes["w15:done"];
-  await saveDocView(view);
+  await saveDocView(view, outputPath);
   await respond({
     ok: true,
     operation: "comments.resolve",
-    path,
+    path: outputPath ?? path,
     commentId: `c${numericId}`,
     resolved
   });
@@ -15522,6 +15738,7 @@ Required:
 
 Optional:
   --unset           Mark unresolved instead of resolved
+  -o, --output PATH Write to PATH instead of overwriting FILE
   --dry-run         Print what would change; do not write the file
   -h, --help        Show this help
 
@@ -15536,147 +15753,15 @@ var init_resolve2 = __esm(() => {
   init_helpers();
 });
 
-// src/cli/comments/restore.ts
-var exports_restore = {};
-__export(exports_restore, {
-  run: () => run6
-});
-import { parseArgs as parseArgs6 } from "util";
-async function run6(args) {
-  let parsed;
-  try {
-    parsed = parseArgs6({
-      args,
-      allowPositionals: true,
-      options: {
-        id: { type: "string" },
-        "dry-run": { type: "boolean" },
-        help: { type: "boolean", short: "h" }
-      }
-    });
-  } catch (parseError) {
-    const message = parseError instanceof Error ? parseError.message : String(parseError);
-    return fail("USAGE", message, HELP6);
-  }
-  if (parsed.values.help) {
-    await writeStdout(HELP6);
-    return EXIT.OK;
-  }
-  const path = parsed.positionals[0];
-  if (!path)
-    return fail("USAGE", "Missing FILE argument", HELP6);
-  const idInput = parsed.values.id;
-  if (!idInput)
-    return fail("USAGE", "Missing --id COMMENT_ID", HELP6);
-  const commentId = idInput.startsWith("c") ? idInput : `c${idInput}`;
-  const numericId = commentId.slice(1);
-  if (parsed.values["dry-run"]) {
-    await respond({
-      ok: true,
-      operation: "comments.restore",
-      dryRun: true,
-      path,
-      commentId
-    });
-    return EXIT.OK;
-  }
-  const entry = await popTrashEntry(path, commentId);
-  if (!entry) {
-    return fail("COMMENT_NOT_FOUND", `No trashed entry for ${commentId} in ${path}`, "Trash lives at <dir>/.docx-cli/trash.json \u2014 make sure it's the same directory.");
-  }
-  if (entry.anchor.startBlockId !== entry.anchor.endBlockId) {
-    return fail("USAGE", "Cross-block comment restore is not yet supported", "v1 supports restoring single-paragraph comment anchors only.");
-  }
-  let view;
-  try {
-    view = await openDocView(path);
-  } catch (openError) {
-    if (openError instanceof PkgError) {
-      if (openError.code === "FILE_NOT_FOUND") {
-        return fail("FILE_NOT_FOUND", openError.message);
-      }
-      if (openError.code === "NOT_A_ZIP") {
-        return fail("NOT_A_ZIP", openError.message);
-      }
-    }
-    throw openError;
-  }
-  const blockId = entry.anchor.startBlockId;
-  const block = view.blockReferences.get(blockId);
-  if (!block) {
-    return fail("BLOCK_NOT_FOUND", `Original anchor block ${blockId} no longer exists`);
-  }
-  const span = {
-    start: entry.anchor.startOffset,
-    end: entry.anchor.endOffset
-  };
-  try {
-    addCommentMarkersToParagraph(block.node, numericId, span);
-  } catch (error) {
-    if (error instanceof SpanOutOfRangeError) {
-      return fail("INVALID_LOCATOR", `Saved span no longer fits the block: ${error.message}`);
-    }
-    throw error;
-  }
-  const commentNodes = XmlNode2.parse(entry.commentXml);
-  const commentNode = commentNodes[0];
-  if (!commentNode) {
-    return fail("USAGE", "Trashed commentXml is empty");
-  }
-  const commentsRoot = ensureCommentsPart(view);
-  commentsRoot.children.push(commentNode);
-  if (entry.extXml) {
-    const extNodes = XmlNode2.parse(entry.extXml);
-    const extNode = extNodes[0];
-    if (extNode) {
-      const extRoot = ensureCommentsExtPart(view);
-      extRoot.children.push(extNode);
-    }
-  }
-  await saveDocView(view);
-  await respond({
-    ok: true,
-    operation: "comments.restore",
-    path,
-    commentId
-  });
-  return EXIT.OK;
-}
-var HELP6 = `docx comments restore \u2014 undo a recent delete
-
-Usage:
-  docx comments restore FILE --id cN [options]
-
-Required:
-  --id ID           Comment id to restore (e.g., c0)
-
-Optional:
-  --dry-run         Print what would be restored; do not write the file
-  -h, --help        Show this help
-
-Pulls the most recent matching entry from <dir>/.docx-cli/trash.json
-and re-anchors the comment at its original location.
-
-Examples:
-  docx comments restore doc.docx --id c2
-`;
-var init_restore = __esm(() => {
-  init_core();
-  init_parser();
-  init_respond();
-  init_helpers();
-  init_trash();
-});
-
 // src/cli/comments/index.ts
 var exports_comments = {};
 __export(exports_comments, {
-  run: () => run7
+  run: () => run6
 });
-async function run7(args) {
+async function run6(args) {
   const verb = args[0];
   if (!verb || verb === "--help" || verb === "-h" || verb === "help") {
-    await writeStdout(HELP7);
+    await writeStdout(HELP6);
     return verb ? 0 : 2;
   }
   const loader = SUBCOMMANDS[verb];
@@ -15686,7 +15771,7 @@ async function run7(args) {
   const module_ = await loader();
   return module_.run(args.slice(1));
 }
-var SUBCOMMANDS, HELP7 = `docx comments \u2014 manage Word comments
+var SUBCOMMANDS, HELP6 = `docx comments \u2014 manage Word comments
 
 Usage:
   docx comments <verb> FILE [options]
@@ -15697,7 +15782,6 @@ Verbs:
   list     Print existing comments as JSON
   resolve  Mark a comment resolved
   delete   Remove a comment
-  restore  Restore a recently deleted comment
 
 Run "docx comments <verb> --help" for verb-specific help.
 `;
@@ -15708,8 +15792,7 @@ var init_comments = __esm(() => {
     delete: () => Promise.resolve().then(() => (init_delete(), exports_delete)),
     list: () => Promise.resolve().then(() => (init_list(), exports_list)),
     reply: () => Promise.resolve().then(() => (init_reply(), exports_reply)),
-    resolve: () => Promise.resolve().then(() => (init_resolve2(), exports_resolve)),
-    restore: () => Promise.resolve().then(() => (init_restore(), exports_restore))
+    resolve: () => Promise.resolve().then(() => (init_resolve2(), exports_resolve))
   };
 });
 
@@ -15805,13 +15888,13 @@ var init_template = __esm(() => {
 // src/cli/create/index.tsx
 var exports_create = {};
 __export(exports_create, {
-  run: () => run8
+  run: () => run7
 });
-import { parseArgs as parseArgs7 } from "util";
-async function run8(args) {
+import { parseArgs as parseArgs6 } from "util";
+async function run7(args) {
   let parsed;
   try {
-    parsed = parseArgs7({
+    parsed = parseArgs6({
       args,
       allowPositionals: true,
       options: {
@@ -15823,20 +15906,20 @@ async function run8(args) {
       }
     });
   } catch (e) {
-    return fail("USAGE", e instanceof Error ? e.message : String(e), HELP8);
+    return fail("USAGE", e instanceof Error ? e.message : String(e), HELP7);
   }
   if (parsed.values.help) {
-    await writeStdout(HELP8);
+    await writeStdout(HELP7);
     return EXIT.OK;
   }
   const path = parsed.positionals[0];
   if (!path) {
-    return fail("USAGE", "Missing FILE argument", HELP8);
+    return fail("USAGE", "Missing FILE argument", HELP7);
   }
   if (await Bun.file(path).exists() && !parsed.values.force) {
     return fail("USAGE", `File already exists: ${path}`, "Pass --force to overwrite.");
   }
-  const author = parsed.values.author ?? process.env.DOCX_AUTHOR ?? "";
+  const author = parsed.values.author ?? Bun.env.DOCX_AUTHOR ?? "";
   const title = parsed.values.title ?? "";
   const text = parsed.values.text;
   const now = new Date().toISOString();
@@ -15851,7 +15934,7 @@ async function run8(args) {
     compression: "DEFLATE",
     compressionOptions: { level: 6 }
   });
-  await Bun.write(path, buf);
+  await writeAtomic(path, buf);
   await respond({
     ok: true,
     operation: "create",
@@ -15861,7 +15944,7 @@ async function run8(args) {
   });
   return EXIT.OK;
 }
-var import_jszip2, HELP8 = `docx create \u2014 create a new minimal .docx
+var import_jszip2, HELP7 = `docx create \u2014 create a new minimal .docx
 
 Usage:
   docx create FILE [options]
@@ -15878,86 +15961,116 @@ Examples:
   docx create out.docx --title "Spec" --author "Claude" --text "First paragraph."
 `;
 var init_create = __esm(() => {
+  init_package();
   init_respond();
   init_template();
   import_jszip2 = __toESM(require_lib3(), 1);
 });
 
-// src/cli/delete/index.ts
+// src/cli/delete/index.tsx
 var exports_delete2 = {};
 __export(exports_delete2, {
-  run: () => run9
+  run: () => run8
 });
-import { parseArgs as parseArgs8 } from "util";
-async function run9(args) {
+import { parseArgs as parseArgs7 } from "util";
+async function run8(args) {
   let parsed;
   try {
-    parsed = parseArgs8({
+    parsed = parseArgs7({
       args,
       allowPositionals: true,
       options: {
         at: { type: "string" },
+        output: { type: "string", short: "o" },
         "dry-run": { type: "boolean" },
         help: { type: "boolean", short: "h" }
       }
     });
   } catch (parseError) {
     const message = parseError instanceof Error ? parseError.message : String(parseError);
-    return fail("USAGE", message, HELP9);
+    return fail("USAGE", message, HELP8);
   }
   if (parsed.values.help) {
-    await writeStdout(HELP9);
+    await writeStdout(HELP8);
     return EXIT.OK;
   }
   const path = parsed.positionals[0];
   if (!path)
-    return fail("USAGE", "Missing FILE argument", HELP9);
+    return fail("USAGE", "Missing FILE argument", HELP8);
   const at = parsed.values.at;
   if (!at)
-    return fail("USAGE", "Missing --at LOCATOR", HELP9);
-  let view;
-  try {
-    view = await openDocView(path);
-  } catch (openError) {
-    if (openError instanceof PkgError) {
-      if (openError.code === "FILE_NOT_FOUND") {
-        return fail("FILE_NOT_FOUND", openError.message);
-      }
-      if (openError.code === "NOT_A_ZIP") {
-        return fail("NOT_A_ZIP", openError.message);
-      }
-    }
-    throw openError;
-  }
-  let blockRef;
-  try {
-    blockRef = resolveBlock(view, at);
-  } catch (resolveError) {
-    if (resolveError instanceof LocatorResolveError) {
-      return fail("BLOCK_NOT_FOUND", resolveError.message);
-    }
-    throw resolveError;
-  }
+    return fail("USAGE", "Missing --at LOCATOR", HELP8);
+  const view = await openOrFail(path);
+  if (typeof view === "number")
+    return view;
+  const blockRef = await resolveBlockOrFail(view, at);
+  if (typeof blockRef === "number")
+    return blockRef;
   const targetIndex = blockRef.parent.indexOf(blockRef.node);
   if (targetIndex === -1) {
     return fail("BLOCK_NOT_FOUND", "Block reference is stale (parent does not contain it)");
   }
+  const outputPath = parsed.values.output;
   if (parsed.values["dry-run"]) {
     await respond({
       ok: true,
       operation: "delete",
       dryRun: true,
       path,
-      locator: at
+      locator: at,
+      ...outputPath ? { output: outputPath } : {}
     });
     return EXIT.OK;
   }
-  blockRef.parent.splice(targetIndex, 1);
-  await saveDocView(view);
-  await respond({ ok: true, operation: "delete", path, locator: at });
+  if (isTrackChangesEnabled(view)) {
+    if (blockRef.node.tag !== "w:p") {
+      return fail("TRACKED_CHANGE_CONFLICT", "Tracked deletion of non-paragraph blocks (e.g., tables) is not supported", "Use `docx track-changes off` first, or delete table contents row-by-row.");
+    }
+    applyTrackedDeletion(view, blockRef.node);
+  } else {
+    blockRef.parent.splice(targetIndex, 1);
+  }
+  await saveDocView(view, outputPath);
+  await respond({
+    ok: true,
+    operation: "delete",
+    path: outputPath ?? path,
+    locator: at
+  });
   return EXIT.OK;
 }
-var HELP9 = `docx delete \u2014 remove a block at a locator
+function applyTrackedDeletion(view, paragraph) {
+  const allocator = createRevisionAllocator(view);
+  const baseMeta = { author: resolveAuthor(), date: resolveDate() };
+  const mintMeta = () => ({
+    ...baseMeta,
+    revisionId: allocator.next()
+  });
+  const newChildren = [];
+  let runBuffer = [];
+  const flush = () => {
+    if (runBuffer.length === 0)
+      return;
+    const converted = runBuffer.map((run9) => convertTextToDelText(run9));
+    newChildren.push(/* @__PURE__ */ jsxDEV(Del, {
+      meta: mintMeta(),
+      children: converted
+    }, undefined, false, undefined, this));
+    runBuffer = [];
+  };
+  for (const child of paragraph.children) {
+    if (child.tag === "w:r") {
+      runBuffer.push(child);
+      continue;
+    }
+    flush();
+    newChildren.push(child);
+  }
+  flush();
+  paragraph.children = newChildren;
+  markParagraphMarkAs(paragraph, "del", mintMeta());
+}
+var HELP8 = `docx delete \u2014 remove a block at a locator
 
 Usage:
   docx delete FILE [options]
@@ -15965,6 +16078,7 @@ Usage:
 Locator (required):
   --at LOCATOR      Block to remove (e.g., p3, t0)
 
+  -o, --output PATH Write to PATH instead of overwriting FILE
   --dry-run         Print what would be removed; do not write the file
   -h, --help        Show this help
 
@@ -15975,6 +16089,7 @@ Examples:
 var init_delete2 = __esm(() => {
   init_core();
   init_respond();
+  init_jsx_dev_runtime();
 });
 
 // src/cli/insert/emit.tsx
@@ -15986,68 +16101,68 @@ function Paragraph(props) {
       /* @__PURE__ */ jsxDEV(ParagraphProperties, {
         options: { style, alignment }
       }, undefined, false, undefined, this),
-      runs.map((run10) => /* @__PURE__ */ jsxDEV(RunElement, {
-        run: run10
+      runs.map((run9) => /* @__PURE__ */ jsxDEV(RunElement, {
+        run: run9
       }, undefined, false, undefined, this))
     ]
   }, undefined, true, undefined, this);
 }
-function RunElement({ run: run10 }) {
-  if (run10.type === "text")
+function RunElement({ run: run9 }) {
+  if (run9.type === "text")
     return /* @__PURE__ */ jsxDEV(TextRunElement, {
-      run: run10
+      run: run9
     }, undefined, false, undefined, this);
-  if (run10.type === "break") {
+  if (run9.type === "break") {
     return /* @__PURE__ */ jsxDEV(w.r, {
       children: /* @__PURE__ */ jsxDEV(w.br, {
-        "w-type": run10.kind === "line" ? undefined : run10.kind
+        "w-type": run9.kind === "line" ? undefined : run9.kind
       }, undefined, false, undefined, this)
     }, undefined, false, undefined, this);
   }
-  if (run10.type === "tab") {
+  if (run9.type === "tab") {
     return /* @__PURE__ */ jsxDEV(w.r, {
       children: /* @__PURE__ */ jsxDEV(w.tab, {}, undefined, false, undefined, this)
     }, undefined, false, undefined, this);
   }
-  throw new Error(`Cannot emit run of type "${run10.type}" \u2014 image emission lives in the images command.`);
+  throw new Error(`Cannot emit run of type "${run9.type}" \u2014 image emission lives in the images command.`);
 }
-function TextRunElement({ run: run10 }) {
+function TextRunElement({ run: run9 }) {
   return /* @__PURE__ */ jsxDEV(w.r, {
     children: [
       /* @__PURE__ */ jsxDEV(RunProperties, {
-        run: run10
+        run: run9
       }, undefined, false, undefined, this),
       /* @__PURE__ */ jsxDEV(w.t, {
         "xml:space": "preserve",
-        children: run10.text
+        children: run9.text
       }, undefined, false, undefined, this)
     ]
   }, undefined, true, undefined, this);
 }
-function RunProperties({ run: run10 }) {
-  const isEmpty = FORMATTING_KEYS.every((key) => run10[key] == null);
+function RunProperties({ run: run9 }) {
+  const isEmpty = FORMATTING_KEYS.every((key) => run9[key] == null);
   if (isEmpty)
     return null;
   return /* @__PURE__ */ jsxDEV(w.rPr, {
     children: [
-      run10.color && /* @__PURE__ */ jsxDEV(w.color, {
-        "w-val": run10.color
+      run9.color && /* @__PURE__ */ jsxDEV(w.color, {
+        "w-val": run9.color
       }, undefined, false, undefined, this),
-      run10.highlight && /* @__PURE__ */ jsxDEV(w.highlight, {
-        "w-val": run10.highlight
+      run9.highlight && /* @__PURE__ */ jsxDEV(w.highlight, {
+        "w-val": run9.highlight
       }, undefined, false, undefined, this),
-      run10.bold && /* @__PURE__ */ jsxDEV(w.b, {}, undefined, false, undefined, this),
-      run10.italic && /* @__PURE__ */ jsxDEV(w.i, {}, undefined, false, undefined, this),
-      run10.underline && /* @__PURE__ */ jsxDEV(w.u, {
-        "w-val": run10.underline
+      run9.bold && /* @__PURE__ */ jsxDEV(w.b, {}, undefined, false, undefined, this),
+      run9.italic && /* @__PURE__ */ jsxDEV(w.i, {}, undefined, false, undefined, this),
+      run9.underline && /* @__PURE__ */ jsxDEV(w.u, {
+        "w-val": run9.underline
       }, undefined, false, undefined, this),
-      run10.strike && /* @__PURE__ */ jsxDEV(w.strike, {}, undefined, false, undefined, this),
-      run10.font && /* @__PURE__ */ jsxDEV(w.rFonts, {
-        "w-ascii": run10.font,
-        "w-hAnsi": run10.font
+      run9.strike && /* @__PURE__ */ jsxDEV(w.strike, {}, undefined, false, undefined, this),
+      run9.font && /* @__PURE__ */ jsxDEV(w.rFonts, {
+        "w-ascii": run9.font,
+        "w-hAnsi": run9.font
       }, undefined, false, undefined, this),
-      run10.sizeHalfPoints !== undefined && /* @__PURE__ */ jsxDEV(w.sz, {
-        "w-val": String(run10.sizeHalfPoints)
+      run9.sizeHalfPoints !== undefined && /* @__PURE__ */ jsxDEV(w.sz, {
+        "w-val": String(run9.sizeHalfPoints)
       }, undefined, false, undefined, this)
     ]
   }, undefined, true, undefined, this);
@@ -16079,7 +16194,7 @@ function textRunFromProps(props) {
   return { type: "text", text, ...formatting };
 }
 var FORMATTING_KEYS;
-var init_emit = __esm(() => {
+var init_emit2 = __esm(() => {
   init_jsx();
   init_jsx_dev_runtime();
   FORMATTING_KEYS = [
@@ -16097,13 +16212,13 @@ var init_emit = __esm(() => {
 // src/cli/edit/index.tsx
 var exports_edit = {};
 __export(exports_edit, {
-  run: () => run10
+  run: () => run9
 });
-import { parseArgs as parseArgs9 } from "util";
-async function run10(args) {
+import { parseArgs as parseArgs8 } from "util";
+async function run9(args) {
   let parsed;
   try {
-    parsed = parseArgs9({
+    parsed = parseArgs8({
       args,
       allowPositionals: true,
       options: {
@@ -16115,31 +16230,32 @@ async function run10(args) {
         color: { type: "string" },
         bold: { type: "boolean" },
         italic: { type: "boolean" },
+        output: { type: "string", short: "o" },
         "dry-run": { type: "boolean" },
         help: { type: "boolean", short: "h" }
       }
     });
   } catch (parseError) {
     const message = parseError instanceof Error ? parseError.message : String(parseError);
-    return fail("USAGE", message, HELP10);
+    return fail("USAGE", message, HELP9);
   }
   if (parsed.values.help) {
-    await writeStdout(HELP10);
+    await writeStdout(HELP9);
     return EXIT.OK;
   }
   const path = parsed.positionals[0];
   if (!path)
-    return fail("USAGE", "Missing FILE argument", HELP10);
+    return fail("USAGE", "Missing FILE argument", HELP9);
   const at = parsed.values.at;
   if (!at)
-    return fail("USAGE", "Missing --at LOCATOR", HELP10);
+    return fail("USAGE", "Missing --at LOCATOR", HELP9);
   const text = parsed.values.text;
   const runsJson = parsed.values.runs;
   if (!text && !runsJson) {
-    return fail("USAGE", "Missing content: pass --text or --runs", HELP10);
+    return fail("USAGE", "Missing content: pass --text or --runs", HELP9);
   }
   if (text && runsJson) {
-    return fail("USAGE", "Pass either --text or --runs, not both", HELP10);
+    return fail("USAGE", "Pass either --text or --runs, not both", HELP9);
   }
   const paragraphOptions = {};
   const styleValue = parsed.values.style;
@@ -16152,29 +16268,12 @@ async function run10(args) {
     }
     paragraphOptions.alignment = alignmentValue;
   }
-  let view;
-  try {
-    view = await openDocView(path);
-  } catch (openError) {
-    if (openError instanceof PkgError) {
-      if (openError.code === "FILE_NOT_FOUND") {
-        return fail("FILE_NOT_FOUND", openError.message);
-      }
-      if (openError.code === "NOT_A_ZIP") {
-        return fail("NOT_A_ZIP", openError.message);
-      }
-    }
-    throw openError;
-  }
-  let blockRef;
-  try {
-    blockRef = resolveBlock(view, at);
-  } catch (resolveError) {
-    if (resolveError instanceof LocatorResolveError) {
-      return fail("BLOCK_NOT_FOUND", resolveError.message);
-    }
-    throw resolveError;
-  }
+  const view = await openOrFail(path);
+  if (typeof view === "number")
+    return view;
+  const blockRef = await resolveBlockOrFail(view, at);
+  if (typeof blockRef === "number")
+    return blockRef;
   let paragraphNode;
   if (text !== undefined) {
     const color = parsed.values.color;
@@ -16205,22 +16304,81 @@ async function run10(args) {
   if (targetIndex === -1) {
     return fail("BLOCK_NOT_FOUND", "Block reference is stale (parent does not contain it)");
   }
+  const outputPath = parsed.values.output;
   if (parsed.values["dry-run"]) {
     await respond({
       ok: true,
       operation: "edit",
       dryRun: true,
       path,
-      locator: at
+      locator: at,
+      ...outputPath ? { output: outputPath } : {}
     });
     return EXIT.OK;
   }
-  blockRef.parent.splice(targetIndex, 1, paragraphNode);
-  await saveDocView(view);
-  await respond({ ok: true, operation: "edit", path, locator: at });
+  if (isTrackChangesEnabled(view)) {
+    applyTrackedEdit(view, blockRef.node, paragraphNode);
+  } else {
+    blockRef.parent.splice(targetIndex, 1, paragraphNode);
+  }
+  await saveDocView(view, outputPath);
+  await respond({
+    ok: true,
+    operation: "edit",
+    path: outputPath ?? path,
+    locator: at
+  });
   return EXIT.OK;
 }
-var HELP10 = `docx edit \u2014 replace a paragraph at a locator
+function applyTrackedEdit(view, existingParagraph, newParagraph) {
+  const allocator = createRevisionAllocator(view);
+  const baseMeta = { author: resolveAuthor(), date: resolveDate() };
+  const mintMeta = () => ({
+    ...baseMeta,
+    revisionId: allocator.next()
+  });
+  const oldRuns = [];
+  const oldNonRuns = [];
+  for (const child of existingParagraph.children) {
+    if (child.tag === "w:r")
+      oldRuns.push(child);
+    else
+      oldNonRuns.push(child);
+  }
+  let newPPr = null;
+  const newRuns = [];
+  for (const child of newParagraph.children) {
+    if (child.tag === "w:pPr")
+      newPPr = child;
+    else if (child.tag === "w:r")
+      newRuns.push(child);
+  }
+  const rebuilt = [];
+  if (newPPr) {
+    rebuilt.push(newPPr);
+    for (const child of oldNonRuns) {
+      if (child.tag !== "w:pPr")
+        rebuilt.push(child);
+    }
+  } else {
+    rebuilt.push(...oldNonRuns);
+  }
+  if (oldRuns.length > 0) {
+    const deletedRuns = oldRuns.map((run10) => convertTextToDelText(run10));
+    rebuilt.push(/* @__PURE__ */ jsxDEV(Del, {
+      meta: mintMeta(),
+      children: deletedRuns
+    }, undefined, false, undefined, this));
+  }
+  if (newRuns.length > 0) {
+    rebuilt.push(/* @__PURE__ */ jsxDEV(Ins, {
+      meta: mintMeta(),
+      children: newRuns
+    }, undefined, false, undefined, this));
+  }
+  existingParagraph.children = rebuilt;
+}
+var HELP9 = `docx edit \u2014 replace a paragraph at a locator
 
 Usage:
   docx edit FILE [options]
@@ -16241,6 +16399,7 @@ Run options (only with --text):
   --bold            Bold
   --italic          Italic
 
+  -o, --output PATH Write to PATH instead of overwriting FILE
   --dry-run         Print what would change; do not write the file
   -h, --help        Show this help
 
@@ -16250,17 +16409,232 @@ Examples:
 `;
 var init_edit = __esm(() => {
   init_core();
-  init_emit();
+  init_emit2();
   init_respond();
   init_jsx_dev_runtime();
 });
 
+// src/core/find/index.ts
+function findTextSpans(doc, query, options = {}) {
+  const matcher = options.regex ? regexMatcher(query, options.ignoreCase ?? false) : literalMatcher(query, options.ignoreCase ?? false);
+  const out = [];
+  collectMatches(doc.blocks, matcher, out);
+  return out;
+}
+function literalMatcher(query, ignoreCase) {
+  if (query.length === 0) {
+    throw new Error("query cannot be empty");
+  }
+  const needle = ignoreCase ? query.toLowerCase() : query;
+  return (paragraphText) => {
+    const haystack = ignoreCase ? paragraphText.toLowerCase() : paragraphText;
+    const matches = [];
+    let cursor = haystack.indexOf(needle);
+    while (cursor !== -1) {
+      matches.push({
+        start: cursor,
+        end: cursor + needle.length,
+        text: paragraphText.slice(cursor, cursor + needle.length)
+      });
+      cursor = haystack.indexOf(needle, cursor + needle.length);
+    }
+    return matches;
+  };
+}
+function regexMatcher(pattern, ignoreCase) {
+  const flags = `g${ignoreCase ? "i" : ""}`;
+  const regex = new RegExp(pattern, flags);
+  return (paragraphText) => {
+    const matches = [];
+    regex.lastIndex = 0;
+    let result = regex.exec(paragraphText);
+    while (result !== null) {
+      const matched = result[0];
+      if (matched.length === 0) {
+        regex.lastIndex += 1;
+        result = regex.exec(paragraphText);
+        continue;
+      }
+      matches.push({
+        start: result.index,
+        end: result.index + matched.length,
+        text: matched
+      });
+      result = regex.exec(paragraphText);
+    }
+    return matches;
+  };
+}
+function collectMatches(blocks, matcher, out) {
+  for (const block of blocks) {
+    if (block.type === "paragraph") {
+      const paragraphText = block.runs.map((run10) => run10.type === "text" ? run10.text : "").join("");
+      for (const span of matcher(paragraphText)) {
+        const match = {
+          blockId: block.id,
+          start: span.start,
+          end: span.end,
+          text: span.text
+        };
+        const overlaps = trackedChangesOverlapping(block, span.start, span.end);
+        if (overlaps.length > 0)
+          match.trackedChanges = overlaps;
+        out.push(match);
+      }
+      continue;
+    }
+    if (block.type === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          collectMatches(cell.blocks, matcher, out);
+        }
+      }
+    }
+  }
+}
+function trackedChangesOverlapping(paragraph, start, end) {
+  const seen = new Set;
+  const out = [];
+  let offset = 0;
+  for (const run10 of paragraph.runs) {
+    const length = run10.type === "text" ? run10.text.length : 0;
+    const runStart = offset;
+    const runEnd = offset + length;
+    offset = runEnd;
+    if (run10.type !== "text")
+      continue;
+    if (runEnd <= start || runStart >= end)
+      continue;
+    const change = run10.trackedChange;
+    if (!change)
+      continue;
+    const key = `${change.kind}:${change.revisionId}:${change.author}`;
+    if (seen.has(key))
+      continue;
+    seen.add(key);
+    out.push(change);
+  }
+  return out;
+}
+
+// src/cli/find/index.ts
+var exports_find = {};
+__export(exports_find, {
+  run: () => run10
+});
+import { parseArgs as parseArgs9 } from "util";
+async function run10(args) {
+  let parsed;
+  try {
+    parsed = parseArgs9({
+      args,
+      allowPositionals: true,
+      options: {
+        regex: { type: "boolean" },
+        "ignore-case": { type: "boolean" },
+        all: { type: "boolean" },
+        nth: { type: "string" },
+        help: { type: "boolean", short: "h" }
+      }
+    });
+  } catch (parseError) {
+    const message = parseError instanceof Error ? parseError.message : String(parseError);
+    return fail("USAGE", message, HELP10);
+  }
+  if (parsed.values.help) {
+    await writeStdout(HELP10);
+    return EXIT.OK;
+  }
+  const path = parsed.positionals[0];
+  const query = parsed.positionals[1];
+  if (!path)
+    return fail("USAGE", "Missing FILE argument", HELP10);
+  if (query == null)
+    return fail("USAGE", "Missing QUERY argument", HELP10);
+  const ignoreCase = Boolean(parsed.values["ignore-case"]);
+  const useRegex = Boolean(parsed.values.regex);
+  const wantAll = Boolean(parsed.values.all);
+  const nthRaw = parsed.values.nth;
+  const nth = nthRaw === undefined ? undefined : Number(nthRaw);
+  if (nth !== undefined && (!Number.isInteger(nth) || nth < 0)) {
+    return fail("USAGE", `--nth must be a non-negative integer, got "${nthRaw}"`);
+  }
+  const view = await openOrFail(path);
+  if (typeof view === "number")
+    return view;
+  let allMatches;
+  try {
+    allMatches = findTextSpans(view.doc, query, {
+      regex: useRegex,
+      ignoreCase
+    });
+  } catch (matcherError) {
+    const message = matcherError instanceof Error ? matcherError.message : String(matcherError);
+    return fail("USAGE", `Invalid query: ${message}`);
+  }
+  let selected;
+  if (nth !== undefined) {
+    const single = allMatches[nth];
+    if (!single) {
+      return fail("MATCH_NOT_FOUND", `Only ${allMatches.length} match(es); --nth ${nth} is out of range`);
+    }
+    selected = [single];
+  } else if (wantAll) {
+    selected = allMatches;
+  } else {
+    selected = allMatches.slice(0, 1);
+  }
+  await respond({
+    ok: true,
+    operation: "find",
+    path,
+    query,
+    regex: useRegex,
+    ignoreCase,
+    totalMatches: allMatches.length,
+    matches: selected.map((match) => ({
+      locator: `${match.blockId}:${match.start}-${match.end}`,
+      ...match
+    }))
+  });
+  return EXIT.OK;
+}
+var HELP10 = `docx find \u2014 locate text spans and return their locators
+
+Usage:
+  docx find FILE QUERY [options]
+
+Required positional:
+  QUERY             literal substring (or regex if --regex)
+
+Options:
+  --regex           treat QUERY as a JavaScript regular expression
+  --ignore-case     case-insensitive match
+  --all             return every match (default: just the first)
+  --nth N           return only the Nth match (0-indexed)
+  -h, --help        show this help
+
+Within-paragraph matches only \u2014 cross-paragraph ranges aren't supported
+yet. Searches the concatenated text of each paragraph in document order,
+including paragraphs nested in table cells (locators look like
+tT:rRcC:pK:S-E for those).
+
+Examples:
+  docx find doc.docx "fox"
+  docx find doc.docx "Action Item:" --all
+  docx find doc.docx "TODO|FIXME" --regex --ignore-case
+  docx comments add doc.docx --range "$(docx find doc.docx fox | jq -r .matches[0].locator)" --text "..."
+`;
+var init_find = __esm(() => {
+  init_respond();
+});
+
 // src/cli/images/extract.ts
 var exports_extract = {};
 __export(exports_extract, {
   run: () => run11
 });
-import { join as join2 } from "path";
+import { join } from "path";
 import { parseArgs as parseArgs10 } from "util";
 async function run11(args) {
   let parsed;
@@ -16289,20 +16663,9 @@ async function run11(args) {
   if (!outputDir)
     return fail("USAGE", "Missing --to DIR", HELP11);
   const targetId = parsed.values.id;
-  let view;
-  try {
-    view = await openDocView(path);
-  } catch (openError) {
-    if (openError instanceof PkgError) {
-      if (openError.code === "FILE_NOT_FOUND") {
-        return fail("FILE_NOT_FOUND", openError.message);
-      }
-      if (openError.code === "NOT_A_ZIP") {
-        return fail("NOT_A_ZIP", openError.message);
-      }
-    }
-    throw openError;
-  }
+  const view = await openOrFail(path);
+  if (typeof view === "number")
+    return view;
   await enrichImageHashes(view);
   const allImages = [];
   collectImages(view.doc.blocks, allImages);
@@ -16318,7 +16681,7 @@ async function run11(args) {
       continue;
     const extension = extensionFor(image.contentType, reference.partName);
     const fileName = `${image.hash}.${extension}`;
-    const outputPath = join2(outputDir, fileName);
+    const outputPath = join(outputDir, fileName);
     if (!seenHashes.has(image.hash)) {
       const bytes = await view.pkg.readBytes(reference.partName);
       await Bun.write(outputPath, bytes);
@@ -16423,20 +16786,9 @@ async function run12(args) {
   const path = parsed.positionals[0];
   if (!path)
     return fail("USAGE", "Missing FILE argument", HELP12);
-  let view;
-  try {
-    view = await openDocView(path);
-  } catch (openError) {
-    if (openError instanceof PkgError) {
-      if (openError.code === "FILE_NOT_FOUND") {
-        return fail("FILE_NOT_FOUND", openError.message);
-      }
-      if (openError.code === "NOT_A_ZIP") {
-        return fail("NOT_A_ZIP", openError.message);
-      }
-    }
-    throw openError;
-  }
+  const view = await openOrFail(path);
+  if (typeof view === "number")
+    return view;
   await enrichImageHashes(view);
   const images = [];
   collectImages2(view.doc.blocks, images);
@@ -16492,6 +16844,7 @@ async function run13(args) {
       options: {
         at: { type: "string" },
         with: { type: "string" },
+        output: { type: "string", short: "o" },
         "dry-run": { type: "boolean" },
         help: { type: "boolean", short: "h" }
       }
@@ -16522,26 +16875,16 @@ async function run13(args) {
   if (!newExtension) {
     return fail("USAGE", `Unsupported replacement image type: ${newMimeType}`, "Supported: png, jpeg, gif, webp, bmp, tiff, svg, emf, wmf, ico.");
   }
-  let view;
-  try {
-    view = await openDocView(path);
-  } catch (openError) {
-    if (openError instanceof PkgError) {
-      if (openError.code === "FILE_NOT_FOUND") {
-        return fail("FILE_NOT_FOUND", openError.message);
-      }
-      if (openError.code === "NOT_A_ZIP") {
-        return fail("NOT_A_ZIP", openError.message);
-      }
-    }
-    throw openError;
-  }
+  const view = await openOrFail(path);
+  if (typeof view === "number")
+    return view;
   const reference = view.imageById.get(targetId);
   if (!reference) {
     return fail("IMAGE_NOT_FOUND", `Image not found: ${targetId}`);
   }
   const originalPartName = reference.partName;
   const newPartName = renameExtension(originalPartName, newExtension);
+  const outputPath = parsed.values.output;
   if (parsed.values["dry-run"]) {
     await respond({
       ok: true,
@@ -16550,7 +16893,8 @@ async function run13(args) {
       path,
       imageId: targetId,
       from: { partName: originalPartName, mimeType: reference.contentType },
-      to: { partName: newPartName, mimeType: newMimeType }
+      to: { partName: newPartName, mimeType: newMimeType },
+      ...outputPath ? { output: outputPath } : {}
     });
     return EXIT.OK;
   }
@@ -16565,11 +16909,11 @@ async function run13(args) {
     reference.partName = newPartName;
     reference.contentType = newMimeType;
   }
-  await saveDocView(view);
+  await saveDocView(view, outputPath);
   await respond({
     ok: true,
     operation: "images.replace",
-    path,
+    path: outputPath ?? path,
     imageId: targetId,
     partName: newPartName,
     mimeType: newMimeType,
@@ -16623,6 +16967,7 @@ Required:
   --with PATH       New image file (any image MIME type)
 
 Optional:
+  -o, --output PATH Write to PATH instead of overwriting FILE
   --dry-run         Print what would change; do not write the file
   -h, --help        Show this help
 
@@ -16691,9 +17036,118 @@ var init_images = __esm(() => {
   };
 });
 
-// src/cli/insert/index.tsx
-var exports_insert = {};
-__export(exports_insert, {
+// src/core/ast/types.ts
+var types_default = `export type Doc = {
+	schemaVersion: 1;
+	path: string;
+	properties: DocProperties;
+	blocks: Block[];
+	comments: Comment[];
+};
+
+export type DocProperties = {
+	title?: string;
+	author?: string;
+	created?: string;
+	modified?: string;
+};
+
+export type Block = Paragraph | Table | SectionBreak;
+
+export type Paragraph = {
+	id: string;
+	type: "paragraph";
+	style?: string;
+	alignment?: "left" | "center" | "right" | "justify";
+	list?: { level: number; numId: string };
+	runs: Run[];
+};
+
+export type Table = {
+	id: string;
+	type: "table";
+	rows: TableRow[];
+};
+
+export type TableRow = {
+	cells: TableCell[];
+};
+
+export type TableCell = {
+	blocks: Block[];
+};
+
+export type SectionBreak = {
+	id: string;
+	type: "sectionBreak";
+};
+
+export type Run = TextRun | ImageRun | BreakRun | TabRun;
+
+export type TextRun = {
+	type: "text";
+	text: string;
+	color?: string;
+	highlight?: string;
+	bold?: boolean;
+	italic?: boolean;
+	underline?: string;
+	strike?: boolean;
+	font?: string;
+	sizeHalfPoints?: number;
+	comments?: string[];
+	trackedChange?: TrackedChange;
+};
+
+export type ImageRun = {
+	type: "image";
+	id: string;
+	contentType: string;
+	hash: string;
+	widthEmu?: number;
+	heightEmu?: number;
+	alt?: string;
+};
+
+export type BreakRun = {
+	type: "break";
+	kind: "page" | "line" | "column";
+};
+
+export type TabRun = {
+	type: "tab";
+};
+
+export type TrackedChange = {
+	kind: "ins" | "del";
+	author: string;
+	date: string;
+	revisionId: string;
+};
+
+export type Comment = {
+	id: string;
+	author: string;
+	initials?: string;
+	date: string;
+	text: string;
+	parentId?: string;
+	resolved?: boolean;
+	anchor: CommentAnchor;
+};
+
+export type CommentAnchor = {
+	startBlockId: string;
+	startOffset: number;
+	endBlockId: string;
+	endOffset: number;
+};
+`;
+var init_types = () => {};
+
+// src/cli/info/schema.ts
+var exports_schema = {};
+__export(exports_schema, {
   run: () => run15
 });
 import { parseArgs as parseArgs13 } from "util";
@@ -16704,16 +17158,8 @@ async function run15(args) {
       args,
       allowPositionals: true,
       options: {
-        after: { type: "string" },
-        before: { type: "string" },
-        text: { type: "string" },
-        runs: { type: "string" },
-        style: { type: "string" },
-        alignment: { type: "string" },
-        color: { type: "string" },
-        bold: { type: "boolean" },
-        italic: { type: "boolean" },
-        "dry-run": { type: "boolean" },
+        json: { type: "boolean" },
+        ts: { type: "boolean" },
         help: { type: "boolean", short: "h" }
       }
     });
@@ -16725,153 +17171,205 @@ async function run15(args) {
     await writeStdout(HELP15);
     return EXIT.OK;
   }
-  const path = parsed.positionals[0];
-  if (!path)
-    return fail("USAGE", "Missing FILE argument", HELP15);
-  const after = parsed.values.after;
-  const before = parsed.values.before;
-  if (!after && !before) {
-    return fail("USAGE", "Missing locator: pass --after or --before", HELP15);
-  }
-  if (after && before) {
-    return fail("USAGE", "Pass either --after or --before, not both", HELP15);
-  }
-  const text = parsed.values.text;
-  const runsJson = parsed.values.runs;
-  if (!text && !runsJson) {
-    return fail("USAGE", "Missing content: pass --text or --runs", HELP15);
-  }
-  if (text && runsJson) {
-    return fail("USAGE", "Pass either --text or --runs, not both", HELP15);
-  }
-  const paragraphOptions = {};
-  const styleValue = parsed.values.style;
-  if (styleValue)
-    paragraphOptions.style = styleValue;
-  const alignmentValue = parsed.values.alignment;
-  if (alignmentValue) {
-    if (alignmentValue !== "left" && alignmentValue !== "center" && alignmentValue !== "right" && alignmentValue !== "justify") {
-      return fail("USAGE", `Invalid --alignment: ${alignmentValue}`, "Valid values: left, center, right, justify");
-    }
-    paragraphOptions.alignment = alignmentValue;
-  }
-  let view;
-  try {
-    view = await openDocView(path);
-  } catch (openError) {
-    if (openError instanceof PkgError) {
-      if (openError.code === "FILE_NOT_FOUND") {
-        return fail("FILE_NOT_FOUND", openError.message);
-      }
-      if (openError.code === "NOT_A_ZIP") {
-        return fail("NOT_A_ZIP", openError.message);
-      }
-    }
-    throw openError;
-  }
-  const targetLocator = after ?? before;
-  let blockRef;
-  try {
-    blockRef = resolveBlock(view, targetLocator);
-  } catch (resolveError) {
-    if (resolveError instanceof LocatorResolveError) {
-      return fail("BLOCK_NOT_FOUND", resolveError.message);
-    }
-    throw resolveError;
-  }
-  let paragraphNode;
-  if (text !== undefined) {
-    const color = parsed.values.color;
-    paragraphNode = /* @__PURE__ */ jsxDEV(Paragraph, {
-      text,
-      ...paragraphOptions,
-      ...color ? { color } : {},
-      ...parsed.values.bold ? { bold: true } : {},
-      ...parsed.values.italic ? { italic: true } : {}
-    }, undefined, false, undefined, this);
-  } else {
-    let runsValue;
-    try {
-      runsValue = JSON.parse(runsJson);
-    } catch (jsonError) {
-      const message = jsonError instanceof Error ? jsonError.message : String(jsonError);
-      return fail("USAGE", `Invalid --runs JSON: ${message}`);
-    }
-    if (!Array.isArray(runsValue)) {
-      return fail("USAGE", "--runs must be a JSON array of Run objects");
-    }
-    paragraphNode = /* @__PURE__ */ jsxDEV(Paragraph, {
-      runs: runsValue,
-      ...paragraphOptions
-    }, undefined, false, undefined, this);
-  }
-  const targetIndex = blockRef.parent.indexOf(blockRef.node);
-  if (targetIndex === -1) {
-    return fail("BLOCK_NOT_FOUND", "Block reference is stale (parent does not contain it)");
-  }
-  const insertIndex = after !== undefined ? targetIndex + 1 : targetIndex;
-  if (parsed.values["dry-run"]) {
-    await respond({
-      ok: true,
-      operation: "insert",
-      dryRun: true,
-      path,
-      locator: targetLocator,
-      placement: after !== undefined ? "after" : "before"
-    });
+  if (parsed.values.ts) {
+    await writeStdout(types_default);
     return EXIT.OK;
   }
-  blockRef.parent.splice(insertIndex, 0, paragraphNode);
-  await saveDocView(view);
-  await respond({
-    ok: true,
-    operation: "insert",
-    path,
-    locator: targetLocator,
-    placement: after !== undefined ? "after" : "before"
-  });
+  await respond(JSON_SCHEMA);
   return EXIT.OK;
 }
-var HELP15 = `docx insert \u2014 insert a paragraph at a locator
+var HELP15 = `docx schema \u2014 print the AST type definitions
 
 Usage:
-  docx insert FILE [options]
-
-Locator (one required):
-  --after LOCATOR   Insert after the block at LOCATOR (e.g., p3)
-  --before LOCATOR  Insert before the block at LOCATOR
-
-Content (one required):
-  --text TEXT       Insert a paragraph with this text
-  --runs JSON       Insert a paragraph with custom runs (Run[] JSON)
-
-Paragraph options:
-  --style NAME       Apply paragraph style (e.g., Heading1)
-  --alignment ALIGN  left | center | right | justify
-
-Run options (only with --text):
-  --color HEX       Run color, hex (e.g., 800080 for purple)
-  --bold            Bold
-  --italic          Italic
+  docx schema [options]
 
-  --dry-run         Print what would be inserted; do not write the file
-  -h, --help        Show this help
+Options:
+  --json       Print as a JSON Schema document (default)
+  --ts         Print TypeScript type source (read live from src/core/ast/types.ts)
+  -h, --help   Show this help
 
 Examples:
-  docx insert doc.docx --after p3 --text "Section header" --style Heading2
-  docx insert doc.docx --before p0 --text "ALERT" --color CC0000 --bold
-  docx insert doc.docx --after p2 --runs '[{"type":"text","text":"X","bold":true}]'
-`;
-var init_insert = __esm(() => {
-  init_core();
+  docx schema | jq '.definitions.Run'
+  docx schema --ts > ast.d.ts
+`, JSON_SCHEMA;
+var init_schema = __esm(() => {
+  init_types();
   init_respond();
-  init_emit();
-  init_jsx_dev_runtime();
+  JSON_SCHEMA = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://github.com/kklimuk/docx-cli/schema",
+    title: "docx-cli AST",
+    type: "object",
+    required: ["schemaVersion", "path", "properties", "blocks", "comments"],
+    properties: {
+      schemaVersion: { const: 1 },
+      path: { type: "string" },
+      properties: {
+        type: "object",
+        properties: {
+          title: { type: "string" },
+          author: { type: "string" },
+          created: { type: "string" },
+          modified: { type: "string" }
+        }
+      },
+      blocks: { type: "array", items: { $ref: "#/$defs/Block" } },
+      comments: { type: "array", items: { $ref: "#/$defs/Comment" } }
+    },
+    $defs: {
+      Block: {
+        oneOf: [
+          { $ref: "#/$defs/Paragraph" },
+          { $ref: "#/$defs/Table" },
+          { $ref: "#/$defs/SectionBreak" }
+        ]
+      },
+      Paragraph: {
+        type: "object",
+        required: ["id", "type", "runs"],
+        properties: {
+          id: { type: "string" },
+          type: { const: "paragraph" },
+          style: { type: "string" },
+          alignment: { enum: ["left", "center", "right", "justify"] },
+          list: {
+            type: "object",
+            required: ["level", "numId"],
+            properties: {
+              level: { type: "number" },
+              numId: { type: "string" }
+            }
+          },
+          runs: { type: "array", items: { $ref: "#/$defs/Run" } }
+        }
+      },
+      Run: {
+        oneOf: [
+          { $ref: "#/$defs/TextRun" },
+          { $ref: "#/$defs/ImageRun" },
+          { $ref: "#/$defs/BreakRun" },
+          { $ref: "#/$defs/TabRun" }
+        ]
+      },
+      TextRun: {
+        type: "object",
+        required: ["type", "text"],
+        properties: {
+          type: { const: "text" },
+          text: { type: "string" },
+          color: { type: "string" },
+          highlight: { type: "string" },
+          bold: { type: "boolean" },
+          italic: { type: "boolean" },
+          underline: { type: "string" },
+          strike: { type: "boolean" },
+          font: { type: "string" },
+          sizeHalfPoints: { type: "number" },
+          comments: { type: "array", items: { type: "string" } },
+          trackedChange: {
+            type: "object",
+            required: ["kind", "author", "date", "revisionId"],
+            properties: {
+              kind: { enum: ["ins", "del"] },
+              author: { type: "string" },
+              date: { type: "string" },
+              revisionId: { type: "string" }
+            }
+          }
+        }
+      },
+      ImageRun: {
+        type: "object",
+        required: ["type", "id", "contentType", "hash"],
+        properties: {
+          type: { const: "image" },
+          id: { type: "string" },
+          contentType: { type: "string" },
+          hash: { type: "string" },
+          widthEmu: { type: "number" },
+          heightEmu: { type: "number" },
+          alt: { type: "string" }
+        }
+      },
+      BreakRun: {
+        type: "object",
+        required: ["type", "kind"],
+        properties: {
+          type: { const: "break" },
+          kind: { enum: ["page", "line", "column"] }
+        }
+      },
+      TabRun: {
+        type: "object",
+        required: ["type"],
+        properties: { type: { const: "tab" } }
+      },
+      Table: {
+        type: "object",
+        required: ["id", "type", "rows"],
+        properties: {
+          id: { type: "string" },
+          type: { const: "table" },
+          rows: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                cells: {
+                  type: "array",
+                  items: {
+                    type: "object",
+                    properties: {
+                      blocks: {
+                        type: "array",
+                        items: { $ref: "#/$defs/Block" }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      SectionBreak: {
+        type: "object",
+        required: ["id", "type"],
+        properties: {
+          id: { type: "string" },
+          type: { const: "sectionBreak" }
+        }
+      },
+      Comment: {
+        type: "object",
+        required: ["id", "author", "date", "text", "anchor"],
+        properties: {
+          id: { type: "string" },
+          author: { type: "string" },
+          initials: { type: "string" },
+          date: { type: "string" },
+          text: { type: "string" },
+          parentId: { type: "string" },
+          resolved: { type: "boolean" },
+          anchor: {
+            type: "object",
+            required: ["startBlockId", "startOffset", "endBlockId", "endOffset"],
+            properties: {
+              startBlockId: { type: "string" },
+              startOffset: { type: "number" },
+              endBlockId: { type: "string" },
+              endOffset: { type: "number" }
+            }
+          }
+        }
+      }
+    }
+  };
 });
 
-// src/cli/locators-cmd/index.ts
-var exports_locators_cmd = {};
-__export(exports_locators_cmd, {
+// src/cli/info/locators.ts
+var exports_locators = {};
+__export(exports_locators, {
   run: () => run16
 });
 import { parseArgs as parseArgs14 } from "util";
@@ -16895,11 +17393,11 @@ async function run16(args) {
     return EXIT.OK;
   }
   if (parsed.values.json) {
-    await Bun.write(Bun.stdout, `${JSON.stringify(JSON_REFERENCE, null, 2)}
+    await writeStdout(`${JSON.stringify(JSON_REFERENCE, null, 2)}
 `);
     return EXIT.OK;
   }
-  await Bun.write(Bun.stdout, REFERENCE);
+  await writeStdout(REFERENCE);
   return EXIT.OK;
 }
 var HELP16 = `docx locators \u2014 print the locator grammar reference
@@ -16913,21 +17411,22 @@ Options:
 `, REFERENCE = `LOCATOR GRAMMAR
 
 Block locators:
-  pN          Paragraph N (e.g., p3)
-  tN          Table N
-  sN          Section break N
-  cellpN      Paragraph inside a table cell
+  pN              Paragraph N (e.g., p3)
+  tN              Table N
+  sN              Section break N
+  tT:rRcC:pK      Paragraph K of cell (R,C) in table T
 
 Span locators (within a single paragraph):
-  pN:S-E      Characters S..E of paragraph N (inclusive start, exclusive end)
+  pN:S-E          Characters S..E of paragraph N (inclusive start, exclusive end)
+  tT:rRcC:pK:S-E  Characters S..E of a cell paragraph
 
 Range locators (across blocks):
-  pN:S-pM:E   From char S of paragraph N to char E of paragraph M
+  pN:S-pM:E       From char S of paragraph N to char E of paragraph M
 
 Entity locators:
-  cN          Comment id (e.g., c0)
-  imgN        Image id (e.g., img2)
-  tN:rRcC     Cell at row R, column C of table tN
+  cN              Comment id (e.g., c0)
+  imgN            Image id (e.g., img2)
+  tN:rRcC         Cell at row R, column C of table tN
 
 Examples:
   p3              -> the entire paragraph p3
@@ -16937,25 +17436,27 @@ Examples:
   img0            -> image img0
   t0:r1c2         -> cell at row 1, col 2 of table t0
   t0:r1c2:p0      -> first paragraph of that cell
+  t0:r1c2:p0:5-10 -> chars 5..10 of that paragraph
 
 Notes:
   Block ids are positional and shift after structural edits \u2014 re-read
   between non-trivial mutations. Mutating commands print before/after
   locator info in their JSON ack so agents can chain operations.
 `, JSON_REFERENCE;
-var init_locators_cmd = __esm(() => {
+var init_locators2 = __esm(() => {
   init_respond();
   JSON_REFERENCE = {
     blockLocators: {
       paragraph: { syntax: "pN", example: "p3" },
       table: { syntax: "tN", example: "t0" },
       sectionBreak: { syntax: "sN", example: "s0" },
-      cellParagraph: { syntax: "cellpN", example: "cellp0" }
+      cellParagraph: { syntax: "tT:rRcC:pK", example: "t0:r1c2:p0" }
     },
     spanLocator: {
       syntax: "pN:S-E",
       example: "p3:5-20",
-      semantics: "Characters S..E within paragraph N (start inclusive, end exclusive)"
+      semantics: "Characters S..E within paragraph N (start inclusive, end exclusive)",
+      cellSyntax: "tT:rRcC:pK:S-E"
     },
     rangeLocator: {
       syntax: "pN:S-pM:E",
@@ -16976,16 +17477,251 @@ var init_locators_cmd = __esm(() => {
   };
 });
 
+// src/cli/info/index.ts
+var exports_info = {};
+__export(exports_info, {
+  run: () => run17
+});
+async function run17(args) {
+  const topic = args[0];
+  if (!topic || topic === "--help" || topic === "-h" || topic === "help") {
+    await writeStdout(HELP17);
+    return topic ? 0 : 2;
+  }
+  const loader = SUBCOMMANDS3[topic];
+  if (!loader) {
+    return fail("USAGE", `Unknown info topic: ${topic}`, 'Run "docx info --help".');
+  }
+  const module_ = await loader();
+  return module_.run(args.slice(1));
+}
+var SUBCOMMANDS3, HELP17 = `docx info \u2014 print reference material about the CLI
+
+Usage:
+  docx info <topic> [options]
+
+Topics:
+  schema    Dump AST JSON Schema (or TS source via --ts)
+  locators  Dump locator grammar reference
+
+Run "docx info <topic> --help" for topic-specific help.
+`;
+var init_info = __esm(() => {
+  init_respond();
+  SUBCOMMANDS3 = {
+    schema: () => Promise.resolve().then(() => (init_schema(), exports_schema)),
+    locators: () => Promise.resolve().then(() => (init_locators2(), exports_locators))
+  };
+});
+
+// src/cli/insert/index.tsx
+var exports_insert = {};
+__export(exports_insert, {
+  run: () => run18
+});
+import { parseArgs as parseArgs15 } from "util";
+async function run18(args) {
+  let parsed;
+  try {
+    parsed = parseArgs15({
+      args,
+      allowPositionals: true,
+      options: {
+        after: { type: "string" },
+        before: { type: "string" },
+        text: { type: "string" },
+        runs: { type: "string" },
+        style: { type: "string" },
+        alignment: { type: "string" },
+        color: { type: "string" },
+        bold: { type: "boolean" },
+        italic: { type: "boolean" },
+        output: { type: "string", short: "o" },
+        "dry-run": { type: "boolean" },
+        help: { type: "boolean", short: "h" }
+      }
+    });
+  } catch (parseError) {
+    const message = parseError instanceof Error ? parseError.message : String(parseError);
+    return fail("USAGE", message, HELP18);
+  }
+  if (parsed.values.help) {
+    await writeStdout(HELP18);
+    return EXIT.OK;
+  }
+  const path = parsed.positionals[0];
+  if (!path)
+    return fail("USAGE", "Missing FILE argument", HELP18);
+  const after = parsed.values.after;
+  const before = parsed.values.before;
+  if (!after && !before) {
+    return fail("USAGE", "Missing locator: pass --after or --before", HELP18);
+  }
+  if (after && before) {
+    return fail("USAGE", "Pass either --after or --before, not both", HELP18);
+  }
+  const text = parsed.values.text;
+  const runsJson = parsed.values.runs;
+  if (!text && !runsJson) {
+    return fail("USAGE", "Missing content: pass --text or --runs", HELP18);
+  }
+  if (text && runsJson) {
+    return fail("USAGE", "Pass either --text or --runs, not both", HELP18);
+  }
+  const paragraphOptions = {};
+  const styleValue = parsed.values.style;
+  if (styleValue)
+    paragraphOptions.style = styleValue;
+  const alignmentValue = parsed.values.alignment;
+  if (alignmentValue) {
+    if (alignmentValue !== "left" && alignmentValue !== "center" && alignmentValue !== "right" && alignmentValue !== "justify") {
+      return fail("USAGE", `Invalid --alignment: ${alignmentValue}`, "Valid values: left, center, right, justify");
+    }
+    paragraphOptions.alignment = alignmentValue;
+  }
+  const view = await openOrFail(path);
+  if (typeof view === "number")
+    return view;
+  const targetLocator = after ?? before;
+  const blockRef = await resolveBlockOrFail(view, targetLocator);
+  if (typeof blockRef === "number")
+    return blockRef;
+  let paragraphNode;
+  if (text !== undefined) {
+    const color = parsed.values.color;
+    paragraphNode = /* @__PURE__ */ jsxDEV(Paragraph, {
+      text,
+      ...paragraphOptions,
+      ...color ? { color } : {},
+      ...parsed.values.bold ? { bold: true } : {},
+      ...parsed.values.italic ? { italic: true } : {}
+    }, undefined, false, undefined, this);
+  } else {
+    let runsValue;
+    try {
+      runsValue = JSON.parse(runsJson);
+    } catch (jsonError) {
+      const message = jsonError instanceof Error ? jsonError.message : String(jsonError);
+      return fail("USAGE", `Invalid --runs JSON: ${message}`);
+    }
+    if (!Array.isArray(runsValue)) {
+      return fail("USAGE", "--runs must be a JSON array of Run objects");
+    }
+    paragraphNode = /* @__PURE__ */ jsxDEV(Paragraph, {
+      runs: runsValue,
+      ...paragraphOptions
+    }, undefined, false, undefined, this);
+  }
+  const targetIndex = blockRef.parent.indexOf(blockRef.node);
+  if (targetIndex === -1) {
+    return fail("BLOCK_NOT_FOUND", "Block reference is stale (parent does not contain it)");
+  }
+  const insertIndex = after !== undefined ? targetIndex + 1 : targetIndex;
+  if (isTrackChangesEnabled(view)) {
+    applyTrackedInsertion(paragraphNode, view);
+  }
+  const outputPath = parsed.values.output;
+  if (parsed.values["dry-run"]) {
+    await respond({
+      ok: true,
+      operation: "insert",
+      dryRun: true,
+      path,
+      locator: targetLocator,
+      placement: after !== undefined ? "after" : "before",
+      ...outputPath ? { output: outputPath } : {}
+    });
+    return EXIT.OK;
+  }
+  blockRef.parent.splice(insertIndex, 0, paragraphNode);
+  await saveDocView(view, outputPath);
+  await respond({
+    ok: true,
+    operation: "insert",
+    path: outputPath ?? path,
+    locator: targetLocator,
+    placement: after !== undefined ? "after" : "before"
+  });
+  return EXIT.OK;
+}
+function applyTrackedInsertion(paragraph, view) {
+  const allocator = createRevisionAllocator(view);
+  const baseMeta = { author: resolveAuthor(), date: resolveDate() };
+  const mintMeta = () => ({
+    ...baseMeta,
+    revisionId: allocator.next()
+  });
+  const newChildren = [];
+  let runBuffer = [];
+  const flush = () => {
+    if (runBuffer.length === 0)
+      return;
+    newChildren.push(/* @__PURE__ */ jsxDEV(Ins, {
+      meta: mintMeta(),
+      children: runBuffer
+    }, undefined, false, undefined, this));
+    runBuffer = [];
+  };
+  for (const child of paragraph.children) {
+    if (child.tag === "w:r") {
+      runBuffer.push(child);
+      continue;
+    }
+    flush();
+    newChildren.push(child);
+  }
+  flush();
+  paragraph.children = newChildren;
+  markParagraphMarkAs(paragraph, "ins", mintMeta());
+}
+var HELP18 = `docx insert \u2014 insert a paragraph at a locator
+
+Usage:
+  docx insert FILE [options]
+
+Locator (one required):
+  --after LOCATOR   Insert after the block at LOCATOR (e.g., p3)
+  --before LOCATOR  Insert before the block at LOCATOR
+
+Content (one required):
+  --text TEXT       Insert a paragraph with this text
+  --runs JSON       Insert a paragraph with custom runs (Run[] JSON)
+
+Paragraph options:
+  --style NAME       Apply paragraph style (e.g., Heading1)
+  --alignment ALIGN  left | center | right | justify
+
+Run options (only with --text):
+  --color HEX       Run color, hex (e.g., 800080 for purple)
+  --bold            Bold
+  --italic          Italic
+
+  -o, --output PATH Write to PATH instead of overwriting FILE
+  --dry-run         Print what would be inserted; do not write the file
+  -h, --help        Show this help
+
+Examples:
+  docx insert doc.docx --after p3 --text "Section header" --style Heading2
+  docx insert doc.docx --before p0 --text "ALERT" --color CC0000 --bold
+  docx insert doc.docx --after p2 --runs '[{"type":"text","text":"X","bold":true}]'
+`;
+var init_insert = __esm(() => {
+  init_core();
+  init_respond();
+  init_emit2();
+  init_jsx_dev_runtime();
+});
+
 // src/cli/read/index.ts
 var exports_read = {};
 __export(exports_read, {
-  run: () => run17
+  run: () => run19
 });
-import { parseArgs as parseArgs15 } from "util";
-async function run17(args) {
+import { parseArgs as parseArgs16 } from "util";
+async function run19(args) {
   let parsed;
   try {
-    parsed = parseArgs15({
+    parsed = parseArgs16({
       args,
       allowPositionals: true,
       options: {
@@ -16994,32 +17730,23 @@ async function run17(args) {
       }
     });
   } catch (e) {
-    return fail("USAGE", e instanceof Error ? e.message : String(e), HELP17);
+    return fail("USAGE", e instanceof Error ? e.message : String(e), HELP19);
   }
   if (parsed.values.help) {
-    await writeStdout(HELP17);
+    await writeStdout(HELP19);
     return EXIT.OK;
   }
   const path = parsed.positionals[0];
   if (!path)
-    return fail("USAGE", "Missing FILE argument", HELP17);
-  let view;
-  try {
-    view = await openDocView(path);
-  } catch (e) {
-    if (e instanceof PkgError) {
-      if (e.code === "FILE_NOT_FOUND")
-        return fail("FILE_NOT_FOUND", e.message);
-      if (e.code === "NOT_A_ZIP")
-        return fail("NOT_A_ZIP", e.message);
-    }
-    throw e;
-  }
+    return fail("USAGE", "Missing FILE argument", HELP19);
+  const view = await openOrFail(path);
+  if (typeof view === "number")
+    return view;
   await enrichImageHashes(view);
   await respond(view.doc);
   return EXIT.OK;
 }
-var HELP17 = `docx read \u2014 print AST as JSON
+var HELP19 = `docx read \u2014 print AST as JSON
 
 Usage:
   docx read FILE [options]
@@ -17037,394 +17764,524 @@ var init_read2 = __esm(() => {
   init_respond();
 });
 
-// src/core/ast/types.ts
-var types_default = `export type Doc = {
-	schemaVersion: 1;
-	path: string;
-	properties: DocProperties;
-	blocks: Block[];
-	comments: Comment[];
-};
-
-export type DocProperties = {
-	title?: string;
-	author?: string;
-	created?: string;
-	modified?: string;
-};
-
-export type Block = Paragraph | Table | SectionBreak;
-
-export type Paragraph = {
-	id: string;
-	type: "paragraph";
-	style?: string;
-	alignment?: "left" | "center" | "right" | "justify";
-	list?: { level: number; numId: string };
-	runs: Run[];
-};
-
-export type Table = {
-	id: string;
-	type: "table";
-	rows: TableRow[];
-};
-
-export type TableRow = {
-	cells: TableCell[];
-};
-
-export type TableCell = {
-	blocks: Block[];
-};
-
-export type SectionBreak = {
-	id: string;
-	type: "sectionBreak";
-};
-
-export type Run = TextRun | ImageRun | BreakRun | TabRun;
-
-export type TextRun = {
-	type: "text";
-	text: string;
-	color?: string;
-	highlight?: string;
-	bold?: boolean;
-	italic?: boolean;
-	underline?: string;
-	strike?: boolean;
-	font?: string;
-	sizeHalfPoints?: number;
-	comments?: string[];
-	trackedChange?: TrackedChange;
-};
-
-export type ImageRun = {
-	type: "image";
-	id: string;
-	contentType: string;
-	hash: string;
-	widthEmu?: number;
-	heightEmu?: number;
-	alt?: string;
-	extractedPath?: string;
-};
-
-export type BreakRun = {
-	type: "break";
-	kind: "page" | "line" | "column";
-};
-
-export type TabRun = {
-	type: "tab";
-};
-
-export type TrackedChange = {
-	kind: "ins" | "del";
-	author: string;
-	date: string;
-	revisionId: string;
-};
-
-export type Comment = {
-	id: string;
-	author: string;
-	initials?: string;
-	date: string;
-	text: string;
-	parentId?: string;
-	resolved?: boolean;
-	anchor: CommentAnchor;
-};
-
-export type CommentAnchor = {
-	startBlockId: string;
-	startOffset: number;
-	endBlockId: string;
-	endOffset: number;
-};
-`;
-var init_types = () => {};
+// src/cli/replace/replace-span.tsx
+function replaceSpanInParagraph(paragraph, span, replacement, tracked) {
+  if (span.start > span.end) {
+    throw new Error(`replaceSpanInParagraph: invalid span ${span.start}-${span.end}`);
+  }
+  const slots = collectRunSlots(paragraph);
+  const overlapping = slots.filter((slot) => slot.offsetBefore + slot.length > span.start && slot.offsetBefore < span.end);
+  const firstSlot = overlapping[0];
+  if (!firstSlot) {
+    paragraph.children.push(/* @__PURE__ */ jsxDEV(ReplacementRun, {
+      runProperties: null,
+      text: replacement
+    }, undefined, false, undefined, this));
+    return;
+  }
+  const inheritedProperties = firstSlot.run.findChild("w:rPr")?.clone() ?? null;
+  const firstParent = firstSlot.parent;
+  const allSameParent = overlapping.every((slot) => slot.parent === firstParent);
+  if (allSameParent) {
+    const containerStart = firstParent === paragraph ? 0 : firstSlot.offsetBefore;
+    rebuildContainer(firstParent, containerStart, span, replacement, inheritedProperties, firstParent === paragraph, tracked ?? null);
+    return;
+  }
+  rebuildAcrossBoundaries(paragraph, span, replacement, inheritedProperties, tracked ?? null);
+}
+function collectRunSlots(paragraph) {
+  const slots = [];
+  let offset = 0;
+  for (const child of paragraph.children) {
+    if (child.tag === "w:r") {
+      const length = runTextLength(child);
+      slots.push({
+        parent: paragraph,
+        run: child,
+        offsetBefore: offset,
+        length
+      });
+      offset += length;
+      continue;
+    }
+    if (child.tag === "w:ins" || child.tag === "w:del") {
+      for (const inner of child.children) {
+        if (inner.tag !== "w:r")
+          continue;
+        const length = runTextLength(inner);
+        slots.push({
+          parent: child,
+          run: inner,
+          offsetBefore: offset,
+          length
+        });
+        offset += length;
+      }
+    }
+  }
+  return slots;
+}
+function rebuildContainer(container, baseOffset, span, replacement, runProperties, isParagraph, tracked) {
+  const newChildren = [];
+  let offset = baseOffset;
+  let placed = false;
+  const placeReplacement = () => {
+    if (placed)
+      return;
+    placed = true;
+    const run20 = /* @__PURE__ */ jsxDEV(ReplacementRun, {
+      runProperties,
+      text: replacement
+    }, undefined, false, undefined, this);
+    newChildren.push(tracked && isParagraph ? /* @__PURE__ */ jsxDEV(Ins, {
+      meta: mintMeta(tracked),
+      children: run20
+    }, undefined, false, undefined, this) : run20);
+  };
+  for (const child of container.children) {
+    if (child.tag === "w:r") {
+      const length = runTextLength(child);
+      const runStart = offset;
+      const runEnd = offset + length;
+      offset = runEnd;
+      if (runEnd <= span.start) {
+        newChildren.push(child);
+        continue;
+      }
+      if (runStart >= span.end) {
+        placeReplacement();
+        newChildren.push(child);
+        continue;
+      }
+      const sliceStartInRun = Math.max(0, span.start - runStart);
+      const sliceEndInRun = Math.min(length, span.end - runStart);
+      if (sliceStartInRun > 0) {
+        newChildren.push(sliceRun(child, 0, sliceStartInRun));
+      }
+      if (tracked) {
+        const cutRun = sliceRun(child, sliceStartInRun, sliceEndInRun);
+        convertRunTextToDelText(cutRun);
+        newChildren.push(/* @__PURE__ */ jsxDEV(Del, {
+          meta: mintMeta(tracked),
+          children: cutRun
+        }, undefined, false, undefined, this));
+      }
+      placeReplacement();
+      if (sliceEndInRun < length) {
+        newChildren.push(sliceRun(child, sliceEndInRun, length));
+      }
+      continue;
+    }
+    if (isParagraph && (child.tag === "w:ins" || child.tag === "w:del")) {
+      let innerLength = 0;
+      for (const inner of child.children) {
+        if (inner.tag === "w:r")
+          innerLength += runTextLength(inner);
+      }
+      offset += innerLength;
+      newChildren.push(child);
+      continue;
+    }
+    newChildren.push(child);
+  }
+  if (!placed)
+    placeReplacement();
+  container.children = newChildren;
+}
+function rebuildAcrossBoundaries(paragraph, span, replacement, runProperties, tracked) {
+  const newChildren = [];
+  let offset = 0;
+  let placed = false;
+  const placeReplacement = () => {
+    if (placed)
+      return;
+    placed = true;
+    const run20 = /* @__PURE__ */ jsxDEV(ReplacementRun, {
+      runProperties,
+      text: replacement
+    }, undefined, false, undefined, this);
+    newChildren.push(tracked ? /* @__PURE__ */ jsxDEV(Ins, {
+      meta: mintMeta(tracked),
+      children: run20
+    }, undefined, false, undefined, this) : run20);
+  };
+  for (const child of paragraph.children) {
+    if (child.tag === "w:r") {
+      const length = runTextLength(child);
+      const runStart = offset;
+      const runEnd = offset + length;
+      offset = runEnd;
+      if (runEnd <= span.start) {
+        newChildren.push(child);
+        continue;
+      }
+      if (runStart >= span.end) {
+        placeReplacement();
+        newChildren.push(child);
+        continue;
+      }
+      const sliceStartInRun = Math.max(0, span.start - runStart);
+      const sliceEndInRun = Math.min(length, span.end - runStart);
+      if (sliceStartInRun > 0) {
+        newChildren.push(sliceRun(child, 0, sliceStartInRun));
+      }
+      if (tracked) {
+        const cutRun = sliceRun(child, sliceStartInRun, sliceEndInRun);
+        convertRunTextToDelText(cutRun);
+        newChildren.push(/* @__PURE__ */ jsxDEV(Del, {
+          meta: mintMeta(tracked),
+          children: cutRun
+        }, undefined, false, undefined, this));
+      }
+      placeReplacement();
+      if (sliceEndInRun < length) {
+        newChildren.push(sliceRun(child, sliceEndInRun, length));
+      }
+      continue;
+    }
+    if (child.tag === "w:ins" || child.tag === "w:del") {
+      const innerLength = sumInnerRunLengths(child);
+      const wrapperStart = offset;
+      const wrapperEnd = offset + innerLength;
+      offset = wrapperEnd;
+      if (wrapperEnd <= span.start) {
+        newChildren.push(child);
+        continue;
+      }
+      if (wrapperStart >= span.end) {
+        placeReplacement();
+        newChildren.push(child);
+        continue;
+      }
+      splitWrapperAcrossSpan(child, wrapperStart, span, tracked, newChildren, placeReplacement);
+      continue;
+    }
+    newChildren.push(child);
+  }
+  if (!placed)
+    placeReplacement();
+  paragraph.children = newChildren;
+}
+function splitWrapperAcrossSpan(wrapper, wrapperStart, span, tracked, out, placeReplacement) {
+  const isDel = wrapper.tag === "w:del";
+  const preInner = [];
+  const cutInner = [];
+  const postInner = [];
+  let innerOffset = wrapperStart;
+  for (const inner of wrapper.children) {
+    if (inner.tag !== "w:r") {
+      preInner.push(inner);
+      continue;
+    }
+    const length = runTextLength(inner);
+    const runStart = innerOffset;
+    const runEnd = innerOffset + length;
+    innerOffset = runEnd;
+    if (runEnd <= span.start) {
+      preInner.push(inner);
+      continue;
+    }
+    if (runStart >= span.end) {
+      postInner.push(inner);
+      continue;
+    }
+    const sliceStartInRun = Math.max(0, span.start - runStart);
+    const sliceEndInRun = Math.min(length, span.end - runStart);
+    if (sliceStartInRun > 0)
+      preInner.push(sliceRun(inner, 0, sliceStartInRun));
+    cutInner.push(sliceRun(inner, sliceStartInRun, sliceEndInRun));
+    if (sliceEndInRun < length)
+      postInner.push(sliceRun(inner, sliceEndInRun, length));
+  }
+  const preChildren = preInner.slice();
+  if (isDel) {
+    preChildren.push(...cutInner);
+  } else if (tracked && cutInner.length > 0) {
+    for (const cutRun of cutInner)
+      convertRunTextToDelText(cutRun);
+    preChildren.push(/* @__PURE__ */ jsxDEV(Del, {
+      meta: mintMeta(tracked),
+      children: cutInner
+    }, undefined, false, undefined, this));
+  }
+  if (preChildren.length > 0) {
+    const preWrapper = new XmlNode2(wrapper.tag, { ...wrapper.attributes });
+    preWrapper.children = preChildren;
+    out.push(preWrapper);
+  }
+  placeReplacement();
+  if (postInner.length > 0) {
+    const postWrapper = new XmlNode2(wrapper.tag, { ...wrapper.attributes });
+    postWrapper.children = postInner;
+    out.push(postWrapper);
+  }
+}
+function sumInnerRunLengths(wrapper) {
+  let total = 0;
+  for (const inner of wrapper.children) {
+    if (inner.tag === "w:r")
+      total += runTextLength(inner);
+  }
+  return total;
+}
+function mintMeta(tracked) {
+  return { ...tracked.meta, revisionId: tracked.allocator.next() };
+}
+function convertRunTextToDelText(run20) {
+  for (const child of run20.children) {
+    if (child.tag === "w:t")
+      child.tag = "w:delText";
+  }
+}
+function ReplacementRun({
+  runProperties,
+  text
+}) {
+  return /* @__PURE__ */ jsxDEV(w.r, {
+    children: [
+      runProperties,
+      /* @__PURE__ */ jsxDEV(w.t, {
+        "xml:space": "preserve",
+        children: text
+      }, undefined, false, undefined, this)
+    ]
+  }, undefined, true, undefined, this);
+}
+var init_replace_span = __esm(() => {
+  init_core();
+  init_jsx();
+  init_parser();
+  init_jsx_dev_runtime();
+});
 
-// src/cli/schema/index.ts
-var exports_schema = {};
-__export(exports_schema, {
-  run: () => run18
+// src/cli/replace/index.ts
+var exports_replace2 = {};
+__export(exports_replace2, {
+  run: () => run20
 });
-import { parseArgs as parseArgs16 } from "util";
-async function run18(args) {
+import { parseArgs as parseArgs17 } from "util";
+async function run20(args) {
   let parsed;
   try {
-    parsed = parseArgs16({
+    parsed = parseArgs17({
       args,
       allowPositionals: true,
       options: {
-        json: { type: "boolean" },
-        ts: { type: "boolean" },
+        regex: { type: "boolean" },
+        "ignore-case": { type: "boolean" },
+        all: { type: "boolean" },
+        limit: { type: "string" },
+        output: { type: "string", short: "o" },
+        "dry-run": { type: "boolean" },
         help: { type: "boolean", short: "h" }
       }
     });
-  } catch (parseError) {
-    const message = parseError instanceof Error ? parseError.message : String(parseError);
-    return fail("USAGE", message, HELP18);
-  }
-  if (parsed.values.help) {
-    await writeStdout(HELP18);
+  } catch (parseError) {
+    const message = parseError instanceof Error ? parseError.message : String(parseError);
+    return fail("USAGE", message, HELP20);
+  }
+  if (parsed.values.help) {
+    await writeStdout(HELP20);
+    return EXIT.OK;
+  }
+  const path = parsed.positionals[0];
+  const pattern = parsed.positionals[1];
+  const replacement = parsed.positionals[2];
+  if (!path)
+    return fail("USAGE", "Missing FILE argument", HELP20);
+  if (pattern == null)
+    return fail("USAGE", "Missing PATTERN argument", HELP20);
+  if (replacement == null) {
+    return fail("USAGE", "Missing REPLACEMENT argument", HELP20);
+  }
+  const ignoreCase = Boolean(parsed.values["ignore-case"]);
+  const useRegex = Boolean(parsed.values.regex);
+  const wantAll = Boolean(parsed.values.all);
+  const limitRaw = parsed.values.limit;
+  const limit = limitRaw === undefined ? undefined : Number(limitRaw);
+  if (limit !== undefined && (!Number.isInteger(limit) || limit <= 0)) {
+    return fail("USAGE", `--limit must be a positive integer, got "${limitRaw}"`);
+  }
+  const view = await openOrFail(path);
+  if (typeof view === "number")
+    return view;
+  let allMatches;
+  try {
+    allMatches = findTextSpans(view.doc, pattern, {
+      regex: useRegex,
+      ignoreCase
+    });
+  } catch (matcherError) {
+    const message = matcherError instanceof Error ? matcherError.message : String(matcherError);
+    return fail("USAGE", `Invalid pattern: ${message}`);
+  }
+  let selected;
+  if (limit !== undefined) {
+    selected = allMatches.slice(0, limit);
+  } else if (wantAll) {
+    selected = allMatches;
+  } else {
+    selected = allMatches.slice(0, 1);
+  }
+  const matchesPayload = selected.map((match) => ({
+    locator: `${match.blockId}:${match.start}-${match.end}`,
+    blockId: match.blockId,
+    start: match.start,
+    end: match.end,
+    text: match.text
+  }));
+  const outputPath = parsed.values.output;
+  if (parsed.values["dry-run"]) {
+    await respond({
+      ok: true,
+      operation: "replace",
+      dryRun: true,
+      path,
+      pattern,
+      replacement,
+      regex: useRegex,
+      ignoreCase,
+      totalMatches: allMatches.length,
+      replaced: selected.length,
+      matches: matchesPayload,
+      ...outputPath ? { output: outputPath } : {}
+    });
     return EXIT.OK;
   }
-  if (parsed.values.ts) {
-    await Bun.write(Bun.stdout, types_default);
+  if (selected.length === 0) {
+    await respond({
+      ok: true,
+      operation: "replace",
+      path,
+      pattern,
+      replacement,
+      regex: useRegex,
+      ignoreCase,
+      totalMatches: 0,
+      replaced: 0,
+      matches: []
+    });
     return EXIT.OK;
   }
-  await respond(JSON_SCHEMA);
+  const reversed = [...selected].sort((leftMatch, rightMatch) => {
+    if (leftMatch.blockId !== rightMatch.blockId) {
+      return rightMatch.blockId.localeCompare(leftMatch.blockId);
+    }
+    return rightMatch.start - leftMatch.start;
+  });
+  const tracked = isTrackChangesEnabled(view) ? {
+    meta: { author: resolveAuthor(), date: resolveDate() },
+    allocator: createRevisionAllocator(view)
+  } : undefined;
+  const regexFlags = ignoreCase ? "i" : "";
+  for (const match of reversed) {
+    const concreteReplacement = useRegex ? match.text.replace(new RegExp(pattern, regexFlags), replacement) : replacement;
+    const blockRef = resolveBlock(view, match.blockId);
+    replaceSpanInParagraph(blockRef.node, { start: match.start, end: match.end }, concreteReplacement, tracked);
+  }
+  await saveDocView(view, outputPath);
+  await respond({
+    ok: true,
+    operation: "replace",
+    path: outputPath ?? path,
+    pattern,
+    replacement,
+    regex: useRegex,
+    ignoreCase,
+    totalMatches: allMatches.length,
+    replaced: selected.length,
+    matches: matchesPayload
+  });
   return EXIT.OK;
 }
-var HELP18 = `docx schema \u2014 print the AST type definitions
+var HELP20 = `docx replace \u2014 substitute text spans (sed for docx)
 
 Usage:
-  docx schema [options]
+  docx replace FILE PATTERN REPLACEMENT [options]
 
 Options:
-  --json       Print as a JSON Schema document (default)
-  --ts         Print TypeScript type source (read live from src/core/ast/types.ts)
-  -h, --help   Show this help
+  --regex           treat PATTERN as a JavaScript regular expression
+  --ignore-case     case-insensitive match
+  --all             replace every match (default: just the first)
+  --limit N         replace at most N matches (in document order)
+  -o, --output PATH write to PATH instead of overwriting FILE
+  --dry-run         report what would change without writing the file
+  -h, --help        show this help
+
+Within-paragraph matches only. Run formatting (rPr) on the surrounding text
+is preserved; the replacement run inherits the rPr of the first run that
+overlaps the matched span. When a single invocation produces multiple
+replacements in the same paragraph, they're applied in reverse offset order
+so earlier offsets don't shift before being applied.
+
+With --regex, REPLACEMENT supports JS String.replace substitution syntax:
+  $1, $2, ...   numbered capture groups
+  $&            the matched substring
+  $\`            text before the match
+  $'            text after the match
+  $$            a literal $
 
 Examples:
-  docx schema | jq '.definitions.Run'
-  docx schema --ts > ast.d.ts
-`, JSON_SCHEMA;
-var init_schema = __esm(() => {
-  init_types();
+  docx replace doc.docx "fox" "cat"
+  docx replace doc.docx "fox" "cat" --all
+  docx replace doc.docx "TODO|FIXME" "DONE" --regex --all
+  docx replace doc.docx "(\\w+) (\\w+)" "$2 $1" --regex --all
+  docx replace doc.docx "wordy phrase" "tighter phrase" --all --dry-run
+`;
+var init_replace2 = __esm(() => {
+  init_core();
   init_respond();
-  JSON_SCHEMA = {
-    $schema: "https://json-schema.org/draft/2020-12/schema",
-    $id: "https://github.com/kklimuk/docx-cli/schema",
-    title: "docx-cli AST",
-    type: "object",
-    required: ["schemaVersion", "path", "properties", "blocks", "comments"],
-    properties: {
-      schemaVersion: { const: 1 },
-      path: { type: "string" },
-      properties: {
-        type: "object",
-        properties: {
-          title: { type: "string" },
-          author: { type: "string" },
-          created: { type: "string" },
-          modified: { type: "string" }
-        }
-      },
-      blocks: { type: "array", items: { $ref: "#/$defs/Block" } },
-      comments: { type: "array", items: { $ref: "#/$defs/Comment" } }
-    },
-    $defs: {
-      Block: {
-        oneOf: [
-          { $ref: "#/$defs/Paragraph" },
-          { $ref: "#/$defs/Table" },
-          { $ref: "#/$defs/SectionBreak" }
-        ]
-      },
-      Paragraph: {
-        type: "object",
-        required: ["id", "type", "runs"],
-        properties: {
-          id: { type: "string" },
-          type: { const: "paragraph" },
-          style: { type: "string" },
-          alignment: { enum: ["left", "center", "right", "justify"] },
-          list: {
-            type: "object",
-            required: ["level", "numId"],
-            properties: {
-              level: { type: "number" },
-              numId: { type: "string" }
-            }
-          },
-          runs: { type: "array", items: { $ref: "#/$defs/Run" } }
-        }
-      },
-      Run: {
-        oneOf: [
-          { $ref: "#/$defs/TextRun" },
-          { $ref: "#/$defs/ImageRun" },
-          { $ref: "#/$defs/BreakRun" },
-          { $ref: "#/$defs/TabRun" }
-        ]
-      },
-      TextRun: {
-        type: "object",
-        required: ["type", "text"],
-        properties: {
-          type: { const: "text" },
-          text: { type: "string" },
-          color: { type: "string" },
-          highlight: { type: "string" },
-          bold: { type: "boolean" },
-          italic: { type: "boolean" },
-          underline: { type: "string" },
-          strike: { type: "boolean" },
-          font: { type: "string" },
-          sizeHalfPoints: { type: "number" },
-          comments: { type: "array", items: { type: "string" } },
-          trackedChange: {
-            type: "object",
-            required: ["kind", "author", "date", "revisionId"],
-            properties: {
-              kind: { enum: ["ins", "del"] },
-              author: { type: "string" },
-              date: { type: "string" },
-              revisionId: { type: "string" }
-            }
-          }
-        }
-      },
-      ImageRun: {
-        type: "object",
-        required: ["type", "id", "contentType", "hash"],
-        properties: {
-          type: { const: "image" },
-          id: { type: "string" },
-          contentType: { type: "string" },
-          hash: { type: "string" },
-          widthEmu: { type: "number" },
-          heightEmu: { type: "number" },
-          alt: { type: "string" }
-        }
-      },
-      BreakRun: {
-        type: "object",
-        required: ["type", "kind"],
-        properties: {
-          type: { const: "break" },
-          kind: { enum: ["page", "line", "column"] }
-        }
-      },
-      TabRun: {
-        type: "object",
-        required: ["type"],
-        properties: { type: { const: "tab" } }
-      },
-      Table: {
-        type: "object",
-        required: ["id", "type", "rows"],
-        properties: {
-          id: { type: "string" },
-          type: { const: "table" },
-          rows: {
-            type: "array",
-            items: {
-              type: "object",
-              properties: {
-                cells: {
-                  type: "array",
-                  items: {
-                    type: "object",
-                    properties: {
-                      blocks: {
-                        type: "array",
-                        items: { $ref: "#/$defs/Block" }
-                      }
-                    }
-                  }
-                }
-              }
-            }
-          }
-        }
-      },
-      SectionBreak: {
-        type: "object",
-        required: ["id", "type"],
-        properties: {
-          id: { type: "string" },
-          type: { const: "sectionBreak" }
-        }
-      },
-      Comment: {
-        type: "object",
-        required: ["id", "author", "date", "text", "anchor"],
-        properties: {
-          id: { type: "string" },
-          author: { type: "string" },
-          initials: { type: "string" },
-          date: { type: "string" },
-          text: { type: "string" },
-          parentId: { type: "string" },
-          resolved: { type: "boolean" },
-          anchor: {
-            type: "object",
-            required: ["startBlockId", "startOffset", "endBlockId", "endOffset"],
-            properties: {
-              startBlockId: { type: "string" },
-              startOffset: { type: "number" },
-              endBlockId: { type: "string" },
-              endOffset: { type: "number" }
-            }
-          }
-        }
-      }
-    }
-  };
+  init_replace_span();
 });
 
 // src/cli/track-changes/index.tsx
 var exports_track_changes = {};
 __export(exports_track_changes, {
-  run: () => run19
+  run: () => run21
 });
-import { parseArgs as parseArgs17 } from "util";
-async function run19(args) {
+import { parseArgs as parseArgs18 } from "util";
+async function run21(args) {
   let parsed;
   try {
-    parsed = parseArgs17({
+    parsed = parseArgs18({
       args,
       allowPositionals: true,
       options: {
+        output: { type: "string", short: "o" },
         "dry-run": { type: "boolean" },
         help: { type: "boolean", short: "h" }
       }
     });
   } catch (parseError) {
     const message = parseError instanceof Error ? parseError.message : String(parseError);
-    return fail("USAGE", message, HELP19);
+    return fail("USAGE", message, HELP21);
   }
   if (parsed.values.help) {
-    await writeStdout(HELP19);
+    await writeStdout(HELP21);
     return EXIT.OK;
   }
   const path = parsed.positionals[0];
   if (!path)
-    return fail("USAGE", "Missing FILE argument", HELP19);
+    return fail("USAGE", "Missing FILE argument", HELP21);
   const mode = parsed.positionals[1];
   if (mode !== "on" && mode !== "off") {
-    return fail("USAGE", `Expected "on" or "off", got: ${mode ?? "<nothing>"}`, HELP19);
-  }
-  let view;
-  try {
-    view = await openDocView(path);
-  } catch (openError) {
-    if (openError instanceof PkgError) {
-      if (openError.code === "FILE_NOT_FOUND") {
-        return fail("FILE_NOT_FOUND", openError.message);
-      }
-      if (openError.code === "NOT_A_ZIP") {
-        return fail("NOT_A_ZIP", openError.message);
-      }
-    }
-    throw openError;
-  }
-  const settingsXml = view.pkg.hasPart(SETTINGS_PART) ? await view.pkg.readText(SETTINGS_PART) : null;
-  const settingsTree = settingsXml ? XmlNode2.parse(settingsXml) : [];
-  let settingsRoot = XmlNode2.findRoot(settingsTree, "w:settings");
+    return fail("USAGE", `Expected "on" or "off", got: ${mode ?? "<nothing>"}`, HELP21);
+  }
+  const view = await openOrFail(path);
+  if (typeof view === "number")
+    return view;
+  const wasMissing = view.settingsTree === undefined;
+  if (!view.settingsTree)
+    view.settingsTree = [];
+  let settingsRoot = XmlNode2.findRoot(view.settingsTree, "w:settings");
   if (!settingsRoot) {
     settingsRoot = /* @__PURE__ */ jsxDEV(w.settings, {
       "xmlns:w": NS_W2
     }, undefined, false, undefined, this);
-    settingsTree.push(settingsRoot);
+    view.settingsTree.push(settingsRoot);
   }
   const hasTrackChanges = settingsRoot.children.some((child) => child.tag === "w:trackChanges");
+  const outputPath = parsed.values.output;
   if (parsed.values["dry-run"]) {
     await respond({
       ok: true,
@@ -17432,7 +18289,8 @@ async function run19(args) {
       dryRun: true,
       path,
       mode,
-      previouslyOn: hasTrackChanges
+      previouslyOn: hasTrackChanges,
+      ...outputPath ? { output: outputPath } : {}
     });
     return EXIT.OK;
   }
@@ -17441,71 +18299,36 @@ async function run19(args) {
   } else if (mode === "off" && hasTrackChanges) {
     settingsRoot.children = settingsRoot.children.filter((child) => child.tag !== "w:trackChanges");
   }
-  view.pkg.writeText(SETTINGS_PART, XmlNode2.serializeWithDeclaration(settingsTree));
-  if (!settingsXml) {
-    registerSettingsPart(view);
+  if (wasMissing) {
+    registerPart(view.relationshipsTree, view.contentTypesTree, {
+      partName: SETTINGS_PART,
+      contentType: SETTINGS_CONTENT_TYPE,
+      relationshipType: SETTINGS_REL_TYPE,
+      target: "settings.xml"
+    });
   }
-  view.pkg.writeText("word/_rels/document.xml.rels", XmlNode2.serializeWithDeclaration(view.relationshipsTree));
-  view.pkg.writeText("[Content_Types].xml", XmlNode2.serializeWithDeclaration(view.contentTypesTree));
-  await view.pkg.save();
+  await saveDocView(view, outputPath);
   await respond({
     ok: true,
     operation: "track-changes",
-    path,
+    path: outputPath ?? path,
     mode,
     previouslyOn: hasTrackChanges
   });
   return EXIT.OK;
 }
-function registerSettingsPart(view) {
-  const relationships = XmlNode2.findRoot(view.relationshipsTree, "Relationships");
-  if (relationships) {
-    const alreadyLinked = relationships.children.some((child) => child.tag === "Relationship" && child.getAttribute("Type") === SETTINGS_REL_TYPE);
-    if (!alreadyLinked) {
-      relationships.children.push(new XmlNode2("Relationship", {
-        Id: nextRelationshipId2(relationships),
-        Type: SETTINGS_REL_TYPE,
-        Target: "settings.xml"
-      }));
-    }
-  }
-  const types = XmlNode2.findRoot(view.contentTypesTree, "Types");
-  if (types) {
-    const exists = types.children.some((child) => child.tag === "Override" && child.getAttribute("PartName") === `/${SETTINGS_PART}`);
-    if (!exists) {
-      types.children.push(new XmlNode2("Override", {
-        PartName: `/${SETTINGS_PART}`,
-        ContentType: SETTINGS_CONTENT_TYPE
-      }));
-    }
-  }
-}
-function nextRelationshipId2(relationships) {
-  let highest = 0;
-  for (const child of relationships.children) {
-    if (child.tag !== "Relationship")
-      continue;
-    const id = child.getAttribute("Id");
-    if (!id)
-      continue;
-    const match = id.match(/^rId(\d+)$/);
-    if (!match)
-      continue;
-    const numeric = Number(match[1]);
-    if (Number.isFinite(numeric) && numeric > highest)
-      highest = numeric;
-  }
-  return `rId${highest + 1}`;
-}
-var HELP19 = `docx track-changes \u2014 toggle the document's tracked-changes mode
+var HELP21 = `docx track-changes \u2014 toggle the document's tracked-changes mode
 
 Usage:
   docx track-changes FILE on|off [options]
 
-Sets <w:trackChanges/> in word/settings.xml. When on, Word records new
-edits as tracked changes. Existing <w:ins>/<w:del> markers are unaffected.
+Sets <w:trackChanges/> in word/settings.xml. When on, this CLI's
+insert/edit/delete/replace commands also emit <w:ins>/<w:del> markers
+(attributed to $DOCX_AUTHOR) so changes remain reviewable. Existing
+<w:ins>/<w:del> markers are unaffected by the toggle itself.
 
 Options:
+  -o, --output PATH Write to PATH instead of overwriting FILE
   --dry-run         Print what would change; do not write the file
   -h, --help        Show this help
 
@@ -17513,17 +18336,79 @@ Examples:
   docx track-changes doc.docx on
   docx track-changes doc.docx off
 `, SETTINGS_PART = "word/settings.xml", SETTINGS_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/settings", SETTINGS_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.settings+xml", NS_W2 = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
-var init_track_changes = __esm(() => {
+var init_track_changes2 = __esm(() => {
   init_core();
   init_jsx();
+  init_package();
   init_parser();
   init_respond();
   init_jsx_dev_runtime();
 });
+// package.json
+var package_default = {
+  name: "bun-docx",
+  version: "0.3.0",
+  description: "CLI for AI agents (Claude, Codex) to read, edit, and comment on .docx files with full format fidelity.",
+  keywords: [
+    "docx",
+    "openxml",
+    "ooxml",
+    "word",
+    "cli",
+    "ai",
+    "claude",
+    "codex",
+    "agentic"
+  ],
+  license: "MIT",
+  author: "Kirill Klimuk",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/kklimuk/docx-cli.git"
+  },
+  homepage: "https://github.com/kklimuk/docx-cli#readme",
+  bugs: "https://github.com/kklimuk/docx-cli/issues",
+  type: "module",
+  packageManager: "bun@1.3.13",
+  bin: {
+    docx: "./dist/index.js"
+  },
+  files: [
+    "dist/index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  engines: {
+    bun: ">=1.3.0"
+  },
+  scripts: {
+    dev: "bun src/index.ts",
+    build: "bun build src/index.ts --outfile dist/index.js --target bun",
+    "build:binary": "bun build --compile --outfile=dist/docx src/index.ts",
+    check: "biome check . && knip-bun && bunx tsc --noEmit",
+    test: "bun test",
+    "test:unit": "bun test tests/core tests/cli",
+    "test:integration": "bun test tests/integration",
+    prepack: "bun run build",
+    prepare: "husky"
+  },
+  devDependencies: {
+    "@biomejs/biome": "^2.4.10",
+    "@types/bun": "^1.3.13",
+    husky: "^9.1.7",
+    knip: "^6.3.0",
+    typescript: "^6.0.2"
+  },
+  dependencies: {
+    "fast-xml-builder": "^1.1.6",
+    "fast-xml-parser": "^5.7.2",
+    jszip: "^3.10.1"
+  }
+};
 
 // src/cli/help.ts
 init_respond();
-var VERSION = "0.1.0";
+var VERSION = package_default.version;
 var TOP_HELP = `docx ${VERSION} \u2014 read, edit, and comment on .docx files
 
 Usage:
@@ -17535,16 +18420,23 @@ Commands:
   edit      FILE  Replace text/properties at a locator
   insert    FILE  Insert a block or run
   delete    FILE  Remove a block or run range
-  comments  \u2026     Add, reply, resolve, delete, restore, list comments
+  find      FILE QUERY  Find text spans, return locators
+  replace   FILE PATTERN REPL  Substitute text spans (sed for docx)
+  comments  \u2026     Add, reply, resolve, delete, list comments
   images    \u2026     Extract, replace, list images
   track-changes FILE on|off  Toggle tracked-changes mode
-  schema          Dump AST JSON Schema
-  locators        Dump locator grammar reference
+  info      \u2026     Reference material (schema, locators)
 
 Run "docx <command> --help" for command-specific help.
 
 Environment:
-  DOCX_AUTHOR  Default --author for "comments add" / "comments reply"
+  DOCX_AUTHOR    Default author for comments and tracked-change attribution
+  DOCX_CLI_NOW   Override the timestamp used for tracked changes (test only)
+
+Tracked changes:
+  When <w:trackChanges/> is set in the doc (toggle via "docx track-changes
+  FILE on"), insert/edit/delete/replace automatically emit <w:ins>/<w:del>
+  markers attributed to $DOCX_AUTHOR.
 `;
 async function printTopHelp() {
   await writeStdout(TOP_HELP);
@@ -17557,18 +18449,19 @@ var COMMANDS = {
   create: () => Promise.resolve().then(() => (init_create(), exports_create)),
   delete: () => Promise.resolve().then(() => (init_delete2(), exports_delete2)),
   edit: () => Promise.resolve().then(() => (init_edit(), exports_edit)),
+  find: () => Promise.resolve().then(() => (init_find(), exports_find)),
   images: () => Promise.resolve().then(() => (init_images(), exports_images)),
+  info: () => Promise.resolve().then(() => (init_info(), exports_info)),
   insert: () => Promise.resolve().then(() => (init_insert(), exports_insert)),
-  locators: () => Promise.resolve().then(() => (init_locators_cmd(), exports_locators_cmd)),
   read: () => Promise.resolve().then(() => (init_read2(), exports_read)),
-  schema: () => Promise.resolve().then(() => (init_schema(), exports_schema)),
-  "track-changes": () => Promise.resolve().then(() => (init_track_changes(), exports_track_changes))
+  replace: () => Promise.resolve().then(() => (init_replace2(), exports_replace2)),
+  "track-changes": () => Promise.resolve().then(() => (init_track_changes2(), exports_track_changes))
 };
 async function main(argv) {
   const args = argv.slice(2);
   const cmd = args[0];
   if (!cmd) {
-    process.stderr.write(`Usage: docx <command> [options]
+    Bun.stderr.write(`Usage: docx <command> [options]
 Run "docx --help" for available commands.
 `);
     return 2;