bun-docx 0.1.0 → 0.2.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) {
@@ -13708,70 +13571,245 @@ 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(deepCloneNode(child));
+  }
+  return sliced;
+}
+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));
+  }
+  return clone;
+}
+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);
-  }
-  const activeComments = new Set;
-  let offset = 0;
-  for (const child of node.children) {
-    if (child.tag === "w:pPr")
-      continue;
-    if (child.tag === "w:commentRangeStart") {
+var init_parts = __esm(() => {
+  init_parser();
+});
+
+// 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(() => {
+  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;
+    if (child.tag === "w:commentRangeStart") {
       const commentId = child.getAttribute("w:id");
       if (commentId) {
         const key = `c${commentId}`;
@@ -13815,6 +13853,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);
@@ -13954,26 +14019,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 +14208,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 +14217,7 @@ async function openDocView(path) {
     relationshipsTree,
     contentTypesTree,
     corePropertiesTree,
+    settingsTree,
     doc: undefined,
     blockReferences: new Map,
     commentReferences: new Map,
@@ -14163,6 +14237,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 +14367,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 +14376,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) {
@@ -14332,6 +14429,78 @@ var init_core = __esm(() => {
   init_parser();
 });
 
+// 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/core/jsx/index.ts
 function namespace(prefix, tags) {
   const result = {};
@@ -14548,7 +14717,7 @@ function ensureCommentsPart(view) {
     "xmlns:w14": NS_W14
   }, undefined, false, undefined, this);
   view.commentsTree = [root];
-  registerPart(view, {
+  registerPart(view.relationshipsTree, view.contentTypesTree, {
     partName: "word/comments.xml",
     contentType: COMMENTS_CONTENT_TYPE,
     relationshipType: COMMENTS_REL_TYPE,
@@ -14568,7 +14737,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,77 +14745,66 @@ 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
-      }));
+function paragraphTextLength(paragraph) {
+  let total = 0;
+  for (const child of paragraph.children) {
+    if (child.tag === "w:r")
+      total += runTextLength(child);
+    else if (child.tag === "w:ins" || child.tag === "w:del") {
+      for (const inner of child.children) {
+        if (inner.tag === "w:r")
+          total += runTextLength(inner);
+      }
     }
   }
-  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
-      }));
-    }
+  return total;
+}
+function addCommentMarkersToParagraph(paragraph, commentId, span) {
+  const total = paragraphTextLength(paragraph);
+  const range = span ?? { start: 0, end: total };
+  if (range.start < 0 || range.end > total || range.start > range.end) {
+    throw new SpanOutOfRangeError(`Span ${range.start}-${range.end} out of paragraph length ${total}`);
   }
+  placeMarkersInParagraph(paragraph, [
+    { offset: range.start, node: commentRangeStartMarker(commentId) },
+    {
+      offset: range.end,
+      node: commentRangeEndMarker(commentId),
+      follower: commentReferenceRun(commentId)
+    }
+  ]);
 }
-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;
+function addCommentRangeMarkers(startParagraph, startOffset, endParagraph, endOffset, commentId) {
+  if (startParagraph === endParagraph) {
+    addCommentMarkersToParagraph(startParagraph, commentId, {
+      start: startOffset,
+      end: endOffset
+    });
+    return;
   }
-  return `rId${highest + 1}`;
-}
-function paragraphTextLength(paragraph) {
-  let total = 0;
-  for (const child of paragraph.children) {
-    if (child.tag === "w:r")
-      total += runTextLength(child);
-    else if (child.tag === "w:ins" || child.tag === "w:del") {
-      for (const inner of child.children) {
-        if (inner.tag === "w:r")
-          total += runTextLength(inner);
-      }
+  placeMarkersInParagraph(startParagraph, [
+    { offset: startOffset, node: commentRangeStartMarker(commentId) }
+  ]);
+  placeMarkersInParagraph(endParagraph, [
+    {
+      offset: endOffset,
+      node: commentRangeEndMarker(commentId),
+      follower: commentReferenceRun(commentId)
     }
-  }
-  return total;
+  ]);
 }
-function addCommentMarkersToParagraph(paragraph, commentId, span) {
-  const total = paragraphTextLength(paragraph);
-  const range = span ?? { start: 0, end: total };
-  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, {
+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 +14816,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 +15018,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 {
@@ -14927,34 +15075,75 @@ 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;
+  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();
+  if (parsed.values["dry-run"]) {
+    await respond({
+      ok: true,
+      operation: "comments.add",
+      dryRun: true,
+      path,
+      commentId: `c${numericId}`,
+      locator: rangeInput
+    });
+    return EXIT.OK;
   }
-  let paragraphRef;
   try {
-    paragraphRef = resolveBlock(view, blockId);
+    addCommentMarkersToParagraph(paragraphRef.node, numericId, span);
   } catch (error) {
-    if (error instanceof LocatorResolveError) {
-      return fail("BLOCK_NOT_FOUND", error.message);
+    if (error instanceof SpanOutOfRangeError) {
+      return fail("INVALID_LOCATOR", error.message);
     }
     throw error;
   }
-  const span = locator.kind === "blockSpan" ? { start: locator.start, end: locator.end } : undefined;
+  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);
+  await respond({
+    ok: true,
+    operation: "comments.add",
+    path,
+    commentId: `c${numericId}`,
+    locator: rangeInput
+  });
+  return EXIT.OK;
+}
+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);
@@ -14971,7 +15160,7 @@ async function run(args) {
     return EXIT.OK;
   }
   try {
-    addCommentMarkersToParagraph(paragraphRef.node, numericId, span);
+    addCommentRangeMarkers(startRef.node, locator.start.offset, endRef.node, locator.end.offset, numericId);
   } catch (error) {
     if (error instanceof SpanOutOfRangeError) {
       return fail("INVALID_LOCATOR", error.message);
@@ -15005,8 +15194,12 @@ 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)
+  --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:
@@ -15017,6 +15210,7 @@ Optional:
 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();
@@ -15106,20 +15300,9 @@ 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}`);
@@ -15236,20 +15419,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 +15465,6 @@ Examples:
   docx comments list doc.docx --include-resolved | jq '.[] | select(.author == "Jane")'
 `;
 var init_list = __esm(() => {
-  init_core();
   init_respond();
 });
 
@@ -15335,20 +15506,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}`);
@@ -15459,20 +15619,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}`);
@@ -15584,34 +15733,19 @@ async function run6(args) {
   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 view = await openOrFail(path);
+  if (typeof view === "number")
+    return view;
+  const startBlock = view.blockReferences.get(entry.anchor.startBlockId);
+  if (!startBlock) {
+    return fail("BLOCK_NOT_FOUND", `Original anchor block ${entry.anchor.startBlockId} no longer exists`);
   }
-  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 endBlock = view.blockReferences.get(entry.anchor.endBlockId);
+  if (!endBlock) {
+    return fail("BLOCK_NOT_FOUND", `Original anchor block ${entry.anchor.endBlockId} no longer exists`);
   }
-  const span = {
-    start: entry.anchor.startOffset,
-    end: entry.anchor.endOffset
-  };
   try {
-    addCommentMarkersToParagraph(block.node, numericId, span);
+    addCommentRangeMarkers(startBlock.node, entry.anchor.startOffset, endBlock.node, entry.anchor.endOffset, numericId);
   } catch (error) {
     if (error instanceof SpanOutOfRangeError) {
       return fail("INVALID_LOCATOR", `Saved span no longer fits the block: ${error.message}`);
@@ -15836,7 +15970,7 @@ async function run8(args) {
   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();
@@ -15915,29 +16049,12 @@ async function run9(args) {
   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;
-  }
+  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)");
@@ -16152,29 +16269,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;
@@ -16255,12 +16355,86 @@ var init_edit = __esm(() => {
   init_jsx_dev_runtime();
 });
 
-// src/cli/images/extract.ts
-var exports_extract = {};
-__export(exports_extract, {
+// 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((run11) => run11.type === "text" ? run11.text : "").join("");
+      for (const span of matcher(paragraphText)) {
+        out.push({
+          blockId: block.id,
+          start: span.start,
+          end: span.end,
+          text: span.text
+        });
+      }
+      continue;
+    }
+    if (block.type === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          collectMatches(cell.blocks, matcher, out);
+        }
+      }
+    }
+  }
+}
+
+// src/cli/find/index.ts
+var exports_find = {};
+__export(exports_find, {
   run: () => run11
 });
-import { join as join2 } from "path";
 import { parseArgs as parseArgs10 } from "util";
 async function run11(args) {
   let parsed;
@@ -16269,8 +16443,10 @@ async function run11(args) {
       args,
       allowPositionals: true,
       options: {
-        to: { type: "string" },
-        id: { type: "string" },
+        regex: { type: "boolean" },
+        "ignore-case": { type: "boolean" },
+        all: { type: "boolean" },
+        nth: { type: "string" },
         help: { type: "boolean", short: "h" }
       }
     });
@@ -16283,43 +16459,143 @@ async function run11(args) {
     return EXIT.OK;
   }
   const path = parsed.positionals[0];
+  const query = parsed.positionals[1];
   if (!path)
     return fail("USAGE", "Missing FILE argument", HELP11);
-  const outputDir = parsed.values.to;
-  if (!outputDir)
-    return fail("USAGE", "Missing --to DIR", HELP11);
-  const targetId = parsed.values.id;
-  let view;
+  if (query == null)
+    return fail("USAGE", "Missing QUERY argument", HELP11);
+  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 {
-    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;
-  }
-  await enrichImageHashes(view);
-  const allImages = [];
-  collectImages(view.doc.blocks, allImages);
-  const targets = targetId ? allImages.filter((image) => image.id === targetId) : allImages;
-  if (targetId && targets.length === 0) {
-    return fail("IMAGE_NOT_FOUND", `Image not found: ${targetId}`);
+    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);
   }
-  const manifest = [];
-  const seenHashes = new Set;
-  for (const image of targets) {
-    const reference = view.imageById.get(image.id);
-    if (!reference)
-      continue;
-    const extension = extensionFor(image.contentType, reference.partName);
-    const fileName = `${image.hash}.${extension}`;
-    const outputPath = join2(outputDir, fileName);
-    if (!seenHashes.has(image.hash)) {
+  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 HELP11 = `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: () => run12
+});
+import { join as join2 } from "path";
+import { parseArgs as parseArgs11 } from "util";
+async function run12(args) {
+  let parsed;
+  try {
+    parsed = parseArgs11({
+      args,
+      allowPositionals: true,
+      options: {
+        to: { type: "string" },
+        id: { type: "string" },
+        help: { type: "boolean", short: "h" }
+      }
+    });
+  } catch (parseError) {
+    const message = parseError instanceof Error ? parseError.message : String(parseError);
+    return fail("USAGE", message, HELP12);
+  }
+  if (parsed.values.help) {
+    await writeStdout(HELP12);
+    return EXIT.OK;
+  }
+  const path = parsed.positionals[0];
+  if (!path)
+    return fail("USAGE", "Missing FILE argument", HELP12);
+  const outputDir = parsed.values.to;
+  if (!outputDir)
+    return fail("USAGE", "Missing --to DIR", HELP12);
+  const targetId = parsed.values.id;
+  const view = await openOrFail(path);
+  if (typeof view === "number")
+    return view;
+  await enrichImageHashes(view);
+  const allImages = [];
+  collectImages(view.doc.blocks, allImages);
+  const targets = targetId ? allImages.filter((image) => image.id === targetId) : allImages;
+  if (targetId && targets.length === 0) {
+    return fail("IMAGE_NOT_FOUND", `Image not found: ${targetId}`);
+  }
+  const manifest = [];
+  const seenHashes = new Set;
+  for (const image of targets) {
+    const reference = view.imageById.get(image.id);
+    if (!reference)
+      continue;
+    const extension = extensionFor(image.contentType, reference.partName);
+    const fileName = `${image.hash}.${extension}`;
+    const outputPath = join2(outputDir, fileName);
+    if (!seenHashes.has(image.hash)) {
       const bytes = await view.pkg.readBytes(reference.partName);
       await Bun.write(outputPath, bytes);
       seenHashes.add(image.hash);
@@ -16336,9 +16612,9 @@ async function run11(args) {
 function collectImages(blocks, out) {
   for (const block of blocks) {
     if (block.type === "paragraph") {
-      for (const run12 of block.runs) {
-        if (run12.type === "image")
-          out.push(run12);
+      for (const run13 of block.runs) {
+        if (run13.type === "image")
+          out.push(run13);
       }
       continue;
     }
@@ -16358,7 +16634,7 @@ function extensionFor(contentType, partName) {
   const fromName = partName.split(".").pop()?.toLowerCase();
   return fromName ?? "bin";
 }
-var HELP11 = `docx images extract \u2014 dump image bytes to a directory
+var HELP12 = `docx images extract \u2014 dump image bytes to a directory
 
 Usage:
   docx images extract FILE --to DIR [options]
@@ -16399,13 +16675,13 @@ var init_extract = __esm(() => {
 // src/cli/images/list.ts
 var exports_list2 = {};
 __export(exports_list2, {
-  run: () => run12
+  run: () => run13
 });
-import { parseArgs as parseArgs11 } from "util";
-async function run12(args) {
+import { parseArgs as parseArgs12 } from "util";
+async function run13(args) {
   let parsed;
   try {
-    parsed = parseArgs11({
+    parsed = parseArgs12({
       args,
       allowPositionals: true,
       options: {
@@ -16414,29 +16690,18 @@ async function run12(args) {
     });
   } catch (parseError) {
     const message = parseError instanceof Error ? parseError.message : String(parseError);
-    return fail("USAGE", message, HELP12);
+    return fail("USAGE", message, HELP13);
   }
   if (parsed.values.help) {
-    await writeStdout(HELP12);
+    await writeStdout(HELP13);
     return EXIT.OK;
   }
   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;
-  }
+    return fail("USAGE", "Missing FILE argument", HELP13);
+  const view = await openOrFail(path);
+  if (typeof view === "number")
+    return view;
   await enrichImageHashes(view);
   const images = [];
   collectImages2(view.doc.blocks, images);
@@ -16446,9 +16711,9 @@ async function run12(args) {
 function collectImages2(blocks, out) {
   for (const block of blocks) {
     if (block.type === "paragraph") {
-      for (const run13 of block.runs) {
-        if (run13.type === "image")
-          out.push(run13);
+      for (const run14 of block.runs) {
+        if (run14.type === "image")
+          out.push(run14);
       }
       continue;
     }
@@ -16461,7 +16726,7 @@ function collectImages2(blocks, out) {
     }
   }
 }
-var HELP12 = `docx images list \u2014 print image manifest as JSON
+var HELP13 = `docx images list \u2014 print image manifest as JSON
 
 Usage:
   docx images list FILE [options]
@@ -16480,13 +16745,13 @@ var init_list2 = __esm(() => {
 // src/cli/images/replace.ts
 var exports_replace = {};
 __export(exports_replace, {
-  run: () => run13
+  run: () => run14
 });
-import { parseArgs as parseArgs12 } from "util";
-async function run13(args) {
+import { parseArgs as parseArgs13 } from "util";
+async function run14(args) {
   let parsed;
   try {
-    parsed = parseArgs12({
+    parsed = parseArgs13({
       args,
       allowPositionals: true,
       options: {
@@ -16498,21 +16763,21 @@ async function run13(args) {
     });
   } catch (parseError) {
     const message = parseError instanceof Error ? parseError.message : String(parseError);
-    return fail("USAGE", message, HELP13);
+    return fail("USAGE", message, HELP14);
   }
   if (parsed.values.help) {
-    await writeStdout(HELP13);
+    await writeStdout(HELP14);
     return EXIT.OK;
   }
   const path = parsed.positionals[0];
   if (!path)
-    return fail("USAGE", "Missing FILE argument", HELP13);
+    return fail("USAGE", "Missing FILE argument", HELP14);
   const targetId = parsed.values.at;
   if (!targetId)
-    return fail("USAGE", "Missing --at IMG_ID", HELP13);
+    return fail("USAGE", "Missing --at IMG_ID", HELP14);
   const sourcePath = parsed.values.with;
   if (!sourcePath)
-    return fail("USAGE", "Missing --with PATH", HELP13);
+    return fail("USAGE", "Missing --with PATH", HELP14);
   const sourceFile = Bun.file(sourcePath);
   if (!await sourceFile.exists()) {
     return fail("FILE_NOT_FOUND", `Replacement file not found: ${sourcePath}`);
@@ -16522,20 +16787,9 @@ 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}`);
@@ -16613,7 +16867,7 @@ function ensureContentTypeDefault(contentTypesTree, extension, mimeType) {
   }
   types.children.push(new XmlNode2("Default", { Extension: extension, ContentType: mimeType }));
 }
-var HELP13 = `docx images replace \u2014 swap an image's bytes
+var HELP14 = `docx images replace \u2014 swap an image's bytes
 
 Usage:
   docx images replace FILE --at IMG_ID --with PATH [options]
@@ -16655,12 +16909,12 @@ var init_replace = __esm(() => {
 // src/cli/images/index.ts
 var exports_images = {};
 __export(exports_images, {
-  run: () => run14
+  run: () => run15
 });
-async function run14(args) {
+async function run15(args) {
   const verb = args[0];
   if (!verb || verb === "--help" || verb === "-h" || verb === "help") {
-    await writeStdout(HELP14);
+    await writeStdout(HELP15);
     return verb ? 0 : 2;
   }
   const loader = SUBCOMMANDS2[verb];
@@ -16670,7 +16924,7 @@ async function run14(args) {
   const module_ = await loader();
   return module_.run(args.slice(1));
 }
-var SUBCOMMANDS2, HELP14 = `docx images \u2014 manage embedded images
+var SUBCOMMANDS2, HELP15 = `docx images \u2014 manage embedded images
 
 Usage:
   docx images <verb> FILE [options]
@@ -16691,58 +16945,536 @@ var init_images = __esm(() => {
   };
 });
 
-// src/cli/insert/index.tsx
-var exports_insert = {};
-__export(exports_insert, {
-  run: () => run15
+// 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: () => run16
 });
-import { parseArgs as parseArgs13 } from "util";
-async function run15(args) {
+import { parseArgs as parseArgs14 } from "util";
+async function run16(args) {
   let parsed;
   try {
-    parsed = parseArgs13({
+    parsed = parseArgs14({
       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" }
       }
     });
   } catch (parseError) {
     const message = parseError instanceof Error ? parseError.message : String(parseError);
-    return fail("USAGE", message, HELP15);
+    return fail("USAGE", message, HELP16);
   }
   if (parsed.values.help) {
-    await writeStdout(HELP15);
+    await writeStdout(HELP16);
     return EXIT.OK;
   }
-  const path = parsed.positionals[0];
-  if (!path)
-    return fail("USAGE", "Missing FILE argument", HELP15);
-  const after = parsed.values.after;
+  if (parsed.values.ts) {
+    await writeStdout(types_default);
+    return EXIT.OK;
+  }
+  await respond(JSON_SCHEMA);
+  return EXIT.OK;
+}
+var HELP16 = `docx schema \u2014 print the AST type definitions
+
+Usage:
+  docx schema [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
+
+Examples:
+  docx schema | jq '.definitions.Run'
+  docx schema --ts > ast.d.ts
+`, JSON_SCHEMA;
+var init_schema = __esm(() => {
+  init_types();
+  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" }
+            }
+          }
+        }
+      }
+    }
+  };
+});
+
+// src/cli/info/locators.ts
+var exports_locators = {};
+__export(exports_locators, {
+  run: () => run17
+});
+import { parseArgs as parseArgs15 } from "util";
+async function run17(args) {
+  let parsed;
+  try {
+    parsed = parseArgs15({
+      args,
+      allowPositionals: true,
+      options: {
+        json: { type: "boolean" },
+        help: { type: "boolean", short: "h" }
+      }
+    });
+  } catch (parseError) {
+    const message = parseError instanceof Error ? parseError.message : String(parseError);
+    return fail("USAGE", message, HELP17);
+  }
+  if (parsed.values.help) {
+    await writeStdout(HELP17);
+    return EXIT.OK;
+  }
+  if (parsed.values.json) {
+    await writeStdout(`${JSON.stringify(JSON_REFERENCE, null, 2)}
+`);
+    return EXIT.OK;
+  }
+  await writeStdout(REFERENCE);
+  return EXIT.OK;
+}
+var HELP17 = `docx locators \u2014 print the locator grammar reference
+
+Usage:
+  docx locators [options]
+
+Options:
+  --json       Print as JSON
+  -h, --help   Show this help
+`, REFERENCE = `LOCATOR GRAMMAR
+
+Block locators:
+  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)
+  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
+
+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
+
+Examples:
+  p3              -> the entire paragraph p3
+  p3:5-20         -> characters 5..20 of p3
+  p3:5-p5:10      -> from char 5 of p3 to char 10 of p5
+  c1              -> comment c1
+  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_locators2 = __esm(() => {
+  init_respond();
+  JSON_REFERENCE = {
+    blockLocators: {
+      paragraph: { syntax: "pN", example: "p3" },
+      table: { syntax: "tN", example: "t0" },
+      sectionBreak: { syntax: "sN", example: "s0" },
+      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)",
+      cellSyntax: "tT:rRcC:pK:S-E"
+    },
+    rangeLocator: {
+      syntax: "pN:S-pM:E",
+      example: "p3:5-p5:10",
+      semantics: "From char S of paragraph N to char E of paragraph M"
+    },
+    entityLocators: {
+      comment: { syntax: "cN", example: "c1" },
+      image: { syntax: "imgN", example: "img0" },
+      cell: { syntax: "tN:rRcC", example: "t0:r1c2" },
+      nestedCell: { syntax: "tN:rRcC:pK", example: "t0:r1c2:p0" }
+    },
+    notes: [
+      "Block ids are positional and shift after structural edits.",
+      "Re-read between non-trivial mutations.",
+      "Mutating commands print before/after locator info in their JSON ack."
+    ]
+  };
+});
+
+// src/cli/info/index.ts
+var exports_info = {};
+__export(exports_info, {
+  run: () => run18
+});
+async function run18(args) {
+  const topic = args[0];
+  if (!topic || topic === "--help" || topic === "-h" || topic === "help") {
+    await writeStdout(HELP18);
+    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, HELP18 = `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: () => run19
+});
+import { parseArgs as parseArgs16 } from "util";
+async function run19(args) {
+  let parsed;
+  try {
+    parsed = parseArgs16({
+      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" },
+        help: { type: "boolean", short: "h" }
+      }
+    });
+  } catch (parseError) {
+    const message = parseError instanceof Error ? parseError.message : String(parseError);
+    return fail("USAGE", message, HELP19);
+  }
+  if (parsed.values.help) {
+    await writeStdout(HELP19);
+    return EXIT.OK;
+  }
+  const path = parsed.positionals[0];
+  if (!path)
+    return fail("USAGE", "Missing FILE argument", HELP19);
+  const after = parsed.values.after;
   const before = parsed.values.before;
   if (!after && !before) {
-    return fail("USAGE", "Missing locator: pass --after or --before", HELP15);
+    return fail("USAGE", "Missing locator: pass --after or --before", HELP19);
   }
   if (after && before) {
-    return fail("USAGE", "Pass either --after or --before, not both", HELP15);
+    return fail("USAGE", "Pass either --after or --before, not both", HELP19);
   }
   const text = parsed.values.text;
   const runsJson = parsed.values.runs;
   if (!text && !runsJson) {
-    return fail("USAGE", "Missing content: pass --text or --runs", HELP15);
+    return fail("USAGE", "Missing content: pass --text or --runs", HELP19);
   }
   if (text && runsJson) {
-    return fail("USAGE", "Pass either --text or --runs, not both", HELP15);
+    return fail("USAGE", "Pass either --text or --runs, not both", HELP19);
   }
   const paragraphOptions = {};
   const styleValue = parsed.values.style;
@@ -16755,30 +17487,13 @@ async function run15(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;
-  }
+  const view = await openOrFail(path);
+  if (typeof view === "number")
+    return view;
   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;
-  }
+  const blockRef = await resolveBlockOrFail(view, targetLocator);
+  if (typeof blockRef === "number")
+    return blockRef;
   let paragraphNode;
   if (text !== undefined) {
     const color = parsed.values.color;
@@ -16832,7 +17547,7 @@ async function run15(args) {
   });
   return EXIT.OK;
 }
-var HELP15 = `docx insert \u2014 insert a paragraph at a locator
+var HELP19 = `docx insert \u2014 insert a paragraph at a locator
 
 Usage:
   docx insert FILE [options]
@@ -16855,137 +17570,30 @@ Run options (only with --text):
   --italic          Italic
 
   --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_emit();
-  init_jsx_dev_runtime();
-});
-
-// src/cli/locators-cmd/index.ts
-var exports_locators_cmd = {};
-__export(exports_locators_cmd, {
-  run: () => run16
-});
-import { parseArgs as parseArgs14 } from "util";
-async function run16(args) {
-  let parsed;
-  try {
-    parsed = parseArgs14({
-      args,
-      allowPositionals: true,
-      options: {
-        json: { type: "boolean" },
-        help: { type: "boolean", short: "h" }
-      }
-    });
-  } catch (parseError) {
-    const message = parseError instanceof Error ? parseError.message : String(parseError);
-    return fail("USAGE", message, HELP16);
-  }
-  if (parsed.values.help) {
-    await writeStdout(HELP16);
-    return EXIT.OK;
-  }
-  if (parsed.values.json) {
-    await Bun.write(Bun.stdout, `${JSON.stringify(JSON_REFERENCE, null, 2)}
-`);
-    return EXIT.OK;
-  }
-  await Bun.write(Bun.stdout, REFERENCE);
-  return EXIT.OK;
-}
-var HELP16 = `docx locators \u2014 print the locator grammar reference
-
-Usage:
-  docx locators [options]
-
-Options:
-  --json       Print as JSON
-  -h, --help   Show this help
-`, REFERENCE = `LOCATOR GRAMMAR
-
-Block locators:
-  pN          Paragraph N (e.g., p3)
-  tN          Table N
-  sN          Section break N
-  cellpN      Paragraph inside a table cell
-
-Span locators (within a single paragraph):
-  pN:S-E      Characters S..E of paragraph N (inclusive start, exclusive end)
-
-Range locators (across blocks):
-  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
+  -h, --help        Show this help
 
 Examples:
-  p3              -> the entire paragraph p3
-  p3:5-20         -> characters 5..20 of p3
-  p3:5-p5:10      -> from char 5 of p3 to char 10 of p5
-  c1              -> comment c1
-  img0            -> image img0
-  t0:r1c2         -> cell at row 1, col 2 of table t0
-  t0:r1c2:p0      -> first paragraph of that cell
-
-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(() => {
+  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();
-  JSON_REFERENCE = {
-    blockLocators: {
-      paragraph: { syntax: "pN", example: "p3" },
-      table: { syntax: "tN", example: "t0" },
-      sectionBreak: { syntax: "sN", example: "s0" },
-      cellParagraph: { syntax: "cellpN", example: "cellp0" }
-    },
-    spanLocator: {
-      syntax: "pN:S-E",
-      example: "p3:5-20",
-      semantics: "Characters S..E within paragraph N (start inclusive, end exclusive)"
-    },
-    rangeLocator: {
-      syntax: "pN:S-pM:E",
-      example: "p3:5-p5:10",
-      semantics: "From char S of paragraph N to char E of paragraph M"
-    },
-    entityLocators: {
-      comment: { syntax: "cN", example: "c1" },
-      image: { syntax: "imgN", example: "img0" },
-      cell: { syntax: "tN:rRcC", example: "t0:r1c2" },
-      nestedCell: { syntax: "tN:rRcC:pK", example: "t0:r1c2:p0" }
-    },
-    notes: [
-      "Block ids are positional and shift after structural edits.",
-      "Re-read between non-trivial mutations.",
-      "Mutating commands print before/after locator info in their JSON ack."
-    ]
-  };
+  init_emit();
+  init_jsx_dev_runtime();
 });
 
 // src/cli/read/index.ts
 var exports_read = {};
 __export(exports_read, {
-  run: () => run17
+  run: () => run20
 });
-import { parseArgs as parseArgs15 } from "util";
-async function run17(args) {
+import { parseArgs as parseArgs17 } from "util";
+async function run20(args) {
   let parsed;
   try {
-    parsed = parseArgs15({
+    parsed = parseArgs17({
       args,
       allowPositionals: true,
       options: {
@@ -16994,32 +17602,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), HELP20);
   }
   if (parsed.values.help) {
-    await writeStdout(HELP17);
+    await writeStdout(HELP20);
     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", HELP20);
+  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 HELP20 = `docx read \u2014 print AST as JSON
 
 Usage:
   docx read FILE [options]
@@ -17037,348 +17636,336 @@ 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) {
+  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(replacementRun(null, replacement));
+    return;
+  }
+  const firstParent = firstSlot.parent;
+  if (overlapping.some((slot) => slot.parent !== firstParent)) {
+    throw new TrackedChangeBoundaryError("Span crosses a tracked-change (<w:ins>/<w:del>) boundary; accept or reject the tracked change first.");
+  }
+  const firstRunProperties = firstSlot.run.findChild("w:rPr");
+  const inheritedProperties = firstRunProperties ? deepCloneNode(firstRunProperties) : null;
+  const containerStart = firstParent === paragraph ? 0 : firstSlot.offsetBefore;
+  rebuildContainer(firstParent, containerStart, span, replacement, inheritedProperties, firstParent === paragraph);
+}
+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) {
+  const newChildren = [];
+  let offset = baseOffset;
+  let placedReplacement = false;
+  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) {
+        if (!placedReplacement) {
+          newChildren.push(replacementRun(runProperties, replacement));
+          placedReplacement = true;
+        }
+        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 (!placedReplacement) {
+        newChildren.push(replacementRun(runProperties, replacement));
+        placedReplacement = true;
+      }
+      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 (!placedReplacement) {
+    newChildren.push(replacementRun(runProperties, replacement));
+  }
+  container.children = newChildren;
+}
+function replacementRun(runProperties, text) {
+  if (text.length === 0) {
+    return /* @__PURE__ */ jsxDEV(w.r, {
+      children: [
+        runProperties,
+        /* @__PURE__ */ jsxDEV(w.t, {
+          "xml:space": "preserve",
+          children: ""
+        }, undefined, false, undefined, this)
+      ]
+    }, undefined, true, undefined, this);
+  }
+  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 TrackedChangeBoundaryError;
+var init_replace_span = __esm(() => {
+  init_jsx();
+  init_parser();
+  init_jsx_dev_runtime();
+  TrackedChangeBoundaryError = class TrackedChangeBoundaryError extends Error {
+    constructor(message) {
+      super(message);
+      this.name = "TrackedChangeBoundaryError";
+    }
+  };
+});
 
-// 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: () => run21
 });
-import { parseArgs as parseArgs16 } from "util";
-async function run18(args) {
+import { parseArgs as parseArgs18 } from "util";
+async function run21(args) {
   let parsed;
   try {
-    parsed = parseArgs16({
+    parsed = parseArgs18({
       args,
       allowPositionals: true,
       options: {
-        json: { type: "boolean" },
-        ts: { type: "boolean" },
+        regex: { type: "boolean" },
+        "ignore-case": { type: "boolean" },
+        all: { type: "boolean" },
+        limit: { 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, HELP18);
-  }
-  if (parsed.values.help) {
-    await writeStdout(HELP18);
+  } catch (parseError) {
+    const message = parseError instanceof Error ? parseError.message : String(parseError);
+    return fail("USAGE", message, HELP21);
+  }
+  if (parsed.values.help) {
+    await writeStdout(HELP21);
+    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", HELP21);
+  if (pattern == null)
+    return fail("USAGE", "Missing PATTERN argument", HELP21);
+  if (replacement == null) {
+    return fail("USAGE", "Missing REPLACEMENT argument", HELP21);
+  }
+  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
+  }));
+  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
+    });
     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 regexFlags = ignoreCase ? "i" : "";
+  try {
+    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);
+    }
+  } catch (error) {
+    if (error instanceof TrackedChangeBoundaryError) {
+      return fail("TRACKED_CHANGE_CONFLICT", error.message, "Use `docx track-changes off` (or accept/reject the change in Word) before replacing.");
+    }
+    throw error;
+  }
+  await saveDocView(view);
+  await respond({
+    ok: true,
+    operation: "replace",
+    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 HELP21 = `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)
+  --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: () => run22
 });
-import { parseArgs as parseArgs17 } from "util";
-async function run19(args) {
+import { parseArgs as parseArgs19 } from "util";
+async function run22(args) {
   let parsed;
   try {
-    parsed = parseArgs17({
+    parsed = parseArgs19({
       args,
       allowPositionals: true,
       options: {
@@ -17388,41 +17975,31 @@ async function run19(args) {
     });
   } catch (parseError) {
     const message = parseError instanceof Error ? parseError.message : String(parseError);
-    return fail("USAGE", message, HELP19);
+    return fail("USAGE", message, HELP22);
   }
   if (parsed.values.help) {
-    await writeStdout(HELP19);
+    await writeStdout(HELP22);
     return EXIT.OK;
   }
   const path = parsed.positionals[0];
   if (!path)
-    return fail("USAGE", "Missing FILE argument", HELP19);
+    return fail("USAGE", "Missing FILE argument", HELP22);
   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>"}`, HELP22);
+  }
+  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");
   if (parsed.values["dry-run"]) {
@@ -17441,13 +18018,15 @@ 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);
   await respond({
     ok: true,
     operation: "track-changes",
@@ -17457,47 +18036,7 @@ async function run19(args) {
   });
   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 HELP22 = `docx track-changes \u2014 toggle the document's tracked-changes mode
 
 Usage:
   docx track-changes FILE on|off [options]
@@ -17516,14 +18055,76 @@ Examples:
 var init_track_changes = __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.2.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,11 +18136,12 @@ Commands:
   edit      FILE  Replace text/properties at a locator
   insert    FILE  Insert a block or run
   delete    FILE  Remove a block or run range
+  find      FILE QUERY  Find text spans, return locators
+  replace   FILE PATTERN REPL  Substitute text spans (sed for docx)
   comments  \u2026     Add, reply, resolve, delete, restore, 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.
 
@@ -17557,18 +18159,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)),
+  replace: () => Promise.resolve().then(() => (init_replace2(), exports_replace2)),
   "track-changes": () => Promise.resolve().then(() => (init_track_changes(), 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;