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

package/README.md

@@ -13,6 +13,26 @@ npm install --save-dev @typecad/cuttlefish
 
 `@typecad/ui` is compile-time only — none of its code is shipped to the device. The transpiler intercepts `ui.mount` / `ui.signal` / `ui.bind` / ... calls and lowers them to device variables and binding-table entries, so the package can be safely kept in `dependencies`.
 
+### Integration wizard
+
+Integrating a display is the one step with real hardware decisions — which panel, which bus, which pins, whether there's touch and how it connects. Run the wizard from your project directory:
+
+```bash
+npx @typecad/ui --config
+```
+
+It asks:
+
+1. **Display** — a built-in profile (ILI9341 320×240 SPI TFT, ST7796S 320×480 SPI TFT, SSD1309 128×64 I2C OLED), the desktop SDL simulator, or a fully custom driver.
+2. **Bus wiring** — SPI pins (CS/DC/RST/backlight, frequency in MHz, optional SCK/MOSI/MISO override) or the I2C address. Defaults match the framework profiles and the repo's demo wiring (ESP32 VSPI), and any existing `display` section in your config pre-fills the answers.
+3. **Orientation & rendering** — rotation and antialiasing, with advanced color-order/inversion options behind a confirm.
+4. **Touch** — none, resistive (XPT2046, STMPE610, 4-wire analog), capacitive (FT6336U, GT911, CST816S), or a custom adapter file — each with its pins, address, and a sensible default calibration.
+5. **Theme** — optional `themeCss` / `themeClass`.
+
+After a summary preview and confirmation, the wizard splices only the `display` section into `cuttlefish.config.ts` — every other section (and its comments) is preserved byte-for-byte, unmanaged display keys like `scroll` are carried over, and the result is syntax-checked before anything is written. If your config's `entry` points at a `.ui` file that doesn't exist yet, it offers to generate a starter screen, and it prints the exact `arduino-cli lib install ...`, preview, compile, and flash commands as next steps.
+
+If there is no `cuttlefish.config.ts` yet, create the project first with `npx @typecad/cuttlefish init`, then re-run the wizard.
+
 ## Project layout
 
 A TypeCAD UI project has one **entry** — the file you point `cuttlefish.config.ts` at. The entry can be either a `.ui` single-file component or a plain `.ts` module. Both intermix freely with regular cuttlefish TypeScript (HAL pin reads, `setInterval`, `console.log`, your own `.ts` modules) — the `<script>` block of a `.ui` file and a standalone `.ts` file are lowered by the same pipeline.
@@ -217,7 +237,7 @@ The fastest path is a single `.ui` file with markup, styling, and behavior toget
 </screen>
 ```
 
-Display hardware and wiring live in `cuttlefish.config.ts` under `display`, so the UI source stays focused on UI behavior.
+Display hardware and wiring live in `cuttlefish.config.ts` under `display`, so the UI source stays focused on UI behavior. Run `npx @typecad/ui --config` to generate that section interactively (see [Integration wizard](#integration-wizard)) — the result looks like the `display` line below.
 
 ### 2. Point the entry at the `.ui` file
 

package/assets/fonts/dejavu/LICENSE

@@ -0,0 +1,187 @@
+Fonts are (c) Bitstream (see below). DejaVu changes are in public domain.
+Glyphs imported from Arev fonts are (c) Tavmjong Bah (see below)
+
+
+Bitstream Vera Fonts Copyright
+------------------------------
+
+Copyright (c) 2003 by Bitstream, Inc. All Rights Reserved. Bitstream Vera is
+a trademark of Bitstream, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of the fonts accompanying this license ("Fonts") and associated
+documentation files (the "Font Software"), to reproduce and distribute the
+Font Software, including without limitation the rights to use, copy, merge,
+publish, distribute, and/or sell copies of the Font Software, and to permit
+persons to whom the Font Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright and trademark notices and this permission notice shall
+be included in all copies of one or more of the Font Software typefaces.
+
+The Font Software may be modified, altered, or added to, and in particular
+the designs of glyphs or characters in the Fonts may be modified and
+additional glyphs or characters may be added to the Fonts, only if the fonts
+are renamed to names not containing either the words "Bitstream" or the word
+"Vera".
+
+This License becomes null and void to the extent applicable to Fonts or Font
+Software that has been modified and is distributed under the "Bitstream
+Vera" names.
+
+The Font Software may be sold as part of a larger software package but no
+copy of one or more of the Font Software typefaces may be sold by itself.
+
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT,
+TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL BITSTREAM OR THE GNOME
+FOUNDATION BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING
+ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
+THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE
+FONT SOFTWARE.
+
+Except as contained in this notice, the names of Gnome, the Gnome
+Foundation, and Bitstream Inc., shall not be used in advertising or
+otherwise to promote the sale, use or other dealings in this Font Software
+without prior written authorization from the Gnome Foundation or Bitstream
+Inc., respectively. For further information, contact: fonts at gnome dot
+org.
+
+Arev Fonts Copyright
+------------------------------
+
+Copyright (c) 2006 by Tavmjong Bah. All Rights Reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the fonts accompanying this license ("Fonts") and
+associated documentation files (the "Font Software"), to reproduce
+and distribute the modifications to the Bitstream Vera Font Software,
+including without limitation the rights to use, copy, merge, publish,
+distribute, and/or sell copies of the Font Software, and to permit
+persons to whom the Font Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright and trademark notices and this permission notice
+shall be included in all copies of one or more of the Font Software
+typefaces.
+
+The Font Software may be modified, altered, or added to, and in
+particular the designs of glyphs or characters in the Fonts may be
+modified and additional glyphs or characters may be added to the
+Fonts, only if the fonts are renamed to names not containing either
+the words "Tavmjong Bah" or the word "Arev".
+
+This License becomes null and void to the extent applicable to Fonts
+or Font Software that has been modified and is distributed under the 
+"Tavmjong Bah Arev" names.
+
+The Font Software may be sold as part of a larger software package but
+no copy of one or more of the Font Software typefaces may be sold by
+itself.
+
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL
+TAVMJONG BAH BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
+
+Except as contained in this notice, the name of Tavmjong Bah shall not
+be used in advertising or otherwise to promote the sale, use or other
+dealings in this Font Software without prior written authorization
+from Tavmjong Bah. For further information, contact: tavmjong @ free
+. fr.
+
+TeX Gyre DJV Math
+-----------------
+Fonts are (c) Bitstream (see below). DejaVu changes are in public domain.
+
+Math extensions done by B. Jackowski, P. Strzelczyk and P. Pianowski
+(on behalf of TeX users groups) are in public domain.
+
+Letters imported from Euler Fraktur from AMSfonts are (c) American
+Mathematical Society (see below).
+Bitstream Vera Fonts Copyright
+Copyright (c) 2003 by Bitstream, Inc. All Rights Reserved. Bitstream Vera
+is a trademark of Bitstream, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of the fonts accompanying this license (“Fonts”) and associated
+documentation
+files (the “Font Software”), to reproduce and distribute the Font Software,
+including without limitation the rights to use, copy, merge, publish,
+distribute,
+and/or sell copies of the Font Software, and to permit persons  to whom
+the Font Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright and trademark notices and this permission notice
+shall be
+included in all copies of one or more of the Font Software typefaces.
+
+The Font Software may be modified, altered, or added to, and in particular
+the designs of glyphs or characters in the Fonts may be modified and
+additional
+glyphs or characters may be added to the Fonts, only if the fonts are
+renamed
+to names not containing either the words “Bitstream” or the word “Vera”.
+
+This License becomes null and void to the extent applicable to Fonts or
+Font Software
+that has been modified and is distributed under the “Bitstream Vera”
+names.
+
+The Font Software may be sold as part of a larger software package but
+no copy
+of one or more of the Font Software typefaces may be sold by itself.
+
+THE FONT SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT,
+TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL BITSTREAM OR THE GNOME
+FOUNDATION
+BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING ANY GENERAL,
+SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, WHETHER IN AN
+ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF THE USE OR
+INABILITY TO USE
+THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE FONT SOFTWARE.
+Except as contained in this notice, the names of GNOME, the GNOME
+Foundation,
+and Bitstream Inc., shall not be used in advertising or otherwise to promote
+the sale, use or other dealings in this Font Software without prior written
+authorization from the GNOME Foundation or Bitstream Inc., respectively.
+For further information, contact: fonts at gnome dot org.
+
+AMSFonts (v. 2.2) copyright
+
+The PostScript Type 1 implementation of the AMSFonts produced by and
+previously distributed by Blue Sky Research and Y&Y, Inc. are now freely
+available for general use. This has been accomplished through the
+cooperation
+of a consortium of scientific publishers with Blue Sky Research and Y&Y.
+Members of this consortium include:
+
+Elsevier Science IBM Corporation Society for Industrial and Applied
+Mathematics (SIAM) Springer-Verlag American Mathematical Society (AMS)
+
+In order to assure the authenticity of these fonts, copyright will be
+held by
+the American Mathematical Society. This is not meant to restrict in any way
+the legitimate use of the fonts, such as (but not limited to) electronic
+distribution of documents containing these fonts, inclusion of these fonts
+into other public domain or commercial font collections or computer
+applications, use of the outline data to create derivative fonts and/or
+faces, etc. However, the AMS does require that the AMS copyright notice be
+removed from any derivative versions of the fonts which have been altered in
+any way. In addition, to ensure the fidelity of TeX documents using Computer
+Modern fonts, Professor Donald Knuth, creator of the Computer Modern faces,
+has requested that any alterations which yield different font metrics be
+given a different name.
+
+$Id$

package/assets/fonts/dejavu/README.md

@@ -0,0 +1,49 @@
+# Bundled DejaVu fonts
+
+These are the unmodified TrueType files from the [DejaVu fonts] project,
+release **2.37** (the final upstream release). They are bundled here so every
+cuttlefish UI project gets an antialiased, continuously-sized font out of the
+box (see `@font-face` injection in `packages/ui/src/ui-engine/default-font.ts`).
+
+Do **not** rename or modify these files: the license terms (Bitstream Vera
+License, see [LICENSE](./LICENSE)) permit free redistribution of unmodified
+copies under the original name, but modified variants must be renamed to
+something without the word "DejaVu". Build-time subsetting/rasterization into
+glyph bitmaps is fine — only the installable font files must stay pristine.
+
+## Files
+
+| File                    | Face        | Used for                                  |
+| ----------------------- | ----------- | ----------------------------------------- |
+| `DejaVuSans.ttf`        | Regular     | Default injected face (weight 400)        |
+| `DejaVuSans-Bold.ttf`   | Bold        | Default injected face (weight 700)        |
+| `DejaVuSansMono.ttf`    | Mono Regular | Default injected mono face (`pre`/`code`/`kbd`) |
+| `DejaVuSansMono-Bold.ttf` | Mono Bold | Default injected mono face (weight 700) |
+| `DejaVuSans-Oblique.ttf`| Oblique     | Opt-in via `@font-face` (italic)          |
+| `DejaVuSans-ExtraLight.ttf` | ExtraLight | Opt-in via `@font-face` (weight 300)  |
+
+Only `DejaVuSans(.ttf/-Bold.ttf)` and `DejaVuSansMono(.ttf/-Bold.ttf)` are
+injected by default (the "DejaVu Sans" and "DejaVu Sans Mono" families); the
+oblique and extra-light faces ship for projects that declare them explicitly.
+Devices never receive these files — the build rasterizes the exact (family,
+px, weight, style, characters) subsets a UI uses into glyph tables.
+
+## Checksums (SHA-256, release 2.37)
+
+```
+e6476c1b80502924294eed40894c5b18e06c181444ca953e5334262df9c27724  DejaVuSans-Bold.ttf
+6cb0746a1f68d176bebe83752cee35ebdf726cb1a1e88a01fc038ddf76de9ea8  DejaVuSans-ExtraLight.ttf
+4af75fa16ee6d3ad43e1ecec41862c24954af26a55c6bb1ebb27bd486a50f5f4  DejaVuSans-Oblique.ttf
+7da195a74c55bef988d0d48f9508bd5d849425c1770dba5d7bfc6ce9ed848954  DejaVuSans.ttf
+b4a6c3e4faab8773f4ff761d56451646409f29abedd68f05d38c2df667d3c582  DejaVuSansMono.ttf
+bce60f1b4421acd9ea51ba6623d7024ecbe6817a953e3654df62a5e6bdf8f769  DejaVuSansMono-Bold.ttf
+```
+
+## License
+
+Bitstream Vera License (DejaVu variant) — permissive, GPL-compatible, free to
+redistribute and embed in commercial firmware. The full text is in
+[LICENSE](./LICENSE) and must accompany any redistribution of these files.
+Generated font tables carry an attribution comment pointing back here.
+
+[DejaVu fonts]: https://dejavu-fonts.github.io/

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// ---------------------------------------------------------------------------
+// @typecad/ui CLI — display integration wizard.
+//
+//   npx @typecad/ui --config    Run the interactive integration wizard
+//   npx @typecad/ui --help      Show usage
+//   npx @typecad/ui --version   Show the installed version
+// ---------------------------------------------------------------------------
+import { runIntegrationWizard } from "./wizard/integration-wizard.js";
+const USAGE = `
+@typecad/ui — HTML/CSS-driven graphics for microcontrollers
+
+Usage:
+  npx @typecad/ui --config        Configure a display (+ touch) for your
+                                  cuttlefish project interactively. Writes the
+                                  \`display\` section of cuttlefish.config.ts.
+
+Options:
+  --config            Run the integration wizard
+  --help, -h          Show this help
+  --version, -v       Print the installed @typecad/ui version
+
+The wizard asks which display module you are using (ILI9341 / ST7796S SPI TFT,
+SSD1309 I2C OLED, desktop simulator, or custom), then walks through bus pins,
+SPI/I2C speed, rotation, and touch controller wiring with hardware-aware
+defaults. It never touches the rest of your cuttlefish.config.ts.
+
+Docs: https://github.com/justind000/typecode/tree/main/packages/ui
+`.trim();
+function printUsage() {
+    console.log(USAGE);
+}
+async function main(argv) {
+    const args = argv.slice(2);
+    if (args.includes("--help") || args.includes("-h")) {
+        printUsage();
+        return 0;
+    }
+    if (args.includes("--version") || args.includes("-v")) {
+        // Lazily read the version so importing this module stays side-effect free.
+        const { readFile } = await import("node:fs/promises");
+        const { fileURLToPath } = await import("node:url");
+        const { dirname, join } = await import("node:path");
+        try {
+            const packageJson = JSON.parse(await readFile(join(dirname(dirname(fileURLToPath(import.meta.url))), "package.json"), "utf-8"));
+            console.log(packageJson.version ?? "unknown");
+            return 0;
+        }
+        catch {
+            console.log("unknown");
+            return 0;
+        }
+    }
+    if (args.length === 0 || (args.length === 1 && (args[0] === "--config" || args[0] === "config"))) {
+        if (!process.stdin.isTTY) {
+            console.error("The integration wizard is interactive and needs a terminal.");
+            console.error("Run `npx @typecad/ui --config` from your project directory, or configure");
+            console.error("the `display` section of cuttlefish.config.ts manually:");
+            console.error("https://github.com/justind000/typecode/tree/main/packages/ui#display-configuration");
+            return 1;
+        }
+        const result = await runIntegrationWizard(process.cwd());
+        return result.exitCode;
+    }
+    console.error(`Unknown option${args.length > 1 ? "s" : ""}: ${args.join(" ")}\n`);
+    printUsage();
+    return 2;
+}
+main(process.argv).then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+});

package/dist/engine-index.js

@@ -14,6 +14,7 @@ import { resolveColor, resolveColorInternal } from "./ui-engine/color.js";
 import { emitRuntimeHeader } from "./ui-engine/runtime-header.js";
 import { emitCuttlefishGfx } from "./ui-engine/runtime-header/cuttlefish-gfx.js";
 import { splitUiFile } from "./ui-engine/ui-file-splitter.js";
+import { warmUpImageDecoding } from "./ui-engine/image-decode.js";
 /**
  * Build and return the TranspilerUIHook — the object cuttlefish core uses
  * to access all UI capabilities (parsing, layout, lowering, emission).
@@ -36,6 +37,7 @@ export function registerTranspilerUI() {
         emitRuntimeHeader,
         emitCuttlefishGfx,
         splitUiFile,
+        warmUpImageDecoding,
         generateProjectUITypeDeclarations,
     };
 }

package/dist/preview/build-program.d.ts

@@ -1,7 +1,13 @@
 import { ResolvedCuttlefishConfig } from "@typecad/cuttlefish/config-loader";
-import type { PreviewSnapshot } from "./types.js";
+import type { PreviewDiagnostic, PreviewSnapshot } from "./types.js";
 export interface BuildPreviewSnapshotOptions {
     config: ResolvedCuttlefishConfig;
     projectRoot: string;
 }
+/** Load the stock 5x7 GFX font for the preview runtime. A project-local
+ *  Adafruit_GFX copy wins (byte-identical to what the firmware compiles
+ *  against); otherwise fall back to the table bundled in
+ *  @typecad/cuttlefish (api/shared glcdfont.ts) so stock-font text renders
+ *  without a vendored library. */
+export declare function loadFont(projectRoot: string, diagnostics: PreviewDiagnostic[]): number[];
 export declare function buildPreviewSnapshot(options: BuildPreviewSnapshotOptions): Promise<PreviewSnapshot>;

package/dist/preview/build-program.js

@@ -1,12 +1,16 @@
 import fs from "node:fs";
 import path from "node:path";
 import ts from "typescript";
-import { effectiveDisplaySize, resolveDisplayProfile } from "@typecad/cuttlefish/api/shared";
+import { effectiveDisplaySize, resolveDisplayProfile, GLCDFONT_BYTES } from "@typecad/cuttlefish/api/shared";
 import { parseCss, parseFontFaces, parseKeyframes } from "../ui-engine/css-parser.js";
+import { expandCssImports } from "../ui-engine/css-imports.js";
+import { injectDefaultFontFaces } from "../ui-engine/default-font.js";
 import { extractStyleBlocks, parseHtmlWithKeyboards } from "../ui-engine/html-parser.js";
 import { splitUiFile } from "../ui-engine/ui-file-splitter.js";
 import { buildUIFontAssets } from "../ui-engine/font-assets.js";
-import { loadImageAssets } from "../ui-engine/image-assets.js";
+import { loadImageAssets, applyDecodedImageSizes } from "../ui-engine/image-assets.js";
+import { warmUpImageDecoding } from "../ui-engine/image-decode.js";
+import { SHADCN_KIT_CSS } from "../ui-engine/shadcn-kit.js";
 import { buildKeyframeSets } from "../ui-engine/keyframes.js";
 import { measureWithFonts } from "../ui-engine/layout-engine.js";
 import { lowerUIToModel } from "../ui-engine/model.js";
@@ -66,6 +70,35 @@ function interpolationToExpression(raw) {
         return undefined;
     return "`" + parts.join("") + "`";
 }
+/** Warn about interactive nodes the preview cannot wire because they lack an
+ *  id: on:* handlers, bind:* bindings, and {expr} interpolations all resolve
+ *  their node by id in the preview (the device build auto-wires them without
+ *  one). Without this the element renders but never reacts. */
+function warnUnnamedInteractiveNodes(trees, diagnostics) {
+    const walk = (node) => {
+        if (!node.id) {
+            const features = [];
+            if (node.events && Object.keys(node.events).length > 0)
+                features.push(`on:${Object.keys(node.events).join("/on:")}`);
+            if (node.bind && Object.keys(node.bind).length > 0)
+                features.push(`bind:${Object.keys(node.bind).join("/bind:")}`);
+            if (node.hasInterpolation)
+                features.push("{expr} interpolation");
+            // Images key their loaded asset by node id too (image-assets.ts skips
+            // id-less <img src> silently) — warn so empty frames are explainable.
+            if (node.tag === "img" && node.src)
+                features.push("img src");
+            if (features.length > 0) {
+                diagnostics.push({
+                    severity: "warning",
+                    message: `<${node.tag}> uses ${features.join(", ")} but has no id — the preview loads/wires these by id, so the element renders empty or inert. Add an id, e.g. <${node.tag} id="${node.tag}1"> (the device build behaves the same).`,
+                });
+            }
+        }
+        node.children?.forEach(walk);
+    };
+    trees.forEach(walk);
+}
 /** Walk styled trees for {expr} interpolation nodes and synthesize preview text
  *  bindings (mirroring the runtime's auto-wire synthesis). Each produces a
  *  PreviewBindingSpec whose expression is a template-literal the preview evals. */
@@ -151,22 +184,33 @@ async function loadProfileRegistry(frameworkPackage) {
     const registry = new Map();
     if (!frameworkPackage)
         return registry;
-    const profileMod = await import(frameworkPackage + "/displays/ili9341-spi").catch(() => null);
-    if (profileMod?.BUILT_IN_PROFILES) {
-        for (const [key, value] of Object.entries(profileMod.BUILT_IN_PROFILES)) {
-            registry.set(key, value);
+    // Every framework package exports its named profiles as BUILT_IN_PROFILES
+    // in the shared DisplayProfile shape (Arduino: the displays modules; Zephyr:
+    // the display barrel, mapped from its DT-binding descriptors). Try each
+    // known entry point — the miss is expected per framework — so this loader
+    // stays layout-agnostic and profile names resolve identically here and via
+    // the strategy's getProfileRegistry() (which transpile.ts uses).
+    for (const modPath of [frameworkPackage + "/displays/ili9341-spi", frameworkPackage + "/display"]) {
+        const mod = await import(modPath).catch(() => null);
+        const profiles = mod?.BUILT_IN_PROFILES;
+        if (profiles) {
+            for (const [key, value] of Object.entries(profiles)) {
+                registry.set(key, value);
+            }
+            break;
         }
     }
     return registry;
 }
-function loadFont(projectRoot, diagnostics) {
+/** Load the stock 5x7 GFX font for the preview runtime. A project-local
+ *  Adafruit_GFX copy wins (byte-identical to what the firmware compiles
+ *  against); otherwise fall back to the table bundled in
+ *  @typecad/cuttlefish (api/shared glcdfont.ts) so stock-font text renders
+ *  without a vendored library. */
+export function loadFont(projectRoot, diagnostics) {
     const fontPath = path.join(projectRoot, "lib", "Adafruit_GFX_Library", "glcdfont.c");
     if (!fs.existsSync(fontPath)) {
-        diagnostics.push({
-            severity: "warning",
-            message: `Default GFX font not found at ${fontPath}; text pixels will be blank.`,
-        });
-        return Array.from(new Uint8Array(1280));
+        return GLCDFONT_BYTES.slice(0, 1280);
     }
     const source = fs.readFileSync(fontPath, "utf-8");
     const match = /font\[\]\s+PROGMEM\s*=\s*\{([\s\S]*?)\};/.exec(source);
@@ -568,6 +612,7 @@ export async function buildPreviewSnapshot(options) {
     let sourceFile;
     let htmlText;
     let cssText;
+    let cssFileDir; // directory @imports inside cssText resolve from
     let htmlFilePath; // the effective .ui.html path (real or synthetic)
     let uiImports;
     if (entryExt === ".ui") {
@@ -581,6 +626,7 @@ export async function buildPreviewSnapshot(options) {
         sourceFile = ts.createSourceFile(entryFile, scriptWithImport, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
         htmlText = parts.html;
         cssText = parts.style;
+        cssFileDir = entryDir;
         uiImports = [{ treeName: "screen", htmlPath: htmlFilePath }];
     }
     else {
@@ -600,13 +646,24 @@ export async function buildPreviewSnapshot(options) {
         htmlText = fs.readFileSync(firstImport.htmlPath, "utf-8");
         const cssPath = themeCssPath(config.display?.themeCss, firstImport.htmlPath, configDir);
         cssText = fs.existsSync(cssPath) ? fs.readFileSync(cssPath, "utf-8") : "";
+        cssFileDir = path.dirname(cssPath);
     }
     const registry = await loadProfileRegistry(config.framework);
     const resolved = resolveDisplayProfile(config.display ?? { profile: "ili9341-spi" }, registry);
     const profile = resolved.profile;
     const displaySize = effectiveDisplaySize(profile);
     const parsedHtml = parseHtmlWithKeyboards(htmlText);
-    const fullCss = cssText + "\n" + extractStyleBlocks(htmlText);
+    // @import parity with the CLI build (loadUIModuleFromText in ui-registry.ts
+    // expands imports before parsing). Without this, `@import "./styles/shadcn.css"`
+    // in a .ui <style> stays literal in the preview, the kit's tokens never load,
+    // and model lowering rejects the raw var() color strings. The sidecar css and
+    // the html style blocks can live in different directories, so each part
+    // expands against its own base.
+    // Built-in shadcn kit first (device parity with ui-registry): user token
+    // blocks and recipe overrides win by cascade order.
+    const fullCss = SHADCN_KIT_CSS + "\n" +
+        expandCssImports(cssText, cssFileDir) + "\n" +
+        expandCssImports(extractStyleBlocks(htmlText), path.dirname(htmlFilePath));
     const cssRules = (() => {
         const previousThemeClass = getThemeClass();
         setThemeClass(config.display?.themeClass ?? null);
@@ -617,12 +674,29 @@ export async function buildPreviewSnapshot(options) {
             setThemeClass(previousThemeClass);
         }
     })();
-    const fontFaces = parseFontFaces(fullCss);
+    // Default-font parity with the CLI build (ui-registry.ts / transpile-ui.ts
+    // both inject the bundled DejaVu faces before planning font assets). Without
+    // this the UA root's font-family: "DejaVu Sans" resolves to no face and the
+    // preview falls back to the smoothed 5x7 — the device renders real AA glyphs.
+    const fontFaces = injectDefaultFontFaces(parseFontFaces(fullCss), profile.colorFormat);
     const rawKeyframes = parseKeyframes(fullCss);
     const styled = resolveStyles(parsedHtml.tree, cssRules);
     const allStyledScreens = parsedHtml.screens.map((screen) => resolveStyles(screen, cssRules));
     const fontRoot = { tag: "screen", classes: [], style: {}, children: allStyledScreens };
-    const fontAssets = buildUIFontAssets(fontRoot, fontFaces, path.dirname(htmlFilePath));
+    // Script-side ui.bind(..., 'text', ...) targets render runtime strings the
+    // static template can't predict — collect their ids so font planning widens
+    // those faces to the fallback charset (markup {expr} and bind:text are
+    // detected from the tree inside the planner).
+    const dynamicTextIds = new Set();
+    const bindTextRe = /ui\.bind\(\s*screen\.([A-Za-z_$][\w$]*)\s*,\s*["']text["']/g;
+    for (const m of sourceFile.text.matchAll(bindTextRe))
+        dynamicTextIds.add(m[1]);
+    const fontAssets = buildUIFontAssets(fontRoot, fontFaces, path.dirname(htmlFilePath), dynamicTextIds);
+    // Prime the image-conversion cache (<img src="*.png|jpg|ico|…"> decodes
+    // here) and give id-less-size img nodes their natural geometry before the
+    // synchronous layout + asset pass below.
+    await warmUpImageDecoding(htmlText, path.dirname(htmlFilePath), { maxW: displaySize.width, maxH: displaySize.height });
+    applyDecodedImageSizes(allStyledScreens.length > 0 ? allStyledScreens : [styled], path.dirname(htmlFilePath));
     const viewport = { x: 0, y: 0, w: displaySize.width, h: displaySize.height };
     const boxes = allStyledScreens.flatMap((screen) => {
         const engine = selectEngine(screen);
@@ -633,6 +707,11 @@ export async function buildPreviewSnapshot(options) {
     const program = lowerUIToModel(styled, boxes, profile.colorFormat, profile, fontAssets, allStyledScreens, imageAssets.nodeIdToAssetIndex, keyframeSets, imageAssets.assets);
     const specs = extractAuthorSpecs(sourceFile, uiImports, program.nodes);
     const hrefCallbacks = collectHrefCallbacks(allStyledScreens, program.nodes);
+    // on:*/bind:*/{expr} features resolve their node by id — the device build
+    // auto-wires id-less nodes, but the preview's binding/callback tables key on
+    // id, so an unnamed interactive node is silently inert here. Make that
+    // visible instead of a dead button.
+    warnUnnamedInteractiveNodes(allStyledScreens, diagnostics);
     // {expr} interpolation bindings synthesized from the HTML (mirrors the runtime's
     // auto-wire synthesis). Authors write `taps: {count}` in markup; this collects
     // them so the preview evaluates the template-literal expression each frame.

package/dist/preview/host-gfx.d.ts

@@ -28,6 +28,7 @@ export declare class HostAdafruitGFX {
     private textColor;
     private textBgColor;
     private monoSnap;
+    private storage;
     private textSizeX;
     private textSizeY;
     private wrap;
@@ -38,6 +39,8 @@ export declare class HostAdafruitGFX {
      *  every color to black/white by luminance, matching the device's
      *  UI_MAYBE_SNAP_MONO565. Uses the same threshold as toMono (0.27). */
     setMonoSnap(on: boolean): void;
+    /** Set the buffer's storage depth (see the `storage` field). */
+    setStorageMode(mode: "rgb565" | "rgb666" | "rgb888"): void;
     private snap;
     setRotation(_rotation: number): void;
     setClipRect(rect: {