@superdoc/sdk 2.5.0 → 2.7.0

package/dist/agent/doc-snapshot.cjs

@@ -18,6 +18,62 @@ async function safeCall(thunk, fallback, onError) {
         return fallback;
     }
 }
+/**
+ * Read a specific block's per-run formatting via query.match, matching STRICTLY
+ * by nodeId. When the text is ambiguous (multiple matches) and none matches the
+ * requested nodeId, returns [] rather than guessing a different block — so a
+ * duplicate-text sibling can never contribute the wrong runs. The single-match
+ * fallback is used only when there is exactly one candidate (unambiguous).
+ */
+async function matchRunsForBlock(queryFn, text, nodeId) {
+    const res = asRecord(await queryFn({ select: { type: 'text', pattern: text } }));
+    const items = (Array.isArray(res?.items) ? res.items : []).map(asRecord);
+    const match = items.find((m) => asString(asRecord(m?.address)?.nodeId) === nodeId) ?? (items.length === 1 ? items[0] : null);
+    if (!match)
+        return [];
+    const blocksArr = Array.isArray(match.blocks) ? match.blocks.map(asRecord) : [];
+    const block = blocksArr.find((b) => asString(b?.blockId) === nodeId) ?? (blocksArr.length === 1 ? blocksArr[0] : null);
+    if (!block)
+        return [];
+    const rawRuns = Array.isArray(block.runs) ? block.runs : [];
+    return rawRuns.map(projectRun).filter((r) => r != null);
+}
+/**
+ * Project one raw query.match run into a compact SnapshotRun. Uses the
+ * EFFECTIVE (resolved) mark state and emits booleans only when true. Skips a
+ * default-black color so only meaningful colors surface.
+ */
+function projectRun(raw) {
+    const rec = asRecord(raw);
+    if (!rec)
+        return null;
+    const range = asRecord(rec.range);
+    const styles = asRecord(rec.styles);
+    const eff = asRecord(styles?.effective);
+    const run = {
+        start: asNumber(range?.start),
+        end: asNumber(range?.end),
+        text: asString(rec.text),
+    };
+    if (eff?.bold === true)
+        run.bold = true;
+    if (eff?.italic === true)
+        run.italic = true;
+    if (eff?.underline === true)
+        run.underline = true;
+    if (eff?.strike === true)
+        run.strike = true;
+    const ff = asString(styles?.fontFamily);
+    if (ff)
+        run.fontFamily = ff;
+    const fs = asNumber(styles?.fontSizePt);
+    if (fs > 0)
+        run.fontSize = fs;
+    const color = asString(styles?.color);
+    if (color && color.toLowerCase() !== '#000000')
+        run.color = color;
+    return run;
+}
 function maybeMethod(api, path) {
     let cursor = api;
     for (const token of path) {
@@ -54,8 +110,68 @@ async function buildDocumentSnapshot(doc, options = {}) {
     const recordError = (section) => (err) => {
         diagnostics.push({ section, message: err instanceof Error ? err.message : String(err) });
     };
-    const blockOffset = Math.max(0, options.blockOffset ?? 0);
-    const blockLimit = options.blockLimit != null && options.blockLimit > 0 ? options.blockLimit : 1000;
+    let blockOffset = Math.max(0, options.blockOffset ?? 0);
+    let blockLimit = options.blockLimit != null && options.blockLimit > 0 ? options.blockLimit : 1000;
+    // findText: full-text scan server-side, serialize only ordinals + previews,
+    // and (unless the caller pinned blockOffset) center the block window on the
+    // first match so one call both LOCATES and READS the target section.
+    let finds;
+    if (typeof options.findText === 'string' && options.findText.trim().length > 0) {
+        const scanFn = maybeMethod(doc, ['blocks', 'list']);
+        if (scanFn) {
+            // Paginated scan with a hard cap: bounded bridge payloads per page, and
+            // an explicit truncated flag instead of a silently-partial `total`.
+            const SCAN_PAGE = 2000;
+            const SCAN_CAP = 20000;
+            const needle = options.findText.toLowerCase();
+            const findLimit = options.findLimit != null && options.findLimit > 0 ? options.findLimit : 8;
+            const matches = [];
+            let scanned = 0;
+            let truncated = false;
+            for (let pageOffset = 0; pageOffset < SCAN_CAP; pageOffset += SCAN_PAGE) {
+                const scanRaw = await safeCall(() => scanFn({ offset: pageOffset, limit: SCAN_PAGE, includeText: true }), null, recordError('blocks.findText'));
+                const scanRec = asRecord(scanRaw);
+                const scanBlocks = Array.isArray(scanRec?.blocks) ? scanRec.blocks : [];
+                scanBlocks.forEach((b, i) => {
+                    const rec = asRecord(b) ?? {};
+                    const text = asString(rec.text);
+                    if (!text || !text.toLowerCase().includes(needle))
+                        return;
+                    matches.push({
+                        ordinal: asNumber(rec.ordinal, pageOffset + i) + 1,
+                        nodeId: asString(rec.nodeId),
+                        nodeType: asString(rec.nodeType, 'paragraph'),
+                        preview: text.slice(0, 100),
+                        index: asNumber(rec.ordinal, pageOffset + i),
+                    });
+                });
+                scanned += scanBlocks.length;
+                const totalBlocksReported = explicitCount(scanRec ?? {}, 'total');
+                if (scanBlocks.length < SCAN_PAGE)
+                    break; // last page
+                if (totalBlocksReported != null && scanned >= totalBlocksReported)
+                    break;
+                if (pageOffset + SCAN_PAGE >= SCAN_CAP) {
+                    truncated = true;
+                    break;
+                }
+            }
+            finds = {
+                query: options.findText,
+                total: matches.length,
+                ...(truncated ? { truncated: true } : {}),
+                scannedBlocks: scanned,
+                matches: matches.slice(0, findLimit).map(({ index: _index, nodeId, ...m }) => ({
+                    ...m,
+                    ...(nodeId ? { nodeId } : {}),
+                })),
+            };
+            if (matches.length > 0 && options.blockOffset == null) {
+                blockOffset = Math.max(0, matches[0].index - 2);
+                blockLimit = options.blockLimit != null && options.blockLimit > 0 ? options.blockLimit : 12;
+            }
+        }
+    }
     const blockTextLimit = options.blockTextLimit != null && Number.isFinite(options.blockTextLimit) && options.blockTextLimit > 0
         ? options.blockTextLimit
         : null;
@@ -110,6 +226,7 @@ async function buildDocumentSnapshot(doc, options = {}) {
             permissionRanges: [],
             images: [],
             diagnostics,
+            ...(finds ? { finds } : {}),
         };
     }
     // Blocks
@@ -162,6 +279,35 @@ async function buildDocumentSnapshot(doc, options = {}) {
         blocks = blocks.filter((block) => (fullBlockText.get(block) ?? '').trim().length > 0 ||
             (block.nodeType !== 'paragraph' && block.nodeType !== 'listItem'));
     }
+    // Optionally enrich body blocks with per-run formatting so a reader can
+    // detect a section's intra-paragraph pattern (bold lead-ins, italic terms)
+    // and replicate it on an inserted paragraph. Opt-in and bounded — meant to
+    // be combined with a narrow blockOffset/blockLimit window. Runs before the
+    // dropTextPreview remap so fullBlockText lookups still hit.
+    if (options.includeBlockRuns && includeBlocksInSnapshot) {
+        const queryFn = maybeMethod(doc, ['query', 'match']);
+        if (queryFn) {
+            const cap = typeof options.blockRunsLimit === 'number' && options.blockRunsLimit > 0
+                ? Math.floor(options.blockRunsLimit)
+                : 30;
+            let enriched = 0;
+            for (const block of blocks) {
+                if (enriched >= cap)
+                    break;
+                if (block.nodeType !== 'paragraph' && block.nodeType !== 'listItem' && block.nodeType !== 'heading')
+                    continue;
+                // Match on the FULL block text (the snapshot copy may be truncated by
+                // blockTextLimit, and a partial pattern would misreport run offsets).
+                const text = (fullBlockText.get(block) ?? block.text).trim();
+                if (!text || !block.nodeId)
+                    continue;
+                enriched += 1;
+                const runs = await safeCall(() => matchRunsForBlock(queryFn, text, block.nodeId), null, recordError('blocks.runs'));
+                if (runs && runs.length > 0)
+                    block.runs = runs;
+            }
+        }
+    }
     if (includeBlocksInSnapshot && options.dropTextPreview === true) {
         blocks = blocks.map((block) => ({ ...block, textPreview: null }));
     }
@@ -194,6 +340,32 @@ async function buildDocumentSnapshot(doc, options = {}) {
         });
     }
     const lists = [...listsById.values()];
+    // Optionally enrich list items with per-run formatting so a reader can detect
+    // and replicate an intra-item pattern. Costs one query.match per item, so it
+    // is opt-in and bounded. The block's runs tile the matched text in offset
+    // order; we match by the item's own nodeId to disambiguate duplicate text.
+    if (options.includeListItemRuns && includesDomain(requestedDomains, 'lists')) {
+        const queryFn = maybeMethod(doc, ['query', 'match']);
+        if (queryFn) {
+            const cap = typeof options.listItemRunsLimit === 'number' && options.listItemRunsLimit > 0
+                ? Math.floor(options.listItemRunsLimit)
+                : 40;
+            let enriched = 0;
+            outer: for (const list of listsById.values()) {
+                for (const item of list.items) {
+                    if (enriched >= cap)
+                        break outer;
+                    const text = item.text?.trim();
+                    if (!text || !item.nodeId)
+                        continue;
+                    enriched += 1;
+                    const runs = await safeCall(() => matchRunsForBlock(queryFn, text, item.nodeId), null, recordError('lists.itemRuns'));
+                    if (runs && runs.length > 0)
+                        item.runs = runs;
+                }
+            }
+        }
+    }
     // Tables: derive table block list from `blocks`, then query shape per table.
     const tableBlocks = normalizedBlocks.filter((b) => b.nodeType === 'table');
     const precedingBlocksRaw = blockOffset > 0 && includesDomain(requestedDomains, 'tables') && tableBlocks.length > 0 && blocksFn
@@ -273,6 +445,30 @@ async function buildDocumentSnapshot(doc, options = {}) {
             table.cells = [...cellMap.values()].sort((left, right) => left.rowIndex - right.rowIndex || left.columnIndex - right.columnIndex);
         }
     }
+    // Optionally enrich table cells with per-run formatting (opt-in; one
+    // query.match per cell, bounded) so a reader can match a cell's pattern.
+    if (options.includeTableCellRuns && includesDomain(requestedDomains, 'tables')) {
+        const queryFn = maybeMethod(doc, ['query', 'match']);
+        if (queryFn) {
+            const cap = typeof options.tableCellRunsLimit === 'number' && options.tableCellRunsLimit > 0
+                ? Math.floor(options.tableCellRunsLimit)
+                : 60;
+            let enriched = 0;
+            outer: for (const table of tables) {
+                for (const cell of table.cells) {
+                    if (enriched >= cap)
+                        break outer;
+                    const text = cell.text?.trim();
+                    if (!text || !cell.nodeId)
+                        continue;
+                    enriched += 1;
+                    const runs = await safeCall(() => matchRunsForBlock(queryFn, text, cell.nodeId), null, recordError('tables.cellRuns'));
+                    if (runs && runs.length > 0)
+                        cell.runs = runs;
+                }
+            }
+        }
+    }
     // Comments
     const commentsFn = maybeMethod(doc, ['comments', 'list']);
     const commentsRaw = includesDomain(requestedDomains, 'comments') && commentsFn
@@ -549,6 +745,7 @@ async function buildDocumentSnapshot(doc, options = {}) {
         permissionRanges,
         images,
         diagnostics,
+        ...(finds ? { finds } : {}),
     };
 }
 /**
@@ -686,4 +883,5 @@ function resolveSnapshotSelector(snapshot, selector) {
 
 exports.AmbiguousSelectorError = AmbiguousSelectorError;
 exports.buildDocumentSnapshot = buildDocumentSnapshot;
+exports.matchRunsForBlock = matchRunsForBlock;
 exports.resolveSnapshotSelector = resolveSnapshotSelector;

package/dist/agent/doc-snapshot.d.ts

@@ -38,6 +38,29 @@ export type SnapshotBlock = {
         path: number[] | null;
         kind: string | null;
     } | null;
+    /** Per-run formatting, present only when inspect was asked to include it. */
+    runs?: ReadonlyArray<SnapshotRun>;
+};
+/**
+ * One inline run within a list item, in offset order (runs tile the item text).
+ * Marks are the EFFECTIVE (resolved) state — what the run visually IS — so the
+ * agent can read a formatting pattern across sibling items (e.g. "first word
+ * plain, second word italic") and reproduce it on a new item. Boolean marks are
+ * emitted only when true to keep the payload compact; a run with no marks is
+ * plain. Sourced from query.match's per-run style projection.
+ */
+export type SnapshotRun = {
+    start: number;
+    end: number;
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strike?: boolean;
+    fontFamily?: string;
+    /** Point size. */
+    fontSize?: number;
+    color?: string;
 };
 export type SnapshotList = {
     listId: string;
@@ -47,6 +70,8 @@ export type SnapshotList = {
         ordinal: number;
         level: number;
         text: string;
+        /** Per-run formatting, present only when inspect was asked to include it. */
+        runs?: ReadonlyArray<SnapshotRun>;
     }>;
 };
 export type SnapshotTable = {
@@ -59,6 +84,8 @@ export type SnapshotTable = {
         columnIndex: number;
         text: string;
         nodeId?: string;
+        /** Per-run formatting, present only when inspect was asked to include it. */
+        runs?: ReadonlyArray<SnapshotRun>;
     }>;
 };
 export type SnapshotComment = {
@@ -180,7 +207,30 @@ export type DocumentSnapshot = {
     permissionRanges: readonly SnapshotPermissionRange[];
     images: readonly SnapshotImage[];
     diagnostics: readonly SnapshotDiagnostic[];
+    /** Present when the snapshot was built with `findText` — see SnapshotOptions. */
+    finds?: {
+        query: string;
+        /** Matches within the scanned range; see truncated/scannedBlocks. */
+        total: number;
+        /** True when the document has more blocks than the scan cap covered. */
+        truncated?: boolean;
+        scannedBlocks?: number;
+        matches: ReadonlyArray<{
+            ordinal: number;
+            nodeId?: string;
+            nodeType: string;
+            preview: string;
+        }>;
+    };
 };
+/**
+ * Read a specific block's per-run formatting via query.match, matching STRICTLY
+ * by nodeId. When the text is ambiguous (multiple matches) and none matches the
+ * requested nodeId, returns [] rather than guessing a different block — so a
+ * duplicate-text sibling can never contribute the wrong runs. The single-match
+ * fallback is used only when there is exactly one candidate (unambiguous).
+ */
+export declare function matchRunsForBlock(queryFn: (args: Record<string, unknown>) => Promise<unknown>, text: string, nodeId: string): Promise<SnapshotRun[]>;
 type SnapshotOptions = {
     countsOnly?: boolean;
     includeDomains?: readonly SnapshotDomain[];
@@ -201,6 +251,17 @@ type SnapshotOptions = {
      */
     blockOffset?: number;
     blockLimit?: number;
+    /**
+     * Locate blocks whose text contains this string (case-insensitive) BEFORE
+     * windowing. The scan runs server-side over the full block list; only the
+     * match ordinals + short previews serialize back (snapshot.finds), and when
+     * the caller did not pin blockOffset the block window auto-centers on the
+     * first match. This is the section-jump primitive for large documents —
+     * one findText inspect replaces a linear sweep of wide windows.
+     */
+    findText?: string;
+    /** Cap on reported findText matches (default 8). */
+    findLimit?: number;
     /**
      * Drop empty paragraphs/list-items from the returned blocks. A real DOCX is
      * ~40% empty spacer paragraphs that carry full JSON overhead but no reading
@@ -214,6 +275,36 @@ type SnapshotOptions = {
      * `text`.
      */
     dropTextPreview?: boolean;
+    /**
+     * Attach per-run formatting (`items[].runs`) to the returned list items, so a
+     * reader can detect an intra-item formatting pattern (which segment is bold/
+     * italic, the font/size) and replicate it on a new item. Off by default: it
+     * costs one query.match per list item, so only request it when matching a
+     * list's formatting matters. Bounded by `listItemRunsLimit`.
+     */
+    includeListItemRuns?: boolean;
+    /** Max list items to enrich with runs when includeListItemRuns is set (default 40). */
+    listItemRunsLimit?: number;
+    /**
+     * Attach per-run formatting (`cells[].runs`) to returned table cells, so a
+     * reader can match a cell's formatting pattern. OFF by default: tables can be
+     * large and it costs one query.match per cell, so only request it when cell
+     * styling actually matters. Bounded by `tableCellRunsLimit`.
+     */
+    includeTableCellRuns?: boolean;
+    /** Max table cells to enrich with runs when includeTableCellRuns is set (default 60). */
+    tableCellRunsLimit?: number;
+    /**
+     * Attach per-run formatting (`blocks[].runs`) to the returned body blocks so
+     * a reader can detect a section's formatting pattern (e.g. lettered clauses
+     * with a bold "(m)" lead-in) and replicate it on an inserted paragraph. OFF
+     * by default: it costs one query.match per block, so request it with a
+     * narrow blockOffset/blockLimit window around the insertion target. Bounded
+     * by `blockRunsLimit`.
+     */
+    includeBlockRuns?: boolean;
+    /** Max blocks to enrich with runs when includeBlockRuns is set (default 30). */
+    blockRunsLimit?: number;
 };
 /**
  * Build a deterministic snapshot of a document. The snapshot uses only

package/dist/agent/doc-snapshot.js

@@ -16,6 +16,62 @@ async function safeCall(thunk, fallback, onError) {
         return fallback;
     }
 }
+/**
+ * Read a specific block's per-run formatting via query.match, matching STRICTLY
+ * by nodeId. When the text is ambiguous (multiple matches) and none matches the
+ * requested nodeId, returns [] rather than guessing a different block — so a
+ * duplicate-text sibling can never contribute the wrong runs. The single-match
+ * fallback is used only when there is exactly one candidate (unambiguous).
+ */
+export async function matchRunsForBlock(queryFn, text, nodeId) {
+    const res = asRecord(await queryFn({ select: { type: 'text', pattern: text } }));
+    const items = (Array.isArray(res?.items) ? res.items : []).map(asRecord);
+    const match = items.find((m) => asString(asRecord(m?.address)?.nodeId) === nodeId) ?? (items.length === 1 ? items[0] : null);
+    if (!match)
+        return [];
+    const blocksArr = Array.isArray(match.blocks) ? match.blocks.map(asRecord) : [];
+    const block = blocksArr.find((b) => asString(b?.blockId) === nodeId) ?? (blocksArr.length === 1 ? blocksArr[0] : null);
+    if (!block)
+        return [];
+    const rawRuns = Array.isArray(block.runs) ? block.runs : [];
+    return rawRuns.map(projectRun).filter((r) => r != null);
+}
+/**
+ * Project one raw query.match run into a compact SnapshotRun. Uses the
+ * EFFECTIVE (resolved) mark state and emits booleans only when true. Skips a
+ * default-black color so only meaningful colors surface.
+ */
+function projectRun(raw) {
+    const rec = asRecord(raw);
+    if (!rec)
+        return null;
+    const range = asRecord(rec.range);
+    const styles = asRecord(rec.styles);
+    const eff = asRecord(styles?.effective);
+    const run = {
+        start: asNumber(range?.start),
+        end: asNumber(range?.end),
+        text: asString(rec.text),
+    };
+    if (eff?.bold === true)
+        run.bold = true;
+    if (eff?.italic === true)
+        run.italic = true;
+    if (eff?.underline === true)
+        run.underline = true;
+    if (eff?.strike === true)
+        run.strike = true;
+    const ff = asString(styles?.fontFamily);
+    if (ff)
+        run.fontFamily = ff;
+    const fs = asNumber(styles?.fontSizePt);
+    if (fs > 0)
+        run.fontSize = fs;
+    const color = asString(styles?.color);
+    if (color && color.toLowerCase() !== '#000000')
+        run.color = color;
+    return run;
+}
 function maybeMethod(api, path) {
     let cursor = api;
     for (const token of path) {
@@ -52,8 +108,68 @@ export async function buildDocumentSnapshot(doc, options = {}) {
     const recordError = (section) => (err) => {
         diagnostics.push({ section, message: err instanceof Error ? err.message : String(err) });
     };
-    const blockOffset = Math.max(0, options.blockOffset ?? 0);
-    const blockLimit = options.blockLimit != null && options.blockLimit > 0 ? options.blockLimit : 1000;
+    let blockOffset = Math.max(0, options.blockOffset ?? 0);
+    let blockLimit = options.blockLimit != null && options.blockLimit > 0 ? options.blockLimit : 1000;
+    // findText: full-text scan server-side, serialize only ordinals + previews,
+    // and (unless the caller pinned blockOffset) center the block window on the
+    // first match so one call both LOCATES and READS the target section.
+    let finds;
+    if (typeof options.findText === 'string' && options.findText.trim().length > 0) {
+        const scanFn = maybeMethod(doc, ['blocks', 'list']);
+        if (scanFn) {
+            // Paginated scan with a hard cap: bounded bridge payloads per page, and
+            // an explicit truncated flag instead of a silently-partial `total`.
+            const SCAN_PAGE = 2000;
+            const SCAN_CAP = 20000;
+            const needle = options.findText.toLowerCase();
+            const findLimit = options.findLimit != null && options.findLimit > 0 ? options.findLimit : 8;
+            const matches = [];
+            let scanned = 0;
+            let truncated = false;
+            for (let pageOffset = 0; pageOffset < SCAN_CAP; pageOffset += SCAN_PAGE) {
+                const scanRaw = await safeCall(() => scanFn({ offset: pageOffset, limit: SCAN_PAGE, includeText: true }), null, recordError('blocks.findText'));
+                const scanRec = asRecord(scanRaw);
+                const scanBlocks = Array.isArray(scanRec?.blocks) ? scanRec.blocks : [];
+                scanBlocks.forEach((b, i) => {
+                    const rec = asRecord(b) ?? {};
+                    const text = asString(rec.text);
+                    if (!text || !text.toLowerCase().includes(needle))
+                        return;
+                    matches.push({
+                        ordinal: asNumber(rec.ordinal, pageOffset + i) + 1,
+                        nodeId: asString(rec.nodeId),
+                        nodeType: asString(rec.nodeType, 'paragraph'),
+                        preview: text.slice(0, 100),
+                        index: asNumber(rec.ordinal, pageOffset + i),
+                    });
+                });
+                scanned += scanBlocks.length;
+                const totalBlocksReported = explicitCount(scanRec ?? {}, 'total');
+                if (scanBlocks.length < SCAN_PAGE)
+                    break; // last page
+                if (totalBlocksReported != null && scanned >= totalBlocksReported)
+                    break;
+                if (pageOffset + SCAN_PAGE >= SCAN_CAP) {
+                    truncated = true;
+                    break;
+                }
+            }
+            finds = {
+                query: options.findText,
+                total: matches.length,
+                ...(truncated ? { truncated: true } : {}),
+                scannedBlocks: scanned,
+                matches: matches.slice(0, findLimit).map(({ index: _index, nodeId, ...m }) => ({
+                    ...m,
+                    ...(nodeId ? { nodeId } : {}),
+                })),
+            };
+            if (matches.length > 0 && options.blockOffset == null) {
+                blockOffset = Math.max(0, matches[0].index - 2);
+                blockLimit = options.blockLimit != null && options.blockLimit > 0 ? options.blockLimit : 12;
+            }
+        }
+    }
     const blockTextLimit = options.blockTextLimit != null && Number.isFinite(options.blockTextLimit) && options.blockTextLimit > 0
         ? options.blockTextLimit
         : null;
@@ -108,6 +224,7 @@ export async function buildDocumentSnapshot(doc, options = {}) {
             permissionRanges: [],
             images: [],
             diagnostics,
+            ...(finds ? { finds } : {}),
         };
     }
     // Blocks
@@ -160,6 +277,35 @@ export async function buildDocumentSnapshot(doc, options = {}) {
         blocks = blocks.filter((block) => (fullBlockText.get(block) ?? '').trim().length > 0 ||
             (block.nodeType !== 'paragraph' && block.nodeType !== 'listItem'));
     }
+    // Optionally enrich body blocks with per-run formatting so a reader can
+    // detect a section's intra-paragraph pattern (bold lead-ins, italic terms)
+    // and replicate it on an inserted paragraph. Opt-in and bounded — meant to
+    // be combined with a narrow blockOffset/blockLimit window. Runs before the
+    // dropTextPreview remap so fullBlockText lookups still hit.
+    if (options.includeBlockRuns && includeBlocksInSnapshot) {
+        const queryFn = maybeMethod(doc, ['query', 'match']);
+        if (queryFn) {
+            const cap = typeof options.blockRunsLimit === 'number' && options.blockRunsLimit > 0
+                ? Math.floor(options.blockRunsLimit)
+                : 30;
+            let enriched = 0;
+            for (const block of blocks) {
+                if (enriched >= cap)
+                    break;
+                if (block.nodeType !== 'paragraph' && block.nodeType !== 'listItem' && block.nodeType !== 'heading')
+                    continue;
+                // Match on the FULL block text (the snapshot copy may be truncated by
+                // blockTextLimit, and a partial pattern would misreport run offsets).
+                const text = (fullBlockText.get(block) ?? block.text).trim();
+                if (!text || !block.nodeId)
+                    continue;
+                enriched += 1;
+                const runs = await safeCall(() => matchRunsForBlock(queryFn, text, block.nodeId), null, recordError('blocks.runs'));
+                if (runs && runs.length > 0)
+                    block.runs = runs;
+            }
+        }
+    }
     if (includeBlocksInSnapshot && options.dropTextPreview === true) {
         blocks = blocks.map((block) => ({ ...block, textPreview: null }));
     }
@@ -192,6 +338,32 @@ export async function buildDocumentSnapshot(doc, options = {}) {
         });
     }
     const lists = [...listsById.values()];
+    // Optionally enrich list items with per-run formatting so a reader can detect
+    // and replicate an intra-item pattern. Costs one query.match per item, so it
+    // is opt-in and bounded. The block's runs tile the matched text in offset
+    // order; we match by the item's own nodeId to disambiguate duplicate text.
+    if (options.includeListItemRuns && includesDomain(requestedDomains, 'lists')) {
+        const queryFn = maybeMethod(doc, ['query', 'match']);
+        if (queryFn) {
+            const cap = typeof options.listItemRunsLimit === 'number' && options.listItemRunsLimit > 0
+                ? Math.floor(options.listItemRunsLimit)
+                : 40;
+            let enriched = 0;
+            outer: for (const list of listsById.values()) {
+                for (const item of list.items) {
+                    if (enriched >= cap)
+                        break outer;
+                    const text = item.text?.trim();
+                    if (!text || !item.nodeId)
+                        continue;
+                    enriched += 1;
+                    const runs = await safeCall(() => matchRunsForBlock(queryFn, text, item.nodeId), null, recordError('lists.itemRuns'));
+                    if (runs && runs.length > 0)
+                        item.runs = runs;
+                }
+            }
+        }
+    }
     // Tables: derive table block list from `blocks`, then query shape per table.
     const tableBlocks = normalizedBlocks.filter((b) => b.nodeType === 'table');
     const precedingBlocksRaw = blockOffset > 0 && includesDomain(requestedDomains, 'tables') && tableBlocks.length > 0 && blocksFn
@@ -271,6 +443,30 @@ export async function buildDocumentSnapshot(doc, options = {}) {
             table.cells = [...cellMap.values()].sort((left, right) => left.rowIndex - right.rowIndex || left.columnIndex - right.columnIndex);
         }
     }
+    // Optionally enrich table cells with per-run formatting (opt-in; one
+    // query.match per cell, bounded) so a reader can match a cell's pattern.
+    if (options.includeTableCellRuns && includesDomain(requestedDomains, 'tables')) {
+        const queryFn = maybeMethod(doc, ['query', 'match']);
+        if (queryFn) {
+            const cap = typeof options.tableCellRunsLimit === 'number' && options.tableCellRunsLimit > 0
+                ? Math.floor(options.tableCellRunsLimit)
+                : 60;
+            let enriched = 0;
+            outer: for (const table of tables) {
+                for (const cell of table.cells) {
+                    if (enriched >= cap)
+                        break outer;
+                    const text = cell.text?.trim();
+                    if (!text || !cell.nodeId)
+                        continue;
+                    enriched += 1;
+                    const runs = await safeCall(() => matchRunsForBlock(queryFn, text, cell.nodeId), null, recordError('tables.cellRuns'));
+                    if (runs && runs.length > 0)
+                        cell.runs = runs;
+                }
+            }
+        }
+    }
     // Comments
     const commentsFn = maybeMethod(doc, ['comments', 'list']);
     const commentsRaw = includesDomain(requestedDomains, 'comments') && commentsFn
@@ -547,6 +743,7 @@ export async function buildDocumentSnapshot(doc, options = {}) {
         permissionRanges,
         images,
         diagnostics,
+        ...(finds ? { finds } : {}),
     };
 }
 /**

package/dist/agent/runtime.cjs

@@ -153,7 +153,15 @@ function resolveDocMethod(doc, operationId) {
     return cursor;
 }
 async function agentInspect(doc, args = {}) {
-    return docSnapshot.buildDocumentSnapshot(doc, args);
+    // For the MODEL-facing inspect, expose each list item's per-run formatting BY
+    // DEFAULT so the agent always sees the intra-item pattern it must match when
+    // adding items. (Internal pre/post snapshots call buildDocumentSnapshot
+    // directly and stay cheap — this default lives only on the tool path.) Opt out
+    // with includeListItemRuns:false; countsOnly skips all domains anyway.
+    const listsInScope = !args.countsOnly &&
+        (!Array.isArray(args.includeDomains) || args.includeDomains.length === 0 || args.includeDomains.includes('lists'));
+    const effective = args.includeListItemRuns === undefined && listsInScope ? { ...args, includeListItemRuns: true } : args;
+    return docSnapshot.buildDocumentSnapshot(doc, effective);
 }
 function checkAgainstSnapshot(snapshot, check) {
     switch (check.kind) {

package/dist/agent/runtime.d.ts

@@ -31,8 +31,16 @@ export type AgentInspectArgs = {
     trackedChangeLimit?: number;
     blockOffset?: number;
     blockLimit?: number;
+    findText?: string;
+    findLimit?: number;
     omitEmptyBlocks?: boolean;
     dropTextPreview?: boolean;
+    includeListItemRuns?: boolean;
+    listItemRunsLimit?: number;
+    includeTableCellRuns?: boolean;
+    tableCellRunsLimit?: number;
+    includeBlockRuns?: boolean;
+    blockRunsLimit?: number;
 };
 export type AgentApplyArgs = {
     plan: AgentPlan;