@orangecatai/element 0.0.1 → 0.0.3

package/dist/types/excalidraw/components/ai-chat/canvasTools.d.ts

@@ -0,0 +1,685 @@
+import type { ExcalidrawElement } from "@orangecatai/element/types";
+import type { ExcalidrawImperativeAPI } from "../../types";
+export declare const CANVAS_TOOLS: readonly [{
+    readonly type: "function";
+    readonly function: {
+        readonly name: "create_frame";
+        readonly description: "Create a new frame on the canvas. Frames act as artboards that clip their children. Default size is 512x512.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly width: {
+                    readonly type: "number";
+                    readonly description: "Frame width in pixels (default 512)";
+                };
+                readonly height: {
+                    readonly type: "number";
+                    readonly description: "Frame height in pixels (default 512)";
+                };
+                readonly name: {
+                    readonly type: "string";
+                    readonly description: "Optional display name for the frame";
+                };
+            };
+            readonly required: readonly [];
+            readonly additionalProperties: false;
+        };
+    };
+}, {
+    readonly type: "function";
+    readonly function: {
+        readonly name: "add_rectangle";
+        readonly description: "Add a filled rectangle inside a frame. Commonly used for solid background fills behind images and text.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly frameId: {
+                    readonly type: "string";
+                    readonly description: "ID of the parent frame";
+                };
+                readonly x: {
+                    readonly type: "number";
+                    readonly description: "X position relative to canvas (use the frame's x for full coverage)";
+                };
+                readonly y: {
+                    readonly type: "number";
+                    readonly description: "Y position relative to canvas (use the frame's y for full coverage)";
+                };
+                readonly width: {
+                    readonly type: "number";
+                    readonly description: "Rectangle width in pixels";
+                };
+                readonly height: {
+                    readonly type: "number";
+                    readonly description: "Rectangle height in pixels";
+                };
+                readonly backgroundColor: {
+                    readonly type: "string";
+                    readonly description: "Fill color as hex string e.g. \"#1a1a2e\". Use \"transparent\" for no fill.";
+                };
+                readonly fillStyle: {
+                    readonly type: "string";
+                    readonly enum: readonly ["solid", "hachure", "cross-hatch"];
+                    readonly description: "Fill style (default \"solid\")";
+                };
+                readonly strokeColor: {
+                    readonly type: "string";
+                    readonly description: "Stroke/border color as hex (default \"transparent\")";
+                };
+                readonly strokeWidth: {
+                    readonly type: "number";
+                    readonly description: "Stroke width in pixels (default 0)";
+                };
+                readonly opacity: {
+                    readonly type: "number";
+                    readonly description: "Opacity 0-100 (default 100)";
+                };
+            };
+            readonly required: readonly ["frameId", "x", "y", "width", "height", "backgroundColor"];
+            readonly additionalProperties: false;
+        };
+    };
+}, {
+    readonly type: "function";
+    readonly function: {
+        readonly name: "add_text";
+        readonly description: "Add a text element inside a frame. Use for headlines, subheads, body copy, CTAs etc.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly frameId: {
+                    readonly type: "string";
+                    readonly description: "ID of the parent frame";
+                };
+                readonly x: {
+                    readonly type: "number";
+                    readonly description: "X position (canvas coordinates)";
+                };
+                readonly y: {
+                    readonly type: "number";
+                    readonly description: "Y position (canvas coordinates)";
+                };
+                readonly text: {
+                    readonly type: "string";
+                    readonly description: "The text content";
+                };
+                readonly fontSize: {
+                    readonly type: "number";
+                    readonly description: "Font size in pixels (default 20)";
+                };
+                readonly fontFamily: {
+                    readonly type: "number";
+                    readonly enum: readonly [1, 2, 3, 4, 5];
+                    readonly description: "Font family: 1=Excalifont(hand), 2=Nunito(sans), 3=Comic Shanns(code), 4=Liberation Sans(clean sans), 5=Cascadia(code). Default 2.";
+                };
+                readonly strokeColor: {
+                    readonly type: "string";
+                    readonly description: "Text color as hex string (default \"#000000\")";
+                };
+                readonly textAlign: {
+                    readonly type: "string";
+                    readonly enum: readonly ["left", "center", "right"];
+                    readonly description: "Horizontal alignment (default left)";
+                };
+                readonly width: {
+                    readonly type: "number";
+                    readonly description: "Optional fixed width for text wrapping";
+                };
+            };
+            readonly required: readonly ["frameId", "x", "y", "text"];
+            readonly additionalProperties: false;
+        };
+    };
+}, {
+    readonly type: "function";
+    readonly function: {
+        readonly name: "generate_image";
+        readonly description: "Generate an image using AI (Gemini) from a text prompt and place it inside a frame. Use for hero images, product shots, backgrounds, illustrations etc.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly frameId: {
+                    readonly type: "string";
+                    readonly description: "ID of the parent frame to insert the image into";
+                };
+                readonly prompt: {
+                    readonly type: "string";
+                    readonly description: "Detailed image generation prompt describing what to create";
+                };
+                readonly x: {
+                    readonly type: "number";
+                    readonly description: "X position for the image (canvas coordinates)";
+                };
+                readonly y: {
+                    readonly type: "number";
+                    readonly description: "Y position for the image (canvas coordinates)";
+                };
+                readonly width: {
+                    readonly type: "number";
+                    readonly description: "Image width in pixels";
+                };
+                readonly height: {
+                    readonly type: "number";
+                    readonly description: "Image height in pixels";
+                };
+            };
+            readonly required: readonly ["frameId", "prompt", "x", "y", "width", "height"];
+            readonly additionalProperties: false;
+        };
+    };
+}, {
+    readonly type: "function";
+    readonly function: {
+        readonly name: "update_element";
+        readonly description: "Update properties of an existing element (move, resize, recolor, change text, etc.)";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly elementId: {
+                    readonly type: "string";
+                    readonly description: "ID of the element to update";
+                };
+                readonly x: {
+                    readonly type: "number";
+                    readonly description: "New X position";
+                };
+                readonly y: {
+                    readonly type: "number";
+                    readonly description: "New Y position";
+                };
+                readonly width: {
+                    readonly type: "number";
+                    readonly description: "New width";
+                };
+                readonly height: {
+                    readonly type: "number";
+                    readonly description: "New height";
+                };
+                readonly backgroundColor: {
+                    readonly type: "string";
+                    readonly description: "New background/fill color";
+                };
+                readonly strokeColor: {
+                    readonly type: "string";
+                    readonly description: "New stroke/text color";
+                };
+                readonly opacity: {
+                    readonly type: "number";
+                    readonly description: "New opacity 0-100";
+                };
+                readonly fontSize: {
+                    readonly type: "number";
+                    readonly description: "New font size (text elements only)";
+                };
+                readonly text: {
+                    readonly type: "string";
+                    readonly description: "New text content (text elements only)";
+                };
+                readonly fillStyle: {
+                    readonly type: "string";
+                    readonly enum: readonly ["solid", "hachure", "cross-hatch"];
+                    readonly description: "New fill style";
+                };
+            };
+            readonly required: readonly ["elementId"];
+            readonly additionalProperties: false;
+        };
+    };
+}, {
+    readonly type: "function";
+    readonly function: {
+        readonly name: "delete_element";
+        readonly description: "Delete an element from the canvas";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly elementId: {
+                    readonly type: "string";
+                    readonly description: "ID of the element to delete";
+                };
+            };
+            readonly required: readonly ["elementId"];
+            readonly additionalProperties: false;
+        };
+    };
+}, {
+    readonly type: "function";
+    readonly function: {
+        readonly name: "get_frame_elements";
+        readonly description: "Get all child elements inside a frame. Returns their IDs, types, positions, sizes, colors, and text content. Use this to understand the current layout before making changes.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly frameId: {
+                    readonly type: "string";
+                    readonly description: "ID of the frame to inspect";
+                };
+            };
+            readonly required: readonly ["frameId"];
+            readonly additionalProperties: false;
+        };
+    };
+}];
+/**
+ * Returns the canvas tool definitions for the agent, optionally extending
+ * the `add_text` fontFamily enum with custom font IDs.
+ *
+ * Pass the family IDs registered via `Fonts.registerCustomFont` so the
+ * agent knows it can use those numbers in `add_text` calls.
+ */
+export declare function getCanvasTools(extraFontIds?: number[]): typeof CANVAS_TOOLS;
+export declare const BANNER_TOOLS: readonly [{
+    readonly type: "function";
+    readonly function: {
+        readonly name: "create_frame";
+        readonly description: "Create a new frame on the canvas to act as the root container for your banner. Default size is 512x512. ALWAYS call this FIRST before generating images or HTML.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly width: {
+                    readonly type: "number";
+                    readonly description: "Frame width in pixels (default 512)";
+                };
+                readonly height: {
+                    readonly type: "number";
+                    readonly description: "Frame height in pixels (default 512)";
+                };
+                readonly name: {
+                    readonly type: "string";
+                    readonly description: "Optional display name for the frame";
+                };
+            };
+            readonly required: readonly [];
+            readonly additionalProperties: false;
+        };
+    };
+}, {
+    readonly type: "function";
+    readonly function: {
+        readonly name: "generate_image";
+        readonly description: "Generate an image using AI (Gemini) and place it onto the canvas. Always call this for any photo or image content — even when the user has attached a reference image. The attached image is passed to Gemini as visual reference; Gemini generates the final output. Use referenceImageIndex to tell Gemini which user attachment to reference. IMPORTANT: your prompt must describe a purely visual scene — NO text, NO typography, NO words, NO captions, NO watermarks. All copy is handled by the HTML layer. A 'no text' safety suffix will be auto-appended, but you must also describe composition clearly (e.g. which side should be left open/empty for the HTML text).";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly frameId: {
+                    readonly type: "string";
+                    readonly description: "ID of the parent frame to insert the image into";
+                };
+                readonly prompt: {
+                    readonly type: "string";
+                    readonly description: "Detailed generation prompt. When using a reference image, describe what you want Gemini to produce — e.g. 'use this building as the subject, wide cinematic crop with open sky on the left for text overlay'.";
+                };
+                readonly x: {
+                    readonly type: "number";
+                    readonly description: "X position relative to the frame's top-left corner";
+                };
+                readonly y: {
+                    readonly type: "number";
+                    readonly description: "Y position relative to the frame's top-left corner";
+                };
+                readonly width: {
+                    readonly type: "number";
+                    readonly description: "Image width in pixels";
+                };
+                readonly height: {
+                    readonly type: "number";
+                    readonly description: "Image height in pixels";
+                };
+                readonly referenceImageIndex: {
+                    readonly type: "number";
+                    readonly description: "0-based index of the user's attached image to pass to Gemini as reference. Always use 0 when the user has attached an image.";
+                };
+            };
+            readonly required: readonly ["frameId", "prompt", "x", "y", "width", "height"];
+            readonly additionalProperties: false;
+        };
+    };
+}, {
+    readonly type: "function";
+    readonly function: {
+        readonly name: "generate_html_banner";
+        readonly description: "Place HTML/CSS text and shape elements into an EXISTING frame on the canvas. Always call create_frame first to get a frameId, then generate_image, then call this with that frameId. frameId is required — this tool does NOT create frames.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly html: {
+                    readonly type: "string";
+                    readonly description: "Complete self-contained HTML with inline <style>. All layer elements must use position:absolute with explicit left/top/width/height in px. Root div must have class='canvas'.";
+                };
+                readonly frameId: {
+                    readonly type: "string";
+                    readonly description: "Required. The ID of the frame created by create_frame. Adds HTML elements into this existing frame, preserving existing children like images.";
+                };
+            };
+            readonly required: readonly ["html", "frameId"];
+            readonly additionalProperties: false;
+        };
+    };
+}, {
+    readonly type: "function";
+    readonly function: {
+        readonly name: "get_frame_elements";
+        readonly description: "Get all child elements inside a frame. Use when editing an existing banner to understand its current state before replacing.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly frameId: {
+                    readonly type: "string";
+                    readonly description: "ID of the frame to inspect";
+                };
+            };
+            readonly required: readonly ["frameId"];
+            readonly additionalProperties: false;
+        };
+    };
+}, {
+    readonly type: "function";
+    readonly function: {
+        readonly name: "update_element";
+        readonly description: "Update properties of an existing element. Use for minor targeted fixes after the banner is placed.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly elementId: {
+                    readonly type: "string";
+                };
+                readonly x: {
+                    readonly type: "number";
+                };
+                readonly y: {
+                    readonly type: "number";
+                };
+                readonly width: {
+                    readonly type: "number";
+                };
+                readonly height: {
+                    readonly type: "number";
+                };
+                readonly backgroundColor: {
+                    readonly type: "string";
+                };
+                readonly strokeColor: {
+                    readonly type: "string";
+                };
+                readonly opacity: {
+                    readonly type: "number";
+                };
+                readonly fontSize: {
+                    readonly type: "number";
+                };
+                readonly text: {
+                    readonly type: "string";
+                };
+                readonly fillStyle: {
+                    readonly type: "string";
+                    readonly enum: readonly ["solid", "hachure", "cross-hatch"];
+                };
+            };
+            readonly required: readonly ["elementId"];
+            readonly additionalProperties: false;
+        };
+    };
+}, {
+    readonly type: "function";
+    readonly function: {
+        readonly name: "delete_element";
+        readonly description: "Delete an element from the canvas.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly elementId: {
+                    readonly type: "string";
+                    readonly description: "ID of the element to delete";
+                };
+            };
+            readonly required: readonly ["elementId"];
+            readonly additionalProperties: false;
+        };
+    };
+}, {
+    readonly type: "function";
+    readonly function: {
+        readonly name: "search_brand_assets";
+        readonly description: "Search the brand asset bank for existing product shots, logos, and lifestyle images. ALWAYS call this before generate_image to check if a brand asset already exists.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly query: {
+                    readonly type: "string";
+                    readonly description: "Search query — name or tag keywords";
+                };
+                readonly type: {
+                    readonly type: "string";
+                    readonly enum: readonly ["product", "logo", "lifestyle", "auxiliary"];
+                    readonly description: "Optional filter by asset type";
+                };
+            };
+            readonly required: readonly ["query"];
+            readonly additionalProperties: false;
+        };
+    };
+}, {
+    readonly type: "function";
+    readonly function: {
+        readonly name: "list_brand_templates";
+        readonly description: "List available brand templates by keyword search across template names, campaign tags, and labels.\n\nMANDATORY SEARCH PROTOCOL — follow exactly, no shortcuts:\n\nATTEMPT 1: Generate TWO sets of 10 keywords each from the user's request:\n  - Set A (campaign tag variations): 10 synonyms/abbreviations/phrasings of the campaign topic (e.g. for \"noida datacenter\": [\"datacenter\", \"data center\", \"dc\", \"noida dc\", \"noida datacenter\", \"data centre\", \"server farm\", \"cloud infra\", \"hyperscale\", \"colocation\"])\n  - Set B (template name variations): 10 different name keywords the template might have (e.g. [\"noida\", \"datacenter campaign\", \"new datacenter\", \"dc launch\", \"infrastructure\", \"cloud\", \"enterprise\", \"b2b\", \"tech\", \"facility\"])\n  Merge all 20 into the keywords array. Call list_brand_templates with all 20.\n\nIF templates returned is empty → ATTEMPT 2 (MANDATORY — do NOT skip):\n  Generate a completely DIFFERENT set of 20 keywords — do not reuse any from attempt 1. Think laterally: different synonyms, related industry terms, the city name, brand-adjacent words, seasonal terms. Call list_brand_templates again with the new 20.\n\nONLY after both attempts return empty → tell the user no matching template was found.\n\nIf no search context exists, call with an empty keywords array to list all templates.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly keywords: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "Up to 20 keyword variations to search across template names, campaign tags, and labels. All are OR-matched case-insensitively. Generate 10 tag synonyms + 10 name variations from the user's request.";
+                };
+            };
+            readonly required: readonly [];
+            readonly additionalProperties: false;
+        };
+    };
+}, {
+    readonly type: "function";
+    readonly function: {
+        readonly name: "get_template_variant";
+        readonly description: "Fetch the full canvas JSON for a specific template by its ID.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly variantId: {
+                    readonly type: "string";
+                    readonly description: "The template ID to fetch";
+                };
+            };
+            readonly required: readonly ["variantId"];
+            readonly additionalProperties: false;
+        };
+    };
+}, {
+    readonly type: "function";
+    readonly function: {
+        readonly name: "load_template_into_frame";
+        readonly description: "Load a template into an existing frame, replacing its contents with the template elements.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly frameId: {
+                    readonly type: "string";
+                    readonly description: "The frame ID to load the template into";
+                };
+                readonly variantId: {
+                    readonly type: "string";
+                    readonly description: "The template ID to load (from list_brand_templates)";
+                };
+            };
+            readonly required: readonly ["frameId", "variantId"];
+            readonly additionalProperties: false;
+        };
+    };
+}, {
+    readonly type: "function";
+    readonly function: {
+        readonly name: "fill_template_slots";
+        readonly description: "Fill the slot elements inside a frame with content. Use this after load_template_into_frame to populate slots with actual content.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly frameId: {
+                    readonly type: "string";
+                    readonly description: "The frame ID containing slot elements";
+                };
+                readonly headline: {
+                    readonly type: "string";
+                    readonly description: "Text for the headline slot";
+                };
+                readonly subhead: {
+                    readonly type: "string";
+                    readonly description: "Text for the subhead slot";
+                };
+                readonly cta: {
+                    readonly type: "string";
+                    readonly description: "Text for the CTA slot";
+                };
+                readonly signoff: {
+                    readonly type: "string";
+                    readonly description: "Text for the signoff slot";
+                };
+                readonly product_image_url: {
+                    readonly type: "string";
+                    readonly description: "URL for the product image slot (from search_brand_assets blobUrl, or a generated image data URL)";
+                };
+                readonly product_image_asset_id: {
+                    readonly type: "string";
+                    readonly description: "Asset ID for the product image (from search_brand_assets [id:...] field). Required when using a brand asset so the image can be swapped later.";
+                };
+                readonly logo_url: {
+                    readonly type: "string";
+                    readonly description: "URL for the logo slot (from search_brand_assets blobUrl)";
+                };
+                readonly logo_asset_id: {
+                    readonly type: "string";
+                    readonly description: "Asset ID for the logo (from search_brand_assets [id:...] field). Required when using a brand asset.";
+                };
+                readonly auxiliary_image_url: {
+                    readonly type: "string";
+                    readonly description: "URL for the auxiliary image slot";
+                };
+                readonly auxiliary_image_asset_id: {
+                    readonly type: "string";
+                    readonly description: "Asset ID for the auxiliary image (from search_brand_assets [id:...] field). Required when using a brand asset.";
+                };
+                readonly background_color: {
+                    readonly type: "string";
+                    readonly description: "Hex color (e.g. #000000) for the background slot";
+                };
+            };
+            readonly required: readonly ["frameId"];
+            readonly additionalProperties: false;
+        };
+    };
+}, {
+    readonly type: "function";
+    readonly function: {
+        readonly name: "finalize_ad";
+        readonly description: "Call this when ALL elements are placed on the canvas — brand assets, generated images, and the HTML text overlay. Captures a screenshot of the complete frame for review. Do NOT call this before all assets are in place.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly frameId: {
+                    readonly type: "string";
+                    readonly description: "ID of the frame to capture for review";
+                };
+            };
+            readonly required: readonly ["frameId"];
+            readonly additionalProperties: false;
+        };
+    };
+}];
+export declare function serializeElements(elements: readonly ExcalidrawElement[]): Record<string, unknown>[];
+export type FrameInfo = {
+    id: string;
+    name: string;
+    width: number;
+    height: number;
+    childCount: number;
+};
+export declare function listFrames(api: ExcalidrawImperativeAPI): FrameInfo[];
+export declare function captureFrameScreenshot(api: ExcalidrawImperativeAPI, frameId: string): Promise<string | null>;
+export declare function getFrameContext(api: ExcalidrawImperativeAPI, frameId: string): {
+    serialized: string;
+    frameInfo: FrameInfo;
+} | null;
+export type ToolExecutionContext = {
+    excalidrawAPI: ExcalidrawImperativeAPI;
+    geminiApiKey: string;
+    signal?: AbortSignal;
+    /** Override Gemini model ID for the agent's generate_image tool. */
+    agentImageModel?: string;
+    /**
+     * Maps lowercase brand font-family names to their registered Excalidraw
+     * fontFamilyIds. Built from BrandContext.typography in runAgentLoop and
+     * used by the HTML parser to preserve brand fonts in text elements.
+     */
+    customFontMap?: Record<string, number>;
+    /**
+     * Brand headline font file name (e.g. "Avenir-Heavy.otf"). Sourced from brand DNA.
+     * Passed to generate_image as style context so the AI knows the brand typography.
+     */
+    brandHeadlineFontName?: string;
+    /** Brand body font file name. Sourced from brand DNA. */
+    brandBodyFontName?: string;
+    /**
+     * Excalidraw fontFamilyId for the brand headline font.
+     * When set, ALL text elements (add_text, fill_template_slots headline slots)
+     * use this font. Falls back to brandBodyFontId, then Excalidraw default.
+     */
+    brandHeadlineFontId?: number;
+    /**
+     * Excalidraw fontFamilyId for the brand body font.
+     * When set, ALL text elements use this font — never a built-in fallback
+     * unless the font failed to load.
+     */
+    brandBodyFontId?: number;
+    /**
+     * Image file attachments the user uploaded in the current chat turn.
+     * Indexed 0-based in the order they were attached.
+     * Used by place_attachment (direct placement) and generate_image (as Gemini reference).
+     */
+    fileAttachments?: Array<{
+        name: string;
+        dataUrl?: string;
+    }>;
+    onSearchBrandAssets?: (query: string, type?: string) => Promise<Array<{
+        id: string;
+        name: string;
+        tags: string[];
+        assetType: string;
+        blobUrl: string;
+    }>>;
+    onListBrandTemplates?: (keywords?: string[]) => Promise<Array<{
+        id: string;
+        name: string;
+        campaignTag?: string;
+        label?: string;
+        width?: number;
+        height?: number;
+        thumbnailBlobUrl?: string;
+    }>>;
+    onGetTemplateVariant?: (variantId: string) => Promise<{
+        canvasJson: string;
+    }>;
+    /**
+     * Internal cache: populated by execGetTemplateVariant so that
+     * execLoadTemplateIntoFrame can reuse the already-fetched JSON without a
+     * second round-trip. Avoids the "double fetch → silent {} fallback → crash"
+     * failure mode for private Vercel Blob URLs.
+     */
+    _templateJsonCache?: Map<string, string>;
+};
+export type ToolResult = {
+    success: boolean;
+    data?: Record<string, unknown>;
+    error?: string;
+    statusMessage: string;
+};
+export declare function executeCanvasTool(toolName: string, rawArgs: string, ctx: ToolExecutionContext): Promise<ToolResult>;