@superdoc/sdk 2.12.0-next.3 → 2.12.0-next.5

package/README.md

@@ -96,3 +96,18 @@ automatically replay the write.
 ## License
 
 AGPL-3.0. Commercial licenses are available from [SuperDoc](https://www.superdoc.dev).
+
+## Inspecting textbox sections
+
+`superdoc_inspect` includes discovered text-bearing textbox stories in `textboxes` when
+block inspection is enabled. Each entry contains its explicit `story` locator,
+its story-local `total`, and normalized `blocks` with text, identities, and list
+markers. The top-level `blocks` array and its ordinals continue to refer to the
+body; textbox block ordinals belong to their containing story.
+
+The block offset, limit, text cap, and block filters also apply within each
+textbox. Count-only inspections and inspections excluding the blocks domain do
+not collect textbox text. Check `diagnostics` for incomplete story discovery or
+reads. To edit a discovered heading, use `query.match` with its story locator
+and pass the returned reference to `replace`; a textbox ordinal is not a body
+action selector.

package/dist/agent/doc-snapshot.cjs

@@ -141,6 +141,33 @@ function populateTableCellsFromExtract(tables, extractRaw, tableOrdinalBase = 0)
         table.cells = [...cellMap.values()].sort((left, right) => left.rowIndex - right.rowIndex || left.columnIndex - right.columnIndex);
     }
 }
+function normalizeSnapshotBlock(value, fallbackOrdinal, blockTextLimit) {
+    const rec = asRecord(value) ?? {};
+    const fullText = asString(rec.text);
+    const text = truncateBlockText(fullText, blockTextLimit);
+    const textPreview = typeof rec.textPreview === 'string' ? truncateBlockText(rec.textPreview, blockTextLimit) : null;
+    const block = {
+        // doc-api block.ordinal is 0-based; the model-facing convention is
+        // 1-based (matches paragraphOrdinal/tableOrdinal and ordinal selectors).
+        ordinal: asNumber(rec.ordinal, fallbackOrdinal) + 1,
+        nodeId: asString(rec.nodeId),
+        nodeType: asString(rec.nodeType, 'paragraph'),
+        text,
+        textPreview,
+        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,
+                },
+            }
+            : {}),
+    };
+    return block;
+}
 /**
  * Build a deterministic snapshot of a document. The snapshot uses only
  * read-mode operations from the generated contract — it never mutates state,
@@ -259,30 +286,8 @@ async function buildDocumentSnapshot(doc, options = {}) {
     const rawBlocks = Array.isArray(blocksRec?.blocks) ? blocksRec.blocks : [];
     const fullBlockText = new Map();
     const normalizedBlocks = rawBlocks.map((b, index) => {
-        const rec = asRecord(b) ?? {};
-        const fullText = asString(rec.text);
-        const text = truncateBlockText(fullText, blockTextLimit);
-        const textPreview = typeof rec.textPreview === 'string' ? truncateBlockText(rec.textPreview, blockTextLimit) : null;
-        const block = {
-            // 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,
-            textPreview,
-            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,
-                    },
-                }
-                : {}),
-        };
+        const fullText = asString(asRecord(b)?.text);
+        const block = normalizeSnapshotBlock(b, blockOffset + index, blockTextLimit);
         fullBlockText.set(block, fullText);
         return block;
     });
@@ -1003,4 +1008,5 @@ exports.MutationSnapshotError = MutationSnapshotError;
 exports.buildDocumentSnapshot = buildDocumentSnapshot;
 exports.buildMutationSnapshot = buildMutationSnapshot;
 exports.matchRunsForBlock = matchRunsForBlock;
+exports.normalizeSnapshotBlock = normalizeSnapshotBlock;
 exports.resolveSnapshotSelector = resolveSnapshotSelector;

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

@@ -306,6 +306,7 @@ type SnapshotOptions = {
     /** Max blocks to enrich with runs when includeBlockRuns is set (default 30). */
     blockRunsLimit?: number;
 };
+export declare function normalizeSnapshotBlock(value: unknown, fallbackOrdinal: number, blockTextLimit: number | null): SnapshotBlock;
 /**
  * Build a deterministic snapshot of a document. The snapshot uses only
  * read-mode operations from the generated contract — it never mutates state,

package/dist/agent/doc-snapshot.js

@@ -139,6 +139,33 @@ function populateTableCellsFromExtract(tables, extractRaw, tableOrdinalBase = 0)
         table.cells = [...cellMap.values()].sort((left, right) => left.rowIndex - right.rowIndex || left.columnIndex - right.columnIndex);
     }
 }
+export function normalizeSnapshotBlock(value, fallbackOrdinal, blockTextLimit) {
+    const rec = asRecord(value) ?? {};
+    const fullText = asString(rec.text);
+    const text = truncateBlockText(fullText, blockTextLimit);
+    const textPreview = typeof rec.textPreview === 'string' ? truncateBlockText(rec.textPreview, blockTextLimit) : null;
+    const block = {
+        // doc-api block.ordinal is 0-based; the model-facing convention is
+        // 1-based (matches paragraphOrdinal/tableOrdinal and ordinal selectors).
+        ordinal: asNumber(rec.ordinal, fallbackOrdinal) + 1,
+        nodeId: asString(rec.nodeId),
+        nodeType: asString(rec.nodeType, 'paragraph'),
+        text,
+        textPreview,
+        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,
+                },
+            }
+            : {}),
+    };
+    return block;
+}
 /**
  * Build a deterministic snapshot of a document. The snapshot uses only
  * read-mode operations from the generated contract — it never mutates state,
@@ -257,30 +284,8 @@ export async function buildDocumentSnapshot(doc, options = {}) {
     const rawBlocks = Array.isArray(blocksRec?.blocks) ? blocksRec.blocks : [];
     const fullBlockText = new Map();
     const normalizedBlocks = rawBlocks.map((b, index) => {
-        const rec = asRecord(b) ?? {};
-        const fullText = asString(rec.text);
-        const text = truncateBlockText(fullText, blockTextLimit);
-        const textPreview = typeof rec.textPreview === 'string' ? truncateBlockText(rec.textPreview, blockTextLimit) : null;
-        const block = {
-            // 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,
-            textPreview,
-            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,
-                    },
-                }
-                : {}),
-        };
+        const fullText = asString(asRecord(b)?.text);
+        const block = normalizeSnapshotBlock(b, blockOffset + index, blockTextLimit);
         fullBlockText.set(block, fullText);
         return block;
     });

package/dist/agent/runtime.cjs

@@ -1,5 +1,6 @@
 'use strict';
 
+var textboxSnapshot = require('./textbox-snapshot.cjs');
 var executionContext = require('./execution-context.cjs');
 var contract = require('../generated/contract.cjs');
 var errors = require('../runtime/errors.cjs');
@@ -162,7 +163,11 @@ async function agentInspect(doc, args = {}) {
     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);
+    const snapshot = await docSnapshot.buildDocumentSnapshot(doc, effective);
+    const includeTextboxes = !args.countsOnly && (!args.includeDomains?.length || args.includeDomains.includes('blocks'));
+    const diagnostics = [...snapshot.diagnostics];
+    const textboxes = includeTextboxes ? await textboxSnapshot.readTextboxSnapshots(doc, effective, diagnostics) : [];
+    return { ...snapshot, diagnostics, textboxes };
 }
 function checkAgainstSnapshot(snapshot, check) {
     switch (check.kind) {

package/dist/agent/runtime.d.ts

@@ -1,3 +1,4 @@
+import { type SnapshotTextbox } from './textbox-snapshot.js';
 import { type EvidencePolicy } from './execution-context.js';
 /**
  * Clean agent runtime.
@@ -119,7 +120,10 @@ export type AgentReceipt = {
     /** Action-specific evidence (editsApplied, marker, placement, …). */
     [key: string]: unknown;
 };
-export declare function agentInspect(doc: BoundDocApi, args?: AgentInspectArgs): Promise<DocumentSnapshot>;
+export type AgentInspectResult = DocumentSnapshot & {
+    textboxes: readonly SnapshotTextbox[];
+};
+export declare function agentInspect(doc: BoundDocApi, args?: AgentInspectArgs): Promise<AgentInspectResult>;
 export declare function agentApply(doc: BoundDocApi, args: AgentApplyArgs): Promise<AgentReceipt>;
 export declare function agentVerify(doc: BoundDocApi, args: AgentVerifyArgs): Promise<AgentReceipt>;
 /**

package/dist/agent/runtime.js

@@ -1,3 +1,4 @@
+import { readTextboxSnapshots } from './textbox-snapshot.js';
 import { ExecutionContext, evaluateFactChecks } from './execution-context.js';
 import { CONTRACT } from '../generated/contract.js';
 import { SuperDocCliError } from '../runtime/errors.js';
@@ -159,7 +160,11 @@ export async function agentInspect(doc, args = {}) {
     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 buildDocumentSnapshot(doc, effective);
+    const snapshot = await buildDocumentSnapshot(doc, effective);
+    const includeTextboxes = !args.countsOnly && (!args.includeDomains?.length || args.includeDomains.includes('blocks'));
+    const diagnostics = [...snapshot.diagnostics];
+    const textboxes = includeTextboxes ? await readTextboxSnapshots(doc, effective, diagnostics) : [];
+    return { ...snapshot, diagnostics, textboxes };
 }
 function checkAgainstSnapshot(snapshot, check) {
     switch (check.kind) {

package/dist/agent/textbox-snapshot.cjs

@@ -0,0 +1,65 @@
+'use strict';
+
+var docSnapshot = require('./doc-snapshot.cjs');
+
+async function readTextboxSnapshots(doc, options, diagnostics) {
+    if (typeof doc.query?.match !== 'function' || typeof doc.blocks?.list !== 'function')
+        return [];
+    const stories = new Map();
+    const snapshots = [];
+    try {
+        // Text discovery includes nested stories; blocks.list remains story-scoped
+        // so body ordinals used by existing action selectors cannot shift.
+        // Match one character per nonempty line. Cross-paragraph matches are
+        // rejected and retried at each character by the engine's regex scanner.
+        let offset = 0;
+        for (;;) {
+            const found = await doc.query.match({
+                select: { type: 'text', pattern: '(?<=^|\\n)[^\\n]', mode: 'regex' },
+                offset,
+                limit: 1000,
+            });
+            for (const item of found.items) {
+                const story = item.address.story;
+                if (story?.storyType === 'textbox')
+                    stories.set(story.textboxId, story);
+            }
+            offset += found.items.length;
+            if (offset >= found.total)
+                break;
+            if (found.items.length === 0)
+                throw new Error('Textbox discovery stopped before the reported match total.');
+        }
+    }
+    catch (error) {
+        diagnostics.push({
+            section: 'textboxes.discover',
+            message: error instanceof Error ? error.message : String(error),
+        });
+    }
+    const offset = Math.max(0, options.blockOffset ?? 0);
+    const limit = options.blockLimit != null && options.blockLimit > 0 ? options.blockLimit : 1000;
+    const textLimit = options.blockTextLimit != null && Number.isFinite(options.blockTextLimit) && options.blockTextLimit > 0
+        ? options.blockTextLimit
+        : null;
+    for (const story of stories.values()) {
+        try {
+            const listed = await doc.blocks.list({ in: story, includeText: true, offset, limit });
+            const blocks = listed.blocks
+                .filter((block) => !options.omitEmptyBlocks || Boolean(block.text?.trim()))
+                .map((block, index) => docSnapshot.normalizeSnapshotBlock(block, offset + index, textLimit))
+                .filter((block) => !options.blockNodeTypes?.length || options.blockNodeTypes.includes(block.nodeType))
+                .map((block) => (options.dropTextPreview ? { ...block, textPreview: null } : block));
+            snapshots.push({ story, total: listed.total, blocks });
+        }
+        catch (error) {
+            diagnostics.push({
+                section: `textboxes.blocks:${story.textboxId}`,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return snapshots;
+}
+
+exports.readTextboxSnapshots = readTextboxSnapshots;

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

@@ -0,0 +1,22 @@
+import type { BoundDocApi } from '../generated/client.js';
+import { type SnapshotBlock, type SnapshotDiagnostic } from './doc-snapshot.js';
+export type SnapshotTextbox = {
+    story: {
+        kind: 'story';
+        storyType: 'textbox';
+        textboxId: string;
+    };
+    /** Story-local block count; blocks contains the requested window in this story. */
+    total: number;
+    blocks: readonly SnapshotBlock[];
+};
+type TextboxSnapshotOptions = {
+    blockOffset?: number;
+    blockLimit?: number;
+    blockTextLimit?: number;
+    blockNodeTypes?: readonly string[];
+    omitEmptyBlocks?: boolean;
+    dropTextPreview?: boolean;
+};
+export declare function readTextboxSnapshots(doc: BoundDocApi, options: TextboxSnapshotOptions, diagnostics: SnapshotDiagnostic[]): Promise<SnapshotTextbox[]>;
+export {};

package/dist/agent/textbox-snapshot.js

@@ -0,0 +1,60 @@
+import { normalizeSnapshotBlock } from './doc-snapshot.js';
+export async function readTextboxSnapshots(doc, options, diagnostics) {
+    if (typeof doc.query?.match !== 'function' || typeof doc.blocks?.list !== 'function')
+        return [];
+    const stories = new Map();
+    const snapshots = [];
+    try {
+        // Text discovery includes nested stories; blocks.list remains story-scoped
+        // so body ordinals used by existing action selectors cannot shift.
+        // Match one character per nonempty line. Cross-paragraph matches are
+        // rejected and retried at each character by the engine's regex scanner.
+        let offset = 0;
+        for (;;) {
+            const found = await doc.query.match({
+                select: { type: 'text', pattern: '(?<=^|\\n)[^\\n]', mode: 'regex' },
+                offset,
+                limit: 1000,
+            });
+            for (const item of found.items) {
+                const story = item.address.story;
+                if (story?.storyType === 'textbox')
+                    stories.set(story.textboxId, story);
+            }
+            offset += found.items.length;
+            if (offset >= found.total)
+                break;
+            if (found.items.length === 0)
+                throw new Error('Textbox discovery stopped before the reported match total.');
+        }
+    }
+    catch (error) {
+        diagnostics.push({
+            section: 'textboxes.discover',
+            message: error instanceof Error ? error.message : String(error),
+        });
+    }
+    const offset = Math.max(0, options.blockOffset ?? 0);
+    const limit = options.blockLimit != null && options.blockLimit > 0 ? options.blockLimit : 1000;
+    const textLimit = options.blockTextLimit != null && Number.isFinite(options.blockTextLimit) && options.blockTextLimit > 0
+        ? options.blockTextLimit
+        : null;
+    for (const story of stories.values()) {
+        try {
+            const listed = await doc.blocks.list({ in: story, includeText: true, offset, limit });
+            const blocks = listed.blocks
+                .filter((block) => !options.omitEmptyBlocks || Boolean(block.text?.trim()))
+                .map((block, index) => normalizeSnapshotBlock(block, offset + index, textLimit))
+                .filter((block) => !options.blockNodeTypes?.length || options.blockNodeTypes.includes(block.nodeType))
+                .map((block) => (options.dropTextPreview ? { ...block, textPreview: null } : block));
+            snapshots.push({ story, total: listed.total, blocks });
+        }
+        catch (error) {
+            diagnostics.push({
+                section: `textboxes.blocks:${story.textboxId}`,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return snapshots;
+}

package/dist/index.d.ts

@@ -94,7 +94,7 @@ export { dispatchIntentTool } from './generated/intent-dispatch.generated.js';
 export { wrapV2PresetCompat } from './agent/v2-preset-compat.js';
 export type { BoundDocApi } from './generated/client.js';
 export type { ActionName } from './agent/actions.js';
-export type { AgentReceipt, AgentApplyArgs, AgentVerifyArgs } from './agent/runtime.js';
+export type { AgentReceipt, AgentApplyArgs, AgentVerifyArgs, AgentInspectResult } from './agent/runtime.js';
 export type { GetSystemPromptOptions, GetToolsOptions, GetToolsResult, PresetDescriptor } from './presets.js';
 export { createAgentToolkit } from './tools.js';
 export type { AgentToolkit, CreateAgentToolkitInput } from './tools.js';

package/dist/runtime/sdk-version.generated.cjs

@@ -3,6 +3,6 @@
 // AUTO-GENERATED by scripts/embed-version.mjs — DO NOT EDIT.
 // Source of truth: package.json. Regenerated on every SDK build so the
 // SDK retains its own version identity when bundled into another package.
-const SDK_VERSION = '2.12.0-next.3';
+const SDK_VERSION = '2.12.0-next.5';
 
 exports.SDK_VERSION = SDK_VERSION;

package/dist/runtime/sdk-version.generated.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "2.12.0-next.3";
+export declare const SDK_VERSION = "2.12.0-next.5";

package/dist/runtime/sdk-version.generated.js

@@ -1,4 +1,4 @@
 // AUTO-GENERATED by scripts/embed-version.mjs — DO NOT EDIT.
 // Source of truth: package.json. Regenerated on every SDK build so the
 // SDK retains its own version identity when bundled into another package.
-export const SDK_VERSION = '2.12.0-next.3';
+export const SDK_VERSION = '2.12.0-next.5';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc/sdk",
-  "version": "2.12.0-next.3",
+  "version": "2.12.0-next.5",
   "description": "Node SDK for SuperDoc, wrapping the SuperDoc CLI to read and edit .docx files from JavaScript and TypeScript.",
   "private": false,
   "license": "AGPL-3.0",
@@ -38,11 +38,11 @@
     "typescript": "^5.9.2"
   },
   "optionalDependencies": {
-    "@superdoc/sdk-darwin-arm64": "2.12.0-next.3",
-    "@superdoc/sdk-darwin-x64": "2.12.0-next.3",
-    "@superdoc/sdk-linux-x64": "2.12.0-next.3",
-    "@superdoc/sdk-linux-arm64": "2.12.0-next.3",
-    "@superdoc/sdk-windows-x64": "2.12.0-next.3"
+    "@superdoc/sdk-darwin-arm64": "2.12.0-next.5",
+    "@superdoc/sdk-darwin-x64": "2.12.0-next.5",
+    "@superdoc/sdk-linux-x64": "2.12.0-next.5",
+    "@superdoc/sdk-linux-arm64": "2.12.0-next.5",
+    "@superdoc/sdk-windows-x64": "2.12.0-next.5"
   },
   "publishConfig": {
     "access": "public"
@@ -51,8 +51,8 @@
     "build": "rm -rf dist && node scripts/embed-version.mjs && node scripts/embed-prompts.mjs && node scripts/embed-tools.mjs && tsc && pnpm run typecheck:consumer && rollup -c rollup.cjs.config.mjs && rm -rf dist/prompts && mkdir -p dist/prompts && cp src/prompts/*.md dist/prompts/ && pnpm run audit:publish",
     "audit:publish": "node ../../../../scripts/audit-publish-artifact.mjs dist --label sdk-node-dist",
     "typecheck": "tsc --noEmit",
-    "typecheck:consumer": "tsc --noEmit --strict --skipLibCheck --target ES2022 --module NodeNext --moduleResolution NodeNext ../../../../tests/consumer-typecheck/src/sdk-per-open-collaboration-auth.mts ../../../../tests/consumer-typecheck/src/sdk-replace-file.mts ../../../../tests/consumer-typecheck/src/sdk-agent-evidence.mts ../../../../tests/consumer-typecheck/src/sdk-custom-actions.mts",
-    "test:agent-actions": "bun test src/__tests__/actions.test.ts src/__tests__/agent-runtime.test.ts src/__tests__/custom-actions.test.ts",
+    "typecheck:consumer": "tsc --noEmit --strict --skipLibCheck --target ES2022 --module NodeNext --moduleResolution NodeNext ../../../../tests/consumer-typecheck/src/sdk-per-open-collaboration-auth.mts ../../../../tests/consumer-typecheck/src/sdk-replace-file.mts ../../../../tests/consumer-typecheck/src/sdk-agent-evidence.mts ../../../../tests/consumer-typecheck/src/sdk-custom-actions.mts ../../../../tests/consumer-typecheck/src/sd4807-sdk-inspect.mts",
+    "test:agent-actions": "bun test src/__tests__/actions.test.ts src/__tests__/agent-runtime.test.ts src/__tests__/custom-actions.test.ts src/__tests__/textbox-snapshot.test.ts",
     "test:document-host": "bun test src/runtime/__tests__/host-spawn-args.test.ts src/runtime/__tests__/document-rpc.test.ts src/__tests__/structured-document-rpc.e2e.test.ts src/__tests__/request-timeout-ms.e2e.test.ts src/__tests__/agent-evidence.e2e.test.ts src/__tests__/agent-apply.e2e.test.ts src/__tests__/find-text.e2e.test.ts src/__tests__/custom-actions.e2e.test.ts",
     "smoke:product-action": "node scripts/product-action-smoke.mjs"
   }