@typecad/ui 0.1.0-alpha.1

package/dist/ui-engine/ui-file-splitter.js

@@ -0,0 +1,47 @@
+// ---------------------------------------------------------------------------
+// .ui single-file component splitter.
+//
+// A .ui file combines <script>, <style>, and an HTML template in one file:
+//
+//   <script>
+//     export const count = ui.signal(0);
+//   </script>
+//   <style>
+//     #btn { background: #3399ff; }
+//   </style>
+//   <screen id="home">
+//     <button id="btn" on:click="increment">Tap</button>
+//   </screen>
+//
+// splitUiFile extracts the three streams so the transpiler can feed them to the
+// existing pipelines: script → TS, style → CSS, template → HTML parser. The
+// blocks may appear in any order; multiple <style> blocks are concatenated.
+// ---------------------------------------------------------------------------
+/**
+ * Split a .ui single-file component into its script, style, and template parts.
+ * Extracts <script> and <style> blocks (case-insensitive tags) and returns the
+ * remainder as the HTML template. Multiple <style> blocks are concatenated.
+ */
+export function splitUiFile(src) {
+    let script = "";
+    const styles = [];
+    // Remove script and style blocks from the source, collecting their contents.
+    // The remainder is the HTML template.
+    let html = src;
+    // Extract <script>...</script> (first one wins; v1 supports a single block).
+    html = html.replace(/<script\b[^>]*>([\s\S]*?)<\/script>/gi, (_m, content) => {
+        if (!script)
+            script = content.trim();
+        return "";
+    });
+    // Extract all <style>...</style> blocks.
+    html = html.replace(/<style\b[^>]*>([\s\S]*?)<\/style>/gi, (_m, content) => {
+        styles.push(content.trim());
+        return "";
+    });
+    return {
+        script,
+        style: styles.join("\n"),
+        html: html.trim(),
+    };
+}

package/dist/ui-engine/ui-lowering.d.ts

@@ -0,0 +1,33 @@
+import { StyledNode } from "./style-resolver.js";
+import { Box } from "./layout-engine.js";
+import { type KeyframeSetModel } from "./model.js";
+import type { KeyboardTemplate } from "./html-parser.js";
+import type { CSSRule } from "./css-parser.js";
+import type { DisplayProfile } from "@typecad/cuttlefish/api/shared";
+import type { UIFontAssetModel } from "./font-assets.js";
+import type { Diagnostic } from "@typecad/cuttlefish/api/shared";
+export interface LoweredUI {
+    fontTables: string;
+    nodeTable: string;
+    transitionTable: string;
+    typeDecl: string;
+    /** C++ keyboard loader function bodies (one per keyboard in use). */
+    keyboardLoaders: string;
+    /** C++ dispatch table mapping input node index → loader function. */
+    keyboardDispatch: string;
+    /** Number of distinct screens (for multi-screen navigation). */
+    screenCount: number;
+    /** C++ image data arrays + index table (for <img> support). */
+    imageTables: string;
+    /** C++ keyframe data arrays + animation table. */
+    keyframeTables: string;
+    /** Compile-time warnings for scroll viewports that exceed the canvas budget. */
+    scrollMemoryDiagnostics: Diagnostic[];
+    /** Layout-time diagnostics (viewport overflow, text overflow). Populated by
+     *  lowerOnMount after the boxes are computed; empty until then. */
+    diagnostics: Diagnostic[];
+}
+type ColorFormat = "rgb565" | "rgb666" | "rgb888" | "mono";
+type Storage = "progmem" | "flash";
+export declare function lowerUIToCpp(root: StyledNode, boxes: Box[], colorFormat: ColorFormat, storage: Storage, keyboards?: KeyboardTemplate[], rules?: CSSRule[], display?: DisplayProfile, fontAssets?: UIFontAssetModel[], allScreens?: StyledNode[], imageAssetIds?: Map<string, number>, keyframeSets?: KeyframeSetModel[], scrollCanvasBudgetBytes?: number): LoweredUI;
+export {};

package/dist/ui-engine/ui-lowering.js

@@ -0,0 +1,390 @@
+// ---------------------------------------------------------------------------
+// UI lowering — styled tree + computed boxes → C++ node/binding/transition
+// tables + a .ui.d.html.ts declaration file.
+//
+// This is the bridge between the host-side parse/layout pipeline and the
+// device-side retained runtime. Colors are resolved to the target color format
+// here (once, at transpile time) so the device never converts colors.
+//
+// Output shape:
+//   - nodeTable:       `static const UINode __ui_nodes[] = { ... };`
+//   - transitionTable: `static const UITransition __ui_trans[] = { ... };`
+//   - typeDecl:        TypeScript declarations so .ui.html imports are typed.
+// ---------------------------------------------------------------------------
+import { lowerUIToModel } from "./model.js";
+import { resolveColor } from "./color.js";
+import { DEFAULT_ALPHA_KEYBOARD, DEFAULT_NUMBER_KEYBOARD } from "./default-keyboards.js";
+import { analyzeScrollMemory } from "./scroll-memory-diagnostics.js";
+import { getListBindings } from "@typecad/cuttlefish/ir/transformers/ui-reactive";
+export function lowerUIToCpp(root, boxes, colorFormat, storage, keyboards = [], rules = [], display, fontAssets = [], allScreens = [], imageAssetIds = new Map(), keyframeSets = [], scrollCanvasBudgetBytes) {
+    void storage;
+    const model = lowerUIToModel(root, boxes, colorFormat, display, fontAssets, allScreens, imageAssetIds, keyframeSets);
+    const scrollMemoryDiagnostics = analyzeScrollMemory(model.nodes, scrollCanvasBudgetBytes);
+    // Tables are mutable RAM (ui_tick updates bg/dirty/elapsed/active each
+    // frame), so no PROGMEM/flash storage keyword — those imply read-only.
+    const fontTables = emitFontTables(model);
+    const nodeTable = emitNodeTable(model) + "\n" + emitScrollNodeIdLookup(model);
+    const transitionTable = emitTransitionTable(model);
+    const typeDecl = emitTypeDecl(root);
+    // Keyboard loaders + dispatch: collect input nodes in tree order, resolve
+    // each to its loader (default by type, or a referenced <keyboard>).
+    // Walk ALL screens (inputs may live on any screen, not just the root).
+    const inputSpecs = [];
+    const collectInputs = (n) => {
+        if (n.tag === "input")
+            inputSpecs.push({ type: n.type, keyboard: n.keyboard });
+        n.children.forEach(collectInputs);
+    };
+    const inputRoots = allScreens.length > 0 ? allScreens : [root];
+    for (const sr of inputRoots)
+        collectInputs(sr);
+    const neededKeyboards = [];
+    const addIfNeeded = (kb) => {
+        if (!neededKeyboards.some(k => k.id === kb.id))
+            neededKeyboards.push(kb);
+    };
+    for (const spec of inputSpecs) {
+        if (spec.keyboard) {
+            const match = keyboards.find(k => k.id === spec.keyboard);
+            if (match)
+                addIfNeeded(match);
+        }
+        else {
+            addIfNeeded(spec.type === "number" ? DEFAULT_NUMBER_KEYBOARD : DEFAULT_ALPHA_KEYBOARD);
+        }
+    }
+    const keyboardLoaders = neededKeyboards
+        .map(kb => emitKeyboardLoader(loaderNameForId(kb.id), kb, rules, colorFormat))
+        .join("\n\n");
+    const dispatchEntries = inputSpecs.map(spec => loaderNameForInput(spec, keyboards));
+    const keyboardDispatch = dispatchEntries.length > 0
+        ? `void (*__ui_kb_loaders[])() = { ${dispatchEntries.join(", ")} };\nconst uint16_t __ui_kb_loader_count = ${dispatchEntries.length};`
+        : `void (*__ui_kb_loaders[])() = {};\nconst uint16_t __ui_kb_loader_count = 0;`;
+    const screenCount = model.nodes.length > 0 ? Math.max(...model.nodes.map(n => n.screenId)) + 1 : 1;
+    const imageTables = "const UIImage __ui_images[] = {};\nconst uint16_t __ui_image_count = 0;";
+    const keyframeTables = emitKeyframeTables(model);
+    return { fontTables, nodeTable, transitionTable, typeDecl, keyboardLoaders, keyboardDispatch, screenCount, imageTables, keyframeTables, scrollMemoryDiagnostics, diagnostics: [] };
+}
+function sanitizedId(id) {
+    return id.replace(/[^a-zA-Z0-9_]/g, "_");
+}
+function loaderNameForId(id) {
+    return `__ui_kb_load_${sanitizedId(id)}`;
+}
+function loaderNameForInput(input, keyboards) {
+    if (input.keyboard) {
+        const match = keyboards.find(k => k.id === input.keyboard);
+        if (match)
+            return loaderNameForId(match.id);
+    }
+    return input.type === "number" ? "__ui_kb_load_default_number" : "__ui_kb_load_default_alpha";
+}
+// Default key colors (fallback when no CSS matches). Used for all keys.
+const DEFAULT_KEY_BG = 0x4208; // dark gray
+const DEFAULT_KEY_FG = 0xFFFF; // white
+const DEFAULT_KEY_BORDER = 0xFFFF; // white
+const DEFAULT_KB_BG = 0x0000; // black
+/** Resolve a key's CSS classes into a merged CSSProperty (cascade: last wins). */
+/** Check if a CSS rule's selector matches any of the given class names.
+ *  Only matches single-compound class selectors (no descendant for keys). */
+function ruleMatchesClass(rule, classes) {
+    // Must be a single compound (no descendant combinator).
+    if (rule.selector.compounds.length !== 1)
+        return false;
+    const compound = rule.selector.compounds[0];
+    // Every simple in the compound must be a class that's in the list.
+    for (const s of compound) {
+        if (s.kind !== "class" || !classes.includes(s.name))
+            return false;
+    }
+    return true;
+}
+function resolveKeyStyle(keyClasses, kbClasses, rules) {
+    const merged = {};
+    const allClasses = [...(kbClasses ?? []), ...(keyClasses ?? [])];
+    for (const rule of rules) {
+        if (ruleMatchesClass(rule, allClasses)) {
+            Object.assign(merged, rule.properties);
+        }
+    }
+    return merged;
+}
+/** Resolve the keyboard-level background from CSS (keyboard classes). */
+function resolveKbBg(kbClasses, rules, colorFormat) {
+    const merged = {};
+    const classes = kbClasses ?? [];
+    for (const rule of rules) {
+        if (ruleMatchesClass(rule, classes)) {
+            Object.assign(merged, rule.properties);
+        }
+    }
+    return merged.background ? resolveColor(merged.background, colorFormat) : DEFAULT_KB_BG;
+}
+function emitKeyboardLoader(name, kb, rules, colorFormat) {
+    const rows = kb.rows;
+    const cols = rows.length > 0 ? Math.max(...rows.map(r => r.length)) : 0;
+    const kbBg = resolveKbBg(kb.classes, rules, colorFormat);
+    const lines = [];
+    lines.push(`void ${name}() {`);
+    lines.push(`  __ui_kb_rows = ${rows.length};`);
+    lines.push(`  __ui_kb_cols = ${cols};`);
+    lines.push(`  __ui_kb_keyCount = 0;`);
+    lines.push(`  __ui_kb_bg = ${hex(kbBg)};`);
+    for (const row of rows) {
+        for (const key of row) {
+            lines.push(`  ${emitKeyLine(key, kb.classes, rules, colorFormat)}`);
+        }
+        // Pad short rows so ui_kb_key_rect's idx/cols math stays aligned. Padded
+        // cells use special=255 (skipped in draw + hit-test) with a space char.
+        for (let p = row.length; p < cols; p++) {
+            lines.push(`  ui_kb_add_key(' ', 255, ${hex(DEFAULT_KEY_BG)}, ${hex(DEFAULT_KEY_FG)}, ${hex(DEFAULT_KEY_BORDER)});`);
+        }
+    }
+    lines.push(`}`);
+    return lines.join("\n");
+}
+/** Emit one key's keys[] + styles[] lines, resolving CSS classes to colors. */
+function emitKeyLine(key, kbClasses, rules, colorFormat) {
+    const chEsc = key.ch === "\\" ? "\\\\" : key.ch === "'" ? "\\'" : key.ch;
+    const style = resolveKeyStyle(key.classes, kbClasses, rules);
+    const bg = style.background ? resolveColor(style.background, colorFormat) : DEFAULT_KEY_BG;
+    const fg = style.color ? resolveColor(style.color, colorFormat) : DEFAULT_KEY_FG;
+    const border = style.borderColor ? resolveColor(style.borderColor, colorFormat) : DEFAULT_KEY_BORDER;
+    return `ui_kb_add_key('${chEsc}', ${key.special}, ${hex(bg)}, ${hex(fg)}, ${hex(border)});`;
+}
+function cppKind(kind) {
+    switch (kind) {
+        case "fill": return "NODE_FILL";
+        case "button": return "NODE_BUTTON";
+        case "check": return "NODE_CHECK";
+        case "radio": return "NODE_RADIO";
+        case "progress": return "NODE_PROGRESS";
+        case "range": return "NODE_RANGE";
+        case "input": return "NODE_INPUT";
+        case "img": return "NODE_IMG";
+        case "list": return "NODE_LIST";
+        case "canvas": return "NODE_CANVAS";
+        case "text": return "NODE_TEXT";
+    }
+}
+function hex(c) {
+    return `0x${c.toString(16).padStart(4, "0")}`;
+}
+function cppString(value) {
+    return value ? JSON.stringify(value) : "nullptr";
+}
+function byteArray(values) {
+    if (values.length === 0)
+        return "";
+    const chunks = [];
+    for (let i = 0; i < values.length; i += 16) {
+        chunks.push("  " + values.slice(i, i + 16).map((v) => `0x${(v & 0xff).toString(16).padStart(2, "0")}`).join(", "));
+    }
+    return chunks.join(",\n");
+}
+function emitFontTables(model) {
+    const assets = model.fontAssets ?? [];
+    if (assets.length === 0) {
+        return [
+            `const UIFontFace __ui_font_faces[] = {};`,
+            `const uint16_t __ui_font_face_count = 0;`,
+        ].join("\n");
+    }
+    const lines = [];
+    for (const asset of assets) {
+        lines.push(`// Font ${asset.id}: ${asset.family} ${asset.px}px ${asset.fontWeight} ${asset.fontStyle} ${asset.subset}`);
+        // Alpha data goes in PROGMEM (constants in flash, not RAM) - accessed via pgm_read_byte on AVR
+        lines.push(`static const uint8_t __ui_font_${asset.id}_alpha[] PROGMEM = {`);
+        lines.push(byteArray(asset.alpha));
+        lines.push(`};`);
+        lines.push(`static const UIFontGlyph __ui_font_${asset.id}_glyphs[] = {`);
+        for (const glyph of asset.glyphs) {
+            lines.push(`  { ${glyph.codepoint}, ${glyph.xOffset}, ${glyph.yOffset}, ${glyph.width}, ${glyph.height}, ${glyph.advance}, ${glyph.dataOffset} },`);
+        }
+        lines.push(`};`);
+    }
+    // Font faces and glyphs stay in regular memory for direct struct access
+    // (AVR optimized builds can move the whole table to PROGMEM + accessor functions)
+    lines.push(`const UIFontFace __ui_font_faces[] = {`);
+    for (const asset of assets) {
+        lines.push(`  { ${asset.id}, ${asset.glyphs.length}, ${asset.lineHeight}, ${asset.baseline}, __ui_font_${asset.id}_glyphs, __ui_font_${asset.id}_alpha },`);
+    }
+    lines.push(`};`);
+    lines.push(`const uint16_t __ui_font_face_count = ${assets.length};`);
+    return lines.join("\n");
+}
+function emitScrollNodeIdLookup(model) {
+    const cases = [];
+    for (const n of model.nodes) {
+        if (!n.scrollable || n.contentHeight <= n.box.h || !n.id)
+            continue;
+        const id = n.id.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+        cases.push(`  if (idx == ${n.index}) return "${id}";`);
+    }
+    if (cases.length === 0) {
+        return "static inline const char* __ui_scroll_node_id(uint16_t idx) { (void)idx; return nullptr; }";
+    }
+    return [
+        "static inline const char* __ui_scroll_node_id(uint16_t idx) {",
+        ...cases,
+        "  return nullptr;",
+        "}",
+    ].join("\n");
+}
+function emitNodeTable(model) {
+    // Map node index → list binding so virtualized nodes carry their count/item/
+    // tap function pointers on-node (no UIListBinding side table at runtime).
+    const listBindingByNode = new Map();
+    for (const lb of getListBindings())
+        listBindingByNode.set(lb.nodeIndex, lb);
+    // Accumulate rich-text run / segment / line parallel arrays across all
+    // run-bearing nodes, assigning each a contiguous slice (runStart/richSegStart/
+    // richLineStart + counts). Emitted as global tables after the node table.
+    const runRows = [];
+    const segRows = [];
+    const lineRows = [];
+    const richRanges = new Map();
+    for (const n of model.nodes) {
+        if (!n.runs || !n.runLines || n.runs.length === 0)
+            continue;
+        const runStart = runRows.length;
+        for (const r of n.runs) {
+            runRows.push(`  { .text=${cppString(r.text)}, .fg=${hex(r.fg)}, .textSize=${r.textSize}, .fontFace=${r.fontFace}, .underline=${r.underline}, .letterSpacing=${r.letterSpacing}, .linkTarget=${r.linkTarget} },`);
+        }
+        const richSegStart = segRows.length;
+        for (let s = 0; s < n.runLines.segRun.length; s++) {
+            segRows.push(`  { .runIndex=${n.runLines.segRun[s]}, .text=${cppString(n.runLines.segText[s])}, .x=${n.runLines.segX[s]}, .w=${n.runLines.segW[s]}, .line=${n.runLines.segLine[s]} },`);
+        }
+        const richLineStart = lineRows.length;
+        for (let l = 0; l < n.runLines.lineY.length; l++) {
+            lineRows.push(`  { .y=${n.runLines.lineY[l]}, .h=${n.runLines.lineH[l]}, .baseline=${n.runLines.lineBaseline[l]}, .w=${n.runLines.lineW[l]} },`);
+        }
+        richRanges.set(n.index, {
+            runCount: n.runs.length, runStart,
+            richLineCount: n.runLines.lineY.length, richSegStart,
+            richSegCount: n.runLines.segRun.length, richLineStart,
+        });
+    }
+    const lines = model.nodes.map((n) => {
+        const text = cppString(n.text);
+        const font = "nullptr";
+        // Input nodes store the placeholder in .text (static literal) so the draw
+        // can show it grayed when textBuffer is empty. textBuffer stays {0} so
+        // ui_kb_open starts with a clean edit buffer (no placeholder to delete).
+        const inputText = n.kind === "input" && n.textBuffer ? cppString(n.textBuffer) : text;
+        const box = `{${n.box.x},${n.box.y},${n.box.w},${n.box.h}}`;
+        const parent = n.parentIndex >= 0 ? n.parentIndex : 0xFFFF; // UI_NO_PARENT
+        // Progress/range use lastTextWidth as a "previous fill width" for
+        // incremental redraw. -1 = never drawn, because fill width 0 is valid.
+        const lastTextWidth = n.kind === "progress" || n.kind === "range" ? -1 : 0;
+        const shArr = (vals, n = 4) => `{${[...vals.slice(0, n), ...Array(n - Math.min(vals.length, n)).fill(0)].join(",")}}`;
+        // Virtualized list: resolve on-node function pointers from the binding.
+        const lb = listBindingByNode.get(n.index);
+        const virtualized = n.virtualized ? 1 : 0;
+        const listCountFn = lb ? lb.countFnName : "nullptr";
+        const listItemFn = lb ? lb.itemFnName : "nullptr";
+        const listTapFn = lb && lb.tapFnName ? lb.tapFnName : "nullptr";
+        const rr = richRanges.get(n.index);
+        const runCount = rr ? rr.runCount : 0;
+        const runStart = rr ? rr.runStart : 0;
+        const richLineCount = rr ? rr.richLineCount : 0;
+        const richSegStart = rr ? rr.richSegStart : 0;
+        const richSegCount = rr ? rr.richSegCount : 0;
+        const richLineStart = rr ? rr.richLineStart : 0;
+        return `  { .box=${box}, .bg=${hex(n.bg)}, .fg=${hex(n.fg)}, .kind=${cppKind(n.kind)}, .text=${inputText}, .textBuffer={0}, .hasTextBinding=0, .font=${font}, .hasBg=${n.hasBg ? 1 : 0}, .textAlign=${n.textAlign}, .textSize=${n.textSize}, .lineHeight=${n.lineHeight}, .letterSpacing=${n.letterSpacing}, .fontAntialias=${n.fontAntialias ? 1 : 0}, .fontFace=${n.fontFace}, .borderColor=${hex(n.borderColor)}, .borderStyle=${n.borderStyle}, .borderWidth=${n.borderWidth}, .borderTopWidth=${n.borderTopWidth ?? n.borderWidth}, .borderRightWidth=${n.borderRightWidth ?? n.borderWidth}, .borderBottomWidth=${n.borderBottomWidth ?? n.borderWidth}, .borderLeftWidth=${n.borderLeftWidth ?? n.borderWidth}, .hasPerSideBorder=${((n.borderTopWidth ?? n.borderWidth) !== n.borderWidth || (n.borderRightWidth ?? n.borderWidth) !== n.borderWidth || (n.borderBottomWidth ?? n.borderWidth) !== n.borderWidth || (n.borderLeftWidth ?? n.borderWidth) !== n.borderWidth) ? 1 : 0}, .borderRadius=${n.borderRadius}, .paddingTop=${n.paddingTop ?? 0}, .paddingRight=${n.paddingRight ?? 0}, .paddingBottom=${n.paddingBottom ?? 0}, .paddingLeft=${n.paddingLeft ?? 0}, .gradientEnabled=${n.gradientEnabled}, .gradientColor1=${hex(n.gradientColor1)}, .gradientColor2=${hex(n.gradientColor2)}, .outlineColor=${hex(n.outlineColor)}, .outlineStyle=${n.outlineStyle}, .outlineWidth=${n.outlineWidth}, .zIndex=${n.zIndex}, .transformOffsetX=${n.transformOffsetX}, .transformOffsetY=${n.transformOffsetY}, .rotateDeg=${n.rotateDeg}, .pressedOffsetX=${n.pressedOffsetX}, .pressedOffsetY=${n.pressedOffsetY}, .shadowCount=${n.shadowCount}, .shadowOffsetX=${shArr(n.shadowOffsetX)}, .shadowOffsetY=${shArr(n.shadowOffsetY)}, .shadowBlur=${shArr(n.shadowBlur)}, .shadowColor={${n.shadowColor.slice(0, 4).map(hex).join(",")}}, .shadowAlpha=${shArr(n.shadowAlpha)}, .shadowInset=${shArr(n.shadowInset.map(v => v ? 1 : 0))}, .textShadowCount=${n.textShadowCount}, .textShadowOffsetX=${n.textShadowOffsetX}, .textShadowOffsetY=${n.textShadowOffsetY}, .textShadowBlur=${n.textShadowBlur}, .textShadowColor=${hex(n.textShadowColor)}, .textShadowAlpha=${n.textShadowAlpha}, .underline=${n.underline}, .textOverflow=${n.textOverflow ? 1 : 0}, .nowrap=${n.nowrap ? 1 : 0}, .whiteSpaceMode=${n.whiteSpaceMode}, .visible=${n.visible ? 1 : 0}, .opacity=${n.opacity}, .clearColor=${hex(n.clearColor)}, .lastTextWidth=${lastTextWidth}, .lastTextHeight=0, .layoutCacheKey=0, .layoutMetricsW=0, .layoutMetricsH=0, .scrollable=${n.scrollable ? 1 : 0}, .virtualized=${virtualized}, .scrollY=0, .contentHeight=${n.contentHeight}, .overscrollPx=0, .settling=0, .lastPaintedScrollY=0, .listCount=0, .listCountFn=${listCountFn}, .listItemFn=${listItemFn}, .listTapFn=${listTapFn}, .parent=${parent}, .subtreeEnd=${n.subtreeEnd}, .screenId=${n.screenId}, .imgDataId=${n.imgDataId ?? 255}, .objectFit=${n.objectFit ?? 1}, .listItemHeight=${n.listItemHeight ?? 0}, .rangeMin=${n.rangeMin}, .rangeMax=${n.rangeMax}, .maxlen=${n.maxlen}, .canvasW=${n.canvasW ?? 0}, .canvasH=${n.canvasH ?? 0}, .runCount=${runCount}, .richLineCount=${richLineCount}, .runStart=${runStart}, .richSegStart=${richSegStart}, .richSegCount=${richSegCount}, .richLineStart=${richLineStart}, .dirty=0, .value=${n.value} },`;
+    });
+    return [
+        // Mutable (not const) so ui_tick can update bg/dirty during transitions.
+        // AVR would want PROGMEM + a shadow copy; ESP32-class has RAM to spare.
+        `UINode __ui_nodes[] = {`,
+        ...lines,
+        `};`,
+        // Rich-text parallel arrays. Mutable is unnecessary (static content) but
+        // matches __ui_nodes[] linkage; nodes reference slices via runStart etc.
+        runRows.length > 0
+            ? [`UIRichRun __ui_runs[] = {`, ...runRows, `};`].join("\n")
+            : `UIRichRun __ui_runs[1];`,
+        segRows.length > 0
+            ? [`UIRichSeg __ui_rich_segs[] = {`, ...segRows, `};`].join("\n")
+            : `UIRichSeg __ui_rich_segs[1];`,
+        lineRows.length > 0
+            ? [`UIRichLine __ui_rich_lines[] = {`, ...lineRows, `};`].join("\n")
+            : `UIRichLine __ui_rich_lines[1];`,
+        `const uint16_t __ui_run_count = ${runRows.length};`,
+        `const uint16_t __ui_rich_seg_count = ${segRows.length};`,
+        `const uint16_t __ui_rich_line_count = ${lineRows.length};`,
+    ].join("\n");
+}
+function emitTransitionTable(model) {
+    const entries = model.transitions.map((t) => {
+        const prop = t.prop === "background" ? "PROP_BG" : "PROP_FG";
+        return `  { .node=${t.node}, .prop=${prop}, .durationMs=${t.durationMs}, .pressedTarget=${hex(t.pressedTarget)}, .baseTarget=${hex(t.baseTarget)} },`;
+    });
+    if (entries.length === 0) {
+        return `UITransition __ui_trans[] = {};`;
+    }
+    return [
+        `UITransition __ui_trans[] = {`,
+        ...entries,
+        `};`,
+    ].join("\n");
+}
+/** Emit keyframe stop arrays + keyframe set index + animation table. */
+function emitKeyframeTables(model) {
+    if (model.keyframeSets.length === 0 && model.animations.length === 0) {
+        return [
+            `const UIKeyframeSet __ui_keyframe_sets[] = {};`,
+            `const uint16_t __ui_keyframe_set_count = 0;`,
+            `UIAnimation __ui_anims[] = {};`,
+            `const uint16_t __ui_anim_count = 0;`,
+        ].join("\n");
+    }
+    const lines = [];
+    // Emit one stop array per keyframe set.
+    for (const ks of model.keyframeSets) {
+        const safeName = ks.name.replace(/[^a-zA-Z0-9_]/g, "_");
+        lines.push(`static const UIKeyframeStop __ui_kf_${safeName}_stops[] = {`);
+        for (const s of ks.stops) {
+            lines.push(`  { .percent=${s.percent}, .props=${s.props}, .bg=${hex(s.bg)}, .fg=${hex(s.fg)}, .opacity=${s.opacity}, .transformOffsetX=${s.transformOffsetX}, .transformOffsetY=${s.transformOffsetY}, .translatePctX=${s.translatePctX}, .translatePctY=${s.translatePctY}, .scaleX=${s.scaleX}, .scaleY=${s.scaleY}, .rotateDeg=${s.rotateDeg}, .width=${s.width}, .height=${s.height} },`);
+        }
+        lines.push(`};`);
+    }
+    // Emit keyframe set index table.
+    lines.push(`const UIKeyframeSet __ui_keyframe_sets[] = {`);
+    model.keyframeSets.forEach((ks) => {
+        const safeName = ks.name.replace(/[^a-zA-Z0-9_]/g, "_");
+        lines.push(`  { .stopCount=${ks.stops.length}, .stops=__ui_kf_${safeName}_stops },`);
+    });
+    lines.push(`};`);
+    lines.push(`const uint16_t __ui_keyframe_set_count = ${model.keyframeSets.length};`);
+    // Emit animation table (mutable — runtime advances elapsed/active).
+    lines.push(`UIAnimation __ui_anims[] = {`);
+    for (const a of model.animations) {
+        lines.push(`  { .node=${a.node}, .keyframeSet=${a.keyframeSet}, .durationMs=${a.durationMs}, .delayMs=${a.delayMs}, .iterations=${a.iterations}, .baseWidth=${a.baseWidth}, .baseHeight=${a.baseHeight}, .originX=${a.originX}, .originY=${a.originY}, .timingFunction=${a.timingFunction}, .elapsed=0, .active=1, .lastUpdateMs=0 },`);
+    }
+    lines.push(`};`);
+    lines.push(`const uint16_t __ui_anim_count = ${model.animations.length};`);
+    return lines.join("\n");
+}
+function emitTypeDecl(root) {
+    // Collect id → tag pairs by walking the tree.
+    const ids = [];
+    const collect = (n) => {
+        if (n.id)
+            ids.push({ id: n.id, tag: n.tag });
+        n.children.forEach(collect);
+    };
+    collect(root);
+    const fields = ids.map(({ id, tag }) => {
+        const typeName = tag.charAt(0).toUpperCase() + tag.slice(1);
+        return `  ${id}: ${typeName}Element;`;
+    }).join("\n");
+    return [
+        `// Auto-generated by cuttlefish UI lowering. Do not edit.`,
+        `export interface ScreenTree {`,
+        fields,
+        `}`,
+        ``,
+        `export const screen: ScreenTree;`,
+    ].join("\n");
+}

package/dist/ui-engine/ui-registry.d.ts

@@ -0,0 +1,81 @@
+import type { KeyboardTemplate } from "./html-parser.js";
+import type { CSSFontFace, CSSRule, KeyframeSet } from "./css-parser.js";
+import { StyledNode } from "./style-resolver.js";
+import { LoweredUI } from "./ui-lowering.js";
+import type { UIFontAssetModel } from "./font-assets.js";
+import type { Diagnostic } from "@typecad/cuttlefish/api/shared";
+export interface UIModule {
+    /** Absolute path of the .ui.html source. */
+    htmlPath: string;
+    /** Absolute path of the generated type declaration for this UI module. */
+    typeDeclPath: string;
+    /** Source root overlaid with typeDeclRoot for .ui.html TypeScript imports. */
+    typeDeclSourceRoot: string;
+    /** Generated type declaration root used with TypeScript rootDirs. */
+    typeDeclRoot: string;
+    /** Resolved-style tree (HTML + CSS merged). Layout deferred to mount. */
+    styled: StyledNode;
+    /** All resolved <screen> trees (for multi-screen navigation). */
+    allStyledScreens: StyledNode[];
+    /** <keyboard> templates parsed from the same .ui.html (sibling declarations). */
+    keyboards: KeyboardTemplate[];
+    /** CSS rules from the sibling .ui.css (used for keyboard key styling). */
+    rules: CSSRule[];
+    /** @font-face rules from CSS, resolved into build-time font assets. */
+    fontFaces: CSSFontFace[];
+    fontAssets: UIFontAssetModel[];
+    /** Raw @keyframes blocks parsed from CSS. */
+    rawKeyframes: KeyframeSet[];
+    /** Parser-level warnings (unknown CSS properties / HTML tags). */
+    diagnostics: Diagnostic[];
+    /** Layout-time warnings (scroll memory budget, etc.) from ui.mount lowering. */
+    mountDiagnostics: Diagnostic[];
+}
+export interface LowerOptions {
+    colorFormat: "rgb565" | "rgb666" | "rgb888" | "mono";
+    storage: "progmem" | "flash";
+    viewport: {
+        width: number;
+        height: number;
+    };
+}
+export interface UITypeDeclInfo {
+    dtsPath: string;
+    sourceRoot: string;
+    typesRoot: string;
+}
+export interface UITypeDeclarationResult {
+    written: string[];
+    errors: Array<{
+        filePath: string;
+        error: Error;
+    }>;
+}
+/** Reset the registry. Called at the start of each transpile run. */
+export declare function resetUIRegistry(): void;
+/** Load a `.ui.html` module: parse HTML + sibling `.ui.css`, resolve styles, cache. */
+export declare function loadUIModule(htmlPath: string): UIModule;
+/**
+ * Load a UI module from already-read HTML + CSS text (used by the .ui single-file
+ * component path, which splits the file and passes the parts directly). The
+ * disk-reading `loadUIModule` delegates here after reading the files.
+ */
+export declare function loadUIModuleFromText(htmlPath: string, htmlText: string, cssText: string, cssPathForFonts?: string): UIModule;
+/** Produce (or return cached) the lowered C++ tables for a module, using the mount viewport. */
+export declare function lowerOnMount(htmlPath: string, opts: LowerOptions): LoweredUI;
+export declare function getUIModule(htmlPath: string): UIModule | undefined;
+export declare function getLoweredUIModule(htmlPath: string): LoweredUI | undefined;
+export declare function hasUIModule(htmlPath: string): boolean;
+/** All loaded UI modules (used by the emitter to inject every mounted tree). */
+export declare function allUIModules(): UIModule[];
+/** All lowered UI modules (those whose ui.mount has been processed). */
+export declare function allLoweredUIModules(): Array<{
+    htmlPath: string;
+    lowered: LoweredUI;
+}>;
+export declare function markEntryHasUI(): void;
+export declare function entryHasUI(): boolean;
+export declare function clearEntryHasUI(): void;
+export declare function uiTypeDeclInfoForHtmlPath(htmlPath: string): UITypeDeclInfo;
+export declare function writeUITypeDeclarationFromHtmlText(htmlPath: string, htmlText: string): string;
+export declare function generateProjectUITypeDeclarations(projectRoot: string): UITypeDeclarationResult;