@genart-dev/mcp-server 0.2.0 → 0.3.0

package/dist/lib.js

@@ -1,6 +1,11 @@
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z as z2 } from "zod";
+import { createPluginRegistry } from "@genart-dev/core";
+import typographyPlugin from "@genart-dev/plugin-typography";
+import filtersPlugin from "@genart-dev/plugin-filters";
+import shapesPlugin from "@genart-dev/plugin-shapes";
+import layoutGuidesPlugin from "@genart-dev/plugin-layout-guides";
 
 // src/tools/workspace.ts
 import { readFile, writeFile, stat } from "fs/promises";
@@ -2675,6 +2680,330 @@ async function exportZip(sketch, input) {
   };
 }
 
+// src/tools/design.ts
+function requireSketchId(state, args) {
+  return args.sketchId ?? state.requireSelectedSketchId();
+}
+var BLEND_MODES = [
+  "normal",
+  "multiply",
+  "screen",
+  "overlay",
+  "darken",
+  "lighten",
+  "color-dodge",
+  "color-burn",
+  "hard-light",
+  "soft-light",
+  "difference",
+  "exclusion",
+  "hue",
+  "saturation",
+  "color",
+  "luminosity"
+];
+function generateLayerId() {
+  return `layer-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+async function designAddLayer(state, args) {
+  const sketchId = requireSketchId(state, args);
+  const loaded = state.requireSketch(sketchId);
+  const stack = state.getLayerStack(sketchId);
+  const registry4 = state.pluginRegistry;
+  const layerTypeDef = registry4?.resolveLayerType(args.type);
+  if (!layerTypeDef) {
+    throw new Error(
+      `Unknown layer type: '${args.type}'. Use design_list_layers types from registered plugins.`
+    );
+  }
+  const defaults = layerTypeDef.createDefault();
+  const id = generateLayerId();
+  const { width, height } = loaded.definition.canvas;
+  const layer = {
+    id,
+    type: args.type,
+    name: args.name ?? layerTypeDef.displayName,
+    visible: true,
+    locked: false,
+    opacity: args.opacity ?? 1,
+    blendMode: args.blendMode ?? "normal",
+    transform: {
+      x: 0,
+      y: 0,
+      width,
+      height,
+      rotation: 0,
+      scaleX: 1,
+      scaleY: 1,
+      anchorX: 0.5,
+      anchorY: 0.5,
+      ...args.transform
+    },
+    properties: { ...defaults, ...args.properties }
+  };
+  stack.add(layer, args.index);
+  await state.saveSketch(sketchId);
+  return {
+    layerId: id,
+    type: args.type,
+    name: layer.name,
+    index: args.index ?? stack.count - 1,
+    sketchId
+  };
+}
+async function designRemoveLayer(state, args) {
+  const sketchId = requireSketchId(state, args);
+  const stack = state.getLayerStack(sketchId);
+  const removed = stack.remove(args.layerId);
+  if (!removed) {
+    throw new Error(`Layer '${args.layerId}' not found in sketch '${sketchId}'.`);
+  }
+  await state.saveSketch(sketchId);
+  return { removed: true, layerId: args.layerId, sketchId };
+}
+async function designListLayers(state, args) {
+  const sketchId = requireSketchId(state, args);
+  const stack = state.getLayerStack(sketchId);
+  const layers = stack.getAll();
+  return {
+    sketchId,
+    count: layers.length,
+    layers: layers.map((l, i) => ({
+      index: i,
+      id: l.id,
+      type: l.type,
+      name: l.name,
+      visible: l.visible,
+      locked: l.locked,
+      opacity: l.opacity,
+      blendMode: l.blendMode
+    }))
+  };
+}
+async function designGetLayer(state, args) {
+  const sketchId = requireSketchId(state, args);
+  const stack = state.getLayerStack(sketchId);
+  const layer = stack.get(args.layerId);
+  if (!layer) {
+    throw new Error(`Layer '${args.layerId}' not found in sketch '${sketchId}'.`);
+  }
+  return {
+    sketchId,
+    layer: {
+      id: layer.id,
+      type: layer.type,
+      name: layer.name,
+      visible: layer.visible,
+      locked: layer.locked,
+      opacity: layer.opacity,
+      blendMode: layer.blendMode,
+      transform: layer.transform,
+      properties: layer.properties
+    }
+  };
+}
+async function designUpdateLayer(state, args) {
+  const sketchId = requireSketchId(state, args);
+  const stack = state.getLayerStack(sketchId);
+  const layer = stack.get(args.layerId);
+  if (!layer) {
+    throw new Error(`Layer '${args.layerId}' not found in sketch '${sketchId}'.`);
+  }
+  const updates = {};
+  if (args.properties) {
+    Object.assign(updates, args.properties);
+  }
+  if (Object.keys(updates).length > 0) {
+    stack.updateProperties(args.layerId, updates);
+  }
+  if (args.name !== void 0) {
+    const current = stack.get(args.layerId);
+    stack.updateProperties(args.layerId, { ...current.properties });
+    const mutableLayer = stack.get(args.layerId);
+    mutableLayer.name = args.name;
+  }
+  await state.saveSketch(sketchId);
+  return { updated: true, layerId: args.layerId, sketchId };
+}
+async function designSetTransform(state, args) {
+  const sketchId = requireSketchId(state, args);
+  const stack = state.getLayerStack(sketchId);
+  const layer = stack.get(args.layerId);
+  if (!layer) {
+    throw new Error(`Layer '${args.layerId}' not found in sketch '${sketchId}'.`);
+  }
+  const partial = {};
+  if (args.x !== void 0) partial.x = args.x;
+  if (args.y !== void 0) partial.y = args.y;
+  if (args.width !== void 0) partial.width = args.width;
+  if (args.height !== void 0) partial.height = args.height;
+  if (args.rotation !== void 0) partial.rotation = args.rotation;
+  if (args.scaleX !== void 0) partial.scaleX = args.scaleX;
+  if (args.scaleY !== void 0) partial.scaleY = args.scaleY;
+  if (args.anchorX !== void 0) partial.anchorX = args.anchorX;
+  if (args.anchorY !== void 0) partial.anchorY = args.anchorY;
+  stack.updateTransform(args.layerId, partial);
+  await state.saveSketch(sketchId);
+  return {
+    updated: true,
+    layerId: args.layerId,
+    transform: stack.get(args.layerId).transform,
+    sketchId
+  };
+}
+async function designSetBlend(state, args) {
+  const sketchId = requireSketchId(state, args);
+  const stack = state.getLayerStack(sketchId);
+  const layer = stack.get(args.layerId);
+  if (!layer) {
+    throw new Error(`Layer '${args.layerId}' not found in sketch '${sketchId}'.`);
+  }
+  if (args.blendMode && !BLEND_MODES.includes(args.blendMode)) {
+    throw new Error(
+      `Invalid blend mode '${args.blendMode}'. Must be one of: ${BLEND_MODES.join(", ")}`
+    );
+  }
+  stack.updateBlend(
+    args.layerId,
+    args.blendMode,
+    args.opacity
+  );
+  await state.saveSketch(sketchId);
+  const updated = stack.get(args.layerId);
+  return {
+    updated: true,
+    layerId: args.layerId,
+    blendMode: updated.blendMode,
+    opacity: updated.opacity,
+    sketchId
+  };
+}
+async function designReorderLayers(state, args) {
+  const sketchId = requireSketchId(state, args);
+  const stack = state.getLayerStack(sketchId);
+  const layer = stack.get(args.layerId);
+  if (!layer) {
+    throw new Error(`Layer '${args.layerId}' not found in sketch '${sketchId}'.`);
+  }
+  stack.reorder(args.layerId, args.newIndex);
+  await state.saveSketch(sketchId);
+  return {
+    reordered: true,
+    layerId: args.layerId,
+    newIndex: args.newIndex,
+    sketchId
+  };
+}
+async function designDuplicateLayer(state, args) {
+  const sketchId = requireSketchId(state, args);
+  const stack = state.getLayerStack(sketchId);
+  const layer = stack.get(args.layerId);
+  if (!layer) {
+    throw new Error(`Layer '${args.layerId}' not found in sketch '${sketchId}'.`);
+  }
+  const newId = stack.duplicate(args.layerId);
+  await state.saveSketch(sketchId);
+  return {
+    duplicated: true,
+    sourceLayerId: args.layerId,
+    newLayerId: newId,
+    sketchId
+  };
+}
+async function designToggleVisibility(state, args) {
+  const sketchId = requireSketchId(state, args);
+  const stack = state.getLayerStack(sketchId);
+  const layer = stack.get(args.layerId);
+  if (!layer) {
+    throw new Error(`Layer '${args.layerId}' not found in sketch '${sketchId}'.`);
+  }
+  const newVisible = args.visible ?? !layer.visible;
+  const mutableLayer = layer;
+  mutableLayer.visible = newVisible;
+  stack.updateProperties(args.layerId, { ...layer.properties });
+  await state.saveSketch(sketchId);
+  return {
+    layerId: args.layerId,
+    visible: newVisible,
+    sketchId
+  };
+}
+async function designLockLayer(state, args) {
+  const sketchId = requireSketchId(state, args);
+  const stack = state.getLayerStack(sketchId);
+  const layer = stack.get(args.layerId);
+  if (!layer) {
+    throw new Error(`Layer '${args.layerId}' not found in sketch '${sketchId}'.`);
+  }
+  const newLocked = args.locked ?? !layer.locked;
+  const mutableLayer = layer;
+  mutableLayer.locked = newLocked;
+  stack.updateProperties(args.layerId, { ...layer.properties });
+  await state.saveSketch(sketchId);
+  return {
+    layerId: args.layerId,
+    locked: newLocked,
+    sketchId
+  };
+}
+async function designCaptureComposite(state, args) {
+  const sketchId = requireSketchId(state, args);
+  const stack = state.getLayerStack(sketchId);
+  const layers = stack.getAll();
+  return {
+    sketchId,
+    layerCount: layers.length,
+    visibleCount: layers.filter((l) => l.visible).length,
+    message: "Composite capture requires a rendering surface. Use capture_screenshot to get a rasterized preview of the sketch, then use design_list_layers to see the design layer stack."
+  };
+}
+
+// src/tools/design-plugins.ts
+function registerPluginMcpTools(server, registry4, state) {
+  for (const tool of registry4.getMcpTools()) {
+    const inputSchema = tool.definition.inputSchema;
+    server.tool(
+      tool.name,
+      tool.definition.description,
+      // Pass raw JSON schema — MCP SDK accepts this alongside Zod
+      inputSchema,
+      async (args) => {
+        try {
+          const sketchId = args.sketchId ?? state.requireSelectedSketchId();
+          const context = state.createMcpToolContext(sketchId);
+          const result = await tool.definition.handler(args, context);
+          await state.saveSketch(sketchId);
+          return {
+            content: result.content.map((c) => {
+              if (c.type === "text") {
+                return { type: "text", text: c.text };
+              }
+              return {
+                type: "image",
+                data: c.data,
+                mimeType: c.mimeType
+              };
+            }),
+            isError: result.isError
+          };
+        } catch (e) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  error: e instanceof Error ? e.message : String(e)
+                })
+              }
+            ],
+            isError: true
+          };
+        }
+      }
+    );
+  }
+}
+
 // src/resources/index.ts
 import {
   CANVAS_PRESETS,
@@ -3162,11 +3491,23 @@ function toolError(message) {
     isError: true
   };
 }
+async function initializePluginRegistry() {
+  const registry4 = createPluginRegistry({
+    surface: "mcp",
+    supportsInteractiveTools: false,
+    supportsRendering: false
+  });
+  await registry4.register(typographyPlugin);
+  await registry4.register(filtersPlugin);
+  await registry4.register(shapesPlugin);
+  await registry4.register(layoutGuidesPlugin);
+  return registry4;
+}
 function createServer(state) {
   const server = new McpServer(
     {
       name: "@genart/mcp-server",
-      version: "0.0.1"
+      version: "0.3.0"
     },
     {
       capabilities: {
@@ -3176,6 +3517,11 @@ function createServer(state) {
       }
     }
   );
+  const registryReady = initializePluginRegistry().then((registry4) => {
+    state.pluginRegistry = registry4;
+    registerPluginMcpTools(server, registry4, state);
+  });
+  server._pluginsReady = registryReady;
   registerWorkspaceTools(server, state);
   registerSketchTools(server, state);
   registerComponentTools(server, state);
@@ -3186,6 +3532,7 @@ function createServer(state) {
   registerMergeTools(server, state);
   registerSnapshotTools(server, state);
   registerKnowledgeTools(server, state);
+  registerDesignTools(server, state);
   registerCaptureTools(server, state);
   registerExportTools(server, state);
   registerResources(server, state);
@@ -3974,6 +4321,247 @@ function registerExportTools(server, state) {
     }
   );
 }
+function registerDesignTools(server, state) {
+  server.tool(
+    "design_add_layer",
+    "Add a new design layer of a given type to the active sketch. Layer types come from registered plugins (e.g. 'typography:text', 'filter:grain', 'shapes:rect', 'guides:thirds').",
+    {
+      sketchId: z2.string().optional().describe("Target sketch ID (default: selected sketch)"),
+      type: z2.string().describe("Layer type ID (e.g. 'typography:text', 'filter:grain', 'shapes:rect')"),
+      name: z2.string().optional().describe("Layer display name (default: type's display name)"),
+      properties: z2.record(z2.unknown()).optional().describe("Initial layer properties (merged with type defaults)"),
+      transform: z2.object({
+        x: z2.number().optional(),
+        y: z2.number().optional(),
+        width: z2.number().optional(),
+        height: z2.number().optional(),
+        rotation: z2.number().optional(),
+        scaleX: z2.number().optional(),
+        scaleY: z2.number().optional(),
+        anchorX: z2.number().optional(),
+        anchorY: z2.number().optional()
+      }).optional().describe("Layer transform (default: full canvas)"),
+      opacity: z2.number().optional().describe("Layer opacity 0\u20131 (default: 1)"),
+      blendMode: z2.string().optional().describe("Blend mode (default: 'normal')"),
+      index: z2.number().optional().describe("Insert position in layer stack (default: top)")
+    },
+    async (args) => {
+      try {
+        const result = await designAddLayer(state, args);
+        return jsonResult(result);
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+  server.tool(
+    "design_remove_layer",
+    "Remove a design layer from the active sketch",
+    {
+      sketchId: z2.string().optional().describe("Target sketch ID (default: selected sketch)"),
+      layerId: z2.string().describe("ID of the layer to remove")
+    },
+    async (args) => {
+      try {
+        const result = await designRemoveLayer(state, args);
+        return jsonResult(result);
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+  server.tool(
+    "design_list_layers",
+    "List all design layers in the active sketch with their types, visibility, and key properties",
+    {
+      sketchId: z2.string().optional().describe("Target sketch ID (default: selected sketch)")
+    },
+    async (args) => {
+      try {
+        const result = await designListLayers(state, args);
+        return jsonResult(result);
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+  server.tool(
+    "design_get_layer",
+    "Get full details of a single design layer including all properties and transform",
+    {
+      sketchId: z2.string().optional().describe("Target sketch ID (default: selected sketch)"),
+      layerId: z2.string().describe("ID of the layer to inspect")
+    },
+    async (args) => {
+      try {
+        const result = await designGetLayer(state, args);
+        return jsonResult(result);
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+  server.tool(
+    "design_update_layer",
+    "Update properties on a design layer (e.g. text content, filter intensity, shape fill color)",
+    {
+      sketchId: z2.string().optional().describe("Target sketch ID (default: selected sketch)"),
+      layerId: z2.string().describe("ID of the layer to update"),
+      name: z2.string().optional().describe("New display name"),
+      properties: z2.record(z2.unknown()).optional().describe("Property key-value pairs to set")
+    },
+    async (args) => {
+      try {
+        const result = await designUpdateLayer(state, args);
+        return jsonResult(result);
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+  server.tool(
+    "design_set_transform",
+    "Set the position, size, rotation, and scale of a design layer",
+    {
+      sketchId: z2.string().optional().describe("Target sketch ID (default: selected sketch)"),
+      layerId: z2.string().describe("ID of the layer to transform"),
+      x: z2.number().optional().describe("X position"),
+      y: z2.number().optional().describe("Y position"),
+      width: z2.number().optional().describe("Width"),
+      height: z2.number().optional().describe("Height"),
+      rotation: z2.number().optional().describe("Rotation in degrees"),
+      scaleX: z2.number().optional().describe("Horizontal scale"),
+      scaleY: z2.number().optional().describe("Vertical scale"),
+      anchorX: z2.number().optional().describe("Anchor X (0\u20131)"),
+      anchorY: z2.number().optional().describe("Anchor Y (0\u20131)")
+    },
+    async (args) => {
+      try {
+        const result = await designSetTransform(state, args);
+        return jsonResult(result);
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+  server.tool(
+    "design_set_blend",
+    "Set blend mode and/or opacity on a design layer",
+    {
+      sketchId: z2.string().optional().describe("Target sketch ID (default: selected sketch)"),
+      layerId: z2.string().describe("ID of the layer"),
+      blendMode: z2.enum([
+        "normal",
+        "multiply",
+        "screen",
+        "overlay",
+        "darken",
+        "lighten",
+        "color-dodge",
+        "color-burn",
+        "hard-light",
+        "soft-light",
+        "difference",
+        "exclusion",
+        "hue",
+        "saturation",
+        "color",
+        "luminosity"
+      ]).optional().describe("CSS blend mode"),
+      opacity: z2.number().optional().describe("Layer opacity 0\u20131")
+    },
+    async (args) => {
+      try {
+        const result = await designSetBlend(state, args);
+        return jsonResult(result);
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+  server.tool(
+    "design_reorder_layers",
+    "Move a design layer to a new position in the z-order stack",
+    {
+      sketchId: z2.string().optional().describe("Target sketch ID (default: selected sketch)"),
+      layerId: z2.string().describe("ID of the layer to move"),
+      newIndex: z2.number().describe("New position (0 = bottom, n-1 = top)")
+    },
+    async (args) => {
+      try {
+        const result = await designReorderLayers(state, args);
+        return jsonResult(result);
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+  server.tool(
+    "design_duplicate_layer",
+    "Clone a design layer with a new ID, inserted directly above the source",
+    {
+      sketchId: z2.string().optional().describe("Target sketch ID (default: selected sketch)"),
+      layerId: z2.string().describe("ID of the layer to duplicate")
+    },
+    async (args) => {
+      try {
+        const result = await designDuplicateLayer(state, args);
+        return jsonResult(result);
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+  server.tool(
+    "design_toggle_visibility",
+    "Show or hide a design layer",
+    {
+      sketchId: z2.string().optional().describe("Target sketch ID (default: selected sketch)"),
+      layerId: z2.string().describe("ID of the layer"),
+      visible: z2.boolean().optional().describe("Set visibility (default: toggle)")
+    },
+    async (args) => {
+      try {
+        const result = await designToggleVisibility(state, args);
+        return jsonResult(result);
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+  server.tool(
+    "design_lock_layer",
+    "Lock or unlock a design layer to prevent accidental edits",
+    {
+      sketchId: z2.string().optional().describe("Target sketch ID (default: selected sketch)"),
+      layerId: z2.string().describe("ID of the layer"),
+      locked: z2.boolean().optional().describe("Set lock state (default: toggle)")
+    },
+    async (args) => {
+      try {
+        const result = await designLockLayer(state, args);
+        return jsonResult(result);
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+  server.tool(
+    "design_capture_composite",
+    "Get info about the design layer composite for a sketch. For full visual capture use capture_screenshot.",
+    {
+      sketchId: z2.string().optional().describe("Target sketch ID (default: selected sketch)")
+    },
+    async (args) => {
+      try {
+        const result = await designCaptureComposite(state, args);
+        return jsonResult(result);
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+}
 function registerKnowledgeTools(server, _state) {
   server.tool(
     "list_skills",
@@ -4046,7 +4634,8 @@ import {
   parseGenart as parseGenart4,
   parseWorkspace as parseWorkspace2,
   serializeGenart as serializeGenart5,
-  serializeWorkspace as serializeWorkspace3
+  serializeWorkspace as serializeWorkspace3,
+  createLayerStack
 } from "@genart-dev/core";
 import { writeFile as writeFile7 } from "fs/promises";
 var EditorState = class extends EventEmitter {
@@ -4070,6 +4659,10 @@ var EditorState = class extends EventEmitter {
    * instead of writing to disk. Set by mcp-host for HTTP-based sessions.
    */
   remoteMode = false;
+  /** Plugin registry for design mode. Set during server initialization. */
+  pluginRegistry = null;
+  /** Layer stacks keyed by sketch ID. Created lazily when design tools are used. */
+  layerStacks = /* @__PURE__ */ new Map();
   constructor(options) {
     super();
     if (options?.basePath) {
@@ -4134,6 +4727,7 @@ var EditorState = class extends EventEmitter {
     this.workspace = ws;
     this.sketches.clear();
     this.selection.clear();
+    this.layerStacks.clear();
     for (const ref of ws.sketches) {
       const sketchPath = this.resolveSketchPath(ref.file);
       await this.loadSketch(sketchPath);
@@ -4175,6 +4769,7 @@ var EditorState = class extends EventEmitter {
   removeSketch(id) {
     this.sketches.delete(id);
     this.selection.delete(id);
+    this.layerStacks.delete(id);
     this.emitMutation("sketch:removed", { id });
   }
   /** Save the active workspace to disk. */
@@ -4218,6 +4813,81 @@ var EditorState = class extends EventEmitter {
       selection: Array.from(this.selection)
     };
   }
+  /**
+   * Get or create a LayerStackAccessor for a sketch.
+   * Initializes from the sketch's persisted design layers.
+   */
+  getLayerStack(sketchId) {
+    let stack = this.layerStacks.get(sketchId);
+    if (stack) return stack;
+    const loaded = this.requireSketch(sketchId);
+    const initialLayers = loaded.definition.layers ?? [];
+    stack = createLayerStack(initialLayers, (changeType) => {
+      this.syncLayersToDefinition(sketchId);
+      const mutationType = `design:${changeType}`;
+      this.emitMutation(mutationType, { sketchId, changeType });
+    });
+    this.layerStacks.set(sketchId, stack);
+    return stack;
+  }
+  /**
+   * Sync the layer stack's current state back to the sketch definition.
+   * Called automatically on every layer mutation.
+   */
+  syncLayersToDefinition(sketchId) {
+    const loaded = this.sketches.get(sketchId);
+    const stack = this.layerStacks.get(sketchId);
+    if (!loaded || !stack) return;
+    const layers = stack.getAll();
+    loaded.definition = {
+      ...loaded.definition,
+      layers: layers.length > 0 ? layers : void 0
+    };
+  }
+  /**
+   * Create an McpToolContext for a plugin's MCP tool handler.
+   * Provides access to the layer stack, sketch state, and change notifications.
+   */
+  createMcpToolContext(sketchId) {
+    const loaded = this.requireSketch(sketchId);
+    const layerStack = this.getLayerStack(sketchId);
+    const def = loaded.definition;
+    const sketchState = {
+      seed: def.state.seed,
+      params: def.state.params,
+      colorPalette: def.state.colorPalette,
+      canvasWidth: def.canvas.width,
+      canvasHeight: def.canvas.height,
+      rendererId: def.renderer.type
+    };
+    return {
+      layers: layerStack,
+      sketchState,
+      canvasWidth: def.canvas.width,
+      canvasHeight: def.canvas.height,
+      async resolveAsset(_assetId) {
+        return null;
+      },
+      async captureComposite(_format) {
+        throw new Error("captureComposite is not available in headless MCP mode");
+      },
+      emitChange(_changeType) {
+      }
+    };
+  }
+  /**
+   * Get the currently selected sketch ID for design operations.
+   * Returns the single selected sketch, or throws if none/multiple selected.
+   */
+  requireSelectedSketchId() {
+    if (this.selection.size === 0) {
+      throw new Error("No sketch is selected. Use select_sketch or open_sketch first.");
+    }
+    if (this.selection.size > 1) {
+      throw new Error("Multiple sketches are selected. Design operations require a single sketch.");
+    }
+    return this.selection.values().next().value;
+  }
   /** Emit a mutation event for external listeners (WebSocket broadcast, sidecar IPC). */
   emitMutation(type, payload) {
     this.emit("mutation", { type, payload });