revise 3.0.1 → 3.1.0

package/chunks/{chunk-ZLQVPMBN.js → chunk-SCNG3PKR.js}

@@ -897,12 +897,38 @@ var ReviseDocument = class _ReviseDocument {
       pattern.source,
       pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`
     );
-    return textBlocks(ydocToDocument2(this.currentYDoc)).map((block) => ({
-      id: block.id,
-      blockIndex: block.topIndex,
-      count: (block.text.match(matcher) ?? []).length,
-      text: block.text
-    })).filter((hit) => hit.count > 0);
+    const view = options.view ?? "tracked";
+    return textBlocks(ydocToDocument2(this.currentYDoc)).map((block) => {
+      const matches = matchesIn(block.segments, matcher, view);
+      return {
+        id: block.id,
+        blockIndex: block.topIndex,
+        count: matches.length,
+        text: segmentsText(block.segments, view),
+        matches
+      };
+    }).filter((hit) => hit.count > 0);
+  }
+  /**
+   * HTML the read tools returned (`read_blocks_from_index`,
+   * `read_specific_blocks`), in a view. The tools read the accepted view;
+   * "tracked" marks pending changes as `<ins>`/`<del>` with
+   * `data-change-id` and `data-author`, and shows whole blocks a change
+   * deletes where they were; "original" shows the text before every change.
+   * Block ids are unchanged. The editing tools read `<ins>` as its text and
+   * ignore `<del>`, so tracked HTML pasted back edits the accepted text.
+   */
+  viewHtml(html, view) {
+    if (view === "accepted") return Promise.resolve(html);
+    return this.serial(async () => {
+      await installDomShims();
+      const { AgentHtmlConverter } = await engineModules2.agentHtml();
+      const raw = ydocToDocument2(this.currentYDoc);
+      const authors = new Map(
+        this.currentSession.listSuggestions().map((r) => [r.id, r.agentName ?? r.authorType ?? "unknown"])
+      );
+      return renderView(html, raw, view, authors, AgentHtmlConverter);
+    });
   }
   /** What the document holds, in one glance: page setup, header and footer
    * text with live fields, title, headings, lists, tables, review state. */
@@ -912,23 +938,60 @@ var ReviseDocument = class _ReviseDocument {
     );
   }
   // ── editing ──────────────────────────────────────────────────────────────
-  /** Replace every exact occurrence, block by block (tracked changes in
-   * suggesting mode). `ids` limits it to those blocks. Replacing text with
-   * itself changes nothing and is not a failure. */
-  replaceText(find, replace, options = {}) {
+  /**
+   * Replace every occurrence everywhere: the body, tables, lists, page
+   * headers and footers, and footnotes and endnotes. Tracked changes in
+   * suggesting mode. Curly and straight quotes and non-breaking spaces match
+   * each other unless `exact`, and the replacement keeps the document's
+   * characters (see matchDocumentCharacters). Replacing text with itself
+   * changes nothing and is not a failure.
+   */
+  replaceAll(find, replace, options = {}) {
     return this.serial(async () => {
       if (!find) {
         throw new ReviseError("Nothing to find: give some text.", "usage");
       }
-      const targets = textBlocks(ydocToDocument2(this.currentYDoc)).filter(
-        (block) => block.text.includes(find) && (!options.ids || options.ids.includes(block.id))
+      const only = options.blocks ?? options.ids;
+      const all = replaceTargets(ydocToDocument2(this.currentYDoc)).filter(
+        (block) => !only || only.includes(block.id)
       );
+      const exactMatch = textMatcher(find, {
+        exact: options.exact,
+        ignoreCase: options.ignoreCase
+      });
+      const loosest = textMatcher(find, { ignoreCase: true });
+      const caseOnly = textMatcher(find, {
+        exact: options.exact,
+        ignoreCase: true
+      });
+      const targets = [];
+      const missed = /* @__PURE__ */ new Map();
+      for (const block of all) {
+        const matches = exactMatch(block.text);
+        if (matches.length) targets.push({ ...block, matches });
+        const left = [...matches];
+        for (const text of loosest(block.text)) {
+          const at = left.indexOf(text);
+          if (at >= 0) {
+            left.splice(at, 1);
+            continue;
+          }
+          const reason = caseOnly(text).length ? "case" : "characters";
+          const entry = missed.get(text) ?? { count: 0, reason };
+          entry.count += 1;
+          missed.set(text, entry);
+        }
+      }
+      const nearMisses = [...missed].map(([text, m]) => ({ text, ...m }));
+      const regions = {};
       if (find === replace) {
         return {
           replaced: 0,
           blocks: targets.map((t) => t.id),
+          regions,
           changeIds: [],
-          failures: []
+          failures: [],
+          nearMisses
         };
       }
       const failures = [];
@@ -939,11 +1002,16 @@ var ReviseDocument = class _ReviseDocument {
           block_ids: [target.id],
           context_notes: "N/A"
         });
+        const distinct = [...new Set(target.matches)];
         const result = await this.currentSession.tools.executeDynamic(
           "replace",
           {
             id: target.id,
-            replacements: [{ find, replace, occurrence: "all" }],
+            replacements: distinct.map((text) => ({
+              find: text,
+              replace: matchDocumentCharacters(find, text, replace),
+              occurrence: "all"
+            })),
             context_notes: "N/A"
           }
         );
@@ -956,26 +1024,52 @@ var ReviseDocument = class _ReviseDocument {
             });
           }
         } else {
-          replaced += target.text.split(find).length - 1;
+          replaced += target.matches.length;
+          regions[target.region] = (regions[target.region] ?? 0) + target.matches.length;
           changeIds.push(...result.value.suggestionIds ?? []);
         }
       }
       return {
         replaced,
         blocks: targets.map((t) => t.id),
+        regions,
         changeIds,
-        failures
+        failures,
+        nearMisses
       };
     });
   }
+  /** @deprecated The 3.0 name of `replaceAll`. */
+  replaceText(find, replace, options = {}) {
+    return this.replaceAll(find, replace, options);
+  }
+  /** The document as it was before every pending change, exported from
+   * a copy: this document keeps its changes. */
+  async exportOriginal(options) {
+    const copy = await _ReviseDocument.restore(await this.snapshot(), {
+      author: this.settings.author
+    });
+    try {
+      await copy.reject({ all: true });
+      const result = await copy.export({
+        ...options,
+        view: void 0,
+        mode: "final"
+      });
+      return { ...result, view: "original" };
+    } finally {
+      copy.dispose();
+    }
+  }
   // ── review ───────────────────────────────────────────────────────────────
   /** Pending tracked changes with where they are and what they do. */
   changes(filter = {}) {
     return this.serial(() => this.filteredChanges(filter));
   }
   async filteredChanges(filter = {}) {
-    return (await describeChanges(this.currentYDoc, this.currentSession)).filter((c) => filter.section ? inSection(c, filter.section) : true).filter(
-      (c) => filter.exceptSection ? !inSection(c, filter.exceptSection) : true
+    return applyChangeFilter(
+      await describeChanges(this.currentYDoc, this.currentSession),
+      filter
     );
   }
   /** The tracked changes a selection would settle, without settling them. */
@@ -993,22 +1087,21 @@ var ReviseDocument = class _ReviseDocument {
     return this.serial(() => this.settle(selection, false));
   }
   async selectedIds(selection, known) {
-    const { section, exceptSection, all } = selection;
+    const { section, exceptSection, blocks, all } = selection;
     const ids = selection.ids ?? [];
-    const kinds = [
-      ids.length > 0,
-      Boolean(all),
-      Boolean(section || exceptSection)
-    ];
+    const filtered = Boolean(section || exceptSection || blocks?.length);
+    const kinds = [ids.length > 0, Boolean(all), filtered];
     if (kinds.filter(Boolean).length !== 1) {
       throw new ReviseError(
-        "Select tracked changes one way: ids, all, or a section filter (section/exceptSection).",
+        "Select tracked changes one way: ids, all, or filters (section, exceptSection, blocks).",
         "invalid_selection"
       );
     }
-    if (section || exceptSection) {
-      const changes = known ?? await this.filteredChanges();
-      return changes.filter((c) => section ? inSection(c, section) : true).filter((c) => exceptSection ? !inSection(c, exceptSection) : true).map((c) => c.id);
+    if (filtered) {
+      return applyChangeFilter(
+        known ?? await describeChanges(this.currentYDoc, this.currentSession),
+        { section, exceptSection, blocks }
+      ).map((c) => c.id);
     }
     return all ? "all" : ids;
   }
@@ -1048,9 +1141,15 @@ var ReviseDocument = class _ReviseDocument {
   /** Write the document in a format. Reports what the output actually
    * contains: its pending changes, and for .docx how much of the original
    * file was carried over byte for byte. */
-  export(options) {
+  async export(options) {
+    const view = viewOfMode(options);
+    if (view === "original") return this.exportOriginal(options);
     return this.serial(async () => {
-      options = { ...options, format: exportFormat(options.format) };
+      options = {
+        ...options,
+        format: exportFormat(options.format),
+        mode: view === "accepted" ? "final" : options.mode
+      };
       const mode = options.format === "docx" ? options.mode ?? "review" : "final";
       const pending = this.currentSession.listSuggestions().length;
       const { bytes, outcome } = await exportYDoc(
@@ -1079,6 +1178,7 @@ var ReviseDocument = class _ReviseDocument {
         bytes,
         format: options.format,
         mode,
+        view: mode === "final" ? "accepted" : "tracked",
         pendingTrackedChanges: mode === "final" ? 0 : pending,
         fidelity: outcome,
         warnings
@@ -1184,6 +1284,16 @@ async function compare(originalSource, revisedSource, options = {}) {
 }
 async function convert(source, format, options = {}) {
   format = exportFormat(format);
+  const view = viewOfMode(options);
+  if (view === "original") {
+    const doc = await ReviseDocument.open(source);
+    try {
+      return (await doc.export({ format, view })).bytes;
+    } finally {
+      doc.dispose();
+    }
+  }
+  if (view === "accepted") options = { mode: "final" };
   const { bytes, filename } = await readSource(source);
   assertReadable(filename);
   const ydoc = await importYDoc(bytes, filename);
@@ -1193,6 +1303,22 @@ async function convert(source, format, options = {}) {
     title: stem(filename)
   });
 }
+function viewOfMode(options) {
+  const { mode, view } = options;
+  if (view !== void 0 && !["tracked", "accepted", "original"].includes(view)) {
+    throw new ReviseError(
+      `Unknown view "${view}". Use tracked, accepted, or original.`,
+      "usage"
+    );
+  }
+  if (view && mode && mode === "final" !== (view !== "tracked")) {
+    throw new ReviseError(
+      `mode "${mode}" and view "${view}" disagree; give one of them.`,
+      "usage"
+    );
+  }
+  return view;
+}
 var EXPORT_FORMATS = ["docx", "pdf", "markdown", "html", "txt"];
 function exportFormat(format) {
   const name = String(format).toLowerCase();
@@ -1207,16 +1333,28 @@ function exportFormat(format) {
 }
 function textBlocks(doc) {
   const out = [];
-  const textOf = (node) => (node.children ?? []).map((child) => {
-    const c = child;
-    return c.type === "text" && !c.marks?.deletion ? c.text ?? "" : "";
-  }).join("");
+  const segmentsOf = (node) => {
+    const segments = [];
+    for (const child of node.children ?? []) {
+      const c = child;
+      if (c.type !== "text" || !c.text) continue;
+      const change = c.marks?.deletion ? "deleted" : c.marks?.insertion ? "inserted" : null;
+      const changeId = change ? c.marks?.suggestionId ?? null : null;
+      const last = segments[segments.length - 1];
+      if (last && last.change === change && last.changeId === changeId) {
+        last.text += c.text;
+      } else {
+        segments.push({ text: c.text, change, changeId });
+      }
+    }
+    return segments;
+  };
   doc.children.forEach((block, topIndex) => {
     const visit = (node) => {
       const n = node;
       if (!n || typeof n !== "object") return;
       if ((n.type === "paragraph" || n.type === "list-item") && n.id) {
-        out.push({ id: n.id, text: textOf(n), topIndex });
+        out.push({ id: n.id, segments: segmentsOf(n), topIndex });
         return;
       }
       n.children?.forEach(visit);
@@ -1225,36 +1363,308 @@ function textBlocks(doc) {
   });
   return out;
 }
+function replaceTargets(doc) {
+  const out = [];
+  const textOf = (node) => (node.children ?? []).map((child) => {
+    const c = child;
+    return c.type === "text" && !c.marks?.deletion ? c.text ?? "" : "";
+  }).join("");
+  const visit = (node, region) => {
+    const n = node;
+    if (!n || typeof n !== "object") return;
+    if ((n.type === "paragraph" || n.type === "list-item") && n.id) {
+      out.push({ id: n.id, text: textOf(n), region });
+      return;
+    }
+    n.children?.forEach((child) => visit(child, region));
+  };
+  doc.children.forEach((block) => visit(block, "body"));
+  for (const block of doc.chrome ?? []) {
+    block.children.forEach((column) => visit(column, block.side));
+  }
+  for (const note of doc.notes ?? []) {
+    const region = note.noteKind === "endnote" ? "endnote" : "footnote";
+    note.children.forEach((child) => visit(child, region));
+  }
+  return out;
+}
+var LOOSE_CHARACTERS = {
+  "\u2018": "'",
+  // ‘
+  "\u2019": "'",
+  // ’
+  "\u201A": "'",
+  // ‚
+  "\u201B": "'",
+  // ‛
+  "\u2032": "'",
+  // ′
+  "\u201C": '"',
+  // “
+  "\u201D": '"',
+  // ”
+  "\u201E": '"',
+  // „
+  "\u201F": '"',
+  // ‟
+  "\u2033": '"',
+  // ″
+  "\xA0": " ",
+  // no-break space
+  "\u202F": " ",
+  // narrow no-break space
+  "\u2007": " ",
+  // figure space
+  "\u2009": " ",
+  // thin space
+  "\u2011": "-",
+  // non-breaking hyphen
+  "\u2010": "-"
+  // hyphen
+};
+function fold(text, options) {
+  return Array.from(text, (char) => {
+    let c = options.exact ? char : LOOSE_CHARACTERS[char] ?? char;
+    if (options.ignoreCase) {
+      const lower = c.toLowerCase();
+      if (lower.length === c.length) c = lower;
+    }
+    return c;
+  });
+}
+function textMatcher(find, options) {
+  const needle = fold(find, options).join("");
+  return (text) => {
+    const chars = Array.from(text);
+    const hay = fold(text, options).join("");
+    const matches = [];
+    const starts = [];
+    let offset = 0;
+    for (const c of fold(text, options)) {
+      starts.push(offset);
+      offset += c.length;
+    }
+    let from = 0;
+    while (needle) {
+      const at = hay.indexOf(needle, from);
+      if (at < 0) break;
+      const first = starts.indexOf(at);
+      let last = first;
+      while (last < starts.length && starts[last] < at + needle.length) last++;
+      if (first >= 0) matches.push(chars.slice(first, last).join(""));
+      from = at + Math.max(needle.length, 1);
+    }
+    return matches;
+  };
+}
+function matchDocumentCharacters(find, matched, replace) {
+  const findChars = Array.from(find);
+  const matchedChars = Array.from(matched);
+  const out = Array.from(replace);
+  for (const plain of ["'", '"', " ", "-"]) {
+    const documentChars = findChars.map((c, i) => c === plain ? matchedChars[i] : void 0).filter((c) => c !== void 0);
+    if (documentChars.every((c) => c === plain)) continue;
+    const slots = out.flatMap((c, i) => c === plain ? [i] : []);
+    if (slots.length !== documentChars.length) continue;
+    slots.forEach((slot, n) => out[slot] = documentChars[n]);
+  }
+  return out.join("");
+}
+var shows = (segment, view) => view === "tracked" || segment.change === null || segment.change === "inserted" === (view === "accepted");
+function segmentsText(segments, view) {
+  return segments.filter((segment) => shows(segment, view)).map(
+    (segment) => view !== "tracked" || segment.change === null ? segment.text : segment.change === "deleted" ? `[-${segment.text}-]` : `{+${segment.text}+}`
+  ).join("");
+}
+function matchesIn(segments, matcher, view) {
+  const found = [];
+  const scan = (side, keep) => {
+    const places = [];
+    const owners = [];
+    let text = "";
+    let at = 0;
+    for (const segment of segments) {
+      if (shows(segment, side)) {
+        for (let i = 0; i < segment.text.length; i++) {
+          places.push(at + i);
+          owners.push(segment);
+        }
+        text += segment.text;
+      }
+      at += segment.text.length;
+    }
+    for (const match of text.matchAll(matcher)) {
+      if (!match[0]) continue;
+      const start = match.index ?? 0;
+      const touched = owners.slice(start, start + match[0].length).find((owner) => owner.change !== null);
+      const change = touched?.change ?? null;
+      if (!keep(change)) continue;
+      found.push({
+        text: match[0],
+        change,
+        changeId: touched?.changeId ?? null,
+        at: places[start]
+      });
+    }
+  };
+  if (view === "tracked") {
+    scan("accepted", (change) => change !== "deleted");
+    scan("original", (change) => change === "deleted");
+  } else {
+    scan(view, () => true);
+  }
+  return found.sort(
+    (a, b) => a.at - b.at || Number(b.change === "deleted") - Number(a.change === "deleted")
+  ).map(({ text, change, changeId }) => ({ text, change, changeId }));
+}
+var OPEN = "\uE000";
+var DELETED = "\uE001";
+var INSERTED = "\uE002";
+var CLOSE = "\uE003";
+var CHANGE_BASE = 57600;
+var SENTINEL_RUN = /([])([-])([\s\S]*?)/g;
+function renderView(html, raw, view, authors, AgentHtmlConverter) {
+  const ids = topLevelIds(html);
+  const blocks = [...raw.children, ...raw.notes ?? []];
+  const position = new Map(blocks.map((block, i) => [block.id, i]));
+  const known = ids.map((id) => position.get(id)).filter((at) => at !== void 0);
+  if (!known.length) return html;
+  const deleted = (block) => block !== void 0 && wholeBlockDeletion(block) !== null;
+  let first = Math.min(...known);
+  let last = Math.max(...known);
+  if (blocks.slice(0, first).every((block) => deleted(block))) first = 0;
+  while (last + 1 < blocks.length && deleted(blocks[last + 1])) last += 1;
+  const changes = [];
+  const indexOf = (id) => {
+    let i = changes.indexOf(id);
+    if (i < 0) i = changes.push(id) - 1;
+    return String.fromCharCode(CHANGE_BASE + Math.min(i, 63743 - CHANGE_BASE));
+  };
+  const marked = (node, deletedBy) => {
+    if (!node || typeof node !== "object") return node;
+    const n = node;
+    if (n.type === "text" && n.text) {
+      const deletion = n.marks?.deletion || deletedBy && !n.marks?.insertion;
+      if (!deletion && !n.marks?.insertion) return node;
+      const id = n.marks?.suggestionId ?? deletedBy ?? "";
+      const kind = deletion ? DELETED : INSERTED;
+      return { ...n, text: `${OPEN}${kind}${indexOf(id)}${n.text}${CLOSE}` };
+    }
+    const structural = node;
+    const by = structural.structuralSuggestionKind === "delete" ? structural.structuralSuggestionId : deletedBy;
+    return Array.isArray(n.children) ? { ...n, children: n.children.map((child) => marked(child, by)) } : node;
+  };
+  const range = blocks.slice(first, last + 1).map((block) => marked(block));
+  const doc = { ...raw, children: range, notes: void 0 };
+  const rendered = AgentHtmlConverter.extractSpecificBlocks(
+    doc,
+    range.map((block) => block.id),
+    void 0,
+    { scanDocumentFontFamily: false }
+  ).foundBlocks.map((block, i) => {
+    const whole = view === "tracked" ? wholeBlockDeletion(range[i]) : null;
+    return whole && !block.html.includes(OPEN) ? block.html.replace(
+      /^<([a-z][\w-]*)/,
+      `<$1 data-change="deleted" data-change-id="${escapeAttr(whole)}" data-author="${escapeAttr(authors.get(whole) ?? "unknown")}"`
+    ) : block.html;
+  });
+  const header = /^\s*Showing \d+ block\(s\):\s*/.exec(html) ? `Showing ${rendered.length} block(s):
+
+` : "";
+  return (header + rendered.join("\n")).replace(
+    SENTINEL_RUN,
+    (_, kind, index, text) => {
+      const deletion = kind === DELETED;
+      if (view === "original") return deletion ? text : "";
+      const id = changes[index.charCodeAt(0) - CHANGE_BASE] ?? "";
+      const tag = deletion ? "del" : "ins";
+      return `<${tag} data-change-id="${escapeAttr(id)}" data-author="${escapeAttr(authors.get(id) ?? "unknown")}">${text}</${tag}>`;
+    }
+  );
+}
+function wholeBlockDeletion(block) {
+  const b = block;
+  if (b.structuralSuggestionKind === "delete" && b.structuralSuggestionId) {
+    return b.structuralSuggestionId;
+  }
+  let id = null;
+  let all = true;
+  let any = false;
+  const visit = (node) => {
+    if (!all || !node || typeof node !== "object") return;
+    const n = node;
+    if (n.type === "text") {
+      if (!n.text) return;
+      any = true;
+      if (!n.marks?.deletion) all = false;
+      else id ??= n.marks.suggestionId ?? null;
+      return;
+    }
+    n.children?.forEach(visit);
+  };
+  visit(block);
+  return any && all ? id : null;
+}
+function topLevelIds(html) {
+  const body = new DOMParser().parseFromString(
+    `<!doctype html><body>${html}</body>`,
+    "text/html"
+  ).body;
+  return Array.from(body.children).map((el) => el.getAttribute("id")).filter((id) => Boolean(id));
+}
+var escapeAttr = (value) => value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+var placesByEntries = /* @__PURE__ */ new WeakMap();
 async function describeChanges(ydoc, session) {
   const records = session.listSuggestions();
   const doc = ydocToDocument2(ydoc);
-  const measured = await session.tools.call("measure_document", {
-    include_sections: true,
-    section_limit: 1e3
-  });
-  const sections = measured.data.sections ?? [];
-  const positionOf = new Map(
-    doc.children.map((block, index) => [block.id, index])
-  );
-  const starts = sections.map((s) => ({ title: s.title, at: positionOf.get(s.startBlockId) })).filter((s) => s.at !== void 0).sort((a, b) => a.at - b.at);
-  const sectionAt = (index) => {
+  const { documentHeadingSections } = await engineModules2.outline();
+  const span = /* @__PURE__ */ new Map();
+  let next = 0;
+  const number = (node) => {
+    if (!node || typeof node !== "object") return;
+    const n = node;
+    const isBlock = typeof n.id === "string" && n.type !== "text";
+    const start = next;
+    if (isBlock) next += 1;
+    n.children?.forEach(number);
+    if (isBlock) span.set(n.id, { start, end: next - 1 });
+  };
+  doc.children.forEach(number);
+  const bodyEnd = next;
+  (doc.chrome ?? []).forEach(number);
+  (doc.notes ?? []).forEach(number);
+  const headings = documentHeadingSections(doc, { maxDepth: 3 }).flatMap((h) => {
+    const start = span.get(h.itemId ?? h.blockId)?.start;
+    return start === void 0 ? [] : [{ title: h.title, level: h.level, start }];
+  }).sort((a, b) => a.start - b.start);
+  const sections = headings.map((h, i) => ({
+    ...h,
+    end: (headings.slice(i + 1).find((later) => later.level <= h.level)?.start ?? bodyEnd) - 1
+  }));
+  const sectionAt = (at) => {
     let title;
-    for (const start of starts) {
-      if (start.at > index) break;
-      title = start.title;
+    for (const section of sections) {
+      if (section.start > at) break;
+      title = section.title;
     }
     return title;
   };
+  const positionOf = new Map(
+    doc.children.map((block, index) => [block.id, index])
+  );
   const found = /* @__PURE__ */ new Map();
-  doc.children.forEach((block, blockIndex) => {
-    const visit = (node) => {
+  const collect = (block, blockIndex, label) => {
+    const visit = (node, path) => {
       if (!node || typeof node !== "object") return;
       const n = node;
+      const here = typeof n.id === "string" && n.type !== "text" ? [...path, n.id] : path;
       const id = n.marks?.suggestionId ?? n.suggestionId ?? n.structuralSuggestionId;
       if (id) {
         const entry = found.get(id) ?? {
           blockIndex,
           blockId: block.id ?? "",
+          label,
+          path: here,
           deleted: "",
           inserted: ""
         };
@@ -1264,32 +1674,142 @@ async function describeChanges(ydoc, session) {
         }
         found.set(id, entry);
       }
-      n.children?.forEach(visit);
+      n.children?.forEach((child) => visit(child, here));
     };
-    visit(block);
-  });
-  return records.map((record) => {
+    visit(block, []);
+  };
+  doc.children.forEach(
+    (block, blockIndex) => collect(block, blockIndex, void 0)
+  );
+  for (const block of doc.chrome ?? []) {
+    collect(block, void 0, block.side === "header" ? "Header" : "Footer");
+  }
+  const noteCount = { footnote: 0, endnote: 0 };
+  for (const note of doc.notes ?? []) {
+    const kind = note.noteKind === "endnote" ? "endnote" : "footnote";
+    noteCount[kind] += 1;
+    collect(
+      note,
+      void 0,
+      `${kind === "endnote" ? "Endnote" : "Footnote"} ${noteCount[kind]}`
+    );
+  }
+  const changes = /* @__PURE__ */ new WeakMap();
+  const entries = records.map((record) => {
     const at = found.get(record.id);
     const blockIndex = at?.blockIndex ?? (record.blockId ? positionOf.get(record.blockId) : void 0) ?? (record.tableId ? positionOf.get(record.tableId) : void 0);
-    return {
+    const path = at?.path ?? [record.tableId, record.blockId].filter(
+      (id) => Boolean(id && span.has(id))
+    );
+    const place = path.length ? span.get(path[path.length - 1]) : void 0;
+    const entry = {
       id: record.id,
       type: record.type ?? "text",
       author: record.agentName ?? record.authorType ?? "unknown",
       ...at?.blockId || record.blockId ? { blockId: at?.blockId || record.blockId } : {},
-      ...blockIndex !== void 0 ? { blockIndex, section: sectionAt(blockIndex) } : {},
+      ...blockIndex !== void 0 ? { blockIndex } : {},
+      ...at?.label ? { section: at.label } : place && place.start < bodyEnd ? { section: sectionAt(place.start) } : {},
       deleted: at?.deleted ?? "",
       inserted: at?.inserted ?? ""
     };
+    if (place) changes.set(entry, { at: place.start, path });
+    return entry;
   });
+  placesByEntries.set(entries, { span, sections, changes });
+  return entries;
 }
-function inSection(entry, query) {
-  if (!entry.section) return false;
-  const title = entry.section.trim().toLowerCase();
+function headingMatches(title, query) {
+  const heading = title.trim().toLowerCase();
   const q = query.trim().toLowerCase().replace(/\.$/, "");
   if (/^[\d.]+$/.test(q)) {
-    return new RegExp(`^${q.replace(/\./g, "\\.")}(?:[.\\s)]|$)`).test(title);
+    return new RegExp(`^${q.replace(/\./g, "\\.")}(?:[.\\s)]|$)`).test(heading);
   }
-  return title.includes(q);
+  return heading.includes(q);
+}
+function parseBlockQuery(query) {
+  return query.split(",").map((part) => part.trim()).filter(Boolean).map((part) => {
+    const [from, to, ...rest] = part.split(/\.\.\.?|…/).map((id) => id.trim());
+    if (to === void 0) return from;
+    if (!from || !to || rest.length) {
+      throw new ReviseError(
+        `"${part}" is not a block range; write first..last.`,
+        "invalid_selection"
+      );
+    }
+    return { from, to };
+  });
+}
+function applyChangeFilter(entries, filter) {
+  const { section, exceptSection, blocks } = filter;
+  if (!section && !exceptSection && !blocks?.length) return entries;
+  const places = placesByEntries.get(entries);
+  if (!places) return entries;
+  const sectionRanges = (query) => {
+    const q = query.trim().toLowerCase();
+    const exact = places.sections.filter(
+      (s) => s.title.toLowerCase() === q || s.title.toLowerCase().replace(/^[\d.]+[.)]?\s+/, "") === q
+    );
+    const candidates = exact.length ? exact : places.sections.filter((s) => headingMatches(s.title, query));
+    const matched = candidates.filter(
+      (s) => !candidates.some(
+        (outer) => outer !== s && outer.start < s.start && s.end <= outer.end
+      )
+    );
+    if (matched.length > 1) {
+      throw new ReviseError(
+        `"${query}" matches ${matched.length} headings: ${matched.map((s) => `"${s.title}"`).join(", ")}. Name one by its number or full title.`,
+        "section_ambiguous"
+      );
+    }
+    if (!matched.length) {
+      throw new ReviseError(
+        places.sections.length ? `No heading matches "${query}". Headings: ${places.sections.slice(0, 12).map((s) => `"${s.title}"`).join(", ")}${places.sections.length > 12 ? ", \u2026" : ""}.` : `No heading matches "${query}": the document has no headings. Select by blocks or change ids instead.`,
+        "section_not_found"
+      );
+    }
+    return matched;
+  };
+  const spanOf = (id) => {
+    const found = places.span.get(id);
+    if (!found) {
+      throw new ReviseError(`No block with id "${id}".`, "block_not_found");
+    }
+    return found;
+  };
+  const inside = sectionRanges;
+  const keepSections = section ? inside(section) : void 0;
+  const dropSections = exceptSection ? inside(exceptSection) : void 0;
+  const ids = /* @__PURE__ */ new Set();
+  const ranges = [];
+  for (const item of blocks ?? []) {
+    if (typeof item === "string") {
+      spanOf(item);
+      ids.add(item);
+      continue;
+    }
+    const from = spanOf(item.from);
+    const to = spanOf(item.to);
+    if (from.start > to.start) {
+      throw new ReviseError(
+        `Block "${item.from}" comes after "${item.to}"; write the range first..last.`,
+        "invalid_selection"
+      );
+    }
+    ranges.push({ start: from.start, end: to.end });
+  }
+  const within = (at, r) => at >= r.start && at <= r.end;
+  return entries.filter((entry) => {
+    const place = places.changes.get(entry);
+    if (!place) return false;
+    if (keepSections && !keepSections.some((r) => within(place.at, r))) {
+      return false;
+    }
+    if (dropSections?.some((r) => within(place.at, r))) return false;
+    if (blocks?.length && !place.path.some((id) => ids.has(id)) && !ranges.some((r) => within(place.at, r))) {
+      return false;
+    }
+    return true;
+  });
 }
 async function markdownOf(ydoc) {
   const bytes = await exportDocument(ydoc, {
@@ -1645,6 +2165,7 @@ export {
   seedYDoc,
   compare,
   convert,
+  parseBlockQuery,
   formatToolResult,
   agentTools
 };