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

package/src/ui-engine/image-assets.ts

@@ -6,6 +6,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import type { StyledNode } from "./style-resolver.js";
+import { getCachedDecodedImage } from "./image-decode.js";
 
 type ColorFormat = "rgb565" | "rgb666" | "rgb888" | "mono";
 
@@ -66,9 +67,14 @@ export function loadImageAssets(roots: StyledNode | StyledNode[], htmlDir: strin
   const walk = (node: StyledNode) => {
     const src = (node as any).src as string | undefined;
     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);
@@ -136,7 +142,31 @@ export function emitImageTables(assets: UIImageAsset[], colorFormat: ColorFormat
   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: StyledNode | StyledNode[], htmlDir: string): void {
+  const walk = (node: StyledNode) => {
+    const src = (node as any).src as string | undefined;
+    if (src && (node as any).imgWidth === undefined && (node as any).imgHeight === undefined) {
+      const abs = path.isAbsolute(src) ? src : path.resolve(htmlDir, src);
+      const decoded = getCachedDecodedImage(abs);
+      if (decoded) {
+        (node as any).imgWidth = decoded.width;
+        (node as any).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: string,
   htmlDir: string,
@@ -148,6 +178,11 @@ export function readRgb565Image(
     ? 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/src/ui-engine/image-decode.ts

@@ -0,0 +1,244 @@
+// ---------------------------------------------------------------------------
+// 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";
+
+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 function detectImageFormat(buf: Buffer): DetectedImageFormat | null {
+  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;
+}
+
+/** RGBA/RGB pixel block plus its channel count. */
+interface RawPixels {
+  pixels: Buffer | Uint8Array;
+  channels: number;
+  width: number;
+  height: number;
+}
+
+let sharpLoader: Promise<any> | null = null;
+function loadSharp(): Promise<any> {
+  if (!sharpLoader) {
+    sharpLoader = import("sharp").then((m) => (m as { default: any }).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: any,
+  naturalW: number,
+  naturalH: number,
+  opts: { maxW?: number; maxH?: number },
+): Promise<RawPixels> {
+  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: Buffer): Promise<RawPixels> {
+  const decodeIcoMod = await import("decode-ico");
+  const decodeIco = (decodeIcoMod as unknown as {
+    default: (src: Uint8Array) => Array<{ width: number; height: number; data: Uint8Array }>;
+  }).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: Buffer | Uint8Array, channels: number): number[] {
+  const count = Math.floor(px.length / channels);
+  const out = new Array<number>(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: Buffer,
+  format: DetectedImageFormat,
+  opts: { maxW?: number; maxH?: number },
+): Promise<DecodedImage> {
+  const sharp = await loadSharp();
+  let raw: RawPixels;
+  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) };
+}
+
+// ── Warm-up cache ──────────────────────────────────────────────────────────
+// Keyed by absolute path + mtime so a preview watch session picks up edited
+// images; entries for prior mtimes simply go stale (a snapshot build is
+// short-lived, and the transpile pipeline is one-shot).
+
+interface CacheEntry {
+  mtimeMs: number;
+  image: DecodedImage | null; // null = failed decode (raw fallback, one warning)
+}
+
+const decodedCache = new Map<string, CacheEntry>();
+
+function cacheKey(abs: string, mtimeMs: number): string {
+  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: string): DecodedImage | undefined {
+  let stat: fs.Stats;
+  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: string,
+  baseDir: string,
+  opts: { maxW?: number; maxH?: number } = {},
+): Promise<void> {
+  const pending = new Set<string>();
+  let match: RegExpExecArray | null;
+  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(): void {
+  decodedCache.clear();
+}

package/src/ui-engine/inline-parser.ts

@@ -3,7 +3,7 @@ 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 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"]);
 
 export type InlineItem =
   | { kind: "text"; text: string }

package/src/ui-engine/layout-engine.ts

@@ -40,6 +40,57 @@ export function isDisplayNone(node: StyledNode): boolean {
   return node.style.display?.trim().toLowerCase() === "none";
 }
 
+/** 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 function cssDimValue(val: string | undefined): CssDim {
+  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])}%` as `${number}%`;
+  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: CssDim): boolean {
+  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: string | undefined): number | `${number}%` | undefined {
+  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: string | undefined): [CssDim, CssDim, CssDim, CssDim] {
+  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]] as [CssDim, CssDim, CssDim, CssDim];
+}
+
 /** Parse CSS aspect-ratio values: "16 / 9", "1/1", or "1.777". */
 export function parseAspectRatio(value: string | undefined): number | undefined {
   const raw = value?.trim().toLowerCase();
@@ -172,12 +223,19 @@ export function measure(node: StyledNode, availableWidth?: number, fontAssets: U
     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, {