@1agh/maude 0.30.0 → 0.31.0

package/apps/studio/test/chat-markdown.test.tsx

@@ -0,0 +1,58 @@
+// chat-markdown — Phase 31. The ACP chat feed's compact, XSS-safe markdown
+// renderer. Builds React nodes (never innerHTML), so we assert the rendered
+// markup + that unsafe link schemes are dropped.
+
+import { describe, expect, test } from 'bun:test';
+import { renderToStaticMarkup } from 'react-dom/server';
+
+import { Markdown } from '../client/panels/chat-markdown.jsx';
+
+const html = (text: string) => renderToStaticMarkup(<Markdown text={text} />);
+
+describe('chat-markdown', () => {
+  test('inline bold / italic / code', () => {
+    const out = html('Use **bold**, *italic* and `code` here.');
+    expect(out).toContain('<strong>bold</strong>');
+    expect(out).toContain('<em>italic</em>');
+    expect(out).toContain('<code>code</code>');
+  });
+
+  test('fenced code block', () => {
+    const out = html('text\n```\nconst x = 1;\n```\nmore');
+    expect(out).toContain('class="chat-code"');
+    expect(out).toContain('const x = 1;');
+  });
+
+  test('bullet + numbered lists', () => {
+    const bullet = html('- one\n- two');
+    expect(bullet).toContain('<ul class="chat-md-list">');
+    expect(bullet).toContain('<li>one</li>');
+    const ordered = html('1. first\n2. second');
+    expect(ordered).toContain('<ol class="chat-md-list">');
+    expect(ordered).toContain('<li>first</li>');
+  });
+
+  test('headings render as styled paragraphs (no giant h1)', () => {
+    const out = html('## Section');
+    expect(out).toContain('class="chat-md-h"');
+    expect(out).toContain('Section');
+    expect(out).not.toContain('<h1');
+  });
+
+  test('http(s) links are kept, unsafe schemes are dropped to text', () => {
+    const safe = html('see [Anthropic](https://anthropic.com)');
+    expect(safe).toContain('href="https://anthropic.com"');
+    expect(safe).toContain('rel="noreferrer noopener"');
+
+    const unsafe = html('[click](javascript:alert(1))');
+    expect(unsafe).not.toContain('javascript:');
+    expect(unsafe).not.toContain('<a ');
+    expect(unsafe).toContain('click'); // falls back to plain text
+  });
+
+  test('plain text passes through as a paragraph', () => {
+    const out = html('just a line');
+    expect(out).toContain('class="chat-md-p"');
+    expect(out).toContain('just a line');
+  });
+});

package/apps/studio/test/collab-session-survival.test.tsx

@@ -0,0 +1,176 @@
+// Collab session survives a canvas hot-swap remount — F4 regression.
+//
+// RCA: `.ai/logs/rca/issue-collab-observer-tsx-reload-flicker.md`. A cross-peer
+// synced edit hot-swaps the canvas module in place, which REMOUNTS the whole
+// canvas subtree — including <CollabProvider>. If the Y.Doc + Awareness + socket
+// were per-component, that remount would close + re-handshake the awareness
+// socket and every peer's cursor/avatar would blink. The fix makes the session
+// a module-level, refcounted singleton keyed by slug, so a same-slug remount
+// reuses the SAME live socket + Awareness (stable clientID → the server never
+// sees the peer leave + rejoin → no blink).
+//
+// We register happy-dom (error boundaries / real createRoot need a live DOM,
+// like canvas-hmr-runtime.test.tsx) and stub WebSocket + fetch.
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'bun:test';
+import { GlobalRegistrator } from '@happy-dom/global-registrator';
+
+beforeAll(() => {
+  GlobalRegistrator.register();
+  (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+});
+afterAll(() => {
+  GlobalRegistrator.unregister();
+});
+
+import { act, createElement, useEffect } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import type * as Y from 'yjs';
+
+import { CollabProvider, useCollab } from '../use-collab.tsx';
+
+// ── Fake WebSocket: count constructions + closes; never touches the network ──
+let wsConstructed = 0;
+let wsClosed = 0;
+class FakeWS {
+  static OPEN = 1;
+  static CLOSING = 2;
+  static CLOSED = 3;
+  readyState = 1; // OPEN immediately — the provider only broadcasts when OPEN
+  url: string;
+  private handlers: Record<string, Array<(e: unknown) => void>> = {};
+  constructor(url: string) {
+    this.url = url;
+    wsConstructed++;
+    // Fire `open` on the next microtask so the provider's open handler runs.
+    queueMicrotask(() => this.dispatch('open', {}));
+  }
+  addEventListener(type: string, fn: (e: unknown) => void) {
+    const bucket = this.handlers[type] ?? [];
+    bucket.push(fn);
+    this.handlers[type] = bucket;
+  }
+  removeEventListener() {}
+  send() {}
+  close() {
+    if (this.readyState === FakeWS.CLOSED) return;
+    this.readyState = FakeWS.CLOSED;
+    wsClosed++;
+    this.dispatch('close', {});
+  }
+  private dispatch(type: string, e: unknown) {
+    for (const fn of this.handlers[type] ?? []) fn(e);
+  }
+}
+
+const realWebSocket = globalThis.WebSocket;
+const realFetch = globalThis.fetch;
+
+beforeAll(() => {
+  (globalThis as unknown as { WebSocket: unknown }).WebSocket = FakeWS;
+  (globalThis as unknown as { fetch: unknown }).fetch = () =>
+    Promise.resolve({ json: () => Promise.resolve({ name: 'Tester' }) });
+});
+afterAll(() => {
+  (globalThis as unknown as { WebSocket: unknown }).WebSocket = realWebSocket;
+  (globalThis as unknown as { fetch: unknown }).fetch = realFetch;
+});
+
+afterEach(() => {
+  wsConstructed = 0;
+  wsClosed = 0;
+});
+
+// Captures the live doc + awareness clientID for the mounted provider.
+let captured: { doc: Y.Doc; clientID: number } | null = null;
+function Probe() {
+  const collab = useCollab();
+  useEffect(() => {
+    if (collab) captured = { doc: collab.doc, clientID: collab.awareness.clientID };
+  });
+  return null;
+}
+
+function mount(el: HTMLElement): Root {
+  let root!: Root;
+  act(() => {
+    root = createRoot(el);
+  });
+  return root;
+}
+
+function renderProvider(root: Root, slug: string) {
+  act(() => {
+    root.render(createElement(CollabProvider, { slug }, createElement(Probe)));
+  });
+}
+
+describe('collab session survival across a hot-swap remount', () => {
+  test('a same-slug remount reuses the live socket + Awareness (no reconnect)', () => {
+    captured = null;
+    const host = document.createElement('div');
+    const root = mount(host);
+
+    renderProvider(root, 'survival-slug');
+    expect(wsConstructed).toBe(1);
+    const first = captured;
+    expect(first).not.toBeNull();
+
+    // Hot-swap = unmount the canvas subtree, then immediately remount the SAME
+    // slug (what CanvasHmrRuntime's key=attempt does on a synced module swap).
+    act(() => {
+      root.render(createElement('div', null));
+    });
+    renderProvider(root, 'survival-slug');
+
+    // The session was reused within the grace window — NO second socket, and the
+    // SAME doc + Awareness clientID (the server never saw a leave/rejoin).
+    expect(wsConstructed).toBe(1);
+    expect(wsClosed).toBe(0);
+    expect(captured?.doc).toBe(first?.doc);
+    expect(captured?.clientID).toBe(first?.clientID);
+
+    act(() => root.unmount());
+  });
+
+  test('the session registry is anchored on window under a non-enumerable Symbol', () => {
+    // A hot-swap re-imports the canvas bundle with a `?v=` cache-buster, and
+    // use-collab is INLINED into that bundle — so a module-scoped `const
+    // SESSIONS = new Map()` would be FRESH (empty) on every hot-swap and spin a
+    // new clientID each time (phantom self-avatars pile up). Anchoring the map
+    // on `window` (under a global Symbol so the re-imported module resolves the
+    // same key) is what makes the session survive the swap. This pins that
+    // invariant — the registry holds the slug — AND the security posture: the
+    // key is a NON-ENUMERABLE Symbol so untrusted same-realm canvas script can't
+    // harvest the live network handles via a for-in / Object.keys sweep.
+    captured = null;
+    const host = document.createElement('div');
+    const root = mount(host);
+    renderProvider(root, 'window-anchored-slug');
+    const w = window as unknown as Record<symbol, Map<string, unknown> | undefined>;
+    const reg = w[Symbol.for('maude.collab.sessions.v1')];
+    expect(reg).toBeInstanceOf(Map);
+    expect(reg?.has('window-anchored-slug')).toBe(true);
+    // Not reachable via string-key enumeration (defense in depth).
+    expect(Object.keys(window)).not.toContain('__maudeCollabSessions');
+    act(() => root.unmount());
+  });
+
+  test('a different slug opens its own session (no cross-slug sharing)', () => {
+    captured = null;
+    const host = document.createElement('div');
+    const root = mount(host);
+
+    renderProvider(root, 'slug-a');
+    const a = captured;
+    renderProvider(root, 'slug-b');
+    const b = captured;
+
+    // slug-b reuses slug-a's <CollabProvider> instance but a NEW session →
+    // a second socket + a distinct doc.
+    expect(wsConstructed).toBe(2);
+    expect(b?.doc).not.toBe(a?.doc);
+
+    act(() => root.unmount());
+  });
+});

package/apps/studio/test/csrf-write-guard.test.ts

@@ -15,6 +15,8 @@
 // race unrelated to this guard. See the Phase 12.2 validate notes.)
 
 import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 
 import { sameOriginWrite } from '../http.ts';
 
@@ -50,3 +52,27 @@ describe('CSRF Origin guard — sameOriginWrite (DDR-105)', () => {
     expect(sameOriginWrite(post('not a url'))).toBe(false);
   });
 });
+
+// phase-30 / DDR-120: the ai-activity bridge now projects `/_api/ai/*` POSTs
+// onto room awareness, which crosses the hub to every connected peer. So a
+// forged cross-origin POST to /start /heartbeat /end is no longer a harmless
+// loopback banner — it injects a fake "<x> is editing <slug>" presence to all
+// peers (the channel that drives the social save/publish decision). These three
+// routes MUST carry the same `sameOriginWrite` guard as the other write routes.
+// Source-level assertion (same "don't boot a server" rationale as above): pin
+// the guard into each route block so an accidental removal fails CI.
+describe('CSRF Origin guard — /_api/ai/* presence-bridge routes (phase-30)', () => {
+  const src = readFileSync(fileURLToPath(new URL('../http.ts', import.meta.url)), 'utf8');
+
+  for (const route of ['/_api/ai/start', '/_api/ai/heartbeat', '/_api/ai/end']) {
+    test(`${route} is wired with the sameOriginWrite CSRF guard`, () => {
+      // Slice from this route's key to the next route key, then assert the guard
+      // appears inside that block.
+      const start = src.indexOf(`'${route}':`);
+      expect(start).toBeGreaterThan(-1);
+      const after = src.indexOf("'/_api/", start + 1);
+      const block = src.slice(start, after === -1 ? undefined : after);
+      expect(block).toContain('sameOriginWrite(req)');
+    });
+  }
+});

package/apps/studio/test/editing-presence.test.ts

@@ -0,0 +1,103 @@
+// Unit: soft editing-presence (Phase 30) — the `editing` awareness field at the
+// hub trust boundary. Locking is deliberately NOT built (no lease/takeover); the
+// `editing` field is a soft heads-up. Every foreign value is attacker-influenceable
+// through the semi-trusted hub (DDR-054), so it MUST be validated for VALUE — a
+// future / NaN / non-positive `since` is rejected so a hostile peer can't pin a
+// permanent badge or poison a `Date.now() - since` age computation.
+
+import { describe, expect, test } from 'bun:test';
+
+import { createRoom, type RoomCallbacks } from '../collab/room.ts';
+import { sanitizeForeignState } from '../use-collab.tsx';
+
+const noopCallbacks: RoomCallbacks = {
+  seed() {},
+  persistJson() {},
+  persistBinary() {},
+};
+
+describe('sanitizeForeignState — editing field (Phase 30)', () => {
+  test('keeps a valid current `editing.since`', () => {
+    const now = Date.now();
+    const peer = sanitizeForeignState(3, { name: 'Anna', editing: { since: now } });
+    expect(peer?.editing).toEqual({ since: now });
+  });
+
+  test('absent editing → null (peer is not editing)', () => {
+    const peer = sanitizeForeignState(3, { name: 'Anna' });
+    expect(peer?.editing).toBeNull();
+  });
+
+  test('rejects a FUTURE since beyond the ±5s skew window (no permanent-badge pin)', () => {
+    const future = Date.now() + 60_000;
+    const peer = sanitizeForeignState(3, { name: 'Anna', editing: { since: future } });
+    expect(peer?.editing).toBeNull();
+  });
+
+  test('allows a near-future since inside the 5s skew window', () => {
+    const skew = Date.now() + 3_000;
+    const peer = sanitizeForeignState(3, { name: 'Anna', editing: { since: skew } });
+    expect(peer?.editing).toEqual({ since: skew });
+  });
+
+  test('rejects NaN / Infinity / non-positive since (no Date-math poison)', () => {
+    for (const bad of [Number.NaN, Number.POSITIVE_INFINITY, 0, -1]) {
+      const peer = sanitizeForeignState(3, { name: 'Anna', editing: { since: bad } });
+      expect(peer?.editing).toBeNull();
+    }
+  });
+
+  test('rejects a non-object / malformed editing payload', () => {
+    expect(sanitizeForeignState(3, { name: 'Anna', editing: 'now' })?.editing).toBeNull();
+    expect(sanitizeForeignState(3, { name: 'Anna', editing: 12345 })?.editing).toBeNull();
+    expect(sanitizeForeignState(3, { name: 'Anna', editing: {} })?.editing).toBeNull();
+    expect(sanitizeForeignState(3, { name: 'Anna', editing: { since: '5' } })?.editing).toBeNull();
+  });
+
+  test('editing presence does not disturb the other sanitized fields', () => {
+    const peer = sanitizeForeignState(9, {
+      name: 'Anna',
+      cursor: { x: 1, y: 2 },
+      editing: { since: Date.now() },
+    });
+    expect(peer?.name).toBe('Anna');
+    expect(peer?.cursor).toEqual({ x: 1, y: 2 });
+    expect(peer?.editing).not.toBeNull();
+  });
+});
+
+describe('room.setAgentEditing — agent presence projected onto awareness (Phase 30)', () => {
+  test('projects an editing state that a remote peer can sanitize, then clears it', async () => {
+    const room = createRoom('agent-editing-slug', noopCallbacks);
+    const since = Date.now();
+
+    room.setAgentEditing({ name: 'Anna', since });
+    const states = Array.from(room.awareness.getStates().values());
+    expect(states.length).toBe(1);
+    // The projected state survives the client trust-boundary sanitizer with the
+    // editing field intact (name → re-derived color; since preserved).
+    const sanitized = sanitizeForeignState(1, states[0]);
+    expect(sanitized?.name).toBe('Anna');
+    expect(sanitized?.editing).toEqual({ since });
+
+    room.setAgentEditing(null);
+    expect(room.awareness.getStates().size).toBe(0);
+
+    await room.destroy();
+  });
+
+  test('re-setting the same {name, since} is a no-op (heartbeat re-emit guard)', async () => {
+    const room = createRoom('agent-editing-idempotent', noopCallbacks);
+    const since = Date.now();
+    let updates = 0;
+    room.awareness.on('update', () => {
+      updates += 1;
+    });
+
+    room.setAgentEditing({ name: 'Anna', since });
+    room.setAgentEditing({ name: 'Anna', since }); // identical → no second update
+    expect(updates).toBe(1);
+
+    await room.destroy();
+  });
+});

package/apps/studio/test/fixtures/mock-acp-agent.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env bun
+// Mock ACP agent for acp/bridge.test.ts. Stands in for `claude-agent-acp` so the
+// bridge can be exercised without a real `claude` install. Implements the
+// minimal handshake (initialize + session/new + session/prompt) and streams one
+// `agent_message_chunk` whose text echoes whether ANTHROPIC_API_KEY survived
+// into the child env — it MUST read `<unset>`, proving scrubAgentEnv (DDR-123
+// guardrail #1) stripped it before spawn.
+
+import { Readable, Writable } from 'node:stream';
+
+import * as acp from '@agentclientprotocol/sdk';
+
+const stream = acp.ndJsonStream(Writable.toWeb(process.stdout), Readable.toWeb(process.stdin));
+
+acp
+  .agent({ name: 'mock-acp-agent' })
+  .onRequest('initialize', () => ({
+    protocolVersion: acp.PROTOCOL_VERSION,
+    agentCapabilities: { loadSession: false },
+  }))
+  .onRequest(
+    'session/new',
+    (() => {
+      let n = 0;
+      return () => ({ sessionId: `mock-session-${++n}` });
+    })()
+  )
+  .onRequest('session/prompt', async (ctx) => {
+    // The per-request handler context exposes the client connection at `.client`.
+    await ctx.client.notify('session/update', {
+      sessionId: ctx.params.sessionId,
+      update: {
+        sessionUpdate: 'agent_message_chunk',
+        content: {
+          type: 'text',
+          text:
+            `apiKey=${process.env.ANTHROPIC_API_KEY ?? '<unset>'} ` +
+            `model=${process.env.ANTHROPIC_MODEL ?? '<unset>'} ` +
+            `thinking=${process.env.MAX_THINKING_TOKENS ?? '<unset>'}`,
+        },
+      },
+    });
+    return { stopReason: 'end_turn' };
+  })
+  .connect(stream);

package/apps/studio/test/git-branches.test.ts

@@ -0,0 +1,106 @@
+// Phase 29 (E4) — drafts (branches). List / create / switch against a REAL local
+// git repo via the default isomorphic-git engine (no network). The vocabulary
+// mapping (draft=branch, "Shared version"=main) lives in the UI; this proves the
+// plumbing + the dash-led / duplicate / dirty-tree guards.
+
+import { afterEach, beforeEach, expect, test } from 'bun:test';
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { gitCheckout, gitCreateBranch, gitFoldDraft, gitListBranches } from '../git/service.ts';
+
+let dir: string;
+
+function sh(args: string[]): void {
+  const p = Bun.spawnSync(['git', ...args], {
+    cwd: dir,
+    env: { ...process.env, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_SYSTEM: '/dev/null' },
+  });
+  if (p.exitCode !== 0) throw new Error(`git ${args.join(' ')}: ${p.stderr.toString()}`);
+}
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'maude-drafts-'));
+  sh(['init', '-q']);
+  sh(['config', 'user.email', 't@t.dev']);
+  sh(['config', 'user.name', 'Tester']);
+  writeFileSync(join(dir, 'a.txt'), 'hello\n');
+  sh(['add', '.']);
+  sh(['commit', '-q', '-m', 'init']);
+});
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+test('lists the default branch as current', async () => {
+  const branches = await gitListBranches(dir);
+  expect(branches.length).toBe(1);
+  expect(branches[0].current).toBe(true);
+  expect(['main', 'master']).toContain(branches[0].name);
+});
+
+test('creates a new draft off HEAD and switches to it', async () => {
+  const res = await gitCreateBranch(dir, 'nav-redesign');
+  expect(res.ok).toBe(true);
+  expect(res.branch).toBe('nav-redesign');
+  const branches = await gitListBranches(dir);
+  const cur = branches.find((b) => b.current);
+  expect(cur?.name).toBe('nav-redesign');
+  expect(branches.map((b) => b.name).sort()).toContain('nav-redesign');
+});
+
+test('switches back to the shared version', async () => {
+  const before = await gitListBranches(dir);
+  const shared = before[0].name; // main/master
+  await gitCreateBranch(dir, 'pricing-experiment');
+  const res = await gitCheckout(dir, shared);
+  expect(res.ok).toBe(true);
+  const cur = (await gitListBranches(dir)).find((b) => b.current);
+  expect(cur?.name).toBe(shared);
+});
+
+test('rejects a dash-led / malformed draft name (argv-injection guard)', async () => {
+  const r1 = await gitCreateBranch(dir, '--upload-pack=evil');
+  expect(r1.ok).toBe(false);
+  const r2 = await gitCreateBranch(dir, 'has spaces');
+  expect(r2.ok).toBe(false);
+});
+
+test('fold: rejects a draft that does not exist', async () => {
+  const r = await gitFoldDraft(dir, 'ghost', undefined, {});
+  expect(r.ok).toBe(false);
+  expect(r.error).toMatch(/doesn't exist/i);
+});
+
+test('fold: rejects folding the Shared version into itself', async () => {
+  const shared = (await gitListBranches(dir)).find((b) => b.current)?.name as string;
+  const r = await gitFoldDraft(dir, shared, undefined, {});
+  expect(r.ok).toBe(false);
+  expect(r.error).toMatch(/already the Shared version/i);
+});
+
+test('fold: merges the draft into the Shared version locally; a tokenless publish leaves the draft intact', async () => {
+  const shared = (await gitListBranches(dir)).find((b) => b.current)?.name as string;
+  await gitCreateBranch(dir, 'nav'); // checks out 'nav'
+  writeFileSync(join(dir, 'b.txt'), 'draft work\n');
+  sh(['add', '.']);
+  sh(['commit', '-q', '-m', 'draft work']);
+  const r = await gitFoldDraft(dir, 'nav', undefined, {});
+  // No token/remote → the publish step returns authRequired, so the draft is NOT removed…
+  expect(r.ok).toBe(false);
+  expect(r.authRequired).toBe(true);
+  // …but the merge landed: the Shared version (now checked out) contains the draft's file…
+  expect(existsSync(join(dir, 'b.txt'))).toBe(true);
+  expect((await gitListBranches(dir)).find((b) => b.current)?.name).toBe(shared);
+  // …and the draft still exists (not deleted on a failed publish).
+  expect((await gitListBranches(dir)).some((b) => b.name === 'nav')).toBe(true);
+});
+
+test('rejects creating a draft that already exists', async () => {
+  await gitCreateBranch(dir, 'dupe');
+  // back to a fresh ref first so create (which checks out) has a clean base
+  const shared = (await gitListBranches(dir)).find((b) => !b.current);
+  if (shared) await gitCheckout(dir, shared.name);
+  const r = await gitCreateBranch(dir, 'dupe');
+  expect(r.ok).toBe(false);
+  expect(r.error).toMatch(/already exists/i);
+});

package/apps/studio/test/git-grouping.test.ts

@@ -0,0 +1,106 @@
+// DDR-115 follow-up — Changes-panel canvas grouping (GitPanel variant A).
+// Verifies the pure grouping helpers: a canvas unifies with its same-stem
+// `.meta.json` + its slug-named `.annotations.svg`; loose / orphan files become
+// standalone "other" units; sort + slug-matching (spaces, subdirs) are correct.
+
+import { describe, expect, test } from 'bun:test';
+
+import { baseName, buildUnits, canvasSlug, supportLabel } from '../client/panels/git-grouping.js';
+
+const F = (path: string, status = 'modified') => ({ path, status });
+
+describe('GitPanel canvas grouping (buildUnits)', () => {
+  test('unifies a canvas with its same-stem meta and slug-matched annotation', () => {
+    const files = [
+      F('.design/ui/Pricing.tsx'),
+      F('.design/ui/Pricing.meta.json'),
+      F('.design/ui-pricing.annotations.svg'),
+    ];
+    const { canvasUnits, otherUnits } = buildUnits(files, '.design');
+    expect(canvasUnits.length).toBe(1);
+    expect(otherUnits.length).toBe(0);
+    const u = canvasUnits[0];
+    expect(u.primary.path).toBe('.design/ui/Pricing.tsx');
+    expect(u.supporting.map((s) => s.path).sort()).toEqual([
+      '.design/ui-pricing.annotations.svg',
+      '.design/ui/Pricing.meta.json',
+    ]);
+  });
+
+  test('canvas with spaces + subdir matches its annotation slug', () => {
+    // fileSlug('.design/ui/Sync Hub Admin.tsx') => 'ui-sync_hub_admin'
+    expect(canvasSlug('.design/ui/Sync Hub Admin.tsx', '.design')).toBe('ui-sync_hub_admin');
+    const files = [
+      F('.design/ui/Sync Hub Admin.tsx'),
+      F('.design/ui-sync_hub_admin.annotations.svg'),
+    ];
+    const { canvasUnits } = buildUnits(files, '.design');
+    expect(canvasUnits.length).toBe(1);
+    expect(canvasUnits[0].supporting.map((s) => s.path)).toEqual([
+      '.design/ui-sync_hub_admin.annotations.svg',
+    ]);
+  });
+
+  test('a meta with no canvas in the changeset is a standalone other unit', () => {
+    const { canvasUnits, otherUnits } = buildUnits([F('.design/ui/Orphan.meta.json')], '.design');
+    expect(canvasUnits.length).toBe(0);
+    expect(otherUnits.length).toBe(1);
+    expect(otherUnits[0].primary.path).toBe('.design/ui/Orphan.meta.json');
+    expect(otherUnits[0].supporting.length).toBe(0);
+  });
+
+  test('an annotation with no canvas in the changeset is a standalone other unit', () => {
+    const { canvasUnits, otherUnits } = buildUnits(
+      [F('.design/ui-ghost.annotations.svg')],
+      '.design'
+    );
+    expect(canvasUnits.length).toBe(0);
+    expect(otherUnits).toHaveLength(1);
+    expect(otherUnits[0].primary.path).toBe('.design/ui-ghost.annotations.svg');
+  });
+
+  test('loose files (config, DS tokens) are other units, never grouped under a canvas', () => {
+    const files = [
+      F('.design/ui/Pricing.tsx'),
+      F('.design/config.json'),
+      F('.design/system/project/tokens.css'),
+    ];
+    const { canvasUnits, otherUnits } = buildUnits(files, '.design');
+    expect(canvasUnits.map((u) => u.primary.path)).toEqual(['.design/ui/Pricing.tsx']);
+    expect(canvasUnits[0].supporting.length).toBe(0);
+    expect(otherUnits.map((u) => u.primary.path).sort()).toEqual([
+      '.design/config.json',
+      '.design/system/project/tokens.css',
+    ]);
+  });
+
+  test('multiple canvases are sorted by display name; each keeps its own sidecars', () => {
+    const files = [
+      F('.design/ui/Zebra.tsx'),
+      F('.design/ui/Zebra.meta.json'),
+      F('.design/ui/Alpha.tsx'),
+      F('.design/ui/Alpha.meta.json'),
+    ];
+    const { canvasUnits } = buildUnits(files, '.design');
+    expect(canvasUnits.map((u) => baseName(u.primary.path))).toEqual(['Alpha', 'Zebra']);
+    expect(canvasUnits[0].supporting.map((s) => s.path)).toEqual(['.design/ui/Alpha.meta.json']);
+    expect(canvasUnits[1].supporting.map((s) => s.path)).toEqual(['.design/ui/Zebra.meta.json']);
+  });
+
+  test('a meta does NOT cross-attach to a different-stem canvas (Pricing vs Pricing v3)', () => {
+    const files = [
+      F('.design/ui/Pricing.tsx'),
+      F('.design/ui/Pricing v3.meta.json'), // belongs to a (clean, absent) "Pricing v3" canvas
+    ];
+    const { canvasUnits, otherUnits } = buildUnits(files, '.design');
+    expect(canvasUnits[0].supporting.length).toBe(0); // not grabbed by "Pricing"
+    expect(otherUnits.map((u) => u.primary.path)).toEqual(['.design/ui/Pricing v3.meta.json']);
+  });
+
+  test('supportLabel + baseName render friendly names', () => {
+    expect(supportLabel('.design/ui/Pricing.meta.json')).toBe('Layout & settings');
+    expect(supportLabel('.design/ui-pricing.annotations.svg')).toBe('Annotations');
+    expect(baseName('.design/ui/Sync Hub Admin.tsx')).toBe('Sync Hub Admin');
+    expect(baseName('.design/ui-pricing.annotations.svg')).toBe('ui-pricing');
+  });
+});