@typecad/ui 0.1.0-alpha.1

package/src/ui-engine/runtime-header/scroll-physics.ts

@@ -0,0 +1,161 @@
+// Slice of the C++ runtime header (original source lines 1000-1154).
+// Scroll input + physics layer, framebuffer get/push.
+// See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
+export function emitScrollPhysics(): string {
+  return `
+// ── Scroll engine: Input layer ───────────────────────────────────────────────
+// raw touch sample → smoothed delta (dy). Capacitive: passthrough 1:1.
+// Resistive: deadband suppresses sub-N-px jitter (steady drag still 1:1).
+// 'none' tier compiles drag scroll out entirely.
+static int16_t __ui_scroll_prev_dy = 0;  // last smoothed delta (low-pass state)
+
+static inline int16_t ui_scroll_scale_dy(int16_t dy) {
+  int32_t scaled = (int32_t)dy * (int32_t)UI_SCROLL_DRAG_SCALE_X10;
+  return (int16_t)(scaled >= 0 ? (scaled + 5) / 10 : (scaled - 5) / 10);
+}
+
+static inline int16_t ui_scroll_smooth_dy(int16_t dy) {
+#if UI_SCROLL_INPUT_TIER_CAPACITIVE
+  __ui_scroll_prev_dy = dy;
+  return ui_scroll_scale_dy(dy);
+#elif UI_SCROLL_INPUT_TIER_RESISTIVE
+  int16_t db = (int16_t)UI_SCROLL_DEADBAND_PX;
+  if (dy >= -db && dy <= db) {
+    // Deadband: kill per-sample jitter around zero. Steady drag (|dy|>db) below
+    // passes through unchanged, so steady-state is 1:1 (spec Q1).
+    __ui_scroll_prev_dy = 0;
+    return 0;
+  }
+  __ui_scroll_prev_dy = dy;
+  return ui_scroll_scale_dy(dy);
+#else
+  (void)dy;
+  return 0;
+#endif
+}
+
+// ── Scroll engine: Physics layer ─────────────────────────────────────────────
+// 1:1 in bounds; rubber-band at edges; bounce-back/snap on release. No fling.
+// On constrained render tiers (no elastic), overscroll is hard-clamped away.
+
+static inline int16_t ui_scroll_max(int16_t node) {
+  if (node < 0) return 0;
+  int16_t m = __ui_nodes[node].contentHeight - __ui_nodes[node].box.h;
+  return m < 0 ? 0 : m;
+}
+
+// Rubber-band excursion for d cumulative pixels dragged past a boundary.
+// r = maxOverscroll * d / (d + stiffness). stiffness held as X10 fixed-point.
+static inline int16_t ui_scroll_overscroll_for(int16_t d) {
+  if (d <= 0) return 0;
+  int16_t maxOv = (int16_t)UI_SCROLL_MAX_OVERSCROLL;
+  int16_t stiffX10 = (int16_t)UI_SCROLL_STIFFNESS_X10;
+  if (stiffX10 <= 0) stiffX10 = 1;
+  int32_t r = ((int32_t)maxOv * (int32_t)d) / ((int32_t)d + (int32_t)stiffX10);
+  return r > maxOv ? maxOv : (int16_t)r;
+}
+
+// Apply a smoothed drag delta to the owning scroll node. Returns 1 if the view
+// changed (needs redraw). Sets overscrollPx for rubber-band excursions; scrollY
+// itself never leaves [0, maxScroll] so the committed position stays valid.
+static inline uint8_t ui_apply_scroll_delta(int16_t node, int16_t dy) {
+  if (node < 0 || dy == 0) return 0;
+  int16_t sy = __ui_nodes[node].scrollY;
+  int16_t maxS = ui_scroll_max(node);
+  int16_t nextY = sy - dy;
+  int16_t prevOv = __ui_nodes[node].overscrollPx;
+  int16_t nextOv = prevOv;
+  if (nextY < 0) {
+    __ui_nodes[node].scrollY = 0;
+    // Cumulative drag past the top boundary since crossing it.
+    int16_t draggedPast = dy - sy;            // how far past 0 this delta pushed
+    int16_t cum = prevOv + draggedPast;
+    if (cum < 0) cum = 0;
+#if UI_SCROLL_ELASTIC
+    nextOv = ui_scroll_overscroll_for(cum);
+#else
+    nextOv = 0;
+#endif
+  } else if (nextY > maxS) {
+    __ui_nodes[node].scrollY = maxS;
+    int16_t draggedPast = nextY - maxS;
+    int16_t cum = (prevOv < 0 ? -prevOv : 0) + draggedPast;  // prevOv<0 = bottom
+    if (cum < 0) cum = 0;
+#if UI_SCROLL_ELASTIC
+    nextOv = -ui_scroll_overscroll_for(cum);   // negative = bottom overshoot
+#else
+    nextOv = 0;
+#endif
+  } else {
+    __ui_nodes[node].scrollY = nextY;
+    nextOv = 0;                                 // returned in-bounds → reset
+  }
+  __ui_nodes[node].overscrollPx = nextOv;
+  uint8_t changed = (__ui_nodes[node].scrollY != sy) || (nextOv != prevOv);
+  if (changed) ui_mark_scroll_view_dirty((uint16_t)node);
+  return changed;
+}
+
+// On release: arm a bounded settle animation — bounce overscroll back to 0, or
+// edge-snap scrollY within edgeSnapPx. The animation runs in ui_tick.
+static inline uint8_t ui_scroll_release(int16_t node) {
+  if (node < 0) return 0;
+  uint8_t changed = 0;
+  if (__ui_nodes[node].overscrollPx != 0) {
+    __ui_nodes[node].settling = 1;
+    __ui_settle_from_overscroll = __ui_nodes[node].overscrollPx;
+    __ui_settle_from_scrollY = 0;
+    __ui_settle_start_ms = millis();
+    changed = 1;
+  } else {
+    int16_t sy = __ui_nodes[node].scrollY;
+    int16_t maxS = ui_scroll_max(node);
+    int16_t snap = (int16_t)UI_SCROLL_EDGE_SNAP_PX;
+    if (sy > 0 && sy <= snap) {
+      __ui_nodes[node].settling = 1;
+      __ui_settle_from_scrollY = sy;            // positive → snap toward 0
+      __ui_settle_from_overscroll = 0;
+      __ui_settle_start_ms = millis();
+      changed = 1;
+    } else if (maxS > 0 && sy < maxS && sy >= maxS - snap) {
+      __ui_nodes[node].settling = 1;
+      __ui_settle_from_scrollY = sy - maxS;     // negative → snap toward max
+      __ui_settle_from_overscroll = 0;
+      __ui_settle_start_ms = millis();
+      changed = 1;
+    }
+  }
+  return changed;
+}
+
+// Advance the settle animation for a node (called from ui_tick). Ease-out over
+// UI_SCROLL_SETTLE_MS, terminating at the boundary. Bounded — always ends.
+static inline void ui_scroll_advance_settle(uint8_t node, uint16_t deltaMs) {
+  (void)deltaMs;
+  if (node >= __ui_node_count || !__ui_nodes[node].settling) return;
+  uint32_t elapsed = millis() - __ui_settle_start_ms;
+  uint16_t dur = (uint16_t)UI_SCROLL_SETTLE_MS;
+  // ease-out: k = 1 - (1 - t)^2, t in [0,1]
+  uint32_t t = elapsed >= dur ? 100 : (elapsed * 100) / dur;
+  uint32_t k = 100 - ((100 - t) * (100 - t)) / 100;
+  if (__ui_nodes[node].overscrollPx != 0) {
+    int16_t from = __ui_settle_from_overscroll;
+    __ui_nodes[node].overscrollPx = (int16_t)(from - (int32_t)(from * k) / 100);
+    if (t >= 100) __ui_nodes[node].overscrollPx = 0;
+  } else if (__ui_settle_from_scrollY != 0) {
+    int16_t from = __ui_settle_from_scrollY;   // +toward 0, -toward max
+    int16_t maxS = ui_scroll_max(node);
+    if (from > 0) {
+      __ui_nodes[node].scrollY = (int16_t)(from - (int32_t)(from * k) / 100);
+      if (t >= 100) __ui_nodes[node].scrollY = 0;
+    } else {  // from < 0: snap toward maxS
+      int16_t target = maxS;
+      __ui_nodes[node].scrollY = target + (int16_t)((int32_t)from * (100 - k) / 100);
+      if (t >= 100) __ui_nodes[node].scrollY = target;
+    }
+  }
+  if (t >= 100) __ui_nodes[node].settling = 0;
+  ui_mark_scroll_view_dirty(node);
+}
+`;
+}

package/src/ui-engine/runtime-header/state-bindings-nav.ts

@@ -0,0 +1,176 @@
+// Slice of the C++ runtime header (original source lines 452-621).
+// Mixed slice: nav/touch/scroll/draw-order/kb state vars, image/keyframe/list/canvas/input binding structs, ease, fade. Kept contiguous to preserve byte-identity.
+// See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
+export function emitStateBindingsNav(): string {
+  return `
+
+// ── Multi-screen navigation ─────────────────────────────────────────────────
+// Touch/scroll/keyboard state reset by navigation.
+static uint8_t __ui_touch_state = 0;
+static int16_t __ui_touch_node = -1;  // int16: node index can exceed 127
+// Unified scroll gesture: one owning scroll container per gesture, one baseline.
+// overscrollPx/settling live on the node; only the settle-animation state is here.
+static int16_t __ui_scroll_node = -1;            // owning scroll container (int16: node index can exceed 127)
+// Per-node flag: 1 if the scroll-container loop successfully allocated a Mode B
+// canvas for this node on a recent frame. ui_apply_scroll_delta gates scrolling
+// on this — containers whose canvas won't fit (fragmented heap / no PSRAM) are
+// frozen-but-not-torn rather than allowed to scroll with unclipped children.
+// Sized at runtime via __ui_node_count; defaults to all-zero (lock until proven).
+static uint8_t* __ui_scroll_canvas_ok = nullptr;
+// One-shot scroll memory warnings (indexed by node).
+static uint8_t* __ui_scroll_mem_warned = nullptr;
+// Precomputed draw order (lower z-index first, then source index). Built once in
+// ui_init; zIndex is static after mount so this stays valid for the app lifetime.
+static uint16_t* __ui_draw_order = nullptr;
+// Non-virtualized scroll-container node indices (built once in ui_init).
+static uint16_t* __ui_scroll_owners = nullptr;
+static uint16_t __ui_scroll_owner_count = 0;
+// First NODE_FILL on the active screen (for framebuffer bg seed).
+static uint16_t __ui_active_screen_bg_node = 0xFFFF;
+static uint32_t __ui_settle_start_ms = 0;        // when the active settle animation began
+static int16_t __ui_settle_from_overscroll = 0;  // settle start value (bounce-back)
+static int16_t __ui_settle_from_scrollY = 0;     // settle start value (edge snap; sign: +toward 0, -toward max)
+static uint8_t __ui_kb_visible = 0;
+
+static uint8_t __ui_active_screen = 0;   // which screen is visible/interactive
+extern const uint16_t __ui_screen_count;  // total number of screens (emitted by lowering)
+
+// ── Image assets ────────────────────────────────────────────────────────────
+struct UIImage { uint16_t w; uint16_t h; const UI_COLOR_T* data; };
+extern const UIImage __ui_images[];
+extern const uint16_t __ui_image_count;
+
+// ── @keyframes animations ───────────────────────────────────────────────────
+struct UIKeyframeStop {
+  uint8_t percent;
+  uint8_t props; // bitmask: 1=background, 2=color, 4=opacity, 8=transform, 16=size
+  uint32_t bg;
+  uint32_t fg;
+  uint8_t opacity;
+  int16_t transformOffsetX;
+  int16_t transformOffsetY;
+  int16_t translatePctX;
+  int16_t translatePctY;
+  int16_t scaleX;
+  int16_t scaleY;
+  int16_t rotateDeg;
+  int16_t width;
+  int16_t height;
+};
+#define UI_KF_BG 1
+#define UI_KF_FG 2
+#define UI_KF_OPACITY 4
+#define UI_KF_TRANSFORM 8
+#define UI_KF_SIZE 16
+struct UIKeyframeSet {
+  uint8_t stopCount;
+  const UIKeyframeStop* stops;
+};
+struct UIAnimation {
+  uint16_t node;
+  uint8_t keyframeSet;
+  uint16_t durationMs;
+  uint16_t delayMs;
+  int16_t iterations;
+  int16_t baseWidth;
+  int16_t baseHeight;
+  int8_t originX;
+  int8_t originY;
+  uint8_t timingFunction;  // UI_TIMING_* — applied to the lerp factor between stops
+  uint32_t elapsed;
+  uint8_t active;
+  uint32_t lastUpdateMs;  // throttle: only redraw every ~100ms to avoid tearing
+};
+// animation-timing-function codes (kept in sync with model.ts TIMING_*).
+#define UI_TIMING_LINEAR 0
+#define UI_TIMING_EASE_IN_OUT 1
+#define UI_TIMING_EASE 2
+#define UI_TIMING_EASE_IN 3
+#define UI_TIMING_EASE_OUT 4
+
+// Apply an easing curve to a 0..100 linear lerp factor. Pure integer math
+// (no floats on device). Uses Newton-Raphson to solve the cubic-bezier x axis
+// for the input k, then returns the bezier's y — identical algorithm + control
+// points to easeCurveLerpK in model.ts so preview and device agree.
+// Control points are /1000 fixed point; bezierX/Y(t) = 3(1-t)²t·c1 + 3(1-t)t²·c2 + t³.
+static inline uint8_t ui_ease_lerp_k(uint8_t timing, uint8_t k) {
+  if (timing == UI_TIMING_LINEAR || k == 0) return k;
+  if (k >= 100) return 100;
+  int32_t x1, y1, x2, y2;
+  switch (timing) {
+    case UI_TIMING_EASE_IN_OUT: x1 = 420; y1 = 0;   x2 = 580; y2 = 1000; break;
+    case UI_TIMING_EASE:        x1 = 250; y1 = 100; x2 = 250; y2 = 1000; break;
+    case UI_TIMING_EASE_IN:     x1 = 420; y1 = 0;   x2 = 1000; y2 = 1000; break;
+    case UI_TIMING_EASE_OUT:    x1 = 0;   y1 = 0;   x2 = 580; y2 = 1000; break;
+    default: return k;
+  }
+  // Control points are /1000 (0..1000 == 0..1). t is parametric, also /1000.
+  // X(t) = 3(1-t)²t·x1 + 3(1-t)t²·x2 + t³. Solve X(t)=targetX for t by bisection,
+  // then return Y(t). Bisection (not Newton-Raphson): Newton diverges for curves
+  // whose x-derivative is ~0 near an endpoint (ease-out: x1=0), snapping the dot
+  // to the wrong stop. X(t) is monotonic for valid CSS points, so bisection always
+  // converges. Products of four /1000 values are /1e12; t³ is /1e9 (×1000 to align).
+  // int64 accumulation avoids overflow (3e12 > INT32_MAX). Identical algorithm +
+  // control points to easeCurveLerpK in model.ts — preview and device must agree.
+  int32_t targetX = (int32_t)k * 10;          // input on the /1000 x axis
+  int32_t lo = 0, hi = 1000;
+  for (uint8_t i = 0; i < 14; i++) {
+    int32_t t = (lo + hi) >> 1;
+    int32_t mt = 1000 - t;
+    int64_t termX1 = (int64_t)3 * mt * mt * t * x1;   // /1e12
+    int64_t termX2 = (int64_t)3 * mt * t * t * x2;    // /1e12
+    int64_t termX3 = (int64_t)t * t * t * 1000;       // /1e12 (t³ was /1e9)
+    int32_t X = (int32_t)((termX1 + termX2 + termX3) / 1000000000LL);  // back to /1000
+    if (X < targetX) lo = t; else hi = t;
+  }
+  int32_t t = (lo + hi) >> 1;
+  int32_t mt = 1000 - t;
+  int64_t termY1 = (int64_t)3 * mt * mt * t * y1;
+  int64_t termY2 = (int64_t)3 * mt * t * t * y2;
+  int64_t termY3 = (int64_t)t * t * t * 1000;
+  int32_t Y = (int32_t)((termY1 + termY2 + termY3) / 1000000000LL);  // /1000
+  return (uint8_t)(Y / 10);  // back to /100
+}
+extern const UIKeyframeSet __ui_keyframe_sets[];
+extern const uint16_t __ui_keyframe_set_count;
+extern UIAnimation __ui_anims[];
+extern const uint16_t __ui_anim_count;
+
+// ── List bindings ───────────────────────────────────────────────────────────
+struct UIListBinding {
+  uint16_t node;
+  uint16_t (*countFn)(void);
+  void (*itemFn)(uint16_t idx, char* buf, uint8_t size);
+  void (*tapFn)(uint16_t idx);  // optional: called when an item is tapped
+};
+extern UIListBinding __ui_list_bindings[];
+extern const uint16_t __ui_list_binding_count;
+
+// ── Canvas bindings (ui.drawCanvas) ─────────────────────────────────────────
+// Each canvas node's user-supplied draw function. Called each frame with the
+// node's offscreen CuttlefishCanvas16 set as the active draw target, so the
+// lowered callback body draws via the same ui_display_* wrappers as everything.
+struct UICanvasBinding {
+  uint16_t node;
+  void (*fn)(CuttlefishCanvas16* canvas);
+};
+extern UICanvasBinding __ui_canvas_bindings[];
+extern const uint16_t __ui_canvas_binding_count;
+
+// ── Input bindings (two-way) ─────────────────────────────────────────────────
+// ui.bindInput(node, cb) — cb fires with the node's current text whenever the
+// bound <input>'s textBuffer changes (e.g. user typed via on-screen keyboard).
+// lastSeen holds the previously-observed text so the runtime can detect change.
+struct UIInputBinding {
+  uint16_t node;
+  void (*cb)(const char* text);
+  char lastSeen[UI_TEXT_BUF + 1];
+};
+extern UIInputBinding __ui_input_bindings[];
+extern const uint16_t __ui_input_binding_count;
+
+// List bindings are now carried ON each node (listCountFn/listItemFn/listTapFn).
+// The UIListBinding table below is still emitted by the lowering for the
+// node-initializer to read at static-init time; the runtime never indexes it.
+`;
+}

package/src/ui-engine/runtime-header/structs.ts

@@ -0,0 +1,220 @@
+// Slice of the C++ runtime header (original source lines 90-303).
+// Enums (UINodeKind, UIProperty) and all struct definitions + extern table decls.
+// See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
+export function emitStructs(): string {
+  return `
+enum UINodeKind { NODE_FILL, NODE_TEXT, NODE_BUTTON, NODE_CHECK, NODE_RADIO, NODE_PROGRESS, NODE_RANGE, NODE_INPUT, NODE_IMG, NODE_LIST, NODE_CANVAS };
+enum UIProperty { PROP_BG, PROP_FG, PROP_TEXT, PROP_VISIBLE, PROP_BORDER_COLOR, PROP_VALUE };
+
+struct UIRect { int16_t x, y, w, h; };
+struct UIFontGlyph {
+  uint16_t codepoint;
+  int8_t xOffset;
+  int8_t yOffset;
+  uint8_t width;
+  uint8_t height;
+  uint8_t advance;
+  uint16_t dataOffset; // 4-bit alpha pixel offset
+};
+struct UIFontFace {
+  uint8_t id;
+  uint8_t glyphCount;
+  uint8_t lineHeight;
+  uint8_t baseline;
+  const UIFontGlyph* glyphs;
+  const uint8_t* alpha;
+};
+struct UINode {
+  UIRect box;
+  uint32_t bg;
+  uint32_t fg;
+  UINodeKind kind;
+  const char* text;
+  char textBuffer[UI_TEXT_BUF + 1]; // dynamic text — read only when hasTextBinding == 1
+  uint8_t hasTextBinding;       // set by ui_init when a PROP_TEXT binding targets this node
+  const uint8_t* font;
+  uint8_t hasBg;
+  uint8_t textAlign;    // 0=left, 1=center, 2=right
+  uint8_t textSize;     // GFX text size: 1-4
+  uint8_t lineHeight;   // px per text line (0 = font default)
+  int8_t letterSpacing; // px between chars (0 = default advance)
+  uint8_t fontAntialias; // 1 = smooth text edges when UI_AA is available
+  uint8_t fontFace;     // 0 = classic GFX bitmap font; otherwise UIFontFace id
+  uint32_t borderColor; // resolved color for the border (0 = use fg)
+  uint8_t borderStyle;  // 0=none, 1=solid, 2=dashed
+  uint8_t borderWidth;  // px, 0=none (uniform fallback)
+  uint8_t borderTopWidth;    // per-side; equals borderWidth when uniform
+  uint8_t borderRightWidth;
+  uint8_t borderBottomWidth;
+  uint8_t borderLeftWidth;
+  uint8_t hasPerSideBorder;  // 1 when any per-side width differs from borderWidth
+  uint8_t borderRadius; // px, 0=square
+  uint8_t paddingTop;
+  uint8_t paddingRight;
+  uint8_t paddingBottom;
+  uint8_t paddingLeft;
+  uint8_t gradientEnabled; // 0=none, 1=vertical, 2=horizontal
+  uint32_t gradientColor1;
+  uint32_t gradientColor2;
+  uint32_t outlineColor;
+  uint8_t outlineStyle; // 0=none, 1=solid, 2=dashed
+  uint8_t outlineWidth;
+  int16_t zIndex;      // effective draw layer; higher layers draw later
+  int16_t transformOffsetX; // draw-only transform: translate(...)
+  int16_t transformOffsetY;
+  int16_t rotateDeg;
+  int8_t pressedOffsetX; // draw-only :pressed offset, no Yoga relayout
+  int8_t pressedOffsetY;
+  uint8_t shadowCount;  // 0-4 active shadows
+  int8_t shadowOffsetX[4];
+  int8_t shadowOffsetY[4];
+  uint8_t shadowBlur[4];
+  uint32_t shadowColor[4];
+  uint8_t shadowAlpha[4];
+  uint8_t shadowInset[4]; // 0=outset, 1=inset
+  uint8_t textShadowCount;
+  int8_t textShadowOffsetX;
+  int8_t textShadowOffsetY;
+  uint8_t textShadowBlur;
+  uint32_t textShadowColor;
+  uint8_t textShadowAlpha;
+  uint8_t underline;    // text-decoration: 0=none,1=underline,2=line-through,3=both
+  uint8_t textOverflow; // text-overflow: 0=clip, 1=ellipsis (truncate + ...)
+  uint8_t nowrap;       // 1 = no text wrapping (white-space: nowrap/pre)
+  uint8_t whiteSpaceMode; // 0=normal, 1=nowrap, 2=pre, 3=pre-line
+  uint8_t visible;      // 0=hidden, 1=visible
+  uint8_t opacity;      // 0-100
+  uint32_t clearColor;  // ancestor's background — used to wipe transparent text before redraw
+  int16_t lastTextWidth;
+  int16_t lastTextHeight;
+  uint32_t layoutCacheKey;  // 0 = invalid; non-zero hashes layout inputs
+  uint16_t layoutMetricsW;  // cached ui_text_layout_metrics width
+  uint16_t layoutMetricsH;  // cached ui_text_layout_metrics height
+  // scroll (unified: containers and virtualized lists share these)
+  uint8_t scrollable;   // 1 = children offset by scrollY, clipped to this box
+  uint8_t virtualized;  // 1 = children produced by list*Fn callbacks (<list>)
+  int16_t scrollY;      // committed offset (always in [0, maxScroll]); draw subtracts it
+  int16_t contentHeight; // total child height (clamp bound + scrollbar ratio)
+  int16_t overscrollPx; // elastic excursion past a boundary (0 in-bounds; +top, -bottom)
+  uint8_t settling;     // 1 while a bounce-back/snap animation runs
+  int16_t lastPaintedScrollY;  // scrollY at last container repaint (Mode B shift delta)
+  uint16_t listCount;   // virtualized: current item count (refreshed each frame)
+  uint16_t (*listCountFn)(void);
+  void (*listItemFn)(uint16_t idx, char* buf, uint8_t size);
+  void (*listTapFn)(uint16_t idx);  // nullptr if no tap handler
+  uint16_t parent;      // 0xFFFF = root/no parent (UI_NO_PARENT)
+  uint16_t subtreeEnd;  // exclusive pre-order end index
+  uint8_t screenId;     // which <screen> this node belongs to (for navigation)
+  uint8_t imgDataId;    // index into __ui_images[] (255 = no image)
+  uint8_t objectFit;    // 0=none, 1=fill, 2=contain, 3=cover, 4=scale-down
+  uint16_t listItemHeight; // px per item for <list> (0 = not a list)
+  int16_t rangeMin;     // for <range>: minimum value
+  int16_t rangeMax;     // for <range>: maximum value
+  int16_t maxlen;       // for <input>: max character length (0 = UI_TEXT_BUF)
+  uint16_t canvasW;        // canvas buffer width  (for <canvas>)
+  uint16_t canvasH;        // canvas buffer height (for <canvas>)
+  // Rich-text runs (runCount > 0 for text nodes with mixed inline content).
+  // The node references a contiguous slice of the global run / segment / line
+  // arrays; geometry is precomputed at transpile time (runs are static-only).
+  uint8_t runCount;       // number of runs in this node (0 = plain single-string text)
+  uint8_t richLineCount;  // number of wrapped lines
+  uint16_t runStart;      // first index into __ui_runs[]
+  uint16_t richSegStart;  // first index into __ui_rich_segs[]
+  uint16_t richSegCount;  // total segments across all lines
+  uint16_t richLineStart; // first index into __ui_rich_lines[]
+  // runtime slot
+  uint8_t dirty;
+  int16_t value;  // unified element state
+};
+// Rich-text run: one piece of styled inline text within a node's run list.
+struct UIRichRun {
+  const char* text;
+  uint32_t fg;
+  uint8_t textSize;
+  uint8_t fontFace;
+  uint8_t underline;     // 0=none,1=underline,2=line-through,3=both
+  int8_t letterSpacing;
+  int8_t linkTarget;     // resolved screen index, -1 = not a link
+};
+// One laid-out segment of a run on one line (precomputed geometry).
+struct UIRichSeg {
+  uint8_t runIndex;      // index into the node's runs (0..runCount-1)
+  const char* text;
+  int16_t x;             // offset from the line's left edge (pre-alignment)
+  uint16_t w;            // measured width
+  uint8_t line;          // which line (0..richLineCount-1) this segment is on
+};
+// One wrapped line of rich text (precomputed).
+struct UIRichLine {
+  int16_t y;             // top y relative to the node's text top
+  uint16_t h;            // line height (tallest run on this line)
+  int16_t baseline;      // baseline y (for mixed-size baseline alignment)
+  uint16_t w;            // total line width (for alignment)
+};
+struct UITransition {
+  uint16_t node;
+  UIProperty prop;
+  uint16_t durationMs;
+  // The :pressed and base-state target colors. ui_on_press arms toward
+  // pressedTarget; ui_on_release arms toward baseTarget.
+  uint32_t pressedTarget;
+  uint32_t baseTarget;
+  // runtime
+  uint16_t elapsed;
+  uint32_t prevValue;
+  uint32_t targetValue;
+  uint8_t  active;
+};
+struct UIBinding {
+  uint16_t node;
+  UIProperty prop;
+  uint32_t (*fn)(void);       // for color/numeric bindings
+  void (*textFn)(char* buf, uint8_t size); // for text bindings (PROP_TEXT): fills buf
+};
+
+// Color lerp for transitions (rgb565). For mono, this collapses to a snap.
+static inline uint16_t lerp_color(uint16_t a, uint16_t b, uint8_t k100) {
+  if (k100 >= 100) return b;
+  // Lerp in 888 internally for smoother color transitions (keyframe animation,
+  // :pressed transitions). Unpack 565→888, lerp at 8-bit, re-quantize to 565.
+  uint8_t ar5 = (a >> 11) & 0x1f, ag6 = (a >> 5) & 0x3f, ab5 = a & 0x1f;
+  uint8_t br5 = (b >> 11) & 0x1f, bg6 = (b >> 5) & 0x3f, bb5 = b & 0x1f;
+  uint16_t ar8 = (ar5 << 3) | (ar5 >> 2), ag8 = (ag6 << 2) | (ag6 >> 4), ab8 = (ab5 << 3) | (ab5 >> 2);
+  uint16_t br8 = (br5 << 3) | (br5 >> 2), bg8 = (bg6 << 2) | (bg6 >> 4), bb8 = (bb5 << 3) | (bb5 >> 2);
+  int16_t r = (int16_t)(ar8 + (int16_t)((br8 - ar8) * k100 / 100));
+  int16_t g = (int16_t)(ag8 + (int16_t)((bg8 - ag8) * k100 / 100));
+  int16_t bl = (int16_t)(ab8 + (int16_t)((bb8 - ab8) * k100 / 100));
+  return ((uint16_t)((r >> 3) & 0x1f) << 11) | ((uint16_t)((g >> 2) & 0x3f) << 5) | (uint16_t)((bl >> 3) & 0x1f);
+}
+
+// RGB888 lerp — for transitions on RGB888/RGB666 targets (Phase 2+). Unused in
+// Phase 1; the 565 lerp_color above remains the active path for TFT targets,
+// whose node colors are still emitted as 565 values stored in uint32_t fields.
+static inline uint32_t lerp_color_888(uint32_t a, uint32_t b, uint8_t k100) {
+  if (k100 >= 100) return b;
+  uint8_t ar = (a >> 16) & 0xff, ag = (a >> 8) & 0xff, ab = a & 0xff;
+  uint8_t br = (b >> 16) & 0xff, bg = (b >> 8) & 0xff, bb = b & 0xff;
+  int16_t r = ar + (int16_t)(((int16_t)br - (int16_t)ar) * k100 / 100);
+  int16_t g = ag + (int16_t)(((int16_t)bg - (int16_t)ag) * k100 / 100);
+  int16_t bl = ab + (int16_t)(((int16_t)bb - (int16_t)ab) * k100 / 100);
+  return ((uint32_t)(r & 0xff) << 16) | ((uint32_t)(g & 0xff) << 8) | (uint32_t)(bl & 0xff);
+}
+
+// Declared by the lowering output (the tables). Matches the mutable (non-const)
+// definitions: ui_tick updates node bg/dirty and transition elapsed/active.
+extern UINode __ui_nodes[];
+extern UITransition __ui_trans[];
+extern UIBinding __ui_bindings[];
+extern const UIFontFace __ui_font_faces[];
+// Rich-text run / segment / line tables (parallel arrays; nodes reference
+// contiguous slices via runStart/richSegStart/richLineStart + counts).
+extern UIRichRun __ui_runs[];
+extern UIRichSeg __ui_rich_segs[];
+extern UIRichLine __ui_rich_lines[];
+extern const uint16_t __ui_node_count;
+extern const uint16_t __ui_trans_count;
+extern const uint16_t __ui_binding_count;
+extern const uint16_t __ui_run_count;
+extern const uint16_t __ui_rich_seg_count;
+extern const uint16_t __ui_rich_line_count;`;
+}