@1agh/maude 0.15.0

package/plugins/design/dev-server/test/canvas-meta-api.test.ts

@@ -0,0 +1,236 @@
+// Phase 4 T5 — `/_api/canvas-meta` GET/PATCH endpoint round-trip.
+//
+// Verifies:
+//   - PATCH merges `viewport` into an existing `<canvas>.meta.json`
+//   - PATCH preserves other top-level keys (title, sections, ai_context …)
+//   - PATCH clamps zoom to [0.1, 4.0]
+//   - PATCH rejects non-finite viewport coords (no write, returns prior)
+//   - GET returns the merged meta
+//   - Paths that escape repoRoot are 400
+
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { describe, expect, test } from 'bun:test';
+
+import { bootServer, killProc, makeSandbox, nextPort } from './_helpers.ts';
+
+interface MetaShape {
+  title?: string;
+  sections?: unknown[];
+  viewport?: { x: number; y: number; zoom: number };
+  layout?: { artboards: unknown[] };
+  last_modified?: string;
+  [k: string]: unknown;
+}
+
+function seedCanvas(designRoot: string, name = 'Phase4.tsx', meta?: MetaShape): string {
+  const ui = join(designRoot, 'ui');
+  mkdirSync(ui, { recursive: true });
+  const tsxPath = join(ui, name);
+  writeFileSync(tsxPath, 'export default function P(){return <main/>}\n');
+  const metaPath = tsxPath.replace(/\.tsx$/, '.meta.json');
+  if (meta) writeFileSync(metaPath, JSON.stringify(meta, null, 2));
+  return tsxPath.replace(`${designRoot.replace(/\.design$/, '')}`, '').replace(/^\/+/, '');
+}
+
+function repoRel(designRoot: string, abs: string): string {
+  // designRoot ends in `.design`. repoRoot is its parent.
+  const repoRoot = designRoot.replace(/\.design$/, '').replace(/\/+$/, '');
+  return abs.startsWith(`${repoRoot}/`) ? abs.slice(repoRoot.length + 1) : abs;
+}
+
+describe('/_api/canvas-meta — GET/PATCH', () => {
+  test('PATCH merges viewport onto existing meta and preserves other keys', 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', 'Phase4.tsx');
+      writeFileSync(tsxAbs, 'export default function P(){return <main/>}\n');
+      const metaAbs = tsxAbs.replace(/\.tsx$/, '.meta.json');
+      writeFileSync(
+        metaAbs,
+        JSON.stringify({
+          title: 'Phase 4',
+          sections: [{ id: 'overview', label: 'Overview' }],
+          ai_context: { pinned_decisions: ['keep dc-* classes'] },
+        })
+      );
+      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: { viewport: { x: 12, y: 34, zoom: 1.5 } } }),
+      });
+      expect(r.status).toBe(200);
+      const merged = (await r.json()) as MetaShape;
+      expect(merged.title).toBe('Phase 4');
+      expect(merged.sections).toBeDefined();
+      expect(merged.ai_context).toBeDefined();
+      expect(merged.viewport).toEqual({ x: 12, y: 34, zoom: 1.5 });
+      expect(typeof merged.last_modified).toBe('string');
+
+      // On-disk reflects the merge.
+      const onDisk = JSON.parse(readFileSync(metaAbs, 'utf8')) as MetaShape;
+      expect(onDisk.viewport?.zoom).toBe(1.5);
+      expect(onDisk.title).toBe('Phase 4');
+    } finally {
+      await killProc(proc);
+    }
+  });
+
+  test('PATCH clamps zoom to [0.1, 4.0]', 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', 'Clamp.tsx');
+      writeFileSync(tsxAbs, 'export default function C(){return <main/>}\n');
+      writeFileSync(tsxAbs.replace(/\.tsx$/, '.meta.json'), '{"title":"Clamp"}');
+      const file = repoRel(designRoot, tsxAbs);
+
+      const r1 = await fetch(`http://localhost:${port}/_api/canvas-meta`, {
+        method: 'PATCH',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ file, patch: { viewport: { x: 0, y: 0, zoom: 99 } } }),
+      });
+      const m1 = (await r1.json()) as MetaShape;
+      expect(m1.viewport?.zoom).toBe(4);
+
+      const r2 = await fetch(`http://localhost:${port}/_api/canvas-meta`, {
+        method: 'PATCH',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ file, patch: { viewport: { x: 0, y: 0, zoom: 0.001 } } }),
+      });
+      const m2 = (await r2.json()) as MetaShape;
+      expect(m2.viewport?.zoom).toBe(0.1);
+    } finally {
+      await killProc(proc);
+    }
+  });
+
+  test('PATCH ignores non-finite viewport (NaN/Infinity)', 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', 'Bad.tsx');
+      writeFileSync(tsxAbs, 'export default function B(){return <main/>}\n');
+      writeFileSync(
+        tsxAbs.replace(/\.tsx$/, '.meta.json'),
+        '{"title":"Bad","viewport":{"x":1,"y":2,"zoom":1}}'
+      );
+      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: { viewport: { x: 'nope', y: null, zoom: 1 } } }),
+      });
+      const m = (await r.json()) as MetaShape;
+      // Prior value preserved.
+      expect(m.viewport).toEqual({ x: 1, y: 2, zoom: 1 });
+    } finally {
+      await killProc(proc);
+    }
+  });
+
+  test('GET returns the meta document', 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', 'Read.tsx');
+      writeFileSync(tsxAbs, 'export default function R(){return <main/>}\n');
+      writeFileSync(
+        tsxAbs.replace(/\.tsx$/, '.meta.json'),
+        JSON.stringify({ title: 'Read', viewport: { x: 5, y: 6, zoom: 0.5 } })
+      );
+      const file = repoRel(designRoot, tsxAbs);
+
+      const r = await fetch(
+        `http://localhost:${port}/_api/canvas-meta?file=${encodeURIComponent(file)}`
+      );
+      expect(r.status).toBe(200);
+      const m = (await r.json()) as MetaShape;
+      expect(m.title).toBe('Read');
+      expect(m.viewport?.zoom).toBe(0.5);
+    } finally {
+      await killProc(proc);
+    }
+  });
+
+  test('PATCH layout persists position-only entries (Phase 4.2 strip-on-write)', async () => {
+    // DDR-027: artboard w/h is JSX-authoritative. The client-side writer
+    // (canvas-lib.tsx patchCanvasMeta) strips w/h before PATCH; the server
+    // must round-trip whatever shape it receives without rejecting partial
+    // entries.
+    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', 'Phase42.tsx');
+      writeFileSync(tsxAbs, 'export default function P(){return <main/>}\n');
+      const metaAbs = tsxAbs.replace(/\.tsx$/, '.meta.json');
+      writeFileSync(metaAbs, JSON.stringify({ title: 'P', sections: [] }));
+      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: {
+            layout: {
+              artboards: [
+                { id: 'a', x: 100, y: 50 },
+                { id: 'b', x: 1500, y: 50 },
+              ],
+            },
+          },
+        }),
+      });
+      expect(r.status).toBe(200);
+      const merged = (await r.json()) as MetaShape;
+      const arts = merged.layout?.artboards as Array<Record<string, unknown>> | undefined;
+      expect(arts).toBeDefined();
+      expect(arts?.length).toBe(2);
+      // No w/h written.
+      expect(arts?.[0]).toEqual({ id: 'a', x: 100, y: 50 });
+      expect(arts?.[1]).toEqual({ id: 'b', x: 1500, y: 50 });
+
+      const onDisk = JSON.parse(readFileSync(metaAbs, 'utf8')) as MetaShape;
+      const diskArts = onDisk.layout?.artboards as Array<Record<string, unknown>> | undefined;
+      expect(diskArts?.[0]).not.toHaveProperty('w');
+      expect(diskArts?.[0]).not.toHaveProperty('h');
+    } finally {
+      await killProc(proc);
+    }
+  });
+
+  test('PATCH rejects paths that escape repoRoot', async () => {
+    const { root } = makeSandbox();
+    const port = nextPort();
+    const proc = await bootServer(root, port);
+    try {
+      const r = await fetch(`http://localhost:${port}/_api/canvas-meta`, {
+        method: 'PATCH',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          file: '../escape.tsx',
+          patch: { viewport: { x: 0, y: 0, zoom: 1 } },
+        }),
+      });
+      expect(r.status).toBe(404);
+    } finally {
+      await killProc(proc);
+    }
+  });
+});

package/plugins/design/dev-server/test/canvas-pipeline.test.ts

@@ -0,0 +1,180 @@
+import { describe, expect, test } from 'bun:test';
+import { parseSync } from 'oxc-parser';
+
+import { TranspileError, transpileCanvasSource } from '../canvas-pipeline.ts';
+
+const FIXTURE = `
+import { useState } from 'react';
+
+export default function DocsSite() {
+  const [count, setCount] = useState(0);
+  return (
+    <section className="hero">
+      <h1>Hello, world.</h1>
+      <p data-dc-element="hero-copy">Subhead with <em>emphasis</em>.</p>
+      <button type="button" onClick={() => setCount((c) => c + 1)}>
+        Click {count}
+      </button>
+    </section>
+  );
+}
+`;
+
+describe('transpileCanvasSource — Pass 1 (ID injection)', () => {
+  test('determinism: same source produces same locator map across calls', () => {
+    const a = transpileCanvasSource('/x/DocsSite.tsx', FIXTURE);
+    const b = transpileCanvasSource('/x/DocsSite.tsx', FIXTURE);
+    expect(Object.keys(a.locator).sort()).toEqual(Object.keys(b.locator).sort());
+    expect(a.withIds).toEqual(b.withIds);
+    expect(a.etag).toEqual(b.etag);
+  });
+
+  test('every JSX element gets exactly one data-cd-id', () => {
+    const r = transpileCanvasSource('/x/DocsSite.tsx', FIXTURE);
+    // Fixture has 5 JSX elements: section, h1, p, em, button.
+    const ids = r.withIds.match(/ data-cd-id="[0-9a-f]{8}"/g) ?? [];
+    expect(ids.length).toBe(5);
+    expect(Object.keys(r.locator).length).toBe(5);
+  });
+
+  test('IDs are 8 lowercase hex characters', () => {
+    const r = transpileCanvasSource('/x/DocsSite.tsx', FIXTURE);
+    for (const id of Object.keys(r.locator)) {
+      expect(id).toMatch(/^[0-9a-f]{8}$/);
+    }
+  });
+
+  test('whitespace-only edits inside the component preserve IDs', () => {
+    const a = transpileCanvasSource('/x/DocsSite.tsx', FIXTURE);
+    const withExtraSpaces = FIXTURE.replace('Hello, world.', '  Hello, world.  ');
+    const b = transpileCanvasSource('/x/DocsSite.tsx', withExtraSpaces);
+    // Whitespace doesn't change componentName or pre-order index of any JSX
+    // element, so the same ID set must result.
+    expect(Object.keys(b.locator).sort()).toEqual(Object.keys(a.locator).sort());
+  });
+
+  test('inserting a sibling shifts the element-to-ID mapping (documented contract)', () => {
+    // The contract per DDR-019:
+    //   - ID is computed from (componentName, preOrderIndex).
+    //   - The SET of IDs is therefore a function of element count, not content
+    //     — every position-hash that existed before still exists (superset).
+    //   - But the SOURCE ELEMENT attached to a given ID shifts: ID at idx=1 used
+    //     to point to <h1>, after inserting <span> above it now points to <span>.
+    //     This is the "selection jumps" failure mode Phase-12's (componentName,
+    //     jsxPath) fallback recovers.
+    const a = transpileCanvasSource('/x/DocsSite.tsx', FIXTURE);
+    const withInsert = FIXTURE.replace(
+      '<section className="hero">',
+      '<section className="hero">\n      <span>NEW</span>'
+    );
+    const b = transpileCanvasSource('/x/DocsSite.tsx', withInsert);
+
+    // Count: one new JSX element => one new ID.
+    expect(Object.keys(b.locator).length).toBe(Object.keys(a.locator).length + 1);
+
+    // Superset: every old position-hash still appears.
+    for (const id of Object.keys(a.locator)) expect(b.locator[id]).toBeDefined();
+
+    // jsxPath-at-ID shifts: the IDs that used to point at h1/p/em/button now
+    // point at different element types (or at the new <span>). Concretely:
+    // count how many shared IDs have an UNCHANGED jsxPath after the insert.
+    let unchangedPaths = 0;
+    for (const id of Object.keys(a.locator)) {
+      const before = a.locator[id]?.jsxPath.join('>');
+      const after = b.locator[id]?.jsxPath.join('>');
+      if (before === after) unchangedPaths += 1;
+    }
+    // Only the first element (the <section> wrapper, idx 0) is unaffected by
+    // the insert that happens inside it.
+    expect(unchangedPaths).toBe(1);
+  });
+
+  test('locator entries carry canvas, line, col, jsxPath, componentName', () => {
+    const r = transpileCanvasSource('/x/DocsSite.tsx', FIXTURE);
+    for (const entry of Object.values(r.locator)) {
+      expect(entry.canvas).toBe('/x/DocsSite.tsx');
+      expect(typeof entry.line).toBe('number');
+      expect(entry.line).toBeGreaterThan(0);
+      expect(typeof entry.col).toBe('number');
+      expect(Array.isArray(entry.jsxPath)).toBe(true);
+      expect(entry.jsxPath.length).toBeGreaterThan(0);
+      expect(entry.componentName).toBe('DocsSite');
+    }
+  });
+
+  test('jsxPath reflects element-type nesting', () => {
+    const r = transpileCanvasSource('/x/DocsSite.tsx', FIXTURE);
+    const paths = Object.values(r.locator)
+      .map((e) => e.jsxPath.join('>'))
+      .sort();
+    // Expected, sorted: section, section>button, section>h1, section>p, section>p>em
+    expect(paths).toEqual(['section', 'section>button', 'section>h1', 'section>p', 'section>p>em']);
+  });
+});
+
+describe('transpileCanvasSource — Pass 2 (JSX -> JS)', () => {
+  test('output is parseable JS (no syntax errors)', () => {
+    const r = transpileCanvasSource('/x/DocsSite.tsx', FIXTURE);
+    const parsed = parseSync('/x/DocsSite.js', r.js, { sourceType: 'module' });
+    expect(parsed.errors.length).toBe(0);
+  });
+
+  test('output preserves the default export', () => {
+    const r = transpileCanvasSource('/x/DocsSite.tsx', FIXTURE);
+    expect(r.js).toMatch(/export default/);
+  });
+
+  test('output references data-cd-id on every emitted element', () => {
+    const r = transpileCanvasSource('/x/DocsSite.tsx', FIXTURE);
+    const dcCount = (r.js.match(/"data-cd-id":\s*"[0-9a-f]{8}"/g) ?? []).length;
+    expect(dcCount).toBe(5);
+  });
+});
+
+describe('transpileCanvasSource — robustness', () => {
+  test('idempotent: re-running on the post-pass-1 source does not double-inject', () => {
+    // Re-parsing the post-pass-1 source through the pipeline should detect the
+    // existing data-cd-id attribute on every element and skip injection.
+    const first = transpileCanvasSource('/x/DocsSite.tsx', FIXTURE);
+    const second = transpileCanvasSource('/x/DocsSite.tsx', first.withIds);
+    const firstIds = (first.withIds.match(/ data-cd-id="/g) ?? []).length;
+    const secondIds = (second.withIds.match(/ data-cd-id="/g) ?? []).length;
+    expect(secondIds).toBe(firstIds);
+  });
+
+  test('handles arrow-function component bound to a PascalCase const', () => {
+    const src = `
+      const Hello = () => <h1>hi</h1>;
+      export default Hello;
+    `;
+    const r = transpileCanvasSource('/x/Hello.tsx', src);
+    expect(Object.keys(r.locator).length).toBe(1);
+    expect(Object.values(r.locator)[0]?.componentName).toBe('Hello');
+  });
+
+  test('handles JSXMemberExpression element names (motion.div)', () => {
+    const src = `
+      const motion = { div: 'div' };
+      export default function MotionCanvas() {
+        return <motion.div>boop</motion.div>;
+      }
+    `;
+    const r = transpileCanvasSource('/x/MotionCanvas.tsx', src);
+    expect(Object.keys(r.locator).length).toBe(1);
+    const entry = Object.values(r.locator)[0];
+    expect(entry?.jsxPath).toEqual(['motion.div']);
+  });
+
+  test('throws TranspileError on a malformed source', () => {
+    const broken = 'export default function X() { return <div></span>; }';
+    expect(() => transpileCanvasSource('/x/Broken.tsx', broken)).toThrow(TranspileError);
+  });
+
+  test('source with no JSX produces empty locator + still-valid JS', () => {
+    const src = 'export default function X() { return 42; }';
+    const r = transpileCanvasSource('/x/X.tsx', src);
+    expect(Object.keys(r.locator).length).toBe(0);
+    const parsed = parseSync('/x/X.js', r.js, { sourceType: 'module' });
+    expect(parsed.errors.length).toBe(0);
+  });
+});

package/plugins/design/dev-server/test/canvas-route.test.ts

@@ -0,0 +1,176 @@
+// Integration test for the /.design/ui/*.tsx canvas route.
+//
+// Boots a real Bun.serve dev-server against a sandbox that contains a single
+// canvas TSX file, then verifies:
+//   - GET returns 200 + application/javascript + an ETag header
+//   - If-None-Match: <etag> returns 304 with no body
+//   - The cached body parses as JS via the same Bun.Transpiler the route uses
+//   - _locator.json is written for the canvas slug
+//   - Path-traversal attempts get rejected
+//   - Non-existent canvases return 404
+
+import { describe, expect, test } from 'bun:test';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { Subprocess } from 'bun';
+
+import { readLocator } from '../locator.ts';
+import { bootServer, killProc, nextPort } from './_helpers.ts';
+
+interface CanvasSandbox {
+  root: string;
+  designRoot: string;
+  cleanup: () => void;
+}
+
+function makeCanvasSandbox(canvasName: string, canvasSource: string): CanvasSandbox {
+  const root = mkdtempSync(join(tmpdir(), 'mdcc-canvas-route-'));
+  const designRoot = join(root, '.design');
+  mkdirSync(join(designRoot, 'ui'), { recursive: true });
+  writeFileSync(
+    join(designRoot, 'config.json'),
+    JSON.stringify({
+      name: 'test',
+      designRoot: '.design',
+      canvasGroups: [
+        { label: 'UI', path: 'ui' },
+        { label: 'System', path: 'system' },
+      ],
+    })
+  );
+  writeFileSync(join(designRoot, 'ui', canvasName), canvasSource);
+  return { root, designRoot, cleanup: () => rmSync(root, { recursive: true, force: true }) };
+}
+
+const SIMPLE_TSX = `
+export default function Hello() {
+  return (
+    <section>
+      <h1>Hello, world.</h1>
+      <p>Subhead.</p>
+    </section>
+  );
+}
+`;
+
+describe('TSX canvas route', () => {
+  let proc: Subprocess | null = null;
+  let port = 0;
+  let sb: CanvasSandbox | null = null;
+
+  async function boot(canvasName: string, source: string) {
+    sb = makeCanvasSandbox(canvasName, source);
+    port = nextPort();
+    proc = await bootServer(sb.root, port);
+  }
+
+  async function teardown() {
+    if (proc) await killProc(proc);
+    if (sb) sb.cleanup();
+    proc = null;
+    sb = null;
+  }
+
+  test('returns 200 + JS + ETag for a valid canvas', async () => {
+    await boot('Hello.tsx', SIMPLE_TSX);
+    try {
+      const r = await fetch(`http://localhost:${port}/.design/ui/Hello.tsx`);
+      expect(r.status).toBe(200);
+      expect(r.headers.get('content-type')).toMatch(/javascript/);
+      const etag = r.headers.get('etag');
+      expect(etag).toBeTruthy();
+      expect(etag).toMatch(/^[0-9a-f]+$/i);
+      const body = await r.text();
+      // Body should contain data-cd-id metadata + an export — proves the two
+      // passes ran end to end.
+      expect(body).toMatch(/data-cd-id/);
+      // Bun.build emits `export { Hello as default }` (renamed-default form)
+      // rather than `export default Hello`. Both are valid ESM; match either.
+      expect(body).toMatch(/export\s+\{[\s\S]*\bdefault\b[\s\S]*\}|export\s+default\b/);
+    } finally {
+      await teardown();
+    }
+  });
+
+  test('returns 304 on a matching If-None-Match', async () => {
+    await boot('Hello.tsx', SIMPLE_TSX);
+    try {
+      const first = await fetch(`http://localhost:${port}/.design/ui/Hello.tsx`);
+      const etag = first.headers.get('etag') as string;
+      const second = await fetch(`http://localhost:${port}/.design/ui/Hello.tsx`, {
+        headers: { 'If-None-Match': etag },
+      });
+      expect(second.status).toBe(304);
+      // 304 body should be empty.
+      const body = await second.text();
+      expect(body.length).toBe(0);
+    } finally {
+      await teardown();
+    }
+  });
+
+  test('writes _locator.json with the canvas slug populated', async () => {
+    await boot('Docs Site.tsx', SIMPLE_TSX);
+    try {
+      await fetch(`http://localhost:${port}/.design/ui/Docs%20Site.tsx`);
+      const locFile = join(sb?.designRoot, '_locator.json');
+      // The locator is written synchronously before the response — the file
+      // must exist + carry the canvas slug.
+      expect(existsSync(locFile)).toBe(true);
+      const map = await readLocator(locFile, 'ui/Docs Site');
+      expect(map).not.toBeNull();
+      // SIMPLE_TSX has three JSX elements: section, h1, p.
+      expect(Object.keys(map as Record<string, unknown>).length).toBe(3);
+    } finally {
+      await teardown();
+    }
+  });
+
+  test('returns 404 for a missing canvas', async () => {
+    await boot('Hello.tsx', SIMPLE_TSX);
+    try {
+      const r = await fetch(`http://localhost:${port}/.design/ui/Missing.tsx`);
+      expect(r.status).toBe(404);
+    } finally {
+      await teardown();
+    }
+  });
+
+  test('rejects path traversal via .. (403 from safePathUnderRoot)', async () => {
+    await boot('Hello.tsx', SIMPLE_TSX);
+    try {
+      const r = await fetch(`http://localhost:${port}/.design/ui/../../etc/passwd.tsx`);
+      // safePathUnderRoot kicks the request out before our TSX dispatch runs.
+      expect([400, 403, 404]).toContain(r.status);
+    } finally {
+      await teardown();
+    }
+  });
+
+  test('returns 500 on a malformed canvas with a useful error body', async () => {
+    await boot('Broken.tsx', 'export default function X() { return <div></span>; }');
+    try {
+      const r = await fetch(`http://localhost:${port}/.design/ui/Broken.tsx`);
+      expect(r.status).toBe(500);
+      const body = await r.text();
+      expect(body).toMatch(/Transpile error/i);
+    } finally {
+      await teardown();
+    }
+  });
+
+  test('cache: second GET returns the same ETag without re-reading the file', async () => {
+    await boot('Hello.tsx', SIMPLE_TSX);
+    try {
+      const a = await fetch(`http://localhost:${port}/.design/ui/Hello.tsx`);
+      const b = await fetch(`http://localhost:${port}/.design/ui/Hello.tsx`);
+      expect(a.headers.get('etag')).toBe(b.headers.get('etag'));
+      const bodyA = await a.text();
+      const bodyB = await b.text();
+      expect(bodyA).toBe(bodyB);
+    } finally {
+      await teardown();
+    }
+  });
+});

package/plugins/design/dev-server/test/fs-watch.test.ts

@@ -0,0 +1,41 @@
+// Smoke: recursive fs.watch fires when a file is written under designRoot.
+
+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 { createFsWatch } from '../fs-watch.ts';
+
+describe('fs-watch.ts', () => {
+  test('emits fs:html on recursive write', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'mdcc-fswatch-'));
+    mkdirSync(join(root, '.design', 'ui', 'nested'), { recursive: true });
+    writeFileSync(join(root, '.design', 'config.json'), '{"name":"t"}');
+
+    const origArgv = process.argv;
+    process.argv = [...origArgv, '--root', root];
+    let watch: ReturnType<typeof createFsWatch> | null = null;
+    try {
+      const ctx = createContext();
+      watch = createFsWatch(ctx);
+
+      const seen: string[] = [];
+      ctx.bus.on('fs:html', (file) => seen.push(String(file)));
+
+      watch.start();
+      // give the watcher a moment to register.
+      await Bun.sleep(80);
+
+      const target = join(root, '.design', 'ui', 'nested', 'evt.html');
+      writeFileSync(target, '<doc>1</doc>');
+      await Bun.sleep(250);
+
+      expect(seen.some((f) => f.endsWith('evt.html'))).toBe(true);
+    } finally {
+      watch?.stop();
+      process.argv = origArgv;
+    }
+  });
+});