pmx-canvas 0.3.0 → 0.3.2

package/src/server/intent-registry.ts

@@ -124,7 +124,7 @@ export class IntentRegistry {
 
     const now = Date.now();
     const ttl = typeof input.ttlMs === 'number' ? input.ttlMs : DEFAULT_INTENT_TTL_MS;
-    const id = input.id && this.intents.has(input.id) ? input.id : input.id ?? nextIntentId();
+    const id = input.id && this.intents.has(input.id) ? input.id : (input.id ?? nextIntentId());
     this.pruneVetoTombstones();
     if (this.vetoedIntentIds.has(id)) {
       throw new OperationError(`Intent "${id}" was vetoed. Use a new id for a revised intent.`, 409);
@@ -234,10 +234,7 @@ export class IntentRegistry {
       throw new OperationError(`No live intent "${id}" to commit.`, 409);
     }
     if (!allowedKinds.includes(intent.kind)) {
-      throw new OperationError(
-        `Intent "${id}" has kind "${intent.kind}", which cannot commit this mutation.`,
-        409,
-      );
+      throw new OperationError(`Intent "${id}" has kind "${intent.kind}", which cannot commit this mutation.`, 409);
     }
     this.committingIntentIds.add(id);
     return intent;

package/src/server/mcp-app-candidate.ts

@@ -134,16 +134,12 @@ function toSafeExternalUrl(url: string): string | null {
   return parsed.toString();
 }
 
-export function getMcpAppCandidateFromToolCompletion(
-  data: McpAppToolCompletionInput,
-): McpAppToolCandidate | null {
+export function getMcpAppCandidateFromToolCompletion(data: McpAppToolCompletionInput): McpAppToolCandidate | null {
   const inlineUrls = [
     ...(typeof data.content === 'string' ? [data.content] : []),
     ...(typeof data.detailedContent === 'string' ? [data.detailedContent] : []),
     ...collectToolResultTextFragments(data.result),
-  ].flatMap((value) =>
-    (value.match(/https?:\/\/[^\s<>"'`]+/gi) ?? []).map((url) => ({ url, keyHint: 'inline' })),
-  );
+  ].flatMap((value) => (value.match(/https?:\/\/[^\s<>"'`]+/gi) ?? []).map((url) => ({ url, keyHint: 'inline' })));
 
   const nestedUrls = collectToolResultUrlCandidates(data.result);
   const candidates = [...inlineUrls, ...nestedUrls];
@@ -156,10 +152,9 @@ export function getMcpAppCandidateFromToolCompletion(
     const safe = toSafeExternalUrl(entry.url);
     if (!safe) continue;
     const key = entry.keyHint.toLowerCase();
-    const hintedByKey =
-      /resource|resource_link|resourceurl|resource_url|app|uri|url|link|viewer|preview|canvas/.test(
-        key,
-      );
+    const hintedByKey = /resource|resource_link|resourceurl|resource_url|app|uri|url|link|viewer|preview|canvas/.test(
+      key,
+    );
     const hintedByUrl = isLikelyMcpAppWebUrl(safe);
     if (!hintedByKey && !hintedByUrl && !sourceHasMcp) continue;
     return {

package/src/server/mcp-app-host.ts

@@ -66,11 +66,7 @@ function ensureConfigDir(): void {
   }
 }
 
-const DEFAULT_MCP_APP_HOST_STATE_FILE = join(
-  PMX_CANVAS_CONFIG_DIR,
-  'workbench',
-  'mcp-app-host-state.json',
-);
+const DEFAULT_MCP_APP_HOST_STATE_FILE = join(PMX_CANVAS_CONFIG_DIR, 'workbench', 'mcp-app-host-state.json');
 
 function sessionDiagLogPath(): string {
   return String(process.env.PMX_SESSION_LOG || process.env.PMX_TEST_LOG || '').trim();
@@ -158,9 +154,7 @@ function resetRuntimeMetrics(): void {
 function clearPersistedRuntimeSessionsOnLoad(): void {
   const hadSessions = sessions.size;
   const hadMetrics =
-    metrics.hostedOpens > 0 ||
-    metrics.fallbackTotal > 0 ||
-    Object.keys(metrics.fallbackByReason).length > 0;
+    metrics.hostedOpens > 0 || metrics.fallbackTotal > 0 || Object.keys(metrics.fallbackByReason).length > 0;
   if (hadSessions === 0 && !activeSessionId && !hadMetrics) return;
 
   sessions.clear();
@@ -192,9 +186,7 @@ function ensureStateLoaded(): void {
         const normalized: McpAppHostCapability = {
           serverName: entry.serverName.trim(),
           state:
-            entry.state === 'supported' ||
-            entry.state === 'unsupported' ||
-            entry.state === 'degraded'
+            entry.state === 'supported' || entry.state === 'unsupported' || entry.state === 'degraded'
               ? entry.state
               : 'degraded',
           reasonCode:
@@ -204,9 +196,7 @@ function ensureStateLoaded(): void {
           runtimeReady: entry.runtimeReady === true,
           serverSupportsHost: entry.serverSupportsHost === true,
           updatedAt:
-            typeof entry.updatedAt === 'string' && entry.updatedAt.trim().length > 0
-              ? entry.updatedAt
-              : nowIso(),
+            typeof entry.updatedAt === 'string' && entry.updatedAt.trim().length > 0 ? entry.updatedAt : nowIso(),
         };
         capabilities.set(normalized.serverName, normalized);
       }
@@ -235,20 +225,15 @@ function ensureStateLoaded(): void {
               ? entry.state
               : 'background',
           createdAt:
-            typeof entry.createdAt === 'string' && entry.createdAt.trim().length > 0
-              ? entry.createdAt
-              : nowIso(),
+            typeof entry.createdAt === 'string' && entry.createdAt.trim().length > 0 ? entry.createdAt : nowIso(),
           lastSeenAt:
-            typeof entry.lastSeenAt === 'string' && entry.lastSeenAt.trim().length > 0
-              ? entry.lastSeenAt
-              : nowIso(),
+            typeof entry.lastSeenAt === 'string' && entry.lastSeenAt.trim().length > 0 ? entry.lastSeenAt : nowIso(),
           fallbackReason:
             typeof entry.fallbackReason === 'string' && entry.fallbackReason.trim().length > 0
               ? entry.fallbackReason
               : null,
           lastExternalOpenAt:
-            typeof entry.lastExternalOpenAt === 'string' &&
-            entry.lastExternalOpenAt.trim().length > 0
+            typeof entry.lastExternalOpenAt === 'string' && entry.lastExternalOpenAt.trim().length > 0
               ? entry.lastExternalOpenAt
               : null,
         };
@@ -268,12 +253,8 @@ function ensureStateLoaded(): void {
     if (parsed.metrics && typeof parsed.metrics === 'object') {
       const loadedHostedOpens = Number(parsed.metrics.hostedOpens ?? 0);
       const loadedFallbackTotal = Number(parsed.metrics.fallbackTotal ?? 0);
-      metrics.hostedOpens = Number.isFinite(loadedHostedOpens)
-        ? Math.max(0, Math.floor(loadedHostedOpens))
-        : 0;
-      metrics.fallbackTotal = Number.isFinite(loadedFallbackTotal)
-        ? Math.max(0, Math.floor(loadedFallbackTotal))
-        : 0;
+      metrics.hostedOpens = Number.isFinite(loadedHostedOpens) ? Math.max(0, Math.floor(loadedHostedOpens)) : 0;
+      metrics.fallbackTotal = Number.isFinite(loadedFallbackTotal) ? Math.max(0, Math.floor(loadedFallbackTotal)) : 0;
       if (parsed.metrics.fallbackByReason && typeof parsed.metrics.fallbackByReason === 'object') {
         for (const [reason, count] of Object.entries(parsed.metrics.fallbackByReason)) {
           const normalizedReason = reason.trim();
@@ -370,10 +351,9 @@ function supportsHostSessionByHint(input: McpAppCandidateInput): boolean {
   const keyHint = String(input.keyHint || '').toLowerCase();
   const inferredType = String(input.inferredType || '').toLowerCase();
 
-  const keySuggestsApps =
-    /resource|resource_link|resourceurl|resource_url|app|uri|url|link|viewer|preview|canvas/.test(
-      keyHint,
-    );
+  const keySuggestsApps = /resource|resource_link|resourceurl|resource_url|app|uri|url|link|viewer|preview|canvas/.test(
+    keyHint,
+  );
   const sourceSuggestsApps =
     sourceServer.includes('mcp') ||
     sourceServer.includes('excalidraw') ||
@@ -533,10 +513,7 @@ export function preRegisterKnownMcpAppHostCapabilities(serverNames: string[]): v
   }
 }
 
-function resolveCapabilityForCandidate(
-  input: McpAppCandidateInput,
-  trustedDomain: boolean,
-): McpAppHostCapability {
+function resolveCapabilityForCandidate(input: McpAppCandidateInput, trustedDomain: boolean): McpAppHostCapability {
   const runtimeReady = isHostRuntimeEnabled();
   const serverName = normalizeServerName(input.sourceServer);
   const serverSupportsHost = supportsHostSessionByHint(input);
@@ -645,8 +622,7 @@ function findMatchingOpenSession(input: McpAppCandidateInput): McpAppHostSession
 function registerFallback(reasonCode: string): void {
   metrics.fallbackTotal += 1;
   const normalizedReason = reasonCode.trim() || 'fallback';
-  metrics.fallbackByReason[normalizedReason] =
-    (metrics.fallbackByReason[normalizedReason] ?? 0) + 1;
+  metrics.fallbackByReason[normalizedReason] = (metrics.fallbackByReason[normalizedReason] ?? 0) + 1;
 }
 
 export function routeMcpAppCandidateToHost(input: McpAppCandidateInput): McpAppHostRoutingResult {

package/src/server/mcp-app-runtime.ts

@@ -13,15 +13,8 @@ import type {
   Tool,
 } from '@modelcontextprotocol/sdk/types.js';
 import type { RequestOptions } from '@modelcontextprotocol/sdk/shared/protocol.js';
-import {
-  EXTENSION_ID,
-  RESOURCE_MIME_TYPE,
-} from '@modelcontextprotocol/ext-apps/server';
-import type {
-  McpUiClientCapabilities,
-  McpUiResourceCsp,
-  McpUiResourceMeta,
-} from '@modelcontextprotocol/ext-apps';
+import { EXTENSION_ID, RESOURCE_MIME_TYPE } from '@modelcontextprotocol/ext-apps/server';
+import type { McpUiClientCapabilities, McpUiResourceCsp, McpUiResourceMeta } from '@modelcontextprotocol/ext-apps';
 import { getToolUiResourceUri } from '@modelcontextprotocol/ext-apps/app-bridge';
 import { normalizeExtAppToolResult } from './ext-app-tool-result.js';
 
@@ -39,9 +32,7 @@ export interface ExternalMcpStdioTransportConfig {
   env?: Record<string, string>;
 }
 
-export type ExternalMcpTransportConfig =
-  | ExternalMcpHttpTransportConfig
-  | ExternalMcpStdioTransportConfig;
+export type ExternalMcpTransportConfig = ExternalMcpHttpTransportConfig | ExternalMcpStdioTransportConfig;
 
 export interface OpenMcpAppInput {
   transport: ExternalMcpTransportConfig;
@@ -220,10 +211,7 @@ async function createSession(
   timeoutMs?: number,
 ): Promise<McpAppSession> {
   const transport = buildTransport(transportConfig);
-  const client = new Client(
-    { name: 'pmx-canvas-app-host', version: '0.1.0' },
-    { capabilities: clientCapabilities },
-  );
+  const client = new Client({ name: 'pmx-canvas-app-host', version: '0.1.0' }, { capabilities: clientCapabilities });
   await client.connect(transport, requestOptions(timeoutMs));
 
   const toolList = await client.listTools(undefined, requestOptions(timeoutMs));
@@ -369,10 +357,14 @@ export async function openMcpApp(input: OpenMcpAppInput): Promise<OpenMcpAppResu
     }
 
     const toolInput = isRecord(input.toolArguments) ? input.toolArguments : {};
-    const rawToolResult = await session.client.callTool({
-      name: tool.name,
-      arguments: toolInput,
-    }, undefined, options);
+    const rawToolResult = await session.client.callTool(
+      {
+        name: tool.name,
+        arguments: toolInput,
+      },
+      undefined,
+      options,
+    );
     const toolResult = normalizeExtAppToolResult({ result: rawToolResult });
     const readResult = await session.client.readResource({ uri: resourceUri }, options);
     const resourceMeta = resourceMetaFromReadResult(readResult);

package/src/server/mutation-history.ts

@@ -254,10 +254,14 @@ export function diffLayouts(
     const changes: string[] = [];
 
     if (snapNode.position.x !== curNode.position.x || snapNode.position.y !== curNode.position.y) {
-      changes.push(`moved (${snapNode.position.x},${snapNode.position.y}) → (${curNode.position.x},${curNode.position.y})`);
+      changes.push(
+        `moved (${snapNode.position.x},${snapNode.position.y}) → (${curNode.position.x},${curNode.position.y})`,
+      );
     }
     if (snapNode.size.width !== curNode.size.width || snapNode.size.height !== curNode.size.height) {
-      changes.push(`resized ${snapNode.size.width}x${snapNode.size.height} → ${curNode.size.width}x${curNode.size.height}`);
+      changes.push(
+        `resized ${snapNode.size.width}x${snapNode.size.height} → ${curNode.size.width}x${curNode.size.height}`,
+      );
     }
     if (snapNode.collapsed !== curNode.collapsed) {
       changes.push(curNode.collapsed ? 'collapsed' : 'expanded');
@@ -314,8 +318,12 @@ export function diffLayouts(
 export function formatDiff(diff: SnapshotDiffResult): string {
   const lines: string[] = [`Diff: current canvas vs snapshot "${diff.snapshotName}"`, ''];
 
-  const total = diff.addedNodes.length + diff.removedNodes.length + diff.modifiedNodes.length
-    + diff.addedEdges.length + diff.removedEdges.length;
+  const total =
+    diff.addedNodes.length +
+    diff.removedNodes.length +
+    diff.modifiedNodes.length +
+    diff.addedEdges.length +
+    diff.removedEdges.length;
 
   if (total === 0) {
     lines.push('No differences — canvas matches the snapshot exactly.');
@@ -365,7 +373,9 @@ export function formatDiff(diff: SnapshotDiffResult): string {
     lines.push('');
   }
 
-  lines.push(`Summary: +${diff.addedNodes.length} -${diff.removedNodes.length} ~${diff.modifiedNodes.length} nodes, +${diff.addedEdges.length} -${diff.removedEdges.length} edges`);
+  lines.push(
+    `Summary: +${diff.addedNodes.length} -${diff.removedNodes.length} ~${diff.modifiedNodes.length} nodes, +${diff.addedEdges.length} -${diff.removedEdges.length} edges`,
+  );
 
   return lines.join('\n');
 }

package/src/server/operations/composites.ts

@@ -345,9 +345,7 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
  * Deriving it from the composites keeps suppression in lockstep with them — a
  * newly folded action is automatically suppressed from standalone registration.
  */
-export function compositeFoldedOpNames(
-  definitions: CompositeToolDefinition[] = compositeToolDefinitions,
-): Set<string> {
+export function compositeFoldedOpNames(definitions: CompositeToolDefinition[] = compositeToolDefinitions): Set<string> {
   const names = new Set<string>();
   for (const def of definitions) {
     // Single-discriminator composites: the flat `actions` map values.

package/src/server/operations/http.ts

@@ -69,9 +69,8 @@ async function defaultReadInput(
     return { ...query, ...params };
   }
   const body = await readJsonValue(req);
-  const record = body !== null && typeof body === 'object' && !Array.isArray(body)
-    ? body as Record<string, unknown>
-    : {};
+  const record =
+    body !== null && typeof body === 'object' && !Array.isArray(body) ? (body as Record<string, unknown>) : {};
   return { ...query, ...record, ...params };
 }
 

package/src/server/operations/index.ts

@@ -20,6 +20,9 @@ import { batchOperations } from './ops/batch.js';
 import { webviewOperations } from './ops/webview.js';
 import { appOperations } from './ops/app.js';
 import { intentOperations } from './ops/intent.js';
+import { extAppOperations } from './ops/ext-app.js';
+import { axReadOperations } from './ops/ax-read.js';
+import { canvasWireOperations } from './ops/canvas-wire.js';
 
 for (const op of [
   ...nodeOperations,
@@ -39,6 +42,9 @@ for (const op of [
   ...webviewOperations,
   ...appOperations,
   ...intentOperations,
+  ...extAppOperations,
+  ...axReadOperations,
+  ...canvasWireOperations,
 ]) {
   registerOperation(op);
 }
@@ -53,7 +59,7 @@ export {
 export { dispatchOperationRoute } from './http.js';
 export { runCanvasBatchOperation, type BatchEnvelope } from './ops/batch.js';
 // OpenMcpAppCoreResult is the SDK's cast target for executeOperation('mcpapp.open').
-export { type OpenMcpAppCoreResult } from './ops/app.js';
+export type { OpenMcpAppCoreResult } from './ops/app.js';
 export { LocalOperationInvoker, HttpOperationInvoker, type OperationInvoker } from './invoker.js';
 export { registerOperationTools, registerCompositeTools, type OperationToolHost } from './mcp.js';
 export { compositeToolDefinitions, type CompositeToolDefinition } from './composites.js';

package/src/server/operations/invoker.ts

@@ -77,9 +77,10 @@ export class HttpOperationInvoker implements OperationInvoker {
     }
     if (!response.ok) {
       if (route.errorBodyAsResult) return parsed;
-      const message = parsed !== null && typeof parsed === 'object' && 'error' in parsed
-        ? String((parsed as { error?: unknown }).error)
-        : `HTTP ${response.status}`;
+      const message =
+        parsed !== null && typeof parsed === 'object' && 'error' in parsed
+          ? String((parsed as { error?: unknown }).error)
+          : `HTTP ${response.status}`;
       throw new OperationError(message, toOperationErrorStatus(response.status));
     }
     return parsed;

package/src/server/operations/mcp.ts

@@ -18,10 +18,7 @@ export interface OperationToolHost extends OperationMcpToolHost {
   invoker(): OperationInvoker;
 }
 
-export function registerOperationTools(
-  server: McpServer,
-  getHost: () => Promise<OperationToolHost>,
-): void {
+export function registerOperationTools(server: McpServer, getHost: () => Promise<OperationToolHost>): void {
   // Ops folded by a composite are NOT registered standalone: their legacy
   // single-purpose tools were removed in v0.3.0 (docs/api-stability.md). The op
   // itself is untouched — it stays reachable via its composite and canvas_batch.
@@ -191,32 +188,27 @@ export function registerCompositeTools(
   definitions: CompositeToolDefinition[] = compositeToolDefinitions,
 ): void {
   for (const def of definitions) {
-    server.tool(
-      def.toolName,
-      def.description,
-      buildCompositeShape(def),
-      async (input: Record<string, unknown>) => {
-        try {
-          const host = await getHost();
-          const opName = resolveCompositeOp(def, input);
-          const op = getOperation(opName);
-          // Strip the composite discriminators (action + any extra, e.g. `kind`)
-          // and undo any field remap; the rest is the op's raw MCP args — the same
-          // value the standalone tool would receive.
-          const rest = stripCompositeDiscriminators(def, input);
-          const opInput = op.mcp?.buildInput ? op.mcp.buildInput(rest) : rest;
-          const result = await host.invoker().invoke(opName, opInput);
-          if (op.mcp?.formatResult) {
-            return await op.mcp.formatResult(result, rest, host);
-          }
-          return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
-        } catch (error) {
-          return {
-            content: [{ type: 'text' as const, text: error instanceof Error ? error.message : String(error) }],
-            isError: true,
-          };
+    server.tool(def.toolName, def.description, buildCompositeShape(def), async (input: Record<string, unknown>) => {
+      try {
+        const host = await getHost();
+        const opName = resolveCompositeOp(def, input);
+        const op = getOperation(opName);
+        // Strip the composite discriminators (action + any extra, e.g. `kind`)
+        // and undo any field remap; the rest is the op's raw MCP args — the same
+        // value the standalone tool would receive.
+        const rest = stripCompositeDiscriminators(def, input);
+        const opInput = op.mcp?.buildInput ? op.mcp.buildInput(rest) : rest;
+        const result = await host.invoker().invoke(opName, opInput);
+        if (op.mcp?.formatResult) {
+          return await op.mcp.formatResult(result, rest, host);
         }
-      },
-    );
+        return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return {
+          content: [{ type: 'text' as const, text: error instanceof Error ? error.message : String(error) }],
+          isError: true,
+        };
+      }
+    });
   }
 }

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

@@ -1,18 +1,21 @@
 /**
- * Annotation mutation op (plan-008 Wave 1): annotation.remove.
+ * Annotation ops: annotation.remove (plan-008 Wave 1) and annotation.add
+ * (plan-009 C1 slice 3 — the legacy POST /api/canvas/annotation handler,
+ * wire-identical).
  *
- * DELETE-by-id of a human-drawn canvas annotation. mutates: true → the registry
- * auto-emits one canvas-layout-update after success, matching the legacy
- * handleCanvasRemoveAnnotation handler (which emitted the layout update only on a
- * successful removal). A non-existent id is a 404 OperationError carrying the
- * exact legacy message; an omitted id is a 400 so composite callers get a loud
- * input error instead of a misleading "not found". HTTP renders errors as
- * { ok:false, error } and MCP renders them as isError tool results.
+ * annotation.remove: DELETE-by-id of a human-drawn canvas annotation.
+ * mutates: true → the registry auto-emits one canvas-layout-update after
+ * success, matching the legacy handler. A non-existent id is a 404
+ * OperationError carrying the exact legacy message; an omitted id is a 400 so
+ * composite callers get a loud input error instead of a misleading "not
+ * found". HTTP renders errors as { ok:false, error } and MCP renders them as
+ * isError tool results.
  *
  * This module must never import server.ts or index.ts.
  */
 import { z } from 'zod';
-import { canvasState } from '../../canvas-state.js';
+import { canvasState, type CanvasAnnotation } from '../../canvas-state.js';
+import { summarizeCanvasAnnotation } from '../../canvas-serialization.js';
 import { defineOperation, OperationError, type Operation } from '../types.js';
 
 const annotationRemoveShape = {
@@ -57,4 +60,113 @@ const annotationRemoveOperation = defineOperation<z.infer<typeof annotationRemov
   },
 });
 
-export const annotationOperations: Operation[] = [annotationRemoveOperation];
+// ── annotation.add (helpers moved from server.ts) ─────────────
+
+function annotationBounds(points: CanvasAnnotation['points']): CanvasAnnotation['bounds'] {
+  const xs = points.map((point) => point.x);
+  const ys = points.map((point) => point.y);
+  const minX = Math.min(...xs);
+  const minY = Math.min(...ys);
+  const maxX = Math.max(...xs);
+  const maxY = Math.max(...ys);
+  return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+}
+
+function textAnnotationBounds(
+  point: CanvasAnnotation['points'][number],
+  text: string,
+  width: number,
+): CanvasAnnotation['bounds'] {
+  return {
+    x: point.x,
+    y: point.y - width,
+    width: Math.max(width, text.length * width * 0.62),
+    height: width * 1.2,
+  };
+}
+
+function parseAnnotationPoints(value: unknown): CanvasAnnotation['points'] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((point) => {
+      if (!point || typeof point !== 'object' || Array.isArray(point)) return null;
+      const record = point as Record<string, unknown>;
+      if (typeof record.x !== 'number' || typeof record.y !== 'number') return null;
+      if (!Number.isFinite(record.x) || !Number.isFinite(record.y)) return null;
+      return { x: record.x, y: record.y };
+    })
+    .filter((point): point is CanvasAnnotation['points'][number] => point !== null);
+}
+
+const annotationAddShape = {
+  type: z.unknown().optional().describe("Annotation type: 'freehand' (default) or 'text'"),
+  points: z.unknown().optional().describe('Annotation points: [{ x, y }, …]'),
+  width: z.unknown().optional().describe('Stroke width (freehand) or font size (text)'),
+  color: z.unknown().optional().describe("'currentColor' or a #rrggbb hex color"),
+  label: z.unknown().optional().describe('Short annotation label'),
+  text: z.unknown().optional().describe('Text annotation content'),
+  id: z.unknown().optional().describe('Explicit annotation id'),
+};
+
+const annotationAddSchema = z.looseObject(annotationAddShape);
+
+const annotationAddOperation = defineOperation<z.infer<typeof annotationAddSchema>, Record<string, unknown>>({
+  name: 'annotation.add',
+  mutates: true,
+  input: annotationAddSchema,
+  inputShape: annotationAddShape,
+  http: {
+    method: 'POST',
+    path: '/api/canvas/annotation',
+  },
+  handler: (input) => {
+    const body: Record<string, unknown> = input;
+    const type = body.type === 'text' ? 'text' : 'freehand';
+    const points = parseAnnotationPoints(body.points);
+    if (points.length < (type === 'text' ? 1 : 2)) {
+      throw new OperationError(
+        type === 'text' ? 'Text annotation requires a valid point.' : 'Annotation requires at least two valid points.',
+      );
+    }
+
+    const defaultWidth = type === 'text' ? 24 : 4;
+    const maxWidth = type === 'text' ? 96 : 24;
+    const width =
+      typeof body.width === 'number' && Number.isFinite(body.width)
+        ? Math.min(maxWidth, Math.max(1, body.width))
+        : defaultWidth;
+    const color =
+      typeof body.color === 'string' && (body.color === 'currentColor' || /^#[0-9a-fA-F]{6}$/.test(body.color))
+        ? body.color
+        : 'currentColor';
+    const label =
+      typeof body.label === 'string' && body.label.trim().length > 0 ? body.label.trim().slice(0, 160) : undefined;
+    const text =
+      type === 'text' && typeof body.text === 'string' && body.text.trim().length > 0
+        ? body.text.trim().slice(0, 240)
+        : undefined;
+    if (type === 'text' && !text) {
+      throw new OperationError('Text annotation requires text.');
+    }
+    const id =
+      typeof body.id === 'string' && body.id.trim().length > 0
+        ? body.id.trim().slice(0, 120)
+        : `ann-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+    const annotation: CanvasAnnotation = {
+      id,
+      type,
+      points,
+      bounds: type === 'text' ? textAnnotationBounds(points[0]!, text!, width) : annotationBounds(points),
+      color,
+      width,
+      ...(text ? { text } : {}),
+      ...((label ?? text) ? { label: label ?? text } : {}),
+      createdAt: new Date().toISOString(),
+    };
+
+    canvasState.addAnnotation(annotation);
+    return { ok: true, annotation: summarizeCanvasAnnotation(annotation) };
+  },
+});
+
+export const annotationOperations: Operation[] = [annotationRemoveOperation, annotationAddOperation];