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

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

@@ -7,15 +7,26 @@
 // This is the fallback when no `display: flex` is present. YogaLayoutEngine
 // handles flexbox layouts.
 // ---------------------------------------------------------------------------
-import { isDisplayNone, parseAspectRatio } from "./layout-engine.js";
-/** Parse a CSS value string ("8px", "8") to a number. */
+import { isDisplayNone, parseAspectRatio, cssDimValue, expandBoxShorthand } from "./layout-engine.js";
+/** 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) {
     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, total) {
+    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 {
     id = "block";
@@ -32,12 +43,15 @@ export class BlockLayoutEngine {
         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 = {
-            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;
         for (const child of node.children) {
@@ -55,8 +69,8 @@ export class BlockLayoutEngine {
                 ? 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/dist/ui-engine/color.d.ts

@@ -3,6 +3,12 @@ export interface RGB {
     g: number;
     b: number;
 }
+/** Is this color fully transparent (the `transparent` keyword, alpha-0 rgba/
+ *  hsla, or #rrggbb00)? Callers treat it as "no fill" rather than black. */
+export declare function isTransparentColor(input: string): boolean;
+/** 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 declare function hasIgnoredAlpha(input: string): boolean;
 /** Parse any CSS color string to {r,g,b}. Alpha is ignored (no blending). */
 export declare function parseColor(input: string): RGB;
 /** @deprecated Use parseColor instead — parseHexColor only handles #rrggbb. */

package/dist/ui-engine/color.js

@@ -85,8 +85,41 @@ const NAMED_COLORS = {
     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) {
+    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) {
+    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) {
     const s = input.trim().toLowerCase();
@@ -136,7 +169,52 @@ export function parseColor(input) {
     // 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, c, h) {
+    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) => {
+        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. */
 function hslToRgb(h, s, l) {

package/dist/ui-engine/compat-report.d.ts

@@ -0,0 +1,8 @@
+import type { Diagnostic } from "@typecad/cuttlefish/api/shared";
+import type { StyledNode } from "./style-resolver.js";
+import type { UIFontAssetModel } from "./font-assets.js";
+/** Produce CSS-compatibility diagnostics for the lowered tree. */
+export declare function cssCompatDiagnostics(screens: StyledNode[], fontAssets: UIFontAssetModel[], viewport: {
+    width: number;
+    height: number;
+}, colorFormat: string | undefined, sourceFile: string): Diagnostic[];

package/dist/ui-engine/compat-report.js

@@ -0,0 +1,124 @@
+// ---------------------------------------------------------------------------
+// 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 { 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",
+];
+/** 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) {
+    if (px <= 12)
+        return "1–12";
+    if (px <= 20)
+        return "13–20";
+    if (px <= 28)
+        return "21–28";
+    return "29+";
+}
+function labelOf(node) {
+    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, fontAssets, viewport, colorFormat, sourceFile) {
+    const out = [];
+    const seen = new Set();
+    const push = (key, d) => {
+        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) => {
+        const style = node.style;
+        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/dist/ui-engine/css-imports.d.ts

@@ -0,0 +1,4 @@
+/** 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 declare function expandCssImports(cssText: string, baseDir: string, seen?: Set<string>): string;

package/dist/ui-engine/css-imports.js

@@ -0,0 +1,70 @@
+// ---------------------------------------------------------------------------
+// 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, baseDir) {
+    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, baseDir, seen = new Set()) {
+    return cssText.replace(IMPORT_RE, (match, spec) => {
+        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;
+        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;
+        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/dist/ui-engine/css-parser.js

@@ -279,16 +279,23 @@ function resolveCalc(value) {
     return out;
 }
 /** 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) {
     // 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) => {
         const remM = /^(-?[\d.]+)rem$/.exec(tok);
@@ -728,10 +735,12 @@ function parseFontShorthand(props, val) {
     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) {
@@ -743,12 +752,18 @@ function parseFontShorthand(props, val) {
     }
 }
 /** 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, prop, val, diagnostics) {
     const warn = (message, hint) => {
         if (diagnostics)
             diagnostics.push({ severity: "warning", message, hint, code: "unknown-css-property", source: prop });
     };
+    const warnValue = (code, message, hint) => {
+        if (diagnostics)
+            diagnostics.push({ severity: "warning", message, hint, code, source: prop });
+    };
     switch (prop) {
         // Box model
         case "padding":
@@ -791,6 +806,9 @@ function assignProp(props, prop, val, diagnostics) {
             props.aspectRatio = 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":
@@ -812,9 +830,23 @@ function assignProp(props, prop, val, diagnostics) {
         case "font-family":
             props.fontFamily = val;
             break;
-        case "font-size":
-            props.fontSize = val;
+        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;
@@ -836,6 +868,9 @@ function assignProp(props, prop, val, diagnostics) {
             props.fontSubset = 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":
@@ -874,6 +909,9 @@ function assignProp(props, prop, val, diagnostics) {
             break;
         // Flexbox / layout
         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":
@@ -925,6 +963,9 @@ function assignProp(props, prop, val, diagnostics) {
             props.order = 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":
@@ -1023,12 +1064,14 @@ function parseFlexShorthand(props, val) {
             props.flexBasis = parts[2];
     }
 }
-/** 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, val) {
     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
@@ -1048,8 +1091,9 @@ function parsePerSideBorder(props, prop, val) {
     const cKey = `border${cap}Color`;
     const parts = val.trim().split(/\s+/);
     for (const p of parts) {
-        if (/^\d+px$/.test(p))
-            props[wKey] = p;
+        const w = /^(\d+(?:\.\d+)?)(?:px)?$/.exec(p);
+        if (w)
+            props[wKey] = `${w[1]}px`;
         else if (["solid", "dashed", "dotted", "double", "none"].includes(p))
             props[sKey] = p;
         else if (p.startsWith("#") || p.startsWith("rgb") || p.startsWith("hsl") || p.startsWith("var(") || /^[a-z]+$/i.test(p))

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

@@ -0,0 +1,25 @@
+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 declare const DEFAULT_FONT_FAMILY = "DejaVu Sans";
+/** The monospace family for <pre>/<code>/<kbd> UA styling. */
+export declare const DEFAULT_MONO_FAMILY = "DejaVu Sans Mono";
+/** Absolute source paths of the bundled faces. */
+export declare function bundledFontPath(file: string): string;
+/** True when the bundled font assets are present and usable. */
+export declare function defaultFontAvailable(): boolean;
+/** 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 declare function defaultFontApplies(colorFormat: string | undefined): boolean;
+/** The implicit @font-face declarations for the bundled default fonts. */
+export declare function defaultFontFaces(): CSSFontFace[];
+/** 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 declare function injectDefaultFontFaces(userFaces: CSSFontFace[], colorFormat: string | undefined): CSSFontFace[];
+/** 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 declare function defaultFontAttribution(sourcePath: string): string | undefined;

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

@@ -0,0 +1,80 @@
+// ---------------------------------------------------------------------------
+// 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";
+/** 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 = [
+    { 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) {
+    return path.join(FONT_DIR, file);
+}
+/** True when the bundled font assets are present and usable. */
+export function defaultFontAvailable() {
+    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) {
+    return colorFormat !== "mono" && defaultFontAvailable();
+}
+/** The implicit @font-face declarations for the bundled default fonts. */
+export function defaultFontFaces() {
+    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, colorFormat) {
+    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) {
+    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.";
+}