pmx-canvas 0.1.35 → 0.2.0

package/src/server/operations/ops/viewport.ts

@@ -0,0 +1,219 @@
+/**
+ * Slice 2 operations (plan-005): arrange / node.focus / view.fit /
+ * canvas.clear.
+ *
+ * Event notes (matching the legacy handlers exactly):
+ * - arrange: arrangeCanvasNodes records its own compound history entry; the
+ *   registry emits the single canvas-layout-update (mutates: true).
+ * - node.focus: emits ax-state-changed, canvas-focus-node, and (when panning)
+ *   canvas-viewport-update via ctx.emit; the registry appends the final
+ *   canvas-layout-update.
+ * - view.fit: mutates: false with a manual canvas-viewport-update emit.
+ *
+ * This module must never import server.ts or index.ts.
+ */
+import { z } from 'zod';
+import { canvasState } from '../../canvas-state.js';
+import {
+  arrangeCanvasNodes,
+  clearCanvas,
+  fitCanvasView,
+} from '../../canvas-operations.js';
+import { validateCanvasLayout } from '../../canvas-validation.js';
+import { defineOperation, OperationError, type Operation } from '../types.js';
+import { closeNodeAppSession, isRecord } from './nodes.js';
+
+// ── arrange ───────────────────────────────────────────────────
+
+const arrangeShape = {
+  layout: z.unknown().optional().describe('Arrangement layout: grid (default), column, or flow'),
+};
+
+const arrangeSchema = z.looseObject(arrangeShape);
+
+const arrangeOperation = defineOperation<z.infer<typeof arrangeSchema>, Record<string, unknown>>({
+  name: 'arrange',
+  mutates: true,
+  input: arrangeSchema,
+  inputShape: arrangeShape,
+  http: {
+    method: 'POST',
+    path: '/api/canvas/arrange',
+  },
+  mcp: {
+    toolName: 'canvas_arrange',
+    description: 'Auto-arrange all nodes on the canvas. Layouts: grid (default), column (vertical stack), flow (horizontal row).',
+    extraShape: {
+      layout: z.enum(['grid', 'column', 'flow']).optional().describe('Arrangement layout (default: grid)'),
+    },
+    // Legacy tool reported { ok: true, layout } regardless of the arrange
+    // result (it ignored the arranged count and validation outcome).
+    formatResult: (result, input) => ({
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify({ ok: true, layout: typeof input.layout === 'string' ? input.layout : 'grid' }),
+      }],
+    }),
+  },
+  handler: (input) => {
+    const layout = typeof input.layout === 'string' ? input.layout : 'grid';
+    if (!['grid', 'column', 'flow'].includes(layout)) {
+      throw new OperationError(`Invalid layout: "${layout}". Use: grid, column, flow`);
+    }
+    // arrangeCanvasNodes records its own single compound history entry —
+    // nothing else here may record (no double-record).
+    const result = arrangeCanvasNodes(layout as 'grid' | 'column' | 'flow');
+    const validation = validateCanvasLayout(canvasState.getLayout());
+    return {
+      ok: validation.ok,
+      arranged: result.arranged,
+      layout: result.layout,
+      ...(validation.ok ? {} : { validation, collisions: validation.summary.collisions }),
+    };
+  },
+});
+
+// ── node.focus ────────────────────────────────────────────────
+
+const focusShape = {
+  id: z.unknown().optional().describe('Node ID to focus on'),
+  noPan: z.unknown().optional().describe('If true, raise/select the node without panning the viewport. Default false.'),
+};
+
+const focusSchema = z.looseObject(focusShape);
+
+const focusOperation = defineOperation<z.infer<typeof focusSchema>, Record<string, unknown>>({
+  name: 'node.focus',
+  mutates: true,
+  input: focusSchema,
+  inputShape: focusShape,
+  http: {
+    method: 'POST',
+    path: '/api/canvas/focus',
+  },
+  mcp: {
+    toolName: 'canvas_focus_node',
+    description: 'Bring a node into focus. By default the viewport pans so the node is centered. Pass noPan=true to raise/select the node without moving the human\'s camera (useful when reacting to background events without disrupting the human\'s current view).',
+    extraShape: {
+      id: z.string().describe('Node ID to focus on'),
+      noPan: z
+        .boolean()
+        .optional()
+        .describe('If true, raise/select the node without panning the viewport. Default false.'),
+    },
+    formatResult: (result) => {
+      const body = isRecord(result) ? result : {};
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify({ ok: true, focused: body.focused, panned: body.panned }),
+        }],
+      };
+    },
+  },
+  handler: (input, ctx) => {
+    const body: Record<string, unknown> = input;
+    const nodeId = typeof body.id === 'string' ? body.id : '';
+    if (!nodeId) throw new OperationError('Missing id.');
+    const node = canvasState.getNode(nodeId);
+    if (!node) throw new OperationError(`Node "${nodeId}" not found.`, 404);
+    const noPan = body.noPan === true;
+    if (!noPan) {
+      canvasState.setViewport({ x: node.position.x - 100, y: node.position.y - 100 });
+    } else {
+      const maxZ = canvasState.getLayout().nodes.reduce((max, layoutNode) => Math.max(max, layoutNode.zIndex), 0);
+      canvasState.updateNode(nodeId, { zIndex: maxZ + 1 });
+    }
+    const focus = canvasState.setAxFocus([nodeId], { source: 'api', recordHistory: false });
+    ctx.emit('ax-state-changed', { focus });
+    ctx.emit('canvas-focus-node', { nodeId, noPan });
+    if (!noPan) ctx.emit('canvas-viewport-update', { viewport: canvasState.viewport });
+    return { ok: true, focused: nodeId, panned: !noPan, axFocus: focus };
+  },
+});
+
+// ── view.fit ──────────────────────────────────────────────────
+
+const fitShape = {
+  width: z.number().optional().catch(undefined).describe('Viewport width used for fit math (default 1440)'),
+  height: z.number().optional().catch(undefined).describe('Viewport height used for fit math (default 900)'),
+  padding: z.number().optional().catch(undefined).describe('World-space padding around fitted nodes (default 60)'),
+  maxScale: z.number().optional().catch(undefined).describe('Maximum zoom scale (default 1)'),
+  nodeIds: z.unknown().optional().describe('Optional node IDs to fit instead of the whole canvas'),
+};
+
+const fitSchema = z.looseObject(fitShape);
+
+const fitOperation = defineOperation<z.infer<typeof fitSchema>, Record<string, unknown>>({
+  name: 'view.fit',
+  mutates: false,
+  input: fitSchema,
+  inputShape: fitShape,
+  http: {
+    method: 'POST',
+    path: '/api/canvas/fit',
+  },
+  mcp: {
+    toolName: 'canvas_fit_view',
+    description: 'Fit the canvas viewport to all nodes or a selected subset. Useful before screenshots and whole-board review.',
+    extraShape: {
+      nodeIds: z.array(z.string()).optional().describe('Optional node IDs to fit instead of the whole canvas'),
+    },
+    formatResult: (result) => ({
+      content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
+    }),
+  },
+  handler: (input, ctx) => {
+    const body: Record<string, unknown> = input;
+    const nodeIds = Array.isArray(body.nodeIds)
+      ? body.nodeIds.filter((id): id is string => typeof id === 'string')
+      : undefined;
+    const result = fitCanvasView({
+      ...(typeof body.width === 'number' ? { width: body.width } : {}),
+      ...(typeof body.height === 'number' ? { height: body.height } : {}),
+      ...(typeof body.padding === 'number' ? { padding: body.padding } : {}),
+      ...(typeof body.maxScale === 'number' ? { maxScale: body.maxScale } : {}),
+      ...(nodeIds ? { nodeIds } : {}),
+    });
+    ctx.emit('canvas-viewport-update', { viewport: result.viewport });
+    return result as unknown as Record<string, unknown>;
+  },
+});
+
+// ── canvas.clear ──────────────────────────────────────────────
+
+const clearShape = {};
+
+const clearSchema = z.looseObject(clearShape);
+
+const clearOperation = defineOperation<z.infer<typeof clearSchema>, Record<string, unknown>>({
+  name: 'canvas.clear',
+  mutates: true,
+  input: clearSchema,
+  inputShape: clearShape,
+  http: {
+    method: 'POST',
+    path: '/api/canvas/clear',
+  },
+  mcp: {
+    toolName: 'canvas_clear',
+    description: 'Remove all nodes and edges from the canvas. Use with caution.',
+    formatResult: () => ({
+      content: [{ type: 'text' as const, text: JSON.stringify({ ok: true, cleared: true }) }],
+    }),
+  },
+  handler: () => {
+    for (const node of canvasState.getLayout().nodes) {
+      closeNodeAppSession(node);
+    }
+    clearCanvas();
+    return { ok: true };
+  },
+});
+
+export const viewportOperations: Operation[] = [
+  arrangeOperation,
+  focusOperation,
+  fitOperation,
+  clearOperation,
+];

package/src/server/operations/ops/webview.ts

@@ -0,0 +1,339 @@
+/**
+ * Webview (Bun.WebView automation) operations (plan-008 Wave 3).
+ *
+ * The five browser-automation tools (status / start / stop / resize / evaluate)
+ * migrate to the registry. They are SIDE-SURFACE operations: `mutates: false`
+ * (no canvas node/edge state changes, so NO canvas-layout-update frame).
+ *
+ * The automation machinery lives in `../../server.ts`, which `operations/` must
+ * NEVER import. Each handler calls the INJECTED runner (`getWebviewRunner()`);
+ * server.ts wires the real automation functions via `setWebviewRunner` at module
+ * load — the same injection pattern as `setOperationEventEmitter`.
+ *
+ * Wire + MCP result shapes are byte-identical to the legacy hand-written tools:
+ *  - status   GET    /api/workbench/webview          → raw status object
+ *  - start    POST   /api/workbench/webview/start    → { ok, webview } (+error: { ok, error, webview })
+ *  - stop     DELETE /api/workbench/webview          → { ok, stopped, webview }
+ *  - resize   POST   /api/workbench/webview/resize   → { ok, webview }
+ *  - evaluate POST   /api/workbench/webview/evaluate → { ok, value }
+ *
+ * `canvas_screenshot` is NOT migrated — it returns a binary payload and stays a
+ * standalone hand-written tool (the POST /api/workbench/webview/screenshot route
+ * also stays hand-written in server.ts).
+ *
+ * This module must never import server.ts or index.ts.
+ */
+import { resolve, relative, isAbsolute } from 'node:path';
+import { z } from 'zod';
+import { defineOperation, OperationError, type Operation } from '../types.js';
+import {
+  getWebviewRunner,
+  type WebviewStartOptions,
+  type WebviewStartResult,
+  type WebviewStatus,
+} from '../webview-runner.js';
+
+/**
+ * Resolve a workspace-relative path and reject anything escaping the workspace
+ * (mirrors the MCP server's `safeWorkspacePath`). Inlined here (pure node:path +
+ * process.cwd) so the registry op can enforce the workspace boundary without
+ * importing the MCP server. Applied in buildStartOptions for BOTH the MCP and
+ * HTTP surfaces (the legacy MCP tool sandboxed it; the HTTP route did not —
+ * unified here to the safer behavior).
+ */
+function safeWorkspacePath(pathLike: string): string {
+  const workspace = resolve(process.cwd());
+  const resolved = resolve(workspace, pathLike);
+  const rel = relative(workspace, resolved);
+  const inside = rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+  if (!inside) {
+    throw new OperationError(`Path "${pathLike}" resolves outside workspace.`);
+  }
+  return resolved;
+}
+
+/** Wrap a multi-statement script body in an async IIFE (legacy
+ * wrapCanvasAutomationScript). Inlined — it is a pure string template. */
+function wrapScript(script: string): string {
+  return `(async () => {\n${script}\n})()`;
+}
+
+/**
+ * Run an injected automation-runner call, converting a runtime failure (e.g. no
+ * active session, or a page-side eval error) into the legacy
+ * `400 { ok:false, error, webview }` contract. Without this the plain Error the
+ * runner throws would escape dispatchOperationRoute (which only maps OperationError)
+ * and surface as Bun's default 500 HTML error overlay — a wire regression that also
+ * discloses the server source path. Mirrors the legacy resize/evaluate try/catch.
+ */
+async function runWebviewTask<T>(task: () => Promise<T> | T): Promise<T> {
+  try {
+    return await task();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    let webview: WebviewStatus | undefined;
+    try { webview = getWebviewRunner().status(); } catch { /* runner not wired */ }
+    throw new OperationError(message, 400, webview ? { webview } : undefined);
+  }
+}
+
+function statusText(status: WebviewStatus): { content: [{ type: 'text'; text: string }] } {
+  return { content: [{ type: 'text' as const, text: JSON.stringify(status, null, 2) }] };
+}
+
+// ── webview.status ────────────────────────────────────────────
+
+const statusShape = {};
+const statusSchema = z.looseObject(statusShape);
+
+const statusOperation = defineOperation<z.infer<typeof statusSchema>, WebviewStatus>({
+  name: 'webview.status',
+  mutates: false,
+  input: statusSchema,
+  inputShape: statusShape,
+  http: {
+    method: 'GET',
+    path: '/api/workbench/webview',
+  },
+  mcp: {
+    toolName: 'canvas_webview_status',
+    description:
+      'Get the current Bun.WebView automation status for the PMX Canvas workbench. Returns whether Bun.WebView is supported, whether an automation session is active, backend, viewport size, and the current workbench URL if active.',
+    formatResult: (result) => statusText(result as WebviewStatus),
+  },
+  handler: () => getWebviewRunner().status(),
+});
+
+// ── webview.start ─────────────────────────────────────────────
+
+const startShape = {
+  backend: z.unknown().optional().describe('Automation backend (chrome | webkit)'),
+  width: z.unknown().optional().describe('Viewport width in pixels (default: 1280)'),
+  height: z.unknown().optional().describe('Viewport height in pixels (default: 800)'),
+  chromePath: z.unknown().optional().describe('Optional Chrome/Chromium executable path'),
+  chromeArgv: z.unknown().optional().describe('Optional extra Chrome launch args'),
+  dataStoreDir: z.unknown().optional().describe('Optional persistent data store directory'),
+};
+const startSchema = z.looseObject(startShape);
+
+function buildStartOptions(input: Record<string, unknown>): WebviewStartOptions {
+  const backend = input.backend === 'chrome' || input.backend === 'webkit' ? input.backend : undefined;
+  const width = typeof input.width === 'number' ? input.width : undefined;
+  const height = typeof input.height === 'number' ? input.height : undefined;
+  const chromePath = typeof input.chromePath === 'string' ? input.chromePath : undefined;
+  // Sandbox dataStoreDir to the workspace on BOTH surfaces. The legacy MCP tool
+  // sandboxed it (the HTTP route passed it raw — a cross-surface asymmetry);
+  // unify to the safer behavior here in the shared option builder so an
+  // out-of-workspace data store is a 400 over HTTP and MCP alike.
+  const dataStoreDir = typeof input.dataStoreDir === 'string' ? safeWorkspacePath(input.dataStoreDir) : undefined;
+  const chromeArgv = Array.isArray(input.chromeArgv)
+    ? input.chromeArgv.filter((value): value is string => typeof value === 'string')
+    : undefined;
+  return {
+    ...(backend ? { backend } : {}),
+    ...(width !== undefined ? { width } : {}),
+    ...(height !== undefined ? { height } : {}),
+    ...(chromePath ? { chromePath } : {}),
+    ...(chromeArgv ? { chromeArgv } : {}),
+    ...(dataStoreDir ? { dataStoreDir } : {}),
+  };
+}
+
+const startOperation = defineOperation<z.infer<typeof startSchema>, WebviewStartResult>({
+  name: 'webview.start',
+  mutates: false,
+  input: startSchema,
+  inputShape: startShape,
+  http: {
+    method: 'POST',
+    path: '/api/workbench/webview/start',
+    // Mirror the legacy handler status codes from the SERIALIZED wire body
+    // (`status` receives the serialized result): 200 ok; 503 server-not-running
+    // ({ ok:false, error } — no webview); else 501 when the runtime is
+    // unsupported (webview.supported === false) vs 500 for a supported failure.
+    status: (result) => {
+      const body = result as { ok?: boolean; webview?: WebviewStatus };
+      if (body.ok) return 200;
+      if (!body.webview) return 503;
+      return body.webview.supported ? 500 : 501;
+    },
+  },
+  mcp: {
+    toolName: 'canvas_webview_start',
+    description:
+      'Start or replace the headless Bun.WebView automation session for the current PMX Canvas workbench. Use this before screenshot, evaluate, or resize when no automation session is active.',
+    extraShape: {
+      backend: z.enum(['chrome', 'webkit']).optional()
+        .describe('Automation backend. Default: webkit on macOS, chrome elsewhere.'),
+      width: z.number().optional().describe('Viewport width in pixels (default: 1280)'),
+      height: z.number().optional().describe('Viewport height in pixels (default: 800)'),
+      chromePath: z.string().optional().describe('Optional Chrome/Chromium executable path'),
+      chromeArgv: z.array(z.string()).optional().describe('Optional extra Chrome launch args'),
+      dataStoreDir: z.string().optional().describe('Optional persistent data store directory'),
+    },
+    // dataStoreDir is sandboxed to the workspace in buildStartOptions (both the
+    // MCP and HTTP surfaces), so no MCP-only buildInput is needed.
+    // formatResult receives the SERIALIZED wire body. Legacy
+    // canvas_webview_start: on success JSON-stringifies the webview status; on
+    // failure surfaces a bare-message isError result.
+    formatResult: (result) => {
+      const body = result as { ok?: boolean; webview?: WebviewStatus; error?: string };
+      if (body.ok && body.webview) return statusText(body.webview);
+      return {
+        content: [{ type: 'text' as const, text: body.error ?? 'WebView start failed.' }],
+        isError: true,
+      };
+    },
+  },
+  handler: (input) => getWebviewRunner().start(buildStartOptions(input)),
+  serialize: (output) => {
+    // HTTP wire body: { ok, webview } on success; { ok:false, error } (503,
+    // no webview) when the server is not running; { ok:false, error, webview }
+    // otherwise — byte-identical to the legacy handler bodies.
+    if (output.ok) return { ok: true, webview: output.webview };
+    if (output.serverNotRunning) return { ok: false, error: output.error };
+    return { ok: false, error: output.error, webview: output.webview };
+  },
+});
+
+// ── webview.stop ──────────────────────────────────────────────
+
+const stopShape = {};
+const stopSchema = z.looseObject(stopShape);
+
+const stopOperation = defineOperation<z.infer<typeof stopSchema>, { stopped: boolean; webview: WebviewStatus }>({
+  name: 'webview.stop',
+  mutates: false,
+  input: stopSchema,
+  inputShape: stopShape,
+  http: {
+    method: 'DELETE',
+    path: '/api/workbench/webview',
+  },
+  mcp: {
+    toolName: 'canvas_webview_stop',
+    description: 'Stop the current Bun.WebView automation session if one is active.',
+    // formatResult receives the SERIALIZED wire body { ok, stopped, webview }.
+    formatResult: (result) => {
+      const body = result as { ok: boolean; stopped: boolean; webview: WebviewStatus };
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify({ ok: true, stopped: body.stopped, webview: body.webview }, null, 2),
+        }],
+      };
+    },
+  },
+  handler: async () => {
+    const runner = getWebviewRunner();
+    const stopped = await runner.stop();
+    return { stopped, webview: runner.status() };
+  },
+  serialize: (output) => ({ ok: true, stopped: output.stopped, webview: output.webview }),
+});
+
+// ── webview.resize ────────────────────────────────────────────
+
+const resizeShape = {
+  width: z.unknown().optional().describe('Viewport width in pixels'),
+  height: z.unknown().optional().describe('Viewport height in pixels'),
+};
+const resizeSchema = z.looseObject(resizeShape);
+
+const resizeOperation = defineOperation<z.infer<typeof resizeSchema>, WebviewStatus>({
+  name: 'webview.resize',
+  mutates: false,
+  input: resizeSchema,
+  inputShape: resizeShape,
+  http: {
+    method: 'POST',
+    path: '/api/workbench/webview/resize',
+  },
+  mcp: {
+    toolName: 'canvas_resize',
+    description: 'Resize the active Bun.WebView automation viewport. Requires an active automation session started via canvas_webview_start.',
+    extraShape: {
+      width: z.number().describe('Viewport width in pixels'),
+      height: z.number().describe('Viewport height in pixels'),
+    },
+    // formatResult receives the SERIALIZED wire body { ok, webview }; legacy
+    // canvas_resize JSON-stringifies just the webview status.
+    formatResult: (result) => statusText((result as { webview: WebviewStatus }).webview),
+  },
+  handler: async (input) => {
+    const width = typeof input.width === 'number' ? input.width : NaN;
+    const height = typeof input.height === 'number' ? input.height : NaN;
+    if (!Number.isFinite(width) || width <= 0 || !Number.isFinite(height) || height <= 0) {
+      throw new OperationError('Missing required positive numeric fields: width, height.');
+    }
+    return runWebviewTask(() => getWebviewRunner().resize(width, height));
+  },
+  // HTTP wire body matches the legacy handler: { ok:true, webview }.
+  serialize: (output) => ({ ok: true, webview: output }),
+});
+
+// ── webview.evaluate ──────────────────────────────────────────
+
+const evaluateShape = {
+  expression: z.unknown().optional().describe('JavaScript expression to evaluate in the page context'),
+  script: z.unknown().optional().describe('Multi-statement JavaScript body. The MCP server wraps it in an async IIFE and evaluates the resolved return value.'),
+};
+const evaluateSchema = z.looseObject(evaluateShape);
+
+const evaluateOperation = defineOperation<z.infer<typeof evaluateSchema>, { value: unknown }>({
+  name: 'webview.evaluate',
+  mutates: false,
+  input: evaluateSchema,
+  inputShape: evaluateShape,
+  http: {
+    method: 'POST',
+    path: '/api/workbench/webview/evaluate',
+  },
+  mcp: {
+    toolName: 'canvas_evaluate',
+    description: 'Evaluate JavaScript in the active Bun.WebView automation session for the workbench page. Use this to inspect rendered browser state. Requires an active automation session started via canvas_webview_start.',
+    extraShape: {
+      expression: z.string().optional().describe('JavaScript expression to evaluate in the page context'),
+      script: z.string().optional().describe('Multi-statement JavaScript body. The MCP server wraps it in an async IIFE and evaluates the resolved return value.'),
+    },
+    // Legacy canvas_evaluate validation: exactly one of expression/script (its
+    // own message). Validate here so the MCP tool throws the legacy message
+    // before dispatch; the handler re-validates with the HTTP-style message for
+    // the remote path.
+    buildInput: (input) => {
+      const hasExpression = typeof input.expression === 'string' && input.expression.length > 0;
+      const hasScript = typeof input.script === 'string' && input.script.length > 0;
+      if ((hasExpression ? 1 : 0) + (hasScript ? 1 : 0) !== 1) {
+        throw new OperationError('Pass exactly one of "expression" or "script".');
+      }
+      return input;
+    },
+    // Legacy canvas_evaluate JSON-stringifies { value }.
+    formatResult: (result) => {
+      const r = result as { value: unknown };
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ value: r.value }, null, 2) }] };
+    },
+  },
+  handler: async (input) => {
+    const expression = typeof input.expression === 'string' ? input.expression.trim() : '';
+    const script = typeof input.script === 'string' ? input.script.trim() : '';
+    if ((expression ? 1 : 0) + (script ? 1 : 0) !== 1) {
+      throw new OperationError(
+        'Pass exactly one of "expression" (single JS expression) or "script" (multi-statement body, wrapped in an async IIFE).',
+      );
+    }
+    const source = script ? wrapScript(script) : expression;
+    const value = await runWebviewTask(() => getWebviewRunner().evaluate(source));
+    return { value };
+  },
+  // HTTP wire body matches the legacy handler: { ok:true, value }.
+  serialize: (output) => ({ ok: true, value: output.value }),
+});
+
+export const webviewOperations: Operation[] = [
+  statusOperation,
+  startOperation,
+  stopOperation,
+  resizeOperation,
+  evaluateOperation,
+];

package/src/server/operations/registry.ts

@@ -0,0 +1,79 @@
+/**
+ * Operation registry: register/get/list plus the ONE execution path
+ * (`executeOperation`: validate → run → emit) shared by HTTP, MCP, and CLI.
+ *
+ * SSE wiring: server.ts injects the workbench event emitter via
+ * `setOperationEventEmitter` (same pattern as `setCanvasLayoutUpdateEmitter`).
+ * Handlers never emit `canvas-layout-update` themselves for the final state —
+ * `mutates: true` is the single source; extra events go through `ctx.emit`.
+ */
+import { canvasState } from '../canvas-state.js';
+import { OperationError, type Operation, type OperationContext } from './types.js';
+
+const operations = new Map<string, Operation>();
+
+export function registerOperation(op: Operation): void {
+  if (operations.has(op.name)) {
+    throw new Error(`Operation "${op.name}" is already registered.`);
+  }
+  operations.set(op.name, op);
+}
+
+export function getOperation(name: string): Operation {
+  const op = operations.get(name);
+  if (!op) throw new OperationError(`Unknown operation "${name}".`, 400);
+  return op;
+}
+
+export function listOperations(): Operation[] {
+  return [...operations.values()];
+}
+
+type OperationEventEmitter = (event: string, payload: Record<string, unknown>) => void;
+
+let operationEventEmitter: OperationEventEmitter | null = null;
+
+export function setOperationEventEmitter(emitter: OperationEventEmitter | null): void {
+  operationEventEmitter = emitter;
+}
+
+// Depth-counted emit suppression (mirrors canvasState._suppressRecordingDepth).
+// While > 0, emitOperationEvent is a no-op so a meta-op (canvas.batch) can run
+// many sub-ops without producing per-entry SSE frames, then emit ONE final
+// layout frame itself. Both the `mutates` auto-emit and `ctx.emit` route through
+// emitOperationEvent, so this covers both. Re-entrant-safe via the depth counter.
+let suppressEmitDepth = 0;
+
+function emitOperationEvent(event: string, payload: Record<string, unknown> = {}): void {
+  if (suppressEmitDepth > 0) return;
+  operationEventEmitter?.(event, payload);
+}
+
+/** True while operation SSE emits are being suppressed (inside a meta-op such as
+ * canvas.batch). Ops whose effect depends on a live SSE emit firing — e.g.
+ * mcpapp.open, whose canvas node is created as a side-effect of `ext-app-open` —
+ * use this to reject loudly instead of silently no-op'ing in a suppressed run. */
+export function isEmitSuppressed(): boolean {
+  return suppressEmitDepth > 0;
+}
+
+/** Run `fn` with all operation SSE emits suppressed; restores depth on finally. */
+export async function runWithSuppressedEmits<T>(fn: () => Promise<T>): Promise<T> {
+  suppressEmitDepth++;
+  try {
+    return await fn();
+  } finally {
+    suppressEmitDepth--;
+  }
+}
+
+const operationContext: OperationContext = { emit: emitOperationEvent };
+
+export async function executeOperation(name: string, rawInput: unknown): Promise<unknown> {
+  const op = getOperation(name);
+  const result = await op.execute(rawInput, operationContext);
+  if (op.mutates) {
+    emitOperationEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+  }
+  return result;
+}