@1agh/maude 0.46.0 → 0.48.0

package/apps/studio/test/acp-plugin-bootstrap.test.ts

@@ -16,6 +16,7 @@ import { computeSessionPlugins } from '../acp/plugin-bootstrap.ts';
 
 const DESIGN = '/bundle/plugins/design';
 const FLOW = '/bundle/plugins/flow';
+const KGAI = '/bundle/plugins/kgai';
 
 describe('computeSessionPlugins — gates', () => {
   // `/flow` auto-load is intentionally OFF for now (2026-07-03) — only `design`
@@ -52,4 +53,37 @@ describe('computeSessionPlugins — gates', () => {
     const out = computeSessionPlugins({ native: true, designDir: DESIGN, flowDir: FLOW });
     expect(out.every((c) => c.skipMcpDiscovery === true && c.type === 'local')).toBe(true);
   });
+
+  // feature-kgai-ecosystem-integration Phase 8 — the third-party kgai plugin
+  // carries the `Stop` hook that IS autonomous decision capture. Without
+  // injection the packaged app records nothing (settingSources:['user'], and a
+  // terminal-less DDR-177 user never marketplace-installs it).
+  test('kgai bundled ⇒ injected alongside design (autonomous capture in the .app)', () => {
+    const out = computeSessionPlugins({
+      native: true,
+      designDir: DESIGN,
+      flowDir: FLOW,
+      kgaiDir: KGAI,
+    });
+    expect(out).toEqual([
+      { type: 'local', path: DESIGN, skipMcpDiscovery: true },
+      { type: 'local', path: KGAI, skipMcpDiscovery: true },
+    ]);
+  });
+
+  test('kgai absent (dev tree / npm layout) ⇒ design only, no crash', () => {
+    expect(
+      computeSessionPlugins({ native: true, designDir: DESIGN, flowDir: FLOW, kgaiDir: null })
+    ).toEqual([{ type: 'local', path: DESIGN, skipMcpDiscovery: true }]);
+    // omitted entirely (optional field) behaves the same
+    expect(computeSessionPlugins({ native: true, designDir: DESIGN, flowDir: FLOW })).toEqual([
+      { type: 'local', path: DESIGN, skipMcpDiscovery: true },
+    ]);
+  });
+
+  test('not native ⇒ kgai is NOT injected either (web-serve gate holds)', () => {
+    expect(
+      computeSessionPlugins({ native: false, designDir: DESIGN, flowDir: FLOW, kgaiDir: KGAI })
+    ).toEqual([]);
+  });
 });

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

@@ -1,16 +1,27 @@
-// 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:
+// DDR-184 (+ DDR-185, hardened per its security addendum) — 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). Three 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.
+//   (2) SOURCE-OF-TRUTH guard — the Bash rules are EXACTLY `Bash(maude:*)`
+//       plus a closed read-only fs verb set (DDR-185) — nothing else. A
+//       security fan-out found the ORIGINAL DDR-185 cut's `Bash(agent-browser:*)`
+//       entry was a zero-confirmation session-hijack primitive (agent-browser's
+//       own bundled skill recommends a persistent, real-login Chrome profile)
+//       and `Bash(find:*)` was unrestricted command execution via `-exec`, not
+//       "mutation" as first characterized — both are cut, not patched, because
+//       neither residual is fixable via prefix-matching. `agent-browser` is
+//       now reached ONLY through the hardened `agent-browser-safe` verb
+//       (`Bash(maude:*)` covers it — no separate allow-list entry). If any of
+//       this drifts, this test fails loudly.
+//   (3) `WebSearch`/`WebFetch` (DDR-185) are present as bare native tool names
+//       — no prefix-matching involved, so no source-of-truth guard needed the
+//       way the Bash rules need one.
 
 import { describe, expect, test } from 'bun:test';
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
@@ -68,14 +79,40 @@ describe('MAUDE_DEFAULT_ALLOWED_TOOLS — source-of-truth guard (DDR-184 / DDR-0
     }
   });
 
-  test('the ONLY Bash rule is prefix-scoped to `maude` — never a bare/un-scoped Bash', () => {
+  test('WebSearch and WebFetch are present (DDR-185)', () => {
+    for (const t of ['WebSearch', 'WebFetch']) {
+      expect(MAUDE_DEFAULT_ALLOWED_TOOLS).toContain(t);
+    }
+  });
+
+  test('the Bash rules are EXACTLY this closed set — 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:*)']);
+    // anyone widening it: the list may auto-approve `maude` and the closed
+    // read-only fs verb set (DDR-185) — nothing else. In particular:
+    //   - `Bash(curl:*)` must NEVER appear — curl is routed through the
+    //     `curl-local` verb (covered by `Bash(maude:*)`) instead.
+    //   - `Bash(agent-browser:*)` must NEVER appear — a security fan-out found
+    //     it was a zero-confirmation session-hijack primitive; agent-browser is
+    //     routed through the `agent-browser-safe` verb instead.
+    //   - `Bash(find:*)` must NEVER appear — `find -exec` is unrestricted
+    //     command execution, not "mutation"; there is no verb substitute, it
+    //     is simply cut.
+    expect(bashRules).toEqual([
+      'Bash(maude:*)',
+      'Bash(ls:*)',
+      'Bash(cat:*)',
+      'Bash(pwd:*)',
+      'Bash(head:*)',
+      'Bash(tail:*)',
+      'Bash(wc:*)',
+      'Bash(tree:*)',
+      'Bash(file:*)',
+      'Bash(stat:*)',
+    ]);
   });
 
-  test('the single Bash rule is load-bearing on DDR-062: every design helper is a `maude design <verb>`', () => {
+  test('the `maude` 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://', '')));
@@ -88,4 +125,63 @@ describe('MAUDE_DEFAULT_ALLOWED_TOOLS — source-of-truth guard (DDR-184 / DDR-0
     expect(src).toContain('BIN_VERBS');
     expect(src).toMatch(/maude design <verb>/);
   });
+
+  test('the `curl-local` verb exists and is reached via `maude design <verb>` (DDR-185)', () => {
+    // The mechanism the `Bash(agent-browser:*)`/fs-list comment in bridge.ts
+    // promises for curl: real host enforcement via a first-party verb, not a
+    // Bash prefix rule. If this verb disappears from BIN_VERBS, the DDR-185
+    // curl story (and the bootstrap-brief nudge pointing at it) goes stale.
+    const here = dirname(realpathSync(import.meta.url.replace('file://', '')));
+    const designCli = join(here, '..', '..', '..', 'cli', 'commands', 'design.mjs');
+    const src = readFileSync(designCli, 'utf8');
+    expect(src).toMatch(/'curl-local'/);
+  });
+
+  test('the `agent-browser-safe` verb exists and is reached via `maude design <verb>` (DDR-185 security addendum)', () => {
+    // The replacement for the reverted `Bash(agent-browser:*)` entry — real
+    // subcommand/flag enforcement via a first-party verb, not a Bash prefix
+    // rule. If this verb disappears from BIN_VERBS, motion-critic.md/edit.md's
+    // documented raw agent-browser calls go back to prompting (not silently
+    // insecure — but the friction-reduction this DDR promises goes stale).
+    const here = dirname(realpathSync(import.meta.url.replace('file://', '')));
+    const designCli = join(here, '..', '..', '..', 'cli', 'commands', 'design.mjs');
+    const src = readFileSync(designCli, 'utf8');
+    expect(src).toMatch(/'agent-browser-safe'/);
+  });
+
+  test('plugin markdown no longer documents a RAW agent-browser SCREENSHOT/OPEN/NAVIGATE call (DDR-185 security addendum)', () => {
+    // motion-critic.md and edit.md are the two files that originally justified
+    // `Bash(agent-browser:*)` (raw calls not reached via `maude design <verb>`).
+    // screenshot/open/navigate now go through the hardened wrapper — a
+    // regression here means either those calls silently went back to
+    // prompting every time, or (worse) someone re-introduced a raw call the
+    // allow-list no longer covers. `eval` is the deliberate exception (round
+    // 3: removed from the wrapper's own allow-list entirely — arbitrary JS
+    // execution can't be argv-constrained — so it's EXPECTED to stay a raw,
+    // prompting `agent-browser eval` call; see both files' own comments).
+    const here = dirname(realpathSync(import.meta.url.replace('file://', '')));
+    const pluginsDir = join(here, '..', '..', '..', 'plugins', 'design');
+    for (const rel of ['agents/motion-critic.md', 'commands/edit.md']) {
+      const src = readFileSync(join(pluginsDir, rel), 'utf8');
+      expect(src).not.toMatch(/(?<!maude design )agent-browser (screenshot|open|navigate)\b/);
+      expect(src).toContain('agent-browser eval'); // deliberately raw — see comment above
+    }
+    // Only motion-critic.md actually calls the wrapper (for `screenshot`) —
+    // edit.md's sole agent-browser use was `eval`, which reverted fully to
+    // raw, so it has no `agent-browser-safe` invocation left at all.
+    const motionCritic = readFileSync(join(pluginsDir, 'agents/motion-critic.md'), 'utf8');
+    expect(motionCritic).toContain('maude design agent-browser-safe');
+  });
+
+  test('agent-browser-safe does NOT support eval (DDR-185 round-3 security addendum)', () => {
+    // A future accidental re-add of eval to the wrapper's own allow-list
+    // would silently reopen the zero-click session-hijack chain (ethical-
+    // hacker Finding 1: eval's fetch()/window.location defeat
+    // --allowed-domains entirely, and no argv check can constrain arbitrary
+    // JS execution). Source-of-truth guard against bridge.ts's own wrapper.
+    const here = dirname(realpathSync(import.meta.url.replace('file://', '')));
+    const wrapperPath = join(here, '..', 'bin', '_agent-browser-safe.mjs');
+    const src = readFileSync(wrapperPath, 'utf8');
+    expect(src).not.toMatch(/^\s*eval:\s*\[/m);
+  });
 });

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

@@ -94,6 +94,12 @@ describe('newSessionParams — plugin carrier shape', () => {
     const p = newSessionParams('/repo', undefined, PLUGINS);
     expect((p._meta as Meta).claudeCode?.options?.settings?.enabledPlugins).toEqual({
       'design@maude': false,
+      // kgai (third-party, injected by the desktop bundle for autonomous capture —
+      // feature-kgai-ecosystem-integration Phase 8). Suppressing a user-installed
+      // copy matters MORE here than for our own plugins: it would run its own
+      // SessionStart install.sh and point at a different engine version than the
+      // pinned, signed sidecar we ship.
+      kgai: false,
     });
   });
 

package/apps/studio/test/browse-posture.test.tsx

@@ -0,0 +1,107 @@
+// browse-posture — feature-4 (browse/move split, DDR-187). The LOAD-BEARING
+// gate: a DOM-level proof that the boot-default `browse` tool is a pure native
+// pass-through (a real click handler under the cursor fires, nothing is
+// claimed), while the `move` (select) tool CLAIMS the same bare click (native
+// handler suppressed, onSelect dispatched). This promotes the input-router
+// comment-invariant ("bare clicks pass through") into an enforced test — the
+// canvas-origin-gate equivalent for the input posture.
+//
+// Needs a live DOM (capture-phase listeners + event dispatch + a real React
+// effect) — register happy-dom + drive a createRoot, same convention as
+// canvas-hmr-runtime.test.tsx / specimen-select.test.ts.
+
+import { afterAll, 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, useRef } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+import { type RouterCallbacks, type Tool, useInputRouter } from '../input-router.tsx';
+
+// A minimal host that mounts the router over a single native <button>. The
+// active tool is read fresh at event time via `getActiveTool` (a ref-backed
+// getter), so a test can flip the tool without re-rendering.
+function Harness({ getTool, callbacks }: { getTool: () => Tool; callbacks: RouterCallbacks }) {
+  const hostRef = useRef<HTMLDivElement | null>(null);
+  useInputRouter({ hostRef, getActiveTool: getTool, callbacks });
+  return (
+    <div ref={hostRef} className="dc-canvas">
+      <button type="button" id="native-btn">
+        Click me
+      </button>
+    </div>
+  );
+}
+
+function fireBareLeftClick(el: Element): void {
+  // The full native sequence the router gates: pointerdown → mousedown → click.
+  el.dispatchEvent(new MouseEvent('pointerdown', { bubbles: true, cancelable: true, button: 0 }));
+  el.dispatchEvent(new MouseEvent('mousedown', { bubbles: true, cancelable: true, button: 0 }));
+  el.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true, button: 0 }));
+}
+
+describe('browse tool — native pass-through (boot default)', () => {
+  test('bare click: native button handler FIRES, onSelect NOT dispatched', () => {
+    const el = document.createElement('div');
+    document.body.appendChild(el);
+    const root: Root = createRoot(el);
+    let selectCalls = 0;
+    let nativeClicks = 0;
+
+    act(() => {
+      root.render(
+        <Harness getTool={() => 'browse'} callbacks={{ onSelect: () => (selectCalls += 1) }} />
+      );
+    });
+
+    const btn = el.querySelector('#native-btn') as HTMLButtonElement;
+    btn.addEventListener('click', () => (nativeClicks += 1));
+    act(() => {
+      fireBareLeftClick(btn);
+    });
+
+    expect(selectCalls).toBe(0); // browse never selects
+    expect(nativeClicks).toBe(1); // the mock stays alive
+
+    act(() => root.unmount());
+    el.remove();
+  });
+});
+
+describe('move (select) tool — claims the bare click', () => {
+  test('bare click: native button handler SUPPRESSED, onSelect dispatched', () => {
+    const el = document.createElement('div');
+    document.body.appendChild(el);
+    const root: Root = createRoot(el);
+    let selectCalls = 0;
+    let nativeClicks = 0;
+
+    act(() => {
+      root.render(
+        <Harness getTool={() => 'move'} callbacks={{ onSelect: () => (selectCalls += 1) }} />
+      );
+    });
+
+    const btn = el.querySelector('#native-btn') as HTMLButtonElement;
+    btn.addEventListener('click', () => (nativeClicks += 1));
+    act(() => {
+      fireBareLeftClick(btn);
+    });
+
+    // Router claims the pointerdown (dispatches select) and swallows the
+    // synthetic click so the button under the cursor never activates.
+    expect(selectCalls).toBe(1);
+    expect(nativeClicks).toBe(0);
+
+    act(() => root.unmount());
+    el.remove();
+  });
+});

package/apps/studio/test/canvas-hide-chrome.test.ts

@@ -0,0 +1,58 @@
+// canvas-hide-chrome.test.ts — regression guard for RCA
+// issue-pdf-print-export-marks-missing (Bug A). `_shell.html`'s
+// `#canvas-hide-chrome` style block is the sanctioned "never leaks into an
+// export" list every exporter relies on (`?hide-chrome=1` flips it from
+// `media="not all"` to `media="all"` — see exporters/index.ts
+// canvasShellUrl()). `.dc-artboard-guides` (the print bleed/trim/margin guide
+// overlay, artboard-guides-overlay.tsx) was never added to this list when
+// feature-2-print-artboards shipped, so it rendered straight into every PDF/
+// PNG/SVG capture whenever a canvas had it toggled on. Grep-based, mirrors
+// shell-importmap.test.ts's own style for the same file.
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { DEV_SERVER_ROOT } from '../paths.ts';
+
+const SHELL_HTML_PATH = join(
+  DEV_SERVER_ROOT,
+  '..',
+  '..',
+  'plugins',
+  'design',
+  'templates',
+  '_shell.html'
+);
+
+describe('_shell.html #canvas-hide-chrome covers every overlay mount class', () => {
+  const shellHtml = readFileSync(SHELL_HTML_PATH, 'utf8');
+  const blockMatch = shellHtml.match(/<style id="canvas-hide-chrome"[^>]*>([\s\S]*?)<\/style>/);
+
+  test('the #canvas-hide-chrome style block exists', () => {
+    expect(blockMatch).not.toBeNull();
+  });
+
+  const block = blockMatch?.[1] ?? '';
+
+  // Every editor-chrome overlay class that must never leak into a capture
+  // render. `.dc-artboard-guides` is the one this RCA adds; the rest already
+  // guard against the same class of regression for their own overlays.
+  const REQUIRED_SELECTORS = [
+    '.dc-mm',
+    '.dc-tool-palette',
+    '.dc-participants',
+    '.dc-cv-halo',
+    '.dc-snap-guide',
+    '.dc-annot-svg',
+    '.cm-layer',
+    '.dc-artboard-label',
+    '.dc-artboard-guides',
+  ];
+
+  for (const selector of REQUIRED_SELECTORS) {
+    test(`"${selector}" is hidden during capture`, () => {
+      expect(block.includes(selector)).toBe(true);
+    });
+  }
+});

package/apps/studio/test/canvas-meta-api.test.ts

@@ -524,3 +524,73 @@ describe('/_api/canvas-meta — overlays lane (T6)', () => {
     }
   });
 });
+
+// feature-4 T7b — `locked` (per-user locked layer keys) is the third view-file
+// lane: same split contract as viewport/overlays (never the versioned meta),
+// REPLACE semantics (the client sends the full set), bounded shape.
+describe('/_api/canvas-meta — locked lane (feature-4 T7b)', () => {
+  test('PATCH locked leaves meta byte-unchanged + writes the view file; GET merges it back', async () => {
+    const { root, designRoot } = makeSandbox();
+    const port = nextPort();
+    const proc = await bootServer(root, port);
+    try {
+      mkdirSync(join(designRoot, 'ui'), { recursive: true });
+      const tsxAbs = join(designRoot, 'ui', 'Locked.tsx');
+      writeFileSync(tsxAbs, 'export default function L(){return <main/>}\n');
+      const metaAbs = tsxAbs.replace(/\.tsx$/, '.meta.json');
+      writeFileSync(metaAbs, JSON.stringify({ title: 'Locked', sections: [] }));
+      const before = readFileSync(metaAbs, 'utf8');
+      const file = repoRel(designRoot, tsxAbs);
+
+      const r = await fetch(`http://localhost:${port}/_api/canvas-meta`, {
+        method: 'PATCH',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ file, patch: { locked: ['aabbccdd:0', 'deadbeef:2'] } }),
+      });
+      expect(r.status).toBe(200);
+      const merged = (await r.json()) as MetaShape;
+      expect(merged.locked).toEqual(['aabbccdd:0', 'deadbeef:2']);
+      // Versioned meta byte-identical (runtime state never lands there).
+      expect(readFileSync(metaAbs, 'utf8')).toBe(before);
+      const view = JSON.parse(readFileSync(viewPath(designRoot, 'ui-locked'), 'utf8'));
+      expect(view.locked).toEqual(['aabbccdd:0', 'deadbeef:2']);
+
+      // REPLACE semantics — a smaller set unlocks the dropped key.
+      await fetch(`http://localhost:${port}/_api/canvas-meta`, {
+        method: 'PATCH',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ file, patch: { locked: ['aabbccdd:0'] } }),
+      });
+      const g = await fetch(
+        `http://localhost:${port}/_api/canvas-meta?file=${encodeURIComponent(file)}`
+      );
+      expect(((await g.json()) as MetaShape).locked).toEqual(['aabbccdd:0']);
+    } finally {
+      await killProc(proc);
+    }
+  });
+
+  test('malformed locked keys are a silent no-op (shape-gated)', async () => {
+    const { root, designRoot } = makeSandbox();
+    const port = nextPort();
+    const proc = await bootServer(root, port);
+    try {
+      mkdirSync(join(designRoot, 'ui'), { recursive: true });
+      const tsxAbs = join(designRoot, 'ui', 'BadLock.tsx');
+      writeFileSync(tsxAbs, 'export default function B(){return <main/>}\n');
+      writeFileSync(tsxAbs.replace(/\.tsx$/, '.meta.json'), JSON.stringify({ title: 'B' }));
+      const file = repoRel(designRoot, tsxAbs);
+      await fetch(`http://localhost:${port}/_api/canvas-meta`, {
+        method: 'PATCH',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ file, patch: { locked: ['../../etc/passwd', 'not-a-key'] } }),
+      });
+      const g = await fetch(
+        `http://localhost:${port}/_api/canvas-meta?file=${encodeURIComponent(file)}`
+      );
+      expect(((await g.json()) as MetaShape).locked).toBeUndefined();
+    } finally {
+      await killProc(proc);
+    }
+  });
+});

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

@@ -111,6 +111,10 @@ describe('canvas-origin gate — A1/A2 traversal + privilege containment', () =>
         '/_api/insert-artboard',
         '/_api/resize-artboard',
         '/_api/delete-artboard',
+        // feature-3-web-artboards T3 — "Duplicate at width…" is a source-write,
+        // same MAIN-ORIGIN-ONLY posture as the other artboard structural ops
+        // right above.
+        '/_api/duplicate-artboard',
         // Stage F1 — the AssetPicker's asset-listing GET is a shell (main-origin)
         // concern; the untrusted canvas iframe must not enumerate project media.
         '/_api/assets',

package/apps/studio/test/comment-mount.test.ts

@@ -39,7 +39,8 @@ describe('comment-mount / MaybeToolProvider dedup', () => {
     const html = renderToStaticMarkup(
       createElement(MaybeToolProvider, null, createElement(ToolReader))
     );
-    expect(html).toContain('data-tool="move"');
+    // feature-4 (browse/move split) — the default boot tool is `browse`.
+    expect(html).toContain('data-tool="browse"');
   });
 });
 

package/apps/studio/test/component-map.test.ts

@@ -0,0 +1,48 @@
+// component-map — feature-4 T7a. The Layers panel's purple-instance source:
+// `componentMapForCanvas` reports every element that renders through an
+// INSTANTIATED component (`<Card/>` referenced as JSX in the file), keyed by
+// cd-id. The top-level canvas component (exported/mounted, never referenced as
+// JSX here) must NOT mark its elements as instances.
+
+import { describe, expect, test } from 'bun:test';
+
+import { componentMapForCanvas } from '../canvas-edit.ts';
+import { transpileCanvasSource } from '../canvas-pipeline.ts';
+
+const CANVAS = '/abs/Canvas.tsx';
+
+function idsOf(source: string): Record<string, string> {
+  const { withIds } = transpileCanvasSource(CANVAS, source);
+  const out: Record<string, string> = {};
+  for (const m of withIds.matchAll(/<(\w+)([^>]*?)data-cd-id="([0-9a-f]{8})"/g)) {
+    if (!out[m[1] as string]) out[m[1] as string] = m[3] as string;
+  }
+  return out;
+}
+
+describe('canvas-edit / componentMapForCanvas', () => {
+  test('elements of an instantiated component are instances; the canvas root is not', () => {
+    const src = `
+      function Card() { return <article className="card"><h2>Hi</h2></article>; }
+      function Demo() { return <div><Card /><Card /><p>plain</p></div>; }
+    `;
+    const ids = idsOf(src);
+    const map = componentMapForCanvas(CANVAS, src);
+    // Card's own elements → instances of Card (2 usages); article is the root.
+    expect(map[ids.article as string]).toEqual({ component: 'Card', root: true, usages: 2 });
+    expect(map[ids.h2 as string]).toEqual({ component: 'Card', root: false, usages: 2 });
+    // Demo (the canvas component, never referenced as JSX) → NOT in the map.
+    expect(map[ids.div as string]).toBeUndefined();
+    expect(map[ids.p as string]).toBeUndefined();
+  });
+
+  test('no components → empty map', () => {
+    const src = `function Demo() { return <div><h1>T</h1></div>; }`;
+    const map = componentMapForCanvas(CANVAS, src);
+    expect(Object.keys(map)).toHaveLength(0);
+  });
+
+  test('unparsable source → empty map (no throw)', () => {
+    expect(componentMapForCanvas(CANVAS, 'function {{{')).toEqual({});
+  });
+});