@typecad/cuttlefish 1.0.0-alpha.11 → 1.0.0-alpha.13

package/dist/orchestrator/graph-builder.d.ts

@@ -15,4 +15,7 @@ export declare function topologicalSortFiles(files: string[], dependencies: Map<
  * @param boardPackage  When provided, `@typecad/board` imports resolve to this
  *                      board package (e.g. `'@typecad/board-arduino-uno'`).
  */
-export declare function collectTranspileGraph(entryFile: string, boardPackage?: string): TranspileGraphResult;
+export declare function collectTranspileGraph(entryFile: string, boardPackage?: string, imageDecodeOpts?: {
+    maxW?: number;
+    maxH?: number;
+}): Promise<TranspileGraphResult>;

package/dist/orchestrator/graph-builder.js

@@ -68,7 +68,7 @@ export function topologicalSortFiles(files, dependencies) {
  * @param boardPackage  When provided, `@typecad/board` imports resolve to this
  *                      board package (e.g. `'@typecad/board-arduino-uno'`).
  */
-export function collectTranspileGraph(entryFile, boardPackage) {
+export async function collectTranspileGraph(entryFile, boardPackage, imageDecodeOpts) {
     const ordered = [];
     const pending = [path.resolve(entryFile)];
     const visited = new Set();
@@ -102,6 +102,10 @@ export function collectTranspileGraph(entryFile, boardPackage) {
             const parts = ui.splitUiFile(sourceText);
             // Register the template as a UI module at <file>.ui.html (synthetic path).
             const uiHtmlPath = filePath + ".html";
+            // Prime the image-conversion cache before the (synchronous) module
+            // load — <img src="*.png|jpg|ico|…"> decodes here, and the module's
+            // asset reader + natural-size layout pull from the cache.
+            await ui.warmUpImageDecoding(parts.html, path.dirname(filePath), imageDecodeOpts ?? {});
             ui.loadUIModuleFromText(uiHtmlPath, parts.html, parts.style, filePath);
             uiModules.add(uiHtmlPath);
             // Use the <script> as the TS source for import-graph walking. Inject an
@@ -189,6 +193,8 @@ export function collectTranspileGraph(entryFile, boardPackage) {
             // .ui.html modules: load into the UI registry, record the path, and don't
             // push onto `pending` (they are never parsed as TypeScript).
             if (resolved?.uiModule) {
+                const uiHtmlText = readText(resolved.sourcePath);
+                await requireUIHook().warmUpImageDecoding(uiHtmlText, path.dirname(resolved.sourcePath), imageDecodeOpts ?? {});
                 requireUIHook().loadUIModule(resolved.sourcePath);
                 uiModules.add(resolved.sourcePath);
                 // Track the dependency edge so topological sort orders the importer

package/dist/platform/async-runtime.d.ts

@@ -5,4 +5,4 @@ import type { RuntimePolyfillIR } from "../api/shared/index.js";
  * Build a RuntimePolyfillIR for the async Promise runtime, if the program
  * has async functions and the target architecture has stdlib support.
  */
-export declare function buildAsyncRuntimePolyfill(program: ProgramIR, ctx: PlatformContext | undefined, target: string, queueCapacity?: number): RuntimePolyfillIR | null;
+export declare function buildAsyncRuntimePolyfill(program: ProgramIR, ctx: PlatformContext | undefined, target: string, queueCapacity?: number, strategy?: import("../api/shared/platform-strategy.js").PlatformStrategy): RuntimePolyfillIR | null;

package/dist/platform/async-runtime.js

@@ -3,7 +3,7 @@ import { getStdLibSupport, generatePromiseRuntime } from "../api/shared/index.js
  * Build a RuntimePolyfillIR for the async Promise runtime, if the program
  * has async functions and the target architecture has stdlib support.
  */
-export function buildAsyncRuntimePolyfill(program, ctx, target, queueCapacity) {
+export function buildAsyncRuntimePolyfill(program, ctx, target, queueCapacity, strategy) {
     const hasAsync = program.functions.some(fn => fn.isAsync);
     if (!hasAsync)
         return null;
@@ -11,13 +11,22 @@ export function buildAsyncRuntimePolyfill(program, ctx, target, queueCapacity) {
     const stdlib = getStdLibSupport(architecture);
     if (!stdlib.hasVector || !stdlib.hasString)
         return null;
+    // Pass the strategy through so the runtime's now-expression matches the
+    // target (generic bakes a std::chrono expression via currentTimeMillis()
+    // instead of a millis() token the generic target never defines). When the
+    // expression uses std::chrono, the polyfill must carry <chrono> itself —
+    // the generic strategy's forcedIncludes are empty by design.
+    const now = strategy?.currentTimeMillis?.() ?? "millis()";
+    const requiredIncludes = ["<functional>", "<vector>", "<utility>", "<string>"];
+    if (now.includes("std::chrono"))
+        requiredIncludes.push("<chrono>");
     return {
         kind: "polyfill",
         id: "async_runtime",
         domain: "standard",
-        requiredIncludes: ["<functional>", "<vector>", "<utility>", "<string>"],
+        requiredIncludes,
         forwardDeclarations: [],
-        helperStructs: [generatePromiseRuntime(queueCapacity ?? 256)],
+        helperStructs: [generatePromiseRuntime(queueCapacity ?? 256, false, strategy)],
         helperFunctions: [],
         shimMacros: [],
         dependencies: [],

package/dist/platform/generic-strategy.js

@@ -184,7 +184,7 @@ export class GenericStrategy {
     }
     generateNativePolyfills(program, ctx) {
         const helpers = [];
-        const asyncRuntime = buildAsyncRuntimePolyfill(program, ctx, "generic", this.asyncQueueCapacity());
+        const asyncRuntime = buildAsyncRuntimePolyfill(program, ctx, "generic", this.asyncQueueCapacity(), this);
         if (asyncRuntime)
             helpers.push(asyncRuntime);
         return helpers;

package/dist/preview/api-shared-shim.d.ts

@@ -0,0 +1 @@
+export { resolveScrollConfig } from "../api/shared/display-profile.js";

package/dist/preview/api-shared-shim.js

@@ -0,0 +1,7 @@
+// Browser shim served to the preview page. The host runtime imports
+// resolveScrollConfig from "@typecad/ui/..."→"@typecad/cuttlefish/api/shared",
+// whose barrel index re-exports node-only modules (fs, zod) that cannot load
+// in a browser. The preview's import map points the bare specifier at this
+// file, which re-exports just the browser-safe piece the runtime needs, from
+// the module that actually defines it.
+export { resolveScrollConfig } from "../api/shared/display-profile.js";

package/dist/preview/client.js

@@ -5,6 +5,169 @@ let runtime;
 let imageData;
 let pendingPointerMove;
 let pendingPointerFrame = 0;
+let debugModes = { boxes: false, clips: false, dirty: false, inspect: false };
+let debugOverlay;
+let debugCtx;
+let dirtyFlashAlpha = 0;
+/** CSS px per logical display px — the overlay backing store runs at this
+ *  resolution so debug strokes are 1 CSS px thin (a 1-logical-px stroke on
+ *  the app canvas's own backing store would upscale 3x thick and bury the
+ *  content under investigation). */
+let debugScale = 1;
+// Stroke color per node kind: a screenshot should be self-describing.
+// views cyan · text yellow · interactive magenta · img/canvas orange ·
+// list green · screen transparent (skip; it's the whole panel).
+function debugColor(tag, kind) {
+    if (tag === "screen")
+        return undefined;
+    if (tag === "img" || tag === "canvas")
+        return "#ff9a3c";
+    if (tag === "list")
+        return "#3ddc84";
+    if (["button", "input", "select", "check", "radio", "range", "progress", "drawer"].includes(tag))
+        return "#ff4fd8";
+    if (kind === "text")
+        return "#ffe14d";
+    return "#3cc8ff";
+}
+function applyDebugCapture() {
+    runtime?.setDebugCapture?.(debugModes.boxes || debugModes.clips || debugModes.dirty);
+    const state = document.getElementById("debugState");
+    if (state) {
+        const on = ["boxes", "clips", "dirty", "inspect"].filter((m) => debugModes[m]);
+        state.textContent = on.length === 0
+            ? "overlay: off — check a box or press D"
+            : `overlay: ${on.join("+")}`;
+    }
+}
+function drawDebugOverlay(width, height) {
+    if (!debugOverlay || !debugCtx)
+        return;
+    const ctx = debugCtx;
+    ctx.setTransform(1, 0, 0, 1, 0, 0);
+    ctx.clearRect(0, 0, debugOverlay.width, debugOverlay.height);
+    ctx.setTransform(debugScale, 0, 0, debugScale, 0, 0);
+    const anyVisual = debugModes.boxes || debugModes.clips || debugModes.dirty;
+    if (!anyVisual || !runtime?.debugInfo)
+        return;
+    const info = runtime.debugInfo();
+    if (debugModes.dirty) {
+        // Flash the regions repainted this frame; fades until the next repaint.
+        dirtyFlashAlpha = Math.min(0.55, dirtyFlashAlpha + 0.35);
+        ctx.fillStyle = `rgba(255, 225, 77, ${dirtyFlashAlpha.toFixed(2)})`;
+        for (const r of info.painted)
+            ctx.fillRect(r.x, r.y, r.w, r.h);
+    }
+    else {
+        dirtyFlashAlpha = 0;
+    }
+    // 1 CSS px regardless of the app canvas's logical upscaling — thicker
+    // strokes bury the content being inspected.
+    ctx.lineWidth = Math.max(1 / debugScale, 0.5);
+    if (debugModes.clips) {
+        // Viewport tint guarantees visibility at any stroke sampling; the dashed
+        // outline marks the exact clip edges.
+        for (const c of info.clips) {
+            ctx.fillStyle = "rgba(61, 220, 132, 0.08)";
+            ctx.fillRect(c.x, c.y, c.w, c.h);
+        }
+        ctx.strokeStyle = "#3ddc84";
+        ctx.setLineDash([3, 2]);
+        for (const c of info.clips)
+            ctx.strokeRect(c.x, c.y, c.w - 1, c.h - 1);
+        ctx.setLineDash([]);
+    }
+    if (debugModes.boxes) {
+        for (const n of info.nodes) {
+            const color = debugColor(n.tag, n.kind);
+            if (!color)
+                continue;
+            ctx.strokeStyle = color;
+            ctx.strokeRect(n.x + 0.5, n.y + 0.5, n.w - 1, n.h - 1);
+            // Untappable interactive elements get a red corner mark — the
+            // id-less-element trap (the preview wires by id).
+            if (!n.tappable && ["button", "input", "select", "check", "radio", "list"].includes(n.tag)) {
+                ctx.strokeStyle = "#ff5252";
+                ctx.beginPath();
+                ctx.moveTo(n.x, n.y);
+                ctx.lineTo(n.x + 6, n.y);
+                ctx.moveTo(n.x, n.y);
+                ctx.lineTo(n.x, n.y + 6);
+                ctx.stroke();
+            }
+        }
+    }
+}
+function inspectAt(px, py, width, height, report) {
+    if (!runtime?.debugHit)
+        return false;
+    const i = runtime.debugHit(px, py);
+    if (i < 0) {
+        report(`inspect (${px},${py}): empty space`);
+        return true;
+    }
+    const info = runtime.debugInfo();
+    const n = info.nodes.find((x) => x.i === i);
+    if (!n)
+        return false;
+    report(`inspect #${i}${n.id ? ` '${n.id}'` : ""} <${n.tag}> kind=${n.kind} box=${n.x},${n.y} ${n.w}x${n.h} tappable=${n.tappable}`);
+    return true;
+}
+function wireDebugControls(canvas, width, height, report, redraw) {
+    const modesBox = document.getElementById("debugModes");
+    if (modesBox) {
+        // ?debug=boxes,clips,dirty,inspect seeds the initial state.
+        const params = new URLSearchParams(location.search);
+        const seeded = (params.get("debug") ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+        for (const input of Array.from(modesBox.querySelectorAll("input[data-mode]"))) {
+            const mode = input.dataset.mode;
+            if (seeded.includes(mode))
+                debugModes[mode] = true;
+            input.checked = debugModes[mode];
+            input.addEventListener("change", () => {
+                debugModes[mode] = input.checked;
+                applyDebugCapture();
+                redraw();
+            });
+        }
+    }
+    // D cycles boxes → clips → dirty → off (inspect stays manual — it blocks
+    // normal input and shouldn't be cycled into by accident).
+    window.addEventListener("keydown", (e) => {
+        if (e.key !== "d" && e.key !== "D")
+            return;
+        const on = debugModes.boxes || debugModes.clips || debugModes.dirty;
+        if (!on)
+            debugModes = { ...debugModes, boxes: true };
+        else if (debugModes.boxes)
+            debugModes = { ...debugModes, boxes: false, clips: true };
+        else if (debugModes.clips)
+            debugModes = { ...debugModes, clips: false, dirty: true };
+        else
+            debugModes = { ...debugModes, dirty: false };
+        for (const input of Array.from((modesBox ?? document).querySelectorAll("input[data-mode]"))) {
+            const mode = input.dataset.mode;
+            input.checked = debugModes[mode];
+        }
+        applyDebugCapture();
+        redraw();
+    });
+    // Inspect taps: while inspect mode is on, taps report instead of
+    // interacting. Ctrl-click always inspects without entering the mode.
+    const inspectPointer = (event, force) => {
+        if (!force && !debugModes.inspect)
+            return false;
+        const p = canvasPoint(canvas, event, width, height);
+        inspectAt(p.x, p.y, width, height, report);
+        return true;
+    };
+    canvas.addEventListener("pointerdown", (event) => {
+        if (inspectPointer(event, event.ctrlKey || event.metaKey)) {
+            event.stopImmediatePropagation();
+            event.preventDefault();
+        }
+    }, true);
+}
 function byId(id) {
     const el = document.getElementById(id);
     if (!el)
@@ -74,6 +237,34 @@ async function start() {
     if (!ctx)
         throw new Error("2D canvas context unavailable");
     ctx.imageSmoothingEnabled = false;
+    // Debug overlay: same backing resolution + CSS as the app canvas, stacked
+    // exactly on top; pointer-events pass through to the app canvas below.
+    debugOverlay?.remove();
+    debugOverlay = document.createElement("canvas");
+    debugOverlay.id = "debugOverlay";
+    debugOverlay.width = snapshot.program.width;
+    debugOverlay.height = snapshot.program.height;
+    canvas.parentElement?.appendChild(debugOverlay);
+    debugCtx = debugOverlay.getContext("2d") ?? undefined;
+    const syncOverlayBox = () => {
+        if (!debugOverlay)
+            return;
+        const rect = canvas.getBoundingClientRect();
+        const parent = canvas.parentElement;
+        const prect = parent.getBoundingClientRect();
+        debugOverlay.style.left = `${rect.left - prect.left}px`;
+        debugOverlay.style.top = `${rect.top - prect.top}px`;
+        debugOverlay.style.width = `${rect.width}px`;
+        debugOverlay.style.height = `${rect.height}px`;
+        // Backing store at CSS-pixel resolution: strokes draw at device-crisp
+        // 1 CSS px regardless of the app canvas's logical upscaling.
+        const dpr = window.devicePixelRatio || 1;
+        debugOverlay.width = Math.max(1, Math.round(rect.width * dpr));
+        debugOverlay.height = Math.max(1, Math.round(rect.height * dpr));
+        debugScale = (rect.width * dpr) / snapshot.program.width;
+    };
+    syncOverlayBox();
+    window.addEventListener("resize", syncOverlayBox);
     // Set the canvas CSS aspect-ratio to match the display (e.g. 128:64 for
     // OLED, 320:240 for TFT) so the browser scales it proportionally.
     document.documentElement.style.setProperty("--display-aspect", `${snapshot.program.width} / ${snapshot.program.height}`);
@@ -92,16 +283,39 @@ async function start() {
                 return;
             imageData.data.set(rgba);
             ctx.putImageData(imageData, 0, 0);
+            drawDebugOverlay(snapshot.program.width, snapshot.program.height);
         },
         onDiagnostics: (message) => {
             extraDiagnostics.push(message);
             renderDiagnostics(snapshot, extraDiagnostics);
         },
     });
+    // Mouse wheel scrolls the scroll owner under the cursor — same hit-scan
+    // as a drag (lists, scroll containers). Without this, wheel-scrolling a
+    // canvas preview does nothing.
+    canvas.onwheel = (event) => {
+        if (!runtime)
+            return;
+        event.preventDefault();
+        const p = canvasPoint(canvas, event, snapshot.program.width, snapshot.program.height);
+        // deltaMode: 0 = pixels, 1 = lines, 2 = pages.
+        const scale = event.deltaMode === 1 ? 16 : event.deltaMode === 2 ? 100 : 1;
+        runtime.wheel(p.x, p.y, event.deltaY * scale);
+    };
     canvas.onpointerdown = (event) => {
         if (!runtime)
             return;
-        canvas.setPointerCapture(event.pointerId);
+        // Capture keeps drags flowing when the pointer leaves the canvas, but
+        // synthetic pointers (CDP/browser automation) have no capturable
+        // pointerId — setPointerCapture throws InvalidPointerId for them and
+        // would kill the tap before runtime.pointerDown runs. Losing capture
+        // only degrades off-canvas drags, so swallow the failure.
+        try {
+            canvas.setPointerCapture(event.pointerId);
+        }
+        catch {
+            /* not a capturable pointer — canvas-local move/up still arrive */
+        }
         const p = canvasPoint(canvas, event, snapshot.program.width, snapshot.program.height);
         runtime.pointerDown(p.x, p.y);
     };
@@ -123,6 +337,11 @@ async function start() {
     canvas.onpointercancel = pointerUp;
     renderPinControls(snapshot.pinControls);
     renderDiagnostics(snapshot);
+    wireDebugControls(canvas, snapshot.program.width, snapshot.program.height, (message) => {
+        extraDiagnostics.push(message);
+        renderDiagnostics(snapshot, extraDiagnostics);
+    }, () => drawDebugOverlay(snapshot.program.width, snapshot.program.height));
+    applyDebugCapture();
     runtime.start();
 }
 void start().catch((error) => {

package/dist/preview/server.js

@@ -1,55 +1,83 @@
 import fs from "node:fs";
 import http from "node:http";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createRequire } from "node:module";
 import chalk from "chalk";
 import { findConfigFile, parseConfigFile } from "../config-loader.js";
-import { requireUIHook } from "../ui-hook.js";
-const HTML = `<!doctype html>
-<html lang="en">
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>Cuttlefish Preview</title>
-  <style>
-    :root { color-scheme: dark; font-family: ui-sans-serif, system-ui, sans-serif; background: #111315; color: #e8ecef; }
-    body { margin: 0; height: 100vh; overflow: hidden; display: grid; grid-template-columns: minmax(360px, 1fr) 280px; }
-    main { display: grid; place-items: center; padding: 24px; background: #191d20; }
-    canvas { image-rendering: pixelated; width: min(92vw, 960px); max-height: calc(100vh - 48px); aspect-ratio: var(--display-aspect, 4 / 3); background: #000; box-shadow: 0 12px 36px rgba(0,0,0,.35); }
-    aside { border-left: 1px solid #2d3338; padding: 18px; display: flex; flex-direction: column; gap: 18px; min-height: 0; }
-    aside > section:first-child, aside > section:nth-child(2) { flex-shrink: 0; }  /* Display + GPIO stay visible */
-    aside > section:last-child { min-height: 0; display: flex; flex-direction: column; }
-    #diagnostics { overflow-y: auto; min-height: 0; }
-    h1 { font-size: 15px; margin: 0 0 8px; font-weight: 650; }
-    #status, #diagnostics, .empty { color: #aab3ba; font-size: 12px; line-height: 1.4; }
-    #pins { display: grid; gap: 8px; }
-    button { appearance: none; border: 1px solid #44505a; background: #252b30; color: #f3f6f8; border-radius: 6px; padding: 9px 10px; text-align: left; font: inherit; cursor: pointer; }
-    button:hover { background: #303841; }
-    @media (max-width: 760px) {
-      body { height: auto; min-height: 100vh; overflow: auto; grid-template-rows: auto 1fr; grid-template-columns: 1fr; }
-      aside { border-left: 0; border-top: 1px solid #2d3338; }
-      canvas { width: min(94vw, 640px); }
-    }
-  </style>
-</head>
-<body>
-  <main><canvas id="display" width="320" height="240"></canvas></main>
-  <aside>
-    <section>
-      <h1>Display</h1>
-      <div id="status"></div>
-    </section>
-    <section>
-      <h1>GPIO</h1>
-      <div id="pins"></div>
-    </section>
-    <section>
-      <h1>Diagnostics</h1>
-      <div id="diagnostics"></div>
-    </section>
-  </aside>
-  <script type="module" src="/__cuttlefish/preview/client.js"></script>
-</body>
+import { requireUIHook, hasUIHook } from "../ui-hook.js";
+import { loadUIEngine } from "../ui/ui-bridge.js";
+const HTML = `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Cuttlefish Preview</title>
+  <style>
+    :root { color-scheme: dark; font-family: ui-sans-serif, system-ui, sans-serif; background: #111315; color: #e8ecef; }
+    body { margin: 0; height: 100vh; overflow: hidden; display: grid; grid-template-columns: minmax(360px, 1fr) 280px; }
+    main { display: grid; place-items: center; padding: 24px; background: #191d20; }
+    canvas { image-rendering: pixelated; width: min(92vw, 960px); max-height: calc(100vh - 48px); aspect-ratio: var(--display-aspect, 4 / 3); background: #000; box-shadow: 0 12px 36px rgba(0,0,0,.35); }
+    #debugOverlay { position: absolute; pointer-events: none; image-rendering: pixelated; background: transparent; }
+    main { position: relative; }
+    #debugModes { display: grid; gap: 2px; }
+    #debugModes label { display: flex; align-items: center; gap: 8px; color: #aab3ba; font-size: 12px; cursor: pointer; padding: 5px 6px; border-radius: 5px; }
+    #debugModes label:hover { background: #232a30; color: #dfe6eb; }
+    #debugModes input[type="checkbox"] { width: 14px; height: 14px; margin: 0; }
+    #debugState { color: #7d8790; font-size: 11px; margin-top: 6px; }
+    aside { border-left: 1px solid #2d3338; padding: 18px; display: flex; flex-direction: column; gap: 18px; min-height: 0; }
+    aside > section:first-child, aside > section:nth-child(2) { flex-shrink: 0; }  /* Display + GPIO stay visible */
+    aside > section:last-child { min-height: 0; display: flex; flex-direction: column; }
+    #diagnostics { overflow-y: auto; min-height: 0; }
+    h1 { font-size: 15px; margin: 0 0 8px; font-weight: 650; }
+    #status, #diagnostics, .empty { color: #aab3ba; font-size: 12px; line-height: 1.4; }
+    #pins { display: grid; gap: 8px; }
+    button { appearance: none; border: 1px solid #44505a; background: #252b30; color: #f3f6f8; border-radius: 6px; padding: 9px 10px; text-align: left; font: inherit; cursor: pointer; }
+    button:hover { background: #303841; }
+    @media (max-width: 760px) {
+      body { height: auto; min-height: 100vh; overflow: auto; grid-template-rows: auto 1fr; grid-template-columns: 1fr; }
+      aside { border-left: 0; border-top: 1px solid #2d3338; }
+      canvas { width: min(94vw, 640px); }
+    }
+  </style>
+  <script type="importmap">
+    {
+      "imports": {
+        "@typecad/ui/": "/__cuttlefish-ui/",
+        "@typecad/cuttlefish/api/shared": "/__cuttlefish/preview/api-shared-shim.js"
+      }
+    }
+  </script>
+</head>
+<body>
+  <main><canvas id="display" width="320" height="240"></canvas></main>
+  <aside>
+    <section>
+      <h1>Display</h1>
+      <div id="status"></div>
+    </section>
+    <section>
+      <h1>GPIO</h1>
+      <div id="pins"></div>
+    </section>
+    <section>
+      <h1>Debug overlay</h1>
+      <div id="debugModes">
+        <label><input type="checkbox" data-mode="boxes"> boxes (colors by kind)</label>
+        <label><input type="checkbox" data-mode="clips"> scroll clips (dashed)</label>
+        <label><input type="checkbox" data-mode="dirty"> dirty flash (repaints)</label>
+        <label><input type="checkbox" data-mode="inspect"> inspect taps (blocks input)</label>
+      </div>
+      <div id="debugState">overlay: off — check a box or press D</div>
+      <div style="color:#7d8790;font-size:11px;margin-top:4px">D cycles boxes/clips/dirty · Ctrl-click always inspects</div>
+    </section>
+    <section>
+      <h1>Diagnostics</h1>
+      <div id="diagnostics"></div>
+    </section>
+  </aside>
+  <script type="module" src="/__cuttlefish/preview/client.js"></script>
+</body>
 </html>`;
 function contentType(filePath) {
     if (filePath.endsWith(".js"))
@@ -60,6 +88,42 @@ function contentType(filePath) {
         return "application/json; charset=utf-8";
     return "text/plain; charset=utf-8";
 }
+/** Serve a file from a dist root, with ESM-specifier fallbacks: extensionless
+ *  paths try +".js" (package-exports style "./preview/host-ui-runtime" →
+ *  host-ui-runtime.js) and bare directories try +"/index.js". */
+function serveFromRoot(res, root, relRaw) {
+    const rel = decodeURIComponent(relRaw);
+    const candidates = [rel, `${rel}.js`, `${rel}/index.js`];
+    for (const candidate of candidates) {
+        const filePath = path.resolve(root, candidate);
+        if (!filePath.startsWith(root))
+            break; // path traversal — 404 below
+        if (fs.existsSync(filePath) && fs.statSync(filePath).isFile()) {
+            // no-store: these are compiled dist files that change between builds;
+            // heuristic browser caching serves stale modules after a rebuild and
+            // breaks the preview dev loop (and any debugging of it).
+            res.writeHead(200, { "content-type": contentType(filePath), "cache-control": "no-store" });
+            fs.createReadStream(filePath).pipe(res);
+            return;
+        }
+    }
+    writeText(res, 404, "Not found");
+}
+/** Resolve a dependency package's dist directory (served to the browser).
+ *  Resolves through the package's exports map (subpath → dist file) and walks
+ *  up to the enclosing "dist" — packages don't export "./package.json". */
+function packageDistDir(specifier) {
+    const require = createRequire(import.meta.url);
+    const entry = require.resolve(specifier); // e.g. .../dist/engine.js
+    let dir = path.dirname(entry);
+    for (let i = 0; i < 4 && path.basename(dir) !== "dist"; i++) {
+        dir = path.dirname(dir);
+    }
+    if (path.basename(dir) !== "dist") {
+        throw new Error(`Could not locate the dist directory for ${specifier} (resolved ${entry}).`);
+    }
+    return dir;
+}
 function writeText(res, status, text, type = "text/plain; charset=utf-8") {
     res.writeHead(status, { "content-type": type });
     res.end(text);
@@ -127,13 +191,28 @@ async function listen(server, preferredPort) {
     throw new Error(`No available preview port found starting at ${preferredPort}.`);
 }
 export async function runPreviewServer(options = {}) {
+    // The preview pipeline drives the UI engine directly (snapshot builds,
+    // type-decl generation) without going through transpileFile(), which is the
+    // only path that lazily registers the hook — so load it here first. Preview
+    // is a UI feature: when the engine is absent, fail with a clear message
+    // instead of the generic "hook is not registered" error.
+    await loadUIEngine();
+    if (!hasUIHook()) {
+        throw new Error(`cuttlefish preview requires the @typecad/ui package — install it in this project (npm install @typecad/ui).`);
+    }
     const configPath = resolveConfigPath(options.configPath);
     const config = parseConfigFile(configPath);
     if (!config)
         throw new Error(`Could not parse ${configPath}`);
+    // Snapshots re-read the config on every build (see /snapshot.json below);
+    // this holds the most recent config that parsed, for fallback mid-edit.
+    let lastGoodConfig = config;
     const projectRoot = path.dirname(configPath);
     requireUIHook().generateProjectUITypeDeclarations(projectRoot);
     const distRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+    // The browser client imports the host runtime from @typecad/ui via the
+    // import map — resolve where that package's dist lives on this machine.
+    const uiDistRoot = packageDistDir("@typecad/ui/engine");
     const clients = new Set();
     const server = http.createServer(async (req, res) => {
         const url = new URL(req.url ?? "/", "http://127.0.0.1");
@@ -144,13 +223,26 @@ export async function runPreviewServer(options = {}) {
             }
             if (url.pathname === "/snapshot.json") {
                 requireUIHook().generateProjectUITypeDeclarations(projectRoot);
-                // Routed through a variable (not a string literal) so tsc types this
-                // as `any` and never resolves @typecad/ui's declaration files — see
-                // the comment in ui/ui-bridge.ts for why a literal specifier here
-                // causes TS5055 on rebuilds where dist/ already exists.
-                const buildProgramPath = "@typecad/ui/preview/build-program";
-                const { buildPreviewSnapshot } = await import(buildProgramPath);
-                const snapshot = await buildPreviewSnapshot({ config, projectRoot });
+                // Re-read the config for every snapshot build so edits (themeClass,
+                // entry, display) take effect on page refresh without restarting the
+                // preview server. A config that momentarily fails to parse (mid-edit)
+                // falls back to the last good one — the page keeps working; refresh
+                // again once the edit settles.
+                const latest = parseConfigFile(configPath) ?? lastGoodConfig;
+                lastGoodConfig = latest;
+                // Imported via a computed file:// URL (never a string-literal bare
+                // specifier) so tsc types this as `any` and never resolves
+                // @typecad/ui's declaration files — see the comment in ui/ui-bridge.ts
+                // for why a literal specifier causes TS5055 on rebuilds where dist/
+                // already exists. The ?t= cache-bust forces a fresh ESM load per
+                // snapshot build: without it the server caches the module graph from
+                // startup, and engine rebuilds (font planning, layout fixes, ...)
+                // never take effect until the server restarts — a recurring source of
+                // "fixed but the preview still shows it" confusion. Dev-only cost:
+                // re-evaluating the module graph per snapshot request.
+                const buildProgramUrl = pathToFileURL(path.join(uiDistRoot, "preview", "build-program.js")).href;
+                const { buildPreviewSnapshot } = await import(buildProgramUrl + "?t=" + Date.now());
+                const snapshot = await buildPreviewSnapshot({ config: latest, projectRoot });
                 writeText(res, 200, JSON.stringify(snapshot), "application/json; charset=utf-8");
                 return;
             }
@@ -165,15 +257,15 @@ export async function runPreviewServer(options = {}) {
                 req.on("close", () => clients.delete(res));
                 return;
             }
+            if (url.pathname.startsWith("/__cuttlefish-ui/")) {
+                // The @typecad/ui package's dist — the browser client resolves
+                // "@typecad/ui/..." bare specifiers onto this prefix via the import
+                // map (host runtime, gfx, and their relative engine imports).
+                serveFromRoot(res, uiDistRoot, url.pathname.slice("/__cuttlefish-ui/".length));
+                return;
+            }
             if (url.pathname.startsWith("/__cuttlefish/")) {
-                const rel = decodeURIComponent(url.pathname.slice("/__cuttlefish/".length));
-                const filePath = path.resolve(distRoot, rel);
-                if (!filePath.startsWith(distRoot) || !fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
-                    writeText(res, 404, "Not found");
-                    return;
-                }
-                res.writeHead(200, { "content-type": contentType(filePath) });
-                fs.createReadStream(filePath).pipe(res);
+                serveFromRoot(res, distRoot, url.pathname.slice("/__cuttlefish/".length));
                 return;
             }
             writeText(res, 404, "Not found");

package/dist/theme-tokens.d.ts

@@ -0,0 +1,22 @@
+/** One declaration (`--token: value`), order-preserving. */
+type Decl = [name: string, value: string];
+export interface ShadcnTheme {
+    name: string;
+    light: Decl[];
+    dark: Decl[];
+}
+/** Where a project keeps its own themes: src/styles/themes/*.css next to
+ *  the kit stylesheet. Project themes win over same-named package ones —
+ *  pasting a theme is dropping a file into YOUR project, never node_modules. */
+export declare function projectThemesDir(projectRoot: string): string;
+/** Theme names, project-local (src/styles/themes/) first, then the ones
+ *  shipped in the package (assets/shadcn/themes/). */
+export declare function listShadcnThemes(projectRoot?: string): string[];
+/** Load a theme by name — project-local directory first, then the package
+ *  included set. Throws with the available names when missing. */
+export declare function loadShadcnTheme(name: string, projectRoot?: string): ShadcnTheme;
+/** Merge a theme's tokens into a kit stylesheet's :root/.dark blocks and
+ *  return the rewritten text. Throws when a merged block is missing any
+ *  token the kit's recipes reference. */
+export declare function applyShadcnTheme(cssText: string, theme: ShadcnTheme): string;
+export {};