@typecad/ui 0.1.0-alpha.1

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

@@ -0,0 +1,314 @@
+// ---------------------------------------------------------------------------
+// YogaLayoutEngine — flexbox layout via Facebook's Yoga engine.
+//
+// Implements the LayoutEngine interface using yoga-layout (WASM, ~2MB).
+// Handles display:flex, flex-direction, gap, align-self, padding (shorthand),
+// border, and content-sized leaf nodes. Falls back gracefully when flex
+// properties are absent.
+//
+// The critical contract: arrange() returns Box[] in pre-order DFS order
+// matching the StyledNode tree, so lowerUIToCpp's flatten() can index
+// boxes[] in lockstep with the styled nodes.
+// ---------------------------------------------------------------------------
+import { isDisplayNone, parseAspectRatio } from "./layout-engine.js";
+import Yoga from "yoga-layout";
+/** Parse the first numeric value from a CSS string ("8px", "8px 16px" → 8). */
+/** Parse a single CSS length to device pixels.
+ *  rem/em × 16 (root font size), px/bare as-is, decimals supported. */
+function cssLength(val) {
+    const v = val.trim();
+    const remM = /^(-?[\d.]+)rem$/.exec(v);
+    if (remM)
+        return Math.round(parseFloat(remM[1]) * 16);
+    const emM = /^(-?[\d.]+)em$/.exec(v);
+    if (emM)
+        return Math.round(parseFloat(emM[1]) * 16);
+    const m = /^(-?[\d.]+)(?:px|%)?$/.exec(v);
+    return m ? parseFloat(m[1]) : 0;
+}
+function cssNum(val) {
+    if (!val)
+        return 0;
+    return cssLength(val);
+}
+/** Parse horizontal padding from shorthand ("8px 16px" → 16 for left/right). */
+function cssPadH(val) {
+    if (!val)
+        return 0;
+    const parts = val.trim().split(/\s+/);
+    if (parts.length <= 1)
+        return cssLength(parts[0] ?? "0");
+    return cssLength(parts[1] ?? parts[0]);
+}
+/** Parse vertical padding from shorthand ("8px 16px" → 8 for top/bottom). */
+function cssPadV(val) {
+    if (!val)
+        return 0;
+    const parts = val.trim().split(/\s+/);
+    return cssLength(parts[0] ?? "0");
+}
+/** Parse border width from "2px solid #808080" → 2. */
+function cssBorderWidth(val) {
+    if (!val)
+        return 0;
+    // border shorthand: "<width> <style> <color>" — width is the first token.
+    const first = val.trim().split(/\s+/)[0];
+    return cssLength(first);
+}
+export class YogaLayoutEngine {
+    id = "flex";
+    arrange(root, viewport, measureFn) {
+        const metaArray = [];
+        // Build the Yoga tree from the StyledNode tree.
+        const yogaRoot = this.buildTree(root, metaArray, measureFn);
+        yogaRoot.setWidth(viewport.w);
+        yogaRoot.setHeight(viewport.h);
+        yogaRoot.calculateLayout(viewport.w, viewport.h, Yoga.DIRECTION_LTR);
+        // Extract boxes in pre-order DFS matching the StyledNode tree.
+        const boxes = [];
+        let extractIdx = 0;
+        this.extractBoxes(yogaRoot, boxes, () => metaArray[extractIdx++]);
+        return boxes;
+    }
+    /** Recursively build a Yoga node tree from a StyledNode tree. */
+    buildTree(node, metaArray, measureFn, myIndex = metaArray.length) {
+        const yn = Yoga.Node.create();
+        const idx = metaArray.length;
+        metaArray.push({ style: node.style });
+        const s = node.style;
+        if (isDisplayNone(node)) {
+            yn.setDisplay?.(Yoga.DISPLAY_NONE);
+        }
+        // Flex container
+        // flex-direction: row | row-reverse | column | column-reverse.
+        // Each value maps to a distinct Yoga enum (reverse was previously
+        // dropped — any non-"row" value collapsed to column).
+        const fd = s.display === "flex" ? s.flexDirection : "column";
+        if (fd === "row")
+            yn.setFlexDirection(Yoga.FLEX_DIRECTION_ROW);
+        else if (fd === "row-reverse")
+            yn.setFlexDirection(Yoga.FLEX_DIRECTION_ROW_REVERSE);
+        else if (fd === "column-reverse")
+            yn.setFlexDirection(Yoga.FLEX_DIRECTION_COLUMN_REVERSE);
+        else
+            yn.setFlexDirection(Yoga.FLEX_DIRECTION_COLUMN);
+        // Padding (all edges from shorthand, using the vertical value for uniformity)
+        const padV = cssPadV(s.padding);
+        const padH = cssPadH(s.padding);
+        if (padV || padH) {
+            yn.setPadding(Yoga.EDGE_TOP, padV);
+            yn.setPadding(Yoga.EDGE_BOTTOM, padV);
+            yn.setPadding(Yoga.EDGE_LEFT, padH);
+            yn.setPadding(Yoga.EDGE_RIGHT, padH);
+        }
+        // Margin: per-side overrides win over the `margin` shorthand when set.
+        const marginV = cssPadV(s.margin);
+        const marginH = cssPadH(s.margin);
+        const mTop = s.marginTop !== undefined ? cssLength(s.marginTop) : marginV;
+        const mBottom = s.marginBottom !== undefined ? cssLength(s.marginBottom) : marginV;
+        const mLeft = s.marginLeft !== undefined ? cssLength(s.marginLeft) : marginH;
+        const mRight = s.marginRight !== undefined ? cssLength(s.marginRight) : marginH;
+        if (mTop || mBottom || mLeft || mRight) {
+            yn.setMargin(Yoga.EDGE_TOP, mTop);
+            yn.setMargin(Yoga.EDGE_BOTTOM, mBottom);
+            yn.setMargin(Yoga.EDGE_LEFT, mLeft);
+            yn.setMargin(Yoga.EDGE_RIGHT, mRight);
+        }
+        // Gap: row-gap / column-gap are applied per-axis. Uniform `gap`
+        // (both equal) uses GUTTER_ALL for efficiency; mismatched values
+        // set GUTTER_ROW and GUTTER_COLUMN separately.
+        const rowGap = cssNum(s.rowGap);
+        const colGap = cssNum(s.columnGap);
+        if (rowGap && colGap && rowGap === colGap) {
+            yn.setGap(Yoga.GUTTER_ALL, rowGap);
+        }
+        else {
+            if (rowGap)
+                yn.setGap(Yoga.GUTTER_ROW, rowGap);
+            if (colGap)
+                yn.setGap(Yoga.GUTTER_COLUMN, colGap);
+        }
+        // Border
+        const borderW = cssBorderWidth(s.border);
+        if (borderW) {
+            yn.setBorder(Yoga.EDGE_ALL, borderW);
+        }
+        // Align-self
+        if (s.alignSelf === "flex-start")
+            yn.setAlignSelf(Yoga.ALIGN_FLEX_START);
+        else if (s.alignSelf === "center")
+            yn.setAlignSelf(Yoga.ALIGN_CENTER);
+        else if (s.alignSelf === "stretch")
+            yn.setAlignSelf(Yoga.ALIGN_STRETCH);
+        else if (s.alignSelf === "flex-end")
+            yn.setAlignSelf(Yoga.ALIGN_FLEX_END);
+        else if (s.alignSelf === "baseline")
+            yn.setAlignSelf(Yoga.ALIGN_BASELINE);
+        // Align-items / justify-content (container properties)
+        if (s.alignItems) {
+            if (s.alignItems === "flex-start")
+                yn.setAlignItems(Yoga.ALIGN_FLEX_START);
+            else if (s.alignItems === "center")
+                yn.setAlignItems(Yoga.ALIGN_CENTER);
+            else if (s.alignItems === "stretch")
+                yn.setAlignItems(Yoga.ALIGN_STRETCH);
+            else if (s.alignItems === "flex-end")
+                yn.setAlignItems(Yoga.ALIGN_FLEX_END);
+        }
+        // Align-content (multi-line flex-wrap cross-axis alignment)
+        if (s.alignContent) {
+            if (s.alignContent === "flex-start")
+                yn.setAlignContent(Yoga.ALIGN_FLEX_START);
+            else if (s.alignContent === "center")
+                yn.setAlignContent(Yoga.ALIGN_CENTER);
+            else if (s.alignContent === "flex-end")
+                yn.setAlignContent(Yoga.ALIGN_FLEX_END);
+            else if (s.alignContent === "stretch")
+                yn.setAlignContent(Yoga.ALIGN_STRETCH);
+            else if (s.alignContent === "space-between")
+                yn.setAlignContent(Yoga.ALIGN_SPACE_BETWEEN);
+            else if (s.alignContent === "space-around")
+                yn.setAlignContent(Yoga.ALIGN_SPACE_AROUND);
+            else if (s.alignContent === "space-evenly")
+                yn.setAlignContent(Yoga.ALIGN_SPACE_EVENLY);
+        }
+        if (s.justifyContent) {
+            if (s.justifyContent === "flex-start")
+                yn.setJustifyContent(Yoga.JUSTIFY_FLEX_START);
+            else if (s.justifyContent === "center")
+                yn.setJustifyContent(Yoga.JUSTIFY_CENTER);
+            else if (s.justifyContent === "flex-end")
+                yn.setJustifyContent(Yoga.JUSTIFY_FLEX_END);
+            else if (s.justifyContent === "space-between")
+                yn.setJustifyContent(Yoga.JUSTIFY_SPACE_BETWEEN);
+            else if (s.justifyContent === "space-around")
+                yn.setJustifyContent(Yoga.JUSTIFY_SPACE_AROUND);
+            else if (s.justifyContent === "space-evenly")
+                yn.setJustifyContent(Yoga.JUSTIFY_SPACE_EVENLY);
+        }
+        // Flex wrap
+        if (s.flexWrap === "wrap")
+            yn.setFlexWrap(Yoga.WRAP_WRAP);
+        else if (s.flexWrap === "wrap-reverse")
+            yn.setFlexWrap(Yoga.WRAP_WRAP_REVERSE);
+        else if (s.flexWrap === "nowrap")
+            yn.setFlexWrap(Yoga.WRAP_NO_WRAP);
+        // Flex grow/shrink/basis
+        if (s.flexGrow)
+            yn.setFlexGrow(cssNum(s.flexGrow));
+        if (s.flexShrink)
+            yn.setFlexShrink(cssNum(s.flexShrink));
+        if (s.flexBasis) {
+            const basis = cssNum(s.flexBasis);
+            if (s.flexBasis === "auto")
+                yn.setFlexBasisAuto();
+            else
+                yn.setFlexBasis(basis);
+        }
+        // Order (Yoga may not expose setOrder in its types, but the runtime has it)
+        if (s.order)
+            yn.setOrder?.(cssNum(s.order));
+        // Min/max dimensions
+        if (s.minWidth)
+            yn.setMinWidth(cssNum(s.minWidth));
+        if (s.maxWidth)
+            yn.setMaxWidth(cssNum(s.maxWidth));
+        if (s.minHeight)
+            yn.setMinHeight(cssNum(s.minHeight));
+        if (s.maxHeight)
+            yn.setMaxHeight(cssNum(s.maxHeight));
+        // Box sizing
+        if (s.boxSizing === "border-box")
+            yn.setBoxSizing?.(Yoga.BOX_SIZING_BORDER_BOX);
+        // Overflow
+        if (s.overflow === "hidden")
+            yn.setOverflow?.(Yoga.OVERFLOW_HIDDEN);
+        else if (s.overflow === "scroll")
+            yn.setOverflow?.(Yoga.OVERFLOW_SCROLL);
+        // Position
+        if (s.position === "relative")
+            yn.setPositionType(Yoga.POSITION_TYPE_RELATIVE);
+        else if (s.position === "absolute")
+            yn.setPositionType(Yoga.POSITION_TYPE_ABSOLUTE);
+        else
+            yn.setPositionType(Yoga.POSITION_TYPE_STATIC);
+        if (s.top !== undefined)
+            yn.setPosition(Yoga.EDGE_TOP, cssNum(s.top));
+        if (s.right !== undefined)
+            yn.setPosition(Yoga.EDGE_RIGHT, cssNum(s.right));
+        if (s.bottom !== undefined)
+            yn.setPosition(Yoga.EDGE_BOTTOM, cssNum(s.bottom));
+        if (s.left !== undefined)
+            yn.setPosition(Yoga.EDGE_LEFT, cssNum(s.left));
+        // Width/height (explicit)
+        if (s.width)
+            yn.setWidth(cssNum(s.width));
+        if (s.height)
+            yn.setHeight(cssNum(s.height));
+        const aspectRatio = parseAspectRatio(s.aspectRatio);
+        if (aspectRatio !== undefined)
+            yn.setAspectRatio(aspectRatio);
+        // Children. The yoga binding in use has no setOrder API, so CSS `order`
+        // can't be applied via yoga — sort children by their order value first
+        // (stable sort: source order preserved for equal order) so the flex engine
+        // lays items out in their order sequence.
+        const orderedChildren = [...node.children].sort((a, b) => {
+            const ao = cssNum(a.style.order);
+            const bo = cssNum(b.style.order);
+            return ao - bo;
+        });
+        // Build yoga nodes in the sorted (visual) order so yoga positions them by
+        // order, but record the SOURCE index of each so extractBoxes can emit boxes
+        // in source-tree order (the contract lowerUIToModel relies on).
+        for (let si = 0; si < orderedChildren.length; si++) {
+            const child = orderedChildren[si];
+            const sourceIndex = node.children.indexOf(child);
+            const childNode = this.buildTree(child, metaArray, measureFn);
+            // Tag the yoga node with its source index so extraction can reorder.
+            childNode.__sourceIndex = sourceIndex;
+            yn.insertChild(childNode, yn.getChildCount());
+        }
+        // Leaf nodes with text: let Yoga pass available width into measurement so
+        // wrapped text can expand height under constraints.
+        if (node.children.length === 0) {
+            const textLike = node.tag === "text" || node.tag === "button" || node.tag === "check" || node.tag === "radio";
+            if (textLike) {
+                yn.setMeasureFunc((width, widthMode) => {
+                    const hasWidth = widthMode !== Yoga.MEASURE_MODE_UNDEFINED && Number.isFinite(width) && width > 0;
+                    const intrinsic = measureFn(node, hasWidth ? width : undefined);
+                    return {
+                        width: Math.ceil(intrinsic.w),
+                        height: Math.ceil(intrinsic.h),
+                    };
+                });
+            }
+            else {
+                const intrinsic = measureFn(node);
+                const childPadV = cssPadV(s.padding);
+                const childPadH = cssPadH(s.padding);
+                const childBorder = cssBorderWidth(s.border);
+                if (!s.width && intrinsic.w > 0) {
+                    yn.setWidth(Math.ceil(intrinsic.w + childPadH * 2 + childBorder * 2));
+                }
+                if (!s.height && intrinsic.h > 0) {
+                    yn.setHeight(intrinsic.h + childPadV * 2 + childBorder * 2);
+                }
+            }
+        }
+        return yn;
+    }
+    /** Walk the Yoga tree in pre-order DFS, extracting absolute {x,y,w,h} per node.
+     * Yoga returns positions relative to the parent — we accumulate parentX/Y
+     * to produce absolute coordinates. Must match the StyledNode tree's DFS. */
+    extractBoxes(node, out, nextMeta, parentX = 0, parentY = 0) {
+        const x = parentX + Math.round(node.getComputedLeft());
+        const y = parentY + Math.round(node.getComputedTop());
+        const w = Math.round(node.getComputedWidth());
+        const h = Math.round(node.getComputedHeight());
+        out.push({ x, y, w, h });
+        nextMeta();
+        for (let i = 0; i < node.getChildCount(); i++) {
+            this.extractBoxes(node.getChild(i), out, nextMeta, x, y);
+        }
+    }
+}

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@typecad/ui",
+  "version": "0.1.0-alpha.1",
+  "description": "TypeCAD UI authoring library — HTML/CSS-driven graphics for microcontrollers",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./engine": {
+      "types": "./dist/engine-index.d.ts",
+      "default": "./dist/engine-index.js"
+    },
+    "./runtime-header": {
+      "types": "./dist/ui-engine/runtime-header.d.ts",
+      "default": "./dist/ui-engine/runtime-header.js"
+    },
+    "./ui-engine/*": {
+      "types": "./dist/ui-engine/*.d.ts",
+      "default": "./dist/ui-engine/*.js"
+    },
+    "./preview/*": {
+      "types": "./dist/preview/*.d.ts",
+      "default": "./dist/preview/*.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src"
+  ],
+  "peerDependencies": {
+    "@typecad/cuttlefish": "0.1.0-alpha.1"
+  },
+  "dependencies": {
+    "css-tree": "^3.2.1",
+    "linkedom": "^0.18.12",
+    "opentype.js": "^2.0.0",
+    "yoga-layout": "^3.2.1"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/justind000/typecode.git",
+    "directory": "packages/ui"
+  },
+  "homepage": "https://github.com/justind000/typecode/tree/main/packages/ui",
+  "bugs": {
+    "url": "https://github.com/justind000/typecode/issues"
+  },
+  "keywords": [
+    "arduino",
+    "embedded",
+    "microcontroller",
+    "esp32",
+    "tft",
+    "ili9341",
+    "ui",
+    "html",
+    "css",
+    "gui",
+    "typecad",
+    "cuttlefish",
+    "typescript",
+    "cpp",
+    "firmware"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "@types/opentype.js": "^1.3.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "typecad0"
+}

package/src/engine-index.ts

@@ -0,0 +1,51 @@
+// ---------------------------------------------------------------------------
+// Engine entry point for @typecad/ui.
+//
+// Cuttlefish dynamically imports this module when UI usage is detected:
+//   const engine = await import("@typecad/ui/engine");
+//   const hook = await engine.registerTranspilerUI();
+//
+// registerTranspilerUI() returns an object implementing the TranspilerUIHook
+// interface defined in @typecad/cuttlefish. This is the single runtime
+// contract between the two packages.
+// ---------------------------------------------------------------------------
+
+import type { TranspilerUIHook } from "@typecad/cuttlefish/ui-hook";
+import {
+  resetUIRegistry, loadUIModule, loadUIModuleFromText, getUIModule,
+  hasUIModule, allUIModules, allLoweredUIModules,
+  markEntryHasUI, entryHasUI, clearEntryHasUI, lowerOnMount,
+  generateProjectUITypeDeclarations,
+} from "./ui-engine/ui-registry.js";
+import { resolveColor, resolveColorInternal } from "./ui-engine/color.js";
+import { emitRuntimeHeader } from "./ui-engine/runtime-header.js";
+import { splitUiFile } from "./ui-engine/ui-file-splitter.js";
+import { analyzeScrollMemory } from "./ui-engine/scroll-memory-diagnostics.js";
+
+export type { TranspilerUIHook };
+
+/**
+ * Build and return the TranspilerUIHook — the object cuttlefish core uses
+ * to access all UI capabilities (parsing, layout, lowering, emission).
+ */
+export function registerTranspilerUI(): TranspilerUIHook {
+  return {
+    resetUIRegistry,
+    loadUIModule,
+    loadUIModuleFromText,
+    getUIModule,
+    hasUIModule,
+    allUIModules,
+    allLoweredUIModules,
+    markEntryHasUI,
+    entryHasUI,
+    clearEntryHasUI,
+    lowerOnMount,
+    resolveColor,
+    resolveColorInternal,
+    emitRuntimeHeader,
+    splitUiFile,
+    generateProjectUITypeDeclarations,
+    analyzeScrollMemory,
+  };
+}

package/src/index.ts

@@ -0,0 +1,232 @@
+// ---------------------------------------------------------------------------
+// @typecad/ui — public authoring API.
+//
+// These functions are compile-time constructs: the transpiler intercepts
+// ui.mount / ui.signal / ui.bind and lowers them to device variables and
+// binding-table entries. They have no runtime implementation in the emitted
+// C++; their bodies exist only so TypeScript authoring type-checks.
+// ---------------------------------------------------------------------------
+
+export type { ScreenTree, TextElement, ButtonElement, ViewElement, PressBinding, CheckElement, SelectElement, RadioElement, ProgressElement, RangeElement, InputElement, CanvasElement, CanvasCtx } from "./types.js";
+import type { ScreenTree, CanvasCtx } from "./types.js";
+
+/** Allowed signal value types. The transpiler lowers each of these to a C++
+ *  scalar: `number` → int/double, `string` → const char*, `boolean` → bool.
+ *  Other types (objects, arrays, null) are rejected at type-check time by
+ *  Signal<T extends SignalValue> and at build time by the `ui-signal-initializer`
+ *  diagnostic. */
+export type SignalValue = number | string | boolean;
+
+/** A reactive signal whose value lives on the device. */
+export interface Signal<T extends SignalValue> {
+  (): T;
+  set(value: T): void;
+}
+
+export interface MountOptions {
+  /** Display driver id (must be in the framework's supportedDisplayDrivers()). */
+  display?: string;
+  /** Bus identifier, e.g. "SPI" or "Wire". */
+  bus?: string;
+  /** Chip-select pin. */
+  cs?: number;
+  /** Data/command pin. */
+  dc?: number;
+  /** Reset pin. */
+  rst?: number;
+  /** Rotation override. Defaults to the project display profile. */
+  rotation?: number;
+  /** Backlight pin override. Defaults to the project display profile. */
+  backlight?: number;
+  /** SPI frequency override. Defaults to the project display profile. */
+  spiFrequency?: number;
+  /** I2C address override for I2C displays. Defaults to the project display profile. */
+  address?: number;
+  /** Reset pin override for I2C displays. Defaults to the project display profile. */
+  reset?: number;
+}
+
+/**
+ * Mount a baked UI tree to the display configured in `cuttlefish.config.ts`.
+ * Optional overrides are available for advanced cases, but ordinary apps should
+ * keep hardware setup in the project config and call `ui.mount(screen)`.
+ *
+ * Validates the driver against the active framework at transpile time
+ * (fail-fast). The tree is lowered to a static C++ node table; this call lowers
+ * to display.init + the first-frame draw.
+ *
+ * `tree` is typed loosely (a record of element handles) so the concrete
+ * ScreenTree interface generated per .ui.html file — which has concrete named
+ * fields rather than an index signature — is assignable. The transpiler
+ * intercepts the call structurally; the type only needs to permit it.
+ */
+export declare function mount(tree: unknown, opts?: MountOptions): void;
+
+/**
+ * Declare a reactive signal. Lowers to a plain device variable + dirty flag.
+ *
+ * Accepts `number`, `string`, or `boolean` literals. Literal values are widened
+ * to their primitive type so `ui.signal(0)` returns `Signal<number>` (and
+ * `.set(1)` works), not `Signal<0>`. Other types (objects, arrays, null) are
+ * rejected at type-check time and at build time with a `ui-signal-initializer`
+ * diagnostic.
+ */
+export declare function signal(initial: number): Signal<number>;
+export declare function signal(initial: string): Signal<string>;
+export declare function signal(initial: boolean): Signal<boolean>;
+
+/**
+ * Bind a node property to a computed value, re-evaluated each tick. When the
+ * value changes, the node is marked dirty and (for transition-able properties)
+ * the transition is armed.
+ */
+export declare function bind<K extends string>(
+  node: unknown,
+  property: K,
+  compute: () => unknown,
+): void;
+
+/**
+ * Subscribe to changes on an `<input>` element's text. The callback fires after
+ * the on-screen keyboard commits, with the new text. Use it to push keyboard
+ * input back into app state.
+ *
+ *   let ssid = '';
+ *   ui.bindInput(screen.ssid, (text) => { ssid = text; });
+ */
+export declare function bindInput(node: unknown, onText: (text: string) => void): void;
+
+/**
+ * Watch a GPIO pin for falling edges (button press). The callback runs as an
+ * async task in the existing microtask pump — no ISRs, natural debounce from
+ * the ~20ms poll interval. Safe to write to signals inside the callback.
+ *
+ *   ui.watchPin(4, () => { count.set(count() + 1); });
+ */
+export declare function watchPin(pin: number, onFalling: () => void): void;
+
+/**
+ * Bind a `<list>` element to dynamic data via two callbacks.
+ *
+ *   ui.bindList(screen.myList,
+ *     () => itemCount,          // total number of items
+ *     (i) => `Item ${i}`        // text for item at index i
+ *   );
+ *
+ * The list virtualizes: only visible items are rendered. Scroll by dragging.
+ * The count function is called each frame; if the count changes, the list
+ * refreshes automatically.
+ */
+export declare function bindList(
+  node: unknown,
+  countFn: () => number,
+  itemFn: (index: number) => string,
+  onTap?: (index: number) => void,
+): void;
+
+/**
+ * Await the next tap. Must be used inside an `async` function.
+ *
+ *   async function screensaver() {
+ *     while (true) {
+ *       await ui.onTap();       // resume on the next tap, anywhere
+ *       backlightOn();
+ *     }
+ *   }
+ *
+ * With no argument it resumes on the next tap on the screen (including empty
+ * space — useful for "wake on any touch"). Pass an element to resume only when
+ * that element is tapped:
+ *
+ *   await ui.onTap(screen.btn);
+ *
+ * A tap fires BOTH the tapped element's onClick handler AND resumes any
+ * `await ui.onTap()` awaiter. Returns a Promise<void>; it is a resume signal,
+ * not a value — there is nothing to read from it.
+ */
+export declare function onTap(node?: unknown): Promise<void>;
+
+/**
+ * Register a draw callback for a `<canvas>` element. The callback runs every
+ * frame and receives a `ctx` whose methods map to the display graphics
+ * primitives. Coordinates are canvas-relative ((0,0) = top-left of the element);
+ * drawing is clipped to the canvas buffer.
+ *
+ *   ui.drawCanvas(screen.spark, (ctx) => {
+ *     ctx.fillScreen('black');
+ *     ctx.line(0, ctx.height / 2, ctx.width, ctx.height / 2, 'limegreen');
+ *     ctx.fillCircle(needleX, 20, 3, 'red');
+ *     ctx.text(4, 12, `${temp}°`, 'white');
+ *   });
+ *
+ * Color arguments are CSS color strings resolved to RGB565 at transpile time.
+ * `ctx.width` / `ctx.height` are the canvas buffer dimensions.
+ */
+export declare function drawCanvas(node: unknown, callback: (ctx: CanvasCtx) => void): void;
+
+/**
+ * Native desktop (SDL) window controls. These are no-ops on hardware targets
+ * (Arduino/AVR/ESP32 have no window); on the SDL target they map to the
+ * underlying SDL window calls. The initial title/icon come from
+ * `cuttlefish.config.ts` (`display.title` / `display.icon`); these methods
+ * change them at runtime.
+ */
+export interface WindowApi {
+  /** Set the OS window title. Native SDL only; no-op on hardware. */
+  setTitle(title: string): void;
+  /**
+   * Set the window/taskbar icon from an image file path. Native SDL only.
+   * Note: runtime icon changes require SDL_image; prefer the `display.icon`
+   * config option for the common case (loaded once at launch).
+   */
+  setIcon(path: string): void;
+}
+
+// ---------------------------------------------------------------------------
+// Runtime fallback.
+//
+// Every function above is a compile-time construct: the @typecad/cuttlefish
+// transpiler intercepts `ui.mount` / `ui.signal` / `ui.bind` / ... calls and
+// lowers them to device variables and binding-table entries, so these bodies
+// never run on the device. But the package still has to be importable from
+// plain Node (editor language servers, the test runner, tooling) without
+// crashing, and a forgotten build step should fail loudly rather than silently
+// no-op. Each fallback throws an explicit "compile-time construct" error.
+//
+// The signatures intentionally match the `export declare function` contracts
+// above so the public type surface is unchanged.
+// ---------------------------------------------------------------------------
+
+const COMPILE_TIME_ERROR = () => {
+  throw new Error(
+    "@typecad/ui: this function is a compile-time construct. It must be " +
+      "lowered by the @typecad/cuttlefish transpiler at build time, not " +
+      "called at runtime.",
+  );
+};
+
+export const ui: {
+  mount: typeof mount;
+  signal: typeof signal;
+  bind: typeof bind;
+  bindInput: typeof bindInput;
+  bindList: typeof bindList;
+  watchPin: typeof watchPin;
+  onTap: typeof onTap;
+  drawCanvas: typeof drawCanvas;
+  window: WindowApi;
+} = {
+  mount: COMPILE_TIME_ERROR,
+  signal: COMPILE_TIME_ERROR,
+  bind: COMPILE_TIME_ERROR,
+  bindInput: COMPILE_TIME_ERROR,
+  bindList: COMPILE_TIME_ERROR,
+  watchPin: COMPILE_TIME_ERROR,
+  onTap: COMPILE_TIME_ERROR,
+  drawCanvas: COMPILE_TIME_ERROR,
+  window: {
+    setTitle: COMPILE_TIME_ERROR,
+    setIcon: COMPILE_TIME_ERROR,
+  },
+};
+export default ui;