bun-docx 0.20.3 → 0.20.4

package/README.md

@@ -246,9 +246,16 @@ docx styles set-default-font FILE "Font Name" [--size N] [--all]   # document-wi
 docx replace FILE PATTERN REPLACEMENT [--at pN] [--regex] [--ignore-case] [--all] [--limit N] [--current | --baseline] [--exact] [--track] [--dry-run]
 #   Keeps the run's formatting (bold/font) and any tabs — the no-rebuild way to fill a
 #   formatted/tabbed template line (e.g. "**Org Name**⇥Date"); don't hand-build --runs to refill it.
+#   A TAB matches as one character (pattern "City State Zip" fills a tab-separated line), and
+#   TAB/NBSP/bullet-glyph variants match their plain equivalents unless --exact.
 #   --at pN (or a cell paragraph tT:rRcC:pN) CONFINES the replace to one paragraph — use it when the
 #   SAME placeholder repeats across the doc (a résumé's "City, State" in every entry) and you want THE
 #   one in a specific paragraph, instead of find → edit --at pN:S-E span surgery. Batch entries take "at" too.
+#   MULTI-LINE (editor-style): "\n" in PATTERN matches a line break OR a paragraph boundary
+#   (consecutive paragraphs in the body or one table cell; never across a table/section break/cell wall); the REPLACEMENT's own
+#   "\n"s then define the result — single-line replacement MERGES the paragraphs (first one's
+#   formatting governs), "\n" in the replacement inserts a paragraph mark (splits). Untracked
+#   only: refuses under tracking rather than skip the journal. Block ids shift; re-read after.
 
 # Batch — apply many changes from ONE read (no re-reading between edits). Keys
 # on each JSONL line mirror the command's flags; all locators address the doc as

package/dist/index.js

@@ -4513,8 +4513,8 @@ function runTextLength(run) {
   for (const child of run.children) {
     if (child.tag === "w:t" || child.tag === "w:delText") {
       total += child.collectText().length;
-    } else if (SINGLE_CHAR_TAGS.has(child.tag)) {
-      total += 1;
+    } else {
+      total += inlineMarkerWidth(child);
     }
   }
   return total;
@@ -4539,7 +4539,7 @@ function sliceRun(run, start, end) {
       offset += text.length;
       continue;
     }
-    if (SINGLE_CHAR_TAGS.has(child.tag)) {
+    if (inlineMarkerWidth(child) === 1) {
       if (offset >= start && offset < end) {
         sliced.children.push(child.clone());
       }
@@ -4552,6 +4552,23 @@ function sliceRun(run, start, end) {
   }
   return sliced;
 }
+function inlineMarkerWidth(child) {
+  switch (child.tag) {
+    case "w:noBreakHyphen":
+    case "w:softHyphen":
+    case "w:sym":
+    case "w:tab":
+    case "w:ptab":
+    case "w:cr":
+      return 1;
+    case "w:br": {
+      const type = child.getAttribute("w:type");
+      return type === "page" || type === "column" ? 0 : 1;
+    }
+    default:
+      return 0;
+  }
+}
 function isRunBearingWrapper(tag) {
   return RUN_BEARING_WRAPPER_TAGS.has(tag);
 }
@@ -4595,10 +4612,9 @@ function collectInnerRuns(wrapper, out) {
     }
   }
 }
-var SINGLE_CHAR_TAGS, RUN_BEARING_WRAPPER_TAGS;
+var RUN_BEARING_WRAPPER_TAGS;
 var init_run_ops = __esm(() => {
   init_xml_node();
-  SINGLE_CHAR_TAGS = new Set(["w:noBreakHyphen", "w:softHyphen", "w:sym"]);
   RUN_BEARING_WRAPPER_TAGS = new Set([
     "w:ins",
     "w:del",
@@ -22986,12 +23002,18 @@ function readRun(document2, node, activeComments, trackedChange, hyperlink, stat
     if (child2.tag === "w:br" || child2.tag === "w:cr") {
       flushText();
       const kind = child2.tag === "w:cr" ? "line" : child2.getAttribute("w:type") ?? "line";
-      out.push({ type: "break", kind });
+      const breakRun = { type: "break", kind };
+      if (trackedChange)
+        breakRun.trackedChange = trackedChange;
+      out.push(breakRun);
       continue;
     }
     if (child2.tag === "w:tab" || child2.tag === "w:ptab") {
       flushText();
-      out.push({ type: "tab" });
+      const tabRun = { type: "tab" };
+      if (trackedChange)
+        tabRun.trackedChange = trackedChange;
+      out.push(tabRun);
       continue;
     }
     if (child2.tag === "w:footnoteReference") {
@@ -34790,7 +34812,7 @@ var init_forms = __esm(() => {
     crossSpan: {
       syntax: "pN:S-pM:E",
       example: "p3:5-p5:10",
-      summary: "from char S of paragraph N to char E of paragraph M"
+      summary: "from char S of paragraph N to char E of paragraph M (cell paragraphs too \u2014 tN:rRcC:pA:S-tN:rRcC:pB:E, same cell)"
     },
     cell: {
       syntax: "tN:rRcC",
@@ -34883,6 +34905,21 @@ function parseLocator(input) {
   if (endnoteMatch) {
     return { kind: "endnote", endnoteId: `en${endnoteMatch[1]}` };
   }
+  const rangeMatch = trimmed.match(RANGE_RE);
+  if (rangeMatch) {
+    const [, startBlock, startCapture, endBlock, endCapture] = rangeMatch;
+    if (startBlock && endBlock && cellPrefixOf(startBlock) !== cellPrefixOf(endBlock)) {
+      throw new LocatorParseError(input, "range endpoints must share a container \u2014 both body paragraphs, or paragraphs of the SAME table cell");
+    }
+    const startOffset = Number(startCapture);
+    const endOffset = Number(endCapture);
+    validateOffsets(input, startOffset, endOffset, startBlock !== endBlock);
+    return {
+      kind: "range",
+      start: { blockId: startBlock ?? "", offset: startOffset },
+      end: { blockId: endBlock ?? "", offset: endOffset }
+    };
+  }
   const cellRangeMatch = trimmed.match(CELL_RANGE_RE);
   if (cellRangeMatch) {
     const [, tableIndex, startRow, startCol, endRow, endCol] = cellRangeMatch;
@@ -34924,18 +34961,6 @@ function parseLocator(input) {
       col: Number(columnIndex)
     };
   }
-  const rangeMatch = trimmed.match(RANGE_RE);
-  if (rangeMatch) {
-    const [, startBlock, startCapture, endBlock, endCapture] = rangeMatch;
-    const startOffset = Number(startCapture);
-    const endOffset = Number(endCapture);
-    validateOffsets(input, startOffset, endOffset, startBlock !== endBlock);
-    return {
-      kind: "range",
-      start: { blockId: `p${startBlock}`, offset: startOffset },
-      end: { blockId: `p${endBlock}`, offset: endOffset }
-    };
-  }
   const blockRangeMatch = trimmed.match(BLOCK_RANGE_RE);
   if (blockRangeMatch) {
     const [, startIndex, endIndex] = blockRangeMatch;
@@ -34965,6 +34990,10 @@ function parseLocator(input) {
   }
   throw new LocatorParseError(input, "unrecognized syntax");
 }
+function cellPrefixOf(blockId) {
+  const lastColon = blockId.lastIndexOf(":");
+  return lastColon === -1 ? "" : blockId.slice(0, lastColon);
+}
 function validateOffsets(input, start, end, crossBlock) {
   if (start < 0 || end < 0) {
     throw new LocatorParseError(input, "offsets must be non-negative");
@@ -34985,7 +35014,7 @@ var init_parse = __esm(() => {
   };
   BLOCK_RE = /^(p|t|s)(\d+)$/;
   SPAN_RE = /^p(\d+):(\d+)-(\d+)$/;
-  RANGE_RE = /^p(\d+):(\d+)-p(\d+):(\d+)$/;
+  RANGE_RE = /^((?:t\d+:r\d+c\d+:)?p\d+):(\d+)-((?:t\d+:r\d+c\d+:)?p\d+):(\d+)$/;
   BLOCK_RANGE_RE = /^p(\d+)-p(\d+)$/;
   COMMENT_RE = /^c(\d+)$/;
   IMAGE_RE = /^img(\d+)$/;
@@ -50155,10 +50184,7 @@ function replaceSpanInParagraph(paragraph, span, replacement, tracked, view = "a
   const overlapping = slots.filter((slot) => slot.offsetBefore + slot.length > span.start && slot.offsetBefore < span.end);
   const firstSlot = overlapping[0];
   if (!firstSlot) {
-    paragraph.children.push(/* @__PURE__ */ jsxDEV(ReplacementRun, {
-      runProperties: null,
-      text: replacement
-    }, undefined, false, undefined, this));
+    paragraph.children.push(...replacementRuns(null, replacement));
     return;
   }
   const inheritedProperties = firstSlot.run.findChild("w:rPr")?.clone() ?? null;
@@ -50203,14 +50229,15 @@ function rebuildContainer(container, baseOffset, span, replacement, runPropertie
     if (placed)
       return;
     placed = true;
-    const run = /* @__PURE__ */ jsxDEV(ReplacementRun, {
-      runProperties,
-      text: replacement
-    }, undefined, false, undefined, this);
-    newChildren.push(tracked && isParagraph ? /* @__PURE__ */ jsxDEV(Ins, {
-      meta: mintMeta(tracked),
-      children: run
-    }, undefined, false, undefined, this) : run);
+    const runs = replacementRuns(runProperties, replacement);
+    if (tracked && isParagraph) {
+      newChildren.push(/* @__PURE__ */ jsxDEV(Ins, {
+        meta: mintMeta(tracked),
+        children: runs
+      }, undefined, false, undefined, this));
+      return;
+    }
+    newChildren.push(...runs);
   };
   for (const child2 of container.children) {
     if (child2.tag === "w:r") {
@@ -50265,14 +50292,15 @@ function rebuildAcrossBoundaries(paragraph, span, replacement, runProperties, tr
     if (placed)
       return;
     placed = true;
-    const run = /* @__PURE__ */ jsxDEV(ReplacementRun, {
-      runProperties,
-      text: replacement
-    }, undefined, false, undefined, this);
-    newChildren.push(tracked ? /* @__PURE__ */ jsxDEV(Ins, {
-      meta: mintMeta(tracked),
-      children: run
-    }, undefined, false, undefined, this) : run);
+    const runs = replacementRuns(runProperties, replacement);
+    if (tracked) {
+      newChildren.push(/* @__PURE__ */ jsxDEV(Ins, {
+        meta: mintMeta(tracked),
+        children: runs
+      }, undefined, false, undefined, this));
+      return;
+    }
+    newChildren.push(...runs);
   };
   for (const child2 of paragraph.children) {
     if (child2.tag === "w:r") {
@@ -50497,14 +50525,15 @@ function splitHyperlinkAcrossSpan(wrapper, wrapperStart, span, runProperties, re
     }
   }
   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);
+    const innerRuns = replacementRuns(runProperties, replacement);
+    if (tracked) {
+      preInner.push(/* @__PURE__ */ jsxDEV(Ins, {
+        meta: mintMeta(tracked),
+        children: innerRuns
+      }, undefined, false, undefined, this));
+    } else {
+      preInner.push(...innerRuns);
+    }
     markReplacementPlaced();
   }
   if (preInner.length > 0) {
@@ -50529,48 +50558,318 @@ function convertRunTextToDelText(run) {
       child2.tag = "w:delText";
   }
 }
-function ReplacementRun({
-  runProperties,
-  text: text2
-}) {
-  return /* @__PURE__ */ jsxDEV(w.r, {
+function replacementRuns(runProperties, text2) {
+  if (text2.length === 0) {
+    return [
+      /* @__PURE__ */ jsxDEV(w.r, {
+        children: [
+          runProperties,
+          /* @__PURE__ */ jsxDEV(w.t, {
+            "xml:space": "preserve"
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this)
+    ];
+  }
+  const runs = textToRunElements(text2);
+  for (const run of runs) {
+    if (runProperties)
+      run.children.unshift(runProperties.clone());
+  }
+  return runs;
+}
+var init_replace_span = __esm(() => {
+  init_blocks();
+  init_jsx();
+  init_parser();
+  init_emit2();
+  init_jsx_dev_runtime();
+});
+
+// src/core/find/replace-across.tsx
+function replaceAcrossParagraphs(body, match, replacement, view = "accepted") {
+  const startRef = body.resolveBlock(match.startBlockId);
+  const endRef = body.resolveBlock(match.endBlockId);
+  const { parent, startIndex, endIndex } = body.resolveBlockRange(match.startBlockId, match.endBlockId);
+  const sameNode = startRef.node === endRef.node;
+  const segments = replacement.split(/\r\n|\n/);
+  let head;
+  let tail;
+  let cut;
+  if (sameNode) {
+    const endSplit = splitChildrenAt(startRef.node.children, match.endOffset, view);
+    const startSplit = splitChildrenAt(endSplit.before, match.startOffset, view);
+    head = startSplit.before;
+    tail = endSplit.after;
+    cut = startSplit.after;
+  } else {
+    const startSplit = splitChildrenAt(startRef.node.children, match.startOffset, view);
+    const endSplit = splitChildrenAt(endRef.node.children, match.endOffset, view);
+    head = startSplit.before;
+    tail = endSplit.after;
+    cut = [
+      ...startSplit.after,
+      ...endSplit.before.filter((child2) => child2.tag !== "w:pPr")
+    ];
+  }
+  const inherited = firstVisibleRun(cut, view)?.findChild("w:rPr")?.clone() ?? null;
+  const salvaged = salvageNonContent(cut, view);
+  const segmentRuns = (segment) => segment.length === 0 ? [] : replacementRuns(inherited, segment);
+  const firstSegment = segments[0] ?? "";
+  const startChildren = [...head, ...segmentRuns(firstSegment), ...salvaged];
+  if (segments.length === 1) {
+    startRef.node.children = [...startChildren, ...tail];
+    parent.splice(startIndex + 1, endIndex - startIndex);
+    return;
+  }
+  startRef.node.children = startChildren;
+  const template = paragraphPropertiesTemplate(startRef.node);
+  const middle = segments.slice(1, -1).map((segment) => buildParagraph(template?.clone() ?? null, segmentRuns(segment)));
+  const lastSegment = segments[segments.length - 1] ?? "";
+  if (sameNode) {
+    const finalParagraph = buildParagraph(template?.clone() ?? null, [
+      ...segmentRuns(lastSegment),
+      ...tail
+    ]);
+    parent.splice(startIndex + 1, 0, ...middle, finalParagraph);
+    return;
+  }
+  const endProperties = endRef.node.findChild("w:pPr");
+  endRef.node.children = [
+    ...endProperties ? [endProperties] : [],
+    ...segmentRuns(lastSegment),
+    ...tail
+  ];
+  parent.splice(startIndex + 1, endIndex - startIndex - 1, ...middle);
+}
+function splitChildrenAt(children, offset2, view) {
+  const before = [];
+  const after = [];
+  let cursor = 0;
+  for (const child2 of children) {
+    if (child2.tag === "w:pPr") {
+      before.push(child2);
+      continue;
+    }
+    if (child2.tag === "w:r") {
+      const length = runTextLength(child2);
+      if (cursor + length <= offset2) {
+        before.push(child2);
+      } else if (cursor >= offset2) {
+        after.push(child2);
+      } else {
+        before.push(sliceRun(child2, 0, offset2 - cursor));
+        after.push(sliceRun(child2, offset2 - cursor, length));
+      }
+      cursor += length;
+      continue;
+    }
+    if (isRunBearingWrapper(child2.tag) && isWrapperVisibleInView2(child2.tag, view)) {
+      const length = sumVisibleTextLength2(child2.children, view);
+      if (cursor + length <= offset2) {
+        before.push(child2);
+      } else if (cursor >= offset2) {
+        after.push(child2);
+      } else {
+        const inner2 = splitChildrenAt(child2.children, offset2 - cursor, view);
+        if (inner2.before.length > 0) {
+          const preWrapper = new XmlNode2(child2.tag, { ...child2.attributes });
+          preWrapper.children = inner2.before;
+          before.push(preWrapper);
+        }
+        if (inner2.after.length > 0) {
+          const postWrapper = new XmlNode2(child2.tag, { ...child2.attributes });
+          postWrapper.children = inner2.after;
+          after.push(postWrapper);
+        }
+      }
+      cursor += length;
+      continue;
+    }
+    (cursor < offset2 ? before : after).push(child2);
+  }
+  return { before, after };
+}
+function firstVisibleRun(children, view) {
+  for (const child2 of children) {
+    if (child2.tag === "w:r")
+      return child2;
+    if (isRunBearingWrapper(child2.tag) && isWrapperVisibleInView2(child2.tag, view)) {
+      const nested = firstVisibleRun(child2.children, view);
+      if (nested)
+        return nested;
+    }
+  }
+  return null;
+}
+function salvageNonContent(children, view) {
+  const out = [];
+  for (const child2 of children) {
+    if (child2.tag === "w:r" || child2.tag === "w:pPr")
+      continue;
+    if (isRunBearingWrapper(child2.tag)) {
+      if (isWrapperVisibleInView2(child2.tag, view)) {
+        out.push(...salvageNonContent(child2.children, view));
+      } else {
+        out.push(child2);
+      }
+      continue;
+    }
+    out.push(child2);
+  }
+  return out;
+}
+function paragraphPropertiesTemplate(paragraph) {
+  const source2 = paragraph.findChild("w:pPr");
+  if (!source2)
+    return null;
+  const clone = source2.clone();
+  clone.children = clone.children.filter((child2) => child2.tag !== "w:sectPr");
+  const markProperties = clone.findChild("w:rPr");
+  if (markProperties) {
+    markProperties.children = markProperties.children.filter((child2) => child2.tag !== "w:ins" && child2.tag !== "w:del");
+  }
+  return clone;
+}
+function buildParagraph(paragraphProperties, runs) {
+  return /* @__PURE__ */ jsxDEV(w.p, {
     children: [
-      runProperties,
-      /* @__PURE__ */ jsxDEV(w.t, {
-        "xml:space": "preserve",
-        children: text2
-      }, undefined, false, undefined, this)
+      paragraphProperties,
+      runs
     ]
   }, undefined, true, undefined, this);
 }
-var init_replace_span = __esm(() => {
+var init_replace_across = __esm(() => {
   init_jsx();
   init_parser();
-  init_emit2();
+  init_replace_span();
   init_jsx_dev_runtime();
 });
 
 // src/core/find/index.ts
 function findTextSpans(doc, query, options = {}) {
   const view = options.view ?? "accepted";
-  const exact = options.exact ?? false;
-  const useRegex = options.regex ?? false;
-  let effectiveQuery = query;
-  const applied = [];
-  if (!useRegex && !exact) {
-    const norm = normalizeQuery(query);
-    effectiveQuery = norm.normalized;
-    applied.push(...norm.applied);
-  }
-  const matcher = useRegex ? regexMatcher(query, options.ignoreCase ?? false) : literalMatcher(effectiveQuery, options.ignoreCase ?? false, !exact);
+  const { matcher, ...normalization } = buildMatcher(query, options);
   const out = [];
   collectMatches(doc.blocks, matcher, view, out);
-  const result = { matches: out };
-  if (applied.length > 0) {
-    result.normalizedQuery = effectiveQuery;
-    result.normalizationApplied = applied;
+  return { matches: out, ...normalization };
+}
+function buildMatcher(query, options) {
+  const ignoreCase = options.ignoreCase ?? false;
+  if (options.regex)
+    return { matcher: regexMatcher(query, ignoreCase) };
+  if (options.exact) {
+    return { matcher: literalMatcher(query, ignoreCase, false) };
+  }
+  const { normalized, applied } = normalizeQuery(query);
+  const matcher = literalMatcher(normalized, ignoreCase, true);
+  if (applied.length === 0)
+    return { matcher };
+  return {
+    matcher,
+    normalizedQuery: normalized,
+    normalizationApplied: applied
+  };
+}
+function findAcrossParagraphs(doc, query, options = {}) {
+  const view = options.view ?? "accepted";
+  const { matcher, ...normalization } = buildMatcher(query, options);
+  const out = [];
+  for (const group of consecutiveParagraphGroups(doc.blocks)) {
+    const entries = [];
+    let flat = "";
+    for (const paragraph of group) {
+      const text2 = paragraphTextForView(paragraph, view);
+      entries.push({
+        blockId: paragraph.id,
+        flatStart: flat.length,
+        length: text2.length
+      });
+      flat += `${text2}
+`;
+    }
+    flat = flat.slice(0, -1);
+    let entryCursor = 0;
+    for (const span of matcher(flat)) {
+      const start = mapFlatOffset(span.start, entries, entryCursor);
+      const end = mapFlatOffset(span.end, entries, start.entryIndex);
+      entryCursor = end.entryIndex;
+      out.push({
+        startBlockId: start.blockId,
+        startOffset: start.local,
+        endBlockId: end.blockId,
+        endOffset: end.local,
+        text: span.text
+      });
+    }
   }
-  return result;
+  return { matches: out, ...normalization };
+}
+function consecutiveParagraphGroups(blocks) {
+  const groups = [];
+  let current = [];
+  const flush = () => {
+    if (current.length > 0) {
+      groups.push(current);
+      current = [];
+    }
+  };
+  for (const block of blocks) {
+    if (block.type === "paragraph") {
+      current.push(block);
+      continue;
+    }
+    flush();
+    if (block.type === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          groups.push(...consecutiveParagraphGroups(cell.blocks));
+        }
+      }
+    }
+  }
+  flush();
+  return groups;
+}
+function mapFlatOffset(offset2, entries, fromIndex) {
+  for (let index = fromIndex;index < entries.length; index++) {
+    const entry = entries[index];
+    if (entry && offset2 <= entry.flatStart + entry.length) {
+      return {
+        blockId: entry.blockId,
+        local: Math.max(0, offset2 - entry.flatStart),
+        entryIndex: index
+      };
+    }
+  }
+  throw new Error(`mapFlatOffset: offset ${offset2} out of range`);
+}
+function applyAcrossReplace(doc, spec, { dryRun = false } = {}) {
+  const { matches, ...normalization } = findAcrossParagraphs(doc, spec.pattern, {
+    regex: spec.regex,
+    ignoreCase: spec.ignoreCase,
+    view: spec.view,
+    exact: spec.exact
+  });
+  const replaced = selectMatches(matches, spec);
+  if (!dryRun) {
+    const expand = replacementExpander(spec);
+    for (const match of [...replaced].reverse()) {
+      replaceAcrossParagraphs(doc, match, expand(match.text), spec.view);
+    }
+  }
+  return { totalMatches: matches.length, replaced, ...normalization };
+}
+function selectMatches(matches, options) {
+  if (options.limit !== undefined)
+    return matches.slice(0, options.limit);
+  return options.all ? matches : matches.slice(0, 1);
+}
+function replacementExpander(spec) {
+  if (!spec.regex)
+    return () => spec.replacement;
+  const regex = new RegExp(spec.pattern, spec.ignoreCase ? "i" : "");
+  return (matchText) => matchText.replace(regex, spec.replacement);
 }
 function findFormattedSpans(doc, filter, view = "accepted") {
   const out = [];
@@ -50590,6 +50889,7 @@ function findFormattedSpans(doc, filter, view = "accepted") {
     for (const run of block.runs) {
       if (run.type !== "text") {
         flush(offset2);
+        offset2 += runViewText(run, view).length;
         continue;
       }
       if (!isRunVisibleInView(run.trackedChange?.kind, view))
@@ -50694,15 +50994,23 @@ function collectMatches(blocks, matcher, view, out) {
 }
 function paragraphTextForView(paragraph, view) {
   let out = "";
-  for (const run of paragraph.runs) {
-    if (run.type !== "text")
-      continue;
-    if (!isRunVisibleInView(run.trackedChange?.kind, view))
-      continue;
-    out += run.text;
-  }
+  for (const run of paragraph.runs)
+    out += runViewText(run, view);
   return out;
 }
+function runViewText(run, view) {
+  if (run.type === "text") {
+    return isRunVisibleInView(run.trackedChange?.kind, view) ? run.text : "";
+  }
+  if (run.type === "tab") {
+    return isRunVisibleInView(run.trackedChange?.kind, view) ? "\t" : "";
+  }
+  if (run.type === "break") {
+    return run.kind === "line" && isRunVisibleInView(run.trackedChange?.kind, view) ? `
+` : "";
+  }
+  return "";
+}
 function isRunVisibleInView(kind, view) {
   if (view === "current")
     return true;
@@ -50728,10 +51036,20 @@ function normalizeQuery(query) {
     applied.push("dashes");
     result = dashNormalized;
   }
+  const whitespaceNormalized = normalizeWhitespace(result);
+  if (whitespaceNormalized !== result) {
+    applied.push("whitespace");
+    result = whitespaceNormalized;
+  }
+  const bulletNormalized = normalizeBullets(result);
+  if (bulletNormalized !== result) {
+    applied.push("bullets");
+    result = bulletNormalized;
+  }
   return { normalized: result, applied };
 }
 function normalizeHaystack(text2) {
-  return normalizeDashes(normalizeQuotes(text2));
+  return normalizeBullets(normalizeWhitespace(normalizeDashes(normalizeQuotes(text2))));
 }
 function normalizeQuotes(text2) {
   return text2.replace(/[\u2018\u2019]/g, "'").replace(/[\u201C\u201D]/g, '"');
@@ -50739,6 +51057,12 @@ function normalizeQuotes(text2) {
 function normalizeDashes(text2) {
   return text2.replace(/[\u2013\u2014]/g, "-");
 }
+function normalizeWhitespace(text2) {
+  return text2.replace(/[\t\u00a0\u1680\u2000-\u200a\u202f\u205f\u3000]/g, " ");
+}
+function normalizeBullets(text2) {
+  return text2.replace(/[\u00B7\u2022\u2023\u2219\u25AA\u25E6]/g, "\u2022");
+}
 function stripBalancedMarkdownEmphasis(text2) {
   const patterns = [
     /\*\*(\S(?:.*?\S)?)\*\*/g,
@@ -50758,17 +51082,15 @@ function trackedChangesOverlapping(paragraph, start, end, view) {
   const out = [];
   let offset2 = 0;
   for (const run of paragraph.runs) {
-    if (run.type !== "text")
-      continue;
-    if (!isRunVisibleInView(run.trackedChange?.kind, view))
+    const length = runViewText(run, view).length;
+    if (length === 0)
       continue;
-    const length = run.text.length;
     const runStart = offset2;
     const runEnd = offset2 + length;
     offset2 = runEnd;
     if (runEnd <= start || runStart >= end)
       continue;
-    const change = run.trackedChange;
+    const change = run.type === "text" || run.type === "tab" || run.type === "break" ? run.trackedChange : undefined;
     if (!change)
       continue;
     if (seen.has(change.id))
@@ -50780,6 +51102,7 @@ function trackedChangesOverlapping(paragraph, start, end, view) {
 }
 var init_find = __esm(() => {
   init_body();
+  init_replace_across();
   init_replace_span();
 });
 
@@ -83138,6 +83461,15 @@ function invalidLineSpacing(raw) {
     hint: "Use a multiple (1, 1.5, 2), a name (single, double), or an exact point value (e.g. 15pt, or '15pt atLeast')."
   };
 }
+function spanLocator(match) {
+  if ("blockId" in match) {
+    return `${match.blockId}:${match.start}-${match.end}`;
+  }
+  if (match.startBlockId === match.endBlockId) {
+    return `${match.startBlockId}:${match.startOffset}-${match.endOffset}`;
+  }
+  return `${match.startBlockId}:${match.startOffset}-${match.endBlockId}:${match.endOffset}`;
+}
 var PAGE_SIZES, RUN_FORMAT_FLAGS, TWIPS_PER_POINT = 20, TWIPS_PER_INCH = 1440, LINE_UNITS_PER_MULTIPLE = 240;
 var init_parse_helpers = __esm(() => {
   init_core2();
@@ -87186,7 +87518,7 @@ async function run15(args) {
     return EXIT2.OK;
   }
   const path2 = parsed.positionals[0];
-  const query = parsed.positionals[1];
+  const query = decodeInlineEscapes(parsed.positionals[1]);
   if (!path2)
     return fail("USAGE", "Missing FILE argument", HELP11);
   const formatFilter = {};
@@ -87222,56 +87554,63 @@ async function run15(args) {
   const document4 = await openOrFail(path2);
   if (typeof document4 === "number")
     return document4;
-  let result = { matches: [] };
-  if (hasFormatFilter) {
-    result = {
-      matches: findFormattedSpans(document4.body, formatFilter, findView)
-    };
-  } else if (query != null) {
-    try {
-      result = findTextSpans(document4.body, query, {
+  let matches = [];
+  let normalizationFields = {};
+  try {
+    if (query?.includes(`
+`)) {
+      const result = findAcrossParagraphs(document4.body, query, {
         regex: useRegex,
         ignoreCase,
         view: findView,
         exact
       });
-    } catch (matcherError) {
-      const message = matcherError instanceof Error ? matcherError.message : String(matcherError);
-      return fail("USAGE", `Invalid query: ${message}`);
+      matches = result.matches.map((match) => ({
+        locator: spanLocator(match),
+        ...match
+      }));
+      normalizationFields = normalizationPayload(result);
+    } else if (hasFormatFilter) {
+      matches = findFormattedSpans(document4.body, formatFilter, findView).map((match) => ({ locator: spanLocator(match), ...match }));
+    } else if (query != null) {
+      const result = findTextSpans(document4.body, query, {
+        regex: useRegex,
+        ignoreCase,
+        view: findView,
+        exact
+      });
+      matches = result.matches.map((match) => ({
+        locator: spanLocator(match),
+        ...match
+      }));
+      normalizationFields = normalizationPayload(result);
     }
+  } catch (matcherError) {
+    const message = matcherError instanceof Error ? matcherError.message : String(matcherError);
+    return fail("USAGE", `Invalid query: ${message}`);
   }
-  const allMatches = result.matches;
-  let selected;
+  let selected = matches;
   if (nth !== undefined) {
-    const single = allMatches[nth];
+    const single = matches[nth];
     if (!single) {
-      return fail("MATCH_NOT_FOUND", `Only ${allMatches.length} match(es); --nth ${nth} is out of range`);
+      return fail("MATCH_NOT_FOUND", `Only ${matches.length} match(es); --nth ${nth} is out of range`);
     }
     selected = [single];
-  } else {
-    selected = allMatches;
   }
-  const matches = selected.map((match) => ({
-    locator: `${match.blockId}:${match.start}-${match.end}`,
-    ...match
-  }));
   if (parsed.values.json) {
     await respond({
-      totalMatches: allMatches.length,
+      totalMatches: matches.length,
       query,
       regex: useRegex,
       ignoreCase,
       view: findView,
-      matches,
-      ...result.normalizedQuery !== undefined ? {
-        normalizedQuery: result.normalizedQuery,
-        normalizationApplied: result.normalizationApplied
-      } : {}
+      matches: selected,
+      ...normalizationFields
     });
     return EXIT2.OK;
   }
-  if (matches.length > 0) {
-    await writeStdout(`${matches.map((match) => match.locator).join(`
+  if (selected.length > 0) {
+    await writeStdout(`${selected.map((match) => match.locator).join(`
 `)}
 `);
   } else {
@@ -87280,6 +87619,12 @@ async function run15(args) {
   }
   return EXIT2.OK;
 }
+function normalizationPayload(result) {
+  return result.normalizedQuery !== undefined ? {
+    normalizedQuery: result.normalizedQuery,
+    normalizationApplied: result.normalizationApplied
+  } : {};
+}
 var HELP11 = `docx find \u2014 locate text spans and return their locators
 
 Usage:
@@ -87317,15 +87662,21 @@ Options:
   --json            emit the full match objects as JSON (default: bare locators)
   -h, --help        show this help
 
-Within-paragraph matches only \u2014 cross-paragraph ranges aren't supported
-yet. Searches the concatenated text of each paragraph in document order,
-including paragraphs nested in table cells (locators look like
-tT:rRcC:pK:S-E for those).
+Searches the concatenated text of each paragraph in document order, including
+paragraphs nested in table cells (locators look like tT:rRcC:pK:S-E for those).
+A TAB in the document matches as one character, and an in-paragraph line break
+matches "\\n". A QUERY containing "\\n" may span lines: each "\\n" matches a
+line break OR a paragraph boundary (consecutive paragraphs in the body or
+within ONE table cell \u2014 never across a table, section break, or cell wall). A spanning
+match prints as pA:S-pB:E \u2014 the cross-paragraph range form \`comments add
+--at\` accepts, so a spanning find pipes straight into a spanning comment.
 
 By default the query is normalized: balanced markdown emphasis around
 non-whitespace (**X**, __X__, *X*, \`X\`) is stripped; smart quotes match
-straight quotes; em-dash and en-dash match the hyphen. Pass --exact to
-match the raw query verbatim. --regex is always verbatim.
+straight quotes; em-dash and en-dash match the hyphen; a TAB or non-breaking/
+typographic space matches a plain space; bullet glyph variants (\xB7\u2022\u2023\u2219\u25AA\u25E6) match
+each other. Pass --exact to match the raw query verbatim. --regex is always
+verbatim. \\n and \\t in the QUERY are decoded to real characters first.
 
 Output:
   Default: EVERY matched span locator (e.g. p3:5-8), one per line \u2014 feed them
@@ -90261,10 +90612,19 @@ export type ImageRun = {
 export type BreakRun = {
 	type: "break";
 	kind: "page" | "line" | "column";
+	/** Set when the break sits inside a tracked-change wrapper (\`<w:ins>\`/
+	 *  \`<w:del>\`/\u2026). A LINE break is one offset character (it renders as "\\n"),
+	 *  so \`find\`/\`replace\` must know when to hide it in the accepted/baseline
+	 *  view, exactly as they do for a deleted \`TextRun\`. */
+	trackedChange?: TrackedChange;
 };
 
 export type TabRun = {
 	type: "tab";
+	/** Set when the tab sits inside a tracked-change wrapper. A tab is one offset
+	 *  character (it renders as "\\t"), so its view-visibility must track with the
+	 *  surrounding revision \u2014 see \`BreakRun.trackedChange\`. */
+	trackedChange?: TrackedChange;
 };
 
 /** A math equation. \`latex\` is reconstructed by walking the underlying
@@ -93106,6 +93466,98 @@ var init_render2 = __esm(() => {
   };
 });
 
+// src/cli/replace/across.ts
+async function runReplaceAcross(path2, pattern, replacement, options) {
+  const document4 = await openOrFail(path2);
+  if (typeof document4 === "number")
+    return document4;
+  if (resolveTracked(document4, options.track)) {
+    return fail("USAGE", ACROSS_TRACKED_MESSAGE, ACROSS_TRACKED_HINT);
+  }
+  let result;
+  try {
+    result = applyAcrossReplace(document4.body, {
+      pattern,
+      replacement,
+      regex: options.regex,
+      ignoreCase: options.ignoreCase,
+      exact: options.exact,
+      all: options.all,
+      ...options.limit !== undefined ? { limit: options.limit } : {},
+      view: options.view
+    }, { dryRun: options.dryRun });
+  } catch (matcherError) {
+    const message = matcherError instanceof Error ? matcherError.message : String(matcherError);
+    return fail("USAGE", `Invalid pattern: ${message}`);
+  }
+  const matchesPayload = result.replaced.map((match) => ({
+    locator: spanLocator(match),
+    text: match.text
+  }));
+  const normalizationFields = result.normalizedQuery !== undefined ? {
+    normalizedPattern: result.normalizedQuery,
+    normalizationApplied: result.normalizationApplied
+  } : {};
+  if (options.dryRun) {
+    await respond({
+      operation: "replace",
+      dryRun: true,
+      path: path2,
+      pattern,
+      replacement,
+      regex: options.regex,
+      ignoreCase: options.ignoreCase,
+      view: options.view,
+      crossParagraph: true,
+      totalMatches: result.totalMatches,
+      replaced: result.replaced.length,
+      matches: matchesPayload,
+      ...normalizationFields,
+      ...options.output ? { output: options.output } : {}
+    });
+    return EXIT2.OK;
+  }
+  if (result.replaced.length === 0) {
+    return await fail("MATCH_NOT_FOUND", `Pattern not found: ${JSON.stringify(pattern)} \u2014 0 occurrences, nothing changed.`, `Each \\n in the pattern matches a line break or the boundary between CONSECUTIVE paragraphs (never across a table, section break, or cell wall). \`docx read ${path2}\` shows the lines \u2014 check the exact text on each side of every \\n.`);
+  }
+  await document4.save(options.output);
+  const hints = [
+    "\u21B3 paragraph structure changed \u2014 block ids shifted; re-read before locator-addressed edits."
+  ];
+  const partialHint = partialReplaceHint(result.replaced.length, result.totalMatches);
+  if (partialHint)
+    hints.push(partialHint);
+  await respondAck({
+    ok: true,
+    operation: "replace",
+    path: options.output ?? path2,
+    pattern,
+    replacement,
+    regex: options.regex,
+    ignoreCase: options.ignoreCase,
+    view: options.view,
+    crossParagraph: true,
+    totalMatches: result.totalMatches,
+    replaced: result.replaced.length,
+    matches: matchesPayload,
+    ...normalizationFields
+  }, hints.join(`
+`));
+  return EXIT2.OK;
+}
+function partialReplaceHint(replaced, total) {
+  const remaining = total - replaced;
+  if (remaining <= 0)
+    return;
+  return `\u21B3 ${remaining} more match${remaining === 1 ? "" : "es"} left unreplaced (${replaced} of ${total} done) \u2014 pass --all to replace every match, or --limit N for a specific count.`;
+}
+var ACROSS_TRACKED_MESSAGE = "a replace that crosses or inserts paragraph boundaries can't be recorded as a tracked change yet (OOXML tracks a merge/split on the paragraph mark, which this path doesn't emit) \u2014 it will NOT run silently untracked", ACROSS_TRACKED_HINT = "Turn tracking off (docx track-changes off FILE) and re-run, or make within-paragraph replaces (no \\n) which track fine.";
+var init_across = __esm(() => {
+  init_find();
+  init_parse_helpers();
+  init_respond();
+});
+
 // src/cli/replace/scope.ts
 function validateScopeShape(at) {
   let parsed;
@@ -93188,6 +93640,36 @@ async function runReplaceBatch(filePath, batchSource, values2) {
     const spec = specs[index2];
     if (!spec)
       continue;
+    if (spec.pattern.includes(`
+`) || spec.replacement.includes(`
+`)) {
+      if (spec.at !== undefined) {
+        return fail("USAGE", `entry ${index2}: "at" can't scope a multi-line pattern \u2014 it spans paragraph boundaries`);
+      }
+      if (allocator) {
+        return fail("USAGE", `entry ${index2}: ${ACROSS_TRACKED_MESSAGE}`, ACROSS_TRACKED_HINT);
+      }
+      let acrossResult;
+      try {
+        acrossResult = applyAcrossReplace(document4.body, spec);
+      } catch (matcherError) {
+        const message = matcherError instanceof Error ? matcherError.message : String(matcherError);
+        return fail("USAGE", `entry ${index2}: invalid pattern: ${message}`);
+      }
+      results.push({
+        pattern: spec.pattern,
+        replacement: spec.replacement,
+        totalMatches: acrossResult.totalMatches,
+        replaced: acrossResult.replaced.length,
+        matches: acrossResult.replaced.map((match) => ({
+          locator: spanLocator(match),
+          text: match.text
+        }))
+      });
+      if (acrossResult.replaced.length > 0)
+        document4.reread();
+      continue;
+    }
     if (spec.at !== undefined) {
       try {
         document4.body.resolveBlock(spec.at);
@@ -93208,7 +93690,7 @@ async function runReplaceBatch(filePath, batchSource, values2) {
       return fail("USAGE", `entry ${index2}: invalid pattern: ${message}`);
     }
     const all2 = spec.at !== undefined ? matchesInScope(findResult.matches, spec.at) : findResult.matches;
-    const selected = spec.limit !== undefined ? all2.slice(0, spec.limit) : spec.all ? all2 : all2.slice(0, 1);
+    const selected = selectMatches(all2, spec);
     const tracked = allocator ? {
       meta: {
         author: resolveAuthor(spec.author ?? authorFlag),
@@ -93222,11 +93704,10 @@ async function runReplaceBatch(filePath, batchSource, values2) {
       }
       return right.start - left.start;
     });
-    const regexFlags = spec.ignoreCase ? "i" : "";
+    const expand = replacementExpander(spec);
     for (const match of reversed) {
-      const concreteReplacement = spec.regex ? match.text.replace(new RegExp(spec.pattern, regexFlags), spec.replacement) : spec.replacement;
       const blockRef = document4.body.resolveBlock(match.blockId);
-      replaceSpanInParagraph(blockRef.node, { start: match.start, end: match.end }, concreteReplacement, tracked, spec.view);
+      replaceSpanInParagraph(blockRef.node, { start: match.start, end: match.end }, expand(match.text), tracked, spec.view);
     }
     results.push({
       pattern: spec.pattern,
@@ -93234,11 +93715,12 @@ async function runReplaceBatch(filePath, batchSource, values2) {
       totalMatches: all2.length,
       replaced: selected.length,
       matches: selected.map((match) => ({
-        locator: `${match.blockId}:${match.start}-${match.end}`,
+        locator: spanLocator(match),
         text: match.text
       }))
     });
-    document4.reread();
+    if (selected.length > 0)
+      document4.reread();
   }
   if (dryRun) {
     await respond({
@@ -93319,6 +93801,7 @@ var init_batch4 = __esm(() => {
   init_find();
   init_parse_helpers();
   init_respond();
+  init_across();
   init_scope();
   EntryError3 = class EntryError3 extends Error {
     code;
@@ -93372,8 +93855,8 @@ async function run40(args) {
     }
     return runReplaceBatch(path2, batchInput, parsed.values);
   }
-  const pattern = parsed.positionals[1];
-  const replacement = parsed.positionals[2];
+  const pattern = decodeInlineEscapes(parsed.positionals[1]);
+  const replacement = decodeInlineEscapes(parsed.positionals[2]);
   if (pattern == null)
     return fail("USAGE", "Missing PATTERN argument", HELP36);
   if (replacement == null) {
@@ -93392,6 +93875,24 @@ async function run40(args) {
   if (limit !== undefined && (!Number.isInteger(limit) || limit <= 0)) {
     return fail("USAGE", `--limit must be a positive integer, got "${limitRaw}"`);
   }
+  if (pattern.includes(`
+`) || replacement.includes(`
+`)) {
+    if (parsed.values.at !== undefined) {
+      return fail("USAGE", "--at scopes a replace to ONE paragraph, but a \\n-bearing pattern/replacement spans paragraph boundaries \u2014 drop --at, or remove the \\n");
+    }
+    return runReplaceAcross(path2, pattern, replacement, {
+      regex: useRegex,
+      ignoreCase,
+      exact,
+      all: wantAll,
+      ...limit !== undefined ? { limit } : {},
+      view: findView,
+      track: Boolean(parsed.values.track),
+      ...parsed.values.output !== undefined ? { output: parsed.values.output } : {},
+      dryRun: Boolean(parsed.values["dry-run"])
+    });
+  }
   const document4 = await openOrFail(path2);
   if (typeof document4 === "number")
     return document4;
@@ -93424,16 +93925,9 @@ async function run40(args) {
     normalizedPattern: findResult.normalizedQuery,
     normalizationApplied: findResult.normalizationApplied
   } : {};
-  let selected;
-  if (limit !== undefined) {
-    selected = allMatches.slice(0, limit);
-  } else if (wantAll) {
-    selected = allMatches;
-  } else {
-    selected = allMatches.slice(0, 1);
-  }
+  const selected = selectMatches(allMatches, { all: wantAll, limit });
   const matchesPayload = selected.map((match) => ({
-    locator: `${match.blockId}:${match.start}-${match.end}`,
+    locator: spanLocator(match),
     blockId: match.blockId,
     start: match.start,
     end: match.end,
@@ -93474,15 +93968,18 @@ async function run40(args) {
     meta: { author: resolveAuthor(authorFlag), date: resolveDate() },
     allocator: new TrackChanges(document4).createAllocator()
   } : undefined;
-  const regexFlags = ignoreCase ? "i" : "";
+  const expand = replacementExpander({
+    pattern,
+    replacement,
+    regex: useRegex,
+    ignoreCase
+  });
   for (const match of reversed) {
-    const concreteReplacement = useRegex ? match.text.replace(new RegExp(pattern, regexFlags), replacement) : replacement;
     const blockRef = document4.body.resolveBlock(match.blockId);
-    replaceSpanInParagraph(blockRef.node, { start: match.start, end: match.end }, concreteReplacement, tracked, findView);
+    replaceSpanInParagraph(blockRef.node, { start: match.start, end: match.end }, expand(match.text), tracked, findView);
   }
   await document4.save(outputPath);
-  const remaining = allMatches.length - selected.length;
-  const partialHint = remaining > 0 ? `\u21B3 ${remaining} more match${remaining === 1 ? "" : "es"} left unreplaced (${selected.length} of ${allMatches.length} done) \u2014 pass --all to replace every match, or --limit N for a specific count.` : undefined;
+  const partialHint = partialReplaceHint(selected.length, allMatches.length);
   await respondAck({
     ok: true,
     operation: "replace",
@@ -93534,17 +94031,32 @@ Options:
   -v, --verbose     print the success ack JSON (default: a one-line confirmation)
   -h, --help        show this help
 
-Within-paragraph matches only. Run formatting (rPr) on the surrounding text
-is preserved; the replacement run inherits the rPr of the first run that
-overlaps the matched span. Tabs and other runs in the paragraph are left in
-place \u2014 only the matched text changes. So this is the no-rebuild way to FILL a
-formatted/tabbed template line: \`replace "Organization Name" "Northwind Robotics"\`
+Run formatting (rPr) on the surrounding text is preserved; the replacement
+run inherits the rPr of the first run that overlaps the matched span. Tabs
+and other runs in the paragraph are left in place \u2014 only the matched text
+changes (a TAB matches as one character, so a pattern typed with spaces fills
+a tab-separated line). So this is the no-rebuild way to FILL a formatted/
+tabbed template line: \`replace "Organization Name" "Northwind Robotics"\`
 on a "**Organization Name**\u21E5Date" line keeps the bold and the tab; don't
 hand-build \`edit --runs\` JSON to refill a line. \`--batch\` fills many at once.
 When a single invocation produces multiple replacements in the same paragraph,
 they're applied in reverse offset order so earlier offsets don't shift before
 being applied.
 
+Multi-line (editor-style): \\n and \\t in PATTERN/REPLACEMENT are decoded to
+real characters. A "\\n" in the PATTERN matches an in-paragraph line break OR
+the boundary between consecutive paragraphs \u2014 in the body or within one table
+cell (never across a table, section break, or cell wall); the REPLACEMENT's
+newlines then define the resulting
+structure, exactly as if the span were selected in Word and the replacement
+typed \u2014 a single-line replacement MERGES the spanned paragraphs into one
+(first paragraph's formatting governs), "\\n"s in the replacement keep/create
+paragraph marks (so a "\\n" in the replacement splits a paragraph even when
+the pattern didn't cross one). \`replace FILE "\\n" "" --all\` merges every
+paragraph pair. Cross-paragraph replaces can't be tracked yet: with tracking
+on (or --track) they refuse loudly rather than skip the journal \u2014 turn
+tracking off first. Block ids shift afterward; re-read before more edits.
+
 By default the PATTERN is normalized: balanced markdown emphasis around
 non-whitespace (**X**, __X__, *X*, \`X\`) is stripped; smart quotes match
 straight quotes; em-dash and en-dash match the hyphen. The REPLACEMENT
@@ -93591,6 +94103,7 @@ var init_replace4 = __esm(() => {
   init_find();
   init_parse_helpers();
   init_respond();
+  init_across();
   init_batch4();
   init_scope();
 });
@@ -98015,7 +98528,7 @@ Examples:
 // package.json
 var package_default = {
   name: "bun-docx",
-  version: "0.20.3",
+  version: "0.20.4",
   description: "Read, edit, redline, and comment on Microsoft Word .docx files from the command line \u2014 built for AI agents.",
   keywords: [
     "docx",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bun-docx",
-	"version": "0.20.3",
+	"version": "0.20.4",
 	"description": "Read, edit, redline, and comment on Microsoft Word .docx files from the command line — built for AI agents.",
 	"keywords": [
 		"docx",