bun-docx 0.5.0 → 0.6.1

package/dist/index.js

@@ -13780,7 +13780,17 @@ function buildDoc(view, path) {
   };
   const blocks = readBlocks(view, body, state);
   const comments = readComments(view, state.commentAnchors);
-  return { schemaVersion: 1, path, properties, blocks, comments };
+  const footnotes = readNotes(view.footnotesTree, "w:footnotes", "w:footnote", "fn");
+  const endnotes = readNotes(view.endnotesTree, "w:endnotes", "w:endnote", "en");
+  return {
+    schemaVersion: 1,
+    path,
+    properties,
+    blocks,
+    comments,
+    footnotes,
+    endnotes
+  };
 }
 function readBlocks(view, body, state) {
   const blocks = [];
@@ -13868,6 +13878,28 @@ function walkRunContainer(context, container, trackedChange, hyperlink) {
       }
       continue;
     }
+    if (child.tag === "m:oMath") {
+      const text = collectMathText(child);
+      if (text.length > 0) {
+        context.paragraph.runs.push({
+          type: "equation",
+          text,
+          display: false
+        });
+      }
+      continue;
+    }
+    if (child.tag === "m:oMathPara") {
+      const text = collectMathText(child);
+      if (text.length > 0) {
+        context.paragraph.runs.push({
+          type: "equation",
+          text,
+          display: true
+        });
+      }
+      continue;
+    }
     if (child.tag === "w:ins" || child.tag === "w:del") {
       const change = {
         kind: child.tag === "w:ins" ? "ins" : "del",
@@ -13937,9 +13969,9 @@ function readRun(view, node, activeComments, trackedChange, hyperlink, state) {
   const runProperties = node.findChild("w:rPr");
   for (const child of node.children) {
     if (child.tag === "w:drawing") {
-      const image = readImageFromDrawing(view, child, state);
-      if (image)
-        return image;
+      const drawing = readDrawing(view, child, state);
+      if (drawing)
+        return drawing;
     }
     if (child.tag === "w:br") {
       const kind = child.getAttribute("w:type") ?? "line";
@@ -13948,6 +13980,16 @@ function readRun(view, node, activeComments, trackedChange, hyperlink, state) {
     if (child.tag === "w:tab") {
       return { type: "tab" };
     }
+    if (child.tag === "w:footnoteReference") {
+      const id = child.getAttribute("w:id");
+      if (id)
+        return { type: "footnoteRef", kind: "footnote", id: `fn${id}` };
+    }
+    if (child.tag === "w:endnoteReference") {
+      const id = child.getAttribute("w:id");
+      if (id)
+        return { type: "footnoteRef", kind: "endnote", id: `en${id}` };
+    }
   }
   let combinedText = "";
   for (const child of node.children) {
@@ -13968,6 +14010,29 @@ function readRun(view, node, activeComments, trackedChange, hyperlink, state) {
     run.hyperlink = hyperlink;
   return run;
 }
+function readDrawing(view, drawing, state) {
+  const image = readImageFromDrawing(view, drawing, state);
+  if (image)
+    return image;
+  if (drawing.findDescendant("c:chart"))
+    return { type: "chart", kind: "chart" };
+  if (drawing.findDescendant("dgm:relIds"))
+    return { type: "chart", kind: "smartart" };
+  if (drawing.findDescendant("wps:wsp"))
+    return { type: "chart", kind: "shape" };
+  return { type: "chart", kind: "drawing" };
+}
+function collectMathText(node) {
+  let out = "";
+  for (const child of node.children) {
+    if (child.tag === "m:t") {
+      out += child.collectText();
+      continue;
+    }
+    out += collectMathText(child);
+  }
+  return out;
+}
 function applyRunProperties(run, runProperties) {
   const colorNode = runProperties.findChild("w:color");
   if (colorNode) {
@@ -14222,6 +14287,26 @@ function readCommentsExtended(view) {
   }
   return out;
 }
+function readNotes(tree, rootTag, itemTag, idPrefix) {
+  if (!tree)
+    return [];
+  const root = XmlNode2.findRoot(tree, rootTag);
+  if (!root)
+    return [];
+  const out = [];
+  for (const child of root.children) {
+    if (child.tag !== itemTag)
+      continue;
+    if (child.getAttribute("w:type"))
+      continue;
+    const numericId = child.getAttribute("w:id");
+    if (numericId == null)
+      continue;
+    const text = child.collectText().replace(/\s+/g, " ").trim();
+    out.push({ id: `${idPrefix}${numericId}`, text });
+  }
+  return out;
+}
 var RELATIONSHIP_NAMESPACE_IMAGE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image", RELATIONSHIP_NAMESPACE_HYPERLINK = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink";
 var init_read = __esm(() => {
   init_parser();
@@ -14237,11 +14322,15 @@ async function openDocView(path) {
   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 footnotesTree = pkg.hasPart("word/footnotes.xml") ? XmlNode2.parse(await pkg.readText("word/footnotes.xml")) : undefined;
+  const endnotesTree = pkg.hasPart("word/endnotes.xml") ? XmlNode2.parse(await pkg.readText("word/endnotes.xml")) : undefined;
   const view = {
     pkg,
     documentTree,
     commentsTree,
     commentsExtTree,
+    footnotesTree,
+    endnotesTree,
     relationshipsTree,
     contentTypesTree,
     corePropertiesTree,
@@ -14322,6 +14411,49 @@ var init_doc_view = __esm(() => {
   init_read();
 });
 
+// src/core/ast/text.ts
+function paragraphText(paragraph) {
+  let out = "";
+  for (const run of paragraph.runs) {
+    if (run.type === "text")
+      out += run.text;
+  }
+  return out;
+}
+function flattenParagraphs(blocks) {
+  const out = [];
+  for (const block of blocks) {
+    if (block.type === "paragraph") {
+      out.push(block);
+      continue;
+    }
+    if (block.type === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          out.push(...flattenParagraphs(cell.blocks));
+        }
+      }
+    }
+  }
+  return out;
+}
+function findBlockById(blocks, blockId) {
+  for (const block of blocks) {
+    if (block.id === blockId)
+      return block;
+    if (block.type === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          const inner = findBlockById(cell.blocks, blockId);
+          if (inner)
+            return inner;
+        }
+      }
+    }
+  }
+  return null;
+}
+
 // src/core/ast/index.ts
 var init_ast = __esm(() => {
   init_doc_view();
@@ -14513,8 +14645,6 @@ function resolveAuthor(authorFlag) {
     return authorFlag;
   if (Bun.env.DOCX_AUTHOR)
     return Bun.env.DOCX_AUTHOR;
-  if (Bun.env.DOCX_CLI_AUTHOR)
-    return Bun.env.DOCX_CLI_AUTHOR;
   return "docx-cli";
 }
 function resolveDate() {
@@ -14935,15 +15065,15 @@ function ensureCommentsExtPart(view) {
   return root;
 }
 function paragraphTextLength(paragraph) {
+  return sumTextLength(paragraph.children);
+}
+function sumTextLength(children) {
   let total = 0;
-  for (const child of paragraph.children) {
+  for (const child of 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);
-      }
+    else if (child.tag === "w:ins" || child.tag === "w:del" || child.tag === "w:hyperlink") {
+      total += sumTextLength(child.children);
     }
   }
   return total;
@@ -14982,6 +15112,97 @@ function addCommentRangeMarkers(startParagraph, startOffset, endParagraph, endOf
     }
   ]);
 }
+function addCommentMarkersAroundRun(paragraph, target, commentId) {
+  function walk(parent) {
+    const children = parent.children;
+    for (let index = 0;index < children.length; index++) {
+      const child = children[index];
+      if (child === target) {
+        children.splice(index, 1, commentRangeStartMarker(commentId), target, commentRangeEndMarker(commentId), commentReferenceRun(commentId));
+        return true;
+      }
+      if (child && (child.tag === "w:ins" || child.tag === "w:del" || child.tag === "w:hyperlink")) {
+        if (walk(child))
+          return true;
+      }
+    }
+    return false;
+  }
+  return walk(paragraph);
+}
+function findElementOffsetsInParagraph(paragraph, target) {
+  let cursor = 0;
+  let result = null;
+  function walk(children) {
+    for (const child of children) {
+      if (child === target) {
+        const start = cursor;
+        cursor += sumTextLength([child]);
+        result = { start, end: cursor };
+        return true;
+      }
+      if (child.tag === "w:r") {
+        cursor += runTextLength(child);
+        continue;
+      }
+      if (child.tag === "w:ins" || child.tag === "w:del" || child.tag === "w:hyperlink") {
+        if (walk(child.children))
+          return true;
+      }
+    }
+    return false;
+  }
+  walk(paragraph.children);
+  return result;
+}
+function findContainingParagraph(documentTree, target) {
+  function walk(node) {
+    if (node.tag === "w:p" && containsNode(node, target))
+      return node;
+    for (const child of node.children) {
+      const found = walk(child);
+      if (found)
+        return found;
+    }
+    return null;
+  }
+  for (const root of documentTree) {
+    const found = walk(root);
+    if (found)
+      return found;
+  }
+  return null;
+}
+function containsNode(haystack, needle) {
+  if (haystack === needle)
+    return true;
+  for (const child of haystack.children) {
+    if (containsNode(child, needle))
+      return true;
+  }
+  return false;
+}
+function emitAuditComment(view, anchor, options) {
+  const numericId = nextCommentId(view);
+  const paraId = generateParaId();
+  if (anchor.kind === "span") {
+    addCommentMarkersToParagraph(anchor.paragraph, numericId, anchor.span);
+  } else {
+    addCommentMarkersAroundRun(anchor.paragraph, anchor.run, numericId);
+  }
+  const commentsRoot = ensureCommentsPart(view);
+  commentsRoot.children.push(/* @__PURE__ */ jsxDEV(CommentBody, {
+    options: {
+      id: numericId,
+      author: options.author,
+      date: options.date,
+      initials: authorInitials(options.author),
+      paraId,
+      text: options.body
+    }
+  }, undefined, false, undefined, this));
+  return numericId;
+}
 function commentRangeStartMarker(commentId) {
   return /* @__PURE__ */ jsxDEV(w.commentRangeStart, {
     "w-id": commentId
@@ -15017,13 +15238,13 @@ function placeMarkersInParagraph(paragraph, markers) {
   }
   const pending = markers.slice();
   const state = { offset: 0, placedCount: 0 };
-  paragraph.children = walkAndPlace(paragraph.children, pending, true, state);
+  paragraph.children = walkAndPlace(paragraph.children, pending, 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) {
+function walkAndPlace(children, pending, state) {
   const result = [];
   for (const child of children) {
     if (child.tag === "w:r") {
@@ -15065,9 +15286,9 @@ function walkAndPlace(children, pending, isParagraphLevel, state) {
       state.offset = runEnd;
       continue;
     }
-    if (isParagraphLevel && (child.tag === "w:ins" || child.tag === "w:del")) {
+    if (child.tag === "w:ins" || child.tag === "w:del" || child.tag === "w:hyperlink") {
       flushAtCurrentOffset(result, pending, state);
-      const innerChildren = walkAndPlace(child.children, pending, false, state);
+      const innerChildren = walkAndPlace(child.children, pending, state);
       const wrapper = new XmlNode2(child.tag, { ...child.attributes });
       wrapper.children = innerChildren;
       result.push(wrapper);
@@ -16042,6 +16263,7 @@ async function run8(args) {
       allowPositionals: true,
       options: {
         at: { type: "string" },
+        author: { type: "string" },
         output: { type: "string", short: "o" },
         "dry-run": { type: "boolean" },
         help: { type: "boolean", short: "h" }
@@ -16087,7 +16309,7 @@ async function run8(args) {
     if (blockRef.node.tag !== "w:p") {
       return fail("TRACKED_CHANGE_CONFLICT", "Tracked deletion of non-paragraph blocks (e.g., tables) is not supported", "Use `docx track-changes off` first, or delete table contents row-by-row.");
     }
-    applyTrackedDeletion(view, blockRef.node);
+    applyTrackedDeletion(view, blockRef.node, parsed.values.author);
   } else {
     blockRef.parent.splice(targetIndex, 1);
   }
@@ -16100,9 +16322,9 @@ async function run8(args) {
   });
   return EXIT.OK;
 }
-function applyTrackedDeletion(view, paragraph) {
+function applyTrackedDeletion(view, paragraph, authorFlag) {
   const allocator = createRevisionAllocator(view);
-  const baseMeta = { author: resolveAuthor(), date: resolveDate() };
+  const baseMeta = { author: resolveAuthor(authorFlag), date: resolveDate() };
   const mintMeta = () => ({
     ...baseMeta,
     revisionId: allocator.next()
@@ -16139,6 +16361,7 @@ Usage:
 Locator (required):
   --at LOCATOR      Block to remove (e.g., p3, t0)
 
+  --author NAME     Author for tracked changes (default: $DOCX_AUTHOR)
   -o, --output PATH Write to PATH instead of overwriting FILE
   --dry-run         Print what would be removed; do not write the file
   -h, --help        Show this help
@@ -16185,7 +16408,7 @@ function RunElement({ run: run9 }) {
       children: /* @__PURE__ */ jsxDEV(w.tab, {}, undefined, false, undefined, this)
     }, undefined, false, undefined, this);
   }
-  throw new Error(`Cannot emit run of type "${run9.type}" \u2014 image emission lives in the images command.`);
+  return null;
 }
 function TextRunElement({ run: run9 }) {
   return /* @__PURE__ */ jsxDEV(w.r, {
@@ -16291,6 +16514,7 @@ async function run9(args) {
         color: { type: "string" },
         bold: { type: "boolean" },
         italic: { type: "boolean" },
+        author: { type: "string" },
         output: { type: "string", short: "o" },
         "dry-run": { type: "boolean" },
         help: { type: "boolean", short: "h" }
@@ -16378,7 +16602,7 @@ async function run9(args) {
     return EXIT.OK;
   }
   if (isTrackChangesEnabled(view)) {
-    applyTrackedEdit(view, blockRef.node, paragraphNode);
+    applyTrackedEdit(view, blockRef.node, paragraphNode, parsed.values.author);
   } else {
     blockRef.parent.splice(targetIndex, 1, paragraphNode);
   }
@@ -16391,9 +16615,9 @@ async function run9(args) {
   });
   return EXIT.OK;
 }
-function applyTrackedEdit(view, existingParagraph, newParagraph) {
+function applyTrackedEdit(view, existingParagraph, newParagraph, authorFlag) {
   const allocator = createRevisionAllocator(view);
-  const baseMeta = { author: resolveAuthor(), date: resolveDate() };
+  const baseMeta = { author: resolveAuthor(authorFlag), date: resolveDate() };
   const mintMeta = () => ({
     ...baseMeta,
     revisionId: allocator.next()
@@ -16460,6 +16684,7 @@ Run options (only with --text):
   --bold            Bold
   --italic          Italic
 
+  --author NAME     Author for tracked changes (default: $DOCX_AUTHOR)
   -o, --output PATH Write to PATH instead of overwriting FILE
   --dry-run         Print what would change; do not write the file
   -h, --help        Show this help
@@ -16487,15 +16712,15 @@ function literalMatcher(query, ignoreCase) {
     throw new Error("query cannot be empty");
   }
   const needle = ignoreCase ? query.toLowerCase() : query;
-  return (paragraphText) => {
-    const haystack = ignoreCase ? paragraphText.toLowerCase() : paragraphText;
+  return (paragraphText2) => {
+    const haystack = ignoreCase ? paragraphText2.toLowerCase() : paragraphText2;
     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)
+        text: paragraphText2.slice(cursor, cursor + needle.length)
       });
       cursor = haystack.indexOf(needle, cursor + needle.length);
     }
@@ -16505,15 +16730,15 @@ function literalMatcher(query, ignoreCase) {
 function regexMatcher(pattern, ignoreCase) {
   const flags = `g${ignoreCase ? "i" : ""}`;
   const regex = new RegExp(pattern, flags);
-  return (paragraphText) => {
+  return (paragraphText2) => {
     const matches = [];
     regex.lastIndex = 0;
-    let result = regex.exec(paragraphText);
+    let result = regex.exec(paragraphText2);
     while (result !== null) {
       const matched = result[0];
       if (matched.length === 0) {
         regex.lastIndex += 1;
-        result = regex.exec(paragraphText);
+        result = regex.exec(paragraphText2);
         continue;
       }
       matches.push({
@@ -16521,7 +16746,7 @@ function regexMatcher(pattern, ignoreCase) {
         end: result.index + matched.length,
         text: matched
       });
-      result = regex.exec(paragraphText);
+      result = regex.exec(paragraphText2);
     }
     return matches;
   };
@@ -16529,8 +16754,8 @@ function regexMatcher(pattern, ignoreCase) {
 function collectMatches(blocks, matcher, out) {
   for (const block of blocks) {
     if (block.type === "paragraph") {
-      const paragraphText = block.runs.map((run10) => run10.type === "text" ? run10.text : "").join("");
-      for (const span of matcher(paragraphText)) {
+      const paragraphText2 = block.runs.map((run10) => run10.type === "text" ? run10.text : "").join("");
+      for (const span of matcher(paragraphText2)) {
         const match = {
           blockId: block.id,
           start: span.start,
@@ -16801,6 +17026,7 @@ async function run11(args) {
       options: {
         at: { type: "string" },
         url: { type: "string" },
+        author: { type: "string" },
         output: { type: "string", short: "o" },
         "dry-run": { type: "boolean" },
         help: { type: "boolean", short: "h" }
@@ -16869,6 +17095,13 @@ async function run11(args) {
     throw error;
   }
   view.hyperlinksByRelationshipId.set(relationshipId, { url });
+  if (isTrackChangesEnabled(view)) {
+    emitAuditComment(view, { kind: "span", paragraph: paragraphRef.node, span: target.span }, {
+      body: `[docx-cli] hyperlink added \u2192 ${url}`,
+      author: resolveAuthor(parsed.values.author),
+      date: resolveDate()
+    });
+  }
   await saveDocView(view, outputPath);
   await respond({
     ok: true,
@@ -16891,6 +17124,8 @@ Required:
   --url URL         Target URL
 
 Optional:
+  --author NAME     Author for the audit comment when track-changes is on
+                    (default: $DOCX_AUTHOR)
   -o, --output PATH Write to PATH instead of overwriting FILE
   --dry-run         Print what would change; do not write the file
   -h, --help        Show this help
@@ -16898,12 +17133,16 @@ Optional:
 The span must lie inside a single paragraph and must not overlap an existing
 hyperlink or a tracked-change wrapper.
 
+When track-changes is on, an audit comment is anchored to the wrapped span
+since OOXML has no native tracked-change form for hyperlink edits.
+
 Examples:
   docx hyperlinks add doc.docx --at p3:5-20 --url https://example.com
 `;
 var init_add2 = __esm(() => {
   init_core();
   init_parser();
+  init_helpers();
   init_respond();
   init_wrap();
 });
@@ -16922,6 +17161,7 @@ async function run12(args) {
       allowPositionals: true,
       options: {
         at: { type: "string" },
+        author: { type: "string" },
         output: { type: "string", short: "o" },
         "dry-run": { type: "boolean" },
         help: { type: "boolean", short: "h" }
@@ -16966,6 +17206,9 @@ async function run12(args) {
   if (index === -1) {
     return fail("HYPERLINK_NOT_FOUND", `Hyperlink reference is stale (parent does not contain it): ${targetId}`);
   }
+  const trackingOn = isTrackChangesEnabled(view);
+  const paragraph = trackingOn ? findContainingParagraph(view.documentTree, reference.node) : null;
+  const offsets = trackingOn && paragraph ? findElementOffsetsInParagraph(paragraph, reference.node) : null;
   reference.parent.splice(index, 1, ...reference.node.children);
   view.hyperlinkById.delete(targetId);
   if (reference.relationshipId) {
@@ -16975,6 +17218,13 @@ async function run12(args) {
       view.hyperlinksByRelationshipId.delete(reference.relationshipId);
     }
   }
+  if (trackingOn && paragraph && offsets) {
+    emitAuditComment(view, { kind: "span", paragraph, span: offsets }, {
+      body: `[docx-cli] hyperlink removed (was: ${oldUrl ?? "(none)"})`,
+      author: resolveAuthor(parsed.values.author),
+      date: resolveDate()
+    });
+  }
   await saveDocView(view, outputPath);
   await respond({
     ok: true,
@@ -17017,6 +17267,8 @@ Required:
   --at LINK_ID      Existing hyperlink to remove (e.g., link0)
 
 Optional:
+  --author NAME     Author for the audit comment when track-changes is on
+                    (default: $DOCX_AUTHOR)
   -o, --output PATH Write to PATH instead of overwriting FILE
   --dry-run         Print what would change; do not write the file
   -h, --help        Show this help
@@ -17025,12 +17277,16 @@ The display text stays in place; only the <w:hyperlink> wrapper is removed.
 If the underlying relationship is no longer referenced, it is pruned from the
 rels file too.
 
+When track-changes is on, an audit comment is anchored to the surviving text
+since OOXML has no native tracked-change form for hyperlink removal.
+
 Examples:
   docx hyperlinks delete doc.docx --at link0
 `;
 var init_delete3 = __esm(() => {
   init_core();
   init_parser();
+  init_helpers();
   init_respond();
 });
 
@@ -17140,6 +17396,7 @@ async function run14(args) {
       options: {
         at: { type: "string" },
         with: { type: "string" },
+        author: { type: "string" },
         output: { type: "string", short: "o" },
         "dry-run": { type: "boolean" },
         help: { type: "boolean", short: "h" }
@@ -17201,6 +17458,17 @@ async function run14(args) {
     updateRelationshipTarget(relationships, existingId, newUrl);
     view.hyperlinksByRelationshipId.set(existingId, { url: newUrl });
   }
+  if (isTrackChangesEnabled(view)) {
+    const paragraph = findContainingParagraph(view.documentTree, reference.node);
+    const offsets = paragraph ? findElementOffsetsInParagraph(paragraph, reference.node) : null;
+    if (paragraph && offsets) {
+      emitAuditComment(view, { kind: "span", paragraph, span: offsets }, {
+        body: `[docx-cli] hyperlink target changed: ${oldUrl ?? "(none)"} \u2192 ${newUrl}`,
+        author: resolveAuthor(parsed.values.author),
+        date: resolveDate()
+      });
+    }
+  }
   await saveDocView(view, outputPath);
   await respond({
     ok: true,
@@ -17249,6 +17517,8 @@ Required:
   --with URL        New target URL
 
 Optional:
+  --author NAME     Author for the audit comment when track-changes is on
+                    (default: $DOCX_AUTHOR)
   -o, --output PATH Write to PATH instead of overwriting FILE
   --dry-run         Print what would change; do not write the file
   -h, --help        Show this help
@@ -17257,12 +17527,17 @@ Replaces only the targeted hyperlink. If multiple hyperlinks shared the same
 underlying relationship, a new relationship is allocated so the others are
 unaffected.
 
+When track-changes is on, an audit comment is anchored to the affected
+hyperlink span since OOXML has no native tracked-change form for hyperlink
+target edits.
+
 Examples:
   docx hyperlinks replace doc.docx --at link0 --with https://example.com
 `;
 var init_replace = __esm(() => {
   init_core();
   init_parser();
+  init_helpers();
   init_respond();
 });
 
@@ -17522,6 +17797,7 @@ async function run18(args) {
       options: {
         at: { type: "string" },
         with: { type: "string" },
+        author: { type: "string" },
         output: { type: "string", short: "o" },
         "dry-run": { type: "boolean" },
         help: { type: "boolean", short: "h" }
@@ -17577,6 +17853,7 @@ async function run18(args) {
     return EXIT.OK;
   }
   const bytes = new Uint8Array(await sourceFile.arrayBuffer());
+  const originalMimeType = reference.contentType;
   if (newPartName === originalPartName) {
     view.pkg.writeBytes(originalPartName, bytes);
   } else {
@@ -17587,6 +17864,18 @@ async function run18(args) {
     reference.partName = newPartName;
     reference.contentType = newMimeType;
   }
+  if (isTrackChangesEnabled(view)) {
+    const author = resolveAuthor(parsed.values.author);
+    const date = resolveDate();
+    const body = `[docx-cli] image replaced: ${originalPartName} (${originalMimeType}) \u2192 ${newPartName} (${newMimeType}, ${bytes.length} bytes)`;
+    const drawingRuns = findDrawingRunsForRelationship(view.documentTree, reference.relationshipId);
+    for (const drawingRun of drawingRuns) {
+      const paragraph = findContainingParagraph(view.documentTree, drawingRun);
+      if (!paragraph)
+        continue;
+      emitAuditComment(view, { kind: "run", paragraph, run: drawingRun }, { body, author, date });
+    }
+  }
   await saveDocView(view, outputPath);
   await respond({
     ok: true,
@@ -17599,6 +17888,33 @@ async function run18(args) {
   });
   return EXIT.OK;
 }
+function findDrawingRunsForRelationship(documentTree, relationshipId) {
+  const matches = [];
+  function walk(node) {
+    if (node.tag === "w:r" && runReferencesImage(node, relationshipId)) {
+      matches.push(node);
+      return;
+    }
+    for (const child of node.children)
+      walk(child);
+  }
+  for (const root of documentTree)
+    walk(root);
+  return matches;
+}
+function runReferencesImage(run19, relationshipId) {
+  for (const child of run19.children) {
+    if (child.tag !== "w:drawing")
+      continue;
+    const blip = child.findDescendant("a:blip");
+    if (!blip)
+      continue;
+    const embed = blip.getAttribute("r:embed") ?? blip.getAttribute("r:link");
+    if (embed === relationshipId)
+      return true;
+  }
+  return false;
+}
 function renameExtension(partName, newExtension) {
   const dotIndex = partName.lastIndexOf(".");
   const slashIndex = partName.lastIndexOf("/");
@@ -17645,6 +17961,8 @@ Required:
   --with PATH       New image file (any image MIME type)
 
 Optional:
+  --author NAME     Author for the audit comment when track-changes is on
+                    (default: $DOCX_AUTHOR)
   -o, --output PATH Write to PATH instead of overwriting FILE
   --dry-run         Print what would change; do not write the file
   -h, --help        Show this help
@@ -17653,6 +17971,10 @@ If the replacement uses a different format from the original, the part is
 renamed (extension changes), the relationship Target is rewritten, and
 [Content_Types].xml gets a Default entry for the new extension if needed.
 
+When track-changes is on, an audit comment is anchored to each drawing that
+referenced the swapped image since OOXML has no native tracked-change form
+for image replacement.
+
 Examples:
   docx images replace doc.docx --at img2 --with ./new-photo.png
   docx images replace doc.docx --at img0 --with ./diagram.svg
@@ -17660,6 +17982,7 @@ Examples:
 var init_replace2 = __esm(() => {
   init_core();
   init_parser();
+  init_helpers();
   init_respond();
   EXTENSION_BY_MIME = {
     "image/png": "png",
@@ -17721,6 +18044,8 @@ var types_default = `export type Doc = {
 	properties: DocProperties;
 	blocks: Block[];
 	comments: Comment[];
+	footnotes: Footnote[];
+	endnotes: Footnote[];
 };
 
 export type DocProperties = {
@@ -17760,7 +18085,14 @@ export type SectionBreak = {
 	type: "sectionBreak";
 };
 
-export type Run = TextRun | ImageRun | BreakRun | TabRun;
+export type Run =
+	| TextRun
+	| ImageRun
+	| BreakRun
+	| TabRun
+	| EquationRun
+	| FootnoteRefRun
+	| ChartRun;
 
 export type TextRun = {
 	type: "text";
@@ -17804,6 +18136,37 @@ export type TabRun = {
 	type: "tab";
 };
 
+/** A math equation surfaced as concatenated <m:t> plaintext. The structural
+ * OOMath markup (subscripts, fractions, etc.) is collapsed to literal characters,
+ * so the rendering is degraded. \`display\` distinguishes inline equations
+ * (<m:oMath>) from block-level display equations (<m:oMathPara>). */
+export type EquationRun = {
+	type: "equation";
+	text: string;
+	display: boolean;
+};
+
+/** Reference to a footnote or endnote whose body lives in Doc.footnotes or
+ * Doc.endnotes. The id matches the footnote/endnote id (\`fn1\`, \`en1\`). */
+export type FootnoteRefRun = {
+	type: "footnoteRef";
+	kind: "footnote" | "endnote";
+	id: string;
+};
+
+/** Placeholder for a non-picture drawing (chart, shape, SmartArt, etc.). The
+ * full content is preserved in the underlying XML; the run is a marker so
+ * callers can know "something visual lives here." */
+export type ChartRun = {
+	type: "chart";
+	kind: "chart" | "shape" | "smartart" | "drawing";
+};
+
+export type Footnote = {
+	id: string;
+	text: string;
+};
+
 export type TrackedChange = {
 	kind: "ins" | "del";
 	author: string;
@@ -17864,10 +18227,10 @@ async function run20(args) {
   await respond(JSON_SCHEMA);
   return EXIT.OK;
 }
-var HELP20 = `docx schema \u2014 print the AST type definitions
+var HELP20 = `docx info schema \u2014 print the AST type definitions
 
 Usage:
-  docx schema [options]
+  docx info schema [options]
 
 Options:
   --json       Print as a JSON Schema document (default)
@@ -17875,8 +18238,8 @@ Options:
   -h, --help   Show this help
 
 Examples:
-  docx schema | jq '.definitions.Run'
-  docx schema --ts > ast.d.ts
+  docx info schema | jq '.$defs.Run'
+  docx info schema --ts > ast.d.ts
 `, JSON_SCHEMA;
 var init_schema = __esm(() => {
   init_types();
@@ -17886,7 +18249,15 @@ var init_schema = __esm(() => {
     $id: "https://github.com/kklimuk/docx-cli/schema",
     title: "docx-cli AST",
     type: "object",
-    required: ["schemaVersion", "path", "properties", "blocks", "comments"],
+    required: [
+      "schemaVersion",
+      "path",
+      "properties",
+      "blocks",
+      "comments",
+      "footnotes",
+      "endnotes"
+    ],
     properties: {
       schemaVersion: { const: 1 },
       path: { type: "string" },
@@ -17900,7 +18271,9 @@ var init_schema = __esm(() => {
         }
       },
       blocks: { type: "array", items: { $ref: "#/$defs/Block" } },
-      comments: { type: "array", items: { $ref: "#/$defs/Comment" } }
+      comments: { type: "array", items: { $ref: "#/$defs/Comment" } },
+      footnotes: { type: "array", items: { $ref: "#/$defs/Footnote" } },
+      endnotes: { type: "array", items: { $ref: "#/$defs/Footnote" } }
     },
     $defs: {
       Block: {
@@ -17934,7 +18307,10 @@ var init_schema = __esm(() => {
           { $ref: "#/$defs/TextRun" },
           { $ref: "#/$defs/ImageRun" },
           { $ref: "#/$defs/BreakRun" },
-          { $ref: "#/$defs/TabRun" }
+          { $ref: "#/$defs/TabRun" },
+          { $ref: "#/$defs/EquationRun" },
+          { $ref: "#/$defs/FootnoteRefRun" },
+          { $ref: "#/$defs/ChartRun" }
         ]
       },
       TextRun: {
@@ -18001,6 +18377,40 @@ var init_schema = __esm(() => {
         required: ["type"],
         properties: { type: { const: "tab" } }
       },
+      EquationRun: {
+        type: "object",
+        required: ["type", "text", "display"],
+        properties: {
+          type: { const: "equation" },
+          text: { type: "string" },
+          display: { type: "boolean" }
+        }
+      },
+      FootnoteRefRun: {
+        type: "object",
+        required: ["type", "kind", "id"],
+        properties: {
+          type: { const: "footnoteRef" },
+          kind: { enum: ["footnote", "endnote"] },
+          id: { type: "string" }
+        }
+      },
+      ChartRun: {
+        type: "object",
+        required: ["type", "kind"],
+        properties: {
+          type: { const: "chart" },
+          kind: { enum: ["chart", "shape", "smartart", "drawing"] }
+        }
+      },
+      Footnote: {
+        type: "object",
+        required: ["id", "text"],
+        properties: {
+          id: { type: "string" },
+          text: { type: "string" }
+        }
+      },
       Table: {
         type: "object",
         required: ["id", "type", "rows"],
@@ -18097,14 +18507,18 @@ async function run21(args) {
   await writeStdout(REFERENCE);
   return EXIT.OK;
 }
-var HELP21 = `docx locators \u2014 print the locator grammar reference
+var HELP21 = `docx info locators \u2014 print the locator grammar reference
 
 Usage:
-  docx locators [options]
+  docx info locators [options]
 
 Options:
   --json       Print as JSON
   -h, --help   Show this help
+
+Examples:
+  docx info locators
+  docx info locators --json | jq '.entityLocators'
 `, REFERENCE = `LOCATOR GRAMMAR
 
 Block locators:
@@ -18237,6 +18651,7 @@ async function run23(args) {
         bold: { type: "boolean" },
         italic: { type: "boolean" },
         url: { type: "string" },
+        author: { type: "string" },
         output: { type: "string", short: "o" },
         "dry-run": { type: "boolean" },
         help: { type: "boolean", short: "h" }
@@ -18325,7 +18740,7 @@ async function run23(args) {
   }
   const insertIndex = after !== undefined ? targetIndex + 1 : targetIndex;
   if (isTrackChangesEnabled(view)) {
-    applyTrackedInsertion(paragraphNode, view);
+    applyTrackedInsertion(paragraphNode, view, parsed.values.author);
   }
   const outputPath = parsed.values.output;
   if (parsed.values["dry-run"]) {
@@ -18374,9 +18789,9 @@ function wrapFirstRunInHyperlink(view, paragraph, url) {
   }
   paragraph.children = newChildren;
 }
-function applyTrackedInsertion(paragraph, view) {
+function applyTrackedInsertion(paragraph, view, authorFlag) {
   const allocator = createRevisionAllocator(view);
-  const baseMeta = { author: resolveAuthor(), date: resolveDate() };
+  const baseMeta = { author: resolveAuthor(authorFlag), date: resolveDate() };
   const mintMeta = () => ({
     ...baseMeta,
     revisionId: allocator.next()
@@ -18427,6 +18842,7 @@ Run options (only with --text):
   --italic          Italic
   --url URL         Wrap the inserted text in a hyperlink to URL
 
+  --author NAME     Author for tracked changes (default: $DOCX_AUTHOR)
   -o, --output PATH Write to PATH instead of overwriting FILE
   --dry-run         Print what would be inserted; do not write the file
   -h, --help        Show this help
@@ -18500,14 +18916,9 @@ function* headingParagraphs(blocks, stylePrefix) {
     yield block;
   }
 }
-function paragraphText(paragraph) {
-  let out = "";
-  for (const run24 of paragraph.runs) {
-    if (run24.type === "text")
-      out += run24.text;
-  }
-  return out;
-}
+var init_build = __esm(() => {
+  init_core();
+});
 
 // src/cli/outline/index.ts
 var exports_outline = {};
@@ -18579,6 +18990,425 @@ Examples:
 `;
 var init_outline = __esm(() => {
   init_respond();
+  init_build();
+});
+
+// src/cli/read/markdown.ts
+function renderMarkdown(doc, options = {}) {
+  const blocks = sliceBlocks(doc.blocks, options.from, options.to);
+  const commentIndex = options.showComments ? buildCommentIndex(blocks, options) : emptyCommentIndex();
+  const ctx = {
+    options,
+    commentIndex,
+    referencedFootnoteIds: new Set,
+    referencedEndnoteIds: new Set
+  };
+  const parts = [];
+  for (const block of blocks) {
+    const rendered = renderBlock(block, ctx);
+    if (rendered !== null)
+      parts.push(rendered);
+  }
+  const definitions = [];
+  if (options.showComments) {
+    const commentFootnotes = renderCommentFootnotes(commentIndex, doc.comments);
+    if (commentFootnotes.length > 0)
+      definitions.push(commentFootnotes);
+  }
+  const footnoteDefs = renderNoteDefinitions(doc.footnotes, ctx.referencedFootnoteIds);
+  if (footnoteDefs.length > 0)
+    definitions.push(footnoteDefs);
+  const endnoteDefs = renderNoteDefinitions(doc.endnotes, ctx.referencedEndnoteIds);
+  if (endnoteDefs.length > 0)
+    definitions.push(endnoteDefs);
+  if (definitions.length > 0)
+    parts.push(definitions.join(`
+`));
+  if (parts.length === 0)
+    return "";
+  return `${parts.join(`
+
+`)}
+`;
+}
+function emptyCommentIndex() {
+  return {
+    endingsByRun: new Map,
+    spanText: new Map,
+    orderedIds: []
+  };
+}
+function buildCommentIndex(blocks, options) {
+  const showChanges = options.showChanges ?? false;
+  const lastSlot = new Map;
+  const spanText = new Map;
+  const orderedIds = [];
+  for (const paragraph of flattenParagraphs(blocks)) {
+    paragraph.runs.forEach((run25, index) => {
+      if (run25.type !== "text")
+        return;
+      if (!showChanges && run25.trackedChange?.kind === "del")
+        return;
+      for (const commentId of run25.comments ?? []) {
+        if (!spanText.has(commentId))
+          orderedIds.push(commentId);
+        spanText.set(commentId, (spanText.get(commentId) ?? "") + run25.text);
+        lastSlot.set(commentId, slotKey(paragraph.id, index));
+      }
+    });
+  }
+  const endingsByRun = new Map;
+  for (const commentId of orderedIds) {
+    const slot = lastSlot.get(commentId);
+    if (!slot)
+      continue;
+    const list = endingsByRun.get(slot) ?? [];
+    list.push(commentId);
+    endingsByRun.set(slot, list);
+  }
+  return { endingsByRun, spanText, orderedIds };
+}
+function slotKey(paragraphId, runIndex) {
+  return `${paragraphId}#${runIndex}`;
+}
+function renderBlock(block, ctx) {
+  if (block.type === "paragraph")
+    return renderParagraph(block, ctx);
+  if (block.type === "table")
+    return renderTable(block, ctx);
+  if (block.type === "sectionBreak")
+    return `--- <!-- ${block.id} -->`;
+  return null;
+}
+function renderParagraph(paragraph, ctx) {
+  const body = renderRuns(paragraph.id, paragraph.runs, ctx);
+  if (body.length === 0)
+    return null;
+  const prefix = paragraphPrefix(paragraph);
+  return `${prefix}${body} <!-- ${paragraph.id} -->`;
+}
+function paragraphPrefix(paragraph) {
+  const headingLevel2 = headingLevelFor(paragraph.style);
+  if (headingLevel2 !== null)
+    return `${"#".repeat(headingLevel2)} `;
+  if (paragraph.list) {
+    const indent = "  ".repeat(paragraph.list.level);
+    return `${indent}- `;
+  }
+  return "";
+}
+function headingLevelFor(style) {
+  if (!style)
+    return null;
+  if (!style.startsWith("Heading"))
+    return null;
+  const remainder = style.slice("Heading".length).trim();
+  if (remainder === "")
+    return 1;
+  const parsed = Number(remainder);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > 6)
+    return null;
+  return parsed;
+}
+function renderRuns(paragraphId, runs, ctx) {
+  const showChanges = ctx.options.showChanges ?? false;
+  const visibleEntries = [];
+  runs.forEach((run25, index) => {
+    if (!showChanges && run25.type === "text" && run25.trackedChange?.kind === "del") {
+      return;
+    }
+    visibleEntries.push({ run: run25, originalIndex: index });
+  });
+  let out = "";
+  let cursor = 0;
+  while (cursor < visibleEntries.length) {
+    const entry = visibleEntries[cursor];
+    if (!entry) {
+      cursor++;
+      continue;
+    }
+    const { run: run25 } = entry;
+    if (run25.type === "text") {
+      let lookahead = cursor + 1;
+      while (lookahead < visibleEntries.length) {
+        const next = visibleEntries[lookahead];
+        if (!next || next.run.type !== "text")
+          break;
+        if (!sameDecoration(run25, next.run))
+          break;
+        lookahead++;
+      }
+      const segment = visibleEntries.slice(cursor, lookahead);
+      out += renderTextSegment(segment.map((entry2) => entry2.run), showChanges);
+      out += commentEndingsFor(paragraphId, segment, ctx.commentIndex);
+      cursor = lookahead;
+      continue;
+    }
+    if (run25.type === "image") {
+      const alt = sanitizeAltText(run25.alt ?? run25.id);
+      out += `![${alt}](${run25.id})`;
+    } else if (run25.type === "break") {
+      if (run25.kind === "line")
+        out += "<br>";
+    } else if (run25.type === "tab") {
+      out += "\t";
+    } else if (run25.type === "equation") {
+      const escaped = run25.text.replace(/`/g, "\\`");
+      out += `\`equation: ${escaped}\``;
+    } else if (run25.type === "footnoteRef") {
+      if (run25.kind === "footnote")
+        ctx.referencedFootnoteIds.add(run25.id);
+      else
+        ctx.referencedEndnoteIds.add(run25.id);
+      out += `[^${run25.id}]`;
+    } else if (run25.type === "chart") {
+      out += `\`[${run25.kind}]\``;
+    }
+    cursor++;
+  }
+  return out;
+}
+function commentEndingsFor(paragraphId, segment, commentIndex) {
+  if (commentIndex.endingsByRun.size === 0)
+    return "";
+  let out = "";
+  for (const entry of segment) {
+    const ids = commentIndex.endingsByRun.get(slotKey(paragraphId, entry.originalIndex));
+    if (!ids)
+      continue;
+    for (const commentId of ids)
+      out += `[^${commentId}]`;
+  }
+  return out;
+}
+function sameDecoration(a2, b) {
+  return (a2.bold ?? false) === (b.bold ?? false) && (a2.italic ?? false) === (b.italic ?? false) && (a2.strike ?? false) === (b.strike ?? false) && (a2.underline ?? "") === (b.underline ?? "") && (a2.color ?? "") === (b.color ?? "") && (a2.highlight ?? "") === (b.highlight ?? "") && a2.hyperlink?.id === b.hyperlink?.id && a2.trackedChange?.kind === b.trackedChange?.kind && sameCommentSet(a2.comments, b.comments);
+}
+function sameCommentSet(left, right) {
+  const a2 = left ?? [];
+  const b = right ?? [];
+  if (a2.length !== b.length)
+    return false;
+  for (let i = 0;i < a2.length; i++) {
+    if (a2[i] !== b[i])
+      return false;
+  }
+  return true;
+}
+function renderTextSegment(runs, showChanges) {
+  const text = runs.map((run25) => run25.text).join("");
+  if (text.length === 0)
+    return "";
+  const first = runs[0];
+  if (!first)
+    return "";
+  let out = text;
+  if (first.bold)
+    out = `**${out}**`;
+  if (first.italic)
+    out = `*${out}*`;
+  if (first.strike)
+    out = `~~${out}~~`;
+  if (first.underline)
+    out = `<u>${out}</u>`;
+  const color = colorAttrFor(first.color);
+  if (color)
+    out = `<span style="color:${color}">${out}</span>`;
+  const highlight = highlightCssFor(first.highlight);
+  if (highlight)
+    out = `<span style="background-color:${highlight}">${out}</span>`;
+  if (first.hyperlink) {
+    const target = first.hyperlink.url ?? `#${first.hyperlink.anchor ?? ""}`;
+    out = `[${out}](${target})`;
+  }
+  if (showChanges && first.trackedChange) {
+    out = `<${first.trackedChange.kind}>${out}</${first.trackedChange.kind}>`;
+  }
+  return out;
+}
+function colorAttrFor(value) {
+  if (!value)
+    return null;
+  const lowered = value.toLowerCase();
+  if (lowered === "auto")
+    return null;
+  if (/^[0-9a-f]{6}$/.test(lowered))
+    return `#${lowered}`;
+  return value;
+}
+function highlightCssFor(value) {
+  if (!value)
+    return null;
+  if (value === "none")
+    return null;
+  return value.replace(/[A-Z]/g, (letter) => letter.toLowerCase());
+}
+function renderTable(table, ctx) {
+  if (table.rows.length === 0)
+    return null;
+  const colCount = Math.max(...table.rows.map((row) => row.cells.length));
+  if (colCount === 0)
+    return null;
+  const renderedRows = table.rows.map((row) => {
+    const cells = [];
+    for (let columnIndex = 0;columnIndex < colCount; columnIndex++) {
+      const cell = row.cells[columnIndex];
+      cells.push(cell ? renderCell(cell, ctx) : "");
+    }
+    return cells;
+  });
+  const lines = [];
+  const headerRow = renderedRows[0];
+  if (!headerRow)
+    return null;
+  lines.push(rowToLine(headerRow));
+  lines.push(`| ${Array(colCount).fill("---").join(" | ")} |`);
+  for (let rowIndex = 1;rowIndex < renderedRows.length; rowIndex++) {
+    const row = renderedRows[rowIndex];
+    if (row)
+      lines.push(rowToLine(row));
+  }
+  return lines.join(`
+`);
+}
+function rowToLine(cells) {
+  return `| ${cells.join(" | ")} |`;
+}
+function renderCell(cell, ctx) {
+  const parts = [];
+  for (const block of cell.blocks) {
+    if (block.type === "paragraph") {
+      const body = renderRuns(block.id, block.runs, ctx);
+      if (body.length === 0)
+        continue;
+      parts.push(`${body} <!-- ${block.id} -->`);
+      continue;
+    }
+    if (block.type === "table") {
+      parts.push(renderNestedTable(block, ctx));
+    }
+  }
+  return escapeCell(parts.join("<br>"));
+}
+function renderNestedTable(table, ctx) {
+  const rows = table.rows.map((row) => row.cells.map((cell) => renderCell(cell, ctx)).join(" / "));
+  return rows.join(" // ");
+}
+function escapeCell(text) {
+  return text.replace(/\|/g, "\\|");
+}
+function sanitizeAltText(text) {
+  return text.replace(/[\r\n]+/g, " ").replace(/\]/g, "\\]");
+}
+function renderCommentFootnotes(commentIndex, comments) {
+  if (commentIndex.orderedIds.length === 0)
+    return "";
+  const byId = new Map(comments.map((comment) => [comment.id, comment]));
+  const sorted = [...commentIndex.orderedIds].sort(commentIdCompare);
+  const lines = [];
+  for (const commentId of sorted) {
+    const comment = byId.get(commentId);
+    if (!comment)
+      continue;
+    const span = commentIndex.spanText.get(commentId) ?? "";
+    lines.push(formatFootnote(comment, span));
+  }
+  return lines.join(`
+`);
+}
+function renderNoteDefinitions(notes, referenced) {
+  if (referenced.size === 0)
+    return "";
+  const byId = new Map(notes.map((note) => [note.id, note]));
+  const sorted = [...referenced].sort(noteIdCompare);
+  const lines = [];
+  for (const id of sorted) {
+    const note = byId.get(id);
+    const body = (note?.text ?? "").replace(/\s+/g, " ").trim();
+    lines.push(`[^${id}]: ${body}`);
+  }
+  return lines.join(`
+`);
+}
+function noteIdCompare(left, right) {
+  return numericIdCompare(left, right, /(\d+)$/);
+}
+function commentIdCompare(left, right) {
+  return numericIdCompare(left, right, /^c(\d+)$/);
+}
+function numericIdCompare(left, right, pattern) {
+  const leftMatch = left.match(pattern);
+  const rightMatch = right.match(pattern);
+  if (leftMatch?.[1] && rightMatch?.[1]) {
+    return Number(leftMatch[1]) - Number(rightMatch[1]);
+  }
+  return left.localeCompare(right);
+}
+function formatFootnote(comment, spanText) {
+  const quoted = quoteSpan(spanText);
+  const reply = comment.parentId ? ` \u21B3 ${comment.parentId}` : "";
+  const resolved = comment.resolved ? "\u2713 " : "";
+  const body = comment.text.replace(/\s+/g, " ").trim();
+  return `[^${comment.id}]: ${quoted} \u2014 ${resolved}${comment.author} (${comment.date})${reply}: ${body}`;
+}
+function quoteSpan(text) {
+  const collapsed = text.replace(/\s+/g, " ").trim();
+  const escaped = collapsed.replace(/"/g, "\\\"");
+  return `"${escaped}"`;
+}
+function sliceBlocks(blocks, from, to) {
+  if (!from && !to)
+    return blocks;
+  const fromId = from ? blockIdForLocator(from, "from") : null;
+  const toId = to ? blockIdForLocator(to, "to") : null;
+  const fromIndex = fromId ? blocks.findIndex((b) => b.id === fromId) : 0;
+  if (from && fromId && fromIndex === -1) {
+    throw new MarkdownLocatorError(from, `--from ${from} not found at document top level`);
+  }
+  const toIndex = toId ? blocks.findIndex((b) => b.id === toId) : blocks.length - 1;
+  if (to && toId && toIndex === -1) {
+    throw new MarkdownLocatorError(to, `--to ${to} not found at document top level`);
+  }
+  if (toIndex < fromIndex)
+    return [];
+  return blocks.slice(fromIndex, toIndex + 1);
+}
+function blockIdForLocator(input, position) {
+  let parsed;
+  try {
+    parsed = parseLocator(input);
+  } catch (err) {
+    if (err instanceof LocatorParseError) {
+      throw new MarkdownLocatorError(input, err.message);
+    }
+    throw err;
+  }
+  switch (parsed.kind) {
+    case "block":
+      return parsed.blockId;
+    case "blockSpan":
+      return parsed.blockId;
+    case "range":
+      return position === "from" ? parsed.start.blockId : parsed.end.blockId;
+    case "cell":
+      return parsed.tableId;
+    case "comment":
+    case "image":
+    case "hyperlink":
+      throw new MarkdownLocatorError(input, `--${position} does not accept a ${parsed.kind} locator \u2014 use a paragraph or table locator`);
+  }
+}
+var MarkdownLocatorError;
+var init_markdown = __esm(() => {
+  init_core();
+  MarkdownLocatorError = class MarkdownLocatorError extends Error {
+    input;
+    constructor(input, message) {
+      super(message);
+      this.input = input;
+      this.name = "MarkdownLocatorError";
+    }
+  };
 });
 
 // src/cli/read/index.ts
@@ -18594,7 +19424,11 @@ async function run25(args) {
       args,
       allowPositionals: true,
       options: {
-        text: { type: "boolean" },
+        markdown: { type: "boolean" },
+        from: { type: "string" },
+        to: { type: "string" },
+        changes: { type: "boolean" },
+        comments: { type: "boolean" },
         help: { type: "boolean", short: "h" }
       }
     });
@@ -18608,29 +19442,72 @@ async function run25(args) {
   const path = parsed.positionals[0];
   if (!path)
     return fail("USAGE", "Missing FILE argument", HELP25);
+  const markdown = Boolean(parsed.values.markdown);
+  const from = parsed.values.from;
+  const to = parsed.values.to;
+  const showChanges = Boolean(parsed.values.changes);
+  const showComments = Boolean(parsed.values.comments);
+  if (!markdown && (from || to || showChanges || showComments)) {
+    return fail("USAGE", "--from, --to, --changes, and --comments require --markdown", HELP25);
+  }
   const view = await openOrFail(path);
   if (typeof view === "number")
     return view;
+  if (markdown) {
+    try {
+      const rendered = renderMarkdown(view.doc, {
+        from,
+        to,
+        showChanges,
+        showComments
+      });
+      await writeStdout(rendered);
+      return EXIT.OK;
+    } catch (err) {
+      if (err instanceof MarkdownLocatorError) {
+        return fail("INVALID_LOCATOR", err.message);
+      }
+      throw err;
+    }
+  }
   await enrichImageHashes(view);
   await respond(view.doc);
   return EXIT.OK;
 }
-var HELP25 = `docx read \u2014 print AST as JSON
+var HELP25 = `docx read \u2014 print AST as JSON, or render document body as Markdown
 
 Usage:
   docx read FILE [options]
 
 Options:
-  --text       Render as human-readable text instead of JSON (NOT YET IMPLEMENTED)
-  -h, --help   Show this help
+  --markdown        Render the body as GitHub-flavored Markdown
+                    (instead of JSON). Locators are emitted as
+                    <!-- pN --> HTML comments after each paragraph and
+                    inside cell content (invisible in rendered view,
+                    but parseable from raw markdown).
+  --from LOC        Start markdown rendering at top-level block LOC (inclusive)
+  --to LOC          End markdown rendering at top-level block LOC (inclusive)
+                    Accepts pN, tN, tN:rRcC[:pK[:S-E]], pN:S-E, pN:S-pM:E.
+                    Cell/span/range locators collapse to their enclosing
+                    top-level block (the table or paragraph).
+  --changes         With --markdown, render tracked insertions/deletions as
+                    <ins>/<del> instead of producing the accepted view.
+  --comments        With --markdown, append [^cN] after each commented span
+                    and emit a footnote definition for each comment at the
+                    end of the output (author, date, body).
+  -h, --help        Show this help
 
 Examples:
   docx read input.docx
+  docx read input.docx --markdown
+  docx read input.docx --markdown --from p3 --to p20
+  docx read input.docx --markdown --changes --comments
   docx read input.docx | jq '.blocks[] | select(.type == "paragraph")'
 `;
 var init_read2 = __esm(() => {
   init_core();
   init_respond();
+  init_markdown();
 });
 
 // src/cli/replace/replace-span.tsx
@@ -19014,6 +19891,7 @@ async function run26(args) {
         "ignore-case": { type: "boolean" },
         all: { type: "boolean" },
         limit: { type: "string" },
+        author: { type: "string" },
         output: { type: "string", short: "o" },
         "dry-run": { type: "boolean" },
         help: { type: "boolean", short: "h" }
@@ -19112,8 +19990,9 @@ async function run26(args) {
     }
     return rightMatch.start - leftMatch.start;
   });
+  const authorFlag = parsed.values.author;
   const tracked = isTrackChangesEnabled(view) ? {
-    meta: { author: resolveAuthor(), date: resolveDate() },
+    meta: { author: resolveAuthor(authorFlag), date: resolveDate() },
     allocator: createRevisionAllocator(view)
   } : undefined;
   const regexFlags = ignoreCase ? "i" : "";
@@ -19147,6 +20026,7 @@ Options:
   --ignore-case     case-insensitive match
   --all             replace every match (default: just the first)
   --limit N         replace at most N matches (in document order)
+  --author NAME     author for tracked changes (default: $DOCX_AUTHOR)
   -o, --output PATH write to PATH instead of overwriting FILE
   --dry-run         report what would change without writing the file
   -h, --help        show this help
@@ -19293,19 +20173,11 @@ function countWords(text) {
   const matches = text.match(/\S+/g);
   return matches?.length ?? 0;
 }
-function paragraphText2(paragraph) {
-  let out = "";
-  for (const run28 of paragraph.runs) {
-    if (run28.type === "text")
-      out += run28.text;
-  }
-  return out;
-}
 function countWordsInBlocks(blocks) {
   let total = 0;
   for (const block of blocks) {
     if (block.type === "paragraph") {
-      total += countWords(paragraphText2(block));
+      total += countWords(paragraphText(block));
     } else if (block.type === "table") {
       for (const row of block.rows) {
         for (const cell of row.cells) {
@@ -19316,24 +20188,8 @@ function countWordsInBlocks(blocks) {
   }
   return total;
 }
-function findBlockById(blocks, blockId) {
-  for (const block of blocks) {
-    if (block.id === blockId)
-      return block;
-    if (block.type === "table") {
-      for (const row of block.rows) {
-        for (const cell of row.cells) {
-          const inner = findBlockById(cell.blocks, blockId);
-          if (inner)
-            return inner;
-        }
-      }
-    }
-  }
-  return null;
-}
 function countWordsInParagraphSpan(paragraph, start, end) {
-  const text = paragraphText2(paragraph);
+  const text = paragraphText(paragraph);
   const clampedEnd = Math.min(Math.max(end, 0), text.length);
   const clampedStart = Math.min(Math.max(start, 0), clampedEnd);
   return countWords(text.slice(clampedStart, clampedEnd));
@@ -19354,35 +20210,21 @@ function countWordsInRange(paragraphsInOrder, startBlockId, startOffset, endBloc
   let total = 0;
   const first = paragraphsInOrder[startIndex];
   if (first) {
-    total += countWordsInParagraphSpan(first, startOffset, paragraphText2(first).length);
+    total += countWordsInParagraphSpan(first, startOffset, paragraphText(first).length);
   }
   for (let index = startIndex + 1;index < endIndex; index++) {
     const middle = paragraphsInOrder[index];
     if (middle)
-      total += countWords(paragraphText2(middle));
+      total += countWords(paragraphText(middle));
   }
   const last = paragraphsInOrder[endIndex];
   if (last)
     total += countWordsInParagraphSpan(last, 0, endOffset);
   return total;
 }
-function flattenParagraphs(blocks) {
-  const out = [];
-  for (const block of blocks) {
-    if (block.type === "paragraph") {
-      out.push(block);
-      continue;
-    }
-    if (block.type === "table") {
-      for (const row of block.rows) {
-        for (const cell of row.cells) {
-          out.push(...flattenParagraphs(cell.blocks));
-        }
-      }
-    }
-  }
-  return out;
-}
+var init_count = __esm(() => {
+  init_core();
+});
 
 // src/cli/wc/index.ts
 var exports_wc = {};
@@ -19443,7 +20285,7 @@ async function run28(args) {
     if (!block) {
       return fail("BLOCK_NOT_FOUND", `Block not found: ${locator.blockId}`);
     }
-    const words = block.type === "paragraph" ? countWords(paragraphText2(block)) : block.type === "table" ? countWordsInBlocks([block]) : 0;
+    const words = block.type === "paragraph" ? countWords(paragraphText(block)) : block.type === "table" ? countWordsInBlocks([block]) : 0;
     await respond({
       ok: true,
       operation: "wc",
@@ -19515,7 +20357,7 @@ async function run28(args) {
     if (!block || block.type !== "paragraph") {
       return fail("BLOCK_NOT_FOUND", `Paragraph not found: ${composedId}`);
     }
-    const words = locator.inner.kind === "blockSpan" ? countWordsInParagraphSpan(block, locator.inner.start, locator.inner.end) : countWords(paragraphText2(block));
+    const words = locator.inner.kind === "blockSpan" ? countWordsInParagraphSpan(block, locator.inner.start, locator.inner.end) : countWords(paragraphText(block));
     await respond({
       ok: true,
       operation: "wc",
@@ -19573,11 +20415,12 @@ Examples:
 var init_wc = __esm(() => {
   init_core();
   init_respond();
+  init_count();
 });
 // package.json
 var package_default = {
   name: "bun-docx",
-  version: "0.5.0",
+  version: "0.6.1",
   description: "CLI for AI agents (Claude, Codex) to read, edit, and comment on .docx files with full format fidelity.",
   keywords: [
     "docx",
@@ -19656,7 +20499,7 @@ Commands:
   outline   FILE  List headings as a hierarchical tree
   comments  \u2026     Add, reply, resolve, delete, list comments
   images    \u2026     Extract, replace, list images
-  hyperlinks \u2026    List, replace hyperlinks
+  hyperlinks \u2026    Add, list, replace, delete hyperlinks
   track-changes FILE on|off  Toggle tracked-changes mode
   info      \u2026     Reference material (schema, locators)