@muloka/figma-console-mcp 0.1.0

package/dist/cloudflare/core/annotation-tools.js

@@ -0,0 +1,230 @@
+/**
+ * Figma Annotations MCP Tools
+ * Tools for reading, writing, and managing design annotations on Figma nodes.
+ * Annotations are a Plugin API feature — requires Desktop Bridge plugin connection.
+ *
+ * Annotations are distinct from comments: they are node-level design specs that
+ * can pin specific properties (fills, width, typography, etc.) and support
+ * markdown-formatted labels. Designers use them to communicate animation timings,
+ * accessibility requirements, interaction specs, and other implementation details
+ * that don't fit in the description field.
+ */
+import { z } from "zod";
+import { createChildLogger } from "./logger.js";
+const logger = createChildLogger({ component: "annotation-tools" });
+// Valid AnnotationPropertyType values from the Figma Plugin API
+// Sourced from @figma/plugin-typings — keep in sync with AnnotationPropertyType union
+// Reference: https://developers.figma.com/docs/plugins/api/AnnotationProperty
+const ANNOTATION_PROPERTY_TYPES = [
+    "width",
+    "height",
+    "maxWidth",
+    "minWidth",
+    "maxHeight",
+    "minHeight",
+    "fills",
+    "strokes",
+    "effects",
+    "strokeWeight",
+    "cornerRadius",
+    "textStyleId",
+    "textAlignHorizontal",
+    "fontFamily",
+    "fontStyle",
+    "fontSize",
+    "fontWeight",
+    "lineHeight",
+    "letterSpacing",
+    "itemSpacing",
+    "padding",
+    "layoutMode",
+    "alignItems",
+    "opacity",
+    "mainComponent",
+    "gridRowGap",
+    "gridColumnGap",
+    "gridRowCount",
+    "gridColumnCount",
+    "gridRowAnchorIndex",
+    "gridColumnAnchorIndex",
+    "gridRowSpan",
+    "gridColumnSpan",
+];
+// Zod schema for annotation property
+const annotationPropertySchema = z.object({
+    type: z
+        .enum(ANNOTATION_PROPERTY_TYPES)
+        .describe("Design property to pin (e.g., 'fills', 'width', 'fontSize')"),
+});
+// Zod schema for a single annotation
+const annotationSchema = z.object({
+    label: z
+        .string()
+        .optional()
+        .describe("Plain text annotation label"),
+    labelMarkdown: z
+        .string()
+        .optional()
+        .describe("Rich text annotation label with markdown formatting. Supports bold, italic, links, lists, code, and headers."),
+    properties: z
+        .array(annotationPropertySchema)
+        .optional()
+        .describe("Design properties to pin to this annotation (e.g., fills, width, fontSize)"),
+    categoryId: z
+        .string()
+        .optional()
+        .describe("Annotation category ID. Use figma_get_annotation_categories to list available categories."),
+});
+// ============================================================================
+// Tool Registration
+// ============================================================================
+export function registerAnnotationTools(server, getDesktopConnector) {
+    // -----------------------------------------------------------------------
+    // Tool: figma_get_annotations
+    // -----------------------------------------------------------------------
+    server.tool("figma_get_annotations", "Read annotations from a Figma node. Annotations are designer-authored specs attached to nodes — they can include notes (plain text or markdown), pinned design properties (fills, width, fontSize, etc.), and category labels. Use this to discover animation timings, interaction specs, accessibility requirements, and other implementation details that designers annotate directly on the design. Set include_children=true to get annotations from child nodes too (useful for full component documentation). Requires Desktop Bridge plugin.", {
+        nodeId: z
+            .string()
+            .describe("Node ID to read annotations from (e.g., '695:313')"),
+        include_children: z.preprocess((v) => (typeof v === "string" ? v === "true" : v), z.boolean().optional().default(false)).describe("Also read annotations from child nodes. Useful for getting all annotations within a component tree."),
+        depth: z.preprocess((v) => (typeof v === "string" ? Number(v) : v), z.number().optional().default(1)).describe("How many levels deep to traverse when include_children is true (default: 1, max recommended: 5)"),
+    }, async ({ nodeId, include_children = false, depth = 1 }) => {
+        try {
+            logger.info({ nodeId, include_children, depth }, "Getting annotations");
+            const connector = await getDesktopConnector();
+            const result = await connector.getAnnotations(nodeId, include_children, Math.min(depth, 10));
+            if (!result || (result.success === false)) {
+                throw new Error(result?.error || "Failed to get annotations");
+            }
+            // The result may come back as { success, data } (WebSocket) or directly as data
+            const data = result.data || result;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(data),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error({ error }, "Failed to get annotations");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "get_annotations_failed",
+                            message: `Cannot get annotations. ${message}`,
+                            hint: "Annotations require the Desktop Bridge plugin to be running in Figma.",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // -----------------------------------------------------------------------
+    // Tool: figma_set_annotations
+    // -----------------------------------------------------------------------
+    server.tool("figma_set_annotations", "Write or clear annotations on a Figma node. Annotations communicate design specs to developers — use them to document animation timings, easing curves, interaction behaviors, accessibility requirements, and implementation notes. Supports plain text labels, rich markdown labels, pinned design properties, and annotation categories. Pass an empty array to clear all annotations. Use mode='append' to add to existing annotations, or mode='replace' (default) to overwrite. Requires Desktop Bridge plugin. This operation is undoable in Figma (Cmd+Z).", {
+        nodeId: z
+            .string()
+            .describe("Node ID to write annotations to (e.g., '695:313')"),
+        annotations: z.preprocess((v) => {
+            if (typeof v === "string") {
+                try {
+                    return JSON.parse(v);
+                }
+                catch {
+                    return v;
+                }
+            }
+            return v;
+        }, z.array(annotationSchema)).describe("Array of annotations to set. Each annotation can have a label (plain or markdown), pinned properties, and a category. Pass an empty array [] to clear all annotations."),
+        mode: z
+            .enum(["replace", "append"])
+            .optional()
+            .default("replace")
+            .describe("'replace' (default) overwrites all existing annotations. 'append' adds new annotations while keeping existing ones."),
+    }, async ({ nodeId, annotations, mode = "replace" }) => {
+        try {
+            logger.info({ nodeId, count: annotations.length, mode }, "Setting annotations");
+            const connector = await getDesktopConnector();
+            const result = await connector.setAnnotations(nodeId, annotations, mode);
+            if (!result || (result.success === false)) {
+                throw new Error(result?.error || "Failed to set annotations");
+            }
+            const data = result.data || result;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            ...data,
+                            note: "Annotations set successfully. This operation is undoable in Figma (Cmd+Z).",
+                        }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error({ error }, "Failed to set annotations");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "set_annotations_failed",
+                            message: `Cannot set annotations. ${message}`,
+                            hint: "Annotations require the Desktop Bridge plugin to be running in Figma.",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // -----------------------------------------------------------------------
+    // Tool: figma_get_annotation_categories
+    // -----------------------------------------------------------------------
+    server.tool("figma_get_annotation_categories", "List available annotation categories in the current Figma file. Categories group annotations by purpose (e.g., interactions, accessibility, development notes). Use the returned category IDs when creating annotations with figma_set_annotations. Requires Desktop Bridge plugin.", {}, async () => {
+        try {
+            logger.info("Getting annotation categories");
+            const connector = await getDesktopConnector();
+            const result = await connector.getAnnotationCategories();
+            if (!result || (result.success === false)) {
+                throw new Error(result?.error || "Failed to get annotation categories");
+            }
+            const data = result.data || result;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(data),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error({ error }, "Failed to get annotation categories");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "get_annotation_categories_failed",
+                            message: `Cannot get annotation categories. ${message}`,
+                            hint: "Annotation categories require the Desktop Bridge plugin to be running in Figma.",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/cloudflare/core/cloud-websocket-connector.js

@@ -0,0 +1,419 @@
+/**
+ * Cloud WebSocket Connector
+ *
+ * Implements IFigmaConnector by routing commands through the PluginRelayDO
+ * Durable Object. Each method maps to a command sent via fetch() RPC to
+ * the relay, which forwards it to the Figma Desktop Bridge plugin over
+ * WebSocket.
+ *
+ * Structurally mirrors WebSocketConnector — same methods, different transport.
+ */
+export class CloudWebSocketConnector {
+    constructor(relayStub) {
+        this.relayStub = relayStub;
+    }
+    async initialize() {
+        const res = await this.relayStub.fetch('https://relay/relay/status');
+        const status = await res.json();
+        if (!status.connected) {
+            throw new Error('No plugin connected to cloud relay. User must pair the Desktop Bridge plugin first (use figma_pair_plugin tool).');
+        }
+    }
+    getTransportType() {
+        return 'websocket';
+    }
+    // ============================================================================
+    // Core execution
+    // ============================================================================
+    async executeInPluginContext(code) {
+        return this.sendCommand('EXECUTE_CODE', { code, timeout: 5000 }, 7000);
+    }
+    async getVariablesFromPluginUI(fileKey) {
+        return this.sendCommand('GET_VARIABLES_DATA', {}, 10000);
+    }
+    async getVariables(fileKey) {
+        // IMPORTANT: bare try/catch with top-level `return`, NO inner IIFE.
+        // See issue #68 + the matching note in websocket-connector.ts. The plugin
+        // (code.js) wraps every EXECUTE_CODE payload in its own async IIFE; nesting
+        // another swallows the inner return and silently drops the variables.
+        const code = `
+      try {
+        if (typeof figma === 'undefined') {
+          throw new Error('Figma API not available in this context');
+        }
+        const variables = await figma.variables.getLocalVariablesAsync();
+        const collections = await figma.variables.getLocalVariableCollectionsAsync();
+        return {
+          success: true,
+          timestamp: Date.now(),
+          fileMetadata: { fileName: figma.root.name, fileKey: figma.fileKey || null },
+          variables: variables.map(function(v) { return { id: v.id, name: v.name, key: v.key, resolvedType: v.resolvedType, valuesByMode: v.valuesByMode, variableCollectionId: v.variableCollectionId, scopes: v.scopes, description: v.description, hiddenFromPublishing: v.hiddenFromPublishing }; }),
+          variableCollections: collections.map(function(c) { return { id: c.id, name: c.name, key: c.key, modes: c.modes, defaultModeId: c.defaultModeId, variableIds: c.variableIds }; })
+        };
+      } catch (error) {
+        return { success: false, error: error.message };
+      }
+    `;
+        return this.sendCommand('EXECUTE_CODE', { code, timeout: 30000 }, 32000);
+    }
+    async executeCodeViaUI(code, timeoutMs = 5000) {
+        return this.sendCommand('EXECUTE_CODE', { code, timeout: timeoutMs }, timeoutMs + 2000);
+    }
+    // ============================================================================
+    // Variable operations
+    // ============================================================================
+    async updateVariable(variableId, modeId, value) {
+        return this.sendCommand('UPDATE_VARIABLE', { variableId, modeId, value });
+    }
+    async createVariable(name, collectionId, resolvedType, options) {
+        const params = { name, collectionId, resolvedType };
+        if (options) {
+            if (options.valuesByMode)
+                params.valuesByMode = options.valuesByMode;
+            if (options.description)
+                params.description = options.description;
+            if (options.scopes)
+                params.scopes = options.scopes;
+        }
+        return this.sendCommand('CREATE_VARIABLE', params);
+    }
+    async deleteVariable(variableId) {
+        return this.sendCommand('DELETE_VARIABLE', { variableId });
+    }
+    async refreshVariables() {
+        return this.sendCommand('REFRESH_VARIABLES', {}, 300000);
+    }
+    async renameVariable(variableId, newName) {
+        const result = await this.sendCommand('RENAME_VARIABLE', { variableId, newName });
+        if (!result.oldName && result.variable?.oldName)
+            result.oldName = result.variable.oldName;
+        return result;
+    }
+    async setVariableDescription(variableId, description) {
+        return this.sendCommand('SET_VARIABLE_DESCRIPTION', { variableId, description });
+    }
+    // ============================================================================
+    // Mode operations
+    // ============================================================================
+    async addMode(collectionId, modeName) {
+        return this.sendCommand('ADD_MODE', { collectionId, modeName });
+    }
+    async renameMode(collectionId, modeId, newName) {
+        const result = await this.sendCommand('RENAME_MODE', { collectionId, modeId, newName });
+        if (!result.oldName && result.collection?.oldName)
+            result.oldName = result.collection.oldName;
+        return result;
+    }
+    // ============================================================================
+    // Collection operations
+    // ============================================================================
+    async createVariableCollection(name, options) {
+        const params = { name };
+        if (options) {
+            if (options.initialModeName)
+                params.initialModeName = options.initialModeName;
+            if (options.additionalModes)
+                params.additionalModes = options.additionalModes;
+        }
+        return this.sendCommand('CREATE_VARIABLE_COLLECTION', params);
+    }
+    async deleteVariableCollection(collectionId) {
+        return this.sendCommand('DELETE_VARIABLE_COLLECTION', { collectionId });
+    }
+    // ============================================================================
+    // Component operations
+    // ============================================================================
+    async getComponentFromPluginUI(nodeId) {
+        return this.sendCommand('GET_COMPONENT', { nodeId }, 10000);
+    }
+    async getLocalComponents() {
+        return this.sendCommand('GET_LOCAL_COMPONENTS', {}, 300000);
+    }
+    async setNodeDescription(nodeId, description, descriptionMarkdown) {
+        return this.sendCommand('SET_NODE_DESCRIPTION', { nodeId, description, descriptionMarkdown });
+    }
+    // ============================================================================
+    // Annotation operations
+    // ============================================================================
+    async getAnnotations(nodeId, includeChildren, depth) {
+        return this.sendCommand('GET_ANNOTATIONS', { nodeId, includeChildren, depth }, 10000);
+    }
+    async setAnnotations(nodeId, annotations, mode) {
+        return this.sendCommand('SET_ANNOTATIONS', { nodeId, annotations, mode: mode || 'replace' });
+    }
+    async getAnnotationCategories() {
+        return this.sendCommand('GET_ANNOTATION_CATEGORIES', {}, 5000);
+    }
+    async deepGetComponent(nodeId, depth) {
+        return this.sendCommand('DEEP_GET_COMPONENT', { nodeId, depth: depth || 10 }, 30000);
+    }
+    async analyzeComponentSet(nodeId) {
+        return this.sendCommand('ANALYZE_COMPONENT_SET', { nodeId }, 30000);
+    }
+    async addComponentProperty(nodeId, propertyName, type, defaultValue, options) {
+        const params = { nodeId, propertyName, propertyType: type, defaultValue };
+        if (options?.preferredValues)
+            params.preferredValues = options.preferredValues;
+        if (options?.description)
+            params.description = options.description;
+        return this.sendCommand('ADD_COMPONENT_PROPERTY', params);
+    }
+    async editComponentProperty(nodeId, propertyName, newValue) {
+        return this.sendCommand('EDIT_COMPONENT_PROPERTY', { nodeId, propertyName, newValue });
+    }
+    async deleteComponentProperty(nodeId, propertyName) {
+        return this.sendCommand('DELETE_COMPONENT_PROPERTY', { nodeId, propertyName });
+    }
+    async instantiateComponent(componentKey, options) {
+        const params = { componentKey };
+        if (options) {
+            if (options.nodeId)
+                params.nodeId = options.nodeId;
+            if (options.position)
+                params.position = options.position;
+            if (options.size)
+                params.size = options.size;
+            if (options.overrides)
+                params.overrides = options.overrides;
+            if (options.variant)
+                params.variant = options.variant;
+            if (options.parentId)
+                params.parentId = options.parentId;
+        }
+        return this.sendCommand('INSTANTIATE_COMPONENT', params);
+    }
+    async createComponentSet(params) {
+        // Timeout scales with variant count — the plugin builds all variants in
+        // one uncancellable pass, so a fixed 30s ceiling on big matrices reports
+        // failure while the set still gets created (retry → duplicates).
+        // Mirrors componentSetTimeoutMs in websocket-connector.ts (not imported:
+        // that module pulls the Node 'ws' stack into the Workers bundle).
+        let variantCount = 1;
+        if (params.componentIds?.length) {
+            variantCount = params.componentIds.length;
+        }
+        else if (params.properties) {
+            for (const values of Object.values(params.properties)) {
+                variantCount *= Math.max(1, values?.length ?? 1);
+            }
+        }
+        const timeout = Math.min(120000, Math.max(30000, variantCount * 1200)) + 5000;
+        return this.sendCommand('CREATE_COMPONENT_SET', params, timeout);
+    }
+    // ============================================================================
+    // Slot operations
+    // ============================================================================
+    async createSlot(nodeId, options) {
+        return this.sendCommand('CREATE_SLOT', { nodeId, ...options });
+    }
+    async getSlots(nodeId) {
+        return this.sendCommand('GET_SLOTS', { nodeId });
+    }
+    async appendToSlot(params) {
+        return this.sendCommand('APPEND_TO_SLOT', params);
+    }
+    async resetSlot(params) {
+        return this.sendCommand('RESET_SLOT', params);
+    }
+    // ============================================================================
+    // Node manipulation
+    // ============================================================================
+    async resizeNode(nodeId, width, height, withConstraints = true) {
+        return this.sendCommand('RESIZE_NODE', { nodeId, width, height, withConstraints });
+    }
+    async moveNode(nodeId, x, y) {
+        return this.sendCommand('MOVE_NODE', { nodeId, x, y });
+    }
+    async setNodeFills(nodeId, fills) {
+        return this.sendCommand('SET_NODE_FILLS', { nodeId, fills });
+    }
+    async setNodeStrokes(nodeId, strokes, strokeWeight) {
+        const params = { nodeId, strokes };
+        if (strokeWeight !== undefined)
+            params.strokeWeight = strokeWeight;
+        return this.sendCommand('SET_NODE_STROKES', params);
+    }
+    async setNodeOpacity(nodeId, opacity) {
+        return this.sendCommand('SET_NODE_OPACITY', { nodeId, opacity });
+    }
+    async setNodeCornerRadius(nodeId, radius) {
+        return this.sendCommand('SET_NODE_CORNER_RADIUS', { nodeId, radius });
+    }
+    async cloneNode(nodeId) {
+        return this.sendCommand('CLONE_NODE', { nodeId });
+    }
+    async deleteNode(nodeId) {
+        return this.sendCommand('DELETE_NODE', { nodeId });
+    }
+    async renameNode(nodeId, newName) {
+        return this.sendCommand('RENAME_NODE', { nodeId, newName });
+    }
+    async setTextContent(nodeId, characters, options) {
+        const params = { nodeId, text: characters };
+        if (options) {
+            if (options.fontSize)
+                params.fontSize = options.fontSize;
+            if (options.fontWeight)
+                params.fontWeight = options.fontWeight;
+            if (options.fontFamily)
+                params.fontFamily = options.fontFamily;
+            if (options.fontStyle)
+                params.fontStyle = options.fontStyle;
+        }
+        return this.sendCommand('SET_TEXT_CONTENT', params);
+    }
+    async createChildNode(parentId, nodeType, properties) {
+        return this.sendCommand('CREATE_CHILD_NODE', { parentId, nodeType, properties: properties || {} });
+    }
+    // ============================================================================
+    // Screenshot & instance properties
+    // ============================================================================
+    async captureScreenshot(nodeId, options) {
+        const params = { nodeId };
+        if (options?.format)
+            params.format = options.format;
+        if (options?.scale)
+            params.scale = options.scale;
+        return this.sendCommand('CAPTURE_SCREENSHOT', params, 30000);
+    }
+    async setInstanceProperties(nodeId, properties) {
+        return this.sendCommand('SET_INSTANCE_PROPERTIES', { nodeId, properties });
+    }
+    // ============================================================================
+    // Image fill
+    // ============================================================================
+    async setImageFill(nodeIds, imageData, scaleMode = 'FILL') {
+        return this.sendCommand('SET_IMAGE_FILL', { nodeIds, imageData, scaleMode }, 60000);
+    }
+    // ============================================================================
+    // Design lint
+    // ============================================================================
+    async lintDesign(nodeId, rules, maxDepth, maxFindings) {
+        const params = {};
+        if (nodeId)
+            params.nodeId = nodeId;
+        if (rules)
+            params.rules = rules;
+        if (maxDepth !== undefined)
+            params.maxDepth = maxDepth;
+        if (maxFindings !== undefined)
+            params.maxFindings = maxFindings;
+        return this.sendCommand('LINT_DESIGN', params, 120000);
+    }
+    // ============================================================================
+    // Component accessibility audit
+    // ============================================================================
+    async auditComponentAccessibility(nodeId, targetSize) {
+        const params = {};
+        if (nodeId)
+            params.nodeId = nodeId;
+        if (targetSize !== undefined)
+            params.targetSize = targetSize;
+        return this.sendCommand('AUDIT_COMPONENT_ACCESSIBILITY', params, 120000);
+    }
+    // ============================================================================
+    // FigJam operations
+    // ============================================================================
+    async createSticky(params) {
+        return this.sendCommand('CREATE_STICKY', params);
+    }
+    async createStickies(params) {
+        return this.sendCommand('CREATE_STICKIES', params, 30000);
+    }
+    async createConnector(params) {
+        return this.sendCommand('CREATE_CONNECTOR', params);
+    }
+    async createShapeWithText(params) {
+        return this.sendCommand('CREATE_SHAPE_WITH_TEXT', params);
+    }
+    async createSection(params) {
+        return this.sendCommand('CREATE_SECTION', params);
+    }
+    async createTable(params) {
+        return this.sendCommand('CREATE_TABLE', params, 30000);
+    }
+    async createCodeBlock(params) {
+        return this.sendCommand('CREATE_CODE_BLOCK', params);
+    }
+    async getBoardContents(params) {
+        return this.sendCommand('GET_BOARD_CONTENTS', params, 30000);
+    }
+    async getConnections() {
+        return this.sendCommand('GET_CONNECTIONS', {}, 15000);
+    }
+    // ============================================================================
+    // Slides operations
+    // ============================================================================
+    async listSlides() {
+        return this.sendCommand('LIST_SLIDES', {}, 10000);
+    }
+    async getSlideContent(params) {
+        return this.sendCommand('GET_SLIDE_CONTENT', params, 10000);
+    }
+    async createSlide(params) {
+        return this.sendCommand('CREATE_SLIDE', params, 10000);
+    }
+    async deleteSlide(params) {
+        return this.sendCommand('DELETE_SLIDE', params, 5000);
+    }
+    async duplicateSlide(params) {
+        return this.sendCommand('DUPLICATE_SLIDE', params, 5000);
+    }
+    async getSlideGrid() {
+        return this.sendCommand('GET_SLIDE_GRID', {}, 10000);
+    }
+    async reorderSlides(params) {
+        return this.sendCommand('REORDER_SLIDES', params, 15000);
+    }
+    async setSlideTransition(params) {
+        return this.sendCommand('SET_SLIDE_TRANSITION', params, 5000);
+    }
+    async getSlideTransition(params) {
+        return this.sendCommand('GET_SLIDE_TRANSITION', params, 5000);
+    }
+    async setSlidesViewMode(params) {
+        return this.sendCommand('SET_SLIDES_VIEW_MODE', params, 5000);
+    }
+    async getFocusedSlide() {
+        return this.sendCommand('GET_FOCUSED_SLIDE', {}, 5000);
+    }
+    async focusSlide(params) {
+        return this.sendCommand('FOCUS_SLIDE', params, 5000);
+    }
+    async skipSlide(params) {
+        return this.sendCommand('SKIP_SLIDE', params, 5000);
+    }
+    async addTextToSlide(params) {
+        return this.sendCommand('ADD_TEXT_TO_SLIDE', params, 10000);
+    }
+    async addShapeToSlide(params) {
+        return this.sendCommand('ADD_SHAPE_TO_SLIDE', params, 5000);
+    }
+    async setSlideBackground(params) {
+        return this.sendCommand('SET_SLIDE_BACKGROUND', params, 5000);
+    }
+    async getTextStyles() {
+        return this.sendCommand('GET_TEXT_STYLES', {}, 5000);
+    }
+    // ============================================================================
+    // Cache management (no-op for cloud relay)
+    // ============================================================================
+    clearFrameCache() {
+        // No frame cache in cloud relay mode
+    }
+    // ============================================================================
+    // Transport — fetch-based RPC to the relay DO
+    // ============================================================================
+    async sendCommand(method, params = {}, timeoutMs = 15000) {
+        const res = await this.relayStub.fetch('https://relay/relay/command', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ method, params, timeoutMs }),
+        });
+        const data = await res.json();
+        if (data.error) {
+            throw new Error(data.error);
+        }
+        return data.result;
+    }
+}