web-doc 0.6.2 → 0.8.0

package/dist/edit/ai/outline.js

@@ -0,0 +1,338 @@
+/*
+ * The outline is `getElements()` reshaped for a prompt: nested where the
+ * format nests (a table's cell paragraphs, a group's members, a paragraph's
+ * inline pictures), numbered in reading order, with a short text and a
+ * human label per node and nothing a model cannot use (geometry, styles).
+ * The description is the outline as text in a fixed line grammar, so a host
+ * pastes it into a prompt without a formatter of its own.
+ */
+const DEFAULT_TEXT_CHARS = 160;
+const DEFAULT_DESCRIBE_CHARS = 50_000;
+/** The outline of a session's document; one `getElements()` read, reshaped. */
+export async function readOutline(session, limits, options = {}) {
+    const { pageRange, signal } = options;
+    // A single page is read as such: cheaper for formats that load pages on demand.
+    const query = pageRange && pageRange[0] === pageRange[1]
+        ? { pageIndex: pageRange[0] }
+        : {};
+    const read = await session.getElements(query, signal ? { signal } : {});
+    const built = buildOutline(session.format, read.items, options, limits.maxOutlineNodes);
+    return Object.freeze({
+        sessionId: read.sessionId,
+        revision: read.revision,
+        items: built.nodes,
+        nodeCount: built.nodeCount,
+        truncated: built.truncated,
+    });
+}
+/** The description of a session's document: the outline rendered within a character budget. */
+export async function readDescription(session, limits, options = {}) {
+    const { maxChars, ...outlineOptions } = options;
+    const outline = await readOutline(session, limits, outlineOptions);
+    const budget = Math.max(1, Math.min(maxChars ?? DEFAULT_DESCRIBE_CHARS, limits.maxDescribeChars));
+    return Object.freeze({
+        sessionId: outline.sessionId,
+        revision: outline.revision,
+        item: renderDescription(session.format, session.state.pageCount, outline, budget, limits.maxOutlineNodes),
+    });
+}
+/**
+ * Nests elements by `parentId`, numbers them in reading order, keeps the
+ * nodes the options ask for (a container stays when a descendant is kept)
+ * and cuts the result at `maxNodes`. Ordinals are assigned before any
+ * filtering, so "3.2" names the same paragraph whatever the query.
+ */
+export function buildOutline(format, elements, options, maxNodes) {
+    const maxText = Math.max(0, options.maxTextChars ?? DEFAULT_TEXT_CHARS);
+    const ids = new Set(elements.map((element) => element.id));
+    const childrenOf = new Map();
+    const roots = [];
+    for (const element of elements) {
+        const parent = element.parentId;
+        if (parent === undefined || parent === element.id || !ids.has(parent)) {
+            roots.push(element);
+            continue;
+        }
+        const siblings = childrenOf.get(parent);
+        if (siblings)
+            siblings.push(element);
+        else
+            childrenOf.set(parent, [element]);
+    }
+    const visited = new Set();
+    const toNode = (element, ordinal) => {
+        visited.add(element.id);
+        const children = (childrenOf.get(element.id) ?? [])
+            .filter((child) => !visited.has(child.id))
+            .map((child, index) => toNode(child, `${ordinal}.${index + 1}`));
+        return nodeOf(format, element, ordinal, maxText, children);
+    };
+    const tree = roots.map((element, index) => toNode(element, `${index + 1}`));
+    // Elements whose parents form a cycle are never reached from a root;
+    // they are listed after the roots rather than dropped.
+    let extra = tree.length;
+    for (const element of elements)
+        if (!visited.has(element.id)) {
+            extra += 1;
+            tree.push(toNode(element, `${extra}`));
+        }
+    const kept = prune(tree, keepPredicate(options));
+    const cut = cutNodes(kept, maxNodes);
+    return {
+        nodes: cut.nodes,
+        nodeCount: cut.count,
+        truncated: cut.truncated,
+    };
+}
+function nodeOf(format, element, ordinal, maxText, children) {
+    const text = element.text;
+    const label = labelOf(format, element);
+    const extra = element;
+    return Object.freeze({
+        id: element.id,
+        ordinal,
+        kind: element.kind,
+        pageIndex: element.pageIndex,
+        ...(text === undefined ? {} : { text: cutText(text, maxText) }),
+        textLength: text?.length ?? 0,
+        truncated: text !== undefined && text.length > maxText,
+        ...(label === undefined ? {} : { label }),
+        ...(extra.readOnlyReason === undefined
+            ? {}
+            : { readOnlyReason: extra.readOnlyReason }),
+        ...(extra.hidden ? { hidden: true } : {}),
+        operations: Object.freeze([...element.operations]),
+        ...(children.length > 0 ? { children: Object.freeze(children) } : {}),
+    });
+}
+/** The first `max` code units of `text`, never ending inside a surrogate pair. */
+function cutText(text, max) {
+    if (text.length <= max)
+        return text;
+    let end = max;
+    const last = text.charCodeAt(end - 1);
+    if (end > 0 && last >= 0xd800 && last <= 0xdbff)
+        end -= 1;
+    return text.slice(0, end);
+}
+function keepPredicate(options) {
+    const { pageRange, kinds } = options;
+    if (!pageRange && !kinds)
+        return undefined;
+    const wanted = kinds ? new Set(kinds) : undefined;
+    return (node) => (!wanted || wanted.has(node.kind)) &&
+        (!pageRange ||
+            (node.pageIndex >= pageRange[0] && node.pageIndex <= pageRange[1]));
+}
+/** Keeps the nodes `keep` accepts and every ancestor of one, in order. */
+function prune(nodes, keep) {
+    if (!keep)
+        return nodes;
+    const out = [];
+    for (const node of nodes) {
+        const children = node.children ? prune(node.children, keep) : [];
+        if (!keep(node) && children.length === 0)
+            continue;
+        out.push(children.length === node.children?.length
+            ? node
+            : withChildren(node, children));
+    }
+    return out;
+}
+/** The first `max` nodes in pre-order; the rest are cut, subtrees included. */
+function cutNodes(nodes, max) {
+    let count = 0;
+    let truncated = false;
+    const take = (list) => {
+        const out = [];
+        for (const node of list) {
+            if (count >= max) {
+                truncated = true;
+                break;
+            }
+            count += 1;
+            if (!node.children) {
+                out.push(node);
+                continue;
+            }
+            const children = take(node.children);
+            out.push(children.length === node.children.length
+                ? node
+                : withChildren(node, children));
+            // A cut inside the children leaves nothing for the siblings.
+            if (truncated)
+                break;
+        }
+        return Object.freeze(out);
+    };
+    const kept = take(nodes);
+    return { nodes: kept, count, truncated };
+}
+/** `node` with `children`, the key left out when there are none. */
+function withChildren(node, children) {
+    const { children: _dropped, ...rest } = node;
+    return Object.freeze(children.length > 0 ? { ...rest, children: Object.freeze(children) } : rest);
+}
+/**
+ * What a person calls the element, when the format knows: a shape's name
+ * or placeholder in a deck, a paragraph's style in a Word document, a
+ * table's size everywhere.
+ */
+export function labelOf(format, element) {
+    const known = element;
+    const size = known.table ? tableSize(known.table.rows) : undefined;
+    if (format === "pptx") {
+        const name = known.name?.trim();
+        if (name)
+            return size ? `${name} (${size})` : name;
+        if (known.placeholder)
+            return placeholderLabel(known.placeholder.type);
+    }
+    if (format === "docx" && element.kind === "paragraph") {
+        const style = known.paragraphStyle;
+        const styleId = style?.styleId;
+        const name = styleId && styleId !== "Normal" ? styleName(styleId) : undefined;
+        if (name)
+            return name;
+        if (style?.numbering)
+            return `List item (level ${style.numbering.level + 1})`;
+        return undefined;
+    }
+    if (size)
+        return `Table (${size})`;
+    return undefined;
+}
+function tableSize(rows) {
+    const columns = rows.reduce((max, row) => Math.max(max, row.length), 0);
+    return `${rows.length}×${columns}`;
+}
+const PLACEHOLDER_LABELS = {
+    title: "Title",
+    ctrTitle: "Title",
+    subTitle: "Subtitle",
+    body: "Body",
+    obj: "Content",
+    pic: "Picture",
+    tbl: "Table",
+    chart: "Chart",
+    dgm: "Diagram",
+    media: "Media",
+    clipArt: "Clip art",
+    dt: "Date",
+    ftr: "Footer",
+    sldNum: "Slide number",
+    hdr: "Header",
+    sldImg: "Slide image",
+};
+function placeholderLabel(type) {
+    return PLACEHOLDER_LABELS[type] ?? `${type} placeholder`;
+}
+/** "Heading1" → "Heading 1", "ListParagraph" → "List Paragraph". */
+function styleName(styleId) {
+    return styleId
+        .replace(/([a-z])([A-Z])/g, "$1 $2")
+        .replace(/([A-Za-z])(\d)/g, "$1 $2");
+}
+/**
+ * The description's grammar, one line per node:
+ *
+ *     <format>: <n> pages|slides, <m> elements
+ *     [<id>] page <p> <kind> "<label>" (<flags>): <text>…
+ *       [<child id>] page <p> <kind>: <text>
+ *
+ * The page is left out while the node has none, the label and the flags
+ * while the node has none, the text while it is empty. Tabs in the text
+ * become ` | `, line breaks ` ⏎ `; a cut text ends in `…`. Children are
+ * indented two spaces per level. The budget cuts whole lines and the last
+ * line then says how many were left out.
+ */
+export function renderDescription(format, pageCount, outline, maxChars, maxNodes) {
+    const nodes = "items" in outline ? outline.items : outline.nodes;
+    const noun = format === "pptx" ? "slide" : "page";
+    const lines = [
+        `${format}: ${count(pageCount, noun)}, ${count(outline.nodeCount, "element")}`,
+    ];
+    const push = (node, depth) => {
+        lines.push(`${"  ".repeat(depth)}${describeNode(node, noun)}`);
+        for (const child of node.children ?? [])
+            push(child, depth + 1);
+    };
+    for (const node of nodes)
+        push(node, 0);
+    // Whole lines within the budget; the last line then says what was left
+    // out and makes room for itself. Prefix sums keep this linear in the
+    // number of lines: `joined[k]` is the length of the first `k` lines joined.
+    const joined = new Array(lines.length + 1);
+    joined[0] = 0;
+    for (let index = 0; index < lines.length; index += 1)
+        joined[index + 1] =
+            joined[index] + lines[index].length + (index > 0 ? 1 : 0);
+    const tailOf = (keep) => {
+        const left = lines.length - keep;
+        if (left > 0)
+            return `… (${count(left, "more line")})`;
+        if (outline.truncated)
+            return `… (outline cut at ${count(maxNodes, "node")})`;
+        return undefined;
+    };
+    const lengthOf = (keep) => {
+        const tail = tailOf(keep);
+        const body = joined[keep];
+        if (tail === undefined)
+            return body;
+        return body === 0 ? tail.length : body + 1 + tail.length;
+    };
+    let keep = lines.length;
+    while (keep > 0 && lengthOf(keep) > maxChars)
+        keep -= 1;
+    let text;
+    let truncated = outline.truncated || keep < lines.length;
+    if (keep === 0 && lengthOf(0) > maxChars) {
+        // Not even the header fits: hand back what does.
+        text = lines[0].slice(0, maxChars);
+        truncated = true;
+    }
+    else {
+        const tail = tailOf(keep);
+        const body = lines.slice(0, keep).join("\n");
+        text = tail === undefined ? body : body ? `${body}\n${tail}` : tail;
+    }
+    return Object.freeze({
+        format,
+        pageCount,
+        elementCount: outline.nodeCount,
+        text,
+        truncated,
+    });
+}
+function describeNode(node, noun) {
+    const parts = [`[${node.id}]`];
+    if (node.pageIndex >= 0)
+        parts.push(`${noun} ${node.pageIndex + 1}`);
+    parts.push(node.kind);
+    if (node.label !== undefined)
+        parts.push(`"${node.label.replaceAll('"', "'")}"`);
+    const flags = [
+        ...(node.readOnlyReason ? [`read-only: ${node.readOnlyReason}`] : []),
+        ...(node.hidden ? ["hidden"] : []),
+    ];
+    if (flags.length > 0)
+        parts.push(`(${flags.join(", ")})`);
+    let line = parts.join(" ");
+    if (node.text)
+        line += `: ${foldText(node.text)}${node.truncated ? "…" : ""}`;
+    else if (node.truncated)
+        line += ": …";
+    return line;
+}
+/** One line of text: tabs as cell separators, breaks marked, other controls blanked. */
+export function foldText(text) {
+    return text
+        .replaceAll("\r\n", "\n")
+        .replaceAll("\t", " | ")
+        .replaceAll(/[\n\r\u2028\u2029\v\f]/g, " ⏎ ")
+        .replaceAll(/[\u0000-\u0008\u000e-\u001f\u007f]/g, " ");
+}
+function count(value, noun) {
+    return `${value} ${noun}${value === 1 ? "" : "s"}`;
+}

package/dist/edit/ai/targets.d.ts

@@ -0,0 +1,16 @@
+import type { EditElement, EditFindOptions, ElementQuery, ReadOptions, ReadResult, TextTarget } from "../types.js";
+import type { TargetCandidate, TargetQuery } from "./types.js";
+/** What resolution needs of a session: its elements and its exact text search. */
+export interface TargetSource {
+    getElements(query?: ElementQuery, options?: ReadOptions): Promise<ReadResult<EditElement>>;
+    findText(query: string, options?: EditFindOptions): Promise<ReadResult<TextTarget>>;
+}
+export declare function resolveTargets(session: TargetSource, query: TargetQuery, options?: ReadOptions): Promise<ReadResult<TargetCandidate>>;
+/** Whitespace runs to one space, quotes and dashes to ASCII, NFKC, case folded; offsets kept. */
+export declare function foldWithMap(text: string): {
+    readonly text: string;
+    readonly starts: readonly number[];
+    readonly ends: readonly number[];
+};
+/** The matched text with a little context on each side, on one line. */
+export declare function snippetOf(text: string, start: number, end: number): string;

package/dist/edit/ai/targets.js

@@ -0,0 +1,309 @@
+import { alignFuzzyPassage } from "../../fuzzy-alignment.js";
+import { DEFAULT_FUZZY_SEARCH_OPTIONS, FuzzyPageIndex, } from "../../fuzzy-search.js";
+import { graphemeSegments, normalizeSearchText } from "../../search-text.js";
+import { foldText } from "./outline.js";
+/*
+ * A model names what it wants to edit by quoting it ("the sentence that
+ * starts with…"), by citing it with a page, or by kind ("the first table on
+ * slide 3"). Resolution turns that into element ids and ranges in named
+ * steps, so a host knows how much to trust a candidate: the engine's exact
+ * search first, then a match with whitespace, case, quotes and compatibility
+ * forms folded, then the viewer's fuzzy citation matching over the
+ * elements' text, and a kind lookup when there is no text at all.
+ */
+const DEFAULT_MAX_RESULTS = 5;
+const SNIPPET_CONTEXT = 40;
+/** Fuzzy candidates score from this down to 0.5 at the loosest accepted edit ratio. */
+const FUZZY_TOP = 0.85;
+export async function resolveTargets(session, query, options = {}) {
+    const needle = (query.text ?? query.citation?.text ?? "").trim();
+    const hint = query.citation?.pageNumber !== undefined &&
+        Number.isFinite(query.citation.pageNumber)
+        ? Math.max(0, Math.trunc(query.citation.pageNumber) - 1)
+        : undefined;
+    const limit = Math.max(1, Math.trunc(query.maxResults ?? DEFAULT_MAX_RESULTS));
+    const readOptions = options.signal ? { signal: options.signal } : {};
+    const elementQuery = query.pageIndex === undefined ? {} : { pageIndex: query.pageIndex };
+    // The two reads queue one after the other; a change landing between them
+    // would make the elements stale, so they are read again until they agree.
+    let elements;
+    let found;
+    for (let attempt = 0;; attempt += 1) {
+        elements = await session.getElements(elementQuery, readOptions);
+        found = needle
+            ? await session.findText(needle, {
+                ...readOptions,
+                ...(query.pageIndex === undefined
+                    ? {}
+                    : { pageRange: [query.pageIndex, query.pageIndex] }),
+            })
+            : undefined;
+        if (!found || found.revision === elements.revision || attempt >= 2)
+            break;
+    }
+    const envelope = {
+        sessionId: (found ?? elements).sessionId,
+        revision: (found ?? elements).revision,
+    };
+    const allowed = allowedElements(elements.items, query);
+    const byId = new Map(allowed.map((element) => [element.id, element]));
+    let candidates = [];
+    if (needle && found) {
+        candidates = exactCandidates(found.items, byId);
+        if (candidates.length === 0) {
+            const corpus = buildCorpus(allowed);
+            candidates = normalizedCandidates(corpus, needle);
+            if (candidates.length === 0)
+                candidates = fuzzyCandidates(corpus, needle);
+        }
+    }
+    else if (!needle && query.kinds && query.kinds.length > 0) {
+        candidates = allowed.map((element) => ({
+            elementId: element.id,
+            pageIndex: element.pageIndex,
+            score: 0.5,
+            reason: "kind-only",
+            snippet: snippetOf(element.text ?? "", 0, 0),
+        }));
+    }
+    if (hint !== undefined)
+        candidates = candidates
+            .map((candidate, index) => ({ candidate, index }))
+            .sort((a, b) => distance(a.candidate.pageIndex, hint) -
+            distance(b.candidate.pageIndex, hint) || a.index - b.index)
+            .map((entry) => entry.candidate);
+    return Object.freeze({
+        ...envelope,
+        items: Object.freeze(candidates.slice(0, limit).map((candidate) => Object.freeze(candidate))),
+    });
+}
+function distance(pageIndex, hint) {
+    return pageIndex < 0 ? Number.POSITIVE_INFINITY : Math.abs(pageIndex - hint);
+}
+/** The elements a query may name: by kind, inside `within`, on the page. */
+function allowedElements(elements, query) {
+    let allowed = elements;
+    if (query.within !== undefined) {
+        const inside = new Set([query.within]);
+        // Children follow their parents in reading order, so one pass closes
+        // the set; a second catches a child listed before its parent.
+        for (let pass = 0; pass < 2; pass += 1)
+            for (const element of elements)
+                if (element.parentId !== undefined && inside.has(element.parentId))
+                    inside.add(element.id);
+        allowed = allowed.filter((element) => inside.has(element.id));
+    }
+    if (query.kinds) {
+        const kinds = new Set(query.kinds);
+        allowed = allowed.filter((element) => kinds.has(element.kind));
+    }
+    return allowed;
+}
+function exactCandidates(targets, byId) {
+    const out = [];
+    for (const target of targets) {
+        if (target.elementIds.length === 0)
+            continue;
+        if (!target.elementIds.every((id) => byId.has(id)))
+            continue;
+        const first = target.ranges[0];
+        const last = target.ranges.at(-1);
+        const element = byId.get(target.elementIds[0]);
+        const range = first && last ? { start: first.start, end: last.end } : undefined;
+        out.push({
+            elementId: element.id,
+            ...(range && !coversWhole(range, element) ? { range } : {}),
+            pageIndex: target.pageIndex,
+            score: 1,
+            reason: "exact",
+            snippet: range &&
+                element.text !== undefined &&
+                range.start.elementId === element.id
+                ? snippetOf(element.text, range.start.offset, range.end.elementId === element.id
+                    ? range.end.offset
+                    : element.text.length)
+                : foldText(target.text),
+        });
+    }
+    return out;
+}
+function coversWhole(range, element) {
+    return (range.start.elementId === element.id &&
+        range.end.elementId === element.id &&
+        range.start.offset === 0 &&
+        range.end.offset === (element.text?.length ?? 0));
+}
+/**
+ * The elements' text in reading order, cut into chunks that never span a
+ * page. A container whose children carry text (a Word table, whose cells are
+ * paragraphs) contributes nothing itself, so a match names the cell.
+ */
+function buildCorpus(elements) {
+    const textChildren = new Set();
+    for (const element of elements)
+        if (element.parentId !== undefined && element.text)
+            textChildren.add(element.parentId);
+    const chunks = [];
+    let pageIndex;
+    let text = "";
+    let segments = [];
+    const flush = () => {
+        if (segments.length > 0 && pageIndex !== undefined)
+            chunks.push({ pageIndex, text, segments });
+        text = "";
+        segments = [];
+    };
+    const budget = DEFAULT_FUZZY_SEARCH_OPTIONS.maxPageTextLength;
+    for (const element of elements) {
+        if (!element.text || textChildren.has(element.id))
+            continue;
+        if (pageIndex !== element.pageIndex ||
+            text.length + 1 + element.text.length > budget) {
+            flush();
+            pageIndex = element.pageIndex;
+        }
+        const start = text.length === 0 ? 0 : text.length + 1;
+        text = text.length === 0 ? element.text : `${text} ${element.text}`;
+        segments.push({ element, start, end: start + element.text.length });
+    }
+    flush();
+    return chunks;
+}
+/** Whitespace runs to one space, quotes and dashes to ASCII, NFKC, case folded; offsets kept. */
+export function foldWithMap(text) {
+    const out = [];
+    const starts = [];
+    const ends = [];
+    let spaceStart = -1;
+    let spaceEnd = -1;
+    for (const segment of graphemeSegments(text)) {
+        const value = foldPunctuation(normalizeSearchText(segment.value));
+        if (value.length === 0)
+            continue;
+        if (/^\s+$/u.test(value)) {
+            if (out.length === 0)
+                continue;
+            if (spaceStart < 0)
+                spaceStart = segment.start;
+            spaceEnd = segment.end;
+            continue;
+        }
+        if (spaceStart >= 0) {
+            out.push(" ");
+            starts.push(spaceStart);
+            ends.push(spaceEnd);
+            spaceStart = -1;
+        }
+        for (const char of value) {
+            out.push(char);
+            starts.push(segment.start);
+            ends.push(segment.end);
+        }
+    }
+    return { text: out.join(""), starts, ends };
+}
+const PUNCTUATION = {
+    "‘": "'",
+    "’": "'",
+    "‚": "'",
+    "‛": "'",
+    "′": "'",
+    "“": '"',
+    "”": '"',
+    "„": '"',
+    "‟": '"',
+    "″": '"',
+    "«": '"',
+    "»": '"',
+    "‐": "-",
+    "‑": "-",
+    "‒": "-",
+    "–": "-",
+    "—": "-",
+    "―": "-",
+    "−": "-",
+    "…": "...",
+    " ": " ",
+};
+function foldPunctuation(value) {
+    let out = "";
+    for (const char of value)
+        out += PUNCTUATION[char] ?? char;
+    return out;
+}
+function normalizedCandidates(corpus, needle) {
+    const pattern = foldWithMap(needle).text;
+    if (pattern.length === 0)
+        return [];
+    const out = [];
+    for (const chunk of corpus) {
+        const folded = foldWithMap(chunk.text);
+        let from = 0;
+        while (from <= folded.text.length - pattern.length) {
+            const at = folded.text.indexOf(pattern, from);
+            if (at < 0)
+                break;
+            const start = folded.starts[at];
+            const end = folded.ends[at + pattern.length - 1];
+            const candidate = candidateOf(chunk, start, end, 0.9, "normalized");
+            if (candidate)
+                out.push(candidate);
+            from = at + Math.max(1, pattern.length);
+        }
+    }
+    return out;
+}
+function fuzzyCandidates(corpus, needle) {
+    if (corpus.length === 0)
+        return [];
+    const fuzzy = DEFAULT_FUZZY_SEARCH_OPTIONS;
+    const pattern = needle.slice(0, fuzzy.maxQueryLength);
+    const pages = corpus.map((chunk, index) => ({
+        pageIndex: index,
+        text: chunk.text,
+    }));
+    const index = new FuzzyPageIndex(pages, fuzzy, false);
+    const out = [];
+    for (const match of index.search(pattern, fuzzy.maxScore)) {
+        const chunk = corpus[match.pageIndex];
+        const passage = alignFuzzyPassage(chunk.text, pattern, false, fuzzy.maxScore);
+        if (!passage)
+            continue;
+        const ratio = passage.length === 0 ? 0 : passage.cost / passage.length;
+        const score = FUZZY_TOP - (FUZZY_TOP - 0.5) * Math.min(1, ratio / fuzzy.maxScore);
+        const candidate = candidateOf(chunk, passage.start, passage.end, Math.round(score * 100) / 100, "fuzzy");
+        if (candidate)
+            out.push(candidate);
+    }
+    return out;
+}
+/** The candidate for a span of a chunk: the first element it touches, with a range unless it covers the whole element. */
+function candidateOf(chunk, start, end, score, reason) {
+    const touched = chunk.segments.filter((segment) => segment.end > start && segment.start < end);
+    const first = touched[0];
+    const last = touched.at(-1);
+    if (!first || !last)
+        return undefined;
+    const startOffset = Math.max(0, start - first.start);
+    const endOffset = Math.min(last.end, end) - last.start;
+    const range = {
+        start: { elementId: first.element.id, offset: startOffset },
+        end: { elementId: last.element.id, offset: endOffset },
+    };
+    return {
+        elementId: first.element.id,
+        ...(coversWhole(range, first.element) ? {} : { range }),
+        pageIndex: first.element.pageIndex,
+        score,
+        reason,
+        snippet: snippetOf(chunk.text, start, end),
+    };
+}
+/** The matched text with a little context on each side, on one line. */
+export function snippetOf(text, start, end) {
+    const from = Math.max(0, start - SNIPPET_CONTEXT);
+    const to = Math.min(text.length, end + SNIPPET_CONTEXT);
+    const head = from > 0 ? "…" : "";
+    const tail = to < text.length ? "…" : "";
+    return `${head}${foldText(text.slice(from, to))}${tail}`;
+}

package/dist/edit/ai/tools.d.ts

@@ -0,0 +1,28 @@
+import type { ApplyOptions, EditableFormat, EditElement, EditOperation, EditReceipt, EditState, HistoryOptions, OperationSchemaSet, ReadItem, ReadOptions, ReadResult } from "../types.js";
+import type { DescribeOptions, DocumentDescription, EditCheckpoint, OutlineOptions, OutlineResult, TargetCandidate, TargetQuery, ToolCall, ToolCallOptions, ToolResult, ToolSet } from "./types.js";
+export declare const TOOL_SET_VERSION = 1;
+/** What the tools need of a session. */
+export interface ToolSource {
+    readonly format: EditableFormat;
+    readonly state: EditState;
+    readonly schemas: OperationSchemaSet;
+    describe(options?: DescribeOptions): Promise<ReadItem<DocumentDescription>>;
+    getOutline(options?: OutlineOptions): Promise<OutlineResult>;
+    resolveTargets(query: TargetQuery, options?: ReadOptions): Promise<ReadResult<TargetCandidate>>;
+    getElement(id: string, options?: ReadOptions): Promise<ReadItem<EditElement>>;
+    applyJson(operations: readonly EditOperation[], options?: ApplyOptions): Promise<EditReceipt>;
+    undo(options?: HistoryOptions): Promise<EditReceipt>;
+    createCheckpoint(label?: string): Promise<EditCheckpoint>;
+    listCheckpoints(): readonly EditCheckpoint[];
+    restoreCheckpoint(id: string, options?: HistoryOptions): Promise<EditReceipt>;
+}
+/** The tool definitions of a format, built from its operation schemas. */
+export declare function buildToolSet(format: EditableFormat, schemas: OperationSchemaSet): ToolSet;
+/** Runs one tool call on a session. */
+export declare function callTool(session: ToolSource, tools: ToolSet, call: ToolCall, options?: ToolCallOptions): Promise<ToolResult>;
+/**
+ * What a batch did, in the format's words: one sentence per operation with
+ * the id it created when the receipt names one per creating operation,
+ * then what else the receipt reports.
+ */
+export declare function describeReceipt(format: EditableFormat, operations: readonly EditOperation[], receipt: EditReceipt): string;