@superdoc-dev/sdk 1.19.2 → 1.20.1

package/dist/agent/doc-snapshot.js

@@ -0,0 +1,657 @@
+function asString(v, fallback = '') {
+    return typeof v === 'string' ? v : fallback;
+}
+function asNumber(v, fallback = 0) {
+    return typeof v === 'number' && Number.isFinite(v) ? v : fallback;
+}
+function asRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v) ? v : null;
+}
+async function safeCall(thunk, fallback, onError) {
+    try {
+        return await thunk();
+    }
+    catch (err) {
+        onError(err);
+        return fallback;
+    }
+}
+function maybeMethod(api, path) {
+    let cursor = api;
+    for (const token of path) {
+        // Function-shaped intermediates are legal: RPC/proxy document handles
+        // (e.g. the browser doc-bridge) expose namespaces as callables.
+        if (!cursor || (typeof cursor !== 'object' && typeof cursor !== 'function'))
+            return null;
+        cursor = cursor[token];
+    }
+    return typeof cursor === 'function' ? cursor : null;
+}
+function explicitCount(counts, ...keys) {
+    for (const key of keys) {
+        const value = counts[key];
+        if (typeof value === 'number' && Number.isFinite(value))
+            return value;
+    }
+    return null;
+}
+function includesDomain(requested, domain) {
+    return requested == null || requested.has(domain);
+}
+/**
+ * Build a deterministic snapshot of a document. The snapshot uses only
+ * read-mode operations from the generated contract — it never mutates state,
+ * and any individual section that fails is captured as a diagnostic so the
+ * rest of the snapshot remains usable.
+ */
+export async function buildDocumentSnapshot(doc, options = {}) {
+    const diagnostics = [];
+    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 ?? options.blockTextLimit ?? 1000;
+    const listLimit = options.listLimit ?? 1000;
+    const tableLimit = options.tableLimit ?? 500;
+    const commentLimit = options.commentLimit ?? 500;
+    const trackedChangeLimit = options.trackedChangeLimit ?? 500;
+    const requestedDomains = Array.isArray(options.includeDomains) && options.includeDomains.length > 0 ? new Set(options.includeDomains) : null;
+    const blockNodeTypes = new Set(Array.isArray(options.blockNodeTypes)
+        ? options.blockNodeTypes.filter((value) => typeof value === 'string' && value.length > 0)
+        : []);
+    const infoFn = maybeMethod(doc, ['info']);
+    const info = infoFn ? await safeCall(() => infoFn({}), null, recordError('info')) : null;
+    const infoRec = asRecord(info);
+    const counts = asRecord(infoRec?.counts) ?? {};
+    const revision = asString(infoRec?.revision, 'unknown');
+    const countsFromInfo = {
+        blocks: explicitCount(counts, 'blocks') ?? 0,
+        paragraphs: explicitCount(counts, 'paragraphs') ?? 0,
+        headings: explicitCount(counts, 'headings') ?? 0,
+        tables: explicitCount(counts, 'tables') ?? 0,
+        lists: explicitCount(counts, 'lists') ?? 0,
+        images: explicitCount(counts, 'images') ?? 0,
+        comments: explicitCount(counts, 'comments') ?? 0,
+        trackedChanges: explicitCount(counts, 'trackedChanges') ?? 0,
+        sections: explicitCount(counts, 'sections') ?? 0,
+        fields: explicitCount(counts, 'fields') ?? 0,
+        hyperlinks: explicitCount(counts, 'hyperlinks') ?? 0,
+        bookmarks: explicitCount(counts, 'bookmarks') ?? 0,
+        contentControls: explicitCount(counts, 'contentControls', 'sdtFields') ?? 0,
+        permissionRanges: explicitCount(counts, 'permissionRanges') ?? 0,
+        styles: explicitCount(counts, 'styles') ?? 0,
+        headers: explicitCount(counts, 'headers') ?? 0,
+        footers: explicitCount(counts, 'footers') ?? 0,
+    };
+    if (options.countsOnly === true) {
+        return {
+            revision,
+            counts: countsFromInfo,
+            blocks: [],
+            lists: [],
+            tables: [],
+            comments: [],
+            trackedChanges: [],
+            sections: [],
+            headerFooters: [],
+            styles: [],
+            contentControls: [],
+            fields: [],
+            hyperlinks: [],
+            bookmarks: [],
+            permissionRanges: [],
+            images: [],
+            diagnostics,
+        };
+    }
+    // Blocks
+    const includeBlocksInSnapshot = includesDomain(requestedDomains, 'blocks');
+    const needBlocksRead = includeBlocksInSnapshot || includesDomain(requestedDomains, 'tables');
+    const blocksFn = maybeMethod(doc, ['blocks', 'list']);
+    const blocksRaw = needBlocksRead && blocksFn
+        ? await safeCall(() => blocksFn({ offset: blockOffset, limit: blockLimit, includeText: includeBlocksInSnapshot }), null, recordError('blocks.list'))
+        : null;
+    const blocksRec = asRecord(blocksRaw);
+    const totalBlocks = explicitCount(blocksRec ?? {}, 'total') ?? countsFromInfo.blocks;
+    const rawBlocks = Array.isArray(blocksRec?.blocks) ? blocksRec.blocks : [];
+    const normalizedBlocks = rawBlocks.map((b, index) => {
+        const rec = asRecord(b) ?? {};
+        return {
+            // doc-api block.ordinal is 0-based; the model-facing convention is
+            // 1-based (matches paragraphOrdinal/tableOrdinal and ordinal selectors).
+            ordinal: asNumber(rec.ordinal, blockOffset + index) + 1,
+            nodeId: asString(rec.nodeId),
+            nodeType: asString(rec.nodeType, 'paragraph'),
+            text: asString(rec.text),
+            textPreview: typeof rec.textPreview === 'string' ? rec.textPreview : null,
+            styleId: typeof rec.styleId === 'string' ? rec.styleId : null,
+            headingLevel: typeof rec.headingLevel === 'number' ? rec.headingLevel : undefined,
+            ...(asRecord(rec.numbering)
+                ? {
+                    numbering: {
+                        marker: asString(asRecord(rec.numbering).marker) || null,
+                        path: Array.isArray(asRecord(rec.numbering).path) ? asRecord(rec.numbering).path : null,
+                        kind: asString(asRecord(rec.numbering).kind) || null,
+                    },
+                }
+                : {}),
+        };
+    });
+    let blocks = includeBlocksInSnapshot && blockNodeTypes.size > 0
+        ? normalizedBlocks.filter((block) => blockNodeTypes.has(block.nodeType))
+        : includeBlocksInSnapshot
+            ? normalizedBlocks
+            : [];
+    if (includeBlocksInSnapshot && options.omitEmptyBlocks === true) {
+        // Drop empty paragraphs/list-items only; structural blocks (tables) keep
+        // their slot even with empty text.
+        blocks = blocks.filter((block) => block.text.trim().length > 0 || (block.nodeType !== 'paragraph' && block.nodeType !== 'listItem'));
+    }
+    if (includeBlocksInSnapshot && options.dropTextPreview === true) {
+        blocks = blocks.map((block) => ({ ...block, textPreview: null }));
+    }
+    // Lists
+    const listsFn = maybeMethod(doc, ['lists', 'list']);
+    const listsRaw = includesDomain(requestedDomains, 'lists') && listsFn
+        ? await safeCall(() => listsFn({ offset: 0, limit: listLimit }), null, recordError('lists.list'))
+        : null;
+    const listsRec = asRecord(listsRaw);
+    const listItemsArr = Array.isArray(listsRec?.items) ? listsRec.items : [];
+    const listsById = new Map();
+    for (const item of listItemsArr) {
+        const rec = asRecord(item);
+        if (!rec)
+            continue;
+        const listId = asString(rec.listId, 'list:unknown');
+        if (!listsById.has(listId)) {
+            listsById.set(listId, {
+                listId,
+                kind: asString(rec.kind, 'ordered'),
+                items: [],
+            });
+        }
+        const addr = asRecord(rec.address);
+        listsById.get(listId).items.push({
+            nodeId: asString(addr?.nodeId),
+            ordinal: asNumber(rec.ordinal),
+            level: asNumber(rec.level),
+            text: asString(rec.text),
+        });
+    }
+    const lists = [...listsById.values()];
+    // Tables: derive table block list from `blocks`, then query shape per table.
+    const tableBlocks = normalizedBlocks.filter((b) => b.nodeType === 'table');
+    const tablesFn = maybeMethod(doc, ['tables', 'get']);
+    const tables = [];
+    if (includesDomain(requestedDomains, 'tables')) {
+        for (let i = 0; i < Math.min(tableBlocks.length, tableLimit); i += 1) {
+            const block = tableBlocks[i];
+            if (!tablesFn) {
+                tables.push({ nodeId: block.nodeId, ordinal: i + 1, rows: 0, columns: 0, cells: [] });
+                continue;
+            }
+            const tableRaw = await safeCall(() => tablesFn({ nodeId: block.nodeId }), null, recordError(`tables.get:${block.nodeId}`));
+            const rec = asRecord(tableRaw);
+            tables.push({
+                nodeId: block.nodeId,
+                ordinal: i + 1,
+                rows: asNumber(rec?.rows),
+                columns: asNumber(rec?.columns),
+                cells: [],
+            });
+        }
+    }
+    const extractFn = maybeMethod(doc, ['extract']);
+    if (tables.length > 0 && extractFn) {
+        const extractRaw = await safeCall(() => extractFn({}), null, recordError('extract'));
+        const extractRec = asRecord(extractRaw);
+        const extractBlocks = Array.isArray(extractRec?.blocks) ? extractRec.blocks : [];
+        const cellsByTableNodeId = new Map();
+        for (const block of extractBlocks) {
+            const rec = asRecord(block);
+            const tableContext = asRecord(rec?.tableContext);
+            if (!rec || !tableContext)
+                continue;
+            const tableOrdinal = asNumber(tableContext.tableOrdinal, -1);
+            const rowIndex = asNumber(tableContext.rowIndex, -1);
+            const columnIndex = asNumber(tableContext.columnIndex, -1);
+            if (tableOrdinal < 0 || rowIndex < 0 || columnIndex < 0)
+                continue;
+            const table = tables[tableOrdinal];
+            if (!table)
+                continue;
+            const key = `${rowIndex}:${columnIndex}`;
+            const text = asString(rec.text);
+            const nodeId = asString(rec.nodeId) || undefined;
+            const cellMap = cellsByTableNodeId.get(table.nodeId) ??
+                new Map();
+            const existing = cellMap.get(key);
+            cellMap.set(key, {
+                rowIndex,
+                columnIndex,
+                text: existing == null || text.length === 0
+                    ? (existing?.text ?? text)
+                    : existing.text.length === 0
+                        ? text
+                        : `${existing.text}\n${text}`,
+                nodeId: existing?.nodeId ?? nodeId,
+            });
+            cellsByTableNodeId.set(table.nodeId, cellMap);
+        }
+        for (const table of tables) {
+            const cellMap = cellsByTableNodeId.get(table.nodeId);
+            if (!cellMap)
+                continue;
+            table.cells = [...cellMap.values()].sort((left, right) => left.rowIndex - right.rowIndex || left.columnIndex - right.columnIndex);
+        }
+    }
+    // Comments
+    const commentsFn = maybeMethod(doc, ['comments', 'list']);
+    const commentsRaw = includesDomain(requestedDomains, 'comments') && commentsFn
+        ? await safeCall(() => commentsFn({ includeResolved: true, offset: 0, limit: commentLimit }), null, recordError('comments.list'))
+        : null;
+    const commentsRec = asRecord(commentsRaw);
+    const commentItems = Array.isArray(commentsRec?.items) ? commentsRec.items : [];
+    const comments = commentItems.map((c) => {
+        const rec = asRecord(c) ?? {};
+        const target = asRecord(rec.target);
+        const segments = Array.isArray(target?.segments) ? target.segments : [];
+        return {
+            id: asString(rec.id),
+            text: asString(rec.text),
+            status: asString(rec.status, 'open'),
+            anchoredText: typeof rec.anchoredText === 'string' ? rec.anchoredText : undefined,
+            segments: segments.flatMap((seg) => {
+                const segRec = asRecord(seg);
+                const range = asRecord(segRec?.range);
+                if (!segRec)
+                    return [];
+                return [
+                    {
+                        blockId: asString(segRec.blockId),
+                        start: asNumber(range?.start),
+                        end: asNumber(range?.end),
+                    },
+                ];
+            }),
+        };
+    });
+    // Tracked changes
+    const trackedFn = maybeMethod(doc, ['trackChanges', 'list']);
+    const trackedRaw = includesDomain(requestedDomains, 'trackedChanges') && trackedFn
+        ? await safeCall(() => trackedFn({ offset: 0, limit: trackedChangeLimit }), null, recordError('trackChanges.list'))
+        : null;
+    const trackedRec = asRecord(trackedRaw);
+    const trackedItems = Array.isArray(trackedRec?.items) ? trackedRec.items : [];
+    const trackedChanges = trackedItems.map((t) => {
+        const rec = asRecord(t) ?? {};
+        const addr = asRecord(rec.address);
+        const story = asRecord(addr?.story);
+        return {
+            id: asString(rec.id),
+            type: asString(rec.type, 'insert'),
+            excerpt: typeof rec.excerpt === 'string' ? rec.excerpt : undefined,
+            author: typeof rec.author === 'string' ? rec.author : undefined,
+            date: typeof rec.date === 'string' ? rec.date : undefined,
+            story: typeof story?.storyType === 'string' ? story.storyType : undefined,
+        };
+    });
+    // Sections (best effort; not all SDK builds expose a sections.list)
+    const sectionsFn = maybeMethod(doc, ['sections', 'list']);
+    let sections = [];
+    if (includesDomain(requestedDomains, 'sections') && sectionsFn) {
+        const sectionsRaw = await safeCall(() => sectionsFn({}), null, recordError('sections.list'));
+        const rec = asRecord(sectionsRaw);
+        const items = Array.isArray(rec?.items) ? rec.items : [];
+        sections = items.map((s, index) => {
+            const srec = asRecord(s) ?? {};
+            const pageSize = asRecord(srec.pageSize);
+            return {
+                ordinal: asNumber(srec.ordinal, index + 1),
+                sectionId: typeof srec.sectionId === 'string' ? srec.sectionId : undefined,
+                startNodeId: typeof srec.startNodeId === 'string' ? srec.startNodeId : undefined,
+                endNodeId: typeof srec.endNodeId === 'string' ? srec.endNodeId : undefined,
+                pageSize: pageSize ? { width: asNumber(pageSize.width), height: asNumber(pageSize.height) } : undefined,
+            };
+        });
+    }
+    // Header / footer (best effort)
+    const headerFooterFn = maybeMethod(doc, ['headerFooters', 'list']);
+    let headerFooters = [];
+    if (includesDomain(requestedDomains, 'headerFooters') && headerFooterFn) {
+        const raw = await safeCall(() => headerFooterFn({}), null, recordError('headerFooters.list'));
+        const rec = asRecord(raw);
+        const items = Array.isArray(rec?.items) ? rec.items : [];
+        headerFooters = items.flatMap((hf) => {
+            const r = asRecord(hf);
+            if (!r)
+                return [];
+            const kind = asString(r.kind, 'header');
+            return [
+                {
+                    kind: kind === 'footer' ? 'footer' : 'header',
+                    sectionId: typeof r.sectionId === 'string' ? r.sectionId : undefined,
+                    sectionIndex: typeof r.sectionIndex === 'number' ? r.sectionIndex : undefined,
+                    variant: typeof r.variant === 'string' ? r.variant : undefined,
+                    blocks: [],
+                },
+            ];
+        });
+    }
+    // Styles
+    const stylesFn = maybeMethod(doc, ['styles', 'list']);
+    let styles = [];
+    if (includesDomain(requestedDomains, 'styles') && stylesFn) {
+        const raw = await safeCall(() => stylesFn({}), null, recordError('styles.list'));
+        const rec = asRecord(raw);
+        const items = Array.isArray(rec?.items) ? rec.items : [];
+        styles = items.flatMap((it) => {
+            const r = asRecord(it);
+            if (!r)
+                return [];
+            return [
+                {
+                    styleId: asString(r.styleId),
+                    name: asString(r.name, asString(r.styleId)),
+                    type: typeof r.type === 'string' ? r.type : undefined,
+                    basedOn: typeof r.basedOn === 'string' ? r.basedOn : undefined,
+                },
+            ];
+        });
+    }
+    // Content controls
+    const contentControlsFn = maybeMethod(doc, ['contentControls', 'list']);
+    let contentControls = [];
+    if (includesDomain(requestedDomains, 'contentControls') && contentControlsFn) {
+        const raw = await safeCall(() => contentControlsFn({}), null, recordError('contentControls.list'));
+        const rec = asRecord(raw);
+        const items = Array.isArray(rec?.items) ? rec.items : [];
+        contentControls = items.flatMap((it) => {
+            const r = asRecord(it);
+            if (!r)
+                return [];
+            return [
+                {
+                    id: asString(r.id),
+                    type: typeof r.type === 'string' ? r.type : undefined,
+                    alias: typeof r.alias === 'string' ? r.alias : undefined,
+                    tag: typeof r.tag === 'string' ? r.tag : undefined,
+                    text: typeof r.text === 'string' ? r.text : undefined,
+                },
+            ];
+        });
+    }
+    // Fields
+    const fieldsFn = maybeMethod(doc, ['fields', 'list']);
+    let fields = [];
+    if (includesDomain(requestedDomains, 'fields') && fieldsFn) {
+        const raw = await safeCall(() => fieldsFn({}), null, recordError('fields.list'));
+        const rec = asRecord(raw);
+        const items = Array.isArray(rec?.items) ? rec.items : [];
+        fields = items.flatMap((it) => {
+            const r = asRecord(it);
+            if (!r)
+                return [];
+            return [
+                {
+                    id: asString(r.id),
+                    type: typeof r.type === 'string' ? r.type : undefined,
+                    result: typeof r.result === 'string' ? r.result : undefined,
+                },
+            ];
+        });
+    }
+    // Hyperlinks
+    const hyperlinksFn = maybeMethod(doc, ['hyperlinks', 'list']);
+    let hyperlinks = [];
+    if (includesDomain(requestedDomains, 'hyperlinks') && hyperlinksFn) {
+        const raw = await safeCall(() => hyperlinksFn({}), null, recordError('hyperlinks.list'));
+        const rec = asRecord(raw);
+        const items = Array.isArray(rec?.items) ? rec.items : [];
+        hyperlinks = items.flatMap((it) => {
+            const r = asRecord(it);
+            if (!r)
+                return [];
+            return [
+                {
+                    id: asString(r.id),
+                    url: asString(r.url),
+                    display: typeof r.display === 'string' ? r.display : undefined,
+                    nodeId: typeof r.nodeId === 'string' ? r.nodeId : undefined,
+                },
+            ];
+        });
+    }
+    // Bookmarks
+    const bookmarksFn = maybeMethod(doc, ['bookmarks', 'list']);
+    let bookmarks = [];
+    if (includesDomain(requestedDomains, 'bookmarks') && bookmarksFn) {
+        const raw = await safeCall(() => bookmarksFn({}), null, recordError('bookmarks.list'));
+        const rec = asRecord(raw);
+        const items = Array.isArray(rec?.items) ? rec.items : [];
+        bookmarks = items.flatMap((it) => {
+            const r = asRecord(it);
+            if (!r)
+                return [];
+            return [
+                {
+                    id: asString(r.id),
+                    name: asString(r.name, asString(r.id)),
+                    startNodeId: typeof r.startNodeId === 'string' ? r.startNodeId : undefined,
+                    endNodeId: typeof r.endNodeId === 'string' ? r.endNodeId : undefined,
+                },
+            ];
+        });
+    }
+    // Permission ranges
+    const prFn = maybeMethod(doc, ['permissionRanges', 'list']);
+    let permissionRanges = [];
+    if (includesDomain(requestedDomains, 'permissionRanges') && prFn) {
+        const raw = await safeCall(() => prFn({}), null, recordError('permissionRanges.list'));
+        const rec = asRecord(raw);
+        const items = Array.isArray(rec?.items) ? rec.items : [];
+        permissionRanges = items.flatMap((it) => {
+            const r = asRecord(it);
+            if (!r)
+                return [];
+            return [
+                {
+                    id: asString(r.id),
+                    startNodeId: typeof r.startNodeId === 'string' ? r.startNodeId : undefined,
+                    endNodeId: typeof r.endNodeId === 'string' ? r.endNodeId : undefined,
+                    editorOrEditorGroup: typeof r.editorOrEditorGroup === 'string' ? r.editorOrEditorGroup : undefined,
+                },
+            ];
+        });
+    }
+    // Images
+    const imagesFn = maybeMethod(doc, ['images', 'list']);
+    let images = [];
+    if (includesDomain(requestedDomains, 'images') && imagesFn) {
+        const raw = await safeCall(() => imagesFn({}), null, recordError('images.list'));
+        const rec = asRecord(raw);
+        const items = Array.isArray(rec?.items) ? rec.items : [];
+        images = items.flatMap((it) => {
+            const r = asRecord(it);
+            if (!r)
+                return [];
+            return [
+                {
+                    imageId: asString(r.imageId, asString(r.id)),
+                    nodeId: typeof r.nodeId === 'string' ? r.nodeId : undefined,
+                    alt: typeof r.alt === 'string' ? r.alt : undefined,
+                    caption: typeof r.caption === 'string' ? r.caption : undefined,
+                },
+            ];
+        });
+    }
+    return {
+        revision,
+        counts: {
+            blocks: countsFromInfo.blocks || totalBlocks || normalizedBlocks.length,
+            paragraphs: countsFromInfo.paragraphs || normalizedBlocks.filter((b) => b.nodeType === 'paragraph').length,
+            headings: countsFromInfo.headings || normalizedBlocks.filter((b) => b.nodeType === 'heading').length,
+            tables: countsFromInfo.tables || tableBlocks.length,
+            lists: countsFromInfo.lists || lists.length,
+            images: countsFromInfo.images || images.length,
+            comments: countsFromInfo.comments || comments.length,
+            trackedChanges: countsFromInfo.trackedChanges || trackedChanges.length,
+            sections: countsFromInfo.sections || sections.length,
+            fields: countsFromInfo.fields || fields.length,
+            hyperlinks: countsFromInfo.hyperlinks || hyperlinks.length,
+            bookmarks: countsFromInfo.bookmarks || bookmarks.length,
+            contentControls: countsFromInfo.contentControls || contentControls.length,
+            permissionRanges: countsFromInfo.permissionRanges || permissionRanges.length,
+            styles: countsFromInfo.styles || styles.length,
+            headers: countsFromInfo.headers || headerFooters.filter((h) => h.kind === 'header').length,
+            footers: countsFromInfo.footers || headerFooters.filter((h) => h.kind === 'footer').length,
+        },
+        blocks,
+        lists,
+        tables,
+        comments,
+        trackedChanges,
+        sections,
+        headerFooters,
+        styles,
+        contentControls,
+        fields,
+        hyperlinks,
+        bookmarks,
+        permissionRanges,
+        images,
+        diagnostics,
+    };
+}
+/**
+ * Structured ambiguity error returned when multiple candidates match a
+ * selector and the plan required uniqueness.
+ */
+export class AmbiguousSelectorError extends Error {
+    code = 'AMBIGUOUS_SELECTOR';
+    candidates;
+    constructor(message, candidates) {
+        super(message);
+        this.name = 'AmbiguousSelectorError';
+        this.candidates = candidates;
+    }
+}
+/**
+ * Resolve a deterministic selector against the snapshot. Returns the matching
+ * block ids in document order. Selectors that target entities return
+ * entity-domain matches by id.
+ */
+export function resolveSnapshotSelector(snapshot, selector) {
+    const nonEmptyParagraphs = snapshot.blocks.filter((block) => block.nodeType === 'paragraph' && block.text.trim().length > 0);
+    const firstHeading = snapshot.blocks.find((block) => block.nodeType === 'heading');
+    const bodyParagraphs = firstHeading == null
+        ? nonEmptyParagraphs
+        : snapshot.blocks.filter((block) => block.nodeType === 'paragraph' && block.text.trim().length > 0 && block.ordinal > firstHeading.ordinal);
+    switch (selector.kind) {
+        case 'ref':
+            return snapshot.blocks.filter((b) => b.nodeId === selector.ref).map((b) => b.nodeId);
+        case 'nodeId':
+            return snapshot.blocks.filter((b) => b.nodeId === selector.nodeId).map((b) => b.nodeId);
+        case 'tableCell': {
+            const table = snapshot.tables[selector.tableOrdinal - 1];
+            if (!table)
+                return [];
+            const cell = table.cells.find((entry) => entry.rowIndex === selector.rowIndex && entry.columnIndex === selector.columnIndex);
+            return cell?.nodeId ? [cell.nodeId] : [];
+        }
+        case 'textSearch': {
+            const matchMode = selector.match ?? 'all';
+            const occurrence = selector.occurrence ?? 1;
+            const caseSensitive = selector.caseSensitive === true;
+            const allowedNodeTypes = new Set(selector.nodeTypes ?? ['paragraph', 'heading', 'listItem']);
+            const terms = selector.terms.filter((term) => term.trim().length > 0);
+            if (terms.length === 0)
+                return [];
+            const normalizedTerms = caseSensitive ? terms : terms.map((term) => term.toLocaleLowerCase());
+            const matches = snapshot.blocks.filter((block) => {
+                if (!allowedNodeTypes.has(block.nodeType))
+                    return false;
+                if (block.text.trim().length === 0)
+                    return false;
+                const haystack = caseSensitive ? block.text : block.text.toLocaleLowerCase();
+                const hits = normalizedTerms.filter((term) => haystack.includes(term)).length;
+                return matchMode === 'any' ? hits > 0 : hits === normalizedTerms.length;
+            });
+            const target = matches[occurrence - 1];
+            return target ? [target.nodeId] : [];
+        }
+        case 'ordinal': {
+            switch (selector.ordinalKind) {
+                case 'blockOrdinal': {
+                    const target = snapshot.blocks[selector.value - 1];
+                    return target ? [target.nodeId] : [];
+                }
+                case 'paragraphOrdinal': {
+                    const target = nonEmptyParagraphs[selector.value - 1];
+                    return target ? [target.nodeId] : [];
+                }
+                case 'bodyParagraphOrdinal': {
+                    const target = (bodyParagraphs.length > 0 ? bodyParagraphs : nonEmptyParagraphs)[selector.value - 1];
+                    return target ? [target.nodeId] : [];
+                }
+                case 'headingOrdinal': {
+                    const headings = snapshot.blocks.filter((b) => b.nodeType === 'heading');
+                    const target = headings[selector.value - 1];
+                    return target ? [target.nodeId] : [];
+                }
+                case 'tableOrdinal': {
+                    const target = snapshot.tables[selector.value - 1];
+                    return target ? [target.nodeId] : [];
+                }
+                case 'listOrdinal': {
+                    const target = snapshot.lists[selector.value - 1];
+                    return target ? target.items.map((item) => item.nodeId) : [];
+                }
+                case 'sectionOrdinal': {
+                    const target = snapshot.sections[selector.value - 1];
+                    return target?.startNodeId ? [target.startNodeId] : [];
+                }
+            }
+            return [];
+        }
+        case 'entity':
+            switch (selector.entityType) {
+                case 'comment':
+                    return snapshot.comments.filter((c) => c.id === selector.entityId).map((c) => c.id);
+                case 'trackedChange':
+                    return snapshot.trackedChanges.filter((c) => c.id === selector.entityId).map((c) => c.id);
+                case 'bookmark':
+                    return snapshot.bookmarks.filter((b) => b.id === selector.entityId).map((b) => b.id);
+                case 'image':
+                    return snapshot.images.filter((i) => i.imageId === selector.entityId).map((i) => i.imageId);
+                case 'hyperlink':
+                    return snapshot.hyperlinks.filter((h) => h.id === selector.entityId).map((h) => h.id);
+                case 'field':
+                    return snapshot.fields.filter((f) => f.id === selector.entityId).map((f) => f.id);
+            }
+            return [];
+        case 'placement':
+            if (selector.at === 'document_start') {
+                const first = snapshot.blocks[0];
+                return first ? [first.nodeId] : [];
+            }
+            const last = snapshot.blocks[snapshot.blocks.length - 1];
+            return last ? [last.nodeId] : [];
+        case 'relative': {
+            const targetIds = resolveSnapshotSelector(snapshot, selector.target);
+            const offset = selector.position === 'before' ? -1 : 1;
+            const matches = [];
+            for (const targetId of targetIds) {
+                const index = snapshot.blocks.findIndex((block) => block.nodeId === targetId);
+                if (index === -1)
+                    continue;
+                const sibling = snapshot.blocks[index + offset];
+                if (sibling != null)
+                    matches.push(sibling.nodeId);
+            }
+            return [...new Set(matches)];
+        }
+        case 'document':
+            return snapshot.blocks.map((b) => b.nodeId);
+    }
+}

package/dist/agent/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Clean DOCX agent runtime.
+ *
+ * This barrel exposes the four product-stable agent tool entry points
+ * (inspect, apply, verify, operation) plus the IR types and the
+ * contract-derived operation catalog. Consumers should depend on this
+ * barrel — never reach into the benchmark `workflow-poc` profile from
+ * product code.
+ */
+export { AGENT_TOOL_DEFINITIONS, AGENT_TOOL_NAMES, isAgentToolName, listAgentTools, type AgentToolDefinition, type AgentToolName, type AgentProviderTool, } from './catalog.js';
+export { agentInspect, agentApply, agentVerify, agentOperation, type AgentApplyArgs, type AgentInspectArgs, type AgentOperationArgs, type AgentReceipt, type AgentVerifyArgs, type SelectedTarget, type VerificationResult, } from './runtime.js';
+export { validatePlan, isApplyStep, isInspectStep, isSelectStep, isVerifyStep, type AgentApplyStep, type AgentChangeMode, type AgentEntityKind, type AgentInspectStep, type AgentOrdinalKind, type AgentPlan, type AgentPlanStep, type AgentSelectStep, type AgentSelector, type AgentVerificationCheck, type AgentVerifyStep, type IrValidationError, type IrValidationResult, } from './ir.js';
+export { OPERATION_CATALOG, getOperationCatalogEntry, getOperationCatalogSummary, listMutatingOperations, listOperationsByDomain, listOperationsMissingStructuralVerification, type ExposureStatus, type OperationCatalogEntry, type OperationDomain, type OperationMode, type TargetShape, } from './operation-catalog.js';
+export { AmbiguousSelectorError, buildDocumentSnapshot, resolveSnapshotSelector, type DocumentSnapshot, type SnapshotBlock, type SnapshotComment, type SnapshotDiagnostic, type SnapshotDomain, type SnapshotImage, type SnapshotList, type SnapshotSection, type SnapshotTable, type SnapshotTrackedChange, } from './doc-snapshot.js';
+export { superdocPerformAction, isActionName, ACTION_NAMES_LIST, type AcceptTrackedChangesArgs, type AddCommentsArgs, type AddHyperlinkArgs, type AddListItemsArgs, type ApplyLetterSpacingArgs, type ApplyStyleArgs, type AppendListArgs, type AttachNumberingArgs, type ConvertListArgs, type FormatParagraphArgs, type FormatTextArgs, type InsertPageBreakArgs, type MoveTextArgs, type RedoChangesArgs, type ReplyToCommentArgs, type ResolveCommentsArgs, type SetFontFamilyArgs, type SetParagraphSpacingArgs, type SplitListArgs, type UndoChangesArgs, type CommentParagraphsArgs, type CreateTableArgs, type DeleteTableColumnArgs, type DeleteTableRowArgs, type DeleteTextArgs, type FillPlaceholdersArgs, type InsertHeadingArgs, type StyleTableArgs, type MoveTableArgs, type DeleteTableArgs, type InsertListItemsArgs, type InsertParagraphsArgs, type InsertTableColumnArgs, type InsertTableRowArgs, type InsertTocArgs, type MoveRangeArgs, type NormalizeBodyFontSizeArgs, type ActionArgs, type ActionName, type ActionPlacement, type RejectTrackedChangesArgs, type ReplaceTextArgs, type RewriteBlockArgs, type SplitTableArgs, } from './actions.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/agent/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,iBAAiB,GACvB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,YAAY,EACZ,UAAU,EACV,WAAW,EACX,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,YAAY,EACZ,WAAW,EACX,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,GACxB,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,0BAA0B,EAC1B,sBAAsB,EACtB,sBAAsB,EACtB,2CAA2C,EAC3C,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,WAAW,GACjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,qBAAqB,GAC3B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,qBAAqB,EACrB,YAAY,EACZ,iBAAiB,EACjB,KAAK,wBAAwB,EAC7B,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,yBAAyB,EAC9B,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,wBAAwB,EAC7B,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,cAAc,GACpB,MAAM,cAAc,CAAC"}