bun-docx 0.5.0 → 0.6.0

package/README.md

@@ -31,7 +31,7 @@ bunx bun-docx read doc.docx
 
 ```sh
 docx create FILE [--title T] [--author A] [--text "..."]
-docx read FILE
+docx read FILE [--markdown [--from pN] [--to pN] [--changes] [--comments]]
 docx insert FILE --after p3 --text "..." [--style HeadingN] [--color HEX] [--bold] [--italic] [--url URL]
 docx insert FILE --after p3 --runs '[{"type":"text","text":"X","bold":true}]'
 docx edit   FILE --at p3 --text "..." | --runs '[...]'
@@ -64,6 +64,37 @@ Every command has `--help`. Mutating commands accept `--dry-run` and `-o/--outpu
 
 When `<w:trackChanges/>` is set in the doc (toggle via `docx track-changes FILE on`), `insert`/`edit`/`delete`/`replace` automatically emit `<w:ins>`/`<w:del>` markers attributed to `$DOCX_AUTHOR` (default `docx-cli`). To make a one-off untracked edit, flip the flag off, edit, then flip it back on. `find` results inside tracked-change wrappers carry a `trackedChanges` array so agents can decide what to do with hits in pending insertions/deletions.
 
+### Markdown rendering
+
+`docx read FILE --markdown` renders the document body as GitHub-flavored Markdown instead of JSON. Useful when you (or an LLM) want to skim a doc quickly without parsing the AST. Each rendered paragraph is followed by an HTML comment with its locator (`<!-- p3 -->`) so the markdown is invisible-pinned: humans see clean prose in a renderer, agents parse the locators from raw text.
+
+- Headings → `#`/`##`/`###` based on `style="HeadingN"`
+- Lists → `- ` indented per `level`
+- Bold/italic/strike → `**…**` / `*…*` / `~~…~~`; underline → `<u>…</u>`
+- Run color → `<span style="color:#hex">…</span>`; highlight → `<span style="background-color:NAME">…</span>`
+- Hyperlinks → `[text](url)`
+- Images → `![alt](imgN)`
+- Tables → GitHub pipe tables; multi-paragraph cells joined with `<br>`; per-cell-paragraph locators inline
+- Section breaks → `---`
+- Equations (`<m:oMath>`/`<m:oMathPara>`) → `` `equation: text` `` (concatenated `<m:t>` plaintext; structure like sub/sup/fractions collapses to literal characters — degraded but readable)
+- Footnotes / endnotes → inline `[^fnN]` / `[^enN]` refs with GFM footnote definitions at end of output
+- Charts / SmartArt / shapes / other non-picture drawings → `` `[chart]` `` / `` `[smartart]` `` / `` `[shape]` `` / `` `[drawing]` `` placeholders
+
+`--from LOC` and `--to LOC` slice by top-level block (both inclusive). Accepts paragraph, table, cell, span, and range locators; cell/span/range collapse to their enclosing top-level block. Comment/image/hyperlink locators are rejected.
+
+`--changes` renders tracked insertions and deletions as `<ins>`/`<del>` instead of producing the accepted view (which silently drops deletions and inlines insertions).
+
+`--comments` appends a GFM footnote reference (`[^cN]`) at the end of each commented span and emits one footnote definition per comment at the end of the output:
+
+```
+… some commented text[^c0] …
+
+[^c0]: "commented span" — Author Name (2024-01-15T...): comment body
+[^c1]: "another span" — Author Name (2024-01-15T...) ↳ c0: reply body
+```
+
+Footnotes/endnotes (the document's own `<w:footnoteReference>` / `<w:endnoteReference>`) are rendered unconditionally — `[^fn1]` / `[^en1]` inline + `[^fn1]: body` definitions at the end of the output, alongside any `--comments` footnotes. They use `fn`/`en` prefixes so the namespaces don't collide.
+
 ### Locators
 
 ```
@@ -104,7 +135,7 @@ src/
     help.ts              # top-level --help
     respond.ts           # JSON ack / structured error helpers
     create/              # create FILE
-    read/                # read FILE
+    read/                # read FILE [--markdown ...]  (markdown.ts renderer)
     insert/              # insert FILE  (uses ./emit Paragraph component)
     edit/                # edit FILE
     delete/              # delete FILE
@@ -117,7 +148,7 @@ src/
     package/             # JSZip open/close, named-part read/write
     parser/              # XmlNode class + parse/serialize + JSX factory
     jsx/                 # h, Fragment, namespaces (w, r, a, wp, pic, ...)
-    ast/                 # types + DocView + XML→AST reader
+    ast/                 # types + DocView + XML→AST reader (text.ts: shared paragraph helpers)
     locators/            # parse "p3:5-20" + resolve to refs
 tests/
   core/, cli/, integration/

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();
@@ -16185,7 +16317,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, {
@@ -16487,15 +16619,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 +16637,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 +16653,7 @@ function regexMatcher(pattern, ignoreCase) {
         end: result.index + matched.length,
         text: matched
       });
-      result = regex.exec(paragraphText);
+      result = regex.exec(paragraphText2);
     }
     return matches;
   };
@@ -16529,8 +16661,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,
@@ -17721,6 +17853,8 @@ var types_default = `export type Doc = {
 	properties: DocProperties;
 	blocks: Block[];
 	comments: Comment[];
+	footnotes: Footnote[];
+	endnotes: Footnote[];
 };
 
 export type DocProperties = {
@@ -17760,7 +17894,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 +17945,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;
@@ -17886,7 +18058,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 +18080,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 +18116,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 +18186,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"],
@@ -18500,14 +18719,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 +18793,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 +19227,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 +19245,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
@@ -19293,19 +19973,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 +19988,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 +20010,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 +20085,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 +20157,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 +20215,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.0",
   description: "CLI for AI agents (Claude, Codex) to read, edit, and comment on .docx files with full format fidelity.",
   keywords: [
     "docx",

package/package.json

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