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

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

@@ -8,15 +8,25 @@
 // handles flexbox layouts.
 // ---------------------------------------------------------------------------
 
-import { Box, IntrinsicSize, isDisplayNone, LayoutEngine, parseAspectRatio } from "./layout-engine.js";
+import { Box, IntrinsicSize, isDisplayNone, LayoutEngine, parseAspectRatio, cssDimValue, expandBoxShorthand } from "./layout-engine.js";
 import { StyledNode } from "./style-resolver.js";
 
-/** Parse a CSS value string ("8px", "8") to a number. */
+/** Parse a CSS value string ("8px", "8") to a number (percent folds to its
+ *  numeric part — block layout has no parent-relative resolution). */
 function cssNum(val: string | number | undefined): number {
   if (val === undefined) return 0;
   if (typeof val === "number") return val;
-  const m = val.match(/(\d+)/);
-  return m ? parseInt(m[1]) : 0;
+  const d = cssDimValue(val);
+  return typeof d === "number" ? d : parseFloat(String(d));
+}
+
+/** Resolve a dimension against a reference size: px passes through, a
+ *  percentage resolves against `total` (0 when unresolvable). */
+function resolveDim(val: string | undefined, total: number): number {
+  const d = cssDimValue(val);
+  if (typeof d === "number") return d;
+  if (typeof d === "string" && d.endsWith("%")) return Math.round((parseFloat(d) * total) / 100);
+  return 0;
 }
 
 export class BlockLayoutEngine implements LayoutEngine {
@@ -42,12 +52,15 @@ export class BlockLayoutEngine implements LayoutEngine {
     out.push(box);
     if (node.children.length === 0) return;
 
-    const pad = cssNum(node.style.padding);
+    // Padding: full 1-4 value TRBL expansion (vertical/horizontal pairs).
+    const [padT, , padB, padL] = expandBoxShorthand(node.style.padding);
+    const padV = (typeof padT === "number" ? padT : 0) + (typeof padB === "number" ? padB : 0);
+    const padH = typeof padL === "number" ? padL * 2 : 0;
     const content: Box = {
-      x: box.x + pad,
-      y: box.y + pad,
-      w: box.w - pad * 2,
-      h: box.h - pad * 2,
+      x: box.x + (typeof padL === "number" ? padL : 0),
+      y: box.y + (typeof padT === "number" ? padT : 0),
+      w: box.w - padH,
+      h: box.h - padV,
     };
     let cursorY = content.y;
 
@@ -67,8 +80,8 @@ export class BlockLayoutEngine implements LayoutEngine {
         ? intrinsic.w + childPad * 2
         : content.w;
       const childH = intrinsic.h > 0 ? intrinsic.h + (isButton ? childPad * 2 : 0) : 16;
-      const explicitW = cssNum(child.style.width);
-      const explicitH = cssNum(child.style.height);
+      const explicitW = resolveDim(child.style.width, content.w);
+      const explicitH = resolveDim(child.style.height, content.h);
       const aspectRatio = parseAspectRatio(child.style.aspectRatio);
       let resolvedW = childW;
       let resolvedH = childH;

package/src/ui-engine/color.ts

@@ -88,9 +88,38 @@ const NAMED_COLORS: Record<string, RGB> = {
   violet: { r: 238, g: 130, b: 238 }, wheat: { r: 245, g: 222, b: 179 },
   white: { r: 255, g: 255, b: 255 }, whitesmoke: { r: 245, g: 245, b: 245 },
   yellow: { r: 255, g: 255, b: 0 }, yellowgreen: { r: 154, g: 205, b: 50 },
-  transparent: { r: 0, g: 0, b: 0 },
 };
 
+/** Is this color fully transparent (the `transparent` keyword, alpha-0 rgba/
+ *  hsla, or #rrggbb00)? Callers treat it as "no fill" rather than black. */
+export function isTransparentColor(input: string): boolean {
+  const s = input.trim().toLowerCase();
+  if (s === "transparent" || s === "none") return true;
+  const rgbaM = /^rgba?\([^)]*,\s*(0(?:\.0+)?)\s*\)$/.exec(s);
+  if (rgbaM) return true;
+  const hslaM = /^hsla?\([^)]*\/\s*(0(?:\.0+)?|0%)\s*\)$/.exec(s);
+  if (hslaM) return true;
+  const hex8M = /^#[0-9a-f]{8}$/.exec(s);
+  if (hex8M) return s.endsWith("00");
+  return false;
+}
+
+/** Does this color carry a partial (non-zero, non-one) alpha that the engine
+ *  will ignore? (No alpha blending on bare metal.) Used for warnings. */
+export function hasIgnoredAlpha(input: string): boolean {
+  const s = input.trim().toLowerCase();
+  const rgbaM = /^rgba?\([^)]*,\s*([\d.]+)\s*\)$/.exec(s);
+  if (rgbaM) return parseFloat(rgbaM[1]) < 1;
+  const hslaM = /^hsla?\([^)]*\/\s*([\d.]+)%?\s*\)$/.exec(s);
+  if (hslaM) return (hslaM[1].endsWith("%") ? parseFloat(hslaM[1]) / 100 : parseFloat(hslaM[1])) < 1;
+  const hex8M = /^#[0-9a-f]{8}$/.exec(s);
+  if (hex8M) {
+    const a = parseInt(s.slice(7, 9), 16) / 255;
+    return a > 0 && a < 1;
+  }
+  return false;
+}
+
 /** Parse any CSS color string to {r,g,b}. Alpha is ignored (no blending). */
 export function parseColor(input: string): RGB {
   const s = input.trim().toLowerCase();
@@ -144,7 +173,53 @@ export function parseColor(input: string): RGB {
   // Named colors
   if (NAMED_COLORS[s]) return NAMED_COLORS[s];
 
-  throw new Error(`Unsupported color format "${input}" — use #hex, rgb(), hsl(), or a named color`);
+  // transparent resolves to black as a COLOR (e.g. gradient stops); fill
+  // sites check isTransparentColor() first and skip painting entirely.
+  if (s === "transparent") return { r: 0, g: 0, b: 0 };
+
+  // oklch(L C H [/ a]) — CSS Color 4, the dialect of Tailwind v4 era shadcn
+  // themes. Alpha ignored like everywhere else; L accepts % form.
+  const oklchM = /^oklch\(\s*([\d.]+|none)(%)?\s+([\d.]+|none)\s+([\d.]+|none)(?:deg|turn|rad)?(?:\s*\/\s*[\d.%]+)?\s*\)$/i.exec(s);
+  if (oklchM) {
+    const l = oklchM[1] === "none" ? 0 : parseFloat(oklchM[1]) / (oklchM[2] ? 100 : 1);
+    const c = oklchM[3] === "none" ? 0 : parseFloat(oklchM[3]);
+    let h = oklchM[4] === "none" ? 0 : parseFloat(oklchM[4]);
+    if (/turn\b/i.test(s)) h = h * 360;
+    return oklchToRgb(l, c, h);
+  }
+
+  // shadcn theme dialect: bare HSL channel triplets ("222.2 47.4% 11.2%") —
+  // the format stock shadcn themes store in CSS variables, normally consumed
+  // as hsl(var(--x)). The shape (number % number%) is unambiguous with any
+  // valid CSS color, so both dialects work through var() substitution.
+  const tripletM = /^([\d.]+)(?:deg)?\s+([\d.]+)%\s+([\d.]+)%$/.exec(s);
+  if (tripletM) return hslToRgb(parseFloat(tripletM[1]), parseFloat(tripletM[2]), parseFloat(tripletM[3]));
+
+  throw new Error(`Unsupported color format "${input}" — use #hex, rgb(), hsl(), oklch(), or a named color`);
+}
+
+/** Convert oklch (L 0-1, C 0-~0.4, H degrees) to sRGB via OkLab — Björn
+ *  Ottosson's reference matrices, then the sRGB transfer function. Values
+ *  outside the sRGB gamut clamp per channel (compile-time approximation of
+ *  CSS gamut mapping — good enough for opaque 16-bit panel output). */
+function oklchToRgb(l: number, c: number, h: number): RGB {
+  const rad = (h * Math.PI) / 180;
+  const a = c * Math.cos(rad);
+  const b = c * Math.sin(rad);
+  const l_ = l + 0.3963377774 * a + 0.2158037573 * b;
+  const m_ = l - 0.1055613458 * a - 0.0638541728 * b;
+  const s_ = l - 0.0894841775 * a - 1.2914855480 * b;
+  const L = l_ * l_ * l_;
+  const M = m_ * m_ * m_;
+  const S = s_ * s_ * s_;
+  const lr = 4.0767416621 * L - 3.3077115913 * M + 0.2309699292 * S;
+  const lg = -1.2684380046 * L + 2.6097574011 * M - 0.3413193965 * S;
+  const lb = -0.0041960863 * L - 0.7034186147 * M + 1.7076147010 * S;
+  const gamma = (v: number): number => {
+    const x = Math.min(1, Math.max(0, v));
+    return Math.round(255 * (x <= 0.0031308 ? 12.92 * x : 1.055 * Math.pow(x, 1 / 2.4) - 0.055));
+  };
+  return { r: gamma(lr), g: gamma(lg), b: gamma(lb) };
 }
 
 /** Convert HSL (h: 0-360, s/l: 0-100) to RGB. Standard CSS algorithm. */

package/src/ui-engine/compat-report.ts

@@ -0,0 +1,139 @@
+// ---------------------------------------------------------------------------
+// CSS compatibility report — post-layout diagnostics that make the engine's
+// divergences from browser behavior VISIBLE instead of silent.
+//
+// Every check here corresponds to a place where the engine approximates or
+// quantizes what a browser would do (font-size bucketing on the stock font,
+// ignored alpha, display-anchored UA scale, touch-target minimums). Surfaces
+// as ordinary warnings in the build output; `--strict-css` upgrades them to
+// errors (see the cuttlefish CLI).
+// ---------------------------------------------------------------------------
+
+import type { Diagnostic } from "@typecad/cuttlefish/api/shared";
+import type { StyledNode } from "./style-resolver.js";
+import type { Box } from "./layout-engine.js";
+import type { UIFontAssetModel } from "./font-assets.js";
+import { selectFontAssetForStyle } from "./font-assets.js";
+import { hasIgnoredAlpha } from "./color.js";
+import { uaScaleFor } from "./ua-stylesheet.js";
+
+const COLOR_PROPS = [
+  "color", "background", "borderColor", "borderTopColor", "borderRightColor",
+  "borderBottomColor", "borderLeftColor", "outline",
+] as const;
+
+/** Stock-font size buckets (model.ts textSizeOf): every font-size in a bucket
+ *  renders at the same pixel size when no @font-face matches. */
+function bucketOf(px: number): string {
+  if (px <= 12) return "1–12";
+  if (px <= 20) return "13–20";
+  if (px <= 28) return "21–28";
+  return "29+";
+}
+
+function labelOf(node: StyledNode): string {
+  if (node.id) return `#${node.id}`;
+  if (node.origTag) return `<${node.origTag}>`;
+  return `<${node.tag}>`;
+}
+
+/** Produce CSS-compatibility diagnostics for the lowered tree. */
+export function cssCompatDiagnostics(
+  screens: StyledNode[],
+  fontAssets: UIFontAssetModel[],
+  viewport: { width: number; height: number },
+  colorFormat: string | undefined,
+  sourceFile: string,
+): Diagnostic[] {
+  const out: Diagnostic[] = [];
+  const seen = new Set<string>();
+  const push = (key: string, d: Diagnostic): void => {
+    if (seen.has(key)) return;
+    seen.add(key);
+    out.push(d);
+  };
+
+  const mono = colorFormat === "mono";
+  const scale = uaScaleFor(viewport.height, mono);
+
+  // Surface the display-anchored UA scale once when it differs from the
+  // browser's classic 16px — "why is my text smaller than on desktop" answered
+  // up front instead of discovered pixel-by-pixel.
+  if (scale.root !== 16 || mono) {
+    out.push({
+      severity: "info",
+      code: "css-ua-scale",
+      message: `Display-anchored UA defaults active: root text ${scale.root}px` +
+        (mono ? ` (monochrome; stock-font sizes are bucketed 1–12/13–20/21–28/29+)` : ``) +
+        `, headings ${scale.h.join("/")}, touch-target min-height ${scale.controlMinHeight}px.`,
+      hint: `Override per element with explicit px font-sizes, or restyle the scale in your own CSS.`,
+      source: sourceFile,
+    });
+  }
+
+  const walk = (node: StyledNode): void => {
+    const style = node.style as Record<string, string | undefined>;
+    const label = labelOf(node);
+
+    // Partial alpha is silently dropped (no blending on bare metal).
+    for (const prop of COLOR_PROPS) {
+      const v = style[prop];
+      if (v && hasIgnoredAlpha(v)) {
+        push(`alpha:${v}`, {
+          severity: "warning",
+          code: "css-alpha-ignored",
+          message: `${label}: alpha in "${v}" is ignored — the color renders fully opaque (${prop}).`,
+          hint: `There is no alpha blending on bare metal; blend against the target background color instead.`,
+          source: sourceFile,
+        });
+      }
+    }
+
+    // font-size sanity against the viewport and the stock-font buckets.
+    const fs = style.fontSize;
+    if (fs) {
+      const px = parseFloat(fs);
+      if (Number.isFinite(px) && px > 0) {
+        if (px >= viewport.height * 0.15) {
+          push(`fsvp:${px}`, {
+            severity: "warning",
+            code: "css-font-size-viewport",
+            message: `${label}: font-size ${px}px is ${Math.round((px / viewport.height) * 100)}% of the ${viewport.height}px display height.`,
+            hint: `Large fills of a small screen are sometimes intended — if not, scale it down.`,
+            source: sourceFile,
+          });
+        }
+        // Quantization only bites on the stock font (no matching @font-face).
+        if (mono && selectFontAssetForStyle(fontAssets, node.style) === undefined) {
+          push(`bucket:${px}`, {
+            severity: "warning",
+            code: "css-font-size-quantized",
+            message: `${label}: font-size ${px}px renders at the stock-font bucket for ${bucketOf(px)}px — every size in that range draws identically on monochrome displays.`,
+            hint: `Pick sizes from the bucket edges (12/20/28) or register an @font-face for exact sizes.`,
+            source: sourceFile,
+          });
+        }
+      }
+    }
+
+    // Touch-target minimums that swallow half the screen.
+    const mh = style.minHeight;
+    if (mh) {
+      const px = parseFloat(mh);
+      if (Number.isFinite(px) && px >= viewport.height * 0.5) {
+        push(`mhvp:${px}`, {
+          severity: "warning",
+          code: "css-min-height-viewport",
+          message: `${label}: min-height ${px}px is ${Math.round((px / viewport.height) * 100)}% of the ${viewport.height}px display height.`,
+          hint: `Reduce the min-height for very small panels (the UA default already scales down).`,
+          source: sourceFile,
+        });
+      }
+    }
+
+    for (const child of node.children) walk(child);
+  };
+  for (const screen of screens) walk(screen);
+
+  return out;
+}

package/src/ui-engine/css-imports.ts

@@ -0,0 +1,69 @@
+// ---------------------------------------------------------------------------
+// CSS @import expansion — build-time stylesheet inclusion.
+//
+// Local @import statements are inlined before parsing so shared stylesheets
+// (e.g. the shadcn preset added by `cuttlefish add shadcn`) compose with
+// per-module CSS, like a browser resolving imports. Relative paths resolve
+// against the importing stylesheet's directory; recursion is supported with a
+// cycle guard. Remote (http/data:) imports and unreadable files are left in
+// place — the CSS parser's existing "@import is not supported" warning then
+// reports them instead of failing silently.
+//
+// This is compile-time inclusion only: each firmware build still targets one
+// display, so there is no runtime fetch.
+// ---------------------------------------------------------------------------
+
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+
+/** Guard against runaway include chains (distinct-file budget across the
+ *  whole expansion; cycles are caught by the seen-set, this bounds depth). */
+const MAX_INCLUDED_FILES = 32;
+
+const IMPORT_RE = /@import\s+(?:url\(\s*)?["']?([^"'()\s;]+)["']?\s*\)?\s*[^;]*;/g;
+
+/** Resolve a bare package specifier ("@typecad/ui/themes/blue.css") through
+ *  node_modules relative to baseDir — how pre-packaged themes are imported.
+ *  Returns null when it doesn't resolve (e.g. the Tailwind scaffolding
+ *  specifier "tailwindcss" inside stock theme exports). */
+function resolvePackageSpecifier(spec: string, baseDir: string): string | null {
+  try {
+    const req = createRequire(path.join(baseDir, "package.json"));
+    return req.resolve(spec);
+  } catch {
+    return null;
+  }
+}
+
+/** Inline local @import statements in `cssText`. `baseDir` is the directory
+ *  of the stylesheet the text came from. `seen` tracks normalized absolute
+ *  paths already inlined (cycle guard) across the whole expansion. */
+export function expandCssImports(cssText: string, baseDir: string, seen: Set<string> = new Set()): string {
+  return cssText.replace(IMPORT_RE, (match, spec: string) => {
+    if (/^(https?|data):/i.test(spec)) return match;
+    // Package specifiers ("@typecad/ui/themes/blue.css", but also the
+    // "tailwindcss" scaffolding inside stock exports) start with @ or a bare
+    // name — NOT "./", "../", "/", or a drive letter. Resolvable ones load
+    // from node_modules (pre-packaged themes); the rest drop silently so
+    // pasted tweakcn/ui.shadcn.com files import cleanly.
+    const pathLike = spec.startsWith("./") || spec.startsWith("../") || spec.startsWith("/") || /^[a-zA-Z]:/.test(spec);
+    let abs: string;
+    if (!pathLike) {
+      const resolved = resolvePackageSpecifier(spec, baseDir);
+      if (!resolved) return "";
+      abs = resolved;
+    } else {
+      abs = path.normalize(path.isAbsolute(spec) ? spec : path.join(baseDir, spec));
+    }
+    if (seen.has(abs) || seen.size >= MAX_INCLUDED_FILES) return "";
+    seen.add(abs);
+    let text: string;
+    try {
+      text = fs.readFileSync(abs, "utf-8");
+    } catch {
+      return match; // unreadable: keep the statement so the parser warns
+    }
+    return expandCssImports(text, path.dirname(abs), seen);
+  });
+}

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

@@ -442,15 +442,21 @@ function resolveCalc(value: string): string {
 }
 
 /** Evaluate a simple arithmetic expression of lengths to a length string.
- *  Each term may have a unit (px/rem/em/%); the first unit found wins.
- *  Supports + - * /.  e.g. "10px - 4" → "6px". */
+ *  Supports + - * /. rem/em terms normalize to px (×16), so any length
+ *  expression reduces to px: "calc(0.5rem - 2px)" → "6px".
+ *  Percent + length mixes ("calc(50% - 10px)") cannot resolve numerically at
+ *  parse time — those stay as literal calc() text. Unrecognized → as-is. */
 function evalCalcExpr(expr: string): string {
   // Tokenize into numbers-with-units and operators.
   const tokens = expr.match(/(?:[\d.]+(?:rem|em|px|%)?|[-+*/])/g);
   if (!tokens || tokens.length === 0) return `calc(${expr})`;
-  // Determine the dominant unit from the first length token.
-  const unitMatch = expr.match(/(\d)(rem|em|px|%)/);
-  const unit = unitMatch ? unitMatch[2] : "";
+  const hasPercent = /[\d.]+%/.test(expr);
+  const hasLength = /[\d.]+(?:rem|em|px)/.test(expr);
+  if (hasPercent && hasLength) return `calc(${expr})`;
+  // rem/em already fold to px in toNum, so the output unit is determined by
+  // the term kinds — never "the first unit seen" (that produced 6rem from
+  // 0.5rem - 2px).
+  const unit = hasPercent ? "%" : hasLength ? "px" : "";
   // Convert each token to a plain number (rem/em × 16).
   const toNum = (tok: string): number => {
     const remM = /^(-?[\d.]+)rem$/.exec(tok);
@@ -843,9 +849,10 @@ function parseFontShorthand(props: CSSProperty, val: string): void {
   const sizeIndex = parts.findIndex((part) => /^\d+(?:\.\d+)?(?:px|pt|em|rem)?(?:\/.+)?$/.test(part));
   if (sizeIndex < 0) return;
   const beforeSize = parts.slice(0, sizeIndex);
-  const size = parts[sizeIndex].split("/")[0];
+  const [size, lineHeight] = parts[sizeIndex].split("/");
   const family = parts.slice(sizeIndex + 1).join(" ").trim();
   if (size) props.fontSize = size;
+  if (lineHeight) props.lineHeight = lineHeight;
   if (family) props.fontFamily = family;
   for (const part of beforeSize) {
     const lower = part.toLowerCase();
@@ -855,11 +862,16 @@ function parseFontShorthand(props: CSSProperty, val: string): void {
 }
 
 /** Assign a CSS property to the CSSProperty object. Unknown properties emit a warning
- *  (forward-compatible: they are dropped from output, but the author is notified). */
+ *  (forward-compatible: they are dropped from output, but the author is notified).
+ *  Known properties with values the engine can only partially honor also warn —
+ *  a visible approximation beats a silent one. */
 function assignProp(props: CSSProperty, prop: string, val: string, diagnostics?: Diagnostic[]): void {
   const warn = (message: string, hint?: string): void => {
     if (diagnostics) diagnostics.push({ severity: "warning", message, hint, code: "unknown-css-property", source: prop });
   };
+  const warnValue = (code: string, message: string, hint?: string): void => {
+    if (diagnostics) diagnostics.push({ severity: "warning", message, hint, code, source: prop });
+  };
   switch (prop) {
     // Box model
     case "padding": props.padding = val; break;
@@ -875,7 +887,12 @@ function assignProp(props: CSSProperty, prop: string, val: string, diagnostics?:
     case "min-height": props.minHeight = val; break;
     case "max-height": props.maxHeight = val; break;
     case "aspect-ratio": props.aspectRatio = val; break;
-    case "box-sizing": props.boxSizing = val; break;
+    case "box-sizing":
+      if (val.trim().toLowerCase() === "content-box") {
+        warnValue("css-box-sizing", `box-sizing: content-box is ignored — the engine always lays out border-box (borders and padding inside width/height).`, `Remove the declaration, or size elements accounting for padding/border.`);
+      }
+      props.boxSizing = val;
+      break;
     case "overflow": props.overflow = val; break;
     // Colors
     case "color": props.color = val; break;
@@ -884,7 +901,21 @@ function assignProp(props: CSSProperty, prop: string, val: string, diagnostics?:
     // Text
     case "font": props.font = val; parseFontShorthand(props, val); break;
     case "font-family": props.fontFamily = val; break;
-    case "font-size": props.fontSize = val; break;
+    case "font-size": {
+      const v = val.trim();
+      if (v.endsWith("%")) {
+        warnValue("css-font-size-unit", `font-size "${val}" — percent sizes are not supported; use px. The declaration is ignored.`, `font-size accepts px (or a bare number, treated as px).`);
+      } else {
+        const em = /^([\d.]+)(em|rem)$/.exec(v);
+        if (em) {
+          props.fontSize = `${Math.round(parseFloat(em[1]) * 16)}px`;
+          warnValue("css-font-size-unit", `font-size "${val}" — em/rem resolve against the root (16px), not the parent; wrote ${props.fontSize}.`, `Use px to size text exactly.`);
+        } else {
+          props.fontSize = val;
+        }
+      }
+      break;
+    }
     case "text-align": props.textAlign = val; break;
     case "text-decoration": props.textDecoration = val; break;
     case "font-weight": props.fontWeight = val; break;
@@ -893,7 +924,12 @@ function assignProp(props: CSSProperty, prop: string, val: string, diagnostics?:
     case "font-smooth":
     case "-webkit-font-smoothing": props.fontSmoothing = val; break;
     case "font-subset": props.fontSubset = val; break;
-    case "line-height": props.lineHeight = val; break;
+    case "line-height":
+      if (/^\d+(?:\.\d+)?$/.test(val.trim())) {
+        warnValue("css-line-height", `line-height "${val}" — unitless multipliers are treated as px, not a multiple of the font size.`, `Write an explicit px value (e.g. line-height: 22px).`);
+      }
+      props.lineHeight = val;
+      break;
     case "letter-spacing": props.letterSpacing = val; break;
     case "white-space": props.whiteSpace = val; break;
     case "text-transform": props.textTransform = val; break;
@@ -907,7 +943,12 @@ function assignProp(props: CSSProperty, prop: string, val: string, diagnostics?:
     case "animation-delay": props.animationDelay = val; break;
     case "animation-timing-function": props.animationTimingFunction = val; break;
     // Flexbox / layout
-    case "display": props.display = val; break;
+    case "display":
+      if (["inline", "inline-block", "inline-flex", "grid", "flow-root", "table"].includes(val.trim().toLowerCase())) {
+        warnValue("css-display", `display: ${val.trim()} is not supported — elements stack vertically like a flex column (children use display:flex semantics).`, `Use the default stacking, or a row container with flex-direction: row + gap for inline flows.`);
+      }
+      props.display = val;
+      break;
     case "flex-direction": props.flexDirection = val; break;
     case "gap": props.gap = val; props.rowGap = val; props.columnGap = val; break;
     case "row-gap": props.rowGap = val; if (!props.columnGap) props.columnGap = val; break;
@@ -922,7 +963,12 @@ function assignProp(props: CSSProperty, prop: string, val: string, diagnostics?:
     case "justify-content": props.justifyContent = val; break;
     case "flex-wrap": props.flexWrap = val; break;
     case "order": props.order = val; break;
-    case "position": props.position = val; break;
+    case "position":
+      if (["fixed", "sticky"].includes(val.trim().toLowerCase())) {
+        warnValue("css-position", `position: ${val.trim()} is not supported — treated as static.`, `Use position: absolute (against the nearest ancestor) or keep flow layout.`);
+      }
+      props.position = val;
+      break;
     case "z-index": props.zIndex = val; break;
     case "top": props.top = val; break;
     case "right": props.right = val; break;
@@ -973,11 +1019,13 @@ function parseFlexShorthand(props: CSSProperty, val: string): void {
   }
 }
 
-/** Parse the `border` shorthand: "2px solid #808080" → width, style, color. */
+/** Parse the `border` shorthand: "2px solid #808080" → width, style, color.
+ *  Width accepts px, bare numbers (unitless = px), and decimals. */
 function parseBorderShorthand(props: CSSProperty, val: string): void {
   const parts = val.trim().split(/\s+/);
   for (const p of parts) {
-    if (/^\d+px$/.test(p)) props.borderWidth = p;
+    const w = /^(\d+(?:\.\d+)?)(?:px)?$/.exec(p);
+    if (w) props.borderWidth = `${w[1]}px`;
     else if (["solid", "dashed", "dotted", "double", "none"].includes(p)) props.borderStyle = p;
     // Color: #hex, rgb()/hsl(), a CSS named color, or a var() reference (the
     // token is substituted later by substituteVars, like other properties).
@@ -996,7 +1044,8 @@ function parsePerSideBorder(props: CSSProperty, prop: string, val: string): void
   const cKey = `border${cap}Color` as keyof CSSProperty;
   const parts = val.trim().split(/\s+/);
   for (const p of parts) {
-    if (/^\d+px$/.test(p)) (props[wKey] as string | undefined) = p;
+    const w = /^(\d+(?:\.\d+)?)(?:px)?$/.exec(p);
+    if (w) (props[wKey] as string | undefined) = `${w[1]}px`;
     else if (["solid", "dashed", "dotted", "double", "none"].includes(p)) (props[sKey] as string | undefined) = p;
     else if (p.startsWith("#") || p.startsWith("rgb") || p.startsWith("hsl") || p.startsWith("var(") || /^[a-z]+$/i.test(p)) (props[cKey] as string | undefined) = p;
   }

package/src/ui-engine/default-font.ts

@@ -0,0 +1,95 @@
+// ---------------------------------------------------------------------------
+// Default bundled font — DejaVu Sans 2.37 (Bitstream Vera License).
+//
+// Every color display gets an implicit @font-face pair (regular + bold) so
+// antialiased, continuously-sized text works out of the box: users don't have
+// to source a TTF before their UI renders like the browser preview. Devices
+// never receive the TTF itself — font-assets.ts rasterizes the exact
+// (family, px, weight, style, characters) subsets a UI uses into glyph tables.
+//
+// Monochrome displays (1-bit OLEDs/e-ink) keep the engine's built-in bitmap
+// font: alpha blending is disabled there, so rasterized AA glyphs add flash
+// cost without a visual payoff.
+//
+// License: the unmodified TTFs live in packages/ui/assets/fonts/dejavu with
+// the full text (LICENSE) and checksums (README.md). They must be redistributed
+// with that license file and must not be renamed or modified (Bitstream Vera
+// License reserved-name terms). Generated font tables carry an attribution
+// comment (see ui-lowering.ts emitFontTables).
+// ---------------------------------------------------------------------------
+
+import path from "node:path";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import type { CSSFontFace } from "./css-parser.js";
+
+/** The sans family the default faces register under. It matches the font's
+ *  real name (unmodified file, original name — license-clean). */
+export const DEFAULT_FONT_FAMILY = "DejaVu Sans";
+
+/** The monospace family for <pre>/<code>/<kbd> UA styling. */
+export const DEFAULT_MONO_FAMILY = "DejaVu Sans Mono";
+
+const FONT_DIR = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../../assets/fonts/dejavu",
+);
+
+/** Faces injected by default: sans + mono at the workhorse weights. */
+const DEFAULT_FACES: Array<{ family: string; file: string; weight: string; style: string }> = [
+  { family: DEFAULT_FONT_FAMILY, file: "DejaVuSans.ttf", weight: "400", style: "normal" },
+  { family: DEFAULT_FONT_FAMILY, file: "DejaVuSans-Bold.ttf", weight: "700", style: "normal" },
+  { family: DEFAULT_MONO_FAMILY, file: "DejaVuSansMono.ttf", weight: "400", style: "normal" },
+  { family: DEFAULT_MONO_FAMILY, file: "DejaVuSansMono-Bold.ttf", weight: "700", style: "normal" },
+];
+
+/** Absolute source paths of the bundled faces. */
+export function bundledFontPath(file: string): string {
+  return path.join(FONT_DIR, file);
+}
+
+/** True when the bundled font assets are present and usable. */
+export function defaultFontAvailable(): boolean {
+  return DEFAULT_FACES.every((f) => fs.existsSync(bundledFontPath(f.file)));
+}
+
+/** True when the display profile should use the bundled font. Color displays
+ *  only: monochrome targets keep the built-in bitmap font (no AA). An absent
+ *  profile defaults to color — the common case and the current build target. */
+export function defaultFontApplies(colorFormat: string | undefined): boolean {
+  return colorFormat !== "mono" && defaultFontAvailable();
+}
+
+/** The implicit @font-face declarations for the bundled default fonts. */
+export function defaultFontFaces(): CSSFontFace[] {
+  return DEFAULT_FACES.map((f) => ({
+    fontFamily: f.family,
+    src: bundledFontPath(f.file),
+    fontWeight: f.weight,
+    fontStyle: f.style,
+  }));
+}
+
+/** Merge the bundled default faces into a user's @font-face list. Checked
+ *  per family: if the author registered any face for "DejaVu Sans" (or the
+ *  mono family), theirs wins and that family's bundle faces are skipped.
+ *  Injected faces append so user faces sort first in weight/style matching. */
+export function injectDefaultFontFaces(userFaces: CSSFontFace[], colorFormat: string | undefined): CSSFontFace[] {
+  if (!defaultFontApplies(colorFormat)) return userFaces;
+  const declared = new Set(userFaces.map((f) => f.fontFamily.toLowerCase()));
+  const bundled = defaultFontFaces().filter(
+    (f) => !declared.has(f.fontFamily.toLowerCase()),
+  );
+  return bundled.length > 0 ? [...userFaces, ...bundled] : userFaces;
+}
+
+/** Attribution lines for generated font tables whose glyphs came from the
+ *  bundled DejaVu faces (satisfies the license's binary-notice requirement
+ *  and makes firmware images auditable). */
+export function defaultFontAttribution(sourcePath: string): string | undefined {
+  const resolved = path.resolve(sourcePath);
+  if (path.dirname(resolved) !== FONT_DIR) return undefined;
+  return `${path.basename(resolved)} - DejaVu fonts v2.37` +
+    " - (c) 2003 Bitstream, Inc., (c) 2006 Tavmjong Bah." +
+    " Bitstream Vera License - see @typecad/ui assets/fonts/dejavu/LICENSE.";
+}