@superdoc/sdk 2.6.0 → 2.7.0

package/dist/agent/actions.d.ts

@@ -37,6 +37,14 @@ export type InsertParagraphsArgs = {
     action: 'insert_paragraphs';
     texts?: readonly string[];
     text?: string;
+    /**
+     * Per-paragraph styling specs aligned with `texts` (same order/length).
+     * Entries with runs/marks get a post-insert format.apply pass so an inserted
+     * paragraph can mirror its section's pattern (e.g. a bold "(n)" lead-in).
+     * Populated by the dispatcher when a texts entry is a {text, runs, marks}
+     * object instead of a plain string.
+     */
+    textSpecs?: ReadonlyArray<AgentListItemSpec | null>;
     placement?: ActionPlacement;
     changeMode?: AgentChangeMode;
     headingLevel?: number;
@@ -74,7 +82,12 @@ export type DeleteBlocksArgs = {
 };
 export type AppendListArgs = {
     action: 'append_list';
-    items: readonly string[];
+    /**
+     * Plain strings or styled `{text|runs, marks?}` objects — the shared `items`
+     * schema advertises both, so both must dispatch. Styled entries are inserted
+     * as text and formatted in a post-pass, the same way add_list_items does it.
+     */
+    items: readonly (string | AgentListItemSpec)[];
     kind?: 'ordered' | 'bullet';
     headingText?: string;
     headingLevel?: number;
@@ -88,28 +101,80 @@ export type AppendListArgs = {
 export type InsertListItemsArgs = {
     listOrdinal?: number;
     items: readonly string[];
+    /**
+     * Per-item styling aligned by index with `items`, applied as a post-insert
+     * format pass (the workflow insert itself is text-only). Present when the
+     * caller wants run-level formatting on the new items.
+     */
+    styled?: readonly AgentListItemSpec[];
     changeMode?: AgentChangeMode;
 };
+/**
+ * Inline run marks the agent can request on a list-item segment. `fontSize` is
+ * in POINTS; `color`/`highlight` are hex (e.g. `#1a1a1a`). Mirrors the keys the
+ * shared `doc.format.apply` `inline` payload understands (see marksToInline).
+ */
+export type AgentRunMarks = {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+    fontFamily?: string;
+    fontSize?: number;
+    color?: string;
+    highlight?: string;
+};
+/** One styled text segment of a list item (e.g. first word plain, second italic). */
+export type AgentRunSpec = {
+    text: string;
+    marks?: AgentRunMarks;
+};
+/**
+ * One list item to append. Either plain `text`, or 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, so unstyled runs still
+ * inherit them. `level` nests relative to the anchor (0 = same level).
+ */
+export type AgentListItemSpec = {
+    text?: string;
+    runs?: readonly AgentRunSpec[];
+    marks?: AgentRunMarks;
+    level?: number;
+};
+/**
+ * One table cell's content — plain `text`, or ordered styled `runs` (so a cell
+ * can reproduce an intra-cell formatting pattern), with an optional whole-cell
+ * `marks` default. Same run/marks model as list items.
+ */
+export type AgentCellSpec = {
+    text?: string;
+    runs?: readonly AgentRunSpec[];
+    marks?: AgentRunMarks;
+};
 export type AddListItemsArgs = {
     action: 'add_list_items';
     /** Text inside an existing list item to identify the list to extend. Provide this OR listOrdinal. */
     anchorText?: string;
+    /**
+     * Anchor an existing list item directly by nodeId (internal — used when
+     * listOrdinal is resolved to a concrete item, so styled inserts reach this
+     * path regardless of which locator the model passed).
+     */
+    anchorNodeId?: string;
     /** 1-based index of the target list (from inspect). Alternative to anchorText. */
     listOrdinal?: number;
-    /** Items to append, with relative nesting level (0 = same as anchor, 1 = nested sub-item). */
-    entries?: ReadonlyArray<{
-        text: string;
-        level?: number;
-    }>;
-    /** Plain items to append at the list's base level (simple alias for entries without nesting). */
-    items?: readonly string[];
+    /** Items to append, with relative nesting level and optional per-run styling. */
+    entries?: ReadonlyArray<AgentListItemSpec>;
+    /** Plain or styled items to append at the list's base level. */
+    items?: ReadonlyArray<string | AgentListItemSpec>;
     changeMode?: AgentChangeMode;
 };
 export type CreateTableArgs = {
     action: 'create_table';
     rows: number;
     columns: number;
-    cellTexts?: ReadonlyArray<ReadonlyArray<string>>;
+    cellTexts?: ReadonlyArray<ReadonlyArray<string | AgentCellSpec>>;
     placement?: ActionPlacement;
     changeMode?: AgentChangeMode;
 };
@@ -233,7 +298,7 @@ export type InsertTableRowArgs = {
     tableOrdinal?: number;
     rowIndex?: number;
     position?: 'before' | 'after' | 'above' | 'below';
-    cellTexts?: readonly string[];
+    cellTexts?: readonly (string | AgentCellSpec)[];
     changeMode?: AgentChangeMode;
     dryRun?: boolean;
 };
@@ -243,6 +308,8 @@ export type InsertTableColumnArgs = {
     columnIndex?: number;
     position?: 'left' | 'right';
     headerText?: string;
+    /** Optional styled content per row for the new column's cells (index 0 = top row). */
+    cellTexts?: readonly (string | AgentCellSpec)[];
     changeMode?: AgentChangeMode;
 };
 export type DeleteTableRowArgs = {