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

package/dist/ui-engine/font-assets.d.ts

@@ -54,5 +54,5 @@ export declare function assetTextWidth(text: string, style: CSSProperty, fontAss
  *  title spilling past its header's padded box). Mirrors the preview's
  *  textHeight(size, fontFace) = asset.lineHeight ?? gfx.textHeight(size). */
 export declare function assetLineHeight(style: CSSProperty, fontAssets: UIFontAssetModel[]): number | undefined;
-export declare function buildUIFontAssets(root: StyledNode, fontFaces: CSSFontFace[], baseDir: string): UIFontAssetModel[];
-export declare function planUIFontAssets(root: StyledNode, fontFaces: CSSFontFace[], baseDir: string): UIFontAssetPlan[];
+export declare function buildUIFontAssets(root: StyledNode, fontFaces: CSSFontFace[], baseDir: string, dynamicNodeIds?: Set<string>): UIFontAssetModel[];
+export declare function planUIFontAssets(root: StyledNode, fontFaces: CSSFontFace[], baseDir: string, dynamicNodeIds?: Set<string>): UIFontAssetPlan[];

package/dist/ui-engine/font-assets.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import opentype from "opentype.js";
 import { getDisplayProfile } from "@typecad/cuttlefish/stores/display-profile-store";
-const FALLBACK_CHARS = " 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz.,:;!?+-*/=%()[]{}<>_#@&";
+const FALLBACK_CHARS = " 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz.,:;!?+-*/=%()[]{}<>_#@&^~$'|";
 const SUPERSAMPLE = 4;
 export function normalizeFontFamily(value) {
     if (!value)
@@ -110,8 +110,8 @@ export function assetLineHeight(style, fontAssets) {
         return undefined;
     return asset.lineHeight;
 }
-export function buildUIFontAssets(root, fontFaces, baseDir) {
-    const plans = planUIFontAssets(root, fontFaces, baseDir);
+export function buildUIFontAssets(root, fontFaces, baseDir, dynamicNodeIds) {
+    const plans = planUIFontAssets(root, fontFaces, baseDir, dynamicNodeIds);
     const parsedFonts = new Map();
     const assets = [];
     let id = 1;
@@ -137,13 +137,21 @@ export function buildUIFontAssets(root, fontFaces, baseDir) {
     }
     return assets;
 }
-export function planUIFontAssets(root, fontFaces, baseDir) {
+export function planUIFontAssets(root, fontFaces, baseDir, dynamicNodeIds) {
     if (fontFaces.length === 0)
         return [];
     const requests = new Map();
     const collect = (node) => {
         const face = selectFontFaceForStyle(fontFaces, node.style);
         if (face) {
+            // Runtime-dynamic text renders strings the static template can't
+            // predict — widen those faces to the fallback charset so bound values
+            // ("Gamma" against a subset planned from authored "mode: alpha") don't
+            // drop glyphs. Dynamic = ui.bind(..., 'text') targets (via
+            // dynamicNodeIds), {expr} interpolations, and bind:text attributes.
+            const dynamicText = (node.id !== undefined && dynamicNodeIds?.has(node.id)) ||
+                node.hasInterpolation === true ||
+                node.bind?.text !== undefined;
             const px = fontPxOf(node.style);
             const sourcePath = resolveFontPath(face.src, baseDir);
             const fontWeight = normalizeFontWeight(face.fontWeight ?? node.style.fontWeight);
@@ -162,7 +170,16 @@ export function planUIFontAssets(root, fontFaces, baseDir) {
                 };
                 requests.set(key, request);
             }
-            if (fontSubsetOf(node.style) === "fallback" && request.subset !== "fallback") {
+            if ((fontSubsetOf(node.style) === "fallback" || dynamicText) && request.subset !== "fallback") {
+                request.subset = "fallback";
+                addText(request.chars, FALLBACK_CHARS);
+            }
+            // Virtualized lists render RUNTIME text — item expressions produce
+            // strings the static template can't predict (the same reason `{expr}`
+            // interpolations add digits). Without this the list's face only carries
+            // glyphs from unrelated static text and items render blanks (e.g. a
+            // subset with '0' but no '1'-'9' draws "Item 10" as "Item  0").
+            if (node.tag === "list" && request.subset !== "fallback") {
                 request.subset = "fallback";
                 addText(request.chars, FALLBACK_CHARS);
             }

package/dist/ui-engine/html-parser.d.ts

@@ -45,6 +45,10 @@ export interface UIElementNode {
     canvasH?: number;
     /** Disabled state */
     disabled?: boolean;
+    /** <drawer side="bottom|top|left|right"> — the edge the panel slides from. */
+    drawerSide?: string;
+    /** <toast duration="2500"> — ms a toast stays open before auto-closing. */
+    toastDuration?: number;
     children: UIElementNode[];
     /** Ordered inline content sequence (text/element/break items). Present only
      *  for text nodes with mixed inline children; absent for plain-text nodes. */

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

@@ -13,7 +13,23 @@
 // ---------------------------------------------------------------------------
 import { parseHTML } from "linkedom";
 import { collectInlineSequence, INLINE_TAGS } from "./inline-parser.js";
-const SUPPORTED_TAGS = new Set(["screen", "text", "button", "view", "check", "select", "option", "label", "radio", "progress", "range", "input", "keyboard", "row", "key", "style", "a", "img", "list", "canvas", "br"]);
+const SUPPORTED_TAGS = new Set(["screen", "text", "button", "view", "check", "select", "option", "label", "radio", "progress", "range", "input", "keyboard", "row", "key", "style", "a", "img", "list", "canvas", "br", "drawer", "dialog", "toast"]);
+/** Document-furniture tags that never render. Skipped silently (unlike unknown
+ *  tags, which fall back to generic containers with a warning). */
+const METADATA_TAGS = new Set(["link", "meta", "title", "head", "script", "source", "track", "col", "colgroup"]);
+/** Web elements that cannot work on microcontroller targets (vector graphics,
+ *  media, embedded browsing). Their subtree still renders as generic containers
+ *  — content is never dropped — but the diagnostic says WHY, with the native
+ *  alternative, instead of a generic unknown-tag warning. */
+const UNSUPPORTED_TAGS = {
+    svg: "vector graphics have no renderer — draw via <canvas> or export a bitmap for <img>",
+    video: "there is no video pipeline on MCU targets",
+    audio: "there is no audio pipeline on MCU targets",
+    iframe: "there is no browser engine to embed",
+    embed: "there is no plugin/content engine on MCU targets",
+    object: "there is no plugin/content engine on MCU targets",
+    picture: "art-direction source selection is unsupported — a child <img> still renders",
+};
 /** HTML tag aliases — common HTML elements remapped to internal primitives.
  *  Semantic block containers -> view; inline/heading text tags -> text.
  *  Applied before the SUPPORTED_TAGS check so authors can write familiar HTML. */
@@ -21,12 +37,38 @@ const TAG_REMAP = {
     // Block-level containers -> view (flexbox/positioning surface)
     body: "view", div: "view", header: "view", footer: "view", nav: "view",
     main: "view", section: "view", article: "view", aside: "view",
+    // Forms are layout-transparent here (no submission model) — the wrapper is
+    // just a container; children render normally.
+    form: "view", fieldset: "view",
+    // Lists: the container is a plain view; <li> gets a marker prefix below.
+    ul: "view", ol: "view", li: "text",
+    // Definition lists: dt = bold term, dd = indented description (UA rules).
+    dl: "view", dt: "text", dd: "text",
+    // Tables: equal-width flex approximation — tr is a row, td/th are stretched
+    // cells (UA rules); thead/tbody/tfoot are plain row groups. Approximation
+    // surfaced via the html-table-approximation diagnostic.
+    table: "view", tr: "view", td: "text", th: "text",
+    thead: "view", tbody: "view", tfoot: "view", caption: "text",
+    // Horizontal rule -> 1px rule (styled by the UA stylesheet).
+    hr: "view",
     // Inline/heading text -> text
-    span: "text", p: "text",
+    span: "text", p: "text", small: "text", output: "text",
     h1: "text", h2: "text", h3: "text", h4: "text", h5: "text", h6: "text",
     // Styling tags -> text (inline; resolver applies bold/italic/underline defaults
     // and absorbs them into the parent's run list).
     b: "text", strong: "text", i: "text", em: "text", u: "text",
+    // Code phrase groups -> text; the UA stylesheet gives them the mono family.
+    code: "text", kbd: "text", samp: "text", pre: "text",
+    // Meter is the same bar primitive as progress (min/max/value).
+    meter: "progress",
+    // Multiline text area -> single-line input (single-line OSK at runtime).
+    textarea: "input",
+};
+/** <input type="..."> spellings that remap to the dedicated control tags. */
+const INPUT_TYPE_REMAP = {
+    checkbox: "check",
+    radio: "radio",
+    range: "range",
 };
 /** Extract <style>...</style> block contents from HTML source.
  *  Returns the concatenated CSS text (empty if no style blocks). */
@@ -37,10 +79,23 @@ export function extractStyleBlocks(src) {
 export function parseHtml(src, diagnostics) {
     return parseAllScreens(src, diagnostics)[0];
 }
+// HTML-spec parsers treat `<view .../>` as an OPEN tag for non-void elements
+// (XML-style self-closing is not HTML), so JSX-habit markup silently nests:
+// `<view class="a"/><view class="b"/>` puts b INSIDE a. Expand every
+// self-closing non-void tag to an explicit pair before parsing. Void
+// elements (img, hr, input, ...) already parse correctly and are skipped.
+const VOID_TAGS = new Set(["area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "param", "source", "track", "wbr"]);
+function expandSelfClosingTags(src) {
+    return src.replace(/<([a-zA-Z][\w-]*)((?:[^>"']|"[^"]*"|'[^']*')*?)\/>/g, (m, tag, attrs) => {
+        if (VOID_TAGS.has(tag.toLowerCase()))
+            return m;
+        return `<${tag}${attrs}></${tag}>`;
+    });
+}
 /** Parse all <screen> roots from HTML. Returns one tree per screen.
  *  Used for multi-screen navigation (<a href="#screenId">). */
 export function parseAllScreens(src, diagnostics) {
-    const withoutComments = src.replace(/<!--[\s\S]*?-->/g, "").replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "");
+    const withoutComments = expandSelfClosingTags(src.replace(/<!--[\s\S]*?-->/g, "").replace(/<style[^>]*>[\s\S]*?<\/style>/gi, ""));
     const wrapped = `<div id="__root__">${withoutComments}</div>`;
     const { document } = parseHTML(wrapped);
     const root = document.getElementById("__root__");
@@ -55,7 +110,7 @@ export function parseAllScreens(src, diagnostics) {
 }
 /** Parse HTML, returning both the <screen> tree and any <keyboard> templates. */
 export function parseHtmlWithKeyboards(src, diagnostics) {
-    const withoutComments = src.replace(/<!--[\s\S]*?-->/g, "").replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "");
+    const withoutComments = expandSelfClosingTags(src.replace(/<!--[\s\S]*?-->/g, "").replace(/<style[^>]*>[\s\S]*?<\/style>/gi, ""));
     const wrapped = `<div id="__root__">${withoutComments}</div>`;
     const { document } = parseHTML(wrapped);
     const root = document.getElementById("__root__");
@@ -127,10 +182,52 @@ function domToUIElementNode(el, diagnostics) {
     // <label> and <a> are treated as <text> internally; HTML aliases
     // (div/header/span/p/h1-h6/...) remap to view or text.
     const remapped = TAG_REMAP[tag];
-    const effectiveTag = remapped ? remapped
+    let effectiveTag = remapped ? remapped
         : (tag === "label" || tag === "a") ? "text" : tag;
+    // <input type="checkbox|radio|range"> — the spelling web authors type  // reflexively — remaps to the dedicated control tags with identical behavior.
+    // Other non-text types (email, date, ...) have no MCU counterpart: they
+    // normalize to a single-line text input with a warning.
+    if (tag === "input") {
+        const inputType = (el.getAttribute("type") || "text").toLowerCase();
+        const remap = INPUT_TYPE_REMAP[inputType];
+        if (remap) {
+            effectiveTag = remap;
+        }
+        else if (inputType !== "text" && inputType !== "number") {
+            diagnostics?.push({
+                severity: "warning",
+                message: `<input type="${inputType}"> has no embedded equivalent — treated as a single-line text input.`,
+                hint: `Supported types: text, number, checkbox, radio, range.`,
+                code: "html-input-type-unsupported",
+                source: "input",
+            });
+        }
+    }
     if (!SUPPORTED_TAGS.has(effectiveTag)) {
-        throw new Error(`Unsupported tag <${tag}> — supported: ${[...SUPPORTED_TAGS].join(", ")}`);
+        // Web behavior: unknown elements are generic boxes (this is why custom
+        // elements work in HTML). Content is NEVER dropped — a text-only leaf
+        // becomes a text node, anything with element children a container.
+        const hasElementChildren = Array.from(el.children).some((c) => !METADATA_TAGS.has(c.tagName.toLowerCase()));
+        effectiveTag = hasElementChildren ? "view" : "text";
+        const knownUnsupported = UNSUPPORTED_TAGS[tag];
+        if (knownUnsupported) {
+            diagnostics?.push({
+                severity: "warning",
+                message: `<${tag}> is not supported on microcontroller targets — rendered as a generic container.`,
+                hint: `${knownUnsupported}.`,
+                code: "unsupported-html-tag",
+                source: tag,
+            });
+        }
+        else {
+            diagnostics?.push({
+                severity: "warning",
+                message: `Unknown HTML tag <${tag}> — rendered as a generic ${hasElementChildren ? "container" : "text"} element.`,
+                hint: `Supported tags: ${[...SUPPORTED_TAGS].sort().join(", ")}.`,
+                code: "unknown-html-tag",
+                source: tag,
+            });
+        }
     }
     const id = el.getAttribute("id") || undefined;
     const refAttr = el.getAttribute("ref") || undefined;
@@ -141,16 +238,27 @@ function domToUIElementNode(el, diagnostics) {
     const checkedAttr = el.hasAttribute("checked");
     const minAttr = el.getAttribute("min") || undefined;
     const maxAttr = el.getAttribute("max") || undefined;
-    const typeAttr = tag === "input"
+    // Text-input specifics only apply to the text/number input (not to
+    // checkbox/radio/range inputs remapped above, and not to <textarea>).
+    const isTextInput = tag === "input" && effectiveTag === "input";
+    if (tag === "textarea") {
+        diagnostics?.push({
+            severity: "warning",
+            message: `<textarea> renders as a single-line <input> (the on-screen keyboard is single-line).`,
+            code: "html-textarea-single-line",
+            source: "textarea",
+        });
+    }
+    const typeAttr = isTextInput
         ? (el.getAttribute("type") === "number" ? "number" : "text")
         : undefined;
-    const placeholderAttr = el.getAttribute("placeholder") || undefined;
+    const placeholderAttr = isTextInput ? (el.getAttribute("placeholder") || undefined) : undefined;
     const maxlengthAttr = el.getAttribute("maxlength");
     // <input> defaults maxlength to 16 when absent or unparseable.
-    const maxlengthNum = tag === "input"
+    const maxlengthNum = isTextInput
         ? (maxlengthAttr ? (parseInt(maxlengthAttr, 10) || 16) : 16)
         : undefined;
-    const keyboardAttr = el.getAttribute("keyboard") || undefined;
+    const keyboardAttr = isTextInput ? (el.getAttribute("keyboard") || undefined) : undefined;
     const hiddenAttr = el.hasAttribute("hidden");
     const inlineStyleAttr = el.getAttribute("style") || undefined;
     const hrefAttr = (tag === "a" || tag === "button") ? (el.getAttribute("href") || undefined) : undefined;
@@ -228,21 +336,27 @@ function domToUIElementNode(el, diagnostics) {
     }
     // Text content: only direct text, not children's text.
     let text;
+    // Element children that become nodes: everything except document metadata
+    // (skipped silently) and option/br (consumed by the select/text paths).
+    // Unknown tags are KEPT — their own recursive call renders them as generic
+    // containers, so no subtree is ever dropped for being unrecognized.
     const childElements = Array.from(el.children).filter((c) => {
         const ct = c.tagName.toLowerCase();
-        // Accept native tags and HTML aliases (div/span/p/h1-h6/...) that remap later.
-        const accepted = SUPPORTED_TAGS.has(ct) || TAG_REMAP[ct] !== undefined;
-        if (!accepted && ct !== "option" && ct !== "br" && diagnostics) {
-            diagnostics.push({
-                severity: "warning",
-                message: `Unknown HTML tag <${ct}> — ignored.`,
-                hint: `Supported tags: ${[...SUPPORTED_TAGS].sort().join(", ")}.`,
-                code: "unknown-html-tag",
-                source: ct,
-            });
-        }
-        return accepted && ct !== "option" && ct !== "br";
+        if (METADATA_TAGS.has(ct))
+            return false;
+        return ct !== "option" && ct !== "br";
     });
+    // Non-empty direct text runs (trimmed). Runs that sit next to element
+    // children become anonymous text children below — the CSS anonymous-box
+    // model: a container's stray text is never silently dropped.
+    const directTextRuns = [];
+    for (const child of Array.from(el.childNodes)) {
+        if (child.nodeType === 3) {
+            const t = (child.textContent ?? "").trim();
+            if (t)
+                directTextRuns.push(t);
+        }
+    }
     // Inline-bearing text nodes collect an ordered inline sequence instead of a
     // single text string. Only effective-tag "text" can be inline-bearing;
     // collectInlineSequence returns undefined for plain text or block-child nodes.
@@ -250,6 +364,9 @@ function domToUIElementNode(el, diagnostics) {
     if (effectiveTag === "text") {
         inline = collectInlineSequence(el, diagnostics ?? []);
     }
+    // A text tag whose inline collection failed (block child inside <p>/<text>)
+    // keeps its tag — selectors must keep matching it — and its stray text is
+    // preserved as anonymous text children below (the anonymous-block-box model).
     // Text content: only direct text, and only when there's no inline sequence
     // (inline content is captured above; the plain-text path is unchanged).
     let hasInterpolation = false;
@@ -272,13 +389,111 @@ function domToUIElementNode(el, diagnostics) {
             hasInterpolation = /\{[^{}]+\}/.test(tc);
         }
     }
+    // <table> approximation note: rows are flex rows of equal-width stretched
+    // cells. Visible, not silent — see the UA stylesheet for the styling.
+    if (tag === "table") {
+        diagnostics?.push({
+            severity: "info",
+            message: `<table> renders as equal-width flex columns (tr = row, td/th = cells) — no auto column sizing, colspan, or rowspan.`,
+            hint: `Set explicit widths or flex-grow on cells for custom column sizes.`,
+            code: "html-table-approximation",
+            source: "table",
+        });
+    }
+    // colspan/rowspan have no equal-width-flex equivalent — warn when present.
+    if (tag === "td" || tag === "th") {
+        for (const span of ["colspan", "rowspan"]) {
+            if (el.hasAttribute(span)) {
+                diagnostics?.push({
+                    severity: "warning",
+                    message: `<${tag}> ${span} is not supported — the cell renders as a single equal-width column/row.`,
+                    hint: `Split the content across cells, or restructure with a flex row.`,
+                    code: "html-table-span-unsupported",
+                    source: tag,
+                });
+            }
+        }
+    }
+    // <li> list markers: text-only items get a prefix ("• " for <ul>, "N. " for
+    // <ol>) so plain lists read correctly with zero styling. Items with block
+    // children render as containers without a marker (style those yourself).
+    if (tag === "li" && (text || inline)) {
+        const parentTag = el.parentElement?.tagName?.toLowerCase();
+        let marker = "• ";
+        if (parentTag === "ol") {
+            let n = 0;
+            for (const sib of Array.from(el.parentElement.children)) {
+                if (sib === el)
+                    break;
+                if (sib.tagName.toLowerCase() === "li")
+                    n++;
+            }
+            marker = `${n + 1}. `;
+        }
+        if (text)
+            text = marker + text;
+        if (inline)
+            inline = [{ kind: "text", text: marker }, ...inline];
+    }
     const remappedFrom = (remapped || tag === "label" || tag === "a") && tag !== effectiveTag ? tag : undefined;
-    const node = { tag: effectiveTag, origTag: remappedFrom, id, classes, text, value: valueAttr, name: nameAttr, checked: checkedAttr, min: minAttr, max: maxAttr, type: typeAttr, placeholder: placeholderAttr, maxlength: maxlengthNum, keyboard: keyboardAttr, hidden: hiddenAttr, inlineStyle: inlineStyleAttr, href: hrefAttr, src: srcAttr, imgWidth: imgWidthAttr || undefined, imgHeight: imgHeightAttr || undefined, itemHeight: itemHeightAttr, canvasW: canvasWAttr, canvasH: canvasHAttr, disabled: disabledAttr, inline, hasInterpolation, events: hasEvents ? events : undefined, bind: hasBind ? bind : undefined, ref: refAttr, children: [] };
-    for (const child of childElements) {
-        // Inline children are absorbed into `inline`; don't also emit them as nodes.
-        if (inline && INLINE_TAGS.has(child.tagName.toLowerCase()))
+    const drawerSideAttr = tag === "dialog"
+        ? "center"
+        : (tag === "drawer" || tag === "toast") ? (el.getAttribute("side") ?? "bottom").toLowerCase() : undefined;
+    const toastDurationAttr = tag === "toast"
+        ? Math.max(500, parseInt(el.getAttribute("duration") || "2500", 10) || 2500)
+        : undefined;
+    const node = { tag: effectiveTag, origTag: remappedFrom, id, classes, text, value: valueAttr, name: nameAttr, drawerSide: drawerSideAttr, toastDuration: toastDurationAttr, checked: checkedAttr, min: minAttr, max: maxAttr, type: typeAttr, placeholder: placeholderAttr, maxlength: maxlengthNum, keyboard: keyboardAttr, hidden: hiddenAttr, inlineStyle: inlineStyleAttr, href: hrefAttr, src: srcAttr, imgWidth: imgWidthAttr || undefined, imgHeight: imgHeightAttr || undefined, itemHeight: itemHeightAttr, canvasW: canvasWAttr, canvasH: canvasHAttr, disabled: disabledAttr, inline, hasInterpolation, events: hasEvents ? events : undefined, bind: hasBind ? bind : undefined, ref: refAttr, children: [] };
+    // Anonymous inline wrap: stray text next to ONLY-inline element children
+    // flows as one text line (CSS anonymous inline boxes) instead of stacking
+    // "Total:" above the <b>3</b> run. Requires stray text to trigger — inline
+    // elements alone keep the legacy stacked behavior (deliberate chip layout).
+    if (!inline && childElements.length > 0 && directTextRuns.length > 0) {
+        const allInline = childElements.every((c) => INLINE_TAGS.has(c.tagName.toLowerCase()));
+        if (allInline) {
+            const seq = collectInlineSequence(el, diagnostics ?? []);
+            if (seq) {
+                node.children.push({
+                    tag: "text",
+                    classes: [],
+                    inline: seq,
+                    hasInterpolation: directTextRuns.some((t) => /\{[^{}]+\}/.test(t)),
+                    children: [],
+                });
+                return node;
+            }
+        }
+    }
+    // Children in document order, interleaving anonymous text children for
+    // stray text runs (never dropped — the CSS anonymous-block-box model).
+    // Inline children already absorbed by an inline[] sequence are skipped.
+    let textBuffer = "";
+    const flushText = () => {
+        const t = textBuffer.trim();
+        textBuffer = "";
+        if (!t)
+            return;
+        node.children.push({
+            tag: "text",
+            classes: [],
+            text: t,
+            hasInterpolation: /\{[^{}]+\}/.test(t),
+            children: [],
+        });
+    };
+    for (const child of Array.from(el.childNodes)) {
+        if (child.nodeType === 3) {
+            if (childElements.length > 0 && !inline)
+                textBuffer += child.textContent ?? "";
+            continue;
+        }
+        const childTag = child.tagName?.toLowerCase();
+        if (!childTag || METADATA_TAGS.has(childTag) || childTag === "option" || childTag === "br")
+            continue;
+        if (inline && INLINE_TAGS.has(childTag))
             continue;
+        flushText();
         node.children.push(domToUIElementNode(child, diagnostics));
     }
+    flushText();
     return node;
 }

package/dist/ui-engine/image-assets.d.ts

@@ -16,6 +16,13 @@ export interface LoadedUIImageAssets {
 }
 export declare function loadImageAssets(roots: StyledNode | StyledNode[], htmlDir: string): LoadedUIImageAssets;
 export declare function emitImageTables(assets: UIImageAsset[], colorFormat?: ColorFormat): string;
-/** Read a raw RGB565 binary file and return a padded UIImageAsset. */
+/** Give <img> nodes without explicit width/height attributes their decoded
+ *  image's natural size, so the layout box matches the asset. Must run
+ *  BEFORE layout (both pipelines arrange first, then load assets); explicit
+ *  author attrs keep controlling the layout box, with object-fit scaling. */
+export declare function applyDecodedImageSizes(roots: StyledNode | StyledNode[], htmlDir: string): void;
+/** Read a raw RGB565 binary file and return a padded UIImageAsset. A decoded
+ *  (converted) image in the warm-up cache wins — natural size, converted
+ *  pixels. */
 export declare function readRgb565Image(srcPath: string, htmlDir: string, id: string, width: number, height: number): UIImageAsset | null;
 export {};

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

@@ -4,6 +4,7 @@
 // ---------------------------------------------------------------------------
 import fs from "node:fs";
 import path from "node:path";
+import { getCachedDecodedImage } from "./image-decode.js";
 function sanitizeCppIdentifier(value, fallback) {
     const sanitized = value.replace(/[^a-zA-Z0-9_]/g, "_");
     const base = sanitized.length > 0 ? sanitized : fallback;
@@ -39,9 +40,14 @@ export function loadImageAssets(roots, htmlDir) {
     const walk = (node) => {
         const src = node.src;
         if (src && node.id) {
+            const abs = path.isAbsolute(src) ? src : path.resolve(htmlDir, src);
+            const decoded = getCachedDecodedImage(abs);
             const width = imageNaturalWidth(node);
             const height = imageNaturalHeight(node);
-            const key = imageAssetKey(src, htmlDir, width, height);
+            // Decoded (converted) assets are keyed by file alone — their size is
+            // the image's natural size, not the node's attrs. Raw .img dumps keep
+            // the (src, dims) key — the dims ARE the asset geometry there.
+            const key = decoded ? `decoded:\0${abs}` : imageAssetKey(src, htmlDir, width, height);
             let assetIdx = keyToAssetIndex.get(key);
             if (assetIdx === undefined) {
                 const assetId = uniqueAssetId(node.id, assets.length, usedIds);
@@ -101,11 +107,38 @@ export function emitImageTables(assets, colorFormat = "rgb565") {
     lines.push(`const uint16_t __ui_image_count = ${assets.length};`);
     return lines.join("\n");
 }
-/** Read a raw RGB565 binary file and return a padded UIImageAsset. */
+/** Give <img> nodes without explicit width/height attributes their decoded
+ *  image's natural size, so the layout box matches the asset. Must run
+ *  BEFORE layout (both pipelines arrange first, then load assets); explicit
+ *  author attrs keep controlling the layout box, with object-fit scaling. */
+export function applyDecodedImageSizes(roots, htmlDir) {
+    const walk = (node) => {
+        const src = node.src;
+        if (src && node.imgWidth === undefined && node.imgHeight === undefined) {
+            const abs = path.isAbsolute(src) ? src : path.resolve(htmlDir, src);
+            const decoded = getCachedDecodedImage(abs);
+            if (decoded) {
+                node.imgWidth = decoded.width;
+                node.imgHeight = decoded.height;
+            }
+        }
+        node.children.forEach(walk);
+    };
+    for (const root of Array.isArray(roots) ? roots : [roots]) {
+        walk(root);
+    }
+}
+/** Read a raw RGB565 binary file and return a padded UIImageAsset. A decoded
+ *  (converted) image in the warm-up cache wins — natural size, converted
+ *  pixels. */
 export function readRgb565Image(srcPath, htmlDir, id, width, height) {
     const abs = path.isAbsolute(srcPath)
         ? srcPath
         : path.resolve(htmlDir, srcPath);
+    const decoded = getCachedDecodedImage(abs);
+    if (decoded) {
+        return { id, width: decoded.width, height: decoded.height, data: decoded.data };
+    }
     if (!fs.existsSync(abs)) {
         console.warn(`[img] Image file not found: ${abs}`);
         return null;

package/dist/ui-engine/image-decode.d.ts

@@ -0,0 +1,22 @@
+export type DetectedImageFormat = "png" | "jpeg" | "gif" | "bmp" | "webp" | "avif" | "tiff" | "ico" | "svg";
+/** A decoded image in the asset pipeline's internal currency (RGB565). */
+export interface DecodedImage {
+    width: number;
+    height: number;
+    /** RGB565 pixels, row-major, width*height values. */
+    data: number[];
+}
+/** Identify a buffer by magic bytes. null = unknown (raw RGB565 dump). */
+export declare function detectImageFormat(buf: Buffer): DetectedImageFormat | null;
+/** 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 declare function getCachedDecodedImage(absPath: string): DecodedImage | undefined;
+/** 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 declare function warmUpImageDecoding(sourceText: string, baseDir: string, opts?: {
+    maxW?: number;
+    maxH?: number;
+}): Promise<void>;
+/** Test hook: drop cached decodes. */
+export declare function resetImageDecodeCache(): void;