@1agh/maude 0.45.1 → 0.46.0

package/apps/studio/test/acp-session-allowed-tools.test.ts

@@ -0,0 +1,91 @@
+// DDR-184 — the curated tool allow-list the bridge auto-approves so the design
+// workflow never stalls on a per-edit / per-`maude` permission prompt (the
+// "Manual mode blocks every edit" complaint). Two things under test:
+//
+//   (1) WIRE contract — the list lands on `_meta.claudeCode.options.allowedTools`
+//       (SDK `allowedTools`, sdk.d.ts:1331), coexisting with the DDR-144
+//       `settingSources` narrowing and the DDR-143 `plugins` carrier. Same
+//       adapter/SDK-INTERNAL `_meta` path as acp-session-plugins.test.ts — a
+//       bump that stops forwarding it must fail HERE, not silently re-prompt.
+//   (2) SOURCE-OF-TRUTH guard — the single `Bash(maude:*)` rule only covers the
+//       whole design-helper surface because DDR-062 routes every helper through
+//       `maude design <verb>`. If that stops being true, or someone widens the
+//       Bash scope, this test fails loudly.
+
+import { describe, expect, test } from 'bun:test';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { MAUDE_DEFAULT_ALLOWED_TOOLS, newSessionParams } from '../acp/bridge.ts';
+import type { SdkPluginConfig } from '../acp/plugin-bootstrap.ts';
+
+type Meta = {
+  systemPrompt?: { append?: string };
+  claudeCode?: {
+    options?: {
+      allowedTools?: string[];
+      plugins?: SdkPluginConfig[];
+      settingSources?: string[];
+    };
+  };
+};
+
+const PLUGINS: SdkPluginConfig[] = [
+  { type: 'local', path: '/bundle/plugins/design', skipMcpDiscovery: true },
+];
+
+describe('newSessionParams — allowedTools carrier shape (DDR-184)', () => {
+  test('the allow-list rides _meta.claudeCode.options.allowedTools', () => {
+    const opts = (newSessionParams('/repo', undefined)._meta as Meta).claudeCode?.options;
+    expect(opts?.allowedTools).toEqual([...MAUDE_DEFAULT_ALLOWED_TOOLS]);
+  });
+
+  test('allowedTools is a COPY, not the shared module constant (no accidental mutation)', () => {
+    const opts = (newSessionParams('/repo')._meta as Meta).claudeCode?.options;
+    expect(opts?.allowedTools).not.toBe(MAUDE_DEFAULT_ALLOWED_TOOLS);
+  });
+
+  test('coexists with settingSources (DDR-144) and plugins (DDR-143) under one options', () => {
+    const opts = (newSessionParams('/repo', 'BRIEF', PLUGINS)._meta as Meta).claudeCode?.options;
+    expect(opts?.settingSources).toEqual(['user']);
+    expect(opts?.plugins).toEqual(PLUGINS);
+    expect(opts?.allowedTools).toEqual([...MAUDE_DEFAULT_ALLOWED_TOOLS]);
+  });
+
+  test('present even with no plugins (npm / web / power-user path)', () => {
+    const opts = (newSessionParams('/repo', 'BRIEF', [])._meta as Meta).claudeCode?.options;
+    expect(opts?.plugins).toBeUndefined();
+    expect(opts?.allowedTools).toEqual([...MAUDE_DEFAULT_ALLOWED_TOOLS]);
+  });
+});
+
+describe('MAUDE_DEFAULT_ALLOWED_TOOLS — source-of-truth guard (DDR-184 / DDR-062)', () => {
+  const bashRules = MAUDE_DEFAULT_ALLOWED_TOOLS.filter((t) => t.startsWith('Bash'));
+
+  test('the canvas-editing file tools are all present', () => {
+    for (const t of ['Read', 'Edit', 'Write', 'Glob', 'Grep', 'NotebookEdit']) {
+      expect(MAUDE_DEFAULT_ALLOWED_TOOLS).toContain(t);
+    }
+  });
+
+  test('the ONLY Bash rule is prefix-scoped to `maude` — never a bare/un-scoped Bash', () => {
+    // A bare `Bash` (or `Bash(*)`) would auto-approve arbitrary command execution
+    // — exactly the blanket surface DDR-179 kept behind the prompt. Guard against
+    // anyone widening it: the list may auto-approve `maude` and nothing else.
+    expect(bashRules).toEqual(['Bash(maude:*)']);
+  });
+
+  test('the single Bash rule is load-bearing on DDR-062: every design helper is a `maude design <verb>`', () => {
+    // Resolve cli/commands/design.mjs relative to this test file's real path
+    // (mirrors acp-session-plugins.test.ts's realpath dance for compiled roots).
+    const here = dirname(realpathSync(import.meta.url.replace('file://', '')));
+    const designCli = join(here, '..', '..', '..', 'cli', 'commands', 'design.mjs');
+    expect(existsSync(designCli)).toBe(true);
+    const src = readFileSync(designCli, 'utf8');
+    // The dispatch table the `Bash(maude:*)` scope rests on — helpers reached via
+    // `maude design <verb>`, not raw `bash <path>.sh` (DDR-062). If this marker
+    // disappears, the one-rule assumption needs re-checking.
+    expect(src).toContain('BIN_VERBS');
+    expect(src).toMatch(/maude design <verb>/);
+  });
+});

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

@@ -0,0 +1,76 @@
+// Pure unit tests for client/panels/ToolGroup.jsx's grouping/summary helpers
+// (Task C1 — collapsed consecutive-tool-call groups).
+
+import { describe, expect, test } from 'bun:test';
+
+import { groupToolCalls, summarizeGroup } from '../client/panels/ToolGroup.jsx';
+
+describe('groupToolCalls', () => {
+  test('a lone tool-call stays a single item, not a group', () => {
+    const parts = [{ type: 'tool-call', toolCallId: '1', toolName: 'Read file' }];
+    expect(groupToolCalls(parts)).toEqual([{ type: 'single', part: parts[0] }]);
+  });
+
+  test('2+ CONSECUTIVE tool-calls fold into one group', () => {
+    const parts = [
+      { type: 'tool-call', toolCallId: '1', toolName: 'Read file' },
+      { type: 'tool-call', toolCallId: '2', toolName: 'Run command' },
+      { type: 'tool-call', toolCallId: '3', toolName: 'Write file' },
+    ];
+    const grouped = groupToolCalls(parts);
+    expect(grouped).toEqual([{ type: 'tool-group', parts }]);
+  });
+
+  test('text/reasoning parts break a run into separate groups', () => {
+    const parts = [
+      { type: 'tool-call', toolCallId: '1', toolName: 'Read file' },
+      { type: 'tool-call', toolCallId: '2', toolName: 'Write file' },
+      { type: 'text', text: 'done reading and writing' },
+      { type: 'tool-call', toolCallId: '3', toolName: 'Run command' },
+    ];
+    const grouped = groupToolCalls(parts);
+    expect(grouped).toEqual([
+      { type: 'tool-group', parts: [parts[0], parts[1]] },
+      { type: 'single', part: parts[2] },
+      { type: 'single', part: parts[3] }, // lone tool-call after the break — not a group
+    ]);
+  });
+
+  test('a mix of text and reasoning parts each stay single, in order', () => {
+    const parts = [
+      { type: 'text', text: 'thinking about it' },
+      { type: 'reasoning', text: '...' },
+      { type: 'text', text: 'here is my answer' },
+    ];
+    expect(groupToolCalls(parts)).toEqual(parts.map((part) => ({ type: 'single', part })));
+  });
+
+  test('tolerates an empty/missing parts array', () => {
+    expect(groupToolCalls([])).toEqual([]);
+    expect(groupToolCalls(undefined)).toEqual([]);
+    expect(groupToolCalls(null)).toEqual([]);
+  });
+});
+
+describe('summarizeGroup', () => {
+  test('all entries sharing one title collapse to "Ran N × <title>"', () => {
+    const parts = [{ toolName: 'Read file' }, { toolName: 'Read file' }, { toolName: 'Read file' }];
+    expect(summarizeGroup(parts)).toBe('Ran 3 × Read file');
+  });
+
+  test('mixed titles list the distinct ones, capped at 3 with an ellipsis', () => {
+    const parts = [
+      { toolName: 'Read file' },
+      { toolName: 'Run command' },
+      { toolName: 'Web search' },
+      { toolName: 'Write file' },
+      { toolName: 'Read file' }, // duplicate — must not inflate the unique count
+    ];
+    const summary = summarizeGroup(parts);
+    expect(summary).toBe('Ran 5 tools — Read file, Run command, Web search…');
+  });
+
+  test('a missing toolName falls back to the generic label, not undefined', () => {
+    expect(summarizeGroup([{}, {}])).toBe('Ran 2 × tool');
+  });
+});

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

@@ -0,0 +1,71 @@
+// Pure unit tests for client/panels/transcript-view.js (Task C4).
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  DEFAULT_TRANSCRIPT_VIEW,
+  filterTranscriptParts,
+  TRANSCRIPT_VIEWS,
+  transcriptForcesExpand,
+} from '../client/panels/transcript-view.js';
+
+const PARTS = [
+  { type: 'reasoning', text: 'let me think' },
+  { type: 'tool-call', toolCallId: '1', toolName: 'Read file' },
+  { type: 'text', text: 'first answer' },
+  { type: 'reasoning', text: 'more thinking' },
+  { type: 'text', text: 'final answer' },
+];
+
+describe('filterTranscriptParts', () => {
+  test('normal hides reasoning, keeps text + tool-calls in order', () => {
+    const result = filterTranscriptParts(PARTS, 'normal');
+    expect(result.map((p) => p.type)).toEqual(['tool-call', 'text', 'text']);
+  });
+
+  test('thinking keeps everything, including reasoning', () => {
+    expect(filterTranscriptParts(PARTS, 'thinking')).toEqual(PARTS);
+  });
+
+  test('verbose also keeps everything (the extra verbosity is a render-detail toggle)', () => {
+    expect(filterTranscriptParts(PARTS, 'verbose')).toEqual(PARTS);
+  });
+
+  test('summary keeps ONLY the last text part', () => {
+    const result = filterTranscriptParts(PARTS, 'summary');
+    expect(result).toEqual([{ type: 'text', text: 'final answer' }]);
+  });
+
+  test('summary with no text parts at all returns empty, not a crash', () => {
+    expect(filterTranscriptParts([{ type: 'tool-call', toolCallId: '1' }], 'summary')).toEqual([]);
+  });
+
+  test('an unrecognized mode fails toward normal (less noise), not everything', () => {
+    expect(filterTranscriptParts(PARTS, 'nonsense')).toEqual(
+      filterTranscriptParts(PARTS, 'normal')
+    );
+  });
+
+  test('tolerates missing/empty input', () => {
+    expect(filterTranscriptParts(undefined, 'normal')).toEqual([]);
+    expect(filterTranscriptParts(null, 'thinking')).toEqual([]);
+    expect(filterTranscriptParts([], 'summary')).toEqual([]);
+  });
+});
+
+describe('transcriptForcesExpand', () => {
+  test('only verbose forces expansion', () => {
+    expect(transcriptForcesExpand('verbose')).toBe(true);
+    expect(transcriptForcesExpand('normal')).toBe(false);
+    expect(transcriptForcesExpand('thinking')).toBe(false);
+    expect(transcriptForcesExpand('summary')).toBe(false);
+    expect(transcriptForcesExpand(undefined)).toBe(false);
+  });
+});
+
+describe('constants', () => {
+  test('the view list + default are stable and consistent', () => {
+    expect(TRANSCRIPT_VIEWS).toEqual(['normal', 'thinking', 'verbose', 'summary']);
+    expect(TRANSCRIPT_VIEWS).toContain(DEFAULT_TRANSCRIPT_VIEW);
+  });
+});

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

@@ -1,11 +1,17 @@
 // 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 { existsSync, 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';
+import {
+  deleteChat,
+  listChats,
+  readChatMessages,
+  readChatMeta,
+  writeChatMeta,
+} from '../acp/transcript.ts';
 
 let root: string;
 afterEach(() => {
@@ -109,6 +115,73 @@ describe('deleteChat', () => {
     expect(listChats(designRoot).length).toBe(0);
     expect(deleteChat(designRoot, 'gone')).toBe(false);
   });
+
+  test('also removes the .meta.json and .session.json sidecars (Task C5)', () => {
+    const designRoot = seed('withmeta', [{ ts: 1, role: 'user', text: 'hi' }]);
+    writeChatMeta(designRoot, 'withmeta', { title: 'Renamed' });
+    writeFileSync(
+      join(designRoot, '_chat', 'withmeta.session.json'),
+      JSON.stringify({ sessionId: 'x' })
+    );
+    expect(deleteChat(designRoot, 'withmeta')).toBe(true);
+    expect(readChatMeta(designRoot, 'withmeta')).toEqual({});
+    expect(existsSync(join(designRoot, '_chat', 'withmeta.session.json'))).toBe(false);
+  });
+});
+
+describe('readChatMeta / writeChatMeta (Task C5 — rename + archive)', () => {
+  test('missing sidecar → {} (no override), never throws', () => {
+    const designRoot = seed('nometa', [{ ts: 1, role: 'user', text: 'hi' }]);
+    expect(readChatMeta(designRoot, 'nometa')).toEqual({});
+  });
+
+  test('a corrupt sidecar degrades to {} rather than throwing', () => {
+    const designRoot = seed('badmeta', [{ ts: 1, role: 'user', text: 'hi' }]);
+    writeFileSync(join(designRoot, '_chat', 'badmeta.meta.json'), '{not valid json');
+    expect(readChatMeta(designRoot, 'badmeta')).toEqual({});
+  });
+
+  test('writeChatMeta sets a title and it wins over the auto-derived one in listChats', () => {
+    const designRoot = seed('rn1', [
+      { ts: 1, role: 'user', text: 'the auto-derived first-line title' },
+    ]);
+    expect(listChats(designRoot)[0]?.title).toBe('the auto-derived first-line title');
+    expect(listChats(designRoot)[0]?.renamed).toBeFalsy();
+    writeChatMeta(designRoot, 'rn1', { title: 'My Renamed Chat' });
+    expect(listChats(designRoot)[0]?.title).toBe('My Renamed Chat');
+    expect(listChats(designRoot)[0]?.renamed).toBe(true);
+    expect(readChatMeta(designRoot, 'rn1')).toEqual({ title: 'My Renamed Chat' });
+  });
+
+  test('writeChatMeta merges — setting archived does not clobber an existing title', () => {
+    const designRoot = seed('rn2', [{ ts: 1, role: 'user', text: 'hi' }]);
+    writeChatMeta(designRoot, 'rn2', { title: 'Kept Title' });
+    writeChatMeta(designRoot, 'rn2', { archived: true });
+    expect(readChatMeta(designRoot, 'rn2')).toEqual({ title: 'Kept Title', archived: true });
+  });
+
+  test('archived chats are excluded from listChats but the transcript survives', () => {
+    const designRoot = seed('arch1', [{ ts: 1, role: 'user', text: 'archive me' }]);
+    writeChatMeta(designRoot, 'arch1', { archived: true });
+    expect(listChats(designRoot)).toEqual([]);
+    expect(readChatMessages(designRoot, 'arch1').length).toBe(1); // still readable directly
+  });
+
+  test('unarchiving (archived: false) brings the chat back into listChats', () => {
+    const designRoot = seed('arch2', [{ ts: 1, role: 'user', text: 'x' }]);
+    writeChatMeta(designRoot, 'arch2', { archived: true });
+    expect(listChats(designRoot)).toEqual([]);
+    writeChatMeta(designRoot, 'arch2', { archived: false });
+    expect(listChats(designRoot).length).toBe(1);
+  });
+
+  test('clearing a title (title: null) falls back to the auto-derived one again', () => {
+    const designRoot = seed('rn3', [{ ts: 1, role: 'user', text: 'original first line' }]);
+    writeChatMeta(designRoot, 'rn3', { title: 'Overridden' });
+    expect(listChats(designRoot)[0]?.title).toBe('Overridden');
+    writeChatMeta(designRoot, 'rn3', { title: null });
+    expect(listChats(designRoot)[0]?.title).toBe('original first line');
+  });
 });
 
 describe('context-hardening projection (feature-acp-context-hardening)', () => {

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

@@ -0,0 +1,136 @@
+// Proves the usage-channel harvest (Milestone D, Task D1) end-to-end against
+// a mock ACP agent (fixtures/mock-acp-agent-usage.mjs) — no real `claude`
+// needed. Covers: onUsage fires with {used,size,cost}, the rate-limit _meta
+// payload is carried through opaque, usage_update never leaks into onUpdate
+// (chrome, not turn content), and the Acp manager caches + replays it to a
+// freshly-opened socket.
+
+import { afterEach, describe, expect, test } from 'bun:test';
+import { join } from 'node:path';
+
+import type { ServerWebSocket } from 'bun';
+
+import { AcpBridge, type BridgeUsage } from '../acp/bridge.ts';
+import { createAcp } from '../acp/index.ts';
+import type { Context } from '../context.ts';
+import type { WsData } from '../ws.ts';
+
+const FIXTURE = join(import.meta.dir, 'fixtures', 'mock-acp-agent-usage.mjs');
+const TEST_ENV_KEYS = ['MAUDE_ACP_ADAPTER_ENTRY', 'MAUDE_ACP_RUNTIME', 'MAUDE_CLAUDE_BIN'];
+
+function useMockAgent() {
+  process.env.MAUDE_ACP_ADAPTER_ENTRY = FIXTURE;
+  process.env.MAUDE_ACP_RUNTIME = process.execPath;
+  process.env.MAUDE_CLAUDE_BIN = process.execPath;
+}
+
+afterEach(() => {
+  for (const key of TEST_ENV_KEYS) delete process.env[key];
+});
+
+async function until<T>(fn: () => T | undefined, timeoutMs = 12000): Promise<T> {
+  const start = performance.now();
+  for (;;) {
+    const v = fn();
+    if (v !== undefined) return v;
+    if (performance.now() - start > timeoutMs) throw new Error('timeout waiting for condition');
+    await new Promise((r) => setTimeout(r, 25));
+  }
+}
+
+function fakeWs(id: string) {
+  const frames: Array<Record<string, unknown>> = [];
+  const ws = {
+    data: { id } as WsData,
+    send: (raw: string) => {
+      frames.push(JSON.parse(raw));
+    },
+  } as unknown as ServerWebSocket<WsData>;
+  return { ws, frames };
+}
+
+describe('AcpBridge — usage harvest (Task D1)', () => {
+  test('onUsage fires with used/size/cost; usage_update never reaches onUpdate', async () => {
+    useMockAgent();
+    const usages: BridgeUsage[] = [];
+    const updates: unknown[] = [];
+    const bridge = new AcpBridge({
+      repoRoot: process.cwd(),
+      onUpdate: (u) => updates.push(u),
+      onUsage: (u) => usages.push(u),
+    });
+    try {
+      await bridge.prompt('hi', 'c1');
+      const usage = await until(() => (usages.length ? usages[usages.length - 1] : undefined));
+      expect(usage.used).toBe(4200);
+      expect(usage.size).toBe(200000);
+      expect(usage.cost).toEqual({ amount: 0.0123, currency: 'USD' });
+      expect(bridge.usage).toEqual(usage);
+      // chrome, not turn content — no usage_update leaked into onUpdate
+      expect(
+        updates.some((u) => (u as { sessionUpdate?: string }).sessionUpdate === 'usage_update')
+      ).toBe(false);
+    } finally {
+      await bridge.stop();
+    }
+  }, 15000);
+
+  test('the rate-limit _meta payload is carried through opaque', async () => {
+    useMockAgent();
+    const usages: BridgeUsage[] = [];
+    const bridge = new AcpBridge({
+      repoRoot: process.cwd(),
+      onUpdate: () => {},
+      onUsage: (u) => usages.push(u),
+    });
+    try {
+      await bridge.prompt('trigger-rate-limit', 'c1');
+      const withRateLimit = await until(() => usages.find((u) => u.rateLimit != null));
+      expect(withRateLimit.rateLimit).toMatchObject({
+        status: 'allowed_warning',
+        rateLimitType: 'five_hour',
+        utilization: 82,
+      });
+    } finally {
+      await bridge.stop();
+    }
+  }, 15000);
+
+  test('no usage yet → bridge.usage is null', async () => {
+    useMockAgent();
+    const bridge = new AcpBridge({ repoRoot: process.cwd(), onUpdate: () => {} });
+    try {
+      expect(bridge.usage).toBeNull();
+    } finally {
+      await bridge.stop();
+    }
+  }, 15000);
+});
+
+describe('Acp manager — usage frame is cached + replayed on a fresh socket (Task D1)', () => {
+  test('a usage frame is broadcast during a turn, then replayed to a newly-opened socket', async () => {
+    useMockAgent();
+    const ctx = {
+      paths: { repoRoot: process.cwd(), designRoot: '/tmp/does-not-matter-usage' },
+    } as unknown as Context;
+    const acp = createAcp(ctx);
+
+    const a = fakeWs('usage-ws-a');
+    try {
+      acp.onOpen(a.ws);
+      acp.onMessage(a.ws, JSON.stringify({ t: 'prompt', text: 'hi', chat: 'c1' }));
+      const usageFrame = await until(() => a.frames.find((f) => f.t === 'usage'));
+      expect((usageFrame.usage as BridgeUsage).used).toBe(4200);
+
+      const b = fakeWs('usage-ws-b');
+      acp.onOpen(b.ws);
+      const replay = b.frames.find((f) => f.t === 'usage');
+      if (!replay) throw new Error('expected a replayed usage frame');
+      expect((replay.usage as BridgeUsage).used).toBe(4200);
+      acp.onClose(b.ws);
+    } finally {
+      acp.onClose(a.ws);
+      await new Promise((r) => setTimeout(r, 50));
+    }
+  }, 20000);
+});

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

@@ -0,0 +1,143 @@
+// Pure unit tests for client/panels/acp-usage.js — parseUsage (Tasks D2/D4).
+
+import { describe, expect, test } from 'bun:test';
+
+import { parseUsage } from '../client/panels/acp-usage.js';
+
+const NOW = 1_700_000_000_000;
+
+describe('parseUsage — context + cost', () => {
+  test('computes a rounded percentage from used/size', () => {
+    const result = parseUsage({ t: 'usage', usage: { used: 4200, size: 200000 } }, NOW);
+    expect(result.context).toEqual({ used: 4200, size: 200000, pct: 2 });
+    expect(result.asOf).toBe(NOW);
+  });
+
+  test('clamps the percentage to [0,100] against a bogus used > size', () => {
+    const result = parseUsage({ usage: { used: 999999, size: 1000 } }, NOW);
+    expect(result.context?.pct).toBe(100);
+  });
+
+  test('size:0 (or missing) yields no context gauge rather than dividing by zero', () => {
+    expect(parseUsage({ usage: { used: 10, size: 0 } }, NOW).context).toBeNull();
+    expect(parseUsage({ usage: { used: 10 } }, NOW).context).toBeNull();
+  });
+
+  test('carries cost through, defaulting currency to USD when absent', () => {
+    const result = parseUsage(
+      { usage: { used: 1, size: 2, cost: { amount: 0.5, currency: 'EUR' } } },
+      NOW
+    );
+    expect(result.cost).toEqual({ amount: 0.5, currency: 'EUR' });
+  });
+
+  test('no cost on the frame → null, not undefined/0', () => {
+    expect(parseUsage({ usage: { used: 1, size: 2 } }, NOW).cost).toBeNull();
+  });
+});
+
+describe('parseUsage — rate limit (SDKRateLimitInfo fixtures)', () => {
+  const TYPES = [
+    ['five_hour', '5-hour limit'],
+    ['seven_day', 'Weekly limit'],
+    ['seven_day_opus', 'Weekly · Opus'],
+    ['seven_day_sonnet', 'Weekly · Sonnet'],
+    ['seven_day_overage_included', 'Weekly (overage included)'],
+    ['overage', 'Overage'],
+  ];
+
+  for (const [type, label] of TYPES) {
+    test(`maps rateLimitType "${type}" → "${label}"`, () => {
+      const result = parseUsage(
+        {
+          usage: {
+            used: 1,
+            size: 2,
+            rateLimit: {
+              status: 'allowed_warning',
+              rateLimitType: type,
+              utilization: 61,
+              resetsAt: 123,
+            },
+          },
+        },
+        NOW
+      );
+      expect(result.rateLimit).toEqual({
+        type,
+        label,
+        pct: 61,
+        resetsAt: 123,
+        status: 'allowed_warning',
+      });
+    });
+  }
+
+  test('an unrecognized rateLimitType falls back to a generic label, not undefined', () => {
+    const result = parseUsage(
+      {
+        usage: {
+          used: 1,
+          size: 2,
+          rateLimit: { status: 'rejected', rateLimitType: 'something_new' },
+        },
+      },
+      NOW
+    );
+    expect(result.rateLimit?.label).toBe('Usage limit');
+  });
+
+  test('null/missing rate-limit on the frame → gauge-only (rateLimit: null), no crash', () => {
+    expect(parseUsage({ usage: { used: 1, size: 2, rateLimit: null } }, NOW).rateLimit).toBeNull();
+    expect(parseUsage({ usage: { used: 1, size: 2 } }, NOW).rateLimit).toBeNull();
+  });
+
+  test('utilization/resetsAt clamp + tolerate missing fields', () => {
+    const result = parseUsage(
+      { usage: { used: 1, size: 2, rateLimit: { status: 'allowed', utilization: 250 } } },
+      NOW
+    );
+    expect(result.rateLimit).toEqual({
+      type: null,
+      label: 'Usage limit',
+      pct: 100,
+      resetsAt: null,
+      status: 'allowed',
+    });
+  });
+});
+
+describe('parseUsage — malformed input tolerance', () => {
+  test('missing usage entirely → all-null shape, never throws', () => {
+    expect(parseUsage({}, NOW)).toEqual({ context: null, cost: null, rateLimit: null, asOf: NOW });
+    expect(parseUsage(undefined, NOW)).toEqual({
+      context: null,
+      cost: null,
+      rateLimit: null,
+      asOf: NOW,
+    });
+    expect(parseUsage(null, NOW)).toEqual({
+      context: null,
+      cost: null,
+      rateLimit: null,
+      asOf: NOW,
+    });
+  });
+
+  test('a malformed _meta-derived rateLimit (not an object) is tolerated', () => {
+    expect(() =>
+      parseUsage({ usage: { used: 1, size: 2, rateLimit: 'not-an-object' } }, NOW)
+    ).not.toThrow();
+    expect(
+      parseUsage({ usage: { used: 1, size: 2, rateLimit: 'not-an-object' } }, NOW).rateLimit
+    ).toBeNull();
+  });
+
+  test('defaults `now` to Date.now() when not injected', () => {
+    const before = Date.now();
+    const result = parseUsage({ usage: { used: 1, size: 2 } });
+    const after = Date.now();
+    expect(result.asOf).toBeGreaterThanOrEqual(before);
+    expect(result.asOf).toBeLessThanOrEqual(after);
+  });
+});

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

@@ -5,6 +5,7 @@ import { describe, expect, test } from 'bun:test';
 import {
   computeSnap,
   GRID_PITCH_PX,
+  type GuideLineCandidate,
   SNAP_THRESHOLD_PX,
   type SnapBox,
 } from '../annotations-snap.ts';
@@ -77,3 +78,58 @@ describe('computeSnap', () => {
     expect(res.dy).toBe(0);
   });
 });
+
+// feature-1-artboard-kinds-foundation, T7 — generic-layout-guide lines feed
+// the same candidate pool as stroke/artboard bboxes.
+describe('computeSnap / guide lines (T7)', () => {
+  test('leading edge snaps to a guide line within threshold', () => {
+    const guideLines: GuideLineCandidate[] = [{ axis: 'x', at: 100, from: 0, to: 1000 }];
+    const res = computeSnap(box(104, 300), [], SNAP_THRESHOLD_PX, { guideLines });
+    expect(res.dx).toBe(-4);
+    expect(res.guides).toHaveLength(1);
+    expect(res.guides[0]).toMatchObject({ axis: 'x', at: 100, from: 0, to: 1000 });
+  });
+
+  test('center also tests against a guide line', () => {
+    // moving center x = 153, guide at 150 → dx -3.
+    const guideLines: GuideLineCandidate[] = [{ axis: 'y', at: 350, from: 0, to: 1000 }];
+    const res = computeSnap(box(103, 300), [], SNAP_THRESHOLD_PX, { guideLines });
+    // center y = 350, guide at 350 → dy 0 (exact), still emits a guide.
+    expect(res.dy).toBe(0);
+    expect(res.guides.find((g) => g.axis === 'y')).toMatchObject({ at: 350 });
+  });
+
+  test('nearest-wins applies across BOTH sources — a closer guide beats a farther candidate', () => {
+    const guideLines: GuideLineCandidate[] = [{ axis: 'x', at: 105, from: 0, to: 1000 }];
+    const res = computeSnap(box(104, 300), [box(100, 0)], SNAP_THRESHOLD_PX, { guideLines });
+    // candidate edge (100) is 4 away; guide (105) is 1 away — guide wins.
+    expect(res.dx).toBe(1);
+  });
+
+  test('a closer stroke/artboard candidate beats a farther guide line', () => {
+    // candidate edge (100) is 4 away from x=104; guide (110) is 6 away — the
+    // candidate is strictly closer, so it wins even though the guide is
+    // still within the 6px threshold.
+    const guideLines: GuideLineCandidate[] = [{ axis: 'x', at: 110, from: 0, to: 1000 }];
+    const res = computeSnap(box(104, 300), [box(100, 0)], SNAP_THRESHOLD_PX, { guideLines });
+    expect(res.dx).toBe(-4);
+  });
+
+  test('outside threshold, a guide line is ignored', () => {
+    const guideLines: GuideLineCandidate[] = [{ axis: 'x', at: 500, from: 0, to: 1000 }];
+    const res = computeSnap(box(104, 300), [], SNAP_THRESHOLD_PX, { guideLines });
+    expect(res.dx).toBe(0);
+    expect(res.guides).toHaveLength(0);
+  });
+
+  test('guide-line snap composes with the grid fallback on the OTHER axis', () => {
+    // x snaps to the guide line; y has no candidate → grid fallback fires.
+    const guideLines: GuideLineCandidate[] = [{ axis: 'x', at: 100, from: 0, to: 1000 }];
+    const res = computeSnap(box(104, 50), [], SNAP_THRESHOLD_PX, {
+      guideLines,
+      grid: GRID_PITCH_PX,
+    });
+    expect(res.dx).toBe(-4);
+    expect(res.dy).toBe(-2);
+  });
+});