@1agh/maude 0.15.0

package/plugins/design/dev-server/test/handoff-static-frames.test.ts

@@ -0,0 +1,215 @@
+// Phase 4 T7 — verify `applyHandoffStaticOverrides()` strips engine-bearing
+// code from handoff inline output. Engine exports (useViewportController,
+// DCMiniMap, DCZoomToolbar, ...) MUST NOT travel into a registry item.
+
+import { describe, expect, test } from 'bun:test';
+
+import { buildLibMap, inlineUsedExports } from '../canvas-lib-inline.ts';
+import { HANDOFF_STATIC_FRAME_EXPORTS, applyHandoffStaticOverrides } from '../handoff.ts';
+
+const LIB_PATH = '/virtual/_lib/canvas-lib.tsx';
+
+// Trimmed canvas-lib sample — DesignCanvas pulls useViewportController +
+// WorldContext + DCMiniMap + DCZoomToolbar transitively (the real shape).
+const LIB_SOURCE = `
+import { createContext, useContext } from "react";
+
+export function useViewportController() {
+  return { viewport: { x: 0, y: 0, zoom: 1 } };
+}
+
+export function DCMiniMap() { return <div className="dc-mm" />; }
+export function DCZoomToolbar() { return <div className="dc-zoom-tb" />; }
+
+const WorldContext = createContext(null);
+function harvestArtboards(c) { return c; }
+function synthDefaultGrid(s) { return s; }
+
+export function DesignCanvas({ children }) {
+  const ctl = useViewportController();
+  const seeds = harvestArtboards(children);
+  const layout = synthDefaultGrid(seeds);
+  return (
+    <WorldContext.Provider value={{ ctl, layout }}>
+      <div className="dc-canvas">
+        <div className="dc-world" style={{transform:'translate(0,0) scale(1)'}}>{children}</div>
+        <DCMiniMap />
+        <DCZoomToolbar />
+      </div>
+    </WorldContext.Provider>
+  );
+}
+
+export function DCSection({ id, title, children }) {
+  const ctx = useContext(WorldContext);
+  return <section className="dc-section" data-dc-section={id} data-ctx={!!ctx}><h2>{title}</h2>{children}</section>;
+}
+
+export function DCArtboard({ id, label, width, height, children }) {
+  const ctx = useContext(WorldContext);
+  return (
+    <article className="dc-artboard" data-dc-screen={id} data-has-ctx={!!ctx} style={{ width, height }}>
+      <header>{label}</header>
+      <div>{children}</div>
+    </article>
+  );
+}
+`;
+
+const SAMPLE_CANVAS = `import { DesignCanvas, DCSection, DCArtboard } from "@maude/canvas-lib";
+export default function X() {
+  return (
+    <DesignCanvas>
+      <DCSection id="s" title="S">
+        <DCArtboard id="a" label="A" width={100} height={100}>hi</DCArtboard>
+      </DCSection>
+    </DesignCanvas>
+  );
+}
+`;
+
+describe('handoff-static-frames', () => {
+  test('HANDOFF_STATIC_FRAME_EXPORTS lists DesignCanvas + DCSection + DCArtboard', () => {
+    expect([...HANDOFF_STATIC_FRAME_EXPORTS].sort()).toEqual([
+      'DCArtboard',
+      'DCSection',
+      'DesignCanvas',
+    ]);
+  });
+
+  test('without overrides — engine code IS pulled into the handoff inline', () => {
+    const libMap = buildLibMap(LIB_PATH, LIB_SOURCE);
+    const r = inlineUsedExports(SAMPLE_CANVAS, libMap);
+    // BFS dragged in everything DesignCanvas needs.
+    expect(r.content).toContain('useViewportController');
+    expect(r.content).toContain('DCMiniMap');
+    expect(r.content).toContain('DCZoomToolbar');
+    expect(r.content).toContain('WorldContext');
+  });
+
+  test('with overrides — engine code is stripped from handoff inline', () => {
+    const libMap = buildLibMap(LIB_PATH, LIB_SOURCE);
+    applyHandoffStaticOverrides(libMap);
+    const r = inlineUsedExports(SAMPLE_CANVAS, libMap);
+    expect(r.content).not.toContain('useViewportController');
+    expect(r.content).not.toContain('DCMiniMap');
+    expect(r.content).not.toContain('DCZoomToolbar');
+    expect(r.content).not.toContain('WorldContext');
+    expect(r.content).not.toContain('harvestArtboards');
+    expect(r.content).not.toContain('synthDefaultGrid');
+    // The static frame replacements ARE present.
+    expect(r.content).toContain('function DesignCanvas');
+    expect(r.content).toContain('function DCSection');
+    expect(r.content).toContain('function DCArtboard');
+    // The static DesignCanvas is the minimal `<div className="dc-canvas">` form.
+    expect(r.content).toContain('<div className="dc-canvas">{children}</div>');
+  });
+
+  test('overrides are a no-op when the canvas does not import the frame', () => {
+    const libMap = buildLibMap(LIB_PATH, LIB_SOURCE);
+    applyHandoffStaticOverrides(libMap);
+    // Canvas only imports DCArtboard — DesignCanvas + DCSection stay unused.
+    const canvas = `import { DCArtboard } from "@maude/canvas-lib";
+export default function Y() {
+  return <DCArtboard id="x" label="X" width={10} height={10}>hi</DCArtboard>;
+}
+`;
+    const r = inlineUsedExports(canvas, libMap);
+    expect(r.content).toContain('function DCArtboard');
+    expect(r.content).not.toContain('function DesignCanvas');
+    expect(r.content).not.toContain('function DCSection');
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Phase 4.2 — drag + snap exports must also be stripped from handoff output.
+// The real DCArtboard references useArtboardDrag (and friends) internally;
+// the static-frame override breaks that chain. This test pins that behavior.
+
+const LIB_SOURCE_4_2 = `
+import { createContext, useContext } from "react";
+
+export function useViewportController() { return { viewport: { x: 0, y: 0, zoom: 1 } }; }
+export function DCMiniMap() { return <div />; }
+export function DCZoomToolbar() { return <div />; }
+
+const WorldContext = createContext(null);
+function harvestArtboards(c) { return c; }
+function synthDefaultGrid(s) { return s; }
+
+export function computeSnap(p, others, opts) { return { x: p.x, y: p.y, guides: [] }; }
+export function useSnapGuides() { /* placeholder */ }
+export function useArtboardDrag(opts) {
+  const _snap = computeSnap;
+  return { bindHandle: () => ({}), dragState: { kind: "idle" } };
+}
+const DragStateContext = createContext(null);
+export function SnapGuideOverlay() {
+  const ctx = useContext(DragStateContext);
+  return ctx ? <div className="dc-snap-guide" /> : null;
+}
+
+export function DesignCanvas({ children }) {
+  const ctl = useViewportController();
+  const seeds = harvestArtboards(children);
+  const layout = synthDefaultGrid(seeds);
+  return (
+    <WorldContext.Provider value={{ ctl, layout }}>
+      <DragStateContext.Provider value={null}>
+        <div className="dc-canvas">{children}<DCMiniMap /><DCZoomToolbar /><SnapGuideOverlay /></div>
+      </DragStateContext.Provider>
+    </WorldContext.Provider>
+  );
+}
+
+export function DCSection({ id, title, children }) {
+  return <section data-id={id}><h2>{title}</h2>{children}</section>;
+}
+
+export function DCArtboard({ id, label, width, height, children }) {
+  const drag = useArtboardDrag({ artboardId: id });
+  return (
+    <article className="dc-artboard" data-dc-screen={id} {...drag.bindHandle()} style={{ width, height }}>
+      <header>{label}</header>
+      <div>{children}</div>
+    </article>
+  );
+}
+`;
+
+const PHASE_4_2_CANVAS = `import { DesignCanvas, DCSection, DCArtboard } from "@maude/canvas-lib";
+export default function X() {
+  return (
+    <DesignCanvas>
+      <DCSection id="s" title="S">
+        <DCArtboard id="a" label="A" width={100} height={100}>hi</DCArtboard>
+      </DCSection>
+    </DesignCanvas>
+  );
+}
+`;
+
+describe('handoff-static-frames / Phase 4.2 drag + snap exports', () => {
+  test('without overrides — drag + snap engine code IS pulled in (regression baseline)', () => {
+    const libMap = buildLibMap(LIB_PATH, LIB_SOURCE_4_2);
+    const r = inlineUsedExports(PHASE_4_2_CANVAS, libMap);
+    // DCArtboard depends on useArtboardDrag → BFS reaches it.
+    expect(r.content).toContain('useArtboardDrag');
+    // DesignCanvas wraps SnapGuideOverlay → BFS reaches it.
+    expect(r.content).toContain('SnapGuideOverlay');
+  });
+
+  test('with overrides — drag + snap engine code is stripped', () => {
+    const libMap = buildLibMap(LIB_PATH, LIB_SOURCE_4_2);
+    applyHandoffStaticOverrides(libMap);
+    const r = inlineUsedExports(PHASE_4_2_CANVAS, libMap);
+    expect(r.content).not.toContain('useArtboardDrag');
+    expect(r.content).not.toContain('SnapGuideOverlay');
+    expect(r.content).not.toContain('computeSnap');
+    expect(r.content).not.toContain('useSnapGuides');
+    expect(r.content).not.toContain('DragStateContext');
+    // Static frames still land as the minimal markup.
+    expect(r.content).toContain('function DesignCanvas');
+    expect(r.content).toContain('function DCArtboard');
+  });
+});

package/plugins/design/dev-server/test/handoff.test.ts

@@ -0,0 +1,281 @@
+// handoff.ts — Phase 3.6 Task 7 + 12b. Tests the shadcn registry-item emitter:
+// data-cd-id strip, import classification, className harvest, CSS subset
+// extraction, full emit round-trip.
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { transpileCanvasSource } from '../canvas-pipeline.ts';
+import {
+  type RegistryItem,
+  classifyImports,
+  collectClassNames,
+  emitRegistryItem,
+  filterComponentsCss,
+  filterTokensCss,
+  stripDataCdId,
+  writeRegistryItem,
+} from '../handoff.ts';
+
+const CANVAS = '/abs/Canvas.tsx';
+
+describe('handoff / stripDataCdId', () => {
+  test('removes pipeline-emitted data-cd-id attrs', () => {
+    const src = `function Demo() { return <div className="btn">x</div>; }`;
+    const withIds = transpileCanvasSource(CANVAS, src).withIds;
+    expect(withIds).toContain('data-cd-id=');
+    const stripped = stripDataCdId(CANVAS, withIds);
+    expect(stripped).not.toContain('data-cd-id');
+    // Same shape as the original source (data-cd-id strip is idempotent on the
+    // original).
+    expect(stripped).toBe(src);
+  });
+
+  test('strip is idempotent on already-stripped source', () => {
+    const src = 'function Demo() { return <div>x</div>; }';
+    expect(stripDataCdId(CANVAS, src)).toBe(src);
+  });
+
+  test('preserves other attributes byte-for-byte', () => {
+    const src = `function Demo() { return <button className="btn" aria-label="ok" data-cd-id="deadbeef">go</button>; }`;
+    const out = stripDataCdId(CANVAS, src);
+    expect(out).toContain('className="btn"');
+    expect(out).toContain('aria-label="ok"');
+    expect(out).not.toContain('data-cd-id');
+  });
+});
+
+describe('handoff / classifyImports', () => {
+  test('separates npm specifiers from registry deps', () => {
+    const src = `
+      import { useState } from "react";
+      import * as ReactDOM from "react-dom/client";
+      import { motion } from "motion/react";
+      import { Button } from "@/components/ui/button";
+      import { Card } from "@/components/ui/card";
+      import { localThing } from "./local";
+      function Demo() { return <div/>; }
+    `;
+    const r = classifyImports(CANVAS, src);
+    expect(r.dependencies).toEqual(['motion', 'react', 'react-dom']);
+    expect(r.registryDependencies).toEqual(['button', 'card']);
+  });
+
+  test('relative imports are ignored', () => {
+    const src = `
+      import { sibling } from "./a";
+      import { up } from "../b/c";
+      function Demo() { return <div/>; }
+    `;
+    const r = classifyImports(CANVAS, src);
+    // Bun.Transpiler.scanImports auto-surfaces "react" when JSX is present
+    // (it's the implicit jsx-runtime import). That's fine — react is in the
+    // mandatory dep floor anyway. The relative imports must NOT appear.
+    expect(r.dependencies.every((d) => !d.startsWith('.'))).toBe(true);
+    expect(r.dependencies).not.toContain('./a');
+    expect(r.registryDependencies).toEqual([]);
+  });
+});
+
+describe('handoff / collectClassNames', () => {
+  test('gathers tokens from className literals', () => {
+    const src = `
+      function Demo() {
+        return (
+          <div className="btn btn--ghost">
+            <span className="sku">x</span>
+            <em className={"tile " + "tile--active"}>y</em>
+          </div>
+        );
+      }
+    `;
+    const names = collectClassNames(CANVAS, src);
+    expect(names.has('btn')).toBe(true);
+    expect(names.has('btn--ghost')).toBe(true);
+    expect(names.has('sku')).toBe(true);
+    // String concat → first literal contributes "tile ", second contributes
+    // "tile--active". Both surface.
+    expect(names.has('tile')).toBe(true);
+    expect(names.has('tile--active')).toBe(true);
+  });
+
+  test('TemplateLiteral quasis contribute', () => {
+    const src = `
+      function Demo() {
+        const active = true;
+        return <div className={\`btn \${active ? 'btn--active' : ''}\`}>x</div>;
+      }
+    `;
+    const names = collectClassNames(CANVAS, src);
+    expect(names.has('btn')).toBe(true);
+  });
+});
+
+describe('handoff / filterComponentsCss', () => {
+  const cssSource = `
+    /* Buttons */
+    .btn {
+      padding: 6px var(--space-3);
+      color: var(--fg-0);
+    }
+    .btn--ghost {
+      background: transparent;
+    }
+    .btn:hover { color: var(--accent); }
+    .sku {
+      letter-spacing: var(--tracking-sku);
+    }
+    .unused {
+      color: red;
+    }
+    @media (min-width: 1200px) {
+      .btn { padding: 8px var(--space-4); }
+      .unused { font-size: 16px; }
+    }
+  `;
+
+  test('keeps rules whose base class is in the keep set', () => {
+    const r = filterComponentsCss(cssSource, new Set(['btn']));
+    expect(r.css).toContain('.btn {');
+    expect(r.css).toContain('.btn--ghost');
+    expect(r.css).toContain('.btn:hover');
+    expect(r.css).not.toContain('.unused');
+    expect(r.css).not.toContain('.sku');
+  });
+
+  test('collects var(--*) tokens from kept rules', () => {
+    const r = filterComponentsCss(cssSource, new Set(['btn']));
+    expect(r.tokens.has('--space-3')).toBe(true);
+    expect(r.tokens.has('--fg-0')).toBe(true);
+    expect(r.tokens.has('--accent')).toBe(true);
+    expect(r.tokens.has('--tracking-sku')).toBe(false);
+  });
+
+  test('recurses into @media rules', () => {
+    const r = filterComponentsCss(cssSource, new Set(['btn']));
+    expect(r.css).toContain('@media');
+    expect(r.css).toContain('--space-4');
+  });
+
+  test('empty keep set produces empty output', () => {
+    const r = filterComponentsCss(cssSource, new Set());
+    expect(r.css.trim()).toBe('');
+  });
+});
+
+describe('handoff / filterTokensCss', () => {
+  const tokensCss = `
+    :root {
+      --fg-0: #111;
+      --bg-0: #fff;
+      --accent: #d97706;
+      --unused: #abc;
+    }
+  `;
+
+  test('extracts only requested tokens', () => {
+    const r = filterTokensCss(tokensCss, new Set(['--fg-0', '--accent']));
+    expect(r.theme['fg-0']).toBe('#111');
+    expect(r.theme.accent).toBe('#d97706');
+    expect(r.theme.unused).toBeUndefined();
+    expect(r.usedCss).toContain('--fg-0: #111;');
+    expect(r.usedCss).toContain('--accent: #d97706;');
+    expect(r.usedCss).not.toContain('--unused');
+  });
+});
+
+describe('handoff / emitRegistryItem end-to-end', () => {
+  let tmpDir = '';
+  beforeAll(() => {
+    tmpDir = mkdtempSync(path.join(tmpdir(), 'handoff-'));
+  });
+  afterAll(() => {
+    if (tmpDir) rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test('emits valid registry-item with stripped TSX + bundled CSS + cssVars', async () => {
+    // Lay out a minimal canvas + DS in the tmp dir.
+    const canvasAbs = path.join(tmpDir, 'Test Canvas.tsx');
+    const componentsCssAbs = path.join(tmpDir, '_components.css');
+    const tokensCssAbs = path.join(tmpDir, 'tokens.css');
+    await Bun.write(
+      canvasAbs,
+      `import { useState } from "react";
+       import { Button } from "@/components/ui/button";
+       export default function TestCanvas() {
+         return (
+           <div className="mdcc">
+             <h1 className="sku">Hi</h1>
+             <button className="btn btn--ghost" data-cd-id="cafef00d">Go</button>
+           </div>
+         );
+       }`
+    );
+    await Bun.write(
+      componentsCssAbs,
+      `.btn { padding: 6px var(--space-3); color: var(--fg-0); }
+       .btn--ghost { background: transparent; }
+       .sku { letter-spacing: var(--tracking-sku); }
+       .unused { color: red; }`
+    );
+    await Bun.write(
+      tokensCssAbs,
+      ':root { --space-3: 12px; --fg-0: #111; --tracking-sku: 0.04em; --unused: #abc; }'
+    );
+
+    const item = await emitRegistryItem({
+      canvasAbsPath: canvasAbs,
+      title: 'Test Canvas',
+      description: 'Smoke harness',
+      componentsCssPath: componentsCssAbs,
+      tokensCssPath: tokensCssAbs,
+    });
+
+    expect(item.$schema).toBe('https://ui.shadcn.com/schema/registry-item.json');
+    expect(item.name).toBe('test-canvas');
+    expect(item.type).toBe('registry:block');
+    expect(item.title).toBe('Test Canvas');
+    expect(item.description).toBe('Smoke harness');
+    expect(item.dependencies).toContain('react');
+    expect(item.dependencies).toContain('react-dom');
+    expect(item.registryDependencies).toEqual(['button']);
+
+    // files[0] is the TSX, sans data-cd-id.
+    expect(item.files[0]?.path).toBe('components/test-canvas.tsx');
+    expect(item.files[0]?.type).toBe('registry:component');
+    expect(item.files[0]?.content).not.toContain('data-cd-id');
+
+    // CSS bundle present + token bundle present + cssVars present.
+    const cssFile = item.files.find((f) => f.type === 'registry:style');
+    expect(cssFile).toBeDefined();
+    expect(cssFile?.content).toContain('.btn');
+    expect(cssFile?.content).toContain('.sku');
+    expect(cssFile?.content).not.toContain('.unused');
+
+    const tokenFile = item.files.find((f) => f.type === 'registry:theme');
+    expect(tokenFile?.content).toContain('--space-3');
+    expect(tokenFile?.content).toContain('--fg-0');
+    expect(tokenFile?.content).not.toContain('--unused');
+
+    expect(item.cssVars?.theme?.['space-3']).toBe('12px');
+    expect(item.cssVars?.theme?.['fg-0']).toBe('#111');
+
+    // Persisted form is valid JSON.
+    const dest = path.join(tmpDir, 'Test Canvas.registry.json');
+    await writeRegistryItem(dest, item);
+    const parsed: RegistryItem = await Bun.file(dest).json();
+    expect(parsed.name).toBe('test-canvas');
+    expect(parsed.files.length).toBe(item.files.length);
+  });
+
+  test('emit without CSS paths produces TSX-only registry-item', async () => {
+    const canvasAbs = path.join(tmpDir, 'NoCss.tsx');
+    await Bun.write(canvasAbs, 'export default function NoCss() { return <div>x</div>; }');
+    const item = await emitRegistryItem({ canvasAbsPath: canvasAbs });
+    expect(item.files.length).toBe(1);
+    expect(item.files[0]?.type).toBe('registry:component');
+    expect(item.cssVars).toBeUndefined();
+  });
+});

package/plugins/design/dev-server/test/history-rollback.test.ts

@@ -0,0 +1,62 @@
+// Smoke: snapshot writer + rollback reader round-trip (history.ts directly,
+// no server process).
+
+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 { createContext } from '../context.ts';
+import { createHistory } from '../history.ts';
+
+function withSandbox<T>(fn: (ctx: ReturnType<typeof createContext>) => Promise<T>): Promise<T> {
+  const root = mkdtempSync(join(tmpdir(), 'mdcc-history-'));
+  mkdirSync(join(root, '.design', 'ui'), { recursive: true });
+  writeFileSync(join(root, '.design', 'config.json'), '{"name":"t"}');
+  writeFileSync(join(root, '.design', 'ui', 'a.html'), '<doc>a</doc>');
+
+  // createContext() reads --root from argv; spoof it.
+  const origArgv = process.argv;
+  process.argv = [...origArgv, '--root', root];
+  try {
+    const ctx = createContext();
+    return fn(ctx);
+  } finally {
+    process.argv = origArgv;
+  }
+}
+
+describe('history.ts', () => {
+  test('writeSnapshot + readSnapshot round-trip', async () => {
+    await withSandbox(async (ctx) => {
+      const hist = createHistory(ctx);
+      const wrote = await hist.writeSnapshot('.design/ui/a.html', '<doc>v1</doc>', 'pre-edit');
+      expect(wrote.slug).toBe('ui-a');
+      expect(wrote.reason).toBe('pre-edit');
+      expect(wrote.size).toBeGreaterThan(0);
+
+      const list = await hist.listSnapshots('.design/ui/a.html');
+      expect(list.length).toBe(1);
+      expect(list[0]?.ts).toBe(wrote.ts);
+
+      const read = await hist.readSnapshot('.design/ui/a.html', wrote.ts);
+      expect(read).not.toBeNull();
+      expect(new TextDecoder().decode(read?.content)).toBe('<doc>v1</doc>');
+    });
+  });
+
+  test('rollback overwrites the target file', async () => {
+    await withSandbox(async (ctx) => {
+      const hist = createHistory(ctx);
+      const fp = '.design/ui/a.html';
+      // Take a snapshot of the original content, mutate the file, then roll back.
+      const original = await Bun.file(join(ctx.paths.repoRoot, fp)).text();
+      const snap = await hist.writeSnapshot(fp, original, 'baseline');
+      await Bun.write(join(ctx.paths.repoRoot, fp), '<doc>modified</doc>');
+      const restored = await hist.rollback(fp, snap.ts);
+      expect(restored).not.toBeNull();
+      const after = await Bun.file(join(ctx.paths.repoRoot, fp)).text();
+      expect(after).toBe(original);
+    });
+  });
+});

package/plugins/design/dev-server/test/hmr-broadcast.test.ts

@@ -0,0 +1,108 @@
+// hmr-broadcast — Phase 3.6.1 Task 8. fs:any → canvas-hmr WS message classifier.
+
+import { describe, expect, test } from 'bun:test';
+
+import { type Context, createBus } from '../context.ts';
+import { HMR_DEBOUNCE_MS, type HmrMessage, createHmrBroadcaster } from '../hmr-broadcast.ts';
+
+function mkCtx(): Context {
+  const bus = createBus();
+  return {
+    cfg: {} as Context['cfg'],
+    projectLabel: '',
+    paths: {} as Context['paths'],
+    bus,
+  };
+}
+
+async function awaitNextFlush(): Promise<void> {
+  await new Promise((r) => setTimeout(r, HMR_DEBOUNCE_MS + 20));
+}
+
+describe('hmr-broadcast / classification', () => {
+  test('.tsx → mode: module', async () => {
+    const ctx = mkCtx();
+    const got: HmrMessage[] = [];
+    const h = createHmrBroadcaster(ctx, (m) => got.push(m));
+    ctx.bus.emit('fs:any', 'ui/Docs Site.tsx');
+    await awaitNextFlush();
+    expect(got).toHaveLength(1);
+    expect(got[0]?.mode).toBe('module');
+    expect(got[0]?.file).toBe('ui/Docs Site.tsx');
+    expect(got[0]?.scope).toBe('canvas');
+    h.stop();
+  });
+
+  test('.css → mode: css', async () => {
+    const ctx = mkCtx();
+    const got: HmrMessage[] = [];
+    const h = createHmrBroadcaster(ctx, (m) => got.push(m));
+    ctx.bus.emit('fs:any', 'ui/Docs Site.css');
+    await awaitNextFlush();
+    expect(got[0]?.mode).toBe('css');
+    h.stop();
+  });
+
+  test('_lib/* → mode: hard, scope: lib', async () => {
+    const ctx = mkCtx();
+    const got: HmrMessage[] = [];
+    const h = createHmrBroadcaster(ctx, (m) => got.push(m));
+    ctx.bus.emit('fs:any', '_lib/canvas-lib.tsx');
+    await awaitNextFlush();
+    expect(got[0]?.mode).toBe('hard');
+    expect(got[0]?.scope).toBe('lib');
+    h.stop();
+  });
+
+  test('unrelated extensions are dropped', async () => {
+    const ctx = mkCtx();
+    const got: HmrMessage[] = [];
+    const h = createHmrBroadcaster(ctx, (m) => got.push(m));
+    ctx.bus.emit('fs:any', 'ui/screenshot.png');
+    ctx.bus.emit('fs:any', '_locator.json');
+    await awaitNextFlush();
+    expect(got).toHaveLength(0);
+    h.stop();
+  });
+});
+
+describe('hmr-broadcast / debouncing', () => {
+  test('two rapid events collapse to one message', async () => {
+    const ctx = mkCtx();
+    const got: HmrMessage[] = [];
+    const h = createHmrBroadcaster(ctx, (m) => got.push(m));
+    ctx.bus.emit('fs:any', 'ui/Smoke.tsx');
+    ctx.bus.emit('fs:any', 'ui/Smoke.tsx');
+    ctx.bus.emit('fs:any', 'ui/Smoke.tsx');
+    await awaitNextFlush();
+    expect(got).toHaveLength(1);
+    h.stop();
+  });
+
+  test('coalescing prefers hard > module > css', async () => {
+    const ctx = mkCtx();
+    const got: HmrMessage[] = [];
+    const h = createHmrBroadcaster(ctx, (m) => got.push(m));
+    // Burst of mixed events; final classification should be the strongest
+    // (hard, from the _lib change).
+    ctx.bus.emit('fs:any', 'ui/Smoke.css');
+    ctx.bus.emit('fs:any', 'ui/Smoke.tsx');
+    ctx.bus.emit('fs:any', '_lib/canvas-lib.tsx');
+    await awaitNextFlush();
+    expect(got).toHaveLength(1);
+    expect(got[0]?.mode).toBe('hard');
+    h.stop();
+  });
+});
+
+describe('hmr-broadcast / stop', () => {
+  test('stop() prevents further broadcasts', async () => {
+    const ctx = mkCtx();
+    const got: HmrMessage[] = [];
+    const h = createHmrBroadcaster(ctx, (m) => got.push(m));
+    h.stop();
+    ctx.bus.emit('fs:any', 'ui/X.tsx');
+    await awaitNextFlush();
+    expect(got).toHaveLength(0);
+  });
+});