@typecad/cuttlefish 1.0.0-alpha.12 → 1.0.0-alpha.14

package/dist/library-packages.js

@@ -0,0 +1,275 @@
+// ---------------------------------------------------------------------------
+// Cuttlefish library packages
+//
+// A library package is an npm package whose root carries a
+// `cuttlefish.library.json` manifest. It contributes native artifacts to the
+// generated firmware application:
+//
+//   - an include mapping (the import emits `#include` of the shim header)
+//   - shim files (native C++ written into the emitted source directory)
+//   - framework build contributions (Kconfig lines, a devicetree overlay
+//     fragment) consumed by the framework toolchain via the sidecar
+//
+// Discovery is import-driven: when the transpile graph builder resolves an
+// import whose package ships the manifest, the package is registered at that
+// moment and its TypeScript is NOT transpiled — the package's own types are
+// the compile-time contract, and the native shim is the implementation.
+// Nothing scans node_modules; an installed-but-never-imported library
+// contributes nothing.
+//
+// The transpiler writes a `libraries.json` sidecar next to the emitted
+// sources (the board-constants.json convention) recording the libraries that
+// were actually used, so build-time consumers (framework toolchains) can
+// re-derive their contributions idempotently from disk.
+// ---------------------------------------------------------------------------
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { toModuleKey } from "./utils/strings.js";
+/** Sidecar file name — written next to the emitted sources. */
+export const LIBRARY_SIDECAR_NAME = "libraries.json";
+const registered = new Map();
+/** Specifiers known NOT to be library packages (avoids repeated resolve attempts). */
+const knownNonLibraries = new Set();
+/** Clear all registrations. Called once per transpilation, before graph build. */
+export function resetCuttlefishLibraries() {
+    registered.clear();
+    knownNonLibraries.clear();
+}
+/** All libraries registered during this transpilation (import-driven). */
+export function getRegisteredCuttlefishLibraries() {
+    return [...registered.values()];
+}
+/**
+ * Whether the specifier resolves to a library registered in this
+ * transpilation. Library packages are exempt from the @typecad/* "SDK
+ * imports are type-level only" include skip — their import IS the include
+ * of the shim header.
+ */
+export function isRegisteredCuttlefishLibrary(moduleSpecifier) {
+    return registered.has(moduleSpecifier.toLowerCase());
+}
+function parseManifest(packageRoot) {
+    const manifestPath = path.join(packageRoot, "cuttlefish.library.json");
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const m = raw;
+    if (typeof m.id !== "string" ||
+        typeof m.module !== "string" ||
+        typeof m.framework !== "string" ||
+        typeof m.include !== "string" ||
+        typeof m.gateToken !== "string" ||
+        !Array.isArray(m.shims) ||
+        m.shims.length === 0) {
+        return undefined;
+    }
+    for (const shim of m.shims) {
+        if (typeof shim?.path !== "string" || typeof shim?.outName !== "string") {
+            return undefined;
+        }
+    }
+    return {
+        id: m.id,
+        module: m.module,
+        framework: m.framework,
+        targets: m.targets,
+        include: m.include,
+        gateToken: m.gateToken,
+        shims: m.shims,
+        kconfig: Array.isArray(m.kconfig) ? m.kconfig.filter((k) => typeof k === "string") : [],
+        overlay: typeof m.overlay === "string" ? m.overlay : undefined,
+    };
+}
+/**
+ * Resolve the package root for a bare npm specifier from the importing file,
+ * then register the package as a cuttlefish library if it ships a
+ * `cuttlefish.library.json`. Returns true when the specifier resolved to a
+ * registered library (the import must then be skipped by the graph builder).
+ */
+export function registerCuttlefishLibraryFromSpecifier(fromFile, moduleSpecifier) {
+    // Only bare npm specifiers ('pkg' or '@scope/pkg'[/subpath]) — relative
+    // imports and node builtins cannot be library packages.
+    if (moduleSpecifier.startsWith(".") || moduleSpecifier.startsWith("node:")) {
+        return false;
+    }
+    const cacheKey = moduleSpecifier.toLowerCase();
+    if (knownNonLibraries.has(cacheKey))
+        return false;
+    if (registered.has(cacheKey))
+        return true;
+    let packageRoot;
+    try {
+        const req = createRequire(path.resolve(fromFile));
+        // Resolve the package entry, then walk up to the nearest package.json —
+        // the package root. (Resolving the manifest subpath directly would be
+        // blocked by exports encapsulation; the entry point always resolves.)
+        const entry = req.resolve(moduleSpecifier);
+        let dir = path.dirname(entry);
+        while (dir !== path.dirname(dir)) {
+            if (fs.existsSync(path.join(dir, "package.json")))
+                break;
+            dir = path.dirname(dir);
+        }
+        if (dir !== path.dirname(dir))
+            packageRoot = dir;
+    }
+    catch {
+        packageRoot = undefined;
+    }
+    if (packageRoot === undefined) {
+        knownNonLibraries.add(cacheKey);
+        return false;
+    }
+    const manifest = parseManifest(packageRoot);
+    if (manifest === undefined) {
+        knownNonLibraries.add(cacheKey);
+        return false;
+    }
+    registered.set(cacheKey, { manifest, packageRoot });
+    return true;
+}
+/** Libdef entries for the registry: import → shim include. */
+export function cuttlefishLibraryLibdefs() {
+    return getRegisteredCuttlefishLibraries().map(({ manifest }) => ({
+        module: manifest.module,
+        include: manifest.include,
+    }));
+}
+/**
+ * Validate registered libraries against the loaded framework (and, when
+ * known, the build target). Throws with an actionable message when a library
+ * cannot work in this project — far earlier and clearer than the native
+ * compiler would.
+ */
+export function validateCuttlefishLibraries(frameworkId, buildTarget) {
+    for (const { manifest } of getRegisteredCuttlefishLibraries()) {
+        if (manifest.framework !== frameworkId) {
+            throw new Error(`Library ${manifest.module} requires the '${manifest.framework}' framework, ` +
+                `but this project uses '${frameworkId}'. ` +
+                `Install the matching framework or a '${frameworkId}' counterpart of this library.`);
+        }
+        if (buildTarget !== undefined &&
+            manifest.targets !== undefined &&
+            manifest.targets.length > 0 &&
+            !manifest.targets.some((t) => buildTarget.toLowerCase().startsWith(t.toLowerCase()))) {
+            throw new Error(`Library ${manifest.module} supports board targets ` +
+                `[${manifest.targets.join(", ")}], but this project builds for '${buildTarget}'.`);
+        }
+    }
+}
+function writeIfChanged(filePath, content) {
+    try {
+        if (fs.existsSync(filePath) && fs.readFileSync(filePath, "utf8") === content)
+            return;
+    }
+    catch {
+        /* fall through and write */
+    }
+    fs.writeFileSync(filePath, content);
+}
+function readEmittedTokens(srcDir) {
+    let out = "";
+    let names = [];
+    try {
+        names = fs.readdirSync(srcDir);
+    }
+    catch {
+        return "";
+    }
+    for (const name of names) {
+        if (!/\.(cpp|cc|c|h|hpp|ino)$/.test(name))
+            continue;
+        try {
+            out += fs.readFileSync(path.join(srcDir, name), "utf8");
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    return out;
+}
+function readSidecar(sidecarPath) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(sidecarPath, "utf8"));
+        if (!Array.isArray(raw))
+            return [];
+        return raw.filter((e) => typeof e === "object" && e !== null && typeof e.module === "string");
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Emit the library artifacts for the libraries actually used in this
+ * transpilation, and write the `libraries.json` sidecar:
+ *
+ *   1. scan the emitted sources for each library's gate token;
+ *   2. write (write-if-changed) the shims of every gated library into the
+ *      emitted source directory — the framework scaffold's CMake/sketch
+ *      regen picks the sources up automatically;
+ *   3. delete shim files recorded in the previous sidecar that are no longer
+ *      used, so removing an import removes its native code;
+ *   4. persist the sidecar (even when empty — that clears stale state).
+ */
+export function writeCuttlefishLibraryArtifacts(outDir, srcDir) {
+    const sidecarPath = path.join(outDir, LIBRARY_SIDECAR_NAME);
+    const previous = readSidecar(sidecarPath);
+    const previousShims = new Set(previous.flatMap((e) => e.shims));
+    const emitted = readEmittedTokens(srcDir);
+    const usedShims = new Set();
+    const entries = [];
+    for (const { manifest, packageRoot } of getRegisteredCuttlefishLibraries()) {
+        if (!emitted.includes(manifest.gateToken))
+            continue;
+        for (const shim of manifest.shims) {
+            let content;
+            try {
+                content = fs.readFileSync(path.join(packageRoot, shim.path), "utf8");
+            }
+            catch {
+                continue; // broken library packaging — the missing header surfaces at compile
+            }
+            writeIfChanged(path.join(srcDir, shim.outName), content);
+            usedShims.add(shim.outName);
+        }
+        entries.push({
+            id: manifest.id,
+            module: manifest.module,
+            framework: manifest.framework,
+            gateToken: manifest.gateToken,
+            kconfig: manifest.kconfig ?? [],
+            overlay: manifest.overlay ? path.join(packageRoot, manifest.overlay) : null,
+            shims: manifest.shims.map((s) => s.outName).filter((n) => usedShims.has(n)),
+        });
+    }
+    // Remove shims from a previous build whose library is no longer used.
+    for (const name of previousShims) {
+        if (usedShims.has(name))
+            continue;
+        try {
+            fs.rmSync(path.join(srcDir, name), { force: true });
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    writeIfChanged(sidecarPath, JSON.stringify(entries, null, 2) + "\n");
+}
+/**
+ * Read the `libraries.json` sidecar for build-time consumers (framework
+ * toolchains). Tolerant of a missing or corrupt file (returns []).
+ */
+export function readCuttlefishLibrarySidecar(outDir) {
+    return readSidecar(path.join(outDir, LIBRARY_SIDECAR_NAME));
+}
+/** Re-exported for transpile.ts libdef injection convenience. */
+export function libraryDefinitionKey(module) {
+    return toModuleKey(module);
+}

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

@@ -3,6 +3,7 @@ import ts from "typescript";
 import { readText } from "../utils/fs.js";
 import { detectNativeCppModule, getNpmPackageInfoForFile, isInNodeModules, resolveImport, isCuttlefishSDKPath, } from "../transpile/resolution.js";
 import { requireUIHook } from "../ui-hook.js";
+import { registerCuttlefishLibraryFromSpecifier } from "../library-packages.js";
 /**
  * Sort files in dependency order using Kahn's algorithm.
  * Dependencies come before dependents so that include ordering is correct
@@ -68,7 +69,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 +103,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
@@ -121,6 +126,14 @@ export function collectTranspileGraph(entryFile, boardPackage) {
                 }
                 if (!moduleSpecifier)
                     continue;
+                // Cuttlefish library package: an import whose package ships a
+                // cuttlefish.library.json contributes native shims + build fragments
+                // instead of transpiling — its own TypeScript types are the contract.
+                // Must precede the @typecad/* skips: scoped libraries would otherwise
+                // be dropped as "SDK packages" here (the .ui script loop skips ALL
+                // @typecad/* specifiers, unlike the selective main-loop skip list).
+                if (registerCuttlefishLibraryFromSpecifier(filePath, moduleSpecifier))
+                    continue;
                 if (moduleSpecifier === "@typecad/expect" || moduleSpecifier === "@typecad/ui" || moduleSpecifier === "@typecad/safety")
                     continue;
                 if (moduleSpecifier.startsWith("@typecad/"))
@@ -154,6 +167,13 @@ export function collectTranspileGraph(entryFile, boardPackage) {
                 nativeModules.set(moduleSpecifier, nativeModule);
                 continue; // Don't try to resolve as TypeScript
             }
+            // Cuttlefish library package: an import whose package ships a
+            // cuttlefish.library.json contributes native shims + build fragments
+            // instead of transpiling — its own TypeScript types are the contract.
+            // Checked before the @typecad/* skips so scoped libraries register.
+            if (registerCuttlefishLibraryFromSpecifier(filePath, moduleSpecifier)) {
+                continue;
+            }
             // Skip @typecad/expect — it provides type-level stubs only.
             // The AST preprocessor rewrites all expect calls before transpilation.
             if (moduleSpecifier === "@typecad/expect") {
@@ -189,6 +209,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/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,172 @@ let runtime;
 let imageData;
 let pendingPointerMove;
 let pendingPointerFrame = 0;
+let debugModes = { boxes: false, clips: false, dirty: false, inspect: false };
+let debugOverlay;
+let debugCtx;
+/** Re-syncs the overlay to the app canvas whenever layout changes its box
+ *  (aspect-ratio application, max-height, container reflow). */
+let overlayResizeObserver;
+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,9 +240,48 @@ 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;
+    };
     // 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.
+    // OLED, 320:240 for TFT) BEFORE syncing the overlay: the canvas is
+    // vertically centered (place-items: center), so applying the real aspect
+    // after the sync SHRANK it and moved it DOWN — the overlay stayed at the
+    // old 4/3-fallback position and every debug box sat that far above its
+    // element. A ResizeObserver re-syncs on any later layout-driven size
+    // change (max-height kicking in, container reflow), not just window
+    // resizes.
     document.documentElement.style.setProperty("--display-aspect", `${snapshot.program.width} / ${snapshot.program.height}`);
+    syncOverlayBox();
+    window.addEventListener("resize", syncOverlayBox);
+    if (typeof ResizeObserver !== "undefined") {
+        overlayResizeObserver?.disconnect();
+        overlayResizeObserver = new ResizeObserver(() => syncOverlayBox());
+        overlayResizeObserver.observe(canvas);
+    }
     const status = byId("status");
     status.textContent = `${snapshot.profileName ?? snapshot.program.display?.driver ?? "display"} ${snapshot.program.width}x${snapshot.program.height} ${snapshot.program.colorFormat}`;
     const extraDiagnostics = [];
@@ -92,16 +297,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 +351,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) => {