feat(m2): add prototype + component-nav write tools (48/52)

set_reactions (setReactionsAsync; convert.ts gains toFigmaReaction, a permissive
pass-through meant for round-tripping get_reactions), remove_reactions (clears via
empty array). swap_component (componentKey via importComponentByKeyAsync, or a
local componentId) and detach_instance (returns the new frame).

397 tests pass (+9); typecheck / oxlint / plugin+server build all green. Verified
by unit tests only — real-Figma smoke deferred to the end-of-M2 one-shot pass.
PLAN.md M2 section synced.

Author: awdr74100

packages/plugin/src/code.ts

@@ -21,6 +21,7 @@ import { createDeleteNodesHandler } from './handlers/delete-nodes.js';
 import { createDeletePageHandler } from './handlers/delete-page.js';
 import { createDeleteStyleHandler } from './handlers/delete-style.js';
 import { createDeleteVariableHandler } from './handlers/delete-variable.js';
+import { createDetachInstanceHandler } from './handlers/detach-instance.js';
 import { createFindReplaceTextHandler } from './handlers/find-replace-text.js';
 import { createGroupNodesHandler } from './handlers/group-nodes.js';
 import { createNavigateToPageHandler } from './handlers/navigate-to-page.js';
@@ -46,6 +47,7 @@ import { createScanTextNodesHandler } from './handlers/scan-text-nodes.js';
 import { createSearchNodesHandler } from './handlers/search-nodes.js';
 import { createSetLockedHandler } from './handlers/lock-nodes.js';
 import { createMoveNodesHandler } from './handlers/move-nodes.js';
+import { createRemoveReactionsHandler } from './handlers/remove-reactions.js';
 import { createRenameNodeHandler } from './handlers/rename-node.js';
 import { createRenamePageHandler } from './handlers/rename-page.js';
 import { createReorderNodesHandler } from './handlers/reorder-nodes.js';
@@ -57,12 +59,14 @@ import { createSetBlendModeHandler } from './handlers/set-blend-mode.js';
 import { createSetConstraintsHandler } from './handlers/set-constraints.js';
 import { createSetCornerRadiusHandler } from './handlers/set-corner-radius.js';
 import { createSetEffectsHandler } from './handlers/set-effects.js';
+import { createSetReactionsHandler } from './handlers/set-reactions.js';
 import { createSetFillsHandler } from './handlers/set-fills.js';
 import { createSetOpacityHandler } from './handlers/set-opacity.js';
 import { createSetStrokesHandler } from './handlers/set-strokes.js';
 import { createSetTextHandler } from './handlers/set-text.js';
 import { createSetVariableValueHandler } from './handlers/set-variable-value.js';
 import { createSetVisibleHandler } from './handlers/set-visible.js';
+import { createSwapComponentHandler } from './handlers/swap-component.js';
 import { createUngroupNodesHandler } from './handlers/ungroup-nodes.js';
 import { createUpdatePaintStyleHandler } from './handlers/update-paint-style.js';
 
@@ -166,6 +170,11 @@ const handlers: SandboxHandlers = {
   delete_page: idempotent(idempotencyCache, createDeletePageHandler(figma)),
   rename_page: idempotent(idempotencyCache, createRenamePageHandler(figma)),
   navigate_to_page: idempotent(idempotencyCache, createNavigateToPageHandler(figma)),
+  // Prototype + components
+  set_reactions: idempotent(idempotencyCache, createSetReactionsHandler(figma)),
+  remove_reactions: idempotent(idempotencyCache, createRemoveReactionsHandler(figma)),
+  swap_component: idempotent(idempotencyCache, createSwapComponentHandler(figma)),
+  detach_instance: idempotent(idempotencyCache, createDetachInstanceHandler(figma)),
 };
 
 figma.ui.onmessage = (raw: unknown) => {

packages/plugin/src/handlers/convert.ts

@@ -1,7 +1,10 @@
 import type {
+  SerializedAction,
   SerializedEffect,
   SerializedLayoutGrid,
   SerializedLineHeight,
+  SerializedReaction,
+  SerializedTrigger,
   SerializedVariableValue,
 } from '@figma-mcp-relay/shared';
 
@@ -66,3 +69,26 @@ export const toFigmaVariableValue = (value: SerializedVariableValue): VariableVa
   }
   return value;
 };
+
+// Reactions: the Figma Action/Trigger types are strict discriminated unions, so we pass through the
+// fields we serialized and cast — set_reactions is meant for round-tripping get_reactions output.
+const toFigmaTrigger = (t: SerializedTrigger | null): Trigger | null => {
+  if (t === null) return null;
+  const out: Record<string, unknown> = { type: t.type };
+  if (t.timeout !== undefined) out.timeout = t.timeout;
+  if (t.delay !== undefined) out.delay = t.delay;
+  return out as unknown as Trigger;
+};
+
+const toFigmaAction = (a: SerializedAction): Action => {
+  const out: Record<string, unknown> = { type: a.type };
+  if (a.destinationId !== undefined) out.destinationId = a.destinationId;
+  if (a.navigation !== undefined) out.navigation = a.navigation;
+  if (a.url !== undefined) out.url = a.url;
+  if (a.transition !== undefined) out.transition = a.transition;
+  return out as unknown as Action;
+};
+
+/** Wire reaction → Figma Reaction (modern `actions` array form). */
+export const toFigmaReaction = (r: SerializedReaction): Reaction =>
+  ({ trigger: toFigmaTrigger(r.trigger), actions: r.actions.map(toFigmaAction) }) as unknown as Reaction;

packages/plugin/src/handlers/detach-instance.ts

@@ -0,0 +1,22 @@
+import type { CreateResult } from '@figma-mcp-relay/shared';
+
+import type { SandboxToolHandler } from '../dispatcher.js';
+
+/** Detach an instance into a plain frame. Returns the resulting frame's id / name / type. */
+export const createDetachInstanceHandler =
+  (figmaCtx: typeof figma): SandboxToolHandler =>
+  async params => {
+    const p = (params ?? {}) as { instanceId?: unknown };
+    if (typeof p.instanceId !== 'string') {
+      throw new TypeError('detach_instance: instanceId must be a string');
+    }
+
+    const instance = await figmaCtx.getNodeByIdAsync(p.instanceId);
+    if (instance === null || instance.type !== 'INSTANCE') {
+      throw new Error(`detach_instance: node ${p.instanceId} is not an INSTANCE`);
+    }
+    const frame = (instance as InstanceNode).detachInstance();
+
+    const result: CreateResult = { ok: true, nodeId: frame.id, name: frame.name, type: frame.type };
+    return result;
+  };

packages/plugin/src/handlers/remove-reactions.ts

@@ -0,0 +1,20 @@
+import type { MutateResult } from '@figma-mcp-relay/shared';
+
+import type { SandboxToolHandler } from '../dispatcher.js';
+
+/** Clear all prototype reactions from a node. */
+export const createRemoveReactionsHandler =
+  (figmaCtx: typeof figma): SandboxToolHandler =>
+  async params => {
+    const p = (params ?? {}) as { nodeId?: unknown };
+    if (typeof p.nodeId !== 'string') throw new TypeError('remove_reactions: nodeId must be a string');
+
+    const node = await figmaCtx.getNodeByIdAsync(p.nodeId);
+    if (node === null || typeof (node as { setReactionsAsync?: unknown }).setReactionsAsync !== 'function') {
+      throw new Error(`remove_reactions: node ${p.nodeId} not found or cannot have reactions`);
+    }
+    await (node as ReactionMixin).setReactionsAsync([]);
+
+    const result: MutateResult = { ok: true, nodeId: node.id };
+    return result;
+  };

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

@@ -0,0 +1,24 @@
+import type { MutateResult, SerializedReaction } from '@figma-mcp-relay/shared';
+
+import type { SandboxToolHandler } from '../dispatcher.js';
+import { toFigmaReaction } from './convert.js';
+
+/** Replace a node's prototype reactions. Uses setReactionsAsync (required under dynamic-page). */
+export const createSetReactionsHandler =
+  (figmaCtx: typeof figma): SandboxToolHandler =>
+  async params => {
+    const p = (params ?? {}) as { nodeId?: unknown; reactions?: unknown };
+    if (typeof p.nodeId !== 'string') throw new TypeError('set_reactions: nodeId must be a string');
+    if (!Array.isArray(p.reactions)) throw new TypeError('set_reactions: reactions must be an array');
+
+    const node = await figmaCtx.getNodeByIdAsync(p.nodeId);
+    if (node === null || typeof (node as { setReactionsAsync?: unknown }).setReactionsAsync !== 'function') {
+      throw new Error(`set_reactions: node ${p.nodeId} not found or cannot have reactions`);
+    }
+    await (node as ReactionMixin).setReactionsAsync(
+      (p.reactions as SerializedReaction[]).map(toFigmaReaction),
+    );
+
+    const result: MutateResult = { ok: true, nodeId: node.id };
+    return result;
+  };

packages/plugin/src/handlers/swap-component.ts

@@ -0,0 +1,39 @@
+import type { MutateResult } from '@figma-mcp-relay/shared';
+
+import type { SandboxToolHandler } from '../dispatcher.js';
+
+/**
+ * Swap an instance's main component. Provide a published `componentKey` (imported via the API) or a
+ * local `componentId`. Returns the (unchanged) instance id.
+ */
+export const createSwapComponentHandler =
+  (figmaCtx: typeof figma): SandboxToolHandler =>
+  async params => {
+    const p = (params ?? {}) as { instanceId?: unknown; componentId?: unknown; componentKey?: unknown };
+    if (typeof p.instanceId !== 'string') {
+      throw new TypeError('swap_component: instanceId must be a string');
+    }
+    if (typeof p.componentId !== 'string' && typeof p.componentKey !== 'string') {
+      throw new TypeError('swap_component: provide componentId or componentKey');
+    }
+
+    const instance = await figmaCtx.getNodeByIdAsync(p.instanceId);
+    if (instance === null || instance.type !== 'INSTANCE') {
+      throw new Error(`swap_component: node ${p.instanceId} is not an INSTANCE`);
+    }
+
+    let component: ComponentNode;
+    if (typeof p.componentKey === 'string') {
+      component = await figmaCtx.importComponentByKeyAsync(p.componentKey);
+    } else {
+      const node = await figmaCtx.getNodeByIdAsync(p.componentId as string);
+      if (node === null || node.type !== 'COMPONENT') {
+        throw new Error(`swap_component: component ${String(p.componentId)} not found`);
+      }
+      component = node as ComponentNode;
+    }
+    (instance as InstanceNode).swapComponent(component);
+
+    const result: MutateResult = { ok: true, nodeId: instance.id };
+    return result;
+  };

packages/plugin/test/handlers/detach-instance.test.ts

@@ -0,0 +1,27 @@
+import type { CreateResult } from '@figma-mcp-relay/shared';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createDetachInstanceHandler } from '../../src/handlers/detach-instance.js';
+
+const withNode = (node: unknown): typeof figma =>
+  ({ getNodeByIdAsync: async () => node }) as unknown as typeof figma;
+
+describe('detach_instance handler', () => {
+  it('detaches an instance and returns the resulting frame', async () => {
+    const frame = { id: 'F:1', name: 'Card', type: 'FRAME' };
+    const detachInstance = vi.fn<() => typeof frame>(() => frame);
+    const instance = { id: '1:1', type: 'INSTANCE', detachInstance };
+    const f = { getNodeByIdAsync: async () => instance } as unknown as typeof figma;
+
+    const result = (await createDetachInstanceHandler(f)({ instanceId: '1:1' })) as CreateResult;
+    expect(detachInstance).toHaveBeenCalledOnce();
+    expect(result).toEqual({ ok: true, nodeId: 'F:1', name: 'Card', type: 'FRAME' });
+  });
+
+  it('throws on bad input or non-instance', async () => {
+    await expect(createDetachInstanceHandler(withNode({}))({})).rejects.toThrow(/instanceId/);
+    await expect(
+      createDetachInstanceHandler(withNode({ id: '1:1', type: 'FRAME' }))({ instanceId: '1:1' }),
+    ).rejects.toThrow(/not an INSTANCE/);
+  });
+});

packages/plugin/test/handlers/remove-reactions.test.ts

@@ -0,0 +1,27 @@
+import type { MutateResult } from '@figma-mcp-relay/shared';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createRemoveReactionsHandler } from '../../src/handlers/remove-reactions.js';
+
+const withNode = (node: unknown): typeof figma =>
+  ({ getNodeByIdAsync: async () => node }) as unknown as typeof figma;
+
+describe('remove_reactions handler', () => {
+  it('clears reactions by setting an empty array', async () => {
+    const setReactionsAsync = vi.fn<() => Promise<void>>(async () => {});
+    const node = { id: '1:1', setReactionsAsync };
+
+    const result = (await createRemoveReactionsHandler(withNode(node))({
+      nodeId: '1:1',
+    })) as MutateResult;
+    expect(setReactionsAsync).toHaveBeenCalledWith([]);
+    expect(result).toEqual({ ok: true, nodeId: '1:1' });
+  });
+
+  it('throws on bad input or unsupported node', async () => {
+    await expect(createRemoveReactionsHandler(withNode({}))({})).rejects.toThrow(/nodeId/);
+    await expect(
+      createRemoveReactionsHandler(withNode({ id: '1:1' }))({ nodeId: '1:1' }),
+    ).rejects.toThrow(/cannot have reactions/);
+  });
+});

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

@@ -0,0 +1,43 @@
+import type { MutateResult } from '@figma-mcp-relay/shared';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createSetReactionsHandler } from '../../src/handlers/set-reactions.js';
+
+const withNode = (node: unknown): typeof figma =>
+  ({ getNodeByIdAsync: async () => node }) as unknown as typeof figma;
+
+describe('set_reactions handler', () => {
+  it('converts and applies reactions via setReactionsAsync', async () => {
+    const setReactionsAsync = vi.fn<() => Promise<void>>(async () => {});
+    const node = { id: '1:1', setReactionsAsync };
+    const f = { getNodeByIdAsync: async () => node } as unknown as typeof figma;
+
+    const result = (await createSetReactionsHandler(f)({
+      nodeId: '1:1',
+      reactions: [
+        {
+          trigger: { type: 'ON_CLICK' },
+          actions: [{ type: 'NODE', destinationId: '2:2', navigation: 'NAVIGATE' }],
+        },
+      ],
+    })) as MutateResult;
+
+    expect(setReactionsAsync).toHaveBeenCalledWith([
+      {
+        trigger: { type: 'ON_CLICK' },
+        actions: [{ type: 'NODE', destinationId: '2:2', navigation: 'NAVIGATE' }],
+      },
+    ]);
+    expect(result).toEqual({ ok: true, nodeId: '1:1' });
+  });
+
+  it('throws on bad input or unsupported node', async () => {
+    await expect(createSetReactionsHandler(withNode({}))({ reactions: [] })).rejects.toThrow(/nodeId/);
+    await expect(
+      createSetReactionsHandler(withNode({}))({ nodeId: '1:1', reactions: 'x' }),
+    ).rejects.toThrow(/reactions/);
+    await expect(
+      createSetReactionsHandler(withNode({ id: '1:1' }))({ nodeId: '1:1', reactions: [] }),
+    ).rejects.toThrow(/cannot have reactions/);
+  });
+});

packages/plugin/test/handlers/swap-component.test.ts

@@ -0,0 +1,56 @@
+import type { MutateResult } from '@figma-mcp-relay/shared';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createSwapComponentHandler } from '../../src/handlers/swap-component.js';
+
+const withNode = (node: unknown): typeof figma =>
+  ({ getNodeByIdAsync: async () => node }) as unknown as typeof figma;
+
+describe('swap_component handler', () => {
+  it('swaps using a local componentId', async () => {
+    const swapComponent = vi.fn<() => void>();
+    const instance = { id: '1:1', type: 'INSTANCE', swapComponent };
+    const component = { id: 'C:1', type: 'COMPONENT' };
+    const lookup: Record<string, unknown> = { '1:1': instance, 'C:1': component };
+    const f = {
+      getNodeByIdAsync: async (id: string) => lookup[id] ?? null,
+    } as unknown as typeof figma;
+
+    const result = (await createSwapComponentHandler(f)({
+      instanceId: '1:1',
+      componentId: 'C:1',
+    })) as MutateResult;
+    expect(swapComponent).toHaveBeenCalledWith(component);
+    expect(result).toEqual({ ok: true, nodeId: '1:1' });
+  });
+
+  it('swaps using a published componentKey', async () => {
+    const swapComponent = vi.fn<() => void>();
+    const instance = { id: '1:1', type: 'INSTANCE', swapComponent };
+    const imported = { id: 'C:9', type: 'COMPONENT' };
+    const importComponentByKeyAsync = vi.fn<() => Promise<unknown>>(async () => imported);
+    const f = {
+      getNodeByIdAsync: async () => instance,
+      importComponentByKeyAsync,
+    } as unknown as typeof figma;
+
+    await createSwapComponentHandler(f)({ instanceId: '1:1', componentKey: 'abc123' });
+    expect(importComponentByKeyAsync).toHaveBeenCalledWith('abc123');
+    expect(swapComponent).toHaveBeenCalledWith(imported);
+  });
+
+  it('throws on bad input or non-instance', async () => {
+    await expect(createSwapComponentHandler(withNode({}))({ componentId: 'C:1' })).rejects.toThrow(
+      /instanceId/,
+    );
+    await expect(createSwapComponentHandler(withNode({}))({ instanceId: '1:1' })).rejects.toThrow(
+      /componentId or componentKey/,
+    );
+    await expect(
+      createSwapComponentHandler(withNode({ id: '1:1', type: 'FRAME' }))({
+        instanceId: '1:1',
+        componentId: 'C:1',
+      }),
+    ).rejects.toThrow(/not an INSTANCE/);
+  });
+});