@typecad/ui 0.1.0-alpha.1

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

@@ -0,0 +1,116 @@
+import type { Diagnostic } from "@typecad/cuttlefish/api/shared";
+import { InlineItem } from "./inline-parser.js";
+export interface UIElementNode {
+    tag: string;
+    /** Original HTML tag before remapping (label/a/div/...), so CSS tag
+     *  selectors still match remapped elements. Equals tag when no remap. */
+    origTag?: string;
+    id?: string;
+    classes: string[];
+    text?: string;
+    /** Value attribute (for <option>, <radio>). */
+    value?: string;
+    /** Name attribute (for <radio>: groups radios together). */
+    name?: string;
+    /** Checked attribute (for <radio>: initially selected). */
+    checked?: boolean;
+    /** Min/max attributes (for <range>). */
+    min?: string;
+    max?: string;
+    /** Input type (for <input>: "text" | "number"). */
+    type?: "text" | "number";
+    /** Placeholder (for <input>). */
+    placeholder?: string;
+    /** Max length (for <input>). */
+    maxlength?: number;
+    /** Keyboard ref id (for <input>). */
+    keyboard?: string;
+    /** HTML hidden attribute: removes the element subtree from layout/rendering. */
+    hidden?: boolean;
+    /** Inline style attribute: style="color: red; font-size: 16px" */
+    inlineStyle?: string;
+    /** Navigation target for <a href="#screenId"> links. */
+    href?: string;
+    /** Image source path for <img src="...">. */
+    src?: string;
+    /** Image width in pixels (for <img>). */
+    imgWidth?: number;
+    /** Image height in pixels (for <img>). */
+    imgHeight?: number;
+    /** Item height in pixels (for <list item-height="24">). */
+    itemHeight?: number;
+    /** Canvas buffer width in pixels (for <canvas>). */
+    canvasW?: number;
+    /** Canvas buffer height in pixels (for <canvas>). */
+    canvasH?: number;
+    /** Disabled state */
+    disabled?: boolean;
+    children: UIElementNode[];
+    /** Ordered inline content sequence (text/element/break items). Present only
+     *  for text nodes with mixed inline children; absent for plain-text nodes. */
+    inline?: InlineItem[];
+    /** True when the text content contains a `{expr}` interpolation, which the
+     *  auto-wire layer lowers to an implicit ui.bind(node,'text',...) text
+     *  binding. Plain text (no braces) is unchanged. */
+    hasInterpolation?: boolean;
+    /** Declarative event handlers from on:* attributes (e.g. on:click="save").
+     *  Keys: click | hold | release | change. Values: a named TS export function
+     *  the transpiler emits as a standalone C++ function; the handler table
+     *  references it by name. Absent when no on:* attributes are present. */
+    events?: {
+        click?: string;
+        hold?: string;
+        release?: string;
+        change?: string;
+    };
+    /** Declarative two-way bindings from bind:* attributes (e.g. bind:text="ssid").
+     *  Keys: text | value. Values: a signal name — the node reflects the signal
+     *  (one-way: signal → node), and user input writes back (node → signal.set).
+     *  Absent when no bind:* attributes are present. */
+    bind?: {
+        text?: string;
+        value?: string;
+    };
+    /** TS handle name (screen.<ref>), separate from the CSS #id selector target.
+     *  When absent, falls back to `id` (backward-compatible). Lets an author keep
+     *  a CSS id without leaking every styled element into the TS surface. */
+    ref?: string;
+    /** For <select>: parsed option list from <option> children. */
+    options?: Array<{
+        value: string;
+        text: string;
+    }>;
+}
+/** A single key in a keyboard template. */
+export interface UIKeyTemplate {
+    /** Character to insert, or label for special keys. */
+    ch: string;
+    /** 0=char, 1=shift, 2=backspace, 3=ok, 4=page-swap. */
+    special: 0 | 1 | 2 | 3 | 4;
+    /** CSS classes from <key class="..."> for styling. */
+    classes?: string[];
+}
+/** A keyboard template parsed from <keyboard>. */
+export interface KeyboardTemplate {
+    id: string;
+    variant: "alpha" | "number";
+    rows: UIKeyTemplate[][];
+    /** CSS classes from <keyboard class="..."> for styling the keyboard background. */
+    classes?: string[];
+}
+export interface ParsedHtml {
+    /** The first <screen> tree (backward compat). */
+    tree: UIElementNode;
+    /** All <screen> roots (for multi-screen navigation). */
+    screens: UIElementNode[];
+    keyboards: KeyboardTemplate[];
+}
+/** Extract <style>...</style> block contents from HTML source.
+ *  Returns the concatenated CSS text (empty if no style blocks). */
+export declare function extractStyleBlocks(src: string): string;
+export declare function parseHtml(src: string, diagnostics?: Diagnostic[]): UIElementNode;
+/** Parse all <screen> roots from HTML. Returns one tree per screen.
+ *  Used for multi-screen navigation (<a href="#screenId">). */
+export declare function parseAllScreens(src: string, diagnostics?: Diagnostic[]): UIElementNode[];
+/** Parse HTML, returning both the <screen> tree and any <keyboard> templates. */
+export declare function parseHtmlWithKeyboards(src: string, diagnostics?: Diagnostic[]): ParsedHtml;

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

@@ -0,0 +1,284 @@
+// ---------------------------------------------------------------------------
+// HTML parser — uses linkedom for robust DOM parsing, then adapts to the
+// UIElementNode shape that the rest of the pipeline expects.
+//
+// Supported subset:
+//   - One <screen> root (required, exactly one).
+//   - Child elements: <text>, <button>, <view> (a generic container).
+//   - Attributes: id="...", class="a b".
+//   - Text content of leaf elements.
+//
+// The public API (parseHtml: string → UIElementNode) is unchanged — callers
+// don't know whether linkedom or a regex parser is behind it.
+// ---------------------------------------------------------------------------
+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"]);
+/** 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. */
+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",
+    // Inline/heading text -> text
+    span: "text", p: "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",
+};
+/** Extract <style>...</style> block contents from HTML source.
+ *  Returns the concatenated CSS text (empty if no style blocks). */
+export function extractStyleBlocks(src) {
+    const matches = src.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/gi);
+    return Array.from(matches).map(m => m[1]).join("\n");
+}
+export function parseHtml(src, diagnostics) {
+    return parseAllScreens(src, diagnostics)[0];
+}
+/** 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 wrapped = `<div id="__root__">${withoutComments}</div>`;
+    const { document } = parseHTML(wrapped);
+    const root = document.getElementById("__root__");
+    if (!root) {
+        throw new Error("UI HTML: failed to parse document");
+    }
+    const screenEls = Array.from(root.children).filter((c) => c.tagName.toLowerCase() === "screen");
+    if (screenEls.length === 0) {
+        throw new Error("UI HTML must have at least one <screen> root element");
+    }
+    return screenEls.map(el => domToUIElementNode(el, 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 wrapped = `<div id="__root__">${withoutComments}</div>`;
+    const { document } = parseHTML(wrapped);
+    const root = document.getElementById("__root__");
+    if (!root) {
+        throw new Error("UI HTML: failed to parse document");
+    }
+    // Parse keyboards first (they are siblings of <screen>, not children).
+    const keyboards = [];
+    for (const child of Array.from(root.children)) {
+        if (child.tagName.toLowerCase() !== "keyboard")
+            continue;
+        keyboards.push(parseKeyboardElement(child));
+    }
+    // Parse all screens (for multi-screen navigation) + keyboards.
+    const screens = parseAllScreens(src, diagnostics);
+    const tree = screens[0];
+    return { tree, screens, keyboards };
+}
+/** Parse a <keyboard> element into a KeyboardTemplate. */
+function parseKeyboardElement(el) {
+    const id = el.getAttribute("id") || "";
+    const variantAttr = el.getAttribute("variant");
+    const variant = variantAttr === "number" ? "number" : "alpha";
+    const classAttr = el.getAttribute("class") || "";
+    const classes = classAttr.split(/\s+/).filter(Boolean);
+    const rows = [];
+    for (const rowEl of Array.from(el.children)) {
+        if (rowEl.tagName.toLowerCase() !== "row")
+            continue;
+        const row = [];
+        for (const keyEl of Array.from(rowEl.children)) {
+            if (keyEl.tagName.toLowerCase() !== "key")
+                continue;
+            row.push(parseKeyElement(keyEl));
+        }
+        if (row.length > 0)
+            rows.push(row);
+    }
+    return { id, variant, rows, classes: classes.length > 0 ? classes : undefined };
+}
+/** Parse a <key> element. Special keys are identified by label or special attr. */
+function parseKeyElement(el) {
+    const label = el.textContent?.trim() || "";
+    const classAttr = el.getAttribute("class") || "";
+    const classes = classAttr.split(/\s+/).filter(Boolean);
+    const specialAttr = el.getAttribute("special");
+    let special = 0;
+    if (specialAttr !== null) {
+        const s = parseInt(specialAttr, 10);
+        if (s >= 1 && s <= 4)
+            special = s;
+    }
+    else {
+        // Recognize special keys by conventional labels.
+        if (label === "⇧" || label.toUpperCase() === "SHIFT")
+            special = 1;
+        else if (label === "⌫" || label.toUpperCase() === "BACKSPACE")
+            special = 2;
+        else if (label.toUpperCase() === "OK")
+            special = 3;
+        else if (label === "123" || label.toUpperCase() === "ABC")
+            special = 4;
+    }
+    return { ch: label, special, classes: classes.length > 0 ? classes : undefined };
+}
+/** Adapt a DOM element to UIElementNode, recursively walking children. */
+function domToUIElementNode(el, diagnostics) {
+    const tag = el.tagName.toLowerCase();
+    // <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
+        : (tag === "label" || tag === "a") ? "text" : tag;
+    if (!SUPPORTED_TAGS.has(effectiveTag)) {
+        throw new Error(`Unsupported tag <${tag}> — supported: ${[...SUPPORTED_TAGS].join(", ")}`);
+    }
+    const id = el.getAttribute("id") || undefined;
+    const refAttr = el.getAttribute("ref") || undefined;
+    const classAttr = el.getAttribute("class") || "";
+    const classes = classAttr.split(/\s+/).filter(Boolean);
+    const valueAttr = el.getAttribute("value") || undefined;
+    const nameAttr = el.getAttribute("name") || undefined;
+    const checkedAttr = el.hasAttribute("checked");
+    const minAttr = el.getAttribute("min") || undefined;
+    const maxAttr = el.getAttribute("max") || undefined;
+    const typeAttr = tag === "input"
+        ? (el.getAttribute("type") === "number" ? "number" : "text")
+        : undefined;
+    const placeholderAttr = el.getAttribute("placeholder") || undefined;
+    const maxlengthAttr = el.getAttribute("maxlength");
+    // <input> defaults maxlength to 16 when absent or unparseable.
+    const maxlengthNum = tag === "input"
+        ? (maxlengthAttr ? (parseInt(maxlengthAttr, 10) || 16) : 16)
+        : undefined;
+    const keyboardAttr = el.getAttribute("keyboard") || undefined;
+    const hiddenAttr = el.hasAttribute("hidden");
+    const inlineStyleAttr = el.getAttribute("style") || undefined;
+    const hrefAttr = (tag === "a" || tag === "button") ? (el.getAttribute("href") || undefined) : undefined;
+    // Directive value normalization: Svelte encloses directive values in braces
+    // (on:click={handler}, bind:value={signal}). The bare-string form
+    // (on:click="handler") is also accepted for backward compatibility. Strip the
+    // surrounding braces when present so both forms produce the same value.
+    const normalizeDirective = (v) => {
+        if (!v)
+            return undefined;
+        const trimmed = v.trim();
+        if (!trimmed)
+            return undefined;
+        // Svelte brace form: {expr} → expr
+        const braceMatch = /^\{(.+)\}$/.exec(trimmed);
+        return braceMatch ? braceMatch[1].trim() : trimmed;
+    };
+    // Declarative on:* event attributes → named-function references. Accept both
+    // Svelte form (on:click={fn}) and quoted form (on:click="fn").
+    const EVENT_KINDS = ["click", "hold", "release", "change"];
+    const events = {};
+    for (const kind of EVENT_KINDS) {
+        const v = normalizeDirective(el.getAttribute(`on:${kind}`));
+        if (v)
+            events[kind] = v;
+    }
+    const hasEvents = Object.keys(events).length > 0;
+    // Declarative bind:* two-way bindings → signal names. Accept both
+    // Svelte form (bind:text={signal}) and quoted form (bind:text="signal").
+    const BIND_KINDS = ["text", "value"];
+    const bind = {};
+    for (const kind of BIND_KINDS) {
+        const v = normalizeDirective(el.getAttribute(`bind:${kind}`));
+        if (v)
+            bind[kind] = v;
+    }
+    const hasBind = Object.keys(bind).length > 0;
+    const srcAttr = tag === "img" ? (el.getAttribute("src") || undefined) : undefined;
+    const imgWidthAttr = tag === "img" ? parseInt(el.getAttribute("width") || "0", 10) : undefined;
+    const imgHeightAttr = tag === "img" ? parseInt(el.getAttribute("height") || "0", 10) : undefined;
+    const itemHeightAttr = tag === "list" ? (parseInt(el.getAttribute("item-height") || "24", 10) || 24) : undefined;
+    const canvasWAttr = tag === "canvas" ? (parseInt(el.getAttribute("width") || "0", 10) || 0) : undefined;
+    const canvasHAttr = tag === "canvas" ? (parseInt(el.getAttribute("height") || "0", 10) || 0) : undefined;
+    const disabledAttr = el.hasAttribute("disabled");
+    // For <select>, parse <option> children into an options list
+    if (tag === "select") {
+        const optionEls = Array.from(el.children).filter(c => c.tagName.toLowerCase() === "option");
+        if (optionEls.length > 0) {
+            const options = optionEls.map(opt => ({
+                value: opt.getAttribute("value") || opt.textContent?.trim() || "",
+                text: opt.textContent?.trim() || "",
+            }));
+            // Use the first option's text as the initial display text
+            const firstText = options[0]?.text ?? "";
+            return {
+                tag: "select",
+                id, classes, text: firstText, value: valueAttr,
+                hidden: hiddenAttr,
+                inlineStyle: inlineStyleAttr,
+                children: [],
+                options,
+            };
+        }
+        // Fallback: comma-separated text (legacy shorthand)
+        const text = el.textContent?.trim() || "";
+        const optNames = text.split(",").map(s => s.trim()).filter(Boolean);
+        return {
+            tag: "select",
+            id, classes, text: optNames[0] || "",
+            hidden: hiddenAttr,
+            inlineStyle: inlineStyleAttr,
+            children: [],
+            options: optNames.map(t => ({ value: t.toLowerCase(), text: t })),
+        };
+    }
+    // Text content: only direct text, not children's text.
+    let text;
+    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";
+    });
+    // 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.
+    let inline;
+    if (effectiveTag === "text") {
+        inline = collectInlineSequence(el, diagnostics ?? []);
+    }
+    // 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;
+    if (!inline && childElements.length === 0) {
+        const parts = [];
+        for (const child of Array.from(el.childNodes)) {
+            if (child.nodeType === 3) {
+                parts.push(child.textContent ?? "");
+                continue;
+            }
+            const childTag = child.tagName?.toLowerCase();
+            if (childTag === "br")
+                parts.push("\n");
+        }
+        const tc = parts.join("").trim();
+        if (tc) {
+            text = tc;
+            // Detect a `{expr}` interpolation (non-empty content between braces).
+            // Inline + interpolation is rejected later by the run-text-binding guard.
+            hasInterpolation = /\{[^{}]+\}/.test(tc);
+        }
+    }
+    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()))
+            continue;
+        node.children.push(domToUIElementNode(child, diagnostics));
+    }
+    return node;
+}

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

@@ -0,0 +1,21 @@
+import type { StyledNode } from "./style-resolver.js";
+type ColorFormat = "rgb565" | "rgb666" | "rgb888" | "mono";
+export interface UIImageAsset {
+    /** C++-safe unique id used for the generated data symbol. */
+    id: string;
+    /** Pixel width of the raw RGB565 asset. */
+    width: number;
+    /** Pixel height of the raw RGB565 asset. */
+    height: number;
+    /** RGB565 pixel data (width * height values, row-major). */
+    data: number[];
+}
+export interface LoadedUIImageAssets {
+    assets: UIImageAsset[];
+    nodeIdToAssetIndex: Map<string, number>;
+}
+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. */
+export declare function readRgb565Image(srcPath: string, htmlDir: string, id: string, width: number, height: number): UIImageAsset | null;
+export {};

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

@@ -0,0 +1,125 @@
+// ---------------------------------------------------------------------------
+// Image asset loader: reads raw RGB565 binary files for <img> nodes and keeps
+// node ids mapped to the generated image table indices.
+// ---------------------------------------------------------------------------
+import fs from "node:fs";
+import path from "node:path";
+function sanitizeCppIdentifier(value, fallback) {
+    const sanitized = value.replace(/[^a-zA-Z0-9_]/g, "_");
+    const base = sanitized.length > 0 ? sanitized : fallback;
+    return /^[A-Za-z_]/.test(base) ? base : `img_${base}`;
+}
+function uniqueAssetId(preferred, index, used) {
+    const base = sanitizeCppIdentifier(preferred, `img_${index}`);
+    let candidate = base;
+    let suffix = 1;
+    while (used.has(candidate)) {
+        candidate = `${base}_${suffix++}`;
+    }
+    used.add(candidate);
+    return candidate;
+}
+function imageNaturalWidth(node) {
+    const width = node.imgWidth;
+    return width && width > 0 ? width : 32;
+}
+function imageNaturalHeight(node) {
+    const height = node.imgHeight;
+    return height && height > 0 ? height : 32;
+}
+function imageAssetKey(src, htmlDir, width, height) {
+    const abs = path.isAbsolute(src) ? src : path.resolve(htmlDir, src);
+    return `${abs}\0${width}\0${height}`;
+}
+export function loadImageAssets(roots, htmlDir) {
+    const assets = [];
+    const nodeIdToAssetIndex = new Map();
+    const keyToAssetIndex = new Map();
+    const usedIds = new Set();
+    const walk = (node) => {
+        const src = node.src;
+        if (src && node.id) {
+            const width = imageNaturalWidth(node);
+            const height = imageNaturalHeight(node);
+            const key = imageAssetKey(src, htmlDir, width, height);
+            let assetIdx = keyToAssetIndex.get(key);
+            if (assetIdx === undefined) {
+                const assetId = uniqueAssetId(node.id, assets.length, usedIds);
+                const asset = readRgb565Image(src, htmlDir, assetId, width, height);
+                if (asset) {
+                    assetIdx = assets.length;
+                    assets.push(asset);
+                    keyToAssetIndex.set(key, assetIdx);
+                }
+            }
+            if (assetIdx !== undefined) {
+                nodeIdToAssetIndex.set(node.id, assetIdx);
+            }
+        }
+        node.children.forEach(walk);
+    };
+    for (const root of Array.isArray(roots) ? roots : [roots]) {
+        walk(root);
+    }
+    return { assets, nodeIdToAssetIndex };
+}
+function rgb565ToRgb888(v) {
+    const r5 = (v >> 11) & 0x1f;
+    const g6 = (v >> 5) & 0x3f;
+    const b5 = v & 0x1f;
+    const r = (r5 << 3) | (r5 >> 2);
+    const g = (g6 << 2) | (g6 >> 4);
+    const b = (b5 << 3) | (b5 >> 2);
+    return (r << 16) | (g << 8) | b;
+}
+function emitPixelValue(v, colorFormat) {
+    if (colorFormat === "rgb666" || colorFormat === "rgb888") {
+        return "0x" + rgb565ToRgb888(v).toString(16).padStart(6, "0");
+    }
+    return "0x" + (v & 0xffff).toString(16).padStart(4, "0");
+}
+export function emitImageTables(assets, colorFormat = "rgb565") {
+    if (assets.length === 0) {
+        return "const UIImage __ui_images[] = {};\nconst uint16_t __ui_image_count = 0;";
+    }
+    const lines = [];
+    for (const asset of assets) {
+        lines.push(`static const UI_COLOR_T __ui_img_${asset.id}_data[] = {`);
+        for (let i = 0; i < asset.data.length; i += 16) {
+            const chunk = asset.data
+                .slice(i, i + 16)
+                .map((v) => emitPixelValue(v, colorFormat));
+            lines.push("  " + chunk.join(", ") + ",");
+        }
+        lines.push("};");
+    }
+    lines.push("const UIImage __ui_images[] = {");
+    for (const asset of assets) {
+        lines.push(`  { ${asset.width}, ${asset.height}, __ui_img_${asset.id}_data },`);
+    }
+    lines.push("};");
+    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. */
+export function readRgb565Image(srcPath, htmlDir, id, width, height) {
+    const abs = path.isAbsolute(srcPath)
+        ? srcPath
+        : path.resolve(htmlDir, srcPath);
+    if (!fs.existsSync(abs)) {
+        console.warn(`[img] Image file not found: ${abs}`);
+        return null;
+    }
+    const buf = fs.readFileSync(abs);
+    const expectedPixels = width * height;
+    const expectedBytes = expectedPixels * 2;
+    if (buf.length < expectedBytes) {
+        console.warn(`[img] Image ${srcPath} is ${buf.length} bytes, expected ${expectedBytes} (${width}x${height}x2). Padding missing pixels with 0.`);
+    }
+    const availablePixels = Math.min(expectedPixels, Math.floor(buf.length / 2));
+    const data = new Array(expectedPixels).fill(0);
+    for (let i = 0; i < availablePixels; i++) {
+        data[i] = buf.readUInt16LE(i * 2);
+    }
+    return { id, width, height, data };
+}

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

@@ -0,0 +1,30 @@
+import type { Diagnostic } from "@typecad/cuttlefish/api/shared";
+/** 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 declare const INLINE_TAGS: Set<string>;
+export type InlineItem = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "element";
+    tag: string;
+    origTag?: string;
+    classes: string[];
+    inlineStyle?: string;
+    href?: string;
+    inline?: InlineItem[];
+} | {
+    kind: "break";
+};
+/** Walk childNodes in document order, building an inline sequence.
+ *
+ *  Returns `undefined` when the element is NOT inline-bearing:
+ *  - has any block-level child (a non-inline, non-br element) → block breaks
+ *    the flow, so this element is treated as a container, not a rich-text node;
+ *  - has no recognized inline element child at all → plain text, handled by the
+ *    existing single-string text path.
+ *
+ *  Otherwise returns the ordered sequence of text fragments, inline elements
+ *  (recursively), and hard-break markers (`<br>`). */
+export declare function collectInlineSequence(el: Element, diagnostics: Diagnostic[]): InlineItem[] | undefined;

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

@@ -0,0 +1,66 @@
+/** 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"]);
+/** Walk childNodes in document order, building an inline sequence.
+ *
+ *  Returns `undefined` when the element is NOT inline-bearing:
+ *  - has any block-level child (a non-inline, non-br element) → block breaks
+ *    the flow, so this element is treated as a container, not a rich-text node;
+ *  - has no recognized inline element child at all → plain text, handled by the
+ *    existing single-string text path.
+ *
+ *  Otherwise returns the ordered sequence of text fragments, inline elements
+ *  (recursively), and hard-break markers (`<br>`). */
+export function collectInlineSequence(el, diagnostics) {
+    const childElements = Array.from(el.children);
+    const hasBlockChild = childElements.some((c) => !INLINE_TAGS.has(c.tagName.toLowerCase()) && c.tagName.toLowerCase() !== "br");
+    if (hasBlockChild)
+        return undefined;
+    // Only build a sequence when there's at least one recognized inline element
+    // child OR a <br> among mixed text (a <br> mid-paragraph is inline content
+    // that needs the rich-text path to render as a hard line break). A node with
+    // only bare text nodes (no elements, no <br>) is plain text — existing path.
+    const hasInlineChild = childElements.some((c) => INLINE_TAGS.has(c.tagName.toLowerCase()) || c.tagName.toLowerCase() === "br");
+    if (!hasInlineChild)
+        return undefined;
+    const seq = [];
+    for (const child of Array.from(el.childNodes)) {
+        const nodeType = child.nodeType;
+        if (nodeType === 3) { // text node
+            const text = child.textContent ?? "";
+            if (text)
+                seq.push({ kind: "text", text });
+            continue;
+        }
+        const childTag = child.tagName?.toLowerCase();
+        if (childTag === "br") {
+            seq.push({ kind: "break" });
+            continue;
+        }
+        if (childTag && INLINE_TAGS.has(childTag)) {
+            const cel = child;
+            const classes = (cel.getAttribute("class") || "").split(/\s+/).filter(Boolean);
+            let subInline = collectInlineSequence(cel, diagnostics);
+            // A leaf inline element (only text, no nested inline children) collects
+            // no sub-sequence — synthesize one text item from its text content so the
+            // resolver emits a run for it. Without this, <b>world</b> would carry no
+            // text and produce no run.
+            if (subInline === undefined) {
+                const leafText = cel.textContent ?? "";
+                subInline = leafText ? [{ kind: "text", text: leafText }] : [];
+            }
+            seq.push({
+                kind: "element",
+                tag: "text",
+                origTag: childTag,
+                classes,
+                inlineStyle: cel.getAttribute("style") || undefined,
+                href: childTag === "a" ? (cel.getAttribute("href") || undefined) : undefined,
+                inline: subInline,
+            });
+        }
+        // Other node types (comments, unknown elements already filtered) are ignored.
+    }
+    return seq;
+}

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

@@ -0,0 +1,3 @@
+import type { KeyframeSet } from "./css-parser.js";
+import { type KeyframeSetModel } from "./model.js";
+export declare function buildKeyframeSets(rawKeyframes: KeyframeSet[], colorFormat: "rgb565" | "rgb666" | "rgb888" | "mono"): KeyframeSetModel[];