@typecad/ui 0.1.0-alpha.1

package/dist/ui-engine/runtime-header/touch-keyboard-fwd.js

@@ -0,0 +1,406 @@
+// Slice of the C++ runtime header (original source lines 2562-2961).
+// Touch hit-test/dispatch/state machine + keyboard forward-decls & state defines.
+// See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
+export function emitTouchKeyboardFwd() {
+    return `
+// ── Touch hit-testing + click dispatch ─────────────────────────────────────
+// Radio groups for mutual exclusion
+struct UIRadioGroup {
+  uint16_t nodeIndices[8];
+  uint8_t count;
+};
+extern UIRadioGroup __ui_radio_groups[];
+extern const uint16_t __ui_radio_group_count;
+
+// Forward-declare the click handler type + tables (defined by the emit layer).
+extern void (*__ui_click_handlers[])();
+extern void (*__ui_hold_handlers[])();
+extern void (*__ui_release_handlers[])();
+extern void (*__ui_rangechange_handlers[])();
+extern const uint16_t __ui_click_handler_count;
+extern const uint16_t __ui_rangechange_handler_count;
+
+// Touch state machine: tracks down → hold → up → click lifecycle
+// Touch node/scroll node state is defined near navigation because ui_navigate resets it.
+static uint32_t __ui_touch_down_time = 0;  // millis() when touch started
+static int16_t __ui_touch_down_y_pos = 0; // Y position when touch started (for tap vs drag detection)
+static uint32_t __ui_last_touch_time = 0;  // for debounce (updated on touch down only)
+static uint32_t __ui_last_release_time = 0;  // for release debounce
+static int16_t __ui_drag_start_x = 0;
+static int16_t __ui_drag_start_y = 0;
+static uint8_t __ui_is_dragging = 0;     // 1 once movement exceeds threshold
+static int16_t __ui_range_node = -1;     // range slider being dragged (int16: node index can exceed 127)
+
+// ── Awaitable tap source (for \`await ui.onTap()\`) ─────────────────────────
+// __ui_tap_seq increments on every completed tap (after click/release dispatch);
+// async awaiters poll it for change. __ui_tap_node records the node hit by the
+// last tap (-1 = empty space / non-interactive area) for per-element awaiters.
+// volatile: written in the touch path, read from task .step() polls.
+static volatile uint32_t __ui_tap_seq = 0;
+static volatile int16_t  __ui_tap_node = -1;   // int16: node index can exceed 127
+// Keyboard overlay state.
+#define UI_KB_MAX 48   // max key cells (4 rows × 11 padded cols + margin)
+#define UI_KB_HOLD_MS 600
+#define UI_KB_REPEAT_MS 100
+#define UI_KB_TEXT_H 24  // height reserved for the preview text row at the top
+struct UIKey { char ch; uint8_t special; };  // special: 0=char,1=shift,2=bs,3=ok,4=page
+struct UIKeyStyle { uint32_t bg, fg, borderColor; };
+static UIRect  __ui_kb_box;
+static UIKey   __ui_kb_keys[UI_KB_MAX];
+static UIKeyStyle __ui_kb_styles[UI_KB_MAX];
+static UI_COLOR_T __ui_kb_bg = 0x0000;  // keyboard background (resolved from CSS)
+static uint8_t __ui_kb_bs_held = 0;
+static uint8_t __ui_kb_dirty = 0;     // 0=clean, 1=full redraw, 2=text row + single key
+// Forward-declared here (defined in the keyboard subsystem block below) so the
+// UI_HIDE_OSK caret/blink paths in ui_tick and the input draw can reference it.
+static int16_t  __ui_kb_target;
+#if defined(UI_HIDE_OSK)
+// Caret blink phase for the desktop target (no OSK grid → no focus indicator).
+// Incremented each tick; the input draw path blinks a caret on the active edit
+// target every ~530ms (32 ticks ≈ 512ms at 60fps, even-power-of-2 mask).
+static uint16_t __ui_kb_blink = 0;
+#endif
+static int8_t __ui_kb_pressed_key = -1; // key index under the current touch (-1=none)
+static int8_t __ui_kb_repaint_key = -1; // key to repaint on a targeted (mode 2) redraw
+static int16_t __ui_last_touch_x = 0;
+static int16_t __ui_last_touch_y = 0;
+// Keyboard function forward declarations (defined in the subsystem block below;
+// needed because ui_touch_down/up/handle_touch reference them, AND to suppress
+// Arduino's auto-prototyper which would inject prototypes before UIRect is defined).
+static inline void ui_kb_insert(char c);
+static inline void ui_kb_delete();
+static inline void ui_kb_open(uint16_t nodeIdx, uint8_t inputPosition);
+static inline void ui_kb_close();
+static inline void ui_kb_tick(uint32_t now);
+static inline void ui_kb_handle_touch(int16_t tx, int16_t ty);
+static inline void ui_kb_handle_tap(int16_t tx, int16_t ty);
+static inline void ui_kb_key_rect(uint8_t idx, UIRect* out);
+static inline void ui_kb_draw();
+static inline void ui_kb_draw_key(uint8_t i);
+static inline void ui_kb_draw_text_row();
+static inline void ui_kb_compute_box();
+#define UI_TOUCH_DEBOUNCE_MS 50
+#define UI_TOUCH_HOLD_MS 600
+#define UI_DRAG_THRESHOLD 10
+
+// Hit-test a touch point against all visible nodes (topmost first).
+// Returns the node index of the topmost node that BOTH contains the point
+// AND has a click handler registered. Returns -1 if none.
+static int16_t ui_hit_test(int16_t tx, int16_t ty) {
+  int16_t best = -1;
+  for (uint16_t i = 0; i < __ui_node_count; i++) {
+    if (!ui_is_effectively_visible(i)) continue;
+    if (__ui_nodes[i].screenId != __ui_active_screen) continue;
+    int16_t drawX = ui_draw_x_for_node((uint16_t)i);
+    int16_t drawY = ui_draw_y_for_node((uint16_t)i);
+    if (tx >= drawX && tx < drawX + __ui_nodes[i].box.w &&
+        ty >= drawY && ty < drawY + __ui_nodes[i].box.h) {
+      // The node's box contains the tap. For nodes inside a scroll container,
+      // the tap point (not the whole box) must lie within the visible viewport:
+      // a tall wrapped paragraph can overflow below the fold yet still have a
+      // tappable link segment in its visible portion.
+      if (ui_is_point_clipped_by_scroll((uint16_t)i, tx, ty)) continue;
+      // Skip nodes without any click handler — they're containers, not targets.
+      // Exceptions: NODE_RANGE (horizontal drag), NODE_INPUT (opens keyboard),
+      // NODE_LIST (virtualized item tap), and NODE_BUTTON — the last so a button
+      // gets :pressed/transition visual feedback even with no JS onClick wired
+      // (a pure-CSS button like a demo "tap to transition" control).
+      if (__ui_nodes[i].kind == NODE_RANGE || __ui_nodes[i].kind == NODE_INPUT || __ui_nodes[i].kind == NODE_LIST || __ui_nodes[i].kind == NODE_BUTTON || __ui_nodes[i].kind == NODE_CHECK || __ui_nodes[i].kind == NODE_RADIO) {
+        if (best < 0 || ui_node_draws_before(best, i)) best = i;
+        continue;
+      }
+      if (i < __ui_click_handler_count &&
+          (__ui_click_handlers[i] || __ui_hold_handlers[i] || __ui_release_handlers[i])) {
+        if (best < 0 || ui_node_draws_before(best, i)) best = i;
+      }
+    }
+  }
+  return best;
+}
+
+// Dispatch a handler from the given table if registered for the node.
+static void ui_dispatch(void (**table)(), uint16_t count, int16_t node) {
+  if (node >= 0 && (uint16_t)node < count && table[node]) {
+    table[node]();
+  }
+}
+
+static inline void ui_open_keyboard_for_input(uint16_t nodeIdx) {
+  if (__ui_nodes[nodeIdx].kind != NODE_INPUT) return;
+#if defined(UI_HIDE_OSK)
+  // Desktop target: the OSK grid isn't shown, so inputs remain visible and
+  // tappable while another is being edited. Commit any open session before
+  // opening for the new target, so focus follows the tap instead of being
+  // locked to the first input. (ui_kb_open is a no-op if already closed.)
+  if (__ui_kb_visible) ui_kb_close();
+#endif
+  if (__ui_kb_visible) return;
+  // Resolve the input's position in the loader dispatch table by scanning
+  // for the Nth NODE_INPUT. (The loader table is indexed by input order.)
+  // Counter is uint16_t: nodeIdx is uint16_t and inputs can live past node
+  // 255 (demo-ui's are at 263/265/309). A uint8_t counter wraps 255→0 and
+  // never reaches nodeIdx, deadlocking the device on input tap.
+  uint8_t inputPos = 0;
+  for (uint16_t j = 0; j < nodeIdx; j++) {
+    if (__ui_nodes[j].kind == NODE_INPUT) inputPos++;
+  }
+  ui_kb_open(nodeIdx, inputPos);
+}
+
+// Touch down: called when screen is first touched.
+static void ui_touch_down(int16_t tx, int16_t ty) {
+  int16_t node = ui_hit_test(tx, ty);
+  __ui_touch_node = node;
+  __ui_touch_state = 1;
+  __ui_touch_down_time = millis();
+  __ui_touch_down_y_pos = ty;
+  __ui_drag_start_x = tx;
+  __ui_drag_start_y = ty;
+  __ui_is_dragging = 0;
+  __ui_scroll_node = -1;
+  __ui_range_node = -1;
+  // Unified scroll-scan: one pass over scrollable nodes (containers AND lists —
+  // lists are scrollable via the UA stylesheet) finds the owning container.
+  // One owner per gesture; the double-delta bug class (node in both a container
+  // and a list) is gone because there's no second mechanism.
+#if UI_SCROLL_HAS_TOUCH
+  int16_t bestScroll = -1;
+  for (uint16_t i = 0; i < __ui_node_count; i++) {
+    if (!__ui_nodes[i].scrollable || !ui_is_effectively_visible(i)) continue;
+    if (__ui_nodes[i].screenId != __ui_active_screen) continue;
+    // Only scrollable if content overflows the viewport.
+    if (__ui_nodes[i].contentHeight <= __ui_nodes[i].box.h) continue;
+    int16_t drawX = ui_draw_x_for_node((uint16_t)i);
+    int16_t drawY = ui_draw_y_for_node((uint16_t)i);
+    if (tx >= drawX && tx < drawX + __ui_nodes[i].box.w &&
+        ty >= drawY && ty < drawY + __ui_nodes[i].box.h) {
+      if (bestScroll < 0 || ui_node_draws_before(bestScroll, i)) bestScroll = i;
+    }
+  }
+  __ui_scroll_node = bestScroll;
+#else
+  (void)tx; (void)ty;
+#endif
+  if (node >= 0) {
+    uint8_t handledTouchTarget = 0;
+    if (__ui_nodes[node].kind == NODE_BUTTON) {
+      ui_set_pressed((uint16_t)node, 1);
+      handledTouchTarget = 1;
+    }
+    // Track range nodes for horizontal drag
+    if (__ui_nodes[node].kind == NODE_RANGE) {
+      __ui_range_node = node;
+      // Range owns this gesture. Do not let vertical touch jitter also scroll
+      // the containing view, which would dirty and repaint the whole viewport.
+      __ui_scroll_node = -1;
+      // Immediately set value from touch position
+      int16_t rMin = __ui_nodes[node].rangeMin;
+      int16_t rMax = __ui_nodes[node].rangeMax;
+      int16_t range = rMax - rMin;
+      if (range <= 0) range = 100;
+      int16_t relX = tx - ui_draw_x_for_node((uint16_t)node) - 4;
+      int16_t usable = __ui_nodes[node].box.w - 8;
+      if (usable <= 0) usable = 1;
+      int16_t nextVal = rMin + ((int32_t)relX * range) / usable;
+      nextVal = constrain(nextVal, rMin, rMax);
+      if (nextVal != __ui_nodes[node].value) {
+        __ui_nodes[node].value = nextVal;
+        ui_mark_dirty(node);
+      }
+      handledTouchTarget = 1;
+    }
+    uint8_t touchStartsScrollableView =
+      (__ui_scroll_node >= 0 && node == __ui_scroll_node);
+    if (!handledTouchTarget && !touchStartsScrollableView) ui_mark_dirty(node);
+  }
+}
+
+// Touch up: called when touch is released. Determines click vs hold.
+static void ui_touch_up() {
+  // Modal keyboard: route tap-up to the keyboard; swallow normal click logic.
+  // (Skipped on UI_HIDE_OSK desktop targets — touches pass through to the app,
+  // since the editing session is driven by the real keyboard, not the grid.)
+#if !defined(UI_HIDE_OSK)
+  if (__ui_kb_visible) {
+    ui_kb_handle_tap(__ui_last_touch_x, __ui_last_touch_y);
+    __ui_kb_bs_held = 0;
+    __ui_touch_state = 0;
+    __ui_last_touch_time = millis();
+    return;
+  }
+#endif
+  uint32_t elapsed = millis() - __ui_touch_down_time;
+  // Release the scroll owner: arm a bounded settle (bounce-back / edge-snap).
+  // No fling — motion ends with the finger (the settle animation is the only
+  // post-lift motion, terminating within UI_SCROLL_SETTLE_MS).
+  if (__ui_scroll_node >= 0) {
+    ui_scroll_release(__ui_scroll_node);
+  }
+  if (__ui_touch_node >= 0 && !__ui_is_dragging) {
+    int16_t clickedNode = __ui_touch_node;
+    if (elapsed < UI_TOUCH_HOLD_MS) {
+      if (__ui_nodes[clickedNode].kind == NODE_INPUT) {
+        ui_open_keyboard_for_input((uint16_t)clickedNode);
+      }
+      ui_dispatch(__ui_click_handlers, __ui_click_handler_count, __ui_touch_node);
+      // Rich-text inline link: if the tapped node has link runs, find which link
+      // segment the tap falls within and navigate to its target screen. Copies
+      // the list-item subdivision precedent with measured run rects.
+      if (__ui_nodes[clickedNode].runCount > 0) {
+        int16_t ndx = __ui_last_touch_x - ui_draw_x_for_node((uint16_t)clickedNode);
+        int16_t ndy = __ui_last_touch_y - ui_draw_y_for_node((uint16_t)clickedNode);
+        int8_t target = ui_rich_link_hit((uint16_t)clickedNode, ndx, ndy);
+        if (target >= 0) ui_navigate((uint8_t)target);
+      }
+    }
+    ui_dispatch(__ui_release_handlers, __ui_click_handler_count, __ui_touch_node);
+    ui_mark_dirty(clickedNode);
+  }
+  // Release the pressed button's :pressed state unconditionally — even when a
+  // drag/scroll hijacked the gesture (the click above is correctly gated on
+  // !__ui_is_dragging, but the visual press state should always reset on lift,
+  // otherwise a touch-down on a button followed by a scroll leaves it stuck).
+  if (__ui_touch_node >= 0 && __ui_touch_node < __ui_node_count &&
+      __ui_nodes[__ui_touch_node].kind == NODE_BUTTON && __ui_nodes[__ui_touch_node].value != 0) {
+    ui_set_pressed((uint16_t)__ui_touch_node, 0);
+  }
+  // Resume any \`await ui.onTap()\` awaiter. Runs for EVERY completed tap —
+  // including holds (released above) and taps on empty space (__ui_touch_node
+  // == -1), which is what makes "wake on any touch" work for display-sleep.
+  // Placed AFTER the click/release dispatch so onClick always fires first.
+  __ui_tap_seq++;
+  __ui_tap_node = __ui_touch_node;
+  // Virtualized list item tap: if the touch was inside a list, compute the item
+  // index from the touch Y. Use total movement (not drag flag) to distinguish
+  // tap from scroll: a tap moves < itemHeight/2 total; a scroll moves more.
+  if (__ui_scroll_node >= 0 && __ui_nodes[__ui_scroll_node].virtualized) {
+    int16_t n = __ui_scroll_node;
+    if (__ui_nodes[n].listTapFn) {
+      int16_t drawY = ui_draw_y_for_node(n);
+      int16_t relY = __ui_last_touch_y - drawY;
+      int16_t totalMove = abs(__ui_last_touch_y - __ui_touch_down_y_pos);
+      uint16_t ih = __ui_nodes[n].listItemHeight > 0 ? __ui_nodes[n].listItemHeight : 24;
+      if (totalMove < (int16_t)(ih / 2) &&
+          relY >= 0 && relY < __ui_nodes[n].box.h) {
+        uint16_t itemIdx = (uint16_t)((relY + __ui_nodes[n].scrollY) / ih);
+        if (itemIdx < __ui_nodes[n].listCount) {
+          __ui_nodes[n].listTapFn(itemIdx);
+        }
+      }
+    }
+  }
+  __ui_touch_state = 0;
+  __ui_touch_node = -1;
+  __ui_is_dragging = 0;
+  __ui_scroll_node = -1;
+  __ui_range_node = -1;
+}
+
+// Called each frame from ui_poll_touch when touch is detected.
+// Implements debounce + the down/hold/up/click state machine.
+static inline void ui_handle_touch(int16_t tx, int16_t ty) {
+  uint32_t now = millis();
+  // Track last touch coords for tap-up routing.
+  __ui_last_touch_x = tx;
+  __ui_last_touch_y = ty;
+
+  // Modal keyboard: if visible, route touch to the keyboard only.
+  // (Skipped on UI_HIDE_OSK desktop targets — touches pass through to the app,
+  // since the editing session is driven by the real keyboard, not the grid.)
+#if !defined(UI_HIDE_OSK)
+  if (__ui_kb_visible) {
+    // Only process the down-edge for key actions (insert/delete-on-down).
+    // Repeat is handled by ui_kb_tick; release by ui_touch_up → ui_kb_handle_tap.
+    if (__ui_touch_state == 0) {
+      __ui_touch_state = 1;
+      __ui_touch_down_time = now;
+      if (tx >= __ui_kb_box.x && tx < __ui_kb_box.x + __ui_kb_box.w &&
+          ty >= __ui_kb_box.y && ty < __ui_kb_box.y + __ui_kb_box.h) {
+        ui_kb_handle_touch(tx, ty);
+      }
+    } else {
+      // Held: run auto-repeat (backspace).
+      ui_kb_tick(now);
+    }
+    __ui_last_touch_time = now;
+    return;  // swallow all other touches while modal
+  }
+#endif
+
+  if (__ui_touch_state == 0) {
+    // Idle: check debounce, then start touch
+    if (now - __ui_last_touch_time < UI_TOUCH_DEBOUNCE_MS) return;
+    ui_touch_down(tx, ty);
+  } else {
+    // Already touching: check for drag or hold
+    if (__ui_range_node < 0 && !__ui_is_dragging && __ui_scroll_node >= 0) {
+      // Check if movement exceeds drag threshold
+      int16_t dy = ty - __ui_drag_start_y;
+      if (abs(dy) >= UI_DRAG_THRESHOLD) {
+        __ui_is_dragging = 1;
+      }
+    }
+    // Range slider: update value from horizontal touch position
+    if (__ui_range_node >= 0) {
+      int16_t rMin = __ui_nodes[__ui_range_node].rangeMin;
+      int16_t rMax = __ui_nodes[__ui_range_node].rangeMax;
+      int16_t range = rMax - rMin;
+      if (range <= 0) range = 100;
+      int16_t relX = tx - ui_draw_x_for_node((uint16_t)__ui_range_node) - 4;
+      int16_t usable = __ui_nodes[__ui_range_node].box.w - 8;
+      if (usable <= 0) usable = 1;
+      int16_t newVal = rMin + ((int32_t)relX * range) / usable;
+      newVal = constrain(newVal, rMin, rMax);
+      if (newVal != __ui_nodes[__ui_range_node].value) {
+        __ui_nodes[__ui_range_node].value = newVal;
+        ui_mark_dirty(__ui_range_node);
+        // Fire the onChange callback (if any) — every value change during drag.
+        if (__ui_range_node < (int16_t)__ui_rangechange_handler_count &&
+            __ui_rangechange_handlers[__ui_range_node]) {
+          __ui_rangechange_handlers[__ui_range_node]();
+        }
+      }
+    }
+    // Unified scroll drag: one owning node, immediate-apply each frame (the
+    // list's proven model, now used for all scroll containers). No accumulator,
+    // no cadence gate, no pending buffer — the smoothed delta is applied via the
+    // physics layer (1:1 in-bounds, rubber-band at edges). Telemetry optional.
+    if (__ui_range_node < 0 && __ui_is_dragging && __ui_scroll_node >= 0) {
+      int16_t rawDy = ty - __ui_drag_start_y;
+      if (rawDy != 0) {
+        int16_t dy = ui_scroll_smooth_dy(rawDy);
+        if (dy != 0) {
+          ui_apply_scroll_delta(__ui_scroll_node, dy);
+          __ui_drag_start_y = ty;
+#if UI_SCROLL_DEBUG
+          Serial.printf("scroll dy=%d sy=%d ov=%d virt=%d\\n",
+            dy, __ui_nodes[__ui_scroll_node].scrollY,
+            __ui_nodes[__ui_scroll_node].overscrollPx,
+            (int)__ui_nodes[__ui_scroll_node].virtualized);
+#endif
+        }
+      }
+    }
+    if (__ui_touch_state == 1 && __ui_touch_node >= 0 && !__ui_is_dragging) {
+      if (now - __ui_touch_down_time >= UI_TOUCH_HOLD_MS) {
+        __ui_touch_state = 2;
+        ui_dispatch(__ui_hold_handlers, __ui_click_handler_count, __ui_touch_node);
+      }
+    }
+  }
+  __ui_last_touch_time = now;
+}
+
+// Called each frame when no touch is detected.
+static inline void ui_handle_no_touch() {
+  if (__ui_touch_state != 0) {
+    // Debounce: require a gap since the last release before processing another.
+    // This prevents crash from rapid touch/no-touch flicker on resistive screens.
+    if (millis() - __ui_last_release_time < UI_TOUCH_DEBOUNCE_MS) return;
+    ui_touch_up();
+    __ui_last_release_time = millis();
+  }
+}
+
+// Blend two RGB565 colors by opacity (0-100). Returns fg faded toward bg.`;
+}

package/dist/ui-engine/runtime-header/types-defines.d.ts

@@ -0,0 +1 @@
+export declare function emitTypesDefines(): string;

package/dist/ui-engine/runtime-header/types-defines.js

@@ -0,0 +1,79 @@
+// Slice of the C++ runtime header (original source lines 17-89).
+// Guard open, includes, and #define knobs.
+// See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
+export function emitTypesDefines() {
+    return `
+// ── Cuttlefish UI runtime (emit once per TU) ──────────────────────────────
+#ifndef __TC_UI_RUNTIME
+#define __TC_UI_RUNTIME
+#include <stdint.h>
+#include <string.h>
+#define UI_TEXT_BUF 32   // max stored UI text chars, excluding the trailing NUL
+#define UI_TEXT_LINE_BUF 96
+#define UI_WS_NORMAL 0
+#define UI_WS_NOWRAP 1
+#define UI_WS_PRE 2
+#define UI_WS_PRE_LINE 3
+#ifndef UI_MAX_BUFFERED_PAINT_PIXELS
+#define UI_MAX_BUFFERED_PAINT_PIXELS 20000
+#endif
+#ifndef UI_USE_FULL_FRAMEBUFFER
+#define UI_USE_FULL_FRAMEBUFFER 0
+#endif
+#ifndef UI_TRANSITION_SNAP_MS
+#define UI_TRANSITION_SNAP_MS 100
+#endif
+// Scroll physics + capability defaults. The per-TU #define overrides emitted
+// by the UI emitter (from resolveScrollConfig) hit BEFORE this header, so these
+// #ifndef guards adopt the configured values. Spec: 2026-06-28-scroll-engine-rewrite-design.md
+#ifndef UI_SCROLL_MAX_OVERSCROLL
+#define UI_SCROLL_MAX_OVERSCROLL 40
+#endif
+#ifndef UI_SCROLL_STIFFNESS_X10
+#define UI_SCROLL_STIFFNESS_X10 5
+#endif
+#ifndef UI_SCROLL_EDGE_SNAP_PX
+#define UI_SCROLL_EDGE_SNAP_PX 12
+#endif
+#ifndef UI_SCROLL_DRAG_SCALE_X10
+#define UI_SCROLL_DRAG_SCALE_X10 10
+#endif
+#ifndef UI_SCROLL_SETTLE_MS
+#define UI_SCROLL_SETTLE_MS 180
+#endif
+#ifndef UI_SCROLL_DEADBAND_PX
+#define UI_SCROLL_DEADBAND_PX 2
+#endif
+// Capability tier flags (emitted per-TU before this header; defaults = full).
+#ifndef UI_SCROLL_INPUT_TIER_CAPACITIVE
+#define UI_SCROLL_INPUT_TIER_CAPACITIVE 0
+#endif
+#ifndef UI_SCROLL_INPUT_TIER_RESISTIVE
+#define UI_SCROLL_INPUT_TIER_RESISTIVE 0
+#endif
+#ifndef UI_SCROLL_INPUT_TIER_NONE
+#define UI_SCROLL_INPUT_TIER_NONE 0
+#endif
+#ifndef UI_SCROLL_RENDER_TIER_FULL
+#define UI_SCROLL_RENDER_TIER_FULL 1
+#endif
+#ifndef UI_SCROLL_RENDER_TIER_CONSTRAINED
+#define UI_SCROLL_RENDER_TIER_CONSTRAINED 0
+#endif
+#if (UI_SCROLL_INPUT_TIER_CAPACITIVE + UI_SCROLL_INPUT_TIER_RESISTIVE + UI_SCROLL_INPUT_TIER_NONE) == 0
+#define UI_SCROLL_INPUT_TIER_RESISTIVE 1
+#endif
+#define UI_SCROLL_HAS_TOUCH (UI_SCROLL_INPUT_TIER_CAPACITIVE || UI_SCROLL_INPUT_TIER_RESISTIVE)
+#define UI_SCROLL_ELASTIC (UI_SCROLL_RENDER_TIER_FULL)
+// Telemetry: emits per-frame scrollY/overscrollPx/dy over Serial when defined.
+#ifndef UI_SCROLL_DEBUG
+#define UI_SCROLL_DEBUG 0
+#endif
+#ifndef UI_SCROLL_CANVAS_BUDGET_BYTES
+#define UI_SCROLL_CANVAS_BUDGET_BYTES 88000
+#endif
+#if defined(ESP32) || defined(ESP8266)
+#include <Esp.h>
+#endif
+`;
+}

package/dist/ui-engine/runtime-header.d.ts

@@ -0,0 +1 @@
+export declare function emitRuntimeHeader(): string;

package/dist/ui-engine/runtime-header.js

@@ -0,0 +1,69 @@
+// ---------------------------------------------------------------------------
+// C++ reactive runtime header — the driver code that walks the node/binding/
+// transition tables each frame.
+//
+// This is emitted once per translation unit (guarded) so the static tables
+// produced by the lowering transformer have something to drive them. It
+// implements the three-phase frame from spec §7:
+//   1. Advance transitions (lerp toward target)
+//   2. Draw traversal (dirty nodes only)
+//   3. Flush dirty rects
+//
+// Plus the press/release entry points that node.onPress(pin) lowers to.
+//
+// The C++ source is split into contiguous slice modules under
+// ./runtime-header/, concatenated here in source order. Each slice is a
+// verbatim range of the original template literal; the assembled output is
+// byte-identical to the pre-split single-file version (guarded by
+// tests/packages/cuttlefish/runtime-header-byte-identity.test.ts).
+// ---------------------------------------------------------------------------
+import { emitTypesDefines } from "./runtime-header/types-defines.js";
+import { emitStructs } from "./runtime-header/structs.js";
+import { emitColorMonoRefresh } from "./runtime-header/color-mono-refresh.js";
+import { emitStateBindingsNav } from "./runtime-header/state-bindings-nav.js";
+import { emitForwardDecls } from "./runtime-header/forward-decls.js";
+import { emitCanvasHelpers } from "./runtime-header/canvas-helpers.js";
+import { emitDisplayShim } from "./runtime-header/display-shim.js";
+import { emitScrollPhysics } from "./runtime-header/scroll-physics.js";
+import { emitImageDrawing } from "./runtime-header/image-drawing.js";
+import { emitCanvasScrollbar } from "./runtime-header/canvas-scrollbar.js";
+import { emitDirtyScrollMutators } from "./runtime-header/dirty-scroll-mutators.js";
+import { emitPaintOrderCoords } from "./runtime-header/paint-order-coords.js";
+import { emitPaintRectsRepair } from "./runtime-header/paint-rects-repair.js";
+import { emitInitPressInput } from "./runtime-header/init-press-input.js";
+import { emitTouchKeyboardFwd } from "./runtime-header/touch-keyboard-fwd.js";
+import { emitBlendBodies } from "./runtime-header/blend-bodies.js";
+import { emitTextRendering } from "./runtime-header/text-rendering.js";
+import { emitNodeDecoration } from "./runtime-header/node-decoration.js";
+import { emitTickMotionHelpers } from "./runtime-header/tick-motion-helpers.js";
+import { emitTick } from "./runtime-header/tick.js";
+import { emitAntialiasing } from "./runtime-header/antialiasing.js";
+import { emitKeyboard } from "./runtime-header/keyboard.js";
+import { emitGuardClose } from "./runtime-header/guard-close.js";
+export function emitRuntimeHeader() {
+    return [
+        emitTypesDefines(),
+        emitStructs(),
+        emitColorMonoRefresh(),
+        emitStateBindingsNav(),
+        emitForwardDecls(),
+        emitCanvasHelpers(),
+        emitDisplayShim(),
+        emitScrollPhysics(),
+        emitImageDrawing(),
+        emitCanvasScrollbar(),
+        emitDirtyScrollMutators(),
+        emitPaintOrderCoords(),
+        emitPaintRectsRepair(),
+        emitInitPressInput(),
+        emitTouchKeyboardFwd(),
+        emitBlendBodies(),
+        emitTextRendering(),
+        emitNodeDecoration(),
+        emitTickMotionHelpers(),
+        emitTick(),
+        emitAntialiasing(),
+        emitKeyboard(),
+        emitGuardClose(),
+    ].join("");
+}

package/dist/ui-engine/scroll-memory-diagnostics.d.ts

@@ -0,0 +1,16 @@
+import type { Diagnostic } from "@typecad/cuttlefish/api/shared";
+import type { UINodeModel } from "./model.js";
+import { DEFAULT_SCROLL_CANVAS_BUDGET_BYTES } from "@typecad/cuttlefish/api/shared";
+export { DEFAULT_SCROLL_CANVAS_BUDGET_BYTES };
+export interface ScrollMemoryIssue {
+    nodeIndex: number;
+    id?: string;
+    width: number;
+    height: number;
+    canvasBytes: number;
+    budgetBytes: number;
+}
+/** Collect overflow scroll nodes whose viewport canvas exceeds the budget. */
+export declare function collectScrollMemoryIssues(nodes: UINodeModel[], budgetBytes?: number): ScrollMemoryIssue[];
+/** Emit transpile warnings for scroll viewports that cannot fit a Mode B canvas. */
+export declare function analyzeScrollMemory(nodes: UINodeModel[], budgetBytes?: number): Diagnostic[];

package/dist/ui-engine/scroll-memory-diagnostics.js

@@ -0,0 +1,58 @@
+// Compile-time scroll viewport memory analysis. Overflow scroll containers
+// need a viewport-sized RGB565 canvas (~w×h×2 bytes) for smooth Mode B
+// scrolling; when that exceeds the device budget, runtime falls back to
+// Mode C strip scroll or freezes until memory is available.
+import { DEFAULT_SCROLL_CANVAS_BUDGET_BYTES } from "@typecad/cuttlefish/api/shared";
+export { DEFAULT_SCROLL_CANVAS_BUDGET_BYTES };
+/** Collect overflow scroll nodes whose viewport canvas exceeds the budget. */
+export function collectScrollMemoryIssues(nodes, budgetBytes = DEFAULT_SCROLL_CANVAS_BUDGET_BYTES) {
+    const issues = [];
+    for (const node of nodes) {
+        if (!node.scrollable)
+            continue;
+        if (node.contentHeight <= node.box.h)
+            continue;
+        const canvasBytes = node.box.w * node.box.h * 2;
+        if (canvasBytes <= budgetBytes)
+            continue;
+        issues.push({
+            nodeIndex: node.index,
+            id: node.id,
+            width: node.box.w,
+            height: node.box.h,
+            canvasBytes,
+            budgetBytes,
+        });
+    }
+    return issues;
+}
+function formatKb(bytes) {
+    return `${Math.round(bytes / 1024)} KB`;
+}
+function minimizationHint(issue) {
+    const maxArea = Math.floor(issue.budgetBytes / 2);
+    const maxHAtWidth = issue.width > 0 ? Math.floor(maxArea / issue.width) : 0;
+    const maxWAtHeight = issue.height > 0 ? Math.floor(maxArea / issue.height) : 0;
+    return [
+        `Reduce the scroll viewport in CSS (e.g. height ≤ ${maxHAtWidth}px at ${issue.width}px width, or width ≤ ${maxWAtHeight}px at ${issue.height}px height).`,
+        "Trim fonts, images, or inactive screens to free heap for canvas allocation.",
+        "Use PSRAM or a board with more SRAM if you need a larger scroll viewport.",
+        "Adjust display.scroll.scrollCanvasBudgetBytes in cuttlefish.config.ts only if your target has more headroom (runtime allocation may still fail).",
+    ].join("\n");
+}
+/** Emit transpile warnings for scroll viewports that cannot fit a Mode B canvas. */
+export function analyzeScrollMemory(nodes, budgetBytes = DEFAULT_SCROLL_CANVAS_BUDGET_BYTES) {
+    return collectScrollMemoryIssues(nodes, budgetBytes).map((issue) => {
+        const label = issue.id ? `#${issue.id}` : `node ${issue.nodeIndex}`;
+        return {
+            severity: "warning",
+            code: "scroll-canvas-memory",
+            message: `Scroll viewport ${label} (${issue.width}×${issue.height}px) needs ${issue.canvasBytes} bytes ` +
+                `(${formatKb(issue.canvasBytes)}) for accurate smooth scrolling, exceeding the ` +
+                `${issue.budgetBytes}-byte budget (~${formatKb(issue.budgetBytes)}). ` +
+                "Rendering will fall back to Mode C strip scroll or freeze updates until memory is available — " +
+                "scrolling may tear, stutter, or skip frames.",
+            hint: minimizationHint(issue),
+        };
+    });
+}

package/dist/ui-engine/select-engine.d.ts

@@ -0,0 +1,4 @@
+import { LayoutEngine } from "./layout-engine.js";
+import { StyledNode } from "./style-resolver.js";
+/** Select the layout engine: Yoga for flex, BlockLayoutEngine as fallback. */
+export declare function selectEngine(root: StyledNode): LayoutEngine;

package/dist/ui-engine/select-engine.js

@@ -0,0 +1,19 @@
+// ---------------------------------------------------------------------------
+// Engine selection — picks Yoga (flexbox) or BlockLayout based on whether any
+// node in the styled tree declares display: flex.
+// ---------------------------------------------------------------------------
+import { isDisplayNone } from "./layout-engine.js";
+import { BlockLayoutEngine } from "./block-layout.js";
+import { YogaLayoutEngine } from "./yoga-layout.js";
+/** Check if any node in the tree uses display: flex. */
+function usesFlex(node) {
+    if (isDisplayNone(node))
+        return false;
+    if (node.style.display === "flex")
+        return true;
+    return node.children.some(usesFlex);
+}
+/** Select the layout engine: Yoga for flex, BlockLayoutEngine as fallback. */
+export function selectEngine(root) {
+    return usesFlex(root) ? new YogaLayoutEngine() : new BlockLayoutEngine();
+}