@genart-dev/mcp-server 0.1.2 → 0.3.0

package/dist/index.js

@@ -25,7 +25,8 @@ import {
   parseGenart,
   parseWorkspace,
   serializeGenart,
-  serializeWorkspace
+  serializeWorkspace,
+  createLayerStack
 } from "@genart-dev/core";
 import { writeFile } from "fs/promises";
 var EditorState = class extends EventEmitter {
@@ -49,6 +50,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) {
@@ -113,6 +118,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);
@@ -154,6 +160,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. */
@@ -197,6 +204,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 });
@@ -207,6 +289,11 @@ var EditorState = class extends EventEmitter {
 // 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 as readFile2, writeFile as writeFile2, stat } from "fs/promises";
@@ -551,6 +638,7 @@ import { writeFile as writeFile3, stat as stat2, unlink } from "fs/promises";
 import { basename as basename2, dirname as dirname3, resolve as resolve2 } from "path";
 import {
   createDefaultRegistry,
+  resolveComponents,
   resolvePreset,
   serializeGenart as serializeGenart2,
   serializeWorkspace as serializeWorkspace3
@@ -647,10 +735,40 @@ async function createSketch(state, input) {
     const adapter = registry4.resolve(rendererType);
     algorithm = adapter.getAlgorithmTemplate();
   }
+  let resolvedComponents;
+  if (input.components && Object.keys(input.components).length > 0) {
+    const shorthand = {};
+    for (const [name, value] of Object.entries(input.components)) {
+      if (typeof value === "string") {
+        shorthand[name] = value;
+      } else if (value.version) {
+        shorthand[name] = value.version;
+      } else if (value.code) {
+        if (!resolvedComponents) resolvedComponents = {};
+        resolvedComponents[name] = {
+          ...value.version ? { version: value.version } : {},
+          code: value.code,
+          ...value.exports ? { exports: value.exports } : {}
+        };
+      }
+    }
+    if (Object.keys(shorthand).length > 0) {
+      const resolved = resolveComponents(shorthand, rendererType);
+      if (!resolvedComponents) resolvedComponents = {};
+      for (const rc of resolved) {
+        resolvedComponents[rc.name] = {
+          version: rc.version,
+          code: rc.code,
+          exports: [...rc.exports]
+        };
+      }
+    }
+  }
   const seed = input.seed ?? Math.floor(Math.random() * 1e5);
   const ts = now2();
+  const hasComponents = resolvedComponents && Object.keys(resolvedComponents).length > 0;
   const sketch = {
-    genart: "1.1",
+    genart: hasComponents ? "1.2" : "1.1",
     id: input.id,
     title: input.title,
     created: ts,
@@ -664,6 +782,7 @@ async function createSketch(state, input) {
     ...input.philosophy ? { philosophy: input.philosophy } : {},
     ...input.themes && input.themes.length > 0 ? { themes: input.themes } : {},
     ...input.skills && input.skills.length > 0 ? { skills: input.skills } : {},
+    ...hasComponents ? { components: resolvedComponents } : {},
     ...input.agent ? { agent: input.agent } : {},
     ...input.model ? { model: input.model } : {}
   };
@@ -847,10 +966,44 @@ async function updateAlgorithm(state, input) {
       );
     }
   }
+  let resolvedComponents;
+  if (input.components && Object.keys(input.components).length > 0) {
+    const renderer = def.renderer.type;
+    const shorthand = {};
+    for (const [name, value] of Object.entries(input.components)) {
+      if (typeof value === "string") {
+        shorthand[name] = value;
+      } else if (value.version) {
+        shorthand[name] = value.version;
+      } else if (value.code) {
+        if (!resolvedComponents) resolvedComponents = {};
+        resolvedComponents[name] = {
+          ...value.version ? { version: value.version } : {},
+          code: value.code,
+          ...value.exports ? { exports: value.exports } : {}
+        };
+      }
+    }
+    if (Object.keys(shorthand).length > 0) {
+      const resolved = resolveComponents(shorthand, renderer);
+      if (!resolvedComponents) resolvedComponents = {};
+      for (const rc of resolved) {
+        resolvedComponents[rc.name] = {
+          version: rc.version,
+          code: rc.code,
+          exports: [...rc.exports]
+        };
+      }
+    }
+  }
+  const updated = ["algorithm"];
+  const hasNewComponents = resolvedComponents && Object.keys(resolvedComponents).length > 0;
+  if (hasNewComponents) updated.push("components");
   const newDef = {
     ...def,
     modified: now2(),
     algorithm: input.algorithm,
+    ...hasNewComponents ? { genart: "1.2", components: resolvedComponents } : {},
     ...input.agent ? { agent: input.agent } : {},
     ...input.model ? { model: input.model } : {}
   };
@@ -864,7 +1017,7 @@ async function updateAlgorithm(state, input) {
   }
   state.emitMutation("sketch:updated", {
     id: input.sketchId,
-    updated: ["algorithm"]
+    updated
   });
   return {
     success: true,
@@ -872,6 +1025,7 @@ async function updateAlgorithm(state, input) {
     renderer: def.renderer.type,
     algorithmLength: input.algorithm.length,
     validationPassed,
+    ...hasNewComponents ? { componentsUpdated: true } : {},
     fileContent: json
   };
 }
@@ -2173,8 +2327,219 @@ ${guidelines}`,
   };
 }
 
-// src/tools/capture.ts
+// src/tools/components.ts
 import { writeFile as writeFile5 } from "fs/promises";
+import {
+  COMPONENT_REGISTRY,
+  resolveComponents as resolveComponents2,
+  serializeGenart as serializeGenart4
+} from "@genart-dev/core";
+var VALID_RENDERERS2 = [
+  "p5",
+  "three",
+  "glsl",
+  "canvas2d",
+  "svg"
+];
+var RENDERER_TARGET = {
+  p5: "js",
+  three: "js",
+  canvas2d: "js",
+  svg: "js",
+  glsl: "glsl"
+};
+async function listComponents(_state, input) {
+  let entries = Object.values(COMPONENT_REGISTRY);
+  if (input.renderer) {
+    const renderer = input.renderer;
+    const target = RENDERER_TARGET[renderer];
+    if (!target) {
+      throw new Error(
+        `Unknown renderer type: '${input.renderer}'. Valid types: ${VALID_RENDERERS2.join(", ")}`
+      );
+    }
+    entries = entries.filter(
+      (e) => e.target === target && (e.renderers.length === 0 || e.renderers.includes(renderer))
+    );
+  }
+  if (input.category) {
+    const cat = input.category;
+    entries = entries.filter((e) => e.category === cat);
+  }
+  entries.sort((a, b) => {
+    const catCmp = a.category.localeCompare(b.category);
+    if (catCmp !== 0) return catCmp;
+    return a.name.localeCompare(b.name);
+  });
+  const components = entries.map((e) => ({
+    name: e.name,
+    version: e.version,
+    category: e.category,
+    target: e.target,
+    exports: [...e.exports],
+    dependencies: [...e.dependencies],
+    description: e.description
+  }));
+  return {
+    count: components.length,
+    components
+  };
+}
+async function addComponent(state, input) {
+  const loaded = state.requireSketch(input.sketchId);
+  const def = loaded.definition;
+  const renderer = def.renderer.type;
+  const entry = COMPONENT_REGISTRY[input.component];
+  if (!entry) {
+    throw new Error(`Unknown component: "${input.component}"`);
+  }
+  const target = RENDERER_TARGET[renderer];
+  if (entry.target !== target) {
+    throw new Error(
+      `Component "${input.component}" has target "${entry.target}" but renderer "${renderer}" requires target "${target}"`
+    );
+  }
+  if (entry.renderers.length > 0 && !entry.renderers.includes(renderer)) {
+    throw new Error(
+      `Component "${input.component}" is not compatible with renderer "${renderer}". Compatible: ${entry.renderers.join(", ")}`
+    );
+  }
+  const existingComponents = {};
+  if (def.components) {
+    for (const [name, value] of Object.entries(def.components)) {
+      if (typeof value === "string") {
+        existingComponents[name] = value;
+      } else if (value.version) {
+        existingComponents[name] = value.version;
+      }
+    }
+  }
+  if (existingComponents[input.component]) {
+    throw new Error(
+      `Component "${input.component}" is already present in sketch "${input.sketchId}"`
+    );
+  }
+  existingComponents[input.component] = input.version ?? "^1.0.0";
+  const resolved = resolveComponents2(existingComponents, renderer);
+  const resolvedRecord = {};
+  for (const rc of resolved) {
+    resolvedRecord[rc.name] = {
+      version: rc.version,
+      code: rc.code,
+      exports: [...rc.exports]
+    };
+  }
+  const previousNames = new Set(
+    def.components ? Object.keys(def.components) : []
+  );
+  const added = resolved.map((rc) => rc.name).filter((name) => !previousNames.has(name));
+  const newDef = {
+    ...def,
+    genart: "1.2",
+    modified: (/* @__PURE__ */ new Date()).toISOString(),
+    components: resolvedRecord
+  };
+  state.sketches.set(input.sketchId, {
+    definition: newDef,
+    path: loaded.path
+  });
+  const json = serializeGenart4(newDef);
+  if (!state.remoteMode) {
+    await writeFile5(loaded.path, json, "utf-8");
+  }
+  state.emitMutation("sketch:updated", {
+    id: input.sketchId,
+    updated: ["components"]
+  });
+  return {
+    success: true,
+    sketchId: input.sketchId,
+    components: resolvedRecord,
+    added,
+    fileContent: json
+  };
+}
+async function removeComponent(state, input) {
+  const loaded = state.requireSketch(input.sketchId);
+  const def = loaded.definition;
+  if (!def.components || !def.components[input.component]) {
+    throw new Error(
+      `Component "${input.component}" is not present in sketch "${input.sketchId}"`
+    );
+  }
+  const remaining = { ...def.components };
+  delete remaining[input.component];
+  for (const [name, value] of Object.entries(remaining)) {
+    const entry = COMPONENT_REGISTRY[name];
+    if (entry && entry.dependencies.includes(input.component)) {
+      throw new Error(
+        `Cannot remove "${input.component}": component "${name}" depends on it`
+      );
+    }
+  }
+  let warning;
+  const removedValue = def.components[input.component];
+  const exports = typeof removedValue === "string" ? COMPONENT_REGISTRY[input.component]?.exports ?? [] : removedValue.exports ?? [];
+  const usedExports = exports.filter((exp) => def.algorithm.includes(exp));
+  if (usedExports.length > 0) {
+    warning = `Algorithm may reference these exports from "${input.component}": ${usedExports.join(", ")}. Review your algorithm after removal.`;
+  }
+  const removed = [input.component];
+  const neededDeps = /* @__PURE__ */ new Set();
+  for (const name of Object.keys(remaining)) {
+    const entry = COMPONENT_REGISTRY[name];
+    if (entry) {
+      collectTransitiveDeps(name, neededDeps);
+    }
+  }
+  for (const name of Object.keys(remaining)) {
+    if (!neededDeps.has(name) && !isDirectComponent(name, remaining)) {
+      delete remaining[name];
+      removed.push(name);
+    }
+  }
+  const hasRemaining = Object.keys(remaining).length > 0;
+  const newDef = {
+    ...def,
+    modified: (/* @__PURE__ */ new Date()).toISOString(),
+    ...hasRemaining ? { components: remaining } : { components: void 0 }
+  };
+  state.sketches.set(input.sketchId, {
+    definition: newDef,
+    path: loaded.path
+  });
+  const json = serializeGenart4(newDef);
+  if (!state.remoteMode) {
+    await writeFile5(loaded.path, json, "utf-8");
+  }
+  state.emitMutation("sketch:updated", {
+    id: input.sketchId,
+    updated: ["components"]
+  });
+  return {
+    success: true,
+    sketchId: input.sketchId,
+    removed,
+    ...warning ? { warning } : {},
+    fileContent: json
+  };
+}
+function collectTransitiveDeps(name, deps) {
+  const entry = COMPONENT_REGISTRY[name];
+  if (!entry) return;
+  deps.add(name);
+  for (const dep of entry.dependencies) {
+    if (!deps.has(dep)) {
+      collectTransitiveDeps(dep, deps);
+    }
+  }
+}
+function isDirectComponent(name, components) {
+  return name in components;
+}
+
+// src/tools/capture.ts
+import { writeFile as writeFile6 } from "fs/promises";
 import {
   createDefaultRegistry as createDefaultRegistry2
 } from "@genart-dev/core";
@@ -2352,7 +2717,7 @@ async function buildScreenshotMetadata(state, multi, info) {
     previewPath: info.previewPath
   };
   if (!state.remoteMode) {
-    await writeFile5(info.previewPath, multi.previewPng);
+    await writeFile6(info.previewPath, multi.previewPng);
     metadata.savedPreviewTo = info.previewPath;
   }
   return metadata;
@@ -2413,12 +2778,12 @@ async function captureBatch(state, input) {
 
 // src/tools/export.ts
 import { createWriteStream } from "fs";
-import { stat as stat4, writeFile as writeFile6 } from "fs/promises";
+import { stat as stat4, writeFile as writeFile7 } from "fs/promises";
 import { dirname as dirname6 } from "path";
 import archiver from "archiver";
 import {
   createDefaultRegistry as createDefaultRegistry3,
-  serializeGenart as serializeGenart4
+  serializeGenart as serializeGenart5
 } from "@genart-dev/core";
 var registry3 = createDefaultRegistry3();
 async function validateOutputPath(outputPath) {
@@ -2488,7 +2853,7 @@ async function exportHtml(sketch, outputPath) {
   const adapter = registry3.resolve(sketch.renderer.type);
   const html = adapter.generateStandaloneHTML(sketch);
   const content = Buffer.from(html, "utf-8");
-  await writeFile6(outputPath, content);
+  await writeFile7(outputPath, content);
   return {
     success: true,
     sketchId: sketch.id,
@@ -2504,7 +2869,7 @@ async function exportPng(sketch, input) {
   const width = input.width ?? sketch.canvas.width;
   const height = input.height ?? sketch.canvas.height;
   const result = await captureHtml({ html, width, height });
-  await writeFile6(input.outputPath, result.bytes);
+  await writeFile7(input.outputPath, result.bytes);
   return {
     success: true,
     sketchId: sketch.id,
@@ -2519,7 +2884,7 @@ async function exportSvg(sketch, input) {
   const height = input.height ?? sketch.canvas.height;
   if (sketch.renderer.type === "svg") {
     const content2 = Buffer.from(sketch.algorithm, "utf-8");
-    await writeFile6(input.outputPath, content2);
+    await writeFile7(input.outputPath, content2);
     return {
       success: true,
       sketchId: sketch.id,
@@ -2541,7 +2906,7 @@ async function exportSvg(sketch, input) {
          href="data:image/png;base64,${b64}"/>
 </svg>`;
   const content = Buffer.from(svg, "utf-8");
-  await writeFile6(input.outputPath, content);
+  await writeFile7(input.outputPath, content);
   return {
     success: true,
     sketchId: sketch.id,
@@ -2554,7 +2919,7 @@ async function exportSvg(sketch, input) {
 }
 async function exportAlgorithm(sketch, outputPath) {
   const content = Buffer.from(sketch.algorithm, "utf-8");
-  await writeFile6(outputPath, content);
+  await writeFile7(outputPath, content);
   return {
     success: true,
     sketchId: sketch.id,
@@ -2569,7 +2934,7 @@ async function exportZip(sketch, input) {
   const width = input.width ?? sketch.canvas.width;
   const height = input.height ?? sketch.canvas.height;
   const html = adapter.generateStandaloneHTML(sketch);
-  const genartJson = serializeGenart4(sketch);
+  const genartJson = serializeGenart5(sketch);
   const algorithm = sketch.algorithm;
   const algExt = algorithmExtension(sketch.renderer.type);
   const captureResult = await captureHtml({ html, width, height });
@@ -2603,6 +2968,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,
@@ -3090,11 +3779,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: {
@@ -3104,8 +3805,14 @@ 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);
   registerSelectionTools(server, state);
   registerParameterTools(server, state);
   registerArrangementTools(server, state);
@@ -3113,6 +3820,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);
@@ -3209,7 +3917,7 @@ function registerWorkspaceTools(server, state) {
 function registerSketchTools(server, state) {
   server.tool(
     "create_sketch",
-    "Create a new .genart sketch file from metadata, parameters, and algorithm",
+    'Create a new .genart sketch file from metadata, parameters, and algorithm. IMPORTANT: Do not embed common utilities (PRNG, noise, easing, color math, vector ops) inline in the algorithm. Instead, declare them as components: { "prng": "^1.0.0", "noise-2d": "^1.0.0" }. Then use the exported functions directly in your algorithm (e.g., mulberry32, fbm2D). Use list_components to see all available components for the current renderer.',
     {
       id: z2.string().describe("URL-safe kebab-case identifier"),
       title: z2.string().describe("Human-readable title"),
@@ -3247,6 +3955,16 @@ function registerSketchTools(server, state) {
       algorithm: z2.string().optional().describe("Algorithm source code (default: renderer template). For p5: must be `function sketch(p, state) { ... }` in instance mode. State provides: state.WIDTH, state.HEIGHT, state.SEED (number), state.PARAMS (keyed by param key), state.COLORS (keyed by color key, hex strings). Use p5 instance methods (p.createCanvas, p.background, etc)."),
       seed: z2.number().optional().describe("Initial random seed (default: random)"),
       skills: z2.array(z2.string()).optional().describe("Design skill references"),
+      components: z2.record(
+        z2.union([
+          z2.string(),
+          z2.object({
+            version: z2.string().optional(),
+            code: z2.string().optional(),
+            exports: z2.array(z2.string()).optional()
+          })
+        ])
+      ).optional().describe('Component dependencies. Use list_components to see available. Keys are component names, values are semver ranges (e.g. "^1.0.0") or objects with version/code/exports.'),
       addToWorkspace: z2.string().optional().describe("Path to workspace to add sketch to after creation"),
       agent: z2.string().optional().describe("Your CLI agent name (e.g. 'claude-code', 'codex-cli', 'gemini-cli', 'opencode', 'kiro')"),
       model: z2.string().optional().describe("Your AI model identifier (e.g. 'claude-opus-4-6', 'gpt-4o', 'gemini-2.5-pro')")
@@ -3326,11 +4044,21 @@ function registerSketchTools(server, state) {
   );
   server.tool(
     "update_algorithm",
-    "Replace the algorithm source code of a sketch",
+    "Replace the algorithm source code of a sketch. If adding/changing components, pass them in the components field alongside the algorithm.",
     {
       sketchId: z2.string().describe("ID of the sketch to update"),
       algorithm: z2.string().describe("New algorithm source code. For p5: must be `function sketch(p, state) { ... }` in instance mode. State provides: state.WIDTH, state.HEIGHT, state.SEED, state.PARAMS (keyed by param key), state.COLORS (keyed by color key)."),
       validate: z2.boolean().optional().describe("Run renderer-specific validation before saving (default: true)"),
+      components: z2.record(
+        z2.union([
+          z2.string(),
+          z2.object({
+            version: z2.string().optional(),
+            code: z2.string().optional(),
+            exports: z2.array(z2.string()).optional()
+          })
+        ])
+      ).optional().describe("Component dependencies to resolve alongside the algorithm update. Use list_components to see available."),
       agent: z2.string().optional().describe("Your CLI agent name (e.g. 'claude-code', 'codex-cli', 'gemini-cli', 'opencode', 'kiro')"),
       model: z2.string().optional().describe("Your AI model identifier (e.g. 'claude-opus-4-6', 'gpt-4o', 'gemini-2.5-pro')")
     },
@@ -3426,6 +4154,76 @@ function registerSketchTools(server, state) {
     }
   );
 }
+function registerComponentTools(server, state) {
+  server.tool(
+    "list_components",
+    "List available reusable components from the registry, filtered by renderer and/or category. Components provide common utilities (PRNG, noise, easing, color math, etc.) that can be declared as dependencies instead of inlining code in the algorithm.",
+    {
+      renderer: z2.enum(["p5", "three", "glsl", "canvas2d", "svg"]).optional().describe("Filter by renderer compatibility"),
+      category: z2.enum([
+        "randomness",
+        "noise",
+        "math",
+        "easing",
+        "color",
+        "vector",
+        "geometry",
+        "grid",
+        "particle",
+        "physics",
+        "distribution",
+        "pattern",
+        "sdf",
+        "transform",
+        "animation",
+        "string",
+        "data-structure",
+        "imaging"
+      ]).optional().describe("Filter by component category")
+    },
+    async (args) => {
+      try {
+        const result = await listComponents(state, args);
+        return jsonResult(result);
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+  server.tool(
+    "add_component",
+    "Add a component dependency to an existing sketch. Resolves the component and any transitive dependencies from the registry, validates renderer compatibility, and writes the resolved form to the sketch file.",
+    {
+      sketchId: z2.string().describe("ID of the sketch to add the component to"),
+      component: z2.string().describe("Component name (e.g. 'prng', 'noise-2d', 'glsl-noise')"),
+      version: z2.string().optional().describe("Version range (default: '^1.0.0')")
+    },
+    async (args) => {
+      try {
+        const result = await addComponent(state, args);
+        return jsonResult(result);
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+  server.tool(
+    "remove_component",
+    "Remove a component dependency from a sketch. Checks for dependent components and warns if the algorithm references the component's exports.",
+    {
+      sketchId: z2.string().describe("ID of the sketch to remove the component from"),
+      component: z2.string().describe("Component name to remove")
+    },
+    async (args) => {
+      try {
+        const result = await removeComponent(state, args);
+        return jsonResult(result);
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+}
 function registerSelectionTools(server, state) {
   server.tool(
     "get_selection",
@@ -3811,6 +4609,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",