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

package/dist/ui-engine/image-decode.js

@@ -0,0 +1,194 @@
+// ---------------------------------------------------------------------------
+// Automatic image conversion: decode any common image format (PNG, JPEG,
+// GIF, BMP, WebP, AVIF/HEIF, TIFF, SVG, ICO) into the raw RGB565 asset form
+// the runtime consumes, so `<img src="photo.png">` just works — no manual
+// conversion to raw .img dumps.
+//
+// Decoding is asynchronous (sharp); the UI module loader is synchronous. The
+// bridge is a warm-up pass: the transpile graph collector and the preview
+// snapshot builder await `warmUpImageDecoding()` on each UI source BEFORE
+// the module loads, priming a cache keyed by absolute path + mtime. The
+// synchronous image-assets reader then consults `getCachedDecodedImage()`.
+// Anything undecodable (including the legacy raw RGB565 .img files) falls
+// back to the raw reader unchanged.
+// ---------------------------------------------------------------------------
+import fs from "node:fs";
+import path from "node:path";
+/** Identify a buffer by magic bytes. null = unknown (raw RGB565 dump). */
+export function detectImageFormat(buf) {
+    if (buf.length >= 4 && buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47)
+        return "png";
+    if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff)
+        return "jpeg";
+    if (buf.length >= 6 && buf.toString("ascii", 0, 3) === "GIF")
+        return "gif";
+    if (buf.length >= 2 && buf[0] === 0x42 && buf[1] === 0x4d)
+        return "bmp";
+    if (buf.length >= 12 && buf.toString("ascii", 0, 4) === "RIFF" && buf.toString("ascii", 8, 12) === "WEBP")
+        return "webp";
+    // ISO-BMFF family (AVIF/HEIF): bytes 4..8 are "ftyp".
+    if (buf.length >= 8 && buf.toString("ascii", 4, 8) === "ftyp")
+        return "avif";
+    if (buf.length >= 4 && buf.toString("ascii", 0, 4) === "II*\0")
+        return "tiff";
+    if (buf.length >= 4 && buf.toString("ascii", 0, 4) === "MM\0*")
+        return "tiff";
+    if (buf.length >= 4 && buf[0] === 0x00 && buf[1] === 0x00 && buf[2] === 0x01 && buf[3] === 0x00)
+        return "ico";
+    // SVG is XML text: after an optional BOM, the first non-space char is '<'.
+    for (let i = 0; i < Math.min(buf.length, 8); i++) {
+        const b = buf[i];
+        if (b === 0xef || b === 0xbb || b === 0xbf)
+            continue; // UTF-8 BOM bytes
+        if (b === 0x20 || b === 0x09 || b === 0x0a || b === 0x0d)
+            continue;
+        if (b === 0x3c)
+            return "svg";
+        break;
+    }
+    return null;
+}
+let sharpLoader = null;
+function loadSharp() {
+    if (!sharpLoader) {
+        sharpLoader = import("sharp").then((m) => m.default).catch((err) => {
+            sharpLoader = null; // a later call can retry (e.g. after an install fix)
+            throw new Error(`the sharp image decoder could not be loaded (${err instanceof Error ? err.message : String(err)}) — ` +
+                `reinstall dependencies, or convert the image to a raw RGB565 .img file manually`);
+        });
+    }
+    return sharpLoader;
+}
+/** Run a sharp pipeline to raw pixels: flatten alpha onto black, optionally
+ *  downscale to fit the display (never enlarge). */
+async function runSharp(pipeline, naturalW, naturalH, opts) {
+    if (opts.maxW && opts.maxH && (naturalW > opts.maxW || naturalH > opts.maxH)) {
+        pipeline = pipeline.resize({ width: opts.maxW, height: opts.maxH, fit: "inside", withoutEnlargement: true });
+    }
+    const { data, info } = await pipeline
+        .flatten({ background: "#000000" })
+        .raw()
+        .toBuffer({ resolveWithObject: true });
+    return { pixels: data, channels: info.channels, width: info.width, height: info.height };
+}
+/** Decode an .ico: decode-ico returns every frame as RGBA (PNG and BMP
+ *  frames alike); pick the largest so the asset carries the best detail. */
+async function decodeIco(buf) {
+    const decodeIcoMod = await import("decode-ico");
+    const decodeIco = decodeIcoMod.default;
+    const u8 = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+    const frames = decodeIco(u8);
+    if (!frames || frames.length === 0)
+        throw new Error("no frames in .ico");
+    let best = frames[0];
+    for (const f of frames) {
+        if (f.width * f.height > best.width * best.height)
+            best = f;
+    }
+    return { pixels: best.data, channels: 4, width: best.width, height: best.height };
+}
+function rgbaToRgb565(px, channels) {
+    const count = Math.floor(px.length / channels);
+    const out = new Array(count);
+    for (let i = 0; i < count; i++) {
+        const r = px[i * channels] >> 3;
+        const g = px[i * channels + 1] >> 2;
+        const b = px[i * channels + 2] >> 3;
+        out[i] = (r << 11) | (g << 5) | b;
+    }
+    return out;
+}
+async function decodeImageBuffer(buf, format, opts) {
+    const sharp = await loadSharp();
+    let raw;
+    if (format === "ico") {
+        const ico = await decodeIco(buf);
+        if (opts.maxW && opts.maxH && (ico.width > opts.maxW || ico.height > opts.maxH)) {
+            // The largest frame still exceeds the display; route its RGBA through
+            // sharp for the same fit-inside downscale every other format gets.
+            const rgbaBuf = Buffer.from(ico.pixels.buffer, ico.pixels.byteOffset, ico.pixels.byteLength);
+            raw = await runSharp(sharp(rgbaBuf, { raw: { width: ico.width, height: ico.height, channels: 4 } }), ico.width, ico.height, opts);
+        }
+        else {
+            raw = ico;
+        }
+    }
+    else {
+        // File bytes: auto-orient by EXIF first, then the shared flatten/fit path.
+        // metadata() reports the STORED dimensions — an EXIF orientation of 5-8
+        // means the pipeline's rotate() transposes the output, so the fit decision
+        // must compare against the swapped natural size or portrait photos can
+        // skip the downscale they need (and landscape ones downscale needlessly).
+        const oriented = sharp(buf, { failOn: "none" }).rotate();
+        const meta = await oriented.metadata();
+        const exifSwap = (meta.orientation ?? 1) >= 5 && (meta.orientation ?? 1) <= 8;
+        const naturalW = exifSwap ? meta.height : meta.width;
+        const naturalH = exifSwap ? meta.width : meta.height;
+        raw = await runSharp(oriented, naturalW ?? 0, naturalH ?? 0, opts);
+    }
+    return { width: raw.width, height: raw.height, data: rgbaToRgb565(raw.pixels, raw.channels) };
+}
+const decodedCache = new Map();
+function cacheKey(abs, mtimeMs) {
+    return `${abs}\0${mtimeMs}`;
+}
+/** The decoded image for a file, or undefined when it was never warmed up or
+ *  its decode failed (the caller falls back to the raw RGB565 reader). */
+export function getCachedDecodedImage(absPath) {
+    let stat;
+    try {
+        stat = fs.statSync(absPath);
+    }
+    catch {
+        return undefined;
+    }
+    const entry = decodedCache.get(cacheKey(absPath, stat.mtimeMs));
+    return entry ? (entry.image ?? undefined) : undefined;
+}
+const SRC_ATTR = /\bsrc\s*=\s*["']([^"']+)["']/g;
+/** Scan a UI source for src="…" references and pre-decode every referenced
+ *  image file. Called with `await` BEFORE the UI module loads (the module
+ *  loader and asset reader are synchronous); failures warn and fall back. */
+export async function warmUpImageDecoding(sourceText, baseDir, opts = {}) {
+    const pending = new Set();
+    let match;
+    SRC_ATTR.lastIndex = 0;
+    while ((match = SRC_ATTR.exec(sourceText)) !== null) {
+        const src = match[1];
+        if (!src || /^(data:|https?:|#)/.test(src))
+            continue;
+        const abs = path.isAbsolute(src) ? src : path.resolve(baseDir, src);
+        pending.add(abs);
+    }
+    await Promise.all([...pending].map(async (abs) => {
+        // Track the mtime up front so a failed decode is memoized under the key
+        // getCachedDecodedImage() looks up — the next warm-up of an unchanged
+        // file hits the null entry instead of re-attempting (and re-warning).
+        let mtimeMs = 0;
+        try {
+            if (!fs.existsSync(abs))
+                return;
+            const stat = fs.statSync(abs);
+            mtimeMs = stat.mtimeMs;
+            const key = cacheKey(abs, mtimeMs);
+            if (decodedCache.has(key))
+                return;
+            const buf = fs.readFileSync(abs);
+            const format = detectImageFormat(buf);
+            if (!format)
+                return; // legacy raw RGB565 dump — the raw reader handles it
+            const image = await decodeImageBuffer(buf, format, opts);
+            decodedCache.set(key, { mtimeMs, image });
+        }
+        catch (err) {
+            if (mtimeMs > 0) {
+                decodedCache.set(cacheKey(abs, mtimeMs), { mtimeMs, image: null });
+            }
+            console.warn(`[img] ${path.basename(abs)}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }));
+}
+/** Test hook: drop cached decodes. */
+export function resetImageDecodeCache() {
+    decodedCache.clear();
+}

package/dist/ui-engine/inline-parser.js

@@ -1,7 +1,7 @@
 /** Tags whose content participates in inline flow inside a text container.
  *  Bare text nodes between them flow too. Recognized as inline children of a
  *  text-effective node; absorbed into the parent's run list by the resolver. */
-export const INLINE_TAGS = new Set(["span", "a", "b", "strong", "i", "em", "u"]);
+export const INLINE_TAGS = new Set(["span", "a", "b", "strong", "i", "em", "u", "code", "kbd", "samp"]);
 /** Walk childNodes in document order, building an inline sequence.
  *
  *  Returns `undefined` when the element is NOT inline-bearing:

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

@@ -21,6 +21,25 @@ export interface LayoutEngine {
 }
 /** Static display:none predicate shared by layout engines and lowering. */
 export declare function isDisplayNone(node: StyledNode): boolean;
+/** A resolved CSS length: device pixels, a percentage of the parent
+ *  (resolved by the layout engine), or the auto keyword (margins). */
+export type CssDim = number | "auto" | `${number}%`;
+/** Parse a single CSS length to a layout dimension. px/bare numbers are device
+ *  pixels, rem/em resolve × 16 (root font size), percentages are preserved as
+ *  `${n}%` strings so flexbox can resolve them against the parent, and "auto"
+ *  passes through (auto margins absorb free space — `margin: 0 auto` centers). */
+export declare function cssDimValue(val: string | undefined): CssDim;
+/** Is this a set (non-default) dimension? Falsy 0 values are skipped when
+ *  applying to layout; percentages and "auto" always apply. */
+export declare function dimSet(d: CssDim): boolean;
+/** Size- and inset-safe variant of cssDimValue(): Yoga's typings exclude the
+ *  "auto" keyword for sizes/paddings/insets (only margins accept it), so fold
+ *  it to undefined — auto sizing is the engine default anyway. */
+export declare function cssSizeValue(val: string | undefined): number | `${number}%` | undefined;
+/** Expand a 1-4 value CSS box shorthand (padding/margin) to
+ *  [top, right, bottom, left] following the CSS TRBL rotation:
+ *  1 = all, 2 = V H, 3 = T H B, 4 = T R B L. */
+export declare function expandBoxShorthand(val: string | undefined): [CssDim, CssDim, CssDim, CssDim];
 /** Parse CSS aspect-ratio values: "16 / 9", "1/1", or "1.777". */
 export declare function parseAspectRatio(value: string | undefined): number | undefined;
 /** Measure a node's intrinsic size. Accounts for the Adafruit GFX font metrics

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

@@ -17,6 +17,56 @@ import { assetTextWidth, assetLineHeight } from "./font-assets.js";
 export function isDisplayNone(node) {
     return node.style.display?.trim().toLowerCase() === "none";
 }
+/** Parse a single CSS length to a layout dimension. px/bare numbers are device
+ *  pixels, rem/em resolve × 16 (root font size), percentages are preserved as
+ *  `${n}%` strings so flexbox can resolve them against the parent, and "auto"
+ *  passes through (auto margins absorb free space — `margin: 0 auto` centers). */
+export function cssDimValue(val) {
+    const v = (val ?? "").trim();
+    if (!v)
+        return 0;
+    if (/^auto$/i.test(v))
+        return "auto";
+    const remM = /^(-?[\d.]+)rem$/i.exec(v);
+    if (remM)
+        return Math.round(parseFloat(remM[1]) * 16);
+    const emM = /^(-?[\d.]+)em$/i.exec(v);
+    if (emM)
+        return Math.round(parseFloat(emM[1]) * 16);
+    const pctM = /^(-?[\d.]+)%$/.exec(v);
+    if (pctM)
+        return `${parseFloat(pctM[1])}%`;
+    const m = /^(-?[\d.]+)(?:px)?$/i.exec(v);
+    return m ? parseFloat(m[1]) : 0;
+}
+/** Is this a set (non-default) dimension? Falsy 0 values are skipped when
+ *  applying to layout; percentages and "auto" always apply. */
+export function dimSet(d) {
+    return d !== 0;
+}
+/** Size- and inset-safe variant of cssDimValue(): Yoga's typings exclude the
+ *  "auto" keyword for sizes/paddings/insets (only margins accept it), so fold
+ *  it to undefined — auto sizing is the engine default anyway. */
+export function cssSizeValue(val) {
+    const d = cssDimValue(val);
+    return d === "auto" ? undefined : d;
+}
+/** Expand a 1-4 value CSS box shorthand (padding/margin) to
+ *  [top, right, bottom, left] following the CSS TRBL rotation:
+ *  1 = all, 2 = V H, 3 = T H B, 4 = T R B L. */
+export function expandBoxShorthand(val) {
+    const parts = (val ?? "").trim().split(/\s+/).filter(Boolean);
+    const d = parts.map((p) => cssDimValue(p));
+    if (d.length <= 1) {
+        const v = d[0] ?? 0;
+        return [v, v, v, v];
+    }
+    if (d.length === 2)
+        return [d[0], d[1], d[0], d[1]];
+    if (d.length === 3)
+        return [d[0], d[1], d[2], d[1]];
+    return [d[0], d[1], d[2], d[3]];
+}
 /** Parse CSS aspect-ratio values: "16 / 9", "1/1", or "1.777". */
 export function parseAspectRatio(value) {
     const raw = value?.trim().toLowerCase();
@@ -148,12 +198,18 @@ export function measure(node, availableWidth, fontAssets = []) {
     const widthOf = (value) => assetTextWidth(stripInterp(value), node.style, fontAssets) ?? textWidthOf(stripInterp(value), advance);
     if (node.tag === "text" || node.tag === "button" || node.tag === "select") {
         if (node.tag === "select") {
-            // Size to the longest option, not the full comma-separated text
+            // Size to the widest option by RENDERED width, not the full
+            // comma-separated text and not character count — with a proportional
+            // font, equal-length options can differ in width ("Alpha" vs "Gamma"),
+            // and the wider one must fit without wrapping.
             const options = node.options && node.options.length > 0
                 ? node.options.map((option) => option.text)
                 : (node.text ?? "").split(",").map(s => s.trim()).filter(Boolean);
-            const longest = options.length > 0 ? options.reduce((a, b) => a.length >= b.length ? a : b) : "";
-            return { w: widthOf(applyTextTransform(longest, node)), h: lineHeightOf(node, charH) };
+            const widest = options.length > 0
+                ? options.reduce((a, b) => widthOf(applyTextTransform(a, node)) >= widthOf(applyTextTransform(b, node)) ? a : b)
+                : "";
+            // +14: the dropdown chevron the runtimes draw at the right end.
+            return { w: widthOf(applyTextTransform(widest, node)) + 14, h: lineHeightOf(node, charH) };
         }
         const text = applyTextTransform(stripInterp(node.text), node);
         const layout = layoutText(text, {

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

@@ -14,6 +14,12 @@ export interface UINodeModel {
     box: Box;
     bg: number;
     fg: number;
+    /** Checked-state color pair baked from :checked rules (RGB565; -1 unset).
+     *  Check/radio/select draw paths swap to it when the value flips — the
+     *  switch track, checkbox face, radio dot, and the select list's selected
+     *  row (shadcn data-[state=checked] theming). */
+    checkedBg: number;
+    checkedFg: number;
     kind: UINodeKindModel;
     text?: string;
     placeholder?: string;
@@ -73,6 +79,18 @@ export interface UINodeModel {
     nowrap: boolean;
     whiteSpaceMode: 0 | 1 | 2 | 3;
     visible: boolean;
+    /** HTML disabled attribute: blocks taps/keyboard and dims the control. */
+    disabled: boolean;
+    /** <drawer side>: 0=bottom 1=top 2=left 3=right; -1 = not a drawer. */
+    drawerSide: number;
+    /** <toast duration>: ms before auto-close (0 = manual close only). */
+    toastDuration: number;
+    /** Visibility-reflow axis (device): 0 none, 1 column, 2 row. */
+    flowAxis: number;
+    /** Visibility-reflow: main-axis gap between in-flow children (px, 0-255). */
+    flowGap: number;
+    /** Visibility-reflow flags: bit0 auto height, bit1 auto width, bit2 out-of-flow. */
+    flowFlags: number;
     opacity: number;
     clearColor: number;
     lastTextWidth: number;

package/dist/ui-engine/model.js

@@ -1,6 +1,6 @@
 import { effectiveDisplaySize } from "@typecad/cuttlefish/api/shared";
 import { deriveCapabilities } from "@typecad/cuttlefish/api/shared";
-import { resolveColorInternal } from "./color.js";
+import { resolveColorInternal, isTransparentColor } from "./color.js";
 import { parseAnimation } from "./css-parser.js";
 import { selectFontAssetForStyle, assetTextWidth, assetLineHeight } from "./font-assets.js";
 import { isDisplayNone } from "./layout-engine.js";
@@ -14,7 +14,7 @@ export const KEYFRAME_PROP_OPACITY = 4;
 export const KEYFRAME_PROP_TRANSFORM = 8;
 export const KEYFRAME_PROP_SIZE = 16;
 function nodeKind(tag) {
-    if (tag === "screen" || tag === "view")
+    if (tag === "screen" || tag === "view" || tag === "drawer" || tag === "dialog" || tag === "toast")
         return "fill";
     if (tag === "button")
         return "button";
@@ -121,7 +121,12 @@ function borderRadiusOf(style) {
     if (!style.borderRadius)
         return 0;
     const px = parseInt(style.borderRadius, 10);
-    return isNaN(px) ? 0 : px;
+    // Clamp at 0: kit recipes like `calc(var(--radius) - 2px)` go negative for
+    // 0px-radius themes (tweakcn's sharper exports) — a negative radius is both
+    // meaningless and a uint8 narrowing error in the emitted node table.
+    if (isNaN(px) || px < 0)
+        return 0;
+    return Math.min(255, px);
 }
 function paddingOf(style) {
     if (!style.padding)
@@ -449,7 +454,7 @@ function parseBoxShadow(style, format) {
         // Split into a numbers zone (offset/blur) and a color zone. The color
         // zone starts at the first # hex, rgb(, rgba(, or color name. css-tree
         // may strip spaces between values, so we can't rely on whitespace split.
-        const colorStart = part.search(/#|rgba?\(|\b(?:black|white|red|green|blue|gray|grey|yellow|orange|purple|pink|cyan|magenta|silver|gold|brown|tan|navy|teal|maroon|lime|olive|aqua|fuchsia|transparent)\b/i);
+        const colorStart = part.search(/#|rgba?\(|hsla?\(|\b(?:black|white|red|green|blue|gray|grey|yellow|orange|purple|pink|cyan|magenta|silver|gold|brown|tan|navy|teal|maroon|lime|olive|aqua|fuchsia|transparent)\b/i);
         const numZone = colorStart >= 0 ? part.slice(0, colorStart) : part;
         const colorZone = colorStart >= 0 ? part.slice(colorStart) : "";
         // Extract numbers from the numeric zone only (safe — no hex digits here).
@@ -640,11 +645,13 @@ function animationDeclOf(style) {
 function flatten(node, boxes, out, cursor, parentBg, parentIndex = -1, screenId = 0, parentZIndex = 0, parentOpacity = 100) {
     const index = cursor.i++;
     const box = boxes[index] ?? { x: 0, y: 0, w: 0, h: 0 };
-    const hasBg = !!node.style.background;
+    // `background: transparent` (or alpha-0) means NO fill — the parent's
+    // background shows through, matching browsers. (It used to paint black.)
+    const bgStr = node.style.background;
+    const bgIsGradient = bgStr !== undefined && bgStr.includes("linear-gradient");
+    const hasBg = bgStr !== undefined && !bgIsGradient ? !isTransparentColor(bgStr) : !!bgStr;
     // If background is a gradient, extract the first color stop as the base
     // clearColor string (avoids resolveColor choking on "linear-gradient(...)").
-    const bgStr = node.style.background;
-    const bgIsGradient = bgStr && bgStr.includes("linear-gradient");
     const bgBaseColor = bgIsGradient ? extractFirstGradientColor(bgStr) : bgStr;
     const clearColor = hasBg ? bgBaseColor : parentBg;
     const zIndex = Math.max(-32768, Math.min(32767, parentZIndex + zIndexOf(node.style)));
@@ -692,6 +699,10 @@ export function lowerUIToModel(root, boxes, colorFormat, display, fontAssets = [
         if (s.id)
             screenIdToIndex.set(s.id, i);
     });
+    // Raw flex direction per node index (pre-order, parents first) — the
+    // visibility-reflow flags use the parent's direction to decide cross-axis
+    // stretch vs content sizing (see the flowAxis/flowFlags IIFE below).
+    const flowDirByIndex = [];
     const nodes = flat.map(({ index, node, box, hasBg, clearColor, parentIndex, subtreeEnd, screenId, zIndex, effectiveOpacity }) => {
         // If background is a gradient, use the first stop as the base bg color
         // (the runtime draws the actual gradient per-row on top of this).
@@ -700,7 +711,19 @@ export function lowerUIToModel(root, boxes, colorFormat, display, fontAssets = [
             ? (grad ? grad.color1 : resolveColorInternal(node.style.background, colorFormat))
             : 0;
         const fg = node.style.color ? resolveColorInternal(node.style.color, colorFormat) : 0xffff;
-        const bColor = node.style.borderColor ? resolveColorInternal(node.style.borderColor, colorFormat) : 0;
+        // Checked-state pair from :checked rules (e.g. the kit's switch/checkbox/
+        // radio primary pair, the select list's accent pair). -1 = unset.
+        const checkedStyle = node.style.checked;
+        const checkedBg = checkedStyle && checkedStyle.background
+            ? resolveColorInternal(checkedStyle.background, colorFormat)
+            : -1;
+        const checkedFg = checkedStyle && checkedStyle.color
+            ? resolveColorInternal(checkedStyle.color, colorFormat)
+            : -1;
+        // Border color defaults to currentColor (the node's resolved text color),
+        // matching browsers — `border: 1px solid` on a white-on-dark theme gets a
+        // white border, not a hardcoded black one.
+        const bColor = node.style.borderColor ? resolveColorInternal(node.style.borderColor, colorFormat) : fg;
         const clear = clearColor ? resolveColorInternal(clearColor, colorFormat) : 0;
         const outline = outlineOf(node.style);
         const outlineColor = outline.color ? resolveColorInternal(outline.color, colorFormat) : fg;
@@ -792,6 +815,8 @@ export function lowerUIToModel(root, boxes, colorFormat, display, fontAssets = [
             box: baseTransformOffset.box,
             bg,
             fg,
+            checkedBg,
+            checkedFg,
             kind,
             text: applyTextTransform(node.text, node.style),
             placeholder: applyTextTransform(node.placeholder, node.style),
@@ -871,6 +896,49 @@ export function lowerUIToModel(root, boxes, colorFormat, display, fontAssets = [
             nowrap: wsMode === 1 || wsMode === 2,
             whiteSpaceMode: wsMode,
             visible: node.style.visibility !== "hidden" && node.style.visibility !== "collapse" && !isDisplayNone(node),
+            disabled: node.disabled === true,
+            drawerSide: (node.tag === "drawer" || node.tag === "dialog" || node.tag === "toast")
+                ? { bottom: 0, top: 1, left: 2, right: 3, center: 4 }[node.tag === "dialog" ? "center" : (node.drawerSide ?? "bottom")] ?? 0
+                : -1,
+            toastDuration: node.tag === "toast" ? (node.toastDuration ?? 2500) : 0,
+            // Visibility-reflow metadata: how this node's in-flow children stack, so
+            // the device runtime can re-stack them when a child's visibility changes
+            // (the preview re-layouts with yoga every frame; the device's boxes are
+            // baked at build time). The flex mapping mirrors yoga-layout.ts exactly;
+            // wrapped, reversed, or non-flex-start-justified containers opt out
+            // (axis 0) because a linear re-stack can't reproduce their layout.
+            ...(() => {
+                const s = node.style;
+                const fd = s.display === "flex" ? s.flexDirection : "column";
+                const outOfFlow = s.position === "absolute" || s.position === "fixed";
+                const gapPx = (v) => {
+                    const n = v === undefined ? 0 : parseFloat(v);
+                    return Number.isFinite(n) && n > 0 ? Math.min(255, Math.round(n)) : 0;
+                };
+                const dirAxis = (fd === "row" || fd === "row-reverse") ? 2 : 1;
+                flowDirByIndex[index] = dirAxis;
+                let axis = 0;
+                if ((node.children?.length ?? 0) > 0 && !outOfFlow &&
+                    fd !== "row-reverse" && fd !== "column-reverse" &&
+                    s.flexWrap !== "wrap" && s.flexWrap !== "wrap-reverse" &&
+                    (!s.justifyContent || s.justifyContent === "flex-start" || s.justifyContent === "normal")) {
+                    axis = dirAxis;
+                }
+                const gap = axis === 2 ? gapPx(s.rowGap) : gapPx(s.columnGap);
+                // Content-sized only when the size truly comes from the content: an
+                // explicit size, flex-grow space, a flex-basis, or cross-axis
+                // stretch (a child of a row parent stretches its height; of a column
+                // parent its width) all derive the dimension from elsewhere. Getting
+                // this wrong let the reflow resize a flex-grown scroll body to its
+                // collapsed content — contentHeight == box.h, nothing scrollable.
+                const grown = s.flexGrow !== undefined && parseFloat(String(s.flexGrow)) > 0;
+                const basisSet = s.flexBasis !== undefined && s.flexBasis !== "auto";
+                const parentDir = parentIndex >= 0 ? (flowDirByIndex[parentIndex] ?? 1) : 0;
+                const parentDerived = grown || basisSet || parentDir === 0;
+                const autoH = !parentDerived && parentDir !== 2 && (s.height === undefined || s.height === "auto");
+                const autoW = !parentDerived && parentDir !== 1 && (s.width === undefined || s.width === "auto");
+                return { flowAxis: axis, flowGap: gap, flowFlags: (autoH ? 1 : 0) | (autoW ? 2 : 0) | (outOfFlow ? 4 : 0) };
+            })(),
             opacity: effectiveOpacity,
             clearColor: clear,
             lastTextWidth: 0,

package/dist/ui-engine/runtime-header/blend-bodies.js

@@ -3,21 +3,40 @@
 // See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
 export function emitBlendBodies() {
     return `
+// Blend LUTs (LVGL draw-unit trick, memory-frugal variant): two 256-entry
+// per-channel tables rebuilt only when the opacity level CHANGES. Blends
+// typically run per-pixel at a fixed opacity (skeleton pulse frame, one
+// shadow pass, a glyph's coverage step), so the table amortizes to one
+// rebuild per pass and every pixel becomes three array lookups instead of
+// three multiply-divide rounds. Total cost: 513 bytes of static RAM.
+static uint8_t __ui_blend_lut_fg[256];
+static uint8_t __ui_blend_lut_bg[256];
+static uint8_t __ui_blend_lut_opacity = 255; // 255 = never built (valid range 0..100)
+static inline void ui_blend_lut_build(uint8_t opacity) {
+  if (__ui_blend_lut_opacity == opacity) return;
+  for (int16_t v = 0; v < 256; v++) {
+    __ui_blend_lut_fg[v] = static_cast<uint8_t>((v * opacity) / 100);
+    __ui_blend_lut_bg[v] = static_cast<uint8_t>((v * (100 - opacity)) / 100);
+  }
+  __ui_blend_lut_opacity = opacity;
+}
+
 static inline uint16_t ui_blend565(uint16_t fg, uint16_t bg, uint8_t opacity) {
   if (opacity >= 100) return fg;
   if (opacity == 0) return bg;
-  // Blend in 888 internally for higher precision: unpack 565→888 (replicating
+  ui_blend_lut_build(opacity);
+  // Blend in 888 internally for higher precision: unpack 565->888 (replicating
   // high bits), blend at 8-bit, then re-quantize to 565. This produces smoother
-  // intermediate values for AA text edges, opacity, shadows, and gradients —
+  // intermediate values for AA text edges, opacity, shadows, and gradients --
   // the 565-channel blend (32 red levels) was too coarse and showed banding.
   uint8_t fr = (fg >> 11) & 0x1F, fg5 = (fg >> 5) & 0x3F, fb = fg & 0x1F;
   uint8_t br = (bg >> 11) & 0x1F, bg5 = (bg >> 5) & 0x3F, bb = bg & 0x1F;
-  // Unpack to 8-bit (5-bit → 8-bit: (v << 3) | (v >> 2)).
+  // Unpack to 8-bit (5-bit -> 8-bit: (v << 3) | (v >> 2)).
   uint16_t fr8 = (fr << 3) | (fr >> 2), fg8 = (fg5 << 2) | (fg5 >> 4), fb8 = (fb << 3) | (fb >> 2);
   uint16_t br8 = (br << 3) | (br >> 2), bg8 = (bg5 << 2) | (bg5 >> 4), bb8 = (bb << 3) | (bb >> 2);
-  uint16_t r = static_cast<uint16_t>((fr8 * opacity + br8 * (100 - opacity)) / 100);
-  uint16_t g = static_cast<uint16_t>((fg8 * opacity + bg8 * (100 - opacity)) / 100);
-  uint16_t b = static_cast<uint16_t>((fb8 * opacity + bb8 * (100 - opacity)) / 100);
+  uint16_t r = static_cast<uint16_t>(__ui_blend_lut_fg[fr8] + __ui_blend_lut_bg[br8]);
+  uint16_t g = static_cast<uint16_t>(__ui_blend_lut_fg[fg8] + __ui_blend_lut_bg[bg8]);
+  uint16_t b = static_cast<uint16_t>(__ui_blend_lut_fg[fb8] + __ui_blend_lut_bg[bb8]);
   return ((r >> 3) << 11) | ((g >> 2) << 5) | (b >> 3);
 }
 
@@ -28,11 +47,12 @@ static inline uint16_t ui_blend565(uint16_t fg, uint16_t bg, uint8_t opacity) {
 static inline uint32_t ui_blend888(uint32_t fg, uint32_t bg, uint8_t opacity) {
   if (opacity >= 100) return fg;
   if (opacity == 0) return bg;
+  ui_blend_lut_build(opacity);
   uint8_t fr = (fg >> 16) & 0xff, fg8 = (fg >> 8) & 0xff, fb = fg & 0xff;
   uint8_t br = (bg >> 16) & 0xff, bg8 = (bg >> 8) & 0xff, bb = bg & 0xff;
-  uint8_t r = (fr * opacity + br * (100 - opacity)) / 100;
-  uint8_t g = (fg8 * opacity + bg8 * (100 - opacity)) / 100;
-  uint8_t b = (fb * opacity + bb * (100 - opacity)) / 100;
+  uint8_t r = static_cast<uint8_t>(__ui_blend_lut_fg[fr] + __ui_blend_lut_bg[br]);
+  uint8_t g = static_cast<uint8_t>(__ui_blend_lut_fg[fg8] + __ui_blend_lut_bg[bg8]);
+  uint8_t b = static_cast<uint8_t>(__ui_blend_lut_fg[fb] + __ui_blend_lut_bg[bb]);
   return (static_cast<uint32_t>(r) << 16) | (static_cast<uint32_t>(g) << 8) | b;
 }
 `;

package/dist/ui-engine/runtime-header/canvas-helpers.js

@@ -29,13 +29,16 @@ static inline CuttlefishCanvas16* ui_create_canvas_best(int16_t w, int16_t h) {
       if (!psram_logged) {
         psram_logged = 1;
 #if defined(ESP32) && defined(ARDUINO)
-        Serial.printf("[psram] canvas %dx%d allocated in PSRAM (free=%u)\n", w, h, ESP.getFreePsram());
+        Serial.printf("[psram] canvas %dx%d allocated in PSRAM (free=%u)\\n", w, h, ESP.getFreePsram());
 #else
-        printf("[psram] canvas %dx%d allocated in PSRAM\n", w, h);
+        printf("[psram] canvas %dx%d allocated in PSRAM\\n", w, h);
 #endif
       }
       return c;
     }
+    // Object allocated but its pixel buffer failed — free the object before
+    // falling through to SRAM so it isn't leaked.
+    display_deleteCanvas(c);
     // PSRAM allocation failed (rare — fragmented PSRAM) → fall through to SRAM.
   }
 #endif