@1agh/maude 0.29.0 → 0.31.0

package/apps/studio/test/acp-bridge.test.ts

@@ -0,0 +1,127 @@
+// End-to-end bridge test against a mock ACP agent (test/fixtures/mock-acp-agent.mjs)
+// so no real `claude` install is needed. Proves: spawn + handshake + streamed
+// update + turn completion, AND that ANTHROPIC_API_KEY never reaches the child
+// (DDR-123 guardrail #1, verified end-to-end — the mock echoes its own env).
+
+import { afterEach, describe, expect, test } from 'bun:test';
+import { join } from 'node:path';
+
+import { AcpBridge } from '../acp/bridge.ts';
+import { probeAcpAvailability } from '../acp/probe.ts';
+
+const FIXTURE = join(import.meta.dir, 'fixtures', 'mock-acp-agent.mjs');
+const TEST_ENV_KEYS = [
+  'ANTHROPIC_API_KEY',
+  'MAUDE_ACP_ADAPTER_ENTRY',
+  'MAUDE_ACP_RUNTIME',
+  'MAUDE_CLAUDE_BIN',
+];
+
+afterEach(() => {
+  for (const key of TEST_ENV_KEYS) delete process.env[key];
+});
+
+describe('AcpBridge — round-trip + subscription guardrail', () => {
+  test('connects, streams an update, completes a turn, and scrubs ANTHROPIC_API_KEY', async () => {
+    process.env.ANTHROPIC_API_KEY = 'sk-must-be-scrubbed';
+    process.env.MAUDE_ACP_ADAPTER_ENTRY = FIXTURE;
+    process.env.MAUDE_ACP_RUNTIME = process.execPath; // run the mock under this bun
+    process.env.MAUDE_CLAUDE_BIN = process.execPath; // satisfy the claude-present check
+
+    const updates: unknown[] = [];
+    const bridge = new AcpBridge({ repoRoot: process.cwd(), onUpdate: (u) => updates.push(u) });
+    try {
+      const result = await bridge.prompt('hello', 'c1');
+      expect(bridge.connected).toBe(true);
+      expect(bridge.sessionId).toBe('mock-session-1');
+      expect(result.stopReason).toBe('end_turn');
+
+      // The mock streamed its own ANTHROPIC_API_KEY — it must read `<unset>`,
+      // proving scrubAgentEnv stripped it from the child env before spawn.
+      const streamed = JSON.stringify(updates);
+      expect(streamed).toContain('apiKey=<unset>');
+      expect(streamed).not.toContain('sk-must-be-scrubbed');
+    } finally {
+      await bridge.stop();
+    }
+  }, 15000);
+
+  test('setConfig passes model + effort to the child env (ANTHROPIC_MODEL / MAX_THINKING_TOKENS)', async () => {
+    process.env.MAUDE_ACP_ADAPTER_ENTRY = FIXTURE;
+    process.env.MAUDE_ACP_RUNTIME = process.execPath;
+    process.env.MAUDE_CLAUDE_BIN = process.execPath;
+
+    const updates: unknown[] = [];
+    const bridge = new AcpBridge({ repoRoot: process.cwd(), onUpdate: (u) => updates.push(u) });
+    try {
+      bridge.setConfig('opus', 'thorough');
+      await bridge.prompt('hi', 'c1');
+      const first = JSON.stringify(updates);
+      expect(first).toContain('model=opus');
+      expect(first).toContain('thinking=31999');
+
+      // Changing the config re-spawns with the new env on the next prompt.
+      updates.length = 0;
+      bridge.setConfig(null, 'fast');
+      await bridge.prompt('again', 'c1');
+      const second = JSON.stringify(updates);
+      expect(second).toContain('model=<unset>'); // null model → ANTHROPIC_MODEL not set
+      expect(second).toContain('thinking=0'); // fast → thinking disabled
+    } finally {
+      await bridge.stop();
+    }
+  }, 15000);
+
+  test('a second prompt reuses the same live session', async () => {
+    process.env.MAUDE_ACP_ADAPTER_ENTRY = FIXTURE;
+    process.env.MAUDE_ACP_RUNTIME = process.execPath;
+    process.env.MAUDE_CLAUDE_BIN = process.execPath;
+
+    const bridge = new AcpBridge({ repoRoot: process.cwd(), onUpdate: () => {} });
+    try {
+      await bridge.prompt('first', 'c1');
+      const sid = bridge.sessionId;
+      await bridge.prompt('second', 'c1');
+      expect(bridge.sessionId).toBe(sid);
+    } finally {
+      await bridge.stop();
+    }
+  }, 15000);
+
+  test('different chat ids get separate claude sessions; same id reuses its own', async () => {
+    process.env.MAUDE_ACP_ADAPTER_ENTRY = FIXTURE;
+    process.env.MAUDE_ACP_RUNTIME = process.execPath;
+    process.env.MAUDE_CLAUDE_BIN = process.execPath;
+
+    const bridge = new AcpBridge({ repoRoot: process.cwd(), onUpdate: () => {} });
+    try {
+      await bridge.prompt('a', 'chatA');
+      const sa = bridge.sessionId;
+      await bridge.prompt('b', 'chatB');
+      const sb = bridge.sessionId;
+      expect(sa).not.toBe(sb); // separate per-chat contexts
+      await bridge.prompt('a again', 'chatA');
+      expect(bridge.sessionId).toBe(sa); // chatA reuses its own session
+    } finally {
+      await bridge.stop();
+    }
+  }, 15000);
+});
+
+describe('probeAcpAvailability — not-connected detection', () => {
+  test('reports not-available with a Claude-Code reason when the CLI is absent', () => {
+    process.env.MAUDE_ACP_ADAPTER_ENTRY = FIXTURE;
+    process.env.MAUDE_CLAUDE_BIN = join(import.meta.dir, 'no-such-claude-bin');
+    const probe = probeAcpAvailability();
+    expect(probe.available).toBe(false);
+    expect(probe.reason ?? '').toMatch(/Claude Code/i);
+  });
+
+  test('reports available when both the adapter and a claude binary resolve', () => {
+    process.env.MAUDE_ACP_ADAPTER_ENTRY = FIXTURE;
+    process.env.MAUDE_CLAUDE_BIN = process.execPath;
+    const probe = probeAcpAvailability();
+    expect(probe.available).toBe(true);
+    expect(probe.adapterEntry).toBe(FIXTURE);
+  });
+});

package/apps/studio/test/acp-env.test.ts

@@ -0,0 +1,65 @@
+// DDR-123 guardrail #1 — the single load-bearing detail that keeps the chat
+// panel on the user's Pro/Max subscription instead of metered API billing.
+
+import { describe, expect, test } from 'bun:test';
+
+import { SUBSCRIPTION_SCRUBBED_ENV_KEYS, scrubAgentEnv } from '../acp/env.ts';
+
+describe('scrubAgentEnv — subscription guardrail', () => {
+  test('strips the billing-switching keys, keeps everything else', () => {
+    const out = scrubAgentEnv({
+      PATH: '/usr/bin',
+      HOME: '/Users/x',
+      ANTHROPIC_API_KEY: 'sk-live-xxx',
+      ANTHROPIC_AUTH_TOKEN: 'tok-xxx',
+      UNDEFINED_VAR: undefined,
+    });
+    expect(out.PATH).toBe('/usr/bin');
+    expect(out.HOME).toBe('/Users/x');
+    expect('ANTHROPIC_API_KEY' in out).toBe(false);
+    expect('ANTHROPIC_AUTH_TOKEN' in out).toBe(false);
+    // undefined values are dropped (Bun.spawn env wants Record<string,string>)
+    expect('UNDEFINED_VAR' in out).toBe(false);
+  });
+
+  test('pins exactly the two precedence-relevant keys', () => {
+    expect([...SUBSCRIPTION_SCRUBBED_ENV_KEYS].sort()).toEqual([
+      'ANTHROPIC_API_KEY',
+      'ANTHROPIC_AUTH_TOKEN',
+    ]);
+  });
+
+  test('scrubs the whole provider/billing namespace, not just the two keys (F1)', () => {
+    const out = scrubAgentEnv({
+      PATH: '/usr/bin',
+      ANTHROPIC_BASE_URL: 'https://evil.example/v1',
+      ANTHROPIC_MODEL: 'attacker-pinned',
+      ANTHROPIC_BEDROCK_BASE_URL: 'https://evil',
+      CLAUDE_CODE_USE_BEDROCK: '1',
+      CLAUDE_CODE_USE_VERTEX: '1',
+      AWS_BEARER_TOKEN_BEDROCK: 'tok',
+      claude_session: 'keep-me', // not a provider redirect → kept
+    });
+    expect(out.PATH).toBe('/usr/bin');
+    expect('ANTHROPIC_BASE_URL' in out).toBe(false);
+    expect('ANTHROPIC_MODEL' in out).toBe(false); // re-added by the bridge from a validated value
+    expect('ANTHROPIC_BEDROCK_BASE_URL' in out).toBe(false);
+    expect('CLAUDE_CODE_USE_BEDROCK' in out).toBe(false);
+    expect('CLAUDE_CODE_USE_VERTEX' in out).toBe(false);
+    expect('AWS_BEARER_TOKEN_BEDROCK' in out).toBe(false);
+    expect(out.claude_session).toBe('keep-me');
+  });
+
+  test('never mutates the source (process.env stays intact for the parent)', () => {
+    const src: Record<string, string | undefined> = { ANTHROPIC_API_KEY: 'sk', PATH: '/bin' };
+    const out = scrubAgentEnv(src);
+    expect(src.ANTHROPIC_API_KEY).toBe('sk');
+    expect(out).not.toBe(src);
+  });
+
+  test('defaults to process.env when called with no argument', () => {
+    // Smoke: doesn't throw, returns a string map without the scrubbed keys.
+    const out = scrubAgentEnv();
+    expect('ANTHROPIC_API_KEY' in out).toBe(false);
+  });
+});

package/apps/studio/test/acp-origin-gate.test.ts

@@ -0,0 +1,78 @@
+// ACP bridge origin gate (DDR-123). The agent bridge spawns the user's `claude`
+// and can drive file edits, so it lives ONLY on the main (privileged) origin and
+// only over loopback. This proves:
+//   (1) GET /_api/acp/status serves on the main origin;
+//   (2) it is 403'd on the untrusted canvas origin (off CANVAS_SAFE_API +
+//       startCanvasServer routes — the dual-allowlist rule);
+//   (3) /_ws/acp is wired on the main origin (upgrade-without-headers → 400);
+//   (4) the loopback guard that fronts /_ws/acp rejects non-loopback hosts.
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { isLoopbackHost } from '../ws.ts';
+import { bootServer, killProc, makeSandbox, nextPort } from './_helpers.ts';
+
+async function readCanvasOrigin(designRoot: string): Promise<string> {
+  for (let i = 0; i < 40; i++) {
+    try {
+      const info = JSON.parse(readFileSync(join(designRoot, '_server.json'), 'utf8'));
+      if (info.canvasOrigin) return info.canvasOrigin as string;
+    } catch {
+      /* not written yet */
+    }
+    await Bun.sleep(50);
+  }
+  throw new Error('canvasOrigin never appeared in _server.json');
+}
+
+describe('ACP bridge origin gate', () => {
+  test('status is main-origin only; /_ws/acp wired on main', async () => {
+    const { root, designRoot } = makeSandbox();
+    const port = nextPort();
+    const proc = await bootServer(root, port, { MAUDE_CANVAS_ORIGIN_SPLIT: '1' });
+    try {
+      const main = `http://localhost:${port}`;
+      const canvas = await readCanvasOrigin(designRoot);
+      const status = async (base: string, path: string) =>
+        (await fetch(base + path, { signal: AbortSignal.timeout(2000) })).status;
+
+      // (1) main origin exposes the readiness probe
+      const probe = await fetch(`${main}/_api/acp/status`, { signal: AbortSignal.timeout(2000) });
+      expect(probe.status).toBe(200);
+      expect(typeof (await probe.json()).available).toBe('boolean');
+
+      // (2) the untrusted canvas origin must NOT reach the probe
+      expect(await status(canvas, '/_api/acp/status')).toBe(403);
+
+      // (3) /_ws/acp is wired on the main origin — a plain GET (no Upgrade
+      // headers) passes the loopback guard then fails the WS upgrade → 400,
+      // which proves the route branch exists (a 404 would mean it's unwired).
+      expect(await status(main, '/_ws/acp')).toBe(400);
+
+      // (4) /_api/acp/focus (the /design:chat hook) — POST-only on the main
+      // origin, 403 on the canvas origin.
+      const focusPost = await fetch(`${main}/_api/acp/focus`, {
+        method: 'POST',
+        signal: AbortSignal.timeout(2000),
+      });
+      expect(focusPost.status).toBe(200);
+      expect((await focusPost.json()).ok).toBe(true);
+      expect(await status(main, '/_api/acp/focus')).toBe(405); // GET not allowed
+      expect(await status(canvas, '/_api/acp/focus')).toBe(403); // off the canvas origin
+    } finally {
+      await killProc(proc);
+    }
+  }, 15000);
+
+  test('the loopback guard fronting /_ws/acp rejects non-loopback hosts', () => {
+    // Same guard server.ts applies before upgrading the acp socket.
+    expect(isLoopbackHost('127.0.0.1:4399')).toBe(true);
+    expect(isLoopbackHost('localhost:4399')).toBe(true);
+    expect(isLoopbackHost('[::1]:4399')).toBe(true);
+    expect(isLoopbackHost('evil.example.com')).toBe(false);
+    expect(isLoopbackHost('10.0.0.5:4399')).toBe(false);
+    expect(isLoopbackHost(null)).toBe(false);
+  });
+});

package/apps/studio/test/acp-transcript.test.ts

@@ -0,0 +1,112 @@
+// acp/transcript — repo-level chat list + raw-transcript → clean-messages.
+
+import { afterEach, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { deleteChat, listChats, readChatMessages } from '../acp/transcript.ts';
+
+let root: string;
+afterEach(() => {
+  if (root) rmSync(root, { recursive: true, force: true });
+});
+
+function seed(chatId: string, lines: object[]): string {
+  root = mkdtempSync(join(tmpdir(), 'acp-tx-'));
+  const dir = join(root, '_chat');
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${chatId}.jsonl`), lines.map((l) => JSON.stringify(l)).join('\n'));
+  return root;
+}
+
+describe('readChatMessages — raw → clean turns', () => {
+  test('aggregates agent updates into one assistant message; drops noise', () => {
+    const designRoot = seed('c1', [
+      { ts: 1, role: 'user', text: 'make the button red' },
+      {
+        ts: 2,
+        role: 'agent',
+        update: { sessionUpdate: 'available_commands_update', availableCommands: [] },
+      },
+      {
+        ts: 3,
+        role: 'agent',
+        update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: 'Sure, ' } },
+      },
+      {
+        ts: 4,
+        role: 'agent',
+        update: {
+          sessionUpdate: 'tool_call',
+          toolCallId: 't1',
+          title: 'Edit Button.tsx',
+          kind: 'edit',
+          status: 'pending',
+        },
+      },
+      {
+        ts: 5,
+        role: 'agent',
+        update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: 'done.' } },
+      },
+      {
+        ts: 6,
+        role: 'agent',
+        update: { sessionUpdate: 'tool_call_update', toolCallId: 't1', status: 'completed' },
+      },
+      { ts: 7, role: 'agent', update: { sessionUpdate: 'usage_update', used: 10 } },
+      { ts: 8, role: 'stop', stopReason: 'end_turn' },
+    ]);
+
+    const msgs = readChatMessages(designRoot, 'c1');
+    expect(msgs.length).toBe(2);
+    expect(msgs[0]).toEqual({
+      role: 'user',
+      parts: [{ type: 'text', text: 'make the button red' }],
+    });
+    expect(msgs[1].role).toBe('assistant');
+    // text parts merged across the tool call boundary order-preserving
+    const texts = msgs[1].parts.filter((p) => p.type === 'text').map((p) => p.text);
+    expect(texts.join('')).toBe('Sure, done.');
+    const tool = msgs[1].parts.find((p) => p.type === 'tool');
+    expect(tool?.toolName).toBe('Edit Button.tsx');
+    expect(tool?.done).toBe(true);
+    // noise (available_commands_update / usage_update) is not rendered
+    expect(JSON.stringify(msgs)).not.toContain('availableCommands');
+    expect(JSON.stringify(msgs)).not.toContain('usage');
+  });
+
+  test('missing chat → empty', () => {
+    const designRoot = seed('c1', [{ ts: 1, role: 'user', text: 'hi' }]);
+    expect(readChatMessages(designRoot, 'nope')).toEqual([]);
+  });
+});
+
+describe('listChats', () => {
+  test('lists chats with a title derived from the first user line', () => {
+    const designRoot = seed('chat-7', [
+      { ts: 1, role: 'user', text: 'redesign the pricing page please' },
+      { ts: 2, role: 'stop', stopReason: 'end_turn' },
+    ]);
+    const chats = listChats(designRoot);
+    expect(chats.length).toBe(1);
+    expect(chats[0].id).toBe('chat-7');
+    expect(chats[0].title).toBe('redesign the pricing page please');
+  });
+
+  test('no _chat dir → empty', () => {
+    root = mkdtempSync(join(tmpdir(), 'acp-tx-'));
+    expect(listChats(root)).toEqual([]);
+  });
+});
+
+describe('deleteChat', () => {
+  test('removes the transcript; missing → false', () => {
+    const designRoot = seed('gone', [{ ts: 1, role: 'user', text: 'bye' }]);
+    expect(listChats(designRoot).length).toBe(1);
+    expect(deleteChat(designRoot, 'gone')).toBe(true);
+    expect(listChats(designRoot).length).toBe(0);
+    expect(deleteChat(designRoot, 'gone')).toBe(false);
+  });
+});

package/apps/studio/test/activity.test.ts

@@ -2,13 +2,7 @@
 
 import { describe, expect, test } from 'bun:test';
 
-import {
-  ACTIVITY_IDLE_MS,
-  type ActivityChange,
-  createActivity,
-  diffArtboardIds,
-  isCanvasFile,
-} from '../activity.ts';
+import { type ActivityChange, createActivity, diffArtboardIds, isCanvasFile } from '../activity.ts';
 import { type Context, createBus } from '../context.ts';
 
 function mkCtx(): Context {

package/apps/studio/test/annotate-write.test.ts

@@ -0,0 +1,184 @@
+// annotate-write — FigJam v3 AI write verb (`maude design annotate`).
+// Drives bin/annotate.mjs as a subprocess against a temp design root and
+// asserts the output through the CANONICAL parser: everything the verb writes
+// must be sanitize-stable, byte-identical under parse → re-serialize, and
+// readable back as a graph by read-annotations --graph.
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { GlobalRegistrator } from '@happy-dom/global-registrator';
+
+import {
+  type ArrowStroke,
+  type StickyStroke,
+  type Stroke,
+  sanitizeAnnotationSvg,
+  strokesToSvg,
+  svgToStrokes,
+} from '../annotations-model.ts';
+
+const BIN = new URL('../bin/annotate.mjs', import.meta.url).pathname;
+const READER = new URL('../bin/read-annotations.mjs', import.meta.url).pathname;
+
+let root: string;
+
+beforeAll(() => {
+  GlobalRegistrator.register();
+  root = mkdtempSync(join(tmpdir(), 'annotate-test-'));
+  // A design root with no config — resolveDesignRoot defaults to .design.
+  writeFileSync(
+    join(root, 'flow.json'),
+    JSON.stringify({
+      nodes: [
+        { id: 'a', label: 'Start' },
+        { id: 'b', label: 'Middle' },
+        { id: 'c', label: 'End', shape: 'ellipse' },
+      ],
+      edges: [
+        { from: 'a', to: 'b' },
+        { from: 'b', to: 'c', label: 'ships' },
+      ],
+    })
+  );
+  Bun.spawnSync(['mkdir', '-p', join(root, '.design')]);
+});
+
+afterAll(async () => {
+  await GlobalRegistrator.unregister();
+  rmSync(root, { recursive: true, force: true });
+});
+
+function runAnnotate(args: string[], stdin?: string): { code: number; out: string; err: string } {
+  const proc = Bun.spawnSync(['bun', BIN, ...args], {
+    stdin: stdin ? new TextEncoder().encode(stdin) : undefined,
+  });
+  return {
+    code: proc.exitCode,
+    out: new TextDecoder().decode(proc.stdout),
+    err: new TextDecoder().decode(proc.stderr),
+  };
+}
+
+function readSvg(): string {
+  return readFileSync(join(root, '.design', 'ui-flow.annotations.svg'), 'utf8');
+}
+
+describe('annotate --flow', () => {
+  test('writes an auto-laid-out diagram of bound connectors', () => {
+    const res = runAnnotate(['ui/Flow.tsx', '--flow', join(root, 'flow.json'), '--root', root]);
+    expect(res.code).toBe(0);
+    const result = JSON.parse(res.out) as { ok: boolean; refs: Record<string, string> };
+    expect(result.ok).toBe(true);
+    expect(Object.keys(result.refs)).toEqual(['@a', '@b', '@c']);
+
+    const svg = readSvg();
+    // Canonical-parser compatible, sanitize-stable, byte-identical round-trip.
+    expect(sanitizeAnnotationSvg(svg)).toBe(svg);
+    const strokes = svgToStrokes(svg);
+    expect(strokesToSvg(strokes)).toBe(svg);
+    // 3 shapes + 3 labels (2 anchored + 1 ellipse-anchored) + 2 arrows + 1 edge label.
+    const arrows = strokes.filter((s): s is ArrowStroke => s.tool === 'arrow');
+    expect(arrows).toHaveLength(2);
+    for (const a of arrows) {
+      expect(a.startBind?.hostId).toBeDefined();
+      expect(a.endBind?.hostId).toBeDefined();
+      expect(a.author).toBe('ai');
+    }
+    // Layered layout: 'b' sits one column right of 'a'.
+    const aShape = strokes.find((s) => s.id === result.refs['@a']) as Stroke & { x: number };
+    const bShape = strokes.find((s) => s.id === result.refs['@b']) as Stroke & { x: number };
+    expect(bShape.x).toBeGreaterThan(aShape.x);
+  });
+
+  test('read-annotations --graph reads the diagram back as the same graph', () => {
+    const proc = Bun.spawnSync(['node', READER, 'ui/Flow.tsx', '--root', root, '--graph']);
+    const parsed = JSON.parse(new TextDecoder().decode(proc.stdout)) as {
+      graph: { nodes: Array<{ label: string | null }>; edges: unknown[] };
+    };
+    expect(parsed.graph.edges).toHaveLength(2);
+    expect(parsed.graph.nodes.map((n) => n.label).sort()).toEqual(['End', 'Middle', 'Start']);
+  });
+});
+
+describe('annotate --ops', () => {
+  test('create sticky + group + connect-to-existing + delete, via stdin', () => {
+    // Connect to a node minted by the previous --flow run.
+    const flowSvg = readSvg();
+    const existingId = (svgToStrokes(flowSvg).find((s) => s.tool === 'rect') as Stroke).id;
+    const ops = {
+      ops: [
+        { op: 'create', type: 'sticky', ref: '@n1', text: 'pain point', x: 100, y: 600 },
+        { op: 'create', type: 'sticky', ref: '@n2', text: 'idea', x: 340, y: 600 },
+        { op: 'group', ids: ['@n1', '@n2'] },
+        { op: 'connect', from: '@n1', to: existingId },
+      ],
+    };
+    const res = runAnnotate(['ui/Flow.tsx', '--root', root], JSON.stringify(ops));
+    expect(res.code).toBe(0);
+    const svg = readSvg();
+    expect(sanitizeAnnotationSvg(svg)).toBe(svg);
+    const strokes = svgToStrokes(svg);
+    expect(strokesToSvg(svg && strokes ? strokes : [])).toBe(svg);
+    const stickies = strokes.filter((s): s is StickyStroke => s.tool === 'sticky');
+    expect(stickies).toHaveLength(2);
+    expect(stickies[0]?.groupIds).toEqual(stickies[1]?.groupIds);
+    expect(stickies[0]?.groupIds?.length).toBe(1);
+    const bound = strokes.filter(
+      (s): s is ArrowStroke => s.tool === 'arrow' && s.endBind?.hostId === existingId
+    );
+    expect(bound).toHaveLength(1);
+
+    // Delete one sticky — the element disappears and the file stays canonical.
+    const del = runAnnotate(
+      ['ui/Flow.tsx', '--root', root],
+      JSON.stringify({ ops: [{ op: 'delete', id: stickies[1]?.id }] })
+    );
+    expect(del.code).toBe(0);
+    const after = svgToStrokes(readSvg());
+    expect(after.filter((s) => s.tool === 'sticky')).toHaveLength(1);
+    expect(strokesToSvg(after)).toBe(readSvg());
+  });
+
+  test('unknown connect target fails loud, writes nothing', () => {
+    const before = readSvg();
+    const res = runAnnotate(
+      ['ui/Flow.tsx', '--root', root],
+      JSON.stringify({ ops: [{ op: 'connect', from: '@ghost', to: 'nope' }] })
+    );
+    expect(res.code).toBe(2);
+    expect(readSvg()).toBe(before);
+  });
+
+  test('--dry-run prints the merged SVG without writing', () => {
+    const before = readSvg();
+    const res = runAnnotate(
+      ['ui/Flow.tsx', '--root', root, '--dry-run'],
+      JSON.stringify({ ops: [{ op: 'create', type: 'text', text: 'ghost', x: 0, y: 0 }] })
+    );
+    expect(res.code).toBe(0);
+    expect(res.out).toContain('ghost');
+    expect(readSvg()).toBe(before);
+  });
+
+  test('non-loopback _server.json.url is refused — writes to file, never PUTs off-box (F2)', () => {
+    // A poisoned/foreign _server.json points the egress at an external host.
+    // The verb must NOT PUT there (SSRF/exfil); it falls back to the file write.
+    const serverJson = join(root, '.design', '_server.json');
+    writeFileSync(serverJson, JSON.stringify({ url: 'http://attacker.example.com:4399' }));
+    try {
+      const res = runAnnotate(
+        ['ui/F2.tsx', '--root', root],
+        JSON.stringify({ ops: [{ op: 'create', type: 'text', text: 'secret', x: 0, y: 0 }] })
+      );
+      expect(res.code).toBe(0);
+      // via:"file" proves the off-box PUT was skipped (a successful PUT → "server").
+      expect(JSON.parse(res.out).via).toBe('file');
+      const svg = readFileSync(join(root, '.design', 'ui-f2.annotations.svg'), 'utf8');
+      expect(svg).toContain('secret');
+    } finally {
+      rmSync(serverJson, { force: true });
+    }
+  });
+});

package/apps/studio/test/annotations-align.test.ts

@@ -0,0 +1,88 @@
+// annotations-align — FigJam v3 align + distribute (pure bbox math, DOM-free).
+
+import { describe, expect, test } from 'bun:test';
+
+import { alignStrokes, distributeStrokes } from '../annotations-align.ts';
+import type { RectStroke, Stroke } from '../annotations-model.ts';
+
+function rect(
+  id: string,
+  x: number,
+  y: number,
+  w = 50,
+  h = 50,
+  extra: Partial<RectStroke> = {}
+): RectStroke {
+  return { id, tool: 'rect', color: '#1f1f1f', width: 3, x, y, w, h, ...extra };
+}
+
+const byId = (strokes: readonly Stroke[], id: string): RectStroke =>
+  strokes.find((s) => s.id === id) as RectStroke;
+
+describe('alignStrokes', () => {
+  test('align left snaps every unit to the selection bbox left edge', () => {
+    const strokes = [rect('a', 0, 0), rect('b', 100, 80), rect('c', 40, 200)];
+    const out = alignStrokes(strokes, ['a', 'b', 'c'], 'left');
+    expect(byId(out, 'a').x).toBe(0);
+    expect(byId(out, 'b').x).toBe(0);
+    expect(byId(out, 'c').x).toBe(0);
+    // y untouched by a horizontal align
+    expect(byId(out, 'b').y).toBe(80);
+  });
+
+  test('align h-center / right / bottom', () => {
+    const strokes = [rect('a', 0, 0, 100, 100), rect('b', 200, 50, 20, 20)];
+    const centered = alignStrokes(strokes, ['a', 'b'], 'h-center');
+    // Selection spans x:0..220 → center 110; b (w20) → x=100.
+    expect(byId(centered, 'b').x).toBe(100);
+    const right = alignStrokes(strokes, ['a', 'b'], 'right');
+    expect(byId(right, 'a').x).toBe(120);
+    const bottom = alignStrokes(strokes, ['a', 'b'], 'bottom');
+    expect(byId(bottom, 'b').y).toBe(80);
+  });
+
+  test('a group aligns as ONE unit — members keep their relative offsets', () => {
+    const strokes = [
+      rect('g1', 100, 0, 50, 50, { groupIds: ['g'] }),
+      rect('g2', 160, 30, 50, 50, { groupIds: ['g'] }),
+      rect('solo', 0, 200),
+    ];
+    const out = alignStrokes(strokes, ['g1', 'solo'], 'left');
+    // Group bbox spans x:100..210; aligning left moves the group by -100.
+    expect(byId(out, 'g1').x).toBe(0);
+    expect(byId(out, 'g2').x).toBe(60);
+    expect(byId(out, 'solo').x).toBe(0);
+  });
+
+  test('fewer than two units → referential no-op', () => {
+    const strokes = [
+      rect('a', 0, 0),
+      rect('b', 10, 10, 50, 50, { groupIds: ['g'] }),
+      rect('c', 70, 10, 50, 50, { groupIds: ['g'] }),
+    ];
+    expect(alignStrokes(strokes, ['b'], 'left')).toBe(strokes);
+  });
+});
+
+describe('distributeStrokes', () => {
+  test('equalizes gaps, pinning the first and last unit', () => {
+    // a: 0..50, b: 60..110, c: 200..250 → span 250, total 150, gap = 50.
+    const strokes = [rect('a', 0, 0), rect('b', 60, 0), rect('c', 200, 0)];
+    const out = distributeStrokes(strokes, ['a', 'b', 'c'], 'h');
+    expect(byId(out, 'a').x).toBe(0);
+    expect(byId(out, 'b').x).toBe(100);
+    expect(byId(out, 'c').x).toBe(200);
+  });
+
+  test('vertical distribute', () => {
+    // a: 0..50, b: 55..105, c: 300..350 → span 350, total 150, gap = 100.
+    const strokes = [rect('a', 0, 0), rect('b', 0, 55), rect('c', 0, 300)];
+    const out = distributeStrokes(strokes, ['a', 'b', 'c'], 'v');
+    expect(byId(out, 'b').y).toBe(150);
+  });
+
+  test('fewer than three units → referential no-op', () => {
+    const strokes = [rect('a', 0, 0), rect('b', 100, 0)];
+    expect(distributeStrokes(strokes, ['a', 'b'], 'h')).toBe(strokes);
+  });
+});