@superdoc/sdk 2.5.0 → 2.7.0

package/dist/agent/catalog.cjs

@@ -32,6 +32,86 @@ const SELECTOR_SCHEMA = {
         kind: { type: 'string' },
     },
 };
+/**
+ * Inline run marks the agent can attach to a whole list item or a single run of
+ * one. `fontSize` is in POINTS; `color`/`highlight` are hex. Booleans may be set
+ * to `false` to explicitly clear a mark inherited from the anchor/whole-item.
+ */
+const RUN_MARKS_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        bold: { type: 'boolean' },
+        italic: { type: 'boolean' },
+        underline: { type: 'boolean' },
+        strikethrough: { type: 'boolean' },
+        fontFamily: { type: 'string' },
+        fontSize: { type: 'number', description: 'point size, e.g. 16' },
+        color: { type: 'string', description: 'hex color, e.g. #1a1a1a' },
+        highlight: { type: 'string', description: 'hex highlight color' },
+    },
+};
+/**
+ * One list item to add. Either a plain string, or an object with ordered styled
+ * `runs` so the agent can replicate an intra-item formatting PATTERN it inferred
+ * from the sibling items (e.g. first word plain, second word italic). `marks`
+ * are whole-item defaults applied under the per-run marks; `level` nests the
+ * item relative to the anchor (0 = same level). Unstyled items still inherit the
+ * list's existing run formatting automatically.
+ */
+const LIST_ITEM_SCHEMA = {
+    oneOf: [
+        { type: 'string' },
+        {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                text: { type: 'string', description: 'plain item text (use instead of runs when unstyled)' },
+                runs: {
+                    type: 'array',
+                    description: 'ordered styled segments; concatenated they form the item text',
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: { text: { type: 'string' }, marks: RUN_MARKS_SCHEMA },
+                        required: ['text'],
+                    },
+                },
+                marks: RUN_MARKS_SCHEMA,
+                level: { type: 'number' },
+            },
+        },
+    ],
+};
+/**
+ * One table cell: a plain string, or a styled object {text | runs, marks?} —
+ * same run/marks model as list items, so a cell can reproduce an intra-cell
+ * formatting pattern. Used by create_table (rows of cells) and
+ * insert_table_row / insert_table_column (a single row/column of cells).
+ */
+const CELL_SCHEMA = {
+    oneOf: [
+        { type: 'string' },
+        {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                text: { type: 'string', description: 'plain cell text (use instead of runs when unstyled)' },
+                runs: {
+                    type: 'array',
+                    description: 'ordered styled segments; concatenated they form the cell text',
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: { text: { type: 'string' }, marks: RUN_MARKS_SCHEMA },
+                        required: ['text'],
+                    },
+                },
+                marks: RUN_MARKS_SCHEMA,
+            },
+        },
+    ],
+};
 /**
  * Per-argument JSON schema for every `superdoc_perform_action` argument EXCEPT `action`.
  * The single source of truth for each arg's JSON schema. ACTION_ARG_PROPERTIES
@@ -40,16 +120,22 @@ const SELECTOR_SCHEMA = {
  */
 const ACTION_ARG_SCHEMA = {
     text: { type: 'string' },
-    texts: { type: 'array', items: { type: 'string' } },
+    // insert_paragraphs: each entry is a plain string or a styled {text|runs,
+    // marks?} object (same run/marks model as list items) so an inserted
+    // paragraph can mirror its section's intra-paragraph formatting pattern.
+    texts: { type: 'array', items: CELL_SCHEMA },
     level: { type: 'number' },
     headingText: { type: 'string' },
     headingLevel: { type: 'number' },
     kind: { type: 'string', enum: ['ordered', 'bullet'] },
-    items: { type: 'array', items: { type: 'string' } },
+    items: { type: 'array', items: LIST_ITEM_SCHEMA },
     listOrdinal: { type: 'number' },
     rows: { type: 'number' },
     columns: { type: 'number' },
-    cellTexts: { type: 'array', items: {} },
+    // create_table passes rows of cells (2D); insert_table_row/column pass a
+    // single row/column of cells (1D). Accept either: each entry is a cell or an
+    // array of cells.
+    cellTexts: { type: 'array', items: { oneOf: [CELL_SCHEMA, { type: 'array', items: CELL_SCHEMA }] } },
     edits: {
         type: 'array',
         items: {
@@ -117,11 +203,7 @@ const ACTION_ARG_SCHEMA = {
     accentColor: { type: 'string' },
     entries: {
         type: 'array',
-        items: {
-            type: 'object',
-            properties: { text: { type: 'string' }, level: { type: 'number' } },
-            required: ['text'],
-        },
+        items: LIST_ITEM_SCHEMA,
     },
     lineSpacing: { type: 'number' },
     spaceBefore: { type: 'number' },
@@ -244,16 +326,24 @@ function buildPerformActionDefinition(includedActions) {
 const AGENT_TOOL_DEFINITIONS = [
     {
         name: 'superdoc_inspect',
-        description: 'Build a deterministic document snapshot. Prefer the narrowest inspect that answers the question: countsOnly for pure counts, includeDomains to limit which domains are returned, and blockNodeTypes when only specific block types matter. For LARGE documents, read in windows: blockOffset/blockLimit return a contiguous slice of blocks (ordinals are absolute, so windows line up), and omitEmptyBlocks/dropTextPreview trim payload for a reading pass.',
+        description: "Build a deterministic document snapshot. Prefer the narrowest inspect that answers the question: countsOnly for pure counts, includeDomains to limit which domains are returned, and blockNodeTypes when only specific block types matter. TO FIND A SECTION/PHRASE IN A LARGE DOCUMENT, pass findText: the full-text scan runs server-side, `finds` reports every matching block's ordinal + preview, and the returned block window auto-centers on the first match — ONE findText call replaces a linear sweep of wide windows; never page through a large document hunting for a heading. For sequential reading, use windows: blockOffset/blockLimit return a contiguous slice of blocks (ordinals are absolute, so windows line up), and omitEmptyBlocks/dropTextPreview trim payload for a reading pass. Each list item carries a `runs` array of its inline segments {start,end,text, bold/italic/underline/strike?, fontFamily?, fontSize?, color?} BY DEFAULT, revealing the intra-item formatting pattern (e.g. first word plain, second italic) to reproduce via add_list_items `runs` — pass includeListItemRuns:false to omit it for a pure read. Table cells do NOT carry runs by default (tables can be large); pass includeTableCellRuns:true to attach the same per-run formatting to each cell when you need to match a table's cell styling. Body blocks likewise: pass includeBlockRuns:true (with a NARROW blockOffset/blockLimit window around the target) to attach per-run formatting to paragraphs, revealing a section's pattern (e.g. clauses with a bold '(m)' lead-in) to reproduce via insert_paragraphs styled texts.",
         inputSchema: {
             type: 'object',
             additionalProperties: false,
             properties: {
                 countsOnly: { type: 'boolean' },
+                findText: { type: 'string' },
+                findLimit: { type: 'number', minimum: 1 },
                 blockOffset: { type: 'number', minimum: 0 },
                 blockLimit: { type: 'number', minimum: 1 },
                 omitEmptyBlocks: { type: 'boolean' },
                 dropTextPreview: { type: 'boolean' },
+                includeListItemRuns: { type: 'boolean' },
+                listItemRunsLimit: { type: 'number', minimum: 1 },
+                includeTableCellRuns: { type: 'boolean' },
+                tableCellRunsLimit: { type: 'number', minimum: 1 },
+                includeBlockRuns: { type: 'boolean' },
+                blockRunsLimit: { type: 'number', minimum: 1 },
                 includeDomains: {
                     type: 'array',
                     items: {
@@ -476,7 +566,10 @@ function isAgentToolName(toolName) {
 exports.ACTION_ARG_SCHEMA = ACTION_ARG_SCHEMA;
 exports.AGENT_TOOL_DEFINITIONS = AGENT_TOOL_DEFINITIONS;
 exports.AGENT_TOOL_NAMES = AGENT_TOOL_NAMES;
+exports.CELL_SCHEMA = CELL_SCHEMA;
+exports.LIST_ITEM_SCHEMA = LIST_ITEM_SCHEMA;
 exports.PUBLIC_AGENT_TOOL_NAMES = PUBLIC_AGENT_TOOL_NAMES;
+exports.RUN_MARKS_SCHEMA = RUN_MARKS_SCHEMA;
 exports.SELECTOR_SCHEMA = SELECTOR_SCHEMA;
 exports.isAgentToolName = isAgentToolName;
 exports.listAgentTools = listAgentTools;

package/dist/agent/catalog.d.ts

@@ -67,6 +67,249 @@ export declare const SELECTOR_SCHEMA: {
         };
     };
 };
+/**
+ * Inline run marks the agent can attach to a whole list item or a single run of
+ * one. `fontSize` is in POINTS; `color`/`highlight` are hex. Booleans may be set
+ * to `false` to explicitly clear a mark inherited from the anchor/whole-item.
+ */
+export declare const RUN_MARKS_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly bold: {
+            readonly type: "boolean";
+        };
+        readonly italic: {
+            readonly type: "boolean";
+        };
+        readonly underline: {
+            readonly type: "boolean";
+        };
+        readonly strikethrough: {
+            readonly type: "boolean";
+        };
+        readonly fontFamily: {
+            readonly type: "string";
+        };
+        readonly fontSize: {
+            readonly type: "number";
+            readonly description: "point size, e.g. 16";
+        };
+        readonly color: {
+            readonly type: "string";
+            readonly description: "hex color, e.g. #1a1a1a";
+        };
+        readonly highlight: {
+            readonly type: "string";
+            readonly description: "hex highlight color";
+        };
+    };
+};
+/**
+ * One list item to add. Either a plain string, or an object with ordered styled
+ * `runs` so the agent can replicate an intra-item formatting PATTERN it inferred
+ * from the sibling items (e.g. first word plain, second word italic). `marks`
+ * are whole-item defaults applied under the per-run marks; `level` nests the
+ * item relative to the anchor (0 = same level). Unstyled items still inherit the
+ * list's existing run formatting automatically.
+ */
+export declare const LIST_ITEM_SCHEMA: {
+    readonly oneOf: readonly [{
+        readonly type: "string";
+    }, {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly text: {
+                readonly type: "string";
+                readonly description: "plain item text (use instead of runs when unstyled)";
+            };
+            readonly runs: {
+                readonly type: "array";
+                readonly description: "ordered styled segments; concatenated they form the item text";
+                readonly items: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly text: {
+                            readonly type: "string";
+                        };
+                        readonly marks: {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly properties: {
+                                readonly bold: {
+                                    readonly type: "boolean";
+                                };
+                                readonly italic: {
+                                    readonly type: "boolean";
+                                };
+                                readonly underline: {
+                                    readonly type: "boolean";
+                                };
+                                readonly strikethrough: {
+                                    readonly type: "boolean";
+                                };
+                                readonly fontFamily: {
+                                    readonly type: "string";
+                                };
+                                readonly fontSize: {
+                                    readonly type: "number";
+                                    readonly description: "point size, e.g. 16";
+                                };
+                                readonly color: {
+                                    readonly type: "string";
+                                    readonly description: "hex color, e.g. #1a1a1a";
+                                };
+                                readonly highlight: {
+                                    readonly type: "string";
+                                    readonly description: "hex highlight color";
+                                };
+                            };
+                        };
+                    };
+                    readonly required: readonly ["text"];
+                };
+            };
+            readonly marks: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly bold: {
+                        readonly type: "boolean";
+                    };
+                    readonly italic: {
+                        readonly type: "boolean";
+                    };
+                    readonly underline: {
+                        readonly type: "boolean";
+                    };
+                    readonly strikethrough: {
+                        readonly type: "boolean";
+                    };
+                    readonly fontFamily: {
+                        readonly type: "string";
+                    };
+                    readonly fontSize: {
+                        readonly type: "number";
+                        readonly description: "point size, e.g. 16";
+                    };
+                    readonly color: {
+                        readonly type: "string";
+                        readonly description: "hex color, e.g. #1a1a1a";
+                    };
+                    readonly highlight: {
+                        readonly type: "string";
+                        readonly description: "hex highlight color";
+                    };
+                };
+            };
+            readonly level: {
+                readonly type: "number";
+            };
+        };
+    }];
+};
+/**
+ * One table cell: a plain string, or a styled object {text | runs, marks?} —
+ * same run/marks model as list items, so a cell can reproduce an intra-cell
+ * formatting pattern. Used by create_table (rows of cells) and
+ * insert_table_row / insert_table_column (a single row/column of cells).
+ */
+export declare const CELL_SCHEMA: {
+    readonly oneOf: readonly [{
+        readonly type: "string";
+    }, {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly text: {
+                readonly type: "string";
+                readonly description: "plain cell text (use instead of runs when unstyled)";
+            };
+            readonly runs: {
+                readonly type: "array";
+                readonly description: "ordered styled segments; concatenated they form the cell text";
+                readonly items: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly text: {
+                            readonly type: "string";
+                        };
+                        readonly marks: {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly properties: {
+                                readonly bold: {
+                                    readonly type: "boolean";
+                                };
+                                readonly italic: {
+                                    readonly type: "boolean";
+                                };
+                                readonly underline: {
+                                    readonly type: "boolean";
+                                };
+                                readonly strikethrough: {
+                                    readonly type: "boolean";
+                                };
+                                readonly fontFamily: {
+                                    readonly type: "string";
+                                };
+                                readonly fontSize: {
+                                    readonly type: "number";
+                                    readonly description: "point size, e.g. 16";
+                                };
+                                readonly color: {
+                                    readonly type: "string";
+                                    readonly description: "hex color, e.g. #1a1a1a";
+                                };
+                                readonly highlight: {
+                                    readonly type: "string";
+                                    readonly description: "hex highlight color";
+                                };
+                            };
+                        };
+                    };
+                    readonly required: readonly ["text"];
+                };
+            };
+            readonly marks: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly bold: {
+                        readonly type: "boolean";
+                    };
+                    readonly italic: {
+                        readonly type: "boolean";
+                    };
+                    readonly underline: {
+                        readonly type: "boolean";
+                    };
+                    readonly strikethrough: {
+                        readonly type: "boolean";
+                    };
+                    readonly fontFamily: {
+                        readonly type: "string";
+                    };
+                    readonly fontSize: {
+                        readonly type: "number";
+                        readonly description: "point size, e.g. 16";
+                    };
+                    readonly color: {
+                        readonly type: "string";
+                        readonly description: "hex color, e.g. #1a1a1a";
+                    };
+                    readonly highlight: {
+                        readonly type: "string";
+                        readonly description: "hex highlight color";
+                    };
+                };
+            };
+        };
+    }];
+};
 /**
  * Per-argument JSON schema for every `superdoc_perform_action` argument EXCEPT `action`.
  * The single source of truth for each arg's JSON schema. ACTION_ARG_PROPERTIES

package/dist/agent/catalog.js

@@ -29,6 +29,86 @@ export const SELECTOR_SCHEMA = {
         kind: { type: 'string' },
     },
 };
+/**
+ * Inline run marks the agent can attach to a whole list item or a single run of
+ * one. `fontSize` is in POINTS; `color`/`highlight` are hex. Booleans may be set
+ * to `false` to explicitly clear a mark inherited from the anchor/whole-item.
+ */
+export const RUN_MARKS_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        bold: { type: 'boolean' },
+        italic: { type: 'boolean' },
+        underline: { type: 'boolean' },
+        strikethrough: { type: 'boolean' },
+        fontFamily: { type: 'string' },
+        fontSize: { type: 'number', description: 'point size, e.g. 16' },
+        color: { type: 'string', description: 'hex color, e.g. #1a1a1a' },
+        highlight: { type: 'string', description: 'hex highlight color' },
+    },
+};
+/**
+ * One list item to add. Either a plain string, or an object with ordered styled
+ * `runs` so the agent can replicate an intra-item formatting PATTERN it inferred
+ * from the sibling items (e.g. first word plain, second word italic). `marks`
+ * are whole-item defaults applied under the per-run marks; `level` nests the
+ * item relative to the anchor (0 = same level). Unstyled items still inherit the
+ * list's existing run formatting automatically.
+ */
+export const LIST_ITEM_SCHEMA = {
+    oneOf: [
+        { type: 'string' },
+        {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                text: { type: 'string', description: 'plain item text (use instead of runs when unstyled)' },
+                runs: {
+                    type: 'array',
+                    description: 'ordered styled segments; concatenated they form the item text',
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: { text: { type: 'string' }, marks: RUN_MARKS_SCHEMA },
+                        required: ['text'],
+                    },
+                },
+                marks: RUN_MARKS_SCHEMA,
+                level: { type: 'number' },
+            },
+        },
+    ],
+};
+/**
+ * One table cell: a plain string, or a styled object {text | runs, marks?} —
+ * same run/marks model as list items, so a cell can reproduce an intra-cell
+ * formatting pattern. Used by create_table (rows of cells) and
+ * insert_table_row / insert_table_column (a single row/column of cells).
+ */
+export const CELL_SCHEMA = {
+    oneOf: [
+        { type: 'string' },
+        {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                text: { type: 'string', description: 'plain cell text (use instead of runs when unstyled)' },
+                runs: {
+                    type: 'array',
+                    description: 'ordered styled segments; concatenated they form the cell text',
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: { text: { type: 'string' }, marks: RUN_MARKS_SCHEMA },
+                        required: ['text'],
+                    },
+                },
+                marks: RUN_MARKS_SCHEMA,
+            },
+        },
+    ],
+};
 /**
  * Per-argument JSON schema for every `superdoc_perform_action` argument EXCEPT `action`.
  * The single source of truth for each arg's JSON schema. ACTION_ARG_PROPERTIES
@@ -37,16 +117,22 @@ export const SELECTOR_SCHEMA = {
  */
 export const ACTION_ARG_SCHEMA = {
     text: { type: 'string' },
-    texts: { type: 'array', items: { type: 'string' } },
+    // insert_paragraphs: each entry is a plain string or a styled {text|runs,
+    // marks?} object (same run/marks model as list items) so an inserted
+    // paragraph can mirror its section's intra-paragraph formatting pattern.
+    texts: { type: 'array', items: CELL_SCHEMA },
     level: { type: 'number' },
     headingText: { type: 'string' },
     headingLevel: { type: 'number' },
     kind: { type: 'string', enum: ['ordered', 'bullet'] },
-    items: { type: 'array', items: { type: 'string' } },
+    items: { type: 'array', items: LIST_ITEM_SCHEMA },
     listOrdinal: { type: 'number' },
     rows: { type: 'number' },
     columns: { type: 'number' },
-    cellTexts: { type: 'array', items: {} },
+    // create_table passes rows of cells (2D); insert_table_row/column pass a
+    // single row/column of cells (1D). Accept either: each entry is a cell or an
+    // array of cells.
+    cellTexts: { type: 'array', items: { oneOf: [CELL_SCHEMA, { type: 'array', items: CELL_SCHEMA }] } },
     edits: {
         type: 'array',
         items: {
@@ -114,11 +200,7 @@ export const ACTION_ARG_SCHEMA = {
     accentColor: { type: 'string' },
     entries: {
         type: 'array',
-        items: {
-            type: 'object',
-            properties: { text: { type: 'string' }, level: { type: 'number' } },
-            required: ['text'],
-        },
+        items: LIST_ITEM_SCHEMA,
     },
     lineSpacing: { type: 'number' },
     spaceBefore: { type: 'number' },
@@ -241,16 +323,24 @@ function buildPerformActionDefinition(includedActions) {
 export const AGENT_TOOL_DEFINITIONS = [
     {
         name: 'superdoc_inspect',
-        description: 'Build a deterministic document snapshot. Prefer the narrowest inspect that answers the question: countsOnly for pure counts, includeDomains to limit which domains are returned, and blockNodeTypes when only specific block types matter. For LARGE documents, read in windows: blockOffset/blockLimit return a contiguous slice of blocks (ordinals are absolute, so windows line up), and omitEmptyBlocks/dropTextPreview trim payload for a reading pass.',
+        description: "Build a deterministic document snapshot. Prefer the narrowest inspect that answers the question: countsOnly for pure counts, includeDomains to limit which domains are returned, and blockNodeTypes when only specific block types matter. TO FIND A SECTION/PHRASE IN A LARGE DOCUMENT, pass findText: the full-text scan runs server-side, `finds` reports every matching block's ordinal + preview, and the returned block window auto-centers on the first match — ONE findText call replaces a linear sweep of wide windows; never page through a large document hunting for a heading. For sequential reading, use windows: blockOffset/blockLimit return a contiguous slice of blocks (ordinals are absolute, so windows line up), and omitEmptyBlocks/dropTextPreview trim payload for a reading pass. Each list item carries a `runs` array of its inline segments {start,end,text, bold/italic/underline/strike?, fontFamily?, fontSize?, color?} BY DEFAULT, revealing the intra-item formatting pattern (e.g. first word plain, second italic) to reproduce via add_list_items `runs` — pass includeListItemRuns:false to omit it for a pure read. Table cells do NOT carry runs by default (tables can be large); pass includeTableCellRuns:true to attach the same per-run formatting to each cell when you need to match a table's cell styling. Body blocks likewise: pass includeBlockRuns:true (with a NARROW blockOffset/blockLimit window around the target) to attach per-run formatting to paragraphs, revealing a section's pattern (e.g. clauses with a bold '(m)' lead-in) to reproduce via insert_paragraphs styled texts.",
         inputSchema: {
             type: 'object',
             additionalProperties: false,
             properties: {
                 countsOnly: { type: 'boolean' },
+                findText: { type: 'string' },
+                findLimit: { type: 'number', minimum: 1 },
                 blockOffset: { type: 'number', minimum: 0 },
                 blockLimit: { type: 'number', minimum: 1 },
                 omitEmptyBlocks: { type: 'boolean' },
                 dropTextPreview: { type: 'boolean' },
+                includeListItemRuns: { type: 'boolean' },
+                listItemRunsLimit: { type: 'number', minimum: 1 },
+                includeTableCellRuns: { type: 'boolean' },
+                tableCellRunsLimit: { type: 'number', minimum: 1 },
+                includeBlockRuns: { type: 'boolean' },
+                blockRunsLimit: { type: 'number', minimum: 1 },
                 includeDomains: {
                     type: 'array',
                     items: {