@stablebaseline/sdk 0.4.0 → 0.4.2

package/README.md

@@ -1,9 +1,9 @@
 # @stablebaseline/sdk
 
 [![npm](https://img.shields.io/npm/v/@stablebaseline/sdk?color=orange)](https://www.npmjs.com/package/@stablebaseline/sdk)
-[![Tools](https://img.shields.io/badge/MCP%20tools-163-orange)](https://stablebaseline.io/docs/mcp/tools)
+[![Tools](https://img.shields.io/badge/MCP%20tools-184-orange)](https://stablebaseline.io/docs/mcp/tools)
 
-TypeScript SDK for the **[Stable Baseline](https://stablebaseline.io) REST API** — the simplest, most complete, end-to-end agent-managed company brain. Living docs, 40+ visual diagrams, plans, and a self-learning Knowledge Graph. 163 tools across 16 categories.
+TypeScript SDK for the **[Stable Baseline](https://stablebaseline.io) REST API** — the simplest, most complete, end-to-end agent-managed company brain. Living docs, 40+ visual diagrams, plans, and a self-learning Knowledge Graph. 184 tools across 19 categories.
 
 ## Install
 
@@ -52,7 +52,7 @@ Both go in the `Authorization: Bearer <...>` header.
 
 ## Tool catalogue
 
-163 tools across 16 categories. The full list lives at [stablebaseline.io/docs/mcp/tools](https://stablebaseline.io/docs/mcp/tools). Highlights:
+184 tools across 19 categories. The full list lives at [stablebaseline.io/docs/mcp/tools](https://stablebaseline.io/docs/mcp/tools). Highlights:
 
 | Category | Sample tools |
 |---|---|

package/dist/index.cjs

@@ -49,7 +49,7 @@ var StableBaseline = class {
   authHeader;
   signal;
   /**
-   * Strongly-typed dispatch surface. Every entry is one of the 163 MCP tools.
+   * Strongly-typed dispatch surface. Every entry is one of the 184 MCP tools.
    *
    *   const orgs = await sb.tools.listOrganisations({});
    *   const doc = await sb.tools.createDocument({ folderId, title, cdmd });

package/dist/index.d.cts

@@ -434,7 +434,7 @@ interface paths {
         put?: never;
         /**
          * getDocument
-         * @description Read a document's content with line numbers. Returns numbered lines for use with editDocument. Diagrams/images appear as OMITTED markers with metadata (type, diagramId, nlDescription) — use getDiagramInDocument(diagramId) for full DSL code, or dedicated diagram/image tools to manage them.
+         * @description Read a document's content with line numbers. Returns numbered lines for use with editDocument. Diagrams/images appear as OMITTED markers with metadata (type, diagramId, nlDescription) — use getDiagramInDocument(diagramId) for full DSL code, or dedicated diagram/image tools to manage them. Pass includeDiagramDsl:true to inline each diagram's DSL and versionTimestamp directly into its DIAGRAM_OMITTED marker (saves a getDiagramInDocument call when you intend to read or edit diagrams).
          */
         post: operations["getDocument"];
         delete?: never;
@@ -474,7 +474,7 @@ interface paths {
         put?: never;
         /**
          * editDocument
-         * @description Edit a document with line-based patches. Call getDocument first for line numbers and versionTimestamp. Call getCdmdLanguageGuide if unfamiliar with CDMD syntax. Do not edit DIAGRAM/IMAGE markers manually — use dedicated diagram/image tools. To @-mention a person in your patch, insert `<!-- REFERENCE: {"type":"user","id":"<user_uuid>","label":"Name"} -->`; look up the user_id via listAssignablePrincipals. Mentioned users are notified automatically.
+         * @description Edit a document: the PREFERRED tool for small targeted changes. Two patch dialects — do NOT mix them in one call. (1) ANCHOR patches {oldText, newText, before?, after?} — RECOMMENDED: replace an exact snippet of existing text with new text. oldText must match the document byte-for-byte AND be unique; if it occurs more than once, add `before`/`after` (short nearby surrounding text) to disambiguate. A no-match returns nearby context; an ambiguous match returns the occurrence count. Anchors do NOT drift, so you don't need fresh line numbers and they survive concurrent edits. Use newText:"" to delete. (2) LINE patches {startLine, endLine, replacement} — 1-based and INCLUSIVE: call getDocument first for line numbers; replace line 5 with {startLine:5,endLine:5}; INSERT before line N (deleting nothing) with {startLine:N,endLine:N-1}; append to an L-line document with {startLine:L+1,endLine:L}. Line numbers are ABSOLUTE and GO STALE after ANY edit — re-call getDocument before further line patches; out-of-range patches are rejected with the current line count. versionTimestamp from getDocument is required for optimistic locking, EXCEPT when dryRun:true. Set dryRun:true to apply the patches and get the resulting text back WITHOUT saving (verify before committing — kills retry loops). Do not edit or delete DIAGRAM/IMAGE marker lines (rejected with guidance) — use dedicated diagram/image tools. To @-mention a person, insert `<!-- REFERENCE: {"type":"user","id":"<user_uuid>","label":"Name"} -->`; look up the user_id via listAssignablePrincipals. Mentioned users are notified automatically.
          */
         post: operations["editDocument"];
         delete?: never;
@@ -494,7 +494,7 @@ interface paths {
         put?: never;
         /**
          * findAndReplaceTextInDocument
-         * @description Find and replace text in a document. Searches for all occurrences and replaces them. Case-sensitive by default. Diagrams/images are automatically protected — only document text is affected. Note: when the `replace` value contains a `<!-- REFERENCE: {...} -->` marker (e.g. inserting a user mention), it round-trips losslessly through the editor and triggers notifications if it adds a new user mention.
+         * @description Find and replace EXACT substrings in a document (NOT regex: wildcards and patterns are matched literally). Replaces EVERY occurrence and returns the replacement count; best for renames and repeated phrases. For a single targeted change at a known location, prefer editDocument (line patches with optimistic locking). Case-sensitive by default. Diagrams/images are automatically protected — only document text is affected. Note: when the `replace` value contains a `<!-- REFERENCE: {...} -->` marker (e.g. inserting a user mention), it round-trips losslessly through the editor and triggers notifications if it adds a new user mention.
          */
         post: operations["findAndReplaceTextInDocument"];
         delete?: never;
@@ -554,7 +554,7 @@ interface paths {
         put?: never;
         /**
          * updateDiagramInDocument
-         * @description Update a diagram's code, description, or properties. Call getDiagramTypeGuide for DSL syntax. Requires documentVersionTimestamp from getDocument. IMPORTANT: To change what the diagram visually shows, you MUST provide diagramCode with the full updated DSL source. The prompt and nlDescription fields are metadata only and do NOT change the rendered diagram. After updating, re-render with getDiagramImage to confirm it now looks right (iterate if not), and keep prompt/nlDescription in step with what the diagram now shows.
+         * @description Update a diagram's code, description, or properties. Call getDiagramTypeGuide for DSL syntax. Provide a version lock: EITHER documentVersionTimestamp (from getDocument — locks the whole document) OR diagramVersionTimestamp (from getDiagramInDocument, or getDocument with includeDiagramDsl:true — locks just THIS diagram, so two agents can edit two different diagrams in the same document concurrently without a conflict). At least one is required; diagramVersionTimestamp is preferred for concurrency. IMPORTANT: To change what the diagram visually shows, you MUST provide diagramCode with the full updated DSL source. The prompt and nlDescription fields are metadata only and do NOT change the rendered diagram. After updating, re-render with getDiagramImage to confirm it now looks right (iterate if not), and keep prompt/nlDescription in step with what the diagram now shows.
          */
         post: operations["updateDiagramInDocument"];
         delete?: never;
@@ -874,7 +874,7 @@ interface paths {
         put?: never;
         /**
          * getWhiteboardImage
-         * @description Render a whiteboard to an IMAGE so you can SEE it and confirm your edits look right, then iterate — like taking a screenshot. Returns the rendered board as a viewable PNG (default) attached to the result. Pass elementIds to render only specific shapes (e.g. to inspect one section/slide), format:'svg' for vector markup instead of a raster, or background to set the canvas colour. Call this after addWhiteboardElements/updateWhiteboardScene to check layout, overlaps, labels and alignment before continuing.
+         * @description Render a whiteboard to an IMAGE so you can SEE it and confirm your edits look right, then iterate — like taking a screenshot. Returns the rendered board as a viewable image attached to the result. Pass elementIds to render only specific shapes (e.g. to inspect one section/slide), region:{x,y,width,height} to capture an exact scene-coordinate window (e.g. the user's viewport), theme:'light' for the fastest single-variant render, format:'svg' for vector markup, or background to set the canvas colour. Unchanged boards return instantly from a content-keyed cache. Call this after addWhiteboardElements/updateWhiteboardScene to check layout, overlaps, labels and alignment before continuing.
          */
         post: operations["getWhiteboardImage"];
         delete?: never;
@@ -5598,6 +5598,8 @@ interface operations {
                     offset?: number;
                     /** @description Max lines to return. Default: 200. */
                     limit?: number;
+                    /** @description If true, inline each diagram's full DSL (as diagramCode) and its versionTimestamp into the DIAGRAM_OMITTED markers, so you can inspect and then edit a diagram (updateDiagramInDocument with diagramVersionTimestamp) without a second read. Default false. Note: large DSL inflates the response. */
+                    includeDiagramDsl?: boolean;
                     /** @description Field projection. Valid fields: id, title, friendlyId, friendlyIdNumber, projectId, folderId, createdAt, updatedAt, versionTimestamp. */
                     fields?: string[];
                     /** @description Content field projection. Valid fields: offset, limit, totalLines, nextOffset, metadata, text. */
@@ -5779,19 +5781,30 @@ interface operations {
                     folderId?: string;
                     /** @description Sort position within the parent folder. Use to reposition a single document. For batch sibling reorder, use reorderDocuments. */
                     position?: number;
-                    /** @description Version timestamp from getDocument() for optimistic locking. */
-                    versionTimestamp: number;
+                    /** @description Version timestamp from getDocument() for optimistic locking. Required unless dryRun:true. */
+                    versionTimestamp?: number;
+                    /** @description If true, apply the patches and RETURN the resulting document text without saving — no version bump, no lock required. Use to preview/verify a patch before committing. Default false. */
+                    dryRun?: boolean;
                     /** @description Version history summary. */
                     changeSummary?: string;
-                    /** @description Line-based patches. Can be empty if only updating title, folderId, or position. */
-                    patches?: {
+                    /** @description Patches to apply. Use EITHER anchor patches OR line patches, not both in the same call. May be empty if only updating title, folderId, or position. */
+                    patches?: ({
+                        /** @description Exact existing text to replace. Must match the document byte-for-byte and be unique (or use before/after to disambiguate). */
+                        oldText: string;
+                        /** @description Replacement text. Empty string to delete the matched text. */
+                        newText: string;
+                        /** @description Optional. Text that appears immediately before oldText, used to disambiguate when oldText occurs more than once. */
+                        before?: string;
+                        /** @description Optional. Text that appears immediately after oldText, used to disambiguate. */
+                        after?: string;
+                    } | {
                         /** @description 1-based start line. */
                         startLine: number;
                         /** @description 1-based end line (inclusive). */
                         endLine: number;
                         /** @description Replacement text. Empty string to delete lines. */
                         replacement: string;
-                    }[];
+                    })[];
                 };
             };
         };
@@ -6192,8 +6205,10 @@ interface operations {
                             [key: string]: string;
                         };
                     };
-                    /** @description Version timestamp from getDocument() for optimistic locking. */
-                    documentVersionTimestamp: number;
+                    /** @description Document-level optimistic lock: versionTimestamp from getDocument(). Locks the whole document. Provide this OR diagramVersionTimestamp (at least one is required). */
+                    documentVersionTimestamp?: number;
+                    /** @description Diagram-level optimistic lock: versionTimestamp of THIS diagram (from getDiagramInDocument, or getDocument with includeDiagramDsl:true). Pass this instead of documentVersionTimestamp to lock only this diagram, so concurrent edits to OTHER diagrams in the same document don't conflict. Preferred for multi-agent concurrency. The response returns the new diagram.diagramVersionTimestamp for chaining further edits. */
+                    diagramVersionTimestamp?: number;
                 };
             };
         };
@@ -7694,6 +7709,22 @@ interface operations {
                     elementIds?: string[];
                     /** @description Canvas background colour (default white), e.g. '#ffffff' or 'transparent'. */
                     background?: string;
+                    /** @description Capture only this scene-coordinate window instead of the whole board — e.g. the user's current viewport, or the neighbourhood you are editing. The output is cropped to the exact rectangle. */
+                    region?: {
+                        /** @description Window left edge (scene coordinates). */
+                        x: number;
+                        /** @description Window top edge (scene coordinates). */
+                        y: number;
+                        /** @description Window width (> 0). */
+                        width: number;
+                        /** @description Window height (> 0). */
+                        height: number;
+                    };
+                    /**
+                     * @description Which theme variant(s) to render. 'light' is fastest and right for inspecting your own edits; 'both' (default) also produces the dark variant used by the chat widget.
+                     * @enum {string}
+                     */
+                    theme?: "light" | "dark" | "both";
                 };
             };
         };
@@ -20202,7 +20233,7 @@ declare class StableBaseline {
     private authHeader;
     private signal?;
     /**
-     * Strongly-typed dispatch surface. Every entry is one of the 163 MCP tools.
+     * Strongly-typed dispatch surface. Every entry is one of the 184 MCP tools.
      *
      *   const orgs = await sb.tools.listOrganisations({});
      *   const doc = await sb.tools.createDocument({ folderId, title, cdmd });

package/dist/index.d.ts

@@ -434,7 +434,7 @@ interface paths {
         put?: never;
         /**
          * getDocument
-         * @description Read a document's content with line numbers. Returns numbered lines for use with editDocument. Diagrams/images appear as OMITTED markers with metadata (type, diagramId, nlDescription) — use getDiagramInDocument(diagramId) for full DSL code, or dedicated diagram/image tools to manage them.
+         * @description Read a document's content with line numbers. Returns numbered lines for use with editDocument. Diagrams/images appear as OMITTED markers with metadata (type, diagramId, nlDescription) — use getDiagramInDocument(diagramId) for full DSL code, or dedicated diagram/image tools to manage them. Pass includeDiagramDsl:true to inline each diagram's DSL and versionTimestamp directly into its DIAGRAM_OMITTED marker (saves a getDiagramInDocument call when you intend to read or edit diagrams).
          */
         post: operations["getDocument"];
         delete?: never;
@@ -474,7 +474,7 @@ interface paths {
         put?: never;
         /**
          * editDocument
-         * @description Edit a document with line-based patches. Call getDocument first for line numbers and versionTimestamp. Call getCdmdLanguageGuide if unfamiliar with CDMD syntax. Do not edit DIAGRAM/IMAGE markers manually — use dedicated diagram/image tools. To @-mention a person in your patch, insert `<!-- REFERENCE: {"type":"user","id":"<user_uuid>","label":"Name"} -->`; look up the user_id via listAssignablePrincipals. Mentioned users are notified automatically.
+         * @description Edit a document: the PREFERRED tool for small targeted changes. Two patch dialects — do NOT mix them in one call. (1) ANCHOR patches {oldText, newText, before?, after?} — RECOMMENDED: replace an exact snippet of existing text with new text. oldText must match the document byte-for-byte AND be unique; if it occurs more than once, add `before`/`after` (short nearby surrounding text) to disambiguate. A no-match returns nearby context; an ambiguous match returns the occurrence count. Anchors do NOT drift, so you don't need fresh line numbers and they survive concurrent edits. Use newText:"" to delete. (2) LINE patches {startLine, endLine, replacement} — 1-based and INCLUSIVE: call getDocument first for line numbers; replace line 5 with {startLine:5,endLine:5}; INSERT before line N (deleting nothing) with {startLine:N,endLine:N-1}; append to an L-line document with {startLine:L+1,endLine:L}. Line numbers are ABSOLUTE and GO STALE after ANY edit — re-call getDocument before further line patches; out-of-range patches are rejected with the current line count. versionTimestamp from getDocument is required for optimistic locking, EXCEPT when dryRun:true. Set dryRun:true to apply the patches and get the resulting text back WITHOUT saving (verify before committing — kills retry loops). Do not edit or delete DIAGRAM/IMAGE marker lines (rejected with guidance) — use dedicated diagram/image tools. To @-mention a person, insert `<!-- REFERENCE: {"type":"user","id":"<user_uuid>","label":"Name"} -->`; look up the user_id via listAssignablePrincipals. Mentioned users are notified automatically.
          */
         post: operations["editDocument"];
         delete?: never;
@@ -494,7 +494,7 @@ interface paths {
         put?: never;
         /**
          * findAndReplaceTextInDocument
-         * @description Find and replace text in a document. Searches for all occurrences and replaces them. Case-sensitive by default. Diagrams/images are automatically protected — only document text is affected. Note: when the `replace` value contains a `<!-- REFERENCE: {...} -->` marker (e.g. inserting a user mention), it round-trips losslessly through the editor and triggers notifications if it adds a new user mention.
+         * @description Find and replace EXACT substrings in a document (NOT regex: wildcards and patterns are matched literally). Replaces EVERY occurrence and returns the replacement count; best for renames and repeated phrases. For a single targeted change at a known location, prefer editDocument (line patches with optimistic locking). Case-sensitive by default. Diagrams/images are automatically protected — only document text is affected. Note: when the `replace` value contains a `<!-- REFERENCE: {...} -->` marker (e.g. inserting a user mention), it round-trips losslessly through the editor and triggers notifications if it adds a new user mention.
          */
         post: operations["findAndReplaceTextInDocument"];
         delete?: never;
@@ -554,7 +554,7 @@ interface paths {
         put?: never;
         /**
          * updateDiagramInDocument
-         * @description Update a diagram's code, description, or properties. Call getDiagramTypeGuide for DSL syntax. Requires documentVersionTimestamp from getDocument. IMPORTANT: To change what the diagram visually shows, you MUST provide diagramCode with the full updated DSL source. The prompt and nlDescription fields are metadata only and do NOT change the rendered diagram. After updating, re-render with getDiagramImage to confirm it now looks right (iterate if not), and keep prompt/nlDescription in step with what the diagram now shows.
+         * @description Update a diagram's code, description, or properties. Call getDiagramTypeGuide for DSL syntax. Provide a version lock: EITHER documentVersionTimestamp (from getDocument — locks the whole document) OR diagramVersionTimestamp (from getDiagramInDocument, or getDocument with includeDiagramDsl:true — locks just THIS diagram, so two agents can edit two different diagrams in the same document concurrently without a conflict). At least one is required; diagramVersionTimestamp is preferred for concurrency. IMPORTANT: To change what the diagram visually shows, you MUST provide diagramCode with the full updated DSL source. The prompt and nlDescription fields are metadata only and do NOT change the rendered diagram. After updating, re-render with getDiagramImage to confirm it now looks right (iterate if not), and keep prompt/nlDescription in step with what the diagram now shows.
          */
         post: operations["updateDiagramInDocument"];
         delete?: never;
@@ -874,7 +874,7 @@ interface paths {
         put?: never;
         /**
          * getWhiteboardImage
-         * @description Render a whiteboard to an IMAGE so you can SEE it and confirm your edits look right, then iterate — like taking a screenshot. Returns the rendered board as a viewable PNG (default) attached to the result. Pass elementIds to render only specific shapes (e.g. to inspect one section/slide), format:'svg' for vector markup instead of a raster, or background to set the canvas colour. Call this after addWhiteboardElements/updateWhiteboardScene to check layout, overlaps, labels and alignment before continuing.
+         * @description Render a whiteboard to an IMAGE so you can SEE it and confirm your edits look right, then iterate — like taking a screenshot. Returns the rendered board as a viewable image attached to the result. Pass elementIds to render only specific shapes (e.g. to inspect one section/slide), region:{x,y,width,height} to capture an exact scene-coordinate window (e.g. the user's viewport), theme:'light' for the fastest single-variant render, format:'svg' for vector markup, or background to set the canvas colour. Unchanged boards return instantly from a content-keyed cache. Call this after addWhiteboardElements/updateWhiteboardScene to check layout, overlaps, labels and alignment before continuing.
          */
         post: operations["getWhiteboardImage"];
         delete?: never;
@@ -5598,6 +5598,8 @@ interface operations {
                     offset?: number;
                     /** @description Max lines to return. Default: 200. */
                     limit?: number;
+                    /** @description If true, inline each diagram's full DSL (as diagramCode) and its versionTimestamp into the DIAGRAM_OMITTED markers, so you can inspect and then edit a diagram (updateDiagramInDocument with diagramVersionTimestamp) without a second read. Default false. Note: large DSL inflates the response. */
+                    includeDiagramDsl?: boolean;
                     /** @description Field projection. Valid fields: id, title, friendlyId, friendlyIdNumber, projectId, folderId, createdAt, updatedAt, versionTimestamp. */
                     fields?: string[];
                     /** @description Content field projection. Valid fields: offset, limit, totalLines, nextOffset, metadata, text. */
@@ -5779,19 +5781,30 @@ interface operations {
                     folderId?: string;
                     /** @description Sort position within the parent folder. Use to reposition a single document. For batch sibling reorder, use reorderDocuments. */
                     position?: number;
-                    /** @description Version timestamp from getDocument() for optimistic locking. */
-                    versionTimestamp: number;
+                    /** @description Version timestamp from getDocument() for optimistic locking. Required unless dryRun:true. */
+                    versionTimestamp?: number;
+                    /** @description If true, apply the patches and RETURN the resulting document text without saving — no version bump, no lock required. Use to preview/verify a patch before committing. Default false. */
+                    dryRun?: boolean;
                     /** @description Version history summary. */
                     changeSummary?: string;
-                    /** @description Line-based patches. Can be empty if only updating title, folderId, or position. */
-                    patches?: {
+                    /** @description Patches to apply. Use EITHER anchor patches OR line patches, not both in the same call. May be empty if only updating title, folderId, or position. */
+                    patches?: ({
+                        /** @description Exact existing text to replace. Must match the document byte-for-byte and be unique (or use before/after to disambiguate). */
+                        oldText: string;
+                        /** @description Replacement text. Empty string to delete the matched text. */
+                        newText: string;
+                        /** @description Optional. Text that appears immediately before oldText, used to disambiguate when oldText occurs more than once. */
+                        before?: string;
+                        /** @description Optional. Text that appears immediately after oldText, used to disambiguate. */
+                        after?: string;
+                    } | {
                         /** @description 1-based start line. */
                         startLine: number;
                         /** @description 1-based end line (inclusive). */
                         endLine: number;
                         /** @description Replacement text. Empty string to delete lines. */
                         replacement: string;
-                    }[];
+                    })[];
                 };
             };
         };
@@ -6192,8 +6205,10 @@ interface operations {
                             [key: string]: string;
                         };
                     };
-                    /** @description Version timestamp from getDocument() for optimistic locking. */
-                    documentVersionTimestamp: number;
+                    /** @description Document-level optimistic lock: versionTimestamp from getDocument(). Locks the whole document. Provide this OR diagramVersionTimestamp (at least one is required). */
+                    documentVersionTimestamp?: number;
+                    /** @description Diagram-level optimistic lock: versionTimestamp of THIS diagram (from getDiagramInDocument, or getDocument with includeDiagramDsl:true). Pass this instead of documentVersionTimestamp to lock only this diagram, so concurrent edits to OTHER diagrams in the same document don't conflict. Preferred for multi-agent concurrency. The response returns the new diagram.diagramVersionTimestamp for chaining further edits. */
+                    diagramVersionTimestamp?: number;
                 };
             };
         };
@@ -7694,6 +7709,22 @@ interface operations {
                     elementIds?: string[];
                     /** @description Canvas background colour (default white), e.g. '#ffffff' or 'transparent'. */
                     background?: string;
+                    /** @description Capture only this scene-coordinate window instead of the whole board — e.g. the user's current viewport, or the neighbourhood you are editing. The output is cropped to the exact rectangle. */
+                    region?: {
+                        /** @description Window left edge (scene coordinates). */
+                        x: number;
+                        /** @description Window top edge (scene coordinates). */
+                        y: number;
+                        /** @description Window width (> 0). */
+                        width: number;
+                        /** @description Window height (> 0). */
+                        height: number;
+                    };
+                    /**
+                     * @description Which theme variant(s) to render. 'light' is fastest and right for inspecting your own edits; 'both' (default) also produces the dark variant used by the chat widget.
+                     * @enum {string}
+                     */
+                    theme?: "light" | "dark" | "both";
                 };
             };
         };
@@ -20202,7 +20233,7 @@ declare class StableBaseline {
     private authHeader;
     private signal?;
     /**
-     * Strongly-typed dispatch surface. Every entry is one of the 163 MCP tools.
+     * Strongly-typed dispatch surface. Every entry is one of the 184 MCP tools.
      *
      *   const orgs = await sb.tools.listOrganisations({});
      *   const doc = await sb.tools.createDocument({ folderId, title, cdmd });

package/dist/index.js

@@ -23,7 +23,7 @@ var StableBaseline = class {
   authHeader;
   signal;
   /**
-   * Strongly-typed dispatch surface. Every entry is one of the 163 MCP tools.
+   * Strongly-typed dispatch surface. Every entry is one of the 184 MCP tools.
    *
    *   const orgs = await sb.tools.listOrganisations({});
    *   const doc = await sb.tools.createDocument({ folderId, title, cdmd });

package/openapi.json

@@ -2569,7 +2569,7 @@
     "/tools/getDocument": {
       "post": {
         "summary": "getDocument",
-        "description": "Read a document's content with line numbers. Returns numbered lines for use with editDocument. Diagrams/images appear as OMITTED markers with metadata (type, diagramId, nlDescription) — use getDiagramInDocument(diagramId) for full DSL code, or dedicated diagram/image tools to manage them.",
+        "description": "Read a document's content with line numbers. Returns numbered lines for use with editDocument. Diagrams/images appear as OMITTED markers with metadata (type, diagramId, nlDescription) — use getDiagramInDocument(diagramId) for full DSL code, or dedicated diagram/image tools to manage them. Pass includeDiagramDsl:true to inline each diagram's DSL and versionTimestamp directly into its DIAGRAM_OMITTED marker (saves a getDiagramInDocument call when you intend to read or edit diagrams).",
         "operationId": "getDocument",
         "tags": [
           "documents"
@@ -2593,6 +2593,10 @@
                     "type": "number",
                     "description": "Max lines to return. Default: 200."
                   },
+                  "includeDiagramDsl": {
+                    "type": "boolean",
+                    "description": "If true, inline each diagram's full DSL (as diagramCode) and its versionTimestamp into the DIAGRAM_OMITTED markers, so you can inspect and then edit a diagram (updateDiagramInDocument with diagramVersionTimestamp) without a second read. Default false. Note: large DSL inflates the response."
+                  },
                   "fields": {
                     "type": "array",
                     "items": {
@@ -2812,7 +2816,7 @@
     "/tools/editDocument": {
       "post": {
         "summary": "editDocument",
-        "description": "Edit a document with line-based patches. Call getDocument first for line numbers and versionTimestamp. Call getCdmdLanguageGuide if unfamiliar with CDMD syntax. Do not edit DIAGRAM/IMAGE markers manually — use dedicated diagram/image tools. To @-mention a person in your patch, insert `<!-- REFERENCE: {\"type\":\"user\",\"id\":\"<user_uuid>\",\"label\":\"Name\"} -->`; look up the user_id via listAssignablePrincipals. Mentioned users are notified automatically.",
+        "description": "Edit a document: the PREFERRED tool for small targeted changes. Two patch dialects — do NOT mix them in one call. (1) ANCHOR patches {oldText, newText, before?, after?} — RECOMMENDED: replace an exact snippet of existing text with new text. oldText must match the document byte-for-byte AND be unique; if it occurs more than once, add `before`/`after` (short nearby surrounding text) to disambiguate. A no-match returns nearby context; an ambiguous match returns the occurrence count. Anchors do NOT drift, so you don't need fresh line numbers and they survive concurrent edits. Use newText:\"\" to delete. (2) LINE patches {startLine, endLine, replacement} — 1-based and INCLUSIVE: call getDocument first for line numbers; replace line 5 with {startLine:5,endLine:5}; INSERT before line N (deleting nothing) with {startLine:N,endLine:N-1}; append to an L-line document with {startLine:L+1,endLine:L}. Line numbers are ABSOLUTE and GO STALE after ANY edit — re-call getDocument before further line patches; out-of-range patches are rejected with the current line count. versionTimestamp from getDocument is required for optimistic locking, EXCEPT when dryRun:true. Set dryRun:true to apply the patches and get the resulting text back WITHOUT saving (verify before committing — kills retry loops). Do not edit or delete DIAGRAM/IMAGE marker lines (rejected with guidance) — use dedicated diagram/image tools. To @-mention a person, insert `<!-- REFERENCE: {\"type\":\"user\",\"id\":\"<user_uuid>\",\"label\":\"Name\"} -->`; look up the user_id via listAssignablePrincipals. Mentioned users are notified automatically.",
         "operationId": "editDocument",
         "tags": [
           "documents"
@@ -2841,7 +2845,11 @@
                   },
                   "versionTimestamp": {
                     "type": "number",
-                    "description": "Version timestamp from getDocument() for optimistic locking."
+                    "description": "Version timestamp from getDocument() for optimistic locking. Required unless dryRun:true."
+                  },
+                  "dryRun": {
+                    "type": "boolean",
+                    "description": "If true, apply the patches and RETURN the resulting document text without saving — no version bump, no lock required. Use to preview/verify a patch before committing. Default false."
                   },
                   "changeSummary": {
                     "type": "string",
@@ -2849,34 +2857,64 @@
                   },
                   "patches": {
                     "type": "array",
-                    "description": "Line-based patches. Can be empty if only updating title, folderId, or position.",
+                    "description": "Patches to apply. Use EITHER anchor patches OR line patches, not both in the same call. May be empty if only updating title, folderId, or position.",
                     "items": {
-                      "type": "object",
-                      "properties": {
-                        "startLine": {
-                          "type": "number",
-                          "description": "1-based start line."
-                        },
-                        "endLine": {
-                          "type": "number",
-                          "description": "1-based end line (inclusive)."
+                      "oneOf": [
+                        {
+                          "type": "object",
+                          "description": "Anchor patch (recommended): replace an exact, unique snippet of existing text. Drift-proof — no line numbers needed.",
+                          "properties": {
+                            "oldText": {
+                              "type": "string",
+                              "description": "Exact existing text to replace. Must match the document byte-for-byte and be unique (or use before/after to disambiguate)."
+                            },
+                            "newText": {
+                              "type": "string",
+                              "description": "Replacement text. Empty string to delete the matched text."
+                            },
+                            "before": {
+                              "type": "string",
+                              "description": "Optional. Text that appears immediately before oldText, used to disambiguate when oldText occurs more than once."
+                            },
+                            "after": {
+                              "type": "string",
+                              "description": "Optional. Text that appears immediately after oldText, used to disambiguate."
+                            }
+                          },
+                          "required": [
+                            "oldText",
+                            "newText"
+                          ]
                         },
-                        "replacement": {
-                          "type": "string",
-                          "description": "Replacement text. Empty string to delete lines."
+                        {
+                          "type": "object",
+                          "description": "Line patch: 1-based inclusive line range. Requires fresh line numbers from getDocument().",
+                          "properties": {
+                            "startLine": {
+                              "type": "number",
+                              "description": "1-based start line."
+                            },
+                            "endLine": {
+                              "type": "number",
+                              "description": "1-based end line (inclusive)."
+                            },
+                            "replacement": {
+                              "type": "string",
+                              "description": "Replacement text. Empty string to delete lines."
+                            }
+                          },
+                          "required": [
+                            "startLine",
+                            "endLine",
+                            "replacement"
+                          ]
                         }
-                      },
-                      "required": [
-                        "startLine",
-                        "endLine",
-                        "replacement"
                       ]
                     }
                   }
                 },
                 "required": [
-                  "documentId",
-                  "versionTimestamp"
+                  "documentId"
                 ]
               }
             }
@@ -2960,7 +2998,7 @@
     "/tools/findAndReplaceTextInDocument": {
       "post": {
         "summary": "findAndReplaceTextInDocument",
-        "description": "Find and replace text in a document. Searches for all occurrences and replaces them. Case-sensitive by default. Diagrams/images are automatically protected — only document text is affected. Note: when the `replace` value contains a `<!-- REFERENCE: {...} -->` marker (e.g. inserting a user mention), it round-trips losslessly through the editor and triggers notifications if it adds a new user mention.",
+        "description": "Find and replace EXACT substrings in a document (NOT regex: wildcards and patterns are matched literally). Replaces EVERY occurrence and returns the replacement count; best for renames and repeated phrases. For a single targeted change at a known location, prefer editDocument (line patches with optimistic locking). Case-sensitive by default. Diagrams/images are automatically protected — only document text is affected. Note: when the `replace` value contains a `<!-- REFERENCE: {...} -->` marker (e.g. inserting a user mention), it round-trips losslessly through the editor and triggers notifications if it adds a new user mention.",
         "operationId": "findAndReplaceTextInDocument",
         "tags": [
           "documents"
@@ -3376,7 +3414,7 @@
     "/tools/updateDiagramInDocument": {
       "post": {
         "summary": "updateDiagramInDocument",
-        "description": "Update a diagram's code, description, or properties. Call getDiagramTypeGuide for DSL syntax. Requires documentVersionTimestamp from getDocument. IMPORTANT: To change what the diagram visually shows, you MUST provide diagramCode with the full updated DSL source. The prompt and nlDescription fields are metadata only and do NOT change the rendered diagram. After updating, re-render with getDiagramImage to confirm it now looks right (iterate if not), and keep prompt/nlDescription in step with what the diagram now shows.",
+        "description": "Update a diagram's code, description, or properties. Call getDiagramTypeGuide for DSL syntax. Provide a version lock: EITHER documentVersionTimestamp (from getDocument — locks the whole document) OR diagramVersionTimestamp (from getDiagramInDocument, or getDocument with includeDiagramDsl:true — locks just THIS diagram, so two agents can edit two different diagrams in the same document concurrently without a conflict). At least one is required; diagramVersionTimestamp is preferred for concurrency. IMPORTANT: To change what the diagram visually shows, you MUST provide diagramCode with the full updated DSL source. The prompt and nlDescription fields are metadata only and do NOT change the rendered diagram. After updating, re-render with getDiagramImage to confirm it now looks right (iterate if not), and keep prompt/nlDescription in step with what the diagram now shows.",
         "operationId": "updateDiagramInDocument",
         "tags": [
           "diagrams"
@@ -3435,12 +3473,15 @@
                   },
                   "documentVersionTimestamp": {
                     "type": "number",
-                    "description": "Version timestamp from getDocument() for optimistic locking."
+                    "description": "Document-level optimistic lock: versionTimestamp from getDocument(). Locks the whole document. Provide this OR diagramVersionTimestamp (at least one is required)."
+                  },
+                  "diagramVersionTimestamp": {
+                    "type": "number",
+                    "description": "Diagram-level optimistic lock: versionTimestamp of THIS diagram (from getDiagramInDocument, or getDocument with includeDiagramDsl:true). Pass this instead of documentVersionTimestamp to lock only this diagram, so concurrent edits to OTHER diagrams in the same document don't conflict. Preferred for multi-agent concurrency. The response returns the new diagram.diagramVersionTimestamp for chaining further edits."
                   }
                 },
                 "required": [
-                  "diagramId",
-                  "documentVersionTimestamp"
+                  "diagramId"
                 ]
               }
             }
@@ -5417,7 +5458,7 @@
     "/tools/getWhiteboardImage": {
       "post": {
         "summary": "getWhiteboardImage",
-        "description": "Render a whiteboard to an IMAGE so you can SEE it and confirm your edits look right, then iterate — like taking a screenshot. Returns the rendered board as a viewable PNG (default) attached to the result. Pass elementIds to render only specific shapes (e.g. to inspect one section/slide), format:'svg' for vector markup instead of a raster, or background to set the canvas colour. Call this after addWhiteboardElements/updateWhiteboardScene to check layout, overlaps, labels and alignment before continuing.",
+        "description": "Render a whiteboard to an IMAGE so you can SEE it and confirm your edits look right, then iterate — like taking a screenshot. Returns the rendered board as a viewable image attached to the result. Pass elementIds to render only specific shapes (e.g. to inspect one section/slide), region:{x,y,width,height} to capture an exact scene-coordinate window (e.g. the user's viewport), theme:'light' for the fastest single-variant render, format:'svg' for vector markup, or background to set the canvas colour. Unchanged boards return instantly from a content-keyed cache. Call this after addWhiteboardElements/updateWhiteboardScene to check layout, overlaps, labels and alignment before continuing.",
         "operationId": "getWhiteboardImage",
         "tags": [
           "whiteboards"
@@ -5451,6 +5492,43 @@
                   "background": {
                     "type": "string",
                     "description": "Canvas background colour (default white), e.g. '#ffffff' or 'transparent'."
+                  },
+                  "region": {
+                    "type": "object",
+                    "description": "Capture only this scene-coordinate window instead of the whole board — e.g. the user's current viewport, or the neighbourhood you are editing. The output is cropped to the exact rectangle.",
+                    "properties": {
+                      "x": {
+                        "type": "number",
+                        "description": "Window left edge (scene coordinates)."
+                      },
+                      "y": {
+                        "type": "number",
+                        "description": "Window top edge (scene coordinates)."
+                      },
+                      "width": {
+                        "type": "number",
+                        "description": "Window width (> 0)."
+                      },
+                      "height": {
+                        "type": "number",
+                        "description": "Window height (> 0)."
+                      }
+                    },
+                    "required": [
+                      "x",
+                      "y",
+                      "width",
+                      "height"
+                    ]
+                  },
+                  "theme": {
+                    "type": "string",
+                    "enum": [
+                      "light",
+                      "dark",
+                      "both"
+                    ],
+                    "description": "Which theme variant(s) to render. 'light' is fastest and right for inspecting your own edits; 'both' (default) also produces the dark variant used by the chat widget."
                   }
                 },
                 "required": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stablebaseline/sdk",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "TypeScript SDK for the Stable Baseline REST API. End-to-end agent-managed company brain — docs, diagrams, plans, and a self-learning Knowledge Graph. 184 tools across 19 categories.",
   "homepage": "https://stablebaseline.io",
   "repository": {

package/src/client.ts

@@ -93,7 +93,7 @@ export class StableBaseline {
   private signal?: AbortSignal;
 
   /**
-   * Strongly-typed dispatch surface. Every entry is one of the 163 MCP tools.
+   * Strongly-typed dispatch surface. Every entry is one of the 184 MCP tools.
    *
    *   const orgs = await sb.tools.listOrganisations({});
    *   const doc = await sb.tools.createDocument({ folderId, title, cdmd });

package/src/index.ts

@@ -10,7 +10,7 @@
 //     cdmd: "# ...",
 //   });
 //
-// All 163 MCP tools are reachable from `sb.tools.<toolName>(input)`. Types
+// All 184 MCP tools are reachable from `sb.tools.<toolName>(input)`. Types
 // are generated from the live OpenAPI spec (`openapi.json` in this package).
 
 export { StableBaseline } from "./client.js";

package/src/types.generated.ts

@@ -435,7 +435,7 @@ export interface paths {
         put?: never;
         /**
          * getDocument
-         * @description Read a document's content with line numbers. Returns numbered lines for use with editDocument. Diagrams/images appear as OMITTED markers with metadata (type, diagramId, nlDescription) — use getDiagramInDocument(diagramId) for full DSL code, or dedicated diagram/image tools to manage them.
+         * @description Read a document's content with line numbers. Returns numbered lines for use with editDocument. Diagrams/images appear as OMITTED markers with metadata (type, diagramId, nlDescription) — use getDiagramInDocument(diagramId) for full DSL code, or dedicated diagram/image tools to manage them. Pass includeDiagramDsl:true to inline each diagram's DSL and versionTimestamp directly into its DIAGRAM_OMITTED marker (saves a getDiagramInDocument call when you intend to read or edit diagrams).
          */
         post: operations["getDocument"];
         delete?: never;
@@ -475,7 +475,7 @@ export interface paths {
         put?: never;
         /**
          * editDocument
-         * @description Edit a document with line-based patches. Call getDocument first for line numbers and versionTimestamp. Call getCdmdLanguageGuide if unfamiliar with CDMD syntax. Do not edit DIAGRAM/IMAGE markers manually — use dedicated diagram/image tools. To @-mention a person in your patch, insert `<!-- REFERENCE: {"type":"user","id":"<user_uuid>","label":"Name"} -->`; look up the user_id via listAssignablePrincipals. Mentioned users are notified automatically.
+         * @description Edit a document: the PREFERRED tool for small targeted changes. Two patch dialects — do NOT mix them in one call. (1) ANCHOR patches {oldText, newText, before?, after?} — RECOMMENDED: replace an exact snippet of existing text with new text. oldText must match the document byte-for-byte AND be unique; if it occurs more than once, add `before`/`after` (short nearby surrounding text) to disambiguate. A no-match returns nearby context; an ambiguous match returns the occurrence count. Anchors do NOT drift, so you don't need fresh line numbers and they survive concurrent edits. Use newText:"" to delete. (2) LINE patches {startLine, endLine, replacement} — 1-based and INCLUSIVE: call getDocument first for line numbers; replace line 5 with {startLine:5,endLine:5}; INSERT before line N (deleting nothing) with {startLine:N,endLine:N-1}; append to an L-line document with {startLine:L+1,endLine:L}. Line numbers are ABSOLUTE and GO STALE after ANY edit — re-call getDocument before further line patches; out-of-range patches are rejected with the current line count. versionTimestamp from getDocument is required for optimistic locking, EXCEPT when dryRun:true. Set dryRun:true to apply the patches and get the resulting text back WITHOUT saving (verify before committing — kills retry loops). Do not edit or delete DIAGRAM/IMAGE marker lines (rejected with guidance) — use dedicated diagram/image tools. To @-mention a person, insert `<!-- REFERENCE: {"type":"user","id":"<user_uuid>","label":"Name"} -->`; look up the user_id via listAssignablePrincipals. Mentioned users are notified automatically.
          */
         post: operations["editDocument"];
         delete?: never;
@@ -495,7 +495,7 @@ export interface paths {
         put?: never;
         /**
          * findAndReplaceTextInDocument
-         * @description Find and replace text in a document. Searches for all occurrences and replaces them. Case-sensitive by default. Diagrams/images are automatically protected — only document text is affected. Note: when the `replace` value contains a `<!-- REFERENCE: {...} -->` marker (e.g. inserting a user mention), it round-trips losslessly through the editor and triggers notifications if it adds a new user mention.
+         * @description Find and replace EXACT substrings in a document (NOT regex: wildcards and patterns are matched literally). Replaces EVERY occurrence and returns the replacement count; best for renames and repeated phrases. For a single targeted change at a known location, prefer editDocument (line patches with optimistic locking). Case-sensitive by default. Diagrams/images are automatically protected — only document text is affected. Note: when the `replace` value contains a `<!-- REFERENCE: {...} -->` marker (e.g. inserting a user mention), it round-trips losslessly through the editor and triggers notifications if it adds a new user mention.
          */
         post: operations["findAndReplaceTextInDocument"];
         delete?: never;
@@ -555,7 +555,7 @@ export interface paths {
         put?: never;
         /**
          * updateDiagramInDocument
-         * @description Update a diagram's code, description, or properties. Call getDiagramTypeGuide for DSL syntax. Requires documentVersionTimestamp from getDocument. IMPORTANT: To change what the diagram visually shows, you MUST provide diagramCode with the full updated DSL source. The prompt and nlDescription fields are metadata only and do NOT change the rendered diagram. After updating, re-render with getDiagramImage to confirm it now looks right (iterate if not), and keep prompt/nlDescription in step with what the diagram now shows.
+         * @description Update a diagram's code, description, or properties. Call getDiagramTypeGuide for DSL syntax. Provide a version lock: EITHER documentVersionTimestamp (from getDocument — locks the whole document) OR diagramVersionTimestamp (from getDiagramInDocument, or getDocument with includeDiagramDsl:true — locks just THIS diagram, so two agents can edit two different diagrams in the same document concurrently without a conflict). At least one is required; diagramVersionTimestamp is preferred for concurrency. IMPORTANT: To change what the diagram visually shows, you MUST provide diagramCode with the full updated DSL source. The prompt and nlDescription fields are metadata only and do NOT change the rendered diagram. After updating, re-render with getDiagramImage to confirm it now looks right (iterate if not), and keep prompt/nlDescription in step with what the diagram now shows.
          */
         post: operations["updateDiagramInDocument"];
         delete?: never;
@@ -875,7 +875,7 @@ export interface paths {
         put?: never;
         /**
          * getWhiteboardImage
-         * @description Render a whiteboard to an IMAGE so you can SEE it and confirm your edits look right, then iterate — like taking a screenshot. Returns the rendered board as a viewable PNG (default) attached to the result. Pass elementIds to render only specific shapes (e.g. to inspect one section/slide), format:'svg' for vector markup instead of a raster, or background to set the canvas colour. Call this after addWhiteboardElements/updateWhiteboardScene to check layout, overlaps, labels and alignment before continuing.
+         * @description Render a whiteboard to an IMAGE so you can SEE it and confirm your edits look right, then iterate — like taking a screenshot. Returns the rendered board as a viewable image attached to the result. Pass elementIds to render only specific shapes (e.g. to inspect one section/slide), region:{x,y,width,height} to capture an exact scene-coordinate window (e.g. the user's viewport), theme:'light' for the fastest single-variant render, format:'svg' for vector markup, or background to set the canvas colour. Unchanged boards return instantly from a content-keyed cache. Call this after addWhiteboardElements/updateWhiteboardScene to check layout, overlaps, labels and alignment before continuing.
          */
         post: operations["getWhiteboardImage"];
         delete?: never;
@@ -5599,6 +5599,8 @@ export interface operations {
                     offset?: number;
                     /** @description Max lines to return. Default: 200. */
                     limit?: number;
+                    /** @description If true, inline each diagram's full DSL (as diagramCode) and its versionTimestamp into the DIAGRAM_OMITTED markers, so you can inspect and then edit a diagram (updateDiagramInDocument with diagramVersionTimestamp) without a second read. Default false. Note: large DSL inflates the response. */
+                    includeDiagramDsl?: boolean;
                     /** @description Field projection. Valid fields: id, title, friendlyId, friendlyIdNumber, projectId, folderId, createdAt, updatedAt, versionTimestamp. */
                     fields?: string[];
                     /** @description Content field projection. Valid fields: offset, limit, totalLines, nextOffset, metadata, text. */
@@ -5780,19 +5782,30 @@ export interface operations {
                     folderId?: string;
                     /** @description Sort position within the parent folder. Use to reposition a single document. For batch sibling reorder, use reorderDocuments. */
                     position?: number;
-                    /** @description Version timestamp from getDocument() for optimistic locking. */
-                    versionTimestamp: number;
+                    /** @description Version timestamp from getDocument() for optimistic locking. Required unless dryRun:true. */
+                    versionTimestamp?: number;
+                    /** @description If true, apply the patches and RETURN the resulting document text without saving — no version bump, no lock required. Use to preview/verify a patch before committing. Default false. */
+                    dryRun?: boolean;
                     /** @description Version history summary. */
                     changeSummary?: string;
-                    /** @description Line-based patches. Can be empty if only updating title, folderId, or position. */
-                    patches?: {
+                    /** @description Patches to apply. Use EITHER anchor patches OR line patches, not both in the same call. May be empty if only updating title, folderId, or position. */
+                    patches?: ({
+                        /** @description Exact existing text to replace. Must match the document byte-for-byte and be unique (or use before/after to disambiguate). */
+                        oldText: string;
+                        /** @description Replacement text. Empty string to delete the matched text. */
+                        newText: string;
+                        /** @description Optional. Text that appears immediately before oldText, used to disambiguate when oldText occurs more than once. */
+                        before?: string;
+                        /** @description Optional. Text that appears immediately after oldText, used to disambiguate. */
+                        after?: string;
+                    } | {
                         /** @description 1-based start line. */
                         startLine: number;
                         /** @description 1-based end line (inclusive). */
                         endLine: number;
                         /** @description Replacement text. Empty string to delete lines. */
                         replacement: string;
-                    }[];
+                    })[];
                 };
             };
         };
@@ -6193,8 +6206,10 @@ export interface operations {
                             [key: string]: string;
                         };
                     };
-                    /** @description Version timestamp from getDocument() for optimistic locking. */
-                    documentVersionTimestamp: number;
+                    /** @description Document-level optimistic lock: versionTimestamp from getDocument(). Locks the whole document. Provide this OR diagramVersionTimestamp (at least one is required). */
+                    documentVersionTimestamp?: number;
+                    /** @description Diagram-level optimistic lock: versionTimestamp of THIS diagram (from getDiagramInDocument, or getDocument with includeDiagramDsl:true). Pass this instead of documentVersionTimestamp to lock only this diagram, so concurrent edits to OTHER diagrams in the same document don't conflict. Preferred for multi-agent concurrency. The response returns the new diagram.diagramVersionTimestamp for chaining further edits. */
+                    diagramVersionTimestamp?: number;
                 };
             };
         };
@@ -7695,6 +7710,22 @@ export interface operations {
                     elementIds?: string[];
                     /** @description Canvas background colour (default white), e.g. '#ffffff' or 'transparent'. */
                     background?: string;
+                    /** @description Capture only this scene-coordinate window instead of the whole board — e.g. the user's current viewport, or the neighbourhood you are editing. The output is cropped to the exact rectangle. */
+                    region?: {
+                        /** @description Window left edge (scene coordinates). */
+                        x: number;
+                        /** @description Window top edge (scene coordinates). */
+                        y: number;
+                        /** @description Window width (> 0). */
+                        width: number;
+                        /** @description Window height (> 0). */
+                        height: number;
+                    };
+                    /**
+                     * @description Which theme variant(s) to render. 'light' is fastest and right for inspecting your own edits; 'both' (default) also produces the dark variant used by the chat widget.
+                     * @enum {string}
+                     */
+                    theme?: "light" | "dark" | "both";
                 };
             };
         };