@1agh/maude 0.42.0 → 0.44.0

package/apps/studio/test/acp-session-plugins.test.ts

@@ -22,7 +22,13 @@ const PLUGINS: SdkPluginConfig[] = [
 
 type Meta = {
   systemPrompt?: { append?: string };
-  claudeCode?: { options?: { plugins?: SdkPluginConfig[]; settingSources?: string[] } };
+  claudeCode?: {
+    options?: {
+      plugins?: SdkPluginConfig[];
+      settingSources?: string[];
+      settings?: { enabledPlugins?: Record<string, boolean> };
+    };
+  };
 };
 
 describe('newSessionParams — plugin carrier shape', () => {
@@ -79,6 +85,27 @@ describe('newSessionParams — plugin carrier shape', () => {
       expect((p._meta as Meta).claudeCode?.options?.settingSources).toEqual(['user']);
     }
   });
+
+  // DDR-168 — the structural double-registration guard: a non-empty `plugins`
+  // must also force off any natively-loaded user-level copy of the same id via
+  // the SDK's "flag" settings layer, so the bundled copy is the ONLY one that
+  // ever loads.
+  test('with plugins: forces design@maude off via options.settings.enabledPlugins (double-registration guard)', () => {
+    const p = newSessionParams('/repo', undefined, PLUGINS);
+    expect((p._meta as Meta).claudeCode?.options?.settings?.enabledPlugins).toEqual({
+      'design@maude': false,
+    });
+  });
+
+  test('empty plugins: options.settings is entirely absent (web/npm path unaffected)', () => {
+    const p = newSessionParams('/repo', 'BRIEF', []);
+    expect((p._meta as Meta).claudeCode?.options?.settings).toBeUndefined();
+  });
+
+  test('undefined plugins: options.settings is entirely absent', () => {
+    const p = newSessionParams('/repo', 'BRIEF');
+    expect((p._meta as Meta).claudeCode?.options?.settings).toBeUndefined();
+  });
 });
 
 describe('upgrade guard — installed adapter + SDK still honor the plugins contract', () => {
@@ -129,4 +156,48 @@ describe('upgrade guard — installed adapter + SDK still honor the plugins cont
     expect(src).toMatch(/SdkPluginConfig\s*=\s*\{/);
     expect(src).toMatch(/type:\s*'local'/);
   });
+
+  // DDR-168 — the same style of guard, for the `options.settings` mechanism the
+  // double-registration fix depends on: `settings` must NOT be among the fields
+  // the adapter overrides after the `...userProvidedOptions` spread (else our
+  // `enabledPlugins: false` override would be silently discarded), and the SDK
+  // must still declare `Settings.enabledPlugins` as an accepted field.
+  test('adapter forwards `settings` from userProvidedOptions and only ever overrides it conditionally when the caller left it unset', () => {
+    expect(existsSync(adapterEntry)).toBe(true);
+    const src = readFileSync(adapterEntry, 'utf8');
+    // Locate the `...userProvidedOptions` spread and inspect what follows it up
+    // to the `query({ options })` call. Verified live at claude-agent-acp@0.57.0:
+    // the object DOES contain a later `settings:` assignment (a
+    // CLAUDE_MODEL_CONFIG env-var fallback) — but it's gated behind
+    // `!userProvidedOptions?.settings && …`, i.e. it only fires when the caller
+    // did NOT already provide a settings object. A caller-provided `settings`
+    // (ours, carrying `enabledPlugins`) always wins. A bump that drops that
+    // guard — making the fallback unconditional — must fail here, since it
+    // would silently clobber DDR-168's double-registration override.
+    const spreadIdx = src.indexOf('...userProvidedOptions');
+    expect(spreadIdx).toBeGreaterThan(-1);
+    const queryIdx = src.indexOf('query(', spreadIdx);
+    expect(queryIdx).toBeGreaterThan(spreadIdx);
+    const window = src.slice(spreadIdx, queryIdx);
+    expect(window).toMatch(/!userProvidedOptions\?\.settings\s*&&/);
+  });
+
+  test("SDK Options declares settings (Settings.enabledPlugins is the field DDR-168's guard relies on)", () => {
+    let sdkPkg: string | null = null;
+    try {
+      const realAdapterDir = dirname(realpathSync(adapterEntry));
+      sdkPkg = Bun.resolveSync('@anthropic-ai/claude-agent-sdk/package.json', realAdapterDir);
+    } catch {
+      sdkPkg = null;
+    }
+    expect(sdkPkg).not.toBeNull();
+    const dts = join(dirname(sdkPkg as string), 'sdk.d.ts');
+    expect(existsSync(dts)).toBe(true);
+    const src = readFileSync(dts, 'utf8');
+    // sdk.d.ts:1831 `settings?: Settings;` (or similarly named field on Options) +
+    // :5193 `Settings.enabledPlugins` — a bump that renames/drops either must
+    // fail here, then adapt, rather than silently reopening double-registration.
+    expect(src).toMatch(/settings\?\s*:/);
+    expect(src).toMatch(/enabledPlugins\??\s*:/);
+  });
 });

package/apps/studio/test/annotation-strokes-command.test.ts

@@ -90,6 +90,23 @@ describe('createAnnotationStrokesCommand', () => {
     expect(putFn.mock.calls[1]?.[0]).toEqual([pen1]);
   });
 
+  test("do() passes the pre-op BEFORE as putFn's second arg; undo() passes the post-op AFTER", async () => {
+    // The live-bug regression this locks in: putStrokes needs its own
+    // command's baseline to tell a delete (an id `before` had that `next`
+    // dropped) apart from a genuinely concurrent sibling addition (an id
+    // `prev` has that this command's OWN before/next never knew about).
+    const putFn = mock(() => Promise.resolve());
+    const cmd = createAnnotationStrokesCommand({
+      before: [pen1, pen2],
+      after: [pen1],
+      putFn,
+    });
+    await cmd.do();
+    expect(putFn.mock.calls[0]).toEqual([[pen1], [pen1, pen2]]);
+    await cmd.undo();
+    expect(putFn.mock.calls[1]).toEqual([[pen1, pen2], [pen1]]);
+  });
+
   test('default label — add 2 strokes', () => {
     const cmd = createAnnotationStrokesCommand({
       before: [pen1],

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

@@ -21,6 +21,9 @@ import {
   polygonPoints,
   polygonVertices,
   type RectStroke,
+  reconcileCommit,
+  reconcileForeignEcho,
+  resolveImageUploadSwap,
   rid,
   STICKY_PALETTE,
   type StickyStroke,
@@ -427,6 +430,177 @@ describe('annotations-layer / strokes round-trip is stable for arrays', () => {
   });
 });
 
+describe('annotations-layer / reconcileCommit (live-bug regression — delete must stick)', () => {
+  const a: RectStroke = {
+    id: 'a',
+    tool: 'rect',
+    color: '#000',
+    width: 2,
+    x: 0,
+    y: 0,
+    w: 10,
+    h: 10,
+  };
+  const b: RectStroke = {
+    id: 'b',
+    tool: 'rect',
+    color: '#000',
+    width: 2,
+    x: 20,
+    y: 0,
+    w: 10,
+    h: 10,
+  };
+  const c: RectStroke = {
+    id: 'c',
+    tool: 'rect',
+    color: '#000',
+    width: 2,
+    x: 40,
+    y: 0,
+    w: 10,
+    h: 10,
+  };
+  const d: RectStroke = {
+    id: 'd',
+    tool: 'rect',
+    color: '#000',
+    width: 2,
+    x: 60,
+    y: 0,
+    w: 10,
+    h: 10,
+  };
+
+  test('a delete stays deleted even when the rendered `prev` has not caught up yet', () => {
+    // This is exactly the reported bug: Backspace computes next = before
+    // minus the deleted id, but React's `prev` (read by the functional
+    // updater) still shows the pre-delete set. The old reconcileIncoming
+    // treated "id missing from next" as "not caught up, fold it back" —
+    // reverting every delete locally while the smaller set still went out
+    // over PUT.
+    const prev = [a, b, c]; // rendered state, hasn't caught up to the delete
+    const opBefore = [a, b, c]; // this command's own baseline
+    const next = [a, b]; // c deleted
+    expect(reconcileCommit(prev, opBefore, next)).toEqual([a, b]);
+  });
+
+  test('a genuinely concurrent sibling addition (unknown to this commit) is still folded in', () => {
+    // `prev` has `d`, which neither this commit's `opBefore` nor `next` knows
+    // about — a different in-flight commit added it after `opBefore` was
+    // captured. It must survive.
+    const prev = [a, b, d];
+    const opBefore = [a, b];
+    const next = [a, b, c]; // this commit adds c
+    expect(reconcileCommit(prev, opBefore, next)).toEqual([a, b, c, d]);
+  });
+
+  test('delete + concurrent addition combine correctly (delete wins for its own id, addition still folds in)', () => {
+    const prev = [a, b, c, d]; // rendered: hasn't caught up to the delete OR seen `d` reconciled yet
+    const opBefore = [a, b, c];
+    const next = [a, b]; // deletes c
+    expect(reconcileCommit(prev, opBefore, next)).toEqual([a, b, d]);
+  });
+});
+
+describe('annotations-layer / reconcileForeignEcho (deletes must sync across tabs/peers)', () => {
+  const a: RectStroke = {
+    id: 'a',
+    tool: 'rect',
+    color: '#000',
+    width: 2,
+    x: 0,
+    y: 0,
+    w: 10,
+    h: 10,
+  };
+  const b: RectStroke = {
+    id: 'b',
+    tool: 'rect',
+    color: '#000',
+    width: 2,
+    x: 20,
+    y: 0,
+    w: 10,
+    h: 10,
+  };
+  const optimisticImage: ImageStroke = {
+    id: 'img',
+    tool: 'image',
+    x: 0,
+    y: 0,
+    w: 10,
+    h: 10,
+    href: 'blob:local-preview',
+  };
+
+  test('a foreign echo missing a non-ephemeral id (a real delete) is NOT reverted', () => {
+    const prev = [a, b];
+    const incoming = [a]; // peer deleted b
+    expect(reconcileForeignEcho(prev, incoming)).toEqual([a]);
+  });
+
+  test('a still-uploading local optimistic image (ephemeral href) survives a foreign echo that predates it', () => {
+    const prev = [a, optimisticImage];
+    const incoming = [a]; // the peer's broadcast was authored before our upload started
+    expect(reconcileForeignEcho(prev, incoming)).toEqual([a, optimisticImage]);
+  });
+});
+
+describe('annotations-layer / resolveImageUploadSwap (delete-during-upload must not resurrect)', () => {
+  // Adversarial-review finding: dropping an image, then Backspacing it
+  // before its upload resolves, used to resurrect it once the upload
+  // landed — the swap read "id absent from `before`" as render lag
+  // unconditionally, with no way to tell that apart from a genuine delete.
+  const optimistic: ImageStroke = {
+    id: 'img-1',
+    tool: 'image',
+    x: 0,
+    y: 0,
+    w: 10,
+    h: 10,
+    href: 'blob:optimistic-preview',
+  };
+  const sibling: RectStroke = {
+    id: 'sib',
+    tool: 'rect',
+    color: '#000',
+    width: 2,
+    x: 20,
+    y: 0,
+    w: 10,
+    h: 10,
+  };
+
+  test('deleted before the chain caught up to the optimistic insert (common case) → stays gone, no undo record', () => {
+    const before = [sibling]; // render lag — optimistic insert not reflected yet
+    const result = resolveImageUploadSwap(before, 'img-1', optimistic, 'assets/real.png', true);
+    expect(result).toBeNull();
+  });
+
+  test('deleted after the chain already had the optimistic entry → explicitly stripped from `after`', () => {
+    const before = [sibling, optimistic];
+    const result = resolveImageUploadSwap(before, 'img-1', optimistic, 'assets/real.png', true);
+    expect(result?.after).toEqual([sibling]);
+  });
+
+  test('NOT deleted + render lag (the original, still-valid case) → swaps to the real href', () => {
+    const before = [sibling]; // optimistic insert hasn't rendered into `before` yet
+    const result = resolveImageUploadSwap(before, 'img-1', optimistic, 'assets/real.png', false);
+    const img = result?.after.find((s) => s.id === 'img-1') as unknown as { href: string };
+    expect(img?.href).toBe('assets/real.png');
+    expect(result?.commitBefore).toEqual([sibling]); // undo excludes the never-committed blob: entry
+  });
+
+  test('NOT deleted, already present in `before` → swaps in place, sibling order preserved', () => {
+    const before = [sibling, optimistic];
+    const result = resolveImageUploadSwap(before, 'img-1', optimistic, 'assets/real.png', false);
+    expect(result?.after.map((s) => s.id)).toEqual(['sib', 'img-1']);
+    const img = result?.after.find((s) => s.id === 'img-1') as unknown as { href: string };
+    expect(img?.href).toBe('assets/real.png');
+  });
+});
+
 describe('annotations-layer / strokesShallowEqual (drag no-op gate)', () => {
   const pen: PenStroke = {
     id: 'p',

package/apps/studio/test/asset-api.test.ts

@@ -11,7 +11,7 @@ import { describe, expect, test } from 'bun:test';
 import { existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 
-import { sniffImageType } from '../api.ts';
+import { ASSET_MAX_BYTES, sniffImageType } from '../api.ts';
 import { bootServer, killProc, makeSandbox, nextPort } from './_helpers.ts';
 
 // ── Minimal valid magic-byte headers (padded so length checks pass). ──────────
@@ -107,9 +107,9 @@ describe('asset-api / POST /_api/asset (endpoint round-trip)', () => {
     });
   });
 
-  test('rejects an oversize body (> 10 MB) with 413', async () => {
+  test('rejects an oversize body (> ASSET_MAX_BYTES) with 413', async () => {
     await withServer(async (port) => {
-      const big = new Uint8Array(10 * 1024 * 1024 + 1);
+      const big = new Uint8Array(ASSET_MAX_BYTES + 1);
       big.set([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a], 0); // valid PNG header
       const res = await postAsset(port, big);
       expect(res.status).toBe(413);

package/apps/studio/test/canvas-edit.test.ts

@@ -377,10 +377,13 @@ describe('canvas-edit / applyTextEdit', () => {
     expect(() => applyTextEdit(CANVAS, src, id, 'x')).toThrow(CanvasEditError);
   });
 
-  test('refuses an element whose only child is a JSX expression', () => {
-    const src = 'function Demo() { const t = "x"; return <h1>{t}</h1>; }';
+  // unified-text-editing follow-up — a `{identifier}` bound to a const string
+  // is now traced back to that const and edited THERE (was a hard refusal).
+  test('edits an {identifier} child bound to a const string (traces to the const)', () => {
+    const src = 'const t = "x";\nfunction Demo() { return <h1>{t}</h1>; }';
     const id = idsOf(src).h1 as string;
-    expect(() => applyTextEdit(CANVAS, src, id, 'x')).toThrow(CanvasEditError);
+    const out = applyTextEdit(CANVAS, src, id, 'New', { before: 'x' });
+    expect(out.source).toContain('const t = "New"');
   });
 
   test('refuses a self-closing / empty element (no text to edit)', () => {
@@ -412,10 +415,18 @@ describe('canvas-edit / applyTextEdit', () => {
     expect(() => transpileCanvasSource(CANVAS, out.source)).not.toThrow();
   });
 
-  test('still refuses a dynamic {identifier} child (routes to /design:edit)', () => {
-    const src = 'function Demo() { const title = "x"; return <h1>{title}</h1>; }';
+  test('still refuses a genuinely-computed expression child (routes to /design:edit)', () => {
+    // Call expression — no single source string to rewrite → hard refusal.
+    const src = 'const price = 9;\nfunction Demo() { return <h1>{price.toFixed(2)}</h1>; }';
     const id = idsOf(src).h1 as string;
-    expect(() => applyTextEdit(CANVAS, src, id, 'x')).toThrow(CanvasEditError);
+    expect(() => applyTextEdit(CANVAS, src, id, 'x', { before: '9.00' })).toThrow(CanvasEditError);
+  });
+
+  test('refuses an {identifier} that does not resolve to a string const', () => {
+    // `count` is a number const — no string to trace to → refuse.
+    const src = 'const count = 3;\nfunction Demo() { return <h1>{count}</h1>; }';
+    const id = idsOf(src).h1 as string;
+    expect(() => applyTextEdit(CANVAS, src, id, 'x', { before: '3' })).toThrow(CanvasEditError);
   });
 });
 

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

@@ -162,6 +162,56 @@ describe('canvas-origin gate — A1/A2 traversal + privilege containment', () =>
         // untrusted canvas origin must never read (or write) the user's pasted
         // chat images; a GET here 403s at the gate, not 404 from the handler.
         '/_api/acp/attachment',
+        // Phase 4 (feature-whiteboard-annotation-improvements) — the sticker
+        // catalogue + bundled sticker PNGs are MAIN-ORIGIN ONLY, same posture
+        // as /_api/assets above: the StickerPicker is shell UI, absent from
+        // CANVAS_SAFE_API + startCanvasServer's routes. A GET here 403s at
+        // the gate on both — the catalogue route and the static PNG serve.
+        '/_api/stickers',
+        '/_stickers/some-pack/some-sticker.png',
+        // DDR-166 Phase 1 / T2 — the bundled intro-video media serve is
+        // MAIN-ORIGIN ONLY, same posture as /_stickers above: a Maude-product
+        // asset, absent from CANVAS_SAFE_API + startCanvasServer's routes.
+        '/_media/intro.mp4',
+        // feature-footage-analysis-director — the footage-analysis + EDL sidecar
+        // route is MAIN-ORIGIN ONLY (written by the analyst/director agents over
+        // loopback; absent from CANVAS_SAFE_API + startCanvasServer's routes). The
+        // untrusted canvas origin must never read/write the director's analysis —
+        // a GET here 403s at the gate, not 405 from a reached handler.
+        '/_api/footage',
+        // feature-ai-media-generation (DDR-16x) — the generation job queue +
+        // provider catalogue + key routes are MAIN-ORIGIN ONLY (they resolve a
+        // provider KEY and make outbound provider calls). The untrusted canvas
+        // origin must never reach them — it sees only the produced /assets/<sha8>.
+        // A GET here 403s at the gate, not 405/200 from a reached handler.
+        '/_api/generate-jobs',
+        '/_api/generate/providers',
+        '/_api/generate/keys',
+        // Task 2.6 — the non-secret transcription-engine preference writes into
+        // .design/config.json + hot-reloads; still MAIN-ORIGIN ONLY (the canvas
+        // must not steer the user's engine choice).
+        '/_api/generate/prefs',
+        // Task 2.5 — reuse-before-you-pay audio search + history re-download
+        // resolve the provider key server-side; MAIN-ORIGIN ONLY.
+        '/_api/generate/audio-search',
+        '/_api/generate/audio-reuse',
+        // Task 2.7 — managed whisper-model download (egress + local disk write);
+        // MAIN-ORIGIN ONLY.
+        '/_api/generate/whisper-model',
+        // DDR-166 plan, Phase 2 (T6) — the design-setup readiness probe (project/
+        // design-system/first-canvas/brand-assets progress) is a shell/onboarding
+        // concern, same posture as /_api/preflight above; MAIN-ORIGIN ONLY.
+        '/_api/setup-readiness',
+        // DDR-167 (Phase 3 / T10) — local-file SVG/PDF ingestion is a
+        // file-write + local-file-adjacent surface (Decision 4); MAIN-ORIGIN
+        // ONLY, same posture as /_api/asset's containment but privileged
+        // rather than canvas-reachable — the untrusted canvas iframe must
+        // never drive an import.
+        '/_api/import-asset',
+        // DDR-173 (Phase 3 / T12) — brand-file typed-cue extraction is a
+        // file-write surface (writes assets/logos/*), same privileged
+        // posture as /_api/import-asset above; MAIN-ORIGIN ONLY.
+        '/_api/import-brand',
         '/package.json',
       ]) {
         expect(await code(p)).toBe(403);

package/apps/studio/test/csp-canvas-shell.test.ts

@@ -48,4 +48,15 @@ describe('cspForCanvasShell — A6 hardening', () => {
     const csp = cspForCanvasShell(SHELL);
     expect(csp).not.toContain('frame-ancestors');
   });
+
+  // fix-photo-editor-followup-debt Task 22 — the narrow, documented
+  // `connect-src` exception for @imgly/background-removal's model-weight CDN.
+  // Regression guard against both directions of drift: the exception being
+  // silently reverted, AND further hosts creeping in beside it.
+  test('connect-src carries the exact staticimgly.com exception, no more', () => {
+    const csp = cspForCanvasShell(SHELL);
+    expect(csp).toContain("connect-src 'self' https://staticimgly.com");
+    const connectSrc = csp.split('; ').find((d) => d.startsWith('connect-src'));
+    expect(connectSrc).toBe("connect-src 'self' https://staticimgly.com");
+  });
 });

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

@@ -18,7 +18,7 @@ import { describe, expect, test } from 'bun:test';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 
-import { sameOriginWrite } from '../http.ts';
+import { sameOriginRead, sameOriginWrite } from '../http.ts';
 
 const SELF = 'http://localhost:4399';
 const post = (origin?: string): Request =>
@@ -53,6 +53,28 @@ describe('CSRF Origin guard — sameOriginWrite (DDR-105)', () => {
   });
 });
 
+describe('CSRF read guard — sameOriginRead (Task 2.5 F1, Fetch-Metadata)', () => {
+  const get = (secFetchSite?: string): Request =>
+    new Request(`${SELF}/_api/generate/audio-search?q=x`, {
+      method: 'GET',
+      headers: { ...(secFetchSite ? { 'sec-fetch-site': secFetchSite } : {}) },
+    });
+
+  test('rejects a cross-site browser GET (key-bearing fan-out must not be CSRF-triggerable)', () => {
+    expect(sameOriginRead(get('cross-site'))).toBe(false);
+    expect(sameOriginRead(get('same-site'))).toBe(false);
+  });
+
+  test('allows a same-origin browser GET', () => {
+    expect(sameOriginRead(get('same-origin'))).toBe(true);
+    expect(sameOriginRead(get('none'))).toBe(true); // direct navigation
+  });
+
+  test('allows a non-browser client (CLI / curl — no Sec-Fetch-Site header)', () => {
+    expect(sameOriginRead(get())).toBe(true);
+  });
+});
+
 // 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

package/apps/studio/test/design-setup-readiness.test.ts

@@ -0,0 +1,155 @@
+// Design-setup readiness probe (DDR-166 plan, Phase 2 / T6). A pure function
+// over a Context-shaped fixture — no server boot needed, `probeSetupReadiness`
+// only touches `ctx.cfg` + `ctx.paths` (both destructured, so a minimal fake
+// satisfies the type).
+
+import { describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import type { Context, DevServerConfig } from '../context.ts';
+import { probeSetupReadiness } from '../design-setup-readiness.ts';
+
+function fixtureCtx(opts: {
+  hasConfig?: boolean;
+  designSystems?: DevServerConfig['designSystems'];
+  canvasGroups?: DevServerConfig['canvasGroups'];
+  seedCanvas?: boolean;
+  seedTokens?: string[]; // ds names to write a real colors_and_type.css for
+  seedLogo?: string[]; // ds names to write a preview/logo.svg for
+}): Context {
+  const root = mkdtempSync(join(tmpdir(), 'maude-setup-readiness-'));
+  const designRoot = join(root, '.design');
+  mkdirSync(designRoot, { recursive: true });
+
+  const designSystems = opts.designSystems ?? [];
+  const canvasGroups = opts.canvasGroups ?? [
+    { label: 'Design system', path: 'system' },
+    { label: 'UI kit', path: 'ui' },
+  ];
+
+  for (const ds of designSystems) {
+    mkdirSync(join(designRoot, ds.path), { recursive: true });
+    if (opts.seedTokens?.includes(ds.name)) {
+      writeFileSync(join(designRoot, ds.path, 'colors_and_type.css'), ':root{}');
+    }
+    if (opts.seedLogo?.includes(ds.name)) {
+      mkdirSync(join(designRoot, ds.path, 'preview'), { recursive: true });
+      writeFileSync(join(designRoot, ds.path, 'preview', 'logo.svg'), '<svg/>');
+    }
+  }
+  if (opts.seedCanvas) {
+    mkdirSync(join(designRoot, 'ui'), { recursive: true });
+    writeFileSync(
+      join(designRoot, 'ui', 'Welcome.tsx'),
+      'export default function W(){return <main/>}\n'
+    );
+  }
+
+  const cfg: DevServerConfig = {
+    name: 'test',
+    projectLabel: null,
+    designRoot: '.design',
+    canvasGroups,
+    designSystems,
+    rootClass: 'app',
+    themeDefault: 'dark',
+    tokensCssRel: 'system/colors_and_type.css',
+    teamAccentDefault: null,
+    handoffTargets: [],
+    newCanvasDir: 'ui',
+    newComponentDir: 'ui/components',
+    _source: opts.hasConfig === false ? 'defaults' : '.design/config.json',
+  };
+
+  return {
+    cfg,
+    projectLabel: 'test',
+    paths: {
+      repoRoot: root,
+      designRel: '.design',
+      designRoot,
+      serverInfoFile: join(designRoot, '_server.json'),
+      activeFile: join(designRoot, '_active.json'),
+      commentsDir: join(designRoot, '_comments'),
+      canvasStateDir: join(designRoot, '_canvas-state'),
+      historyDir: join(designRoot, '_history'),
+      tokensUrlRel: 'system/colors_and_type.css',
+      systemDirRel: 'system',
+    },
+    bus: { on: () => () => {}, emit: () => {} },
+  } as Context;
+}
+
+describe('probeSetupReadiness', () => {
+  test('bare write_minimal_design scaffold: config missing, everything else missing too', async () => {
+    const report = await probeSetupReadiness(fixtureCtx({ hasConfig: false }));
+    expect(report.ready).toBe(false);
+    const byId = Object.fromEntries(report.items.map((i) => [i.id, i.status]));
+    expect(byId).toEqual({
+      project: 'missing',
+      'design-system': 'missing',
+      'first-canvas': 'missing',
+      'brand-assets': 'missing',
+    });
+  });
+
+  test('real config, no DS, no canvas: project present, rest missing', async () => {
+    const report = await probeSetupReadiness(fixtureCtx({ hasConfig: true }));
+    const byId = Object.fromEntries(report.items.map((i) => [i.id, i.status]));
+    expect(byId.project).toBe('present');
+    expect(byId['design-system']).toBe('missing');
+    expect(byId['first-canvas']).toBe('missing');
+    expect(byId['brand-assets']).toBe('missing');
+    expect(report.ready).toBe(false);
+  });
+
+  test('DS declared but tokens file absent: still missing (declared != on-disk)', async () => {
+    const report = await probeSetupReadiness(
+      fixtureCtx({
+        hasConfig: true,
+        designSystems: [
+          { name: 'acme', path: 'system/acme', tokensCssRel: 'system/acme/colors_and_type.css' },
+        ],
+      })
+    );
+    const item = report.items.find((i) => i.id === 'design-system')!;
+    expect(item.status).toBe('missing');
+    expect(item.detail).toContain('Declared in config');
+  });
+
+  test('all four present → ready: true', async () => {
+    const report = await probeSetupReadiness(
+      fixtureCtx({
+        hasConfig: true,
+        designSystems: [
+          { name: 'acme', path: 'system/acme', tokensCssRel: 'system/acme/colors_and_type.css' },
+        ],
+        seedTokens: ['acme'],
+        seedLogo: ['acme'],
+        seedCanvas: true,
+      })
+    );
+    expect(report.items.every((i) => i.status === 'present')).toBe(true);
+    expect(report.ready).toBe(true);
+  });
+
+  test('a "system" canvas group never counts as the first user canvas', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'maude-setup-readiness-'));
+    const designRoot = join(root, '.design');
+    const canvasGroups = [{ label: 'Design system', path: 'system' }];
+    mkdirSync(join(designRoot, 'system'), { recursive: true });
+    writeFileSync(
+      join(designRoot, 'system', 'specimen.tsx'),
+      'export default function S(){return <main/>}\n'
+    );
+    const ctx = fixtureCtx({ hasConfig: true, canvasGroups });
+    // Overwrite paths.designRoot/repoRoot to point at this second fixture dir
+    // (fixtureCtx already made its own scratch dir we don't need here).
+    ctx.paths.repoRoot = root;
+    ctx.paths.designRoot = designRoot;
+    const report = await probeSetupReadiness(ctx);
+    expect(report.items.find((i) => i.id === 'first-canvas')!.status).toBe('missing');
+  });
+});