bun-docx 0.3.0 → 0.5.0

package/dist/index.js

@@ -13762,7 +13762,7 @@ var init_package = __esm(() => {
 
 // src/core/ast/read.ts
 function buildDoc(view, path) {
-  readImageRelationships(view);
+  readRelationships(view);
   const properties = readDocProperties(view);
   const documentRoot = XmlNode2.findRoot(view.documentTree, "w:document");
   if (!documentRoot) {
@@ -13774,6 +13774,7 @@ function buildDoc(view, path) {
   }
   const state = {
     imageIndex: 0,
+    hyperlinkIndex: 0,
     commentAnchors: new Map,
     openComments: new Map
   };
@@ -13813,17 +13814,30 @@ function readParagraph(view, node, id, state) {
   if (paragraphProperties) {
     applyParagraphProperties(paragraph, paragraphProperties);
   }
-  const activeComments = new Set;
-  let offset = 0;
-  for (const child of node.children) {
+  const context = {
+    view,
+    blockId: id,
+    paragraph,
+    activeComments: new Set,
+    state,
+    offsetRef: { value: 0 }
+  };
+  walkRunContainer(context, node, undefined, undefined);
+  return paragraph;
+}
+function walkRunContainer(context, container, trackedChange, hyperlink) {
+  for (const child of container.children) {
     if (child.tag === "w:pPr")
       continue;
     if (child.tag === "w:commentRangeStart") {
       const commentId = child.getAttribute("w:id");
       if (commentId) {
         const key = `c${commentId}`;
-        activeComments.add(key);
-        state.openComments.set(key, { blockId: id, offset });
+        context.activeComments.add(key);
+        context.state.openComments.set(key, {
+          blockId: context.blockId,
+          offset: context.offsetRef.value
+        });
       }
       continue;
     }
@@ -13831,26 +13845,26 @@ function readParagraph(view, node, id, state) {
       const commentId = child.getAttribute("w:id");
       if (commentId) {
         const key = `c${commentId}`;
-        activeComments.delete(key);
-        const opened = state.openComments.get(key);
+        context.activeComments.delete(key);
+        const opened = context.state.openComments.get(key);
         if (opened) {
-          state.commentAnchors.set(key, {
+          context.state.commentAnchors.set(key, {
             startBlockId: opened.blockId,
             startOffset: opened.offset,
-            endBlockId: id,
-            endOffset: offset
+            endBlockId: context.blockId,
+            endOffset: context.offsetRef.value
           });
-          state.openComments.delete(key);
+          context.state.openComments.delete(key);
         }
       }
       continue;
     }
     if (child.tag === "w:r") {
-      const run = readRun(view, child, activeComments, undefined, state);
+      const run = readRun(context.view, child, context.activeComments, trackedChange, hyperlink, context.state);
       if (run) {
         if (run.type === "text")
-          offset += run.text.length;
-        paragraph.runs.push(run);
+          context.offsetRef.value += run.text.length;
+        context.paragraph.runs.push(run);
       }
       continue;
     }
@@ -13861,46 +13875,40 @@ function readParagraph(view, node, id, state) {
         date: child.getAttribute("w:date") ?? "",
         revisionId: child.getAttribute("w:id") ?? ""
       };
-      for (const inner of child.children) {
-        if (inner.tag === "w:commentRangeStart") {
-          const commentId = inner.getAttribute("w:id");
-          if (commentId) {
-            const key = `c${commentId}`;
-            activeComments.add(key);
-            state.openComments.set(key, { blockId: id, offset });
-          }
-          continue;
-        }
-        if (inner.tag === "w:commentRangeEnd") {
-          const commentId = inner.getAttribute("w:id");
-          if (commentId) {
-            const key = `c${commentId}`;
-            activeComments.delete(key);
-            const opened = state.openComments.get(key);
-            if (opened) {
-              state.commentAnchors.set(key, {
-                startBlockId: opened.blockId,
-                startOffset: opened.offset,
-                endBlockId: id,
-                endOffset: offset
-              });
-              state.openComments.delete(key);
-            }
-          }
-          continue;
-        }
-        if (inner.tag !== "w:r")
-          continue;
-        const run = readRun(view, inner, activeComments, change, state);
-        if (!run)
-          continue;
-        if (run.type === "text")
-          offset += run.text.length;
-        paragraph.runs.push(run);
-      }
+      walkRunContainer(context, child, change, hyperlink);
+      continue;
+    }
+    if (child.tag === "w:hyperlink") {
+      const link = readHyperlinkProperties(context.view, child, container.children, context.state);
+      walkRunContainer(context, child, trackedChange, link);
     }
   }
-  return paragraph;
+}
+function readHyperlinkProperties(view, node, parent, state) {
+  const id = `link${state.hyperlinkIndex++}`;
+  const link = { id };
+  const relationshipId = node.getAttribute("r:id");
+  if (relationshipId) {
+    const relationship = view.hyperlinksByRelationshipId.get(relationshipId);
+    if (relationship?.url)
+      link.url = relationship.url;
+  }
+  const anchor = node.getAttribute("w:anchor");
+  if (anchor)
+    link.anchor = anchor;
+  const tooltip = node.getAttribute("w:tooltip");
+  if (tooltip)
+    link.tooltip = tooltip;
+  if (!link.url && !link.anchor && !link.tooltip) {
+    state.hyperlinkIndex--;
+    return;
+  }
+  view.hyperlinkById.set(id, {
+    node,
+    parent,
+    ...relationshipId ? { relationshipId } : {}
+  });
+  return link;
 }
 function applyParagraphProperties(paragraph, paragraphProperties) {
   const styleNode = paragraphProperties.findChild("w:pStyle");
@@ -13925,7 +13933,7 @@ function applyParagraphProperties(paragraph, paragraphProperties) {
     paragraph.list = { level, numId: id };
   }
 }
-function readRun(view, node, activeComments, trackedChange, state) {
+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") {
@@ -13956,6 +13964,8 @@ function readRun(view, node, activeComments, trackedChange, state) {
     run.comments = [...activeComments];
   if (trackedChange)
     run.trackedChange = trackedChange;
+  if (hyperlink)
+    run.hyperlink = hyperlink;
   return run;
 }
 function applyRunProperties(run, runProperties) {
@@ -14060,22 +14070,30 @@ function readCellBlocks(view, cell, tableId, rowIndex, columnIndex, state) {
   }
   return blocks;
 }
-function readImageRelationships(view) {
+function readRelationships(view) {
   const relationships = XmlNode2.findRoot(view.relationshipsTree, "Relationships");
   if (!relationships)
     return;
   for (const child of relationships.children) {
     if (child.tag !== "Relationship")
       continue;
-    if (child.getAttribute("Type") !== RELATIONSHIP_NAMESPACE_IMAGE)
-      continue;
+    const type = child.getAttribute("Type");
     const relationshipId = child.getAttribute("Id");
     const target = child.getAttribute("Target");
     if (!relationshipId || !target)
       continue;
-    const partName = target.startsWith("/") ? target.slice(1) : `word/${target}`;
-    const contentType = lookupContentType(view, partName);
-    view.imagesByRelationshipId.set(relationshipId, { partName, contentType });
+    if (type === RELATIONSHIP_NAMESPACE_IMAGE) {
+      const partName = target.startsWith("/") ? target.slice(1) : `word/${target}`;
+      const contentType = lookupContentType(view, partName);
+      view.imagesByRelationshipId.set(relationshipId, {
+        partName,
+        contentType
+      });
+      continue;
+    }
+    if (type === RELATIONSHIP_NAMESPACE_HYPERLINK) {
+      view.hyperlinksByRelationshipId.set(relationshipId, { url: target });
+    }
   }
 }
 function lookupContentType(view, partName) {
@@ -14204,7 +14222,7 @@ function readCommentsExtended(view) {
   }
   return out;
 }
-var RELATIONSHIP_NAMESPACE_IMAGE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image";
+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();
 });
@@ -14232,7 +14250,9 @@ async function openDocView(path) {
     blockReferences: new Map,
     commentReferences: new Map,
     imagesByRelationshipId: new Map,
-    imageById: new Map
+    imageById: new Map,
+    hyperlinksByRelationshipId: new Map,
+    hyperlinkById: new Map
   };
   view.doc = buildDoc(view, pkg.path);
   return view;
@@ -14319,6 +14339,10 @@ function parseLocator(input) {
   const imageMatch = trimmed.match(IMAGE_RE);
   if (imageMatch)
     return { kind: "image", imageId: `img${imageMatch[1]}` };
+  const linkMatch = trimmed.match(LINK_RE);
+  if (linkMatch) {
+    return { kind: "hyperlink", hyperlinkId: `link${linkMatch[1]}` };
+  }
   const cellMatch = trimmed.match(CELL_RE);
   if (cellMatch) {
     const [, tableIndex, rowIndex, columnIndex, rest] = cellMatch;
@@ -14367,7 +14391,7 @@ function validateOffsets(input, start, end, crossBlock) {
     throw new LocatorParseError(input, "end offset precedes start");
   }
 }
-var LocatorParseError, BLOCK_RE, SPAN_RE, RANGE_RE, COMMENT_RE, IMAGE_RE, CELL_RE;
+var LocatorParseError, BLOCK_RE, SPAN_RE, RANGE_RE, COMMENT_RE, IMAGE_RE, LINK_RE, CELL_RE;
 var init_parse = __esm(() => {
   LocatorParseError = class LocatorParseError extends Error {
     input;
@@ -14382,6 +14406,7 @@ var init_parse = __esm(() => {
   RANGE_RE = /^p(\d+):(\d+)-p(\d+):(\d+)$/;
   COMMENT_RE = /^c(\d+)$/;
   IMAGE_RE = /^img(\d+)$/;
+  LINK_RE = /^link(\d+)$/;
   CELL_RE = /^t(\d+):r(\d+)c(\d+)(?::(.+))?$/;
 });
 
@@ -14431,6 +14456,39 @@ var init_locators = __esm(() => {
   init_resolve();
 });
 
+// src/core/relationships.ts
+function mintRelationshipId(relationshipsRoot) {
+  let highest = 0;
+  for (const child of relationshipsRoot.children) {
+    if (child.tag !== "Relationship")
+      continue;
+    const id = child.getAttribute("Id");
+    if (!id)
+      continue;
+    const match = id.match(/^rId(\d+)$/);
+    if (match?.[1]) {
+      const number = Number(match[1]);
+      if (number > highest)
+        highest = number;
+    }
+  }
+  return `rId${highest + 1}`;
+}
+function addHyperlinkRelationship(relationshipsRoot, url) {
+  const id = mintRelationshipId(relationshipsRoot);
+  relationshipsRoot.children.push(new XmlNode2("Relationship", {
+    Id: id,
+    Type: HYPERLINK_RELATIONSHIP_TYPE,
+    Target: url,
+    TargetMode: "External"
+  }));
+  return id;
+}
+var HYPERLINK_RELATIONSHIP_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink";
+var init_relationships = __esm(() => {
+  init_parser();
+});
+
 // src/core/track-changes/index.ts
 function isTrackChangesEnabled(view) {
   if (!view.settingsTree)
@@ -14607,7 +14665,8 @@ var init_jsx = __esm(() => {
     "comments",
     "comment",
     "settings",
-    "trackChanges"
+    "trackChanges",
+    "hyperlink"
   ];
   R_TAGS = ["embed", "link", "id"];
   A_TAGS = [
@@ -14722,6 +14781,7 @@ var init_core = __esm(() => {
   init_locators();
   init_package();
   init_parser();
+  init_relationships();
   init_track_changes();
   init_emit();
 });
@@ -14755,6 +14815,7 @@ function exitCodeFor(code) {
     case "BLOCK_NOT_FOUND":
     case "COMMENT_NOT_FOUND":
     case "IMAGE_NOT_FOUND":
+    case "HYPERLINK_NOT_FOUND":
     case "MATCH_NOT_FOUND":
       return EXIT.NOT_FOUND;
     case "NOT_A_ZIP":
@@ -16629,12 +16690,107 @@ var init_find = __esm(() => {
   init_respond();
 });
 
-// src/cli/images/extract.ts
-var exports_extract = {};
-__export(exports_extract, {
+// src/cli/hyperlinks/wrap.tsx
+function wrapSpanInHyperlink(paragraph, span, relationshipId) {
+  if (span.start >= span.end) {
+    throw new HyperlinkWrapError(`Empty or inverted span ${span.start}-${span.end}`);
+  }
+  const newChildren = [];
+  const wrappedRuns = [];
+  let offset = 0;
+  let placed = false;
+  const placeWrapper = () => {
+    if (placed || wrappedRuns.length === 0)
+      return;
+    newChildren.push(hyperlinkWrapper(relationshipId, wrappedRuns));
+    wrappedRuns.length = 0;
+    placed = true;
+  };
+  for (const child of paragraph.children) {
+    if (child.tag === "w:r") {
+      const length = runTextLength(child);
+      const runStart = offset;
+      const runEnd = offset + length;
+      offset = runEnd;
+      if (runEnd <= span.start || runStart >= span.end) {
+        placeWrapper();
+        newChildren.push(child);
+        continue;
+      }
+      const sliceStartInRun = Math.max(0, span.start - runStart);
+      const sliceEndInRun = Math.min(length, span.end - runStart);
+      if (sliceStartInRun > 0) {
+        newChildren.push(sliceRun(child, 0, sliceStartInRun));
+      }
+      wrappedRuns.push(sliceRun(child, sliceStartInRun, sliceEndInRun));
+      if (runEnd >= span.end)
+        placeWrapper();
+      if (sliceEndInRun < length) {
+        newChildren.push(sliceRun(child, sliceEndInRun, length));
+      }
+      continue;
+    }
+    if (child.tag === "w:hyperlink") {
+      const hyperlinkLength = sumInnerRunLengths(child);
+      const hyperlinkStart = offset;
+      const hyperlinkEnd = offset + hyperlinkLength;
+      offset = hyperlinkEnd;
+      if (hyperlinkEnd <= span.start || hyperlinkStart >= span.end) {
+        placeWrapper();
+        newChildren.push(child);
+        continue;
+      }
+      throw new HyperlinkWrapError(`Span ${span.start}-${span.end} overlaps an existing hyperlink at ${hyperlinkStart}-${hyperlinkEnd}; nested hyperlinks are not allowed`);
+    }
+    if (child.tag === "w:ins" || child.tag === "w:del") {
+      const innerLength = sumInnerRunLengths(child);
+      const wrapperStart = offset;
+      const wrapperEnd = offset + innerLength;
+      offset = wrapperEnd;
+      if (wrapperEnd <= span.start || wrapperStart >= span.end) {
+        placeWrapper();
+        newChildren.push(child);
+        continue;
+      }
+      throw new HyperlinkWrapError(`Span ${span.start}-${span.end} crosses a tracked-change wrapper at ${wrapperStart}-${wrapperEnd}; resolve or accept the change first`);
+    }
+    newChildren.push(child);
+  }
+  placeWrapper();
+  paragraph.children = newChildren;
+}
+function hyperlinkWrapper(relationshipId, runs) {
+  return /* @__PURE__ */ jsxDEV(w.hyperlink, {
+    "r:id": relationshipId,
+    children: runs
+  }, undefined, false, undefined, this);
+}
+function sumInnerRunLengths(wrapper) {
+  let total = 0;
+  for (const inner of wrapper.children) {
+    if (inner.tag === "w:r")
+      total += runTextLength(inner);
+  }
+  return total;
+}
+var HyperlinkWrapError;
+var init_wrap = __esm(() => {
+  init_jsx();
+  init_parser();
+  init_jsx_dev_runtime();
+  HyperlinkWrapError = class HyperlinkWrapError extends Error {
+    constructor(message) {
+      super(message);
+      this.name = "HyperlinkWrapError";
+    }
+  };
+});
+
+// src/cli/hyperlinks/add.tsx
+var exports_add2 = {};
+__export(exports_add2, {
   run: () => run11
 });
-import { join } from "path";
 import { parseArgs as parseArgs10 } from "util";
 async function run11(args) {
   let parsed;
@@ -16643,8 +16799,10 @@ async function run11(args) {
       args,
       allowPositionals: true,
       options: {
-        to: { type: "string" },
-        id: { type: "string" },
+        at: { type: "string" },
+        url: { type: "string" },
+        output: { type: "string", short: "o" },
+        "dry-run": { type: "boolean" },
         help: { type: "boolean", short: "h" }
       }
     });
@@ -16659,109 +16817,100 @@ async function run11(args) {
   const path = parsed.positionals[0];
   if (!path)
     return fail("USAGE", "Missing FILE argument", HELP11);
-  const outputDir = parsed.values.to;
-  if (!outputDir)
-    return fail("USAGE", "Missing --to DIR", HELP11);
-  const targetId = parsed.values.id;
+  const atInput = parsed.values.at;
+  const url = parsed.values.url;
+  if (!atInput)
+    return fail("USAGE", "Missing --at LOCATOR", HELP11);
+  if (!url)
+    return fail("USAGE", "Missing --url URL", HELP11);
+  let locator;
+  try {
+    locator = parseLocator(atInput);
+  } catch (error) {
+    if (error instanceof LocatorParseError) {
+      return fail("INVALID_LOCATOR", error.message);
+    }
+    throw error;
+  }
+  const target = locatorToBlockTarget(locator);
+  if (!target?.span) {
+    return fail("INVALID_LOCATOR", "hyperlinks add requires a span locator like pN:S-E or tT:rRcC:pK:S-E");
+  }
   const view = await openOrFail(path);
   if (typeof view === "number")
     return view;
-  await enrichImageHashes(view);
-  const allImages = [];
-  collectImages(view.doc.blocks, allImages);
-  const targets = targetId ? allImages.filter((image) => image.id === targetId) : allImages;
-  if (targetId && targets.length === 0) {
-    return fail("IMAGE_NOT_FOUND", `Image not found: ${targetId}`);
-  }
-  const manifest = [];
-  const seenHashes = new Set;
-  for (const image of targets) {
-    const reference = view.imageById.get(image.id);
-    if (!reference)
-      continue;
-    const extension = extensionFor(image.contentType, reference.partName);
-    const fileName = `${image.hash}.${extension}`;
-    const outputPath = join(outputDir, fileName);
-    if (!seenHashes.has(image.hash)) {
-      const bytes = await view.pkg.readBytes(reference.partName);
-      await Bun.write(outputPath, bytes);
-      seenHashes.add(image.hash);
-    }
-    manifest.push({
-      id: image.id,
-      path: outputPath,
-      bytes: (await Bun.file(outputPath).arrayBuffer()).byteLength
+  const paragraphRef = await resolveBlockOrFail(view, target.blockId);
+  if (typeof paragraphRef === "number")
+    return paragraphRef;
+  const outputPath = parsed.values.output;
+  if (parsed.values["dry-run"]) {
+    await respond({
+      ok: true,
+      operation: "hyperlinks.add",
+      dryRun: true,
+      path,
+      at: atInput,
+      url,
+      ...outputPath ? { output: outputPath } : {}
     });
+    return EXIT.OK;
   }
-  await respond({ ok: true, operation: "images.extract", path, manifest });
-  return EXIT.OK;
-}
-function collectImages(blocks, out) {
-  for (const block of blocks) {
-    if (block.type === "paragraph") {
-      for (const run12 of block.runs) {
-        if (run12.type === "image")
-          out.push(run12);
-      }
-      continue;
-    }
-    if (block.type === "table") {
-      for (const row of block.rows) {
-        for (const cell of row.cells) {
-          collectImages(cell.blocks, out);
-        }
-      }
+  const relationships = XmlNode2.findRoot(view.relationshipsTree, "Relationships");
+  if (!relationships) {
+    return fail("UNHANDLED", "Missing <Relationships> root in document rels");
+  }
+  const relationshipId = addHyperlinkRelationship(relationships, url);
+  try {
+    wrapSpanInHyperlink(paragraphRef.node, target.span, relationshipId);
+  } catch (error) {
+    if (error instanceof HyperlinkWrapError) {
+      return fail("USAGE", error.message);
     }
+    throw error;
   }
+  view.hyperlinksByRelationshipId.set(relationshipId, { url });
+  await saveDocView(view, outputPath);
+  await respond({
+    ok: true,
+    operation: "hyperlinks.add",
+    path: outputPath ?? path,
+    at: atInput,
+    url
+  });
+  return EXIT.OK;
 }
-function extensionFor(contentType, partName) {
-  const fromType = EXTENSION_BY_CONTENT_TYPE[contentType.toLowerCase()];
-  if (fromType)
-    return fromType;
-  const fromName = partName.split(".").pop()?.toLowerCase();
-  return fromName ?? "bin";
-}
-var HELP11 = `docx images extract \u2014 dump image bytes to a directory
+var HELP11 = `docx hyperlinks add \u2014 wrap an existing span in a hyperlink
 
 Usage:
-  docx images extract FILE --to DIR [options]
+  docx hyperlinks add FILE --at LOCATOR --url URL [options]
 
 Required:
-  --to DIR          Output directory (created if missing)
+  --at LOCATOR      Where to wrap. Supports:
+                      pN:S-E          chars S..E of pN
+                      tT:rRcC:pK:S-E  chars S..E of a cell paragraph
+  --url URL         Target URL
 
 Optional:
-  --id IMG_ID       Extract a single image (default: extract all)
+  -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
 
-Files are named <hash>.<ext> where hash is the sha256 of the image bytes
-and ext is derived from contentType. Returns a manifest mapping image ids
-to written paths.
+The span must lie inside a single paragraph and must not overlap an existing
+hyperlink or a tracked-change wrapper.
 
 Examples:
-  docx images extract doc.docx --to ./media
-  docx images extract doc.docx --to ./media --id img2
-`, EXTENSION_BY_CONTENT_TYPE;
-var init_extract = __esm(() => {
+  docx hyperlinks add doc.docx --at p3:5-20 --url https://example.com
+`;
+var init_add2 = __esm(() => {
   init_core();
+  init_parser();
   init_respond();
-  EXTENSION_BY_CONTENT_TYPE = {
-    "image/png": "png",
-    "image/jpeg": "jpg",
-    "image/jpg": "jpg",
-    "image/gif": "gif",
-    "image/svg+xml": "svg",
-    "image/webp": "webp",
-    "image/tiff": "tif",
-    "image/bmp": "bmp",
-    "image/x-emf": "emf",
-    "image/x-wmf": "wmf",
-    "image/vnd.microsoft.icon": "ico"
-  };
+  init_wrap();
 });
 
-// src/cli/images/list.ts
-var exports_list2 = {};
-__export(exports_list2, {
+// src/cli/hyperlinks/delete.ts
+var exports_delete3 = {};
+__export(exports_delete3, {
   run: () => run12
 });
 import { parseArgs as parseArgs11 } from "util";
@@ -16772,6 +16921,9 @@ async function run12(args) {
       args,
       allowPositionals: true,
       options: {
+        at: { type: "string" },
+        output: { type: "string", short: "o" },
+        "dry-run": { type: "boolean" },
         help: { type: "boolean", short: "h" }
       }
     });
@@ -16786,34 +16938,560 @@ async function run12(args) {
   const path = parsed.positionals[0];
   if (!path)
     return fail("USAGE", "Missing FILE argument", HELP12);
+  const targetId = parsed.values.at;
+  if (!targetId)
+    return fail("USAGE", "Missing --at LINK_ID", HELP12);
   const view = await openOrFail(path);
   if (typeof view === "number")
     return view;
-  await enrichImageHashes(view);
-  const images = [];
-  collectImages2(view.doc.blocks, images);
-  await respond(images);
-  return EXIT.OK;
-}
-function collectImages2(blocks, out) {
-  for (const block of blocks) {
-    if (block.type === "paragraph") {
-      for (const run13 of block.runs) {
-        if (run13.type === "image")
-          out.push(run13);
-      }
-      continue;
-    }
-    if (block.type === "table") {
-      for (const row of block.rows) {
-        for (const cell of row.cells) {
-          collectImages2(cell.blocks, out);
-        }
-      }
-    }
+  const reference = view.hyperlinkById.get(targetId);
+  if (!reference) {
+    return fail("HYPERLINK_NOT_FOUND", `Hyperlink not found: ${targetId}`);
+  }
+  const oldUrl = reference.relationshipId ? view.hyperlinksByRelationshipId.get(reference.relationshipId)?.url : undefined;
+  const outputPath = parsed.values.output;
+  if (parsed.values["dry-run"]) {
+    await respond({
+      ok: true,
+      operation: "hyperlinks.delete",
+      dryRun: true,
+      path,
+      hyperlinkId: targetId,
+      from: oldUrl,
+      ...outputPath ? { output: outputPath } : {}
+    });
+    return EXIT.OK;
+  }
+  const index = reference.parent.indexOf(reference.node);
+  if (index === -1) {
+    return fail("HYPERLINK_NOT_FOUND", `Hyperlink reference is stale (parent does not contain it): ${targetId}`);
+  }
+  reference.parent.splice(index, 1, ...reference.node.children);
+  view.hyperlinkById.delete(targetId);
+  if (reference.relationshipId) {
+    const remaining = countHyperlinkUsages(view.documentTree, reference.relationshipId);
+    if (remaining === 0) {
+      pruneRelationship(view.relationshipsTree, reference.relationshipId);
+      view.hyperlinksByRelationshipId.delete(reference.relationshipId);
+    }
+  }
+  await saveDocView(view, outputPath);
+  await respond({
+    ok: true,
+    operation: "hyperlinks.delete",
+    path: outputPath ?? path,
+    hyperlinkId: targetId,
+    from: oldUrl
+  });
+  return EXIT.OK;
+}
+function countHyperlinkUsages(documentTree, relationshipId) {
+  let count = 0;
+  for (const root of documentTree) {
+    count += countInNode(root, relationshipId);
+  }
+  return count;
+}
+function countInNode(node, relationshipId) {
+  let count = 0;
+  if (node.tag === "w:hyperlink" && node.getAttribute("r:id") === relationshipId) {
+    count++;
+  }
+  for (const child of node.children) {
+    count += countInNode(child, relationshipId);
+  }
+  return count;
+}
+function pruneRelationship(relationshipsTree, relationshipId) {
+  const relationships = XmlNode2.findRoot(relationshipsTree, "Relationships");
+  if (!relationships)
+    return;
+  relationships.children = relationships.children.filter((child) => !(child.tag === "Relationship" && child.getAttribute("Id") === relationshipId));
+}
+var HELP12 = `docx hyperlinks delete \u2014 unwrap a hyperlink (keep the text)
+
+Usage:
+  docx hyperlinks delete FILE --at LINK_ID [options]
+
+Required:
+  --at LINK_ID      Existing hyperlink to remove (e.g., link0)
+
+Optional:
+  -o, --output PATH Write to PATH instead of overwriting FILE
+  --dry-run         Print what would change; do not write the file
+  -h, --help        Show this help
+
+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.
+
+Examples:
+  docx hyperlinks delete doc.docx --at link0
+`;
+var init_delete3 = __esm(() => {
+  init_core();
+  init_parser();
+  init_respond();
+});
+
+// src/cli/hyperlinks/list.ts
+var exports_list2 = {};
+__export(exports_list2, {
+  run: () => run13
+});
+import { parseArgs as parseArgs12 } from "util";
+async function run13(args) {
+  let parsed;
+  try {
+    parsed = parseArgs12({
+      args,
+      allowPositionals: true,
+      options: {
+        help: { type: "boolean", short: "h" }
+      }
+    });
+  } catch (parseError) {
+    const message = parseError instanceof Error ? parseError.message : String(parseError);
+    return fail("USAGE", message, HELP13);
+  }
+  if (parsed.values.help) {
+    await writeStdout(HELP13);
+    return EXIT.OK;
+  }
+  const path = parsed.positionals[0];
+  if (!path)
+    return fail("USAGE", "Missing FILE argument", HELP13);
+  const view = await openOrFail(path);
+  if (typeof view === "number")
+    return view;
+  const entries = new Map;
+  collectHyperlinks(view.doc.blocks, entries);
+  await respond([...entries.values()]);
+  return EXIT.OK;
+}
+function collectHyperlinks(blocks, entries) {
+  for (const block of blocks) {
+    if (block.type === "paragraph") {
+      for (const run14 of block.runs) {
+        if (run14.type !== "text" || !run14.hyperlink)
+          continue;
+        addToEntry(entries, run14.hyperlink, block.id, run14.text);
+      }
+      continue;
+    }
+    if (block.type === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          collectHyperlinks(cell.blocks, entries);
+        }
+      }
+    }
+  }
+}
+function addToEntry(entries, hyperlink, blockId, text) {
+  const existing = entries.get(hyperlink.id);
+  if (existing) {
+    existing.text += text;
+    return;
+  }
+  const entry = {
+    id: hyperlink.id,
+    text,
+    blockId
+  };
+  if (hyperlink.url)
+    entry.url = hyperlink.url;
+  if (hyperlink.anchor)
+    entry.anchor = hyperlink.anchor;
+  if (hyperlink.tooltip)
+    entry.tooltip = hyperlink.tooltip;
+  entries.set(hyperlink.id, entry);
+}
+var HELP13 = `docx hyperlinks list \u2014 print hyperlink manifest as JSON
+
+Usage:
+  docx hyperlinks list FILE [options]
+
+Options:
+  -h, --help        Show this help
+
+Each entry has: id, url (or anchor), tooltip (if set), text (display text),
+and blockId (the paragraph containing the link).
+
+Examples:
+  docx hyperlinks list doc.docx | jq -c '.[] | {id, url, text}'
+`;
+var init_list2 = __esm(() => {
+  init_respond();
+});
+
+// src/cli/hyperlinks/replace.ts
+var exports_replace = {};
+__export(exports_replace, {
+  run: () => run14
+});
+import { parseArgs as parseArgs13 } from "util";
+async function run14(args) {
+  let parsed;
+  try {
+    parsed = parseArgs13({
+      args,
+      allowPositionals: true,
+      options: {
+        at: { type: "string" },
+        with: { type: "string" },
+        output: { type: "string", short: "o" },
+        "dry-run": { type: "boolean" },
+        help: { type: "boolean", short: "h" }
+      }
+    });
+  } catch (parseError) {
+    const message = parseError instanceof Error ? parseError.message : String(parseError);
+    return fail("USAGE", message, HELP14);
+  }
+  if (parsed.values.help) {
+    await writeStdout(HELP14);
+    return EXIT.OK;
+  }
+  const path = parsed.positionals[0];
+  if (!path)
+    return fail("USAGE", "Missing FILE argument", HELP14);
+  const targetId = parsed.values.at;
+  if (!targetId)
+    return fail("USAGE", "Missing --at LINK_ID", HELP14);
+  const newUrl = parsed.values.with;
+  if (!newUrl)
+    return fail("USAGE", "Missing --with URL", HELP14);
+  const view = await openOrFail(path);
+  if (typeof view === "number")
+    return view;
+  const reference = view.hyperlinkById.get(targetId);
+  if (!reference) {
+    return fail("HYPERLINK_NOT_FOUND", `Hyperlink not found: ${targetId}`);
+  }
+  const relationships = XmlNode2.findRoot(view.relationshipsTree, "Relationships");
+  if (!relationships) {
+    return fail("UNHANDLED", "Missing <Relationships> root in document rels");
+  }
+  const existingId = reference.relationshipId;
+  const oldUrl = existingId ? view.hyperlinksByRelationshipId.get(existingId)?.url : undefined;
+  const sharedCount = existingId ? countHyperlinkUsages2(view.documentTree, existingId) : 0;
+  const willAllocateNew = !existingId || sharedCount > 1;
+  const outputPath = parsed.values.output;
+  if (parsed.values["dry-run"]) {
+    await respond({
+      ok: true,
+      operation: "hyperlinks.replace",
+      dryRun: true,
+      path,
+      hyperlinkId: targetId,
+      from: oldUrl,
+      to: newUrl,
+      sharedRelationship: sharedCount > 1,
+      ...outputPath ? { output: outputPath } : {}
+    });
+    return EXIT.OK;
+  }
+  if (willAllocateNew) {
+    const newRelationshipId = addHyperlinkRelationship(relationships, newUrl);
+    reference.node.setAttribute("r:id", newRelationshipId);
+    reference.relationshipId = newRelationshipId;
+    view.hyperlinksByRelationshipId.set(newRelationshipId, { url: newUrl });
+  } else if (existingId) {
+    updateRelationshipTarget(relationships, existingId, newUrl);
+    view.hyperlinksByRelationshipId.set(existingId, { url: newUrl });
+  }
+  await saveDocView(view, outputPath);
+  await respond({
+    ok: true,
+    operation: "hyperlinks.replace",
+    path: outputPath ?? path,
+    hyperlinkId: targetId,
+    from: oldUrl,
+    to: newUrl
+  });
+  return EXIT.OK;
+}
+function updateRelationshipTarget(relationships, relationshipId, newTarget) {
+  for (const child of relationships.children) {
+    if (child.tag !== "Relationship")
+      continue;
+    if (child.getAttribute("Id") === relationshipId) {
+      child.setAttribute("Target", newTarget);
+      return;
+    }
+  }
+}
+function countHyperlinkUsages2(documentTree, relationshipId) {
+  let count = 0;
+  for (const root of documentTree) {
+    count += countInNode2(root, relationshipId);
+  }
+  return count;
+}
+function countInNode2(node, relationshipId) {
+  let count = 0;
+  if (node.tag === "w:hyperlink" && node.getAttribute("r:id") === relationshipId) {
+    count++;
+  }
+  for (const child of node.children) {
+    count += countInNode2(child, relationshipId);
+  }
+  return count;
+}
+var HELP14 = `docx hyperlinks replace \u2014 change a hyperlink's URL
+
+Usage:
+  docx hyperlinks replace FILE --at LINK_ID --with URL [options]
+
+Required:
+  --at LINK_ID      Existing hyperlink to update (e.g., link0)
+  --with URL        New target URL
+
+Optional:
+  -o, --output PATH Write to PATH instead of overwriting FILE
+  --dry-run         Print what would change; do not write the file
+  -h, --help        Show this help
+
+Replaces only the targeted hyperlink. If multiple hyperlinks shared the same
+underlying relationship, a new relationship is allocated so the others are
+unaffected.
+
+Examples:
+  docx hyperlinks replace doc.docx --at link0 --with https://example.com
+`;
+var init_replace = __esm(() => {
+  init_core();
+  init_parser();
+  init_respond();
+});
+
+// src/cli/hyperlinks/index.ts
+var exports_hyperlinks = {};
+__export(exports_hyperlinks, {
+  run: () => run15
+});
+async function run15(args) {
+  const verb = args[0];
+  if (!verb || verb === "--help" || verb === "-h" || verb === "help") {
+    await writeStdout(HELP15);
+    return verb ? 0 : 2;
+  }
+  const loader = SUBCOMMANDS2[verb];
+  if (!loader) {
+    return fail("USAGE", `Unknown hyperlinks subcommand: ${verb}`, 'Run "docx hyperlinks --help".');
+  }
+  const module_ = await loader();
+  return module_.run(args.slice(1));
+}
+var SUBCOMMANDS2, HELP15 = `docx hyperlinks \u2014 manage hyperlinks
+
+Usage:
+  docx hyperlinks <verb> FILE [options]
+
+Verbs:
+  add      Wrap an existing span in a hyperlink
+  delete   Unwrap a hyperlink (keep the text)
+  list     Print hyperlink manifest as JSON
+  replace  Change a hyperlink's URL
+
+Run "docx hyperlinks <verb> --help" for verb-specific help.
+`;
+var init_hyperlinks = __esm(() => {
+  init_respond();
+  SUBCOMMANDS2 = {
+    add: () => Promise.resolve().then(() => (init_add2(), exports_add2)),
+    delete: () => Promise.resolve().then(() => (init_delete3(), exports_delete3)),
+    list: () => Promise.resolve().then(() => (init_list2(), exports_list2)),
+    replace: () => Promise.resolve().then(() => (init_replace(), exports_replace))
+  };
+});
+
+// src/cli/images/extract.ts
+var exports_extract = {};
+__export(exports_extract, {
+  run: () => run16
+});
+import { join } from "path";
+import { parseArgs as parseArgs14 } from "util";
+async function run16(args) {
+  let parsed;
+  try {
+    parsed = parseArgs14({
+      args,
+      allowPositionals: true,
+      options: {
+        to: { type: "string" },
+        id: { type: "string" },
+        help: { type: "boolean", short: "h" }
+      }
+    });
+  } catch (parseError) {
+    const message = parseError instanceof Error ? parseError.message : String(parseError);
+    return fail("USAGE", message, HELP16);
+  }
+  if (parsed.values.help) {
+    await writeStdout(HELP16);
+    return EXIT.OK;
+  }
+  const path = parsed.positionals[0];
+  if (!path)
+    return fail("USAGE", "Missing FILE argument", HELP16);
+  const outputDir = parsed.values.to;
+  if (!outputDir)
+    return fail("USAGE", "Missing --to DIR", HELP16);
+  const targetId = parsed.values.id;
+  const view = await openOrFail(path);
+  if (typeof view === "number")
+    return view;
+  await enrichImageHashes(view);
+  const allImages = [];
+  collectImages(view.doc.blocks, allImages);
+  const targets = targetId ? allImages.filter((image) => image.id === targetId) : allImages;
+  if (targetId && targets.length === 0) {
+    return fail("IMAGE_NOT_FOUND", `Image not found: ${targetId}`);
+  }
+  const manifest = [];
+  const seenHashes = new Set;
+  for (const image of targets) {
+    const reference = view.imageById.get(image.id);
+    if (!reference)
+      continue;
+    const extension = extensionFor(image.contentType, reference.partName);
+    const fileName = `${image.hash}.${extension}`;
+    const outputPath = join(outputDir, fileName);
+    if (!seenHashes.has(image.hash)) {
+      const bytes = await view.pkg.readBytes(reference.partName);
+      await Bun.write(outputPath, bytes);
+      seenHashes.add(image.hash);
+    }
+    manifest.push({
+      id: image.id,
+      path: outputPath,
+      bytes: (await Bun.file(outputPath).arrayBuffer()).byteLength
+    });
+  }
+  await respond({ ok: true, operation: "images.extract", path, manifest });
+  return EXIT.OK;
+}
+function collectImages(blocks, out) {
+  for (const block of blocks) {
+    if (block.type === "paragraph") {
+      for (const run17 of block.runs) {
+        if (run17.type === "image")
+          out.push(run17);
+      }
+      continue;
+    }
+    if (block.type === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          collectImages(cell.blocks, out);
+        }
+      }
+    }
+  }
+}
+function extensionFor(contentType, partName) {
+  const fromType = EXTENSION_BY_CONTENT_TYPE[contentType.toLowerCase()];
+  if (fromType)
+    return fromType;
+  const fromName = partName.split(".").pop()?.toLowerCase();
+  return fromName ?? "bin";
+}
+var HELP16 = `docx images extract \u2014 dump image bytes to a directory
+
+Usage:
+  docx images extract FILE --to DIR [options]
+
+Required:
+  --to DIR          Output directory (created if missing)
+
+Optional:
+  --id IMG_ID       Extract a single image (default: extract all)
+  -h, --help        Show this help
+
+Files are named <hash>.<ext> where hash is the sha256 of the image bytes
+and ext is derived from contentType. Returns a manifest mapping image ids
+to written paths.
+
+Examples:
+  docx images extract doc.docx --to ./media
+  docx images extract doc.docx --to ./media --id img2
+`, EXTENSION_BY_CONTENT_TYPE;
+var init_extract = __esm(() => {
+  init_core();
+  init_respond();
+  EXTENSION_BY_CONTENT_TYPE = {
+    "image/png": "png",
+    "image/jpeg": "jpg",
+    "image/jpg": "jpg",
+    "image/gif": "gif",
+    "image/svg+xml": "svg",
+    "image/webp": "webp",
+    "image/tiff": "tif",
+    "image/bmp": "bmp",
+    "image/x-emf": "emf",
+    "image/x-wmf": "wmf",
+    "image/vnd.microsoft.icon": "ico"
+  };
+});
+
+// src/cli/images/list.ts
+var exports_list3 = {};
+__export(exports_list3, {
+  run: () => run17
+});
+import { parseArgs as parseArgs15 } from "util";
+async function run17(args) {
+  let parsed;
+  try {
+    parsed = parseArgs15({
+      args,
+      allowPositionals: true,
+      options: {
+        help: { type: "boolean", short: "h" }
+      }
+    });
+  } catch (parseError) {
+    const message = parseError instanceof Error ? parseError.message : String(parseError);
+    return fail("USAGE", message, HELP17);
+  }
+  if (parsed.values.help) {
+    await writeStdout(HELP17);
+    return EXIT.OK;
+  }
+  const path = parsed.positionals[0];
+  if (!path)
+    return fail("USAGE", "Missing FILE argument", HELP17);
+  const view = await openOrFail(path);
+  if (typeof view === "number")
+    return view;
+  await enrichImageHashes(view);
+  const images = [];
+  collectImages2(view.doc.blocks, images);
+  await respond(images);
+  return EXIT.OK;
+}
+function collectImages2(blocks, out) {
+  for (const block of blocks) {
+    if (block.type === "paragraph") {
+      for (const run18 of block.runs) {
+        if (run18.type === "image")
+          out.push(run18);
+      }
+      continue;
+    }
+    if (block.type === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          collectImages2(cell.blocks, out);
+        }
+      }
+    }
   }
 }
-var HELP12 = `docx images list \u2014 print image manifest as JSON
+var HELP17 = `docx images list \u2014 print image manifest as JSON
 
 Usage:
   docx images list FILE [options]
@@ -16824,21 +17502,21 @@ Options:
 Examples:
   docx images list doc.docx | jq -c '.[] | {id, contentType, hash}'
 `;
-var init_list2 = __esm(() => {
+var init_list3 = __esm(() => {
   init_core();
   init_respond();
 });
 
 // src/cli/images/replace.ts
-var exports_replace = {};
-__export(exports_replace, {
-  run: () => run13
+var exports_replace2 = {};
+__export(exports_replace2, {
+  run: () => run18
 });
-import { parseArgs as parseArgs12 } from "util";
-async function run13(args) {
+import { parseArgs as parseArgs16 } from "util";
+async function run18(args) {
   let parsed;
   try {
-    parsed = parseArgs12({
+    parsed = parseArgs16({
       args,
       allowPositionals: true,
       options: {
@@ -16851,21 +17529,21 @@ async function run13(args) {
     });
   } catch (parseError) {
     const message = parseError instanceof Error ? parseError.message : String(parseError);
-    return fail("USAGE", message, HELP13);
+    return fail("USAGE", message, HELP18);
   }
   if (parsed.values.help) {
-    await writeStdout(HELP13);
+    await writeStdout(HELP18);
     return EXIT.OK;
   }
   const path = parsed.positionals[0];
   if (!path)
-    return fail("USAGE", "Missing FILE argument", HELP13);
+    return fail("USAGE", "Missing FILE argument", HELP18);
   const targetId = parsed.values.at;
   if (!targetId)
-    return fail("USAGE", "Missing --at IMG_ID", HELP13);
+    return fail("USAGE", "Missing --at IMG_ID", HELP18);
   const sourcePath = parsed.values.with;
   if (!sourcePath)
-    return fail("USAGE", "Missing --with PATH", HELP13);
+    return fail("USAGE", "Missing --with PATH", HELP18);
   const sourceFile = Bun.file(sourcePath);
   if (!await sourceFile.exists()) {
     return fail("FILE_NOT_FOUND", `Replacement file not found: ${sourcePath}`);
@@ -16904,7 +17582,7 @@ async function run13(args) {
   } else {
     view.pkg.writeBytes(newPartName, bytes);
     view.pkg.deletePart(originalPartName);
-    updateRelationshipTarget(view.relationshipsTree, reference.relationshipId, relativeTargetFor(newPartName));
+    updateRelationshipTarget2(view.relationshipsTree, reference.relationshipId, relativeTargetFor(newPartName));
     ensureContentTypeDefault(view.contentTypesTree, newExtension, newMimeType);
     reference.partName = newPartName;
     reference.contentType = newMimeType;
@@ -16932,7 +17610,7 @@ function renameExtension(partName, newExtension) {
 function relativeTargetFor(partName) {
   return partName.startsWith("word/") ? partName.slice("word/".length) : partName;
 }
-function updateRelationshipTarget(relationshipsTree, relationshipId, newTarget) {
+function updateRelationshipTarget2(relationshipsTree, relationshipId, newTarget) {
   const relationships = XmlNode2.findRoot(relationshipsTree, "Relationships");
   if (!relationships)
     return;
@@ -16957,7 +17635,7 @@ function ensureContentTypeDefault(contentTypesTree, extension, mimeType) {
   }
   types.children.push(new XmlNode2("Default", { Extension: extension, ContentType: mimeType }));
 }
-var HELP13 = `docx images replace \u2014 swap an image's bytes
+var HELP18 = `docx images replace \u2014 swap an image's bytes
 
 Usage:
   docx images replace FILE --at IMG_ID --with PATH [options]
@@ -16979,7 +17657,7 @@ Examples:
   docx images replace doc.docx --at img2 --with ./new-photo.png
   docx images replace doc.docx --at img0 --with ./diagram.svg
 `, EXTENSION_BY_MIME;
-var init_replace = __esm(() => {
+var init_replace2 = __esm(() => {
   init_core();
   init_parser();
   init_respond();
@@ -17000,22 +17678,22 @@ var init_replace = __esm(() => {
 // src/cli/images/index.ts
 var exports_images = {};
 __export(exports_images, {
-  run: () => run14
+  run: () => run19
 });
-async function run14(args) {
+async function run19(args) {
   const verb = args[0];
   if (!verb || verb === "--help" || verb === "-h" || verb === "help") {
-    await writeStdout(HELP14);
+    await writeStdout(HELP19);
     return verb ? 0 : 2;
   }
-  const loader = SUBCOMMANDS2[verb];
+  const loader = SUBCOMMANDS3[verb];
   if (!loader) {
     return fail("USAGE", `Unknown images subcommand: ${verb}`, 'Run "docx images --help".');
   }
   const module_ = await loader();
   return module_.run(args.slice(1));
 }
-var SUBCOMMANDS2, HELP14 = `docx images \u2014 manage embedded images
+var SUBCOMMANDS3, HELP19 = `docx images \u2014 manage embedded images
 
 Usage:
   docx images <verb> FILE [options]
@@ -17029,10 +17707,10 @@ Run "docx images <verb> --help" for verb-specific help.
 `;
 var init_images = __esm(() => {
   init_respond();
-  SUBCOMMANDS2 = {
+  SUBCOMMANDS3 = {
     extract: () => Promise.resolve().then(() => (init_extract(), exports_extract)),
-    list: () => Promise.resolve().then(() => (init_list2(), exports_list2)),
-    replace: () => Promise.resolve().then(() => (init_replace(), exports_replace))
+    list: () => Promise.resolve().then(() => (init_list3(), exports_list3)),
+    replace: () => Promise.resolve().then(() => (init_replace2(), exports_replace2))
   };
 });
 
@@ -17097,6 +17775,14 @@ export type TextRun = {
 	sizeHalfPoints?: number;
 	comments?: string[];
 	trackedChange?: TrackedChange;
+	hyperlink?: Hyperlink;
+};
+
+export type Hyperlink = {
+	id: string;
+	url?: string;
+	anchor?: string;
+	tooltip?: string;
 };
 
 export type ImageRun = {
@@ -17148,13 +17834,13 @@ var init_types = () => {};
 // src/cli/info/schema.ts
 var exports_schema = {};
 __export(exports_schema, {
-  run: () => run15
+  run: () => run20
 });
-import { parseArgs as parseArgs13 } from "util";
-async function run15(args) {
+import { parseArgs as parseArgs17 } from "util";
+async function run20(args) {
   let parsed;
   try {
-    parsed = parseArgs13({
+    parsed = parseArgs17({
       args,
       allowPositionals: true,
       options: {
@@ -17165,10 +17851,10 @@ async function run15(args) {
     });
   } catch (parseError) {
     const message = parseError instanceof Error ? parseError.message : String(parseError);
-    return fail("USAGE", message, HELP15);
+    return fail("USAGE", message, HELP20);
   }
   if (parsed.values.help) {
-    await writeStdout(HELP15);
+    await writeStdout(HELP20);
     return EXIT.OK;
   }
   if (parsed.values.ts) {
@@ -17178,7 +17864,7 @@ async function run15(args) {
   await respond(JSON_SCHEMA);
   return EXIT.OK;
 }
-var HELP15 = `docx schema \u2014 print the AST type definitions
+var HELP20 = `docx schema \u2014 print the AST type definitions
 
 Usage:
   docx schema [options]
@@ -17275,7 +17961,18 @@ var init_schema = __esm(() => {
               date: { type: "string" },
               revisionId: { type: "string" }
             }
-          }
+          },
+          hyperlink: { $ref: "#/$defs/Hyperlink" }
+        }
+      },
+      Hyperlink: {
+        type: "object",
+        required: ["id"],
+        properties: {
+          id: { type: "string" },
+          url: { type: "string" },
+          anchor: { type: "string" },
+          tooltip: { type: "string" }
         }
       },
       ImageRun: {
@@ -17370,13 +18067,13 @@ var init_schema = __esm(() => {
 // src/cli/info/locators.ts
 var exports_locators = {};
 __export(exports_locators, {
-  run: () => run16
+  run: () => run21
 });
-import { parseArgs as parseArgs14 } from "util";
-async function run16(args) {
+import { parseArgs as parseArgs18 } from "util";
+async function run21(args) {
   let parsed;
   try {
-    parsed = parseArgs14({
+    parsed = parseArgs18({
       args,
       allowPositionals: true,
       options: {
@@ -17386,10 +18083,10 @@ async function run16(args) {
     });
   } catch (parseError) {
     const message = parseError instanceof Error ? parseError.message : String(parseError);
-    return fail("USAGE", message, HELP16);
+    return fail("USAGE", message, HELP21);
   }
   if (parsed.values.help) {
-    await writeStdout(HELP16);
+    await writeStdout(HELP21);
     return EXIT.OK;
   }
   if (parsed.values.json) {
@@ -17400,7 +18097,7 @@ async function run16(args) {
   await writeStdout(REFERENCE);
   return EXIT.OK;
 }
-var HELP16 = `docx locators \u2014 print the locator grammar reference
+var HELP21 = `docx locators \u2014 print the locator grammar reference
 
 Usage:
   docx locators [options]
@@ -17426,6 +18123,7 @@ Range locators (across blocks):
 Entity locators:
   cN              Comment id (e.g., c0)
   imgN            Image id (e.g., img2)
+  linkN           Hyperlink id (e.g., link0)
   tN:rRcC         Cell at row R, column C of table tN
 
 Examples:
@@ -17434,6 +18132,7 @@ Examples:
   p3:5-p5:10      -> from char 5 of p3 to char 10 of p5
   c1              -> comment c1
   img0            -> image img0
+  link0           -> hyperlink link0
   t0:r1c2         -> cell at row 1, col 2 of table t0
   t0:r1c2:p0      -> first paragraph of that cell
   t0:r1c2:p0:5-10 -> chars 5..10 of that paragraph
@@ -17466,6 +18165,7 @@ var init_locators2 = __esm(() => {
     entityLocators: {
       comment: { syntax: "cN", example: "c1" },
       image: { syntax: "imgN", example: "img0" },
+      hyperlink: { syntax: "linkN", example: "link0" },
       cell: { syntax: "tN:rRcC", example: "t0:r1c2" },
       nestedCell: { syntax: "tN:rRcC:pK", example: "t0:r1c2:p0" }
     },
@@ -17480,22 +18180,22 @@ var init_locators2 = __esm(() => {
 // src/cli/info/index.ts
 var exports_info = {};
 __export(exports_info, {
-  run: () => run17
+  run: () => run22
 });
-async function run17(args) {
+async function run22(args) {
   const topic = args[0];
   if (!topic || topic === "--help" || topic === "-h" || topic === "help") {
-    await writeStdout(HELP17);
+    await writeStdout(HELP22);
     return topic ? 0 : 2;
   }
-  const loader = SUBCOMMANDS3[topic];
+  const loader = SUBCOMMANDS4[topic];
   if (!loader) {
     return fail("USAGE", `Unknown info topic: ${topic}`, 'Run "docx info --help".');
   }
   const module_ = await loader();
   return module_.run(args.slice(1));
 }
-var SUBCOMMANDS3, HELP17 = `docx info \u2014 print reference material about the CLI
+var SUBCOMMANDS4, HELP22 = `docx info \u2014 print reference material about the CLI
 
 Usage:
   docx info <topic> [options]
@@ -17508,7 +18208,7 @@ Run "docx info <topic> --help" for topic-specific help.
 `;
 var init_info = __esm(() => {
   init_respond();
-  SUBCOMMANDS3 = {
+  SUBCOMMANDS4 = {
     schema: () => Promise.resolve().then(() => (init_schema(), exports_schema)),
     locators: () => Promise.resolve().then(() => (init_locators2(), exports_locators))
   };
@@ -17517,13 +18217,13 @@ var init_info = __esm(() => {
 // src/cli/insert/index.tsx
 var exports_insert = {};
 __export(exports_insert, {
-  run: () => run18
+  run: () => run23
 });
-import { parseArgs as parseArgs15 } from "util";
-async function run18(args) {
+import { parseArgs as parseArgs19 } from "util";
+async function run23(args) {
   let parsed;
   try {
-    parsed = parseArgs15({
+    parsed = parseArgs19({
       args,
       allowPositionals: true,
       options: {
@@ -17536,6 +18236,7 @@ async function run18(args) {
         color: { type: "string" },
         bold: { type: "boolean" },
         italic: { type: "boolean" },
+        url: { type: "string" },
         output: { type: "string", short: "o" },
         "dry-run": { type: "boolean" },
         help: { type: "boolean", short: "h" }
@@ -17543,30 +18244,34 @@ async function run18(args) {
     });
   } catch (parseError) {
     const message = parseError instanceof Error ? parseError.message : String(parseError);
-    return fail("USAGE", message, HELP18);
+    return fail("USAGE", message, HELP23);
   }
   if (parsed.values.help) {
-    await writeStdout(HELP18);
+    await writeStdout(HELP23);
     return EXIT.OK;
   }
   const path = parsed.positionals[0];
   if (!path)
-    return fail("USAGE", "Missing FILE argument", HELP18);
+    return fail("USAGE", "Missing FILE argument", HELP23);
   const after = parsed.values.after;
   const before = parsed.values.before;
   if (!after && !before) {
-    return fail("USAGE", "Missing locator: pass --after or --before", HELP18);
+    return fail("USAGE", "Missing locator: pass --after or --before", HELP23);
   }
   if (after && before) {
-    return fail("USAGE", "Pass either --after or --before, not both", HELP18);
+    return fail("USAGE", "Pass either --after or --before, not both", HELP23);
   }
   const text = parsed.values.text;
   const runsJson = parsed.values.runs;
+  const url = parsed.values.url;
   if (!text && !runsJson) {
-    return fail("USAGE", "Missing content: pass --text or --runs", HELP18);
+    return fail("USAGE", "Missing content: pass --text or --runs", HELP23);
   }
   if (text && runsJson) {
-    return fail("USAGE", "Pass either --text or --runs, not both", HELP18);
+    return fail("USAGE", "Pass either --text or --runs, not both", HELP23);
+  }
+  if (url && !text) {
+    return fail("USAGE", "--url requires --text", HELP23);
   }
   const paragraphOptions = {};
   const styleValue = parsed.values.style;
@@ -17596,6 +18301,8 @@ async function run18(args) {
       ...parsed.values.bold ? { bold: true } : {},
       ...parsed.values.italic ? { italic: true } : {}
     }, undefined, false, undefined, this);
+    if (url)
+      wrapFirstRunInHyperlink(view, paragraphNode, url);
   } else {
     let runsValue;
     try {
@@ -17644,6 +18351,29 @@ async function run18(args) {
   });
   return EXIT.OK;
 }
+function wrapFirstRunInHyperlink(view, paragraph, url) {
+  const relationships = XmlNode2.findRoot(view.relationshipsTree, "Relationships");
+  if (!relationships) {
+    throw new Error("Missing <Relationships> root in document rels");
+  }
+  const relationshipId = addHyperlinkRelationship(relationships, url);
+  view.hyperlinksByRelationshipId.set(relationshipId, { url });
+  const newChildren = [];
+  let wrapped = false;
+  for (const child of paragraph.children) {
+    if (!wrapped && child.tag === "w:r") {
+      const wrapper = /* @__PURE__ */ jsxDEV(w.hyperlink, {
+        "r:id": relationshipId,
+        children: child
+      }, undefined, false, undefined, this);
+      newChildren.push(wrapper);
+      wrapped = true;
+      continue;
+    }
+    newChildren.push(child);
+  }
+  paragraph.children = newChildren;
+}
 function applyTrackedInsertion(paragraph, view) {
   const allocator = createRevisionAllocator(view);
   const baseMeta = { author: resolveAuthor(), date: resolveDate() };
@@ -17670,58 +18400,197 @@ function applyTrackedInsertion(paragraph, view) {
     flush();
     newChildren.push(child);
   }
-  flush();
-  paragraph.children = newChildren;
-  markParagraphMarkAs(paragraph, "ins", mintMeta());
+  flush();
+  paragraph.children = newChildren;
+  markParagraphMarkAs(paragraph, "ins", mintMeta());
+}
+var HELP23 = `docx insert \u2014 insert a paragraph at a locator
+
+Usage:
+  docx insert FILE [options]
+
+Locator (one required):
+  --after LOCATOR   Insert after the block at LOCATOR (e.g., p3)
+  --before LOCATOR  Insert before the block at LOCATOR
+
+Content (one required):
+  --text TEXT       Insert a paragraph with this text
+  --runs JSON       Insert a paragraph with custom runs (Run[] JSON)
+
+Paragraph options:
+  --style NAME       Apply paragraph style (e.g., Heading1)
+  --alignment ALIGN  left | center | right | justify
+
+Run options (only with --text):
+  --color HEX       Run color, hex (e.g., 800080 for purple)
+  --bold            Bold
+  --italic          Italic
+  --url URL         Wrap the inserted text in a hyperlink to URL
+
+  -o, --output PATH Write to PATH instead of overwriting FILE
+  --dry-run         Print what would be inserted; do not write the file
+  -h, --help        Show this help
+
+Examples:
+  docx insert doc.docx --after p3 --text "Section header" --style Heading2
+  docx insert doc.docx --before p0 --text "ALERT" --color CC0000 --bold
+  docx insert doc.docx --after p2 --runs '[{"type":"text","text":"X","bold":true}]'
+  docx insert doc.docx --after p3 --text "click here" --url https://example.com
+`;
+var init_insert = __esm(() => {
+  init_core();
+  init_jsx();
+  init_parser();
+  init_respond();
+  init_emit2();
+  init_jsx_dev_runtime();
+});
+
+// src/cli/outline/build.ts
+function buildOutline(doc, options = {}) {
+  const stylePrefix = options.stylePrefix ?? "Heading";
+  const root = {
+    id: "",
+    locator: "",
+    level: 0,
+    style: "",
+    text: "",
+    children: []
+  };
+  const stack = [root];
+  for (const paragraph of headingParagraphs(doc.blocks, stylePrefix)) {
+    const level = headingLevel(paragraph.style, stylePrefix);
+    if (level === null)
+      continue;
+    while ((stack[stack.length - 1]?.level ?? 0) >= level)
+      stack.pop();
+    const parent = stack[stack.length - 1] ?? root;
+    const entry = {
+      id: paragraph.id,
+      locator: paragraph.id,
+      level,
+      style: paragraph.style ?? "",
+      text: paragraphText(paragraph),
+      children: []
+    };
+    parent.children.push(entry);
+    stack.push(entry);
+  }
+  return root.children;
+}
+function headingLevel(style, stylePrefix) {
+  if (!style)
+    return null;
+  if (!style.startsWith(stylePrefix))
+    return null;
+  const remainder = style.slice(stylePrefix.length).trim();
+  if (remainder === "")
+    return 1;
+  const parsed = Number(remainder);
+  if (!Number.isInteger(parsed) || parsed < 1)
+    return null;
+  return parsed;
+}
+function* headingParagraphs(blocks, stylePrefix) {
+  for (const block of blocks) {
+    if (block.type !== "paragraph")
+      continue;
+    if (headingLevel(block.style, stylePrefix) === null)
+      continue;
+    yield block;
+  }
+}
+function paragraphText(paragraph) {
+  let out = "";
+  for (const run24 of paragraph.runs) {
+    if (run24.type === "text")
+      out += run24.text;
+  }
+  return out;
+}
+
+// src/cli/outline/index.ts
+var exports_outline = {};
+__export(exports_outline, {
+  run: () => run24
+});
+import { parseArgs as parseArgs20 } from "util";
+async function run24(args) {
+  let parsed;
+  try {
+    parsed = parseArgs20({
+      args,
+      allowPositionals: true,
+      options: {
+        "style-prefix": { type: "string" },
+        help: { type: "boolean", short: "h" }
+      }
+    });
+  } catch (parseError) {
+    const message = parseError instanceof Error ? parseError.message : String(parseError);
+    return fail("USAGE", message, HELP24);
+  }
+  if (parsed.values.help) {
+    await writeStdout(HELP24);
+    return EXIT.OK;
+  }
+  const path = parsed.positionals[0];
+  if (!path)
+    return fail("USAGE", "Missing FILE argument", HELP24);
+  const stylePrefix = parsed.values["style-prefix"] ?? "Heading";
+  if (stylePrefix.length === 0) {
+    return fail("USAGE", "--style-prefix cannot be empty");
+  }
+  const view = await openOrFail(path);
+  if (typeof view === "number")
+    return view;
+  const outline = buildOutline(view.doc, { stylePrefix });
+  await respond({
+    ok: true,
+    operation: "outline",
+    path,
+    stylePrefix,
+    outline
+  });
+  return EXIT.OK;
 }
-var HELP18 = `docx insert \u2014 insert a paragraph at a locator
+var HELP24 = `docx outline \u2014 list headings as a hierarchical tree
 
 Usage:
-  docx insert FILE [options]
-
-Locator (one required):
-  --after LOCATOR   Insert after the block at LOCATOR (e.g., p3)
-  --before LOCATOR  Insert before the block at LOCATOR
-
-Content (one required):
-  --text TEXT       Insert a paragraph with this text
-  --runs JSON       Insert a paragraph with custom runs (Run[] JSON)
+  docx outline FILE [options]
 
-Paragraph options:
-  --style NAME       Apply paragraph style (e.g., Heading1)
-  --alignment ALIGN  left | center | right | justify
+Options:
+  --style-prefix S  paragraph-style prefix that marks a heading (default: "Heading")
+  -h, --help        show this help
 
-Run options (only with --text):
-  --color HEX       Run color, hex (e.g., 800080 for purple)
-  --bold            Bold
-  --italic          Italic
+Walks top-level paragraphs whose style starts with the prefix and parses the
+trailing number as the heading level (e.g. "Heading1" \u2192 1, "Heading 2" \u2192 2).
+Paragraphs nested inside table cells are skipped \u2014 outlines reflect the
+document's structural skeleton, not embedded labels. Lower levels nest under
+higher ones; missing intermediate levels nest directly (H1 \u2192 H3 is fine).
 
-  -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
+Output is JSON: an array of entries, each shaped like
+  { id, locator, level, style, text, children }.
 
 Examples:
-  docx insert doc.docx --after p3 --text "Section header" --style Heading2
-  docx insert doc.docx --before p0 --text "ALERT" --color CC0000 --bold
-  docx insert doc.docx --after p2 --runs '[{"type":"text","text":"X","bold":true}]'
+  docx outline doc.docx
+  docx outline doc.docx --style-prefix "Section"
+  docx outline doc.docx | jq '.outline[].text'
 `;
-var init_insert = __esm(() => {
-  init_core();
+var init_outline = __esm(() => {
   init_respond();
-  init_emit2();
-  init_jsx_dev_runtime();
 });
 
 // src/cli/read/index.ts
 var exports_read = {};
 __export(exports_read, {
-  run: () => run19
+  run: () => run25
 });
-import { parseArgs as parseArgs16 } from "util";
-async function run19(args) {
+import { parseArgs as parseArgs21 } from "util";
+async function run25(args) {
   let parsed;
   try {
-    parsed = parseArgs16({
+    parsed = parseArgs21({
       args,
       allowPositionals: true,
       options: {
@@ -17730,15 +18599,15 @@ async function run19(args) {
       }
     });
   } catch (e) {
-    return fail("USAGE", e instanceof Error ? e.message : String(e), HELP19);
+    return fail("USAGE", e instanceof Error ? e.message : String(e), HELP25);
   }
   if (parsed.values.help) {
-    await writeStdout(HELP19);
+    await writeStdout(HELP25);
     return EXIT.OK;
   }
   const path = parsed.positionals[0];
   if (!path)
-    return fail("USAGE", "Missing FILE argument", HELP19);
+    return fail("USAGE", "Missing FILE argument", HELP25);
   const view = await openOrFail(path);
   if (typeof view === "number")
     return view;
@@ -17746,7 +18615,7 @@ async function run19(args) {
   await respond(view.doc);
   return EXIT.OK;
 }
-var HELP19 = `docx read \u2014 print AST as JSON
+var HELP25 = `docx read \u2014 print AST as JSON
 
 Usage:
   docx read FILE [options]
@@ -17804,7 +18673,7 @@ function collectRunSlots(paragraph) {
       offset += length;
       continue;
     }
-    if (child.tag === "w:ins" || child.tag === "w:del") {
+    if (child.tag === "w:ins" || child.tag === "w:del" || child.tag === "w:hyperlink") {
       for (const inner of child.children) {
         if (inner.tag !== "w:r")
           continue;
@@ -17829,14 +18698,14 @@ function rebuildContainer(container, baseOffset, span, replacement, runPropertie
     if (placed)
       return;
     placed = true;
-    const run20 = /* @__PURE__ */ jsxDEV(ReplacementRun, {
+    const run26 = /* @__PURE__ */ jsxDEV(ReplacementRun, {
       runProperties,
       text: replacement
     }, undefined, false, undefined, this);
     newChildren.push(tracked && isParagraph ? /* @__PURE__ */ jsxDEV(Ins, {
       meta: mintMeta(tracked),
-      children: run20
-    }, undefined, false, undefined, this) : run20);
+      children: run26
+    }, undefined, false, undefined, this) : run26);
   };
   for (const child of container.children) {
     if (child.tag === "w:r") {
@@ -17872,7 +18741,7 @@ function rebuildContainer(container, baseOffset, span, replacement, runPropertie
       }
       continue;
     }
-    if (isParagraph && (child.tag === "w:ins" || child.tag === "w:del")) {
+    if (isParagraph && (child.tag === "w:ins" || child.tag === "w:del" || child.tag === "w:hyperlink")) {
       let innerLength = 0;
       for (const inner of child.children) {
         if (inner.tag === "w:r")
@@ -17896,14 +18765,14 @@ function rebuildAcrossBoundaries(paragraph, span, replacement, runProperties, tr
     if (placed)
       return;
     placed = true;
-    const run20 = /* @__PURE__ */ jsxDEV(ReplacementRun, {
+    const run26 = /* @__PURE__ */ jsxDEV(ReplacementRun, {
       runProperties,
       text: replacement
     }, undefined, false, undefined, this);
     newChildren.push(tracked ? /* @__PURE__ */ jsxDEV(Ins, {
       meta: mintMeta(tracked),
-      children: run20
-    }, undefined, false, undefined, this) : run20);
+      children: run26
+    }, undefined, false, undefined, this) : run26);
   };
   for (const child of paragraph.children) {
     if (child.tag === "w:r") {
@@ -17940,7 +18809,7 @@ function rebuildAcrossBoundaries(paragraph, span, replacement, runProperties, tr
       continue;
     }
     if (child.tag === "w:ins" || child.tag === "w:del") {
-      const innerLength = sumInnerRunLengths(child);
+      const innerLength = sumInnerRunLengths2(child);
       const wrapperStart = offset;
       const wrapperEnd = offset + innerLength;
       offset = wrapperEnd;
@@ -17956,6 +18825,25 @@ function rebuildAcrossBoundaries(paragraph, span, replacement, runProperties, tr
       splitWrapperAcrossSpan(child, wrapperStart, span, tracked, newChildren, placeReplacement);
       continue;
     }
+    if (child.tag === "w:hyperlink") {
+      const innerLength = sumInnerRunLengths2(child);
+      const wrapperStart = offset;
+      const wrapperEnd = offset + innerLength;
+      offset = wrapperEnd;
+      if (wrapperEnd <= span.start) {
+        newChildren.push(child);
+        continue;
+      }
+      if (wrapperStart >= span.end) {
+        placeReplacement();
+        newChildren.push(child);
+        continue;
+      }
+      splitHyperlinkAcrossSpan(child, wrapperStart, span, runProperties, replacement, tracked, newChildren, placeReplacement, () => {
+        placed = true;
+      });
+      continue;
+    }
     newChildren.push(child);
   }
   if (!placed)
@@ -18016,7 +18904,62 @@ function splitWrapperAcrossSpan(wrapper, wrapperStart, span, tracked, out, place
     out.push(postWrapper);
   }
 }
-function sumInnerRunLengths(wrapper) {
+function splitHyperlinkAcrossSpan(wrapper, wrapperStart, span, runProperties, replacement, tracked, out, placeReplacement, markReplacementPlaced) {
+  const wrapperEnd = wrapperStart + wrapper.children.reduce((total, inner) => inner.tag === "w:r" ? total + runTextLength(inner) : total, 0);
+  const startsInside = span.start > wrapperStart && span.start < wrapperEnd;
+  const preInner = [];
+  const postInner = [];
+  let innerOffset = wrapperStart;
+  for (const inner of wrapper.children) {
+    if (inner.tag !== "w:r") {
+      preInner.push(inner);
+      continue;
+    }
+    const length = runTextLength(inner);
+    const runStart = innerOffset;
+    const runEnd = innerOffset + length;
+    innerOffset = runEnd;
+    if (runEnd <= span.start) {
+      preInner.push(inner);
+      continue;
+    }
+    if (runStart >= span.end) {
+      postInner.push(inner);
+      continue;
+    }
+    const sliceStartInRun = Math.max(0, span.start - runStart);
+    const sliceEndInRun = Math.min(length, span.end - runStart);
+    if (sliceStartInRun > 0)
+      preInner.push(sliceRun(inner, 0, sliceStartInRun));
+    if (sliceEndInRun < length) {
+      postInner.push(sliceRun(inner, sliceEndInRun, length));
+    }
+  }
+  if (startsInside) {
+    const innerReplacement = /* @__PURE__ */ jsxDEV(ReplacementRun, {
+      runProperties,
+      text: replacement
+    }, undefined, false, undefined, this);
+    preInner.push(tracked ? /* @__PURE__ */ jsxDEV(Ins, {
+      meta: mintMeta(tracked),
+      children: innerReplacement
+    }, undefined, false, undefined, this) : innerReplacement);
+    markReplacementPlaced();
+  }
+  if (preInner.length > 0) {
+    const preWrapper = new XmlNode2("w:hyperlink", { ...wrapper.attributes });
+    preWrapper.children = preInner;
+    out.push(preWrapper);
+  }
+  if (!startsInside)
+    placeReplacement();
+  if (postInner.length > 0) {
+    const postWrapper = new XmlNode2("w:hyperlink", { ...wrapper.attributes });
+    postWrapper.children = postInner;
+    out.push(postWrapper);
+  }
+}
+function sumInnerRunLengths2(wrapper) {
   let total = 0;
   for (const inner of wrapper.children) {
     if (inner.tag === "w:r")
@@ -18027,8 +18970,8 @@ function sumInnerRunLengths(wrapper) {
 function mintMeta(tracked) {
   return { ...tracked.meta, revisionId: tracked.allocator.next() };
 }
-function convertRunTextToDelText(run20) {
-  for (const child of run20.children) {
+function convertRunTextToDelText(run26) {
+  for (const child of run26.children) {
     if (child.tag === "w:t")
       child.tag = "w:delText";
   }
@@ -18055,15 +18998,15 @@ var init_replace_span = __esm(() => {
 });
 
 // src/cli/replace/index.ts
-var exports_replace2 = {};
-__export(exports_replace2, {
-  run: () => run20
+var exports_replace3 = {};
+__export(exports_replace3, {
+  run: () => run26
 });
-import { parseArgs as parseArgs17 } from "util";
-async function run20(args) {
+import { parseArgs as parseArgs22 } from "util";
+async function run26(args) {
   let parsed;
   try {
-    parsed = parseArgs17({
+    parsed = parseArgs22({
       args,
       allowPositionals: true,
       options: {
@@ -18078,21 +19021,21 @@ async function run20(args) {
     });
   } catch (parseError) {
     const message = parseError instanceof Error ? parseError.message : String(parseError);
-    return fail("USAGE", message, HELP20);
+    return fail("USAGE", message, HELP26);
   }
   if (parsed.values.help) {
-    await writeStdout(HELP20);
+    await writeStdout(HELP26);
     return EXIT.OK;
   }
   const path = parsed.positionals[0];
   const pattern = parsed.positionals[1];
   const replacement = parsed.positionals[2];
   if (!path)
-    return fail("USAGE", "Missing FILE argument", HELP20);
+    return fail("USAGE", "Missing FILE argument", HELP26);
   if (pattern == null)
-    return fail("USAGE", "Missing PATTERN argument", HELP20);
+    return fail("USAGE", "Missing PATTERN argument", HELP26);
   if (replacement == null) {
-    return fail("USAGE", "Missing REPLACEMENT argument", HELP20);
+    return fail("USAGE", "Missing REPLACEMENT argument", HELP26);
   }
   const ignoreCase = Boolean(parsed.values["ignore-case"]);
   const useRegex = Boolean(parsed.values.regex);
@@ -18194,7 +19137,7 @@ async function run20(args) {
   });
   return EXIT.OK;
 }
-var HELP20 = `docx replace \u2014 substitute text spans (sed for docx)
+var HELP26 = `docx replace \u2014 substitute text spans (sed for docx)
 
 Usage:
   docx replace FILE PATTERN REPLACEMENT [options]
@@ -18228,7 +19171,7 @@ Examples:
   docx replace doc.docx "(\\w+) (\\w+)" "$2 $1" --regex --all
   docx replace doc.docx "wordy phrase" "tighter phrase" --all --dry-run
 `;
-var init_replace2 = __esm(() => {
+var init_replace3 = __esm(() => {
   init_core();
   init_respond();
   init_replace_span();
@@ -18237,13 +19180,13 @@ var init_replace2 = __esm(() => {
 // src/cli/track-changes/index.tsx
 var exports_track_changes = {};
 __export(exports_track_changes, {
-  run: () => run21
+  run: () => run27
 });
-import { parseArgs as parseArgs18 } from "util";
-async function run21(args) {
+import { parseArgs as parseArgs23 } from "util";
+async function run27(args) {
   let parsed;
   try {
-    parsed = parseArgs18({
+    parsed = parseArgs23({
       args,
       allowPositionals: true,
       options: {
@@ -18254,18 +19197,18 @@ async function run21(args) {
     });
   } catch (parseError) {
     const message = parseError instanceof Error ? parseError.message : String(parseError);
-    return fail("USAGE", message, HELP21);
+    return fail("USAGE", message, HELP27);
   }
   if (parsed.values.help) {
-    await writeStdout(HELP21);
+    await writeStdout(HELP27);
     return EXIT.OK;
   }
   const path = parsed.positionals[0];
   if (!path)
-    return fail("USAGE", "Missing FILE argument", HELP21);
+    return fail("USAGE", "Missing FILE argument", HELP27);
   const mode = parsed.positionals[1];
   if (mode !== "on" && mode !== "off") {
-    return fail("USAGE", `Expected "on" or "off", got: ${mode ?? "<nothing>"}`, HELP21);
+    return fail("USAGE", `Expected "on" or "off", got: ${mode ?? "<nothing>"}`, HELP27);
   }
   const view = await openOrFail(path);
   if (typeof view === "number")
@@ -18317,7 +19260,7 @@ async function run21(args) {
   });
   return EXIT.OK;
 }
-var HELP21 = `docx track-changes \u2014 toggle the document's tracked-changes mode
+var HELP27 = `docx track-changes \u2014 toggle the document's tracked-changes mode
 
 Usage:
   docx track-changes FILE on|off [options]
@@ -18344,10 +19287,297 @@ var init_track_changes2 = __esm(() => {
   init_respond();
   init_jsx_dev_runtime();
 });
+
+// src/cli/wc/count.ts
+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));
+    } else if (block.type === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          total += countWordsInBlocks(cell.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 clampedEnd = Math.min(Math.max(end, 0), text.length);
+  const clampedStart = Math.min(Math.max(start, 0), clampedEnd);
+  return countWords(text.slice(clampedStart, clampedEnd));
+}
+function countWordsInRange(paragraphsInOrder, startBlockId, startOffset, endBlockId, endOffset) {
+  const startIndex = paragraphsInOrder.findIndex((p) => p.id === startBlockId);
+  const endIndex = paragraphsInOrder.findIndex((p) => p.id === endBlockId);
+  if (startIndex === -1 || endIndex === -1)
+    return 0;
+  if (endIndex < startIndex)
+    return 0;
+  if (startIndex === endIndex) {
+    const paragraph = paragraphsInOrder[startIndex];
+    if (!paragraph)
+      return 0;
+    return countWordsInParagraphSpan(paragraph, startOffset, endOffset);
+  }
+  let total = 0;
+  const first = paragraphsInOrder[startIndex];
+  if (first) {
+    total += countWordsInParagraphSpan(first, startOffset, paragraphText2(first).length);
+  }
+  for (let index = startIndex + 1;index < endIndex; index++) {
+    const middle = paragraphsInOrder[index];
+    if (middle)
+      total += countWords(paragraphText2(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;
+}
+
+// src/cli/wc/index.ts
+var exports_wc = {};
+__export(exports_wc, {
+  run: () => run28
+});
+import { parseArgs as parseArgs24 } from "util";
+async function run28(args) {
+  let parsed;
+  try {
+    parsed = parseArgs24({
+      args,
+      allowPositionals: true,
+      options: {
+        help: { type: "boolean", short: "h" }
+      }
+    });
+  } catch (parseError) {
+    const message = parseError instanceof Error ? parseError.message : String(parseError);
+    return fail("USAGE", message, HELP28);
+  }
+  if (parsed.values.help) {
+    await writeStdout(HELP28);
+    return EXIT.OK;
+  }
+  const path = parsed.positionals[0];
+  const locatorInput = parsed.positionals[1];
+  if (!path)
+    return fail("USAGE", "Missing FILE argument", HELP28);
+  const view = await openOrFail(path);
+  if (typeof view === "number")
+    return view;
+  if (!locatorInput) {
+    await respond({
+      ok: true,
+      operation: "wc",
+      path,
+      scope: "document",
+      words: countWordsInBlocks(view.doc.blocks)
+    });
+    return EXIT.OK;
+  }
+  let locator;
+  try {
+    locator = parseLocator(locatorInput);
+  } catch (error) {
+    if (error instanceof LocatorParseError) {
+      return fail("INVALID_LOCATOR", error.message);
+    }
+    throw error;
+  }
+  if (locator.kind === "comment" || locator.kind === "image") {
+    return fail("USAGE", `Locator ${locatorInput} addresses a ${locator.kind}, not text`, "wc accepts paragraph, span, range, table, and cell locators.");
+  }
+  const blocks = view.doc.blocks;
+  if (locator.kind === "block") {
+    const block = findBlockById(blocks, locator.blockId);
+    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;
+    await respond({
+      ok: true,
+      operation: "wc",
+      path,
+      locator: locatorInput,
+      scope: block.type,
+      words
+    });
+    return EXIT.OK;
+  }
+  if (locator.kind === "blockSpan") {
+    const block = findBlockById(blocks, locator.blockId);
+    if (!block || block.type !== "paragraph") {
+      return fail("BLOCK_NOT_FOUND", `Paragraph not found: ${locator.blockId}`);
+    }
+    await respond({
+      ok: true,
+      operation: "wc",
+      path,
+      locator: locatorInput,
+      scope: "paragraphSpan",
+      words: countWordsInParagraphSpan(block, locator.start, locator.end)
+    });
+    return EXIT.OK;
+  }
+  if (locator.kind === "range") {
+    const paragraphs = flattenParagraphs(blocks);
+    const startExists = paragraphs.some((p) => p.id === locator.start.blockId);
+    const endExists = paragraphs.some((p) => p.id === locator.end.blockId);
+    if (!startExists) {
+      return fail("BLOCK_NOT_FOUND", `Paragraph not found: ${locator.start.blockId}`);
+    }
+    if (!endExists) {
+      return fail("BLOCK_NOT_FOUND", `Paragraph not found: ${locator.end.blockId}`);
+    }
+    await respond({
+      ok: true,
+      operation: "wc",
+      path,
+      locator: locatorInput,
+      scope: "range",
+      words: countWordsInRange(paragraphs, locator.start.blockId, locator.start.offset, locator.end.blockId, locator.end.offset)
+    });
+    return EXIT.OK;
+  }
+  if (locator.kind === "cell") {
+    const cellPath = `${locator.tableId}:r${locator.row}c${locator.col}`;
+    if (!locator.inner) {
+      const cellBlocks = findCellBlocks(blocks, locator);
+      if (!cellBlocks) {
+        return fail("BLOCK_NOT_FOUND", `Cell not found: ${cellPath}`);
+      }
+      await respond({
+        ok: true,
+        operation: "wc",
+        path,
+        locator: locatorInput,
+        scope: "cell",
+        words: countWordsInBlocks(cellBlocks)
+      });
+      return EXIT.OK;
+    }
+    const innerBlockId = locator.inner.kind === "block" ? locator.inner.blockId : locator.inner.kind === "blockSpan" ? locator.inner.blockId : null;
+    if (!innerBlockId) {
+      return fail("USAGE", `Unsupported inner locator for cell: ${locatorInput}`, "Inside a cell, wc accepts pK or pK:S-E only.");
+    }
+    const composedId = `${cellPath}:${innerBlockId}`;
+    const block = findBlockById(blocks, composedId);
+    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));
+    await respond({
+      ok: true,
+      operation: "wc",
+      path,
+      locator: locatorInput,
+      scope: locator.inner.kind === "blockSpan" ? "paragraphSpan" : "paragraph",
+      words
+    });
+    return EXIT.OK;
+  }
+  return fail("USAGE", `Unsupported locator: ${locatorInput}`);
+}
+function findCellBlocks(blocks, locator) {
+  const block = findBlockById(blocks, locator.tableId);
+  if (!block || block.type !== "table")
+    return null;
+  const row = block.rows[locator.row];
+  if (!row)
+    return null;
+  const cell = row.cells[locator.col];
+  if (!cell)
+    return null;
+  return cell.blocks;
+}
+var HELP28 = `docx wc \u2014 count words in a document or a locator-addressed slice
+
+Usage:
+  docx wc FILE [LOCATOR] [options]
+
+Locators (optional; default: whole document):
+  pN              whole paragraph N
+  pN:S-E          chars S..E within paragraph N
+  pN:S-pM:E       cross-paragraph range
+  tN              whole table
+  tN:rRcC         whole cell
+  tN:rRcC:pK      paragraph K inside that cell
+  tN:rRcC:pK:S-E  span within a cell paragraph
+
+Options:
+  -h, --help        show this help
+
+Counting is whitespace-segmented (\\S+) over the joined paragraph text. Hidden
+content like images/breaks/tabs contributes no words. Tracked-change deletions
+are counted alongside insertions because their characters are still part of the
+on-disk text; accept or reject changes first if you need a delta on the
+"accepted" view.
+
+Examples:
+  docx wc doc.docx
+  docx wc doc.docx p3
+  docx wc doc.docx p3:0-120
+  docx wc doc.docx p5:10-p9:42
+  docx wc doc.docx t0:r1c0
+`;
+var init_wc = __esm(() => {
+  init_core();
+  init_respond();
+});
 // package.json
 var package_default = {
   name: "bun-docx",
-  version: "0.3.0",
+  version: "0.5.0",
   description: "CLI for AI agents (Claude, Codex) to read, edit, and comment on .docx files with full format fidelity.",
   keywords: [
     "docx",
@@ -18422,8 +19652,11 @@ Commands:
   delete    FILE  Remove a block or run range
   find      FILE QUERY  Find text spans, return locators
   replace   FILE PATTERN REPL  Substitute text spans (sed for docx)
+  wc        FILE [LOCATOR]  Count words in the doc or a slice
+  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
   track-changes FILE on|off  Toggle tracked-changes mode
   info      \u2026     Reference material (schema, locators)
 
@@ -18450,12 +19683,15 @@ var COMMANDS = {
   delete: () => Promise.resolve().then(() => (init_delete2(), exports_delete2)),
   edit: () => Promise.resolve().then(() => (init_edit(), exports_edit)),
   find: () => Promise.resolve().then(() => (init_find(), exports_find)),
+  hyperlinks: () => Promise.resolve().then(() => (init_hyperlinks(), exports_hyperlinks)),
   images: () => Promise.resolve().then(() => (init_images(), exports_images)),
   info: () => Promise.resolve().then(() => (init_info(), exports_info)),
   insert: () => Promise.resolve().then(() => (init_insert(), exports_insert)),
+  outline: () => Promise.resolve().then(() => (init_outline(), exports_outline)),
   read: () => Promise.resolve().then(() => (init_read2(), exports_read)),
-  replace: () => Promise.resolve().then(() => (init_replace2(), exports_replace2)),
-  "track-changes": () => Promise.resolve().then(() => (init_track_changes2(), exports_track_changes))
+  replace: () => Promise.resolve().then(() => (init_replace3(), exports_replace3)),
+  "track-changes": () => Promise.resolve().then(() => (init_track_changes2(), exports_track_changes)),
+  wc: () => Promise.resolve().then(() => (init_wc(), exports_wc))
 };
 async function main(argv) {
   const args = argv.slice(2);