feat(m2): write-parity kickoff — idempotency infra + 3 tools

Establishes the write pattern on top of the existing dispatch/relay/sandbox chain:

- Idempotency (beats figma-mcp-go, which has none): server injects a stable
  requestId for WRITE_TOOLS before the retrying dispatch; plugin wraps each write
  handler in an LRU/TTL(60s) cache (idempotency.ts) so replayed retries return the
  original result instead of re-applying.
- Three bellwether tools: set_fills (paint write), set_text (async loadFontAsync,
  loads all fonts for mixed text), create_frame (create + parent + new id; removes
  the orphan frame on invalid parent). shared: MutateResult / CreateResult.
- Writes reuse the dispatchTool fall-through (election + resilient reconnect); only
  requestId injection is special-cased in the server.

+18 tests (296 total): idempotency 5x-replay acceptance, all three handlers, tool
defs. lint / typecheck / build green.

Author: awdr74100

packages/plugin/src/code.ts

@@ -1,6 +1,8 @@
 import { createPluginContextEvent, SELECTION_DETAIL_LIMIT } from '@figma-mcp-relay/shared';
 
 import { dispatchSandboxMessage, type SandboxHandlers } from './dispatcher.js';
+import { createIdempotencyCache, idempotent } from './idempotency.js';
+import { createCreateFrameHandler } from './handlers/create-frame.js';
 import { createGetAnnotationsHandler } from './handlers/get-annotations.js';
 import { createGetDesignContextHandler } from './handlers/get-design-context.js';
 import { createGetDocumentHandler } from './handlers/get-document.js';
@@ -21,6 +23,8 @@ import { createPingHandler } from './handlers/ping.js';
 import { createScanNodesByTypesHandler } from './handlers/scan-nodes-by-types.js';
 import { createScanTextNodesHandler } from './handlers/scan-text-nodes.js';
 import { createSearchNodesHandler } from './handlers/search-nodes.js';
+import { createSetFillsHandler } from './handlers/set-fills.js';
+import { createSetTextHandler } from './handlers/set-text.js';
 
 figma.showUI(__html__, { width: 320, height: 400, themeColors: true });
 
@@ -50,6 +54,8 @@ const emitContext = (): void => {
   figma.ui.postMessage(event);
 };
 
+const idempotencyCache = createIdempotencyCache();
+
 const handlers: SandboxHandlers = {
   ping: createPingHandler(figma),
   get_selection: createGetSelectionHandler(figma),
@@ -71,6 +77,10 @@ const handlers: SandboxHandlers = {
   list_files: createListFilesHandler(figma),
   get_design_context: createGetDesignContextHandler(figma),
   get_screenshot: createGetScreenshotHandler(figma),
+  // Write tools: wrapped with idempotency so retries (same requestId) apply the effect once.
+  set_fills: idempotent(idempotencyCache, createSetFillsHandler(figma)),
+  set_text: idempotent(idempotencyCache, createSetTextHandler(figma)),
+  create_frame: idempotent(idempotencyCache, createCreateFrameHandler(figma)),
 };
 
 figma.ui.onmessage = (raw: unknown) => {

packages/plugin/src/handlers/create-frame.ts

@@ -0,0 +1,38 @@
+import type { CreateResult } from '@figma-mcp-relay/shared';
+
+import type { SandboxToolHandler } from '../dispatcher.js';
+
+export const createCreateFrameHandler =
+  (figmaCtx: typeof figma): SandboxToolHandler =>
+  async params => {
+    const p = (params ?? {}) as {
+      parentId?: unknown;
+      name?: unknown;
+      x?: unknown;
+      y?: unknown;
+      width?: unknown;
+      height?: unknown;
+    };
+
+    const frame = figmaCtx.createFrame();
+    if (typeof p.name === 'string') frame.name = p.name;
+    if (typeof p.width === 'number' && typeof p.height === 'number') {
+      frame.resize(p.width, p.height);
+    }
+    if (typeof p.x === 'number') frame.x = p.x;
+    if (typeof p.y === 'number') frame.y = p.y;
+
+    if (typeof p.parentId === 'string') {
+      const parent = await figmaCtx.getNodeByIdAsync(p.parentId);
+      if (parent === null || !('appendChild' in parent)) {
+        frame.remove();
+        throw new Error(`create_frame: parent ${p.parentId} not found or cannot contain children`);
+      }
+      (parent as ChildrenMixin).appendChild(frame);
+    } else {
+      figmaCtx.currentPage.appendChild(frame);
+    }
+
+    const result: CreateResult = { ok: true, nodeId: frame.id, name: frame.name, type: frame.type };
+    return result;
+  };

packages/plugin/src/handlers/set-fills.ts

@@ -0,0 +1,33 @@
+import type { MutateResult, SerializedPaint } from '@figma-mcp-relay/shared';
+
+import type { SandboxToolHandler } from '../dispatcher.js';
+
+/** Convert a serialized paint back to a Figma Paint. Only SOLID is supported for writes so far. */
+const toFigmaPaint = (paint: SerializedPaint): Paint => {
+  if (paint.type !== 'SOLID') {
+    throw new TypeError(`set_fills: only SOLID paints are supported (got ${paint.type})`);
+  }
+  return {
+    type: 'SOLID',
+    color: { r: paint.color.r, g: paint.color.g, b: paint.color.b },
+    opacity: paint.opacity,
+    visible: paint.visible,
+  };
+};
+
+export const createSetFillsHandler =
+  (figmaCtx: typeof figma): SandboxToolHandler =>
+  async params => {
+    const p = (params ?? {}) as { nodeId?: unknown; fills?: unknown };
+    if (typeof p.nodeId !== 'string') throw new TypeError('set_fills: nodeId must be a string');
+    if (!Array.isArray(p.fills)) throw new TypeError('set_fills: fills must be an array');
+
+    const node = await figmaCtx.getNodeByIdAsync(p.nodeId);
+    if (node === null || !('fills' in node)) {
+      throw new Error(`set_fills: node ${p.nodeId} not found or cannot have fills`);
+    }
+    (node as GeometryMixin).fills = (p.fills as SerializedPaint[]).map(toFigmaPaint);
+
+    const result: MutateResult = { ok: true, nodeId: node.id };
+    return result;
+  };

packages/plugin/src/handlers/set-text.ts

@@ -0,0 +1,29 @@
+import type { MutateResult } from '@figma-mcp-relay/shared';
+
+import type { SandboxToolHandler } from '../dispatcher.js';
+
+export const createSetTextHandler =
+  (figmaCtx: typeof figma): SandboxToolHandler =>
+  async params => {
+    const p = (params ?? {}) as { nodeId?: unknown; characters?: unknown };
+    if (typeof p.nodeId !== 'string') throw new TypeError('set_text: nodeId must be a string');
+    if (typeof p.characters !== 'string') throw new TypeError('set_text: characters must be a string');
+
+    const node = await figmaCtx.getNodeByIdAsync(p.nodeId);
+    if (node === null || node.type !== 'TEXT') {
+      throw new Error(`set_text: node ${p.nodeId} is not a TEXT node`);
+    }
+    const text = node as TextNode;
+
+    // Figma requires every font in the node to be loaded before mutating characters.
+    const fonts =
+      text.fontName === figmaCtx.mixed && text.characters.length > 0
+        ? text.getRangeAllFontNames(0, text.characters.length)
+        : [text.fontName as FontName];
+    await Promise.all(fonts.map(font => figmaCtx.loadFontAsync(font)));
+
+    text.characters = p.characters;
+
+    const result: MutateResult = { ok: true, nodeId: text.id };
+    return result;
+  };

packages/plugin/src/idempotency.ts

@@ -0,0 +1,57 @@
+import type { SandboxToolHandler } from './dispatcher.js';
+
+export const DEFAULT_IDEMPOTENCY_TTL_MS = 60_000;
+
+interface Entry {
+  result: unknown;
+  ts: number;
+}
+
+export interface IdempotencyCache {
+  /** Run fn unless this requestId already produced a result within the TTL; then replay it. */
+  run(requestId: string | undefined, fn: () => unknown | Promise<unknown>): Promise<unknown>;
+  size(): number;
+}
+
+/**
+ * Dedupe write side-effects across retries. The server reuses one requestId for all retries of a
+ * logical tool call (our resilience layer retries on transport errors), so a replayed write must
+ * not apply twice — it returns the original result instead.
+ */
+export const createIdempotencyCache = (
+  ttlMs: number = DEFAULT_IDEMPOTENCY_TTL_MS,
+  now: () => number = Date.now,
+): IdempotencyCache => {
+  const map = new Map<string, Entry>();
+
+  const prune = (): void => {
+    const cutoff = now() - ttlMs;
+    for (const [key, entry] of map) {
+      if (entry.ts < cutoff) map.delete(key);
+    }
+  };
+
+  return {
+    async run(requestId, fn) {
+      if (requestId === undefined) return fn(); // no key → no dedup
+      const hit = map.get(requestId);
+      if (hit !== undefined && now() - hit.ts < ttlMs) return hit.result;
+      const result = await fn();
+      map.set(requestId, { result, ts: now() });
+      prune();
+      return result;
+    },
+    size: () => map.size,
+  };
+};
+
+/**
+ * Wrap a write handler so repeated calls carrying the same `requestId` apply the effect once.
+ * Calls without a requestId run normally (reads, or writes invoked without idempotency).
+ */
+export const idempotent =
+  (cache: IdempotencyCache, handler: SandboxToolHandler): SandboxToolHandler =>
+  params => {
+    const requestId = (params as { requestId?: unknown } | null)?.requestId;
+    return cache.run(typeof requestId === 'string' ? requestId : undefined, () => handler(params));
+  };

packages/plugin/test/handlers/create-frame.test.ts

@@ -0,0 +1,77 @@
+import type { CreateResult } from '@figma-mcp-relay/shared';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createCreateFrameHandler } from '../../src/handlers/create-frame.js';
+
+interface FakeFrame {
+  id: string;
+  name: string;
+  type: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  resize: (w: number, h: number) => void;
+  remove: () => void;
+}
+
+const makeFrame = (): FakeFrame => {
+  const frame: FakeFrame = {
+    id: '2:1',
+    name: 'Frame',
+    type: 'FRAME',
+    x: 0,
+    y: 0,
+    width: 100,
+    height: 100,
+    resize(w, h) {
+      frame.width = w;
+      frame.height = h;
+    },
+    remove: vi.fn<() => void>(),
+  };
+  return frame;
+};
+
+const fakeFigma = (
+  frame: FakeFrame,
+  currentPage: { appendChild: (n: unknown) => void },
+  lookup: Record<string, unknown> = {},
+): typeof figma =>
+  ({
+    createFrame: () => frame,
+    currentPage,
+    getNodeByIdAsync: async (id: string) => lookup[id] ?? null,
+  }) as unknown as typeof figma;
+
+describe('create_frame handler', () => {
+  it('creates a sized/named frame on the current page by default', async () => {
+    const frame = makeFrame();
+    const currentPage = { appendChild: vi.fn<(n: unknown) => void>() };
+    const handler = createCreateFrameHandler(fakeFigma(frame, currentPage));
+    const result = (await handler({ name: 'Card', width: 200, height: 120, x: 10, y: 20 })) as CreateResult;
+
+    expect(frame.name).toBe('Card');
+    expect([frame.width, frame.height]).toEqual([200, 120]);
+    expect([frame.x, frame.y]).toEqual([10, 20]);
+    expect(currentPage.appendChild).toHaveBeenCalledWith(frame);
+    expect(result).toEqual({ ok: true, nodeId: '2:1', name: 'Card', type: 'FRAME' });
+  });
+
+  it('appends into a given parent', async () => {
+    const frame = makeFrame();
+    const parent = { id: '1:1', appendChild: vi.fn<(n: unknown) => void>() };
+    const handler = createCreateFrameHandler(
+      fakeFigma(frame, { appendChild: vi.fn<(n: unknown) => void>() }, { '1:1': parent }),
+    );
+    await handler({ parentId: '1:1' });
+    expect(parent.appendChild).toHaveBeenCalledWith(frame);
+  });
+
+  it('removes the orphan frame and throws when the parent is invalid', async () => {
+    const frame = makeFrame();
+    const handler = createCreateFrameHandler(fakeFigma(frame, { appendChild: vi.fn<(n: unknown) => void>() }, {}));
+    await expect(handler({ parentId: '9:9' })).rejects.toThrow(/parent/);
+    expect(frame.remove).toHaveBeenCalled();
+  });
+});

packages/plugin/test/handlers/set-fills.test.ts

@@ -0,0 +1,34 @@
+import type { MutateResult } from '@figma-mcp-relay/shared';
+import { describe, expect, it } from 'vitest';
+
+import { createSetFillsHandler } from '../../src/handlers/set-fills.js';
+
+const fakeFigma = (lookup: Record<string, unknown>): typeof figma =>
+  ({ getNodeByIdAsync: async (id: string) => lookup[id] ?? null }) as unknown as typeof figma;
+
+describe('set_fills handler', () => {
+  it('applies SOLID fills to a node and returns ok + nodeId', async () => {
+    const node = { id: '1:1', fills: [] as unknown };
+    const handler = createSetFillsHandler(fakeFigma({ '1:1': node }));
+    const result = (await handler({
+      nodeId: '1:1',
+      fills: [{ type: 'SOLID', visible: true, opacity: 1, color: { r: 1, g: 0, b: 0 } }],
+    })) as MutateResult;
+
+    expect(node.fills).toEqual([
+      { type: 'SOLID', color: { r: 1, g: 0, b: 0 }, opacity: 1, visible: true },
+    ]);
+    expect(result).toEqual({ ok: true, nodeId: '1:1' });
+  });
+
+  it('throws on non-SOLID paint, missing node, or bad input', async () => {
+    const node = { id: '1:1', fills: [] as unknown };
+    const handler = createSetFillsHandler(fakeFigma({ '1:1': node }));
+    await expect(
+      handler({ nodeId: '1:1', fills: [{ type: 'GRADIENT_LINEAR', visible: true, opacity: 1 }] }),
+    ).rejects.toThrow(/SOLID/);
+    await expect(handler({ nodeId: '9:9', fills: [] })).rejects.toThrow(/not found/);
+    await expect(handler({ fills: [] })).rejects.toThrow(/nodeId/);
+    await expect(handler({ nodeId: '1:1', fills: 'x' })).rejects.toThrow(/fills/);
+  });
+});

packages/plugin/test/handlers/set-text.test.ts

@@ -0,0 +1,62 @@
+import type { MutateResult } from '@figma-mcp-relay/shared';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createSetTextHandler } from '../../src/handlers/set-text.js';
+
+const MIXED = Symbol('figma.mixed');
+
+const fakeFigma = (
+  lookup: Record<string, unknown>,
+  loadFontAsync = vi.fn<() => Promise<void>>(async () => {}),
+): typeof figma =>
+  ({
+    mixed: MIXED,
+    loadFontAsync,
+    getNodeByIdAsync: async (id: string) => lookup[id] ?? null,
+  }) as unknown as typeof figma;
+
+describe('set_text handler', () => {
+  it('loads the font then replaces characters', async () => {
+    const node = {
+      id: '1:1',
+      type: 'TEXT',
+      fontName: { family: 'Inter', style: 'Regular' },
+      characters: 'old',
+    };
+    const loadFontAsync = vi.fn<() => Promise<void>>(async () => {});
+    const handler = createSetTextHandler(fakeFigma({ '1:1': node }, loadFontAsync));
+    const result = (await handler({ nodeId: '1:1', characters: 'new' })) as MutateResult;
+
+    expect(loadFontAsync).toHaveBeenCalledWith({ family: 'Inter', style: 'Regular' });
+    expect(node.characters).toBe('new');
+    expect(result).toEqual({ ok: true, nodeId: '1:1' });
+  });
+
+  it('loads every font for mixed-font text before mutating', async () => {
+    const fonts = [
+      { family: 'Inter', style: 'Regular' },
+      { family: 'Inter', style: 'Bold' },
+    ];
+    const node = {
+      id: '1:2',
+      type: 'TEXT',
+      fontName: MIXED,
+      characters: 'ab',
+      getRangeAllFontNames: () => fonts,
+    };
+    const loadFontAsync = vi.fn<() => Promise<void>>(async () => {});
+    const handler = createSetTextHandler(fakeFigma({ '1:2': node }, loadFontAsync));
+    await handler({ nodeId: '1:2', characters: 'cd' });
+
+    expect(loadFontAsync).toHaveBeenCalledTimes(2);
+    expect(node.characters).toBe('cd');
+  });
+
+  it('throws for non-TEXT nodes and bad input', async () => {
+    const handler = createSetTextHandler(
+      fakeFigma({ '1:1': { id: '1:1', type: 'RECTANGLE' } }),
+    );
+    await expect(handler({ nodeId: '1:1', characters: 'x' })).rejects.toThrow(/TEXT/);
+    await expect(handler({ nodeId: '1:1' })).rejects.toThrow(/characters/);
+  });
+});