@typecad/ui 0.1.0-alpha.1

package/src/ui-engine/runtime-header/canvas-scrollbar.ts

@@ -0,0 +1,105 @@
+// Slice of the C++ runtime header (original source lines 1449-1547).
+// Canvas push/draw helpers, buffered scroll canvas push, scrollbar direct.
+// See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
+export function emitCanvasScrollbar(): string {
+  return `
+static inline void ui_push_canvas_rect(CuttlefishCanvas16* canvas, int16_t x, int16_t y, int16_t w, int16_t h) {
+  if (!canvas || !display_canvasBuffer(canvas)) return;
+  UI_COLOR_T* pixels = display_canvasBuffer(canvas);
+  int16_t stride = display_canvasWidth(canvas);
+  // The canvas is viewport-sized: buffer row 0 = the first row of the viewport.
+  // The display destination is (x, y) but the source buffer starts at (0, 0).
+  // When a full-screen framebuffer is the active draw target, composite into it
+  // via __ui_gfx (so the single bulk push at frame end captures everything).
+  // Otherwise write straight to the display in one SPI transaction.
+  if (__ui_fb) {
+    if (w == stride) {
+      ui_display_draw_rgb_bitmap(x, y, pixels, w, h);
+      return;
+    }
+    for (int16_t row = 0; row < h; row++) {
+      ui_display_draw_rgb_bitmap(x, y + row, pixels + (int32_t)row * stride, w, 1);
+    }
+    return;
+  }
+  display_startWrite();
+  display_setAddrWindow(x, y, w, h);
+  if (w == stride) {
+    // Full-width: contiguous in buffer, single write.
+    display_writePixels(pixels, (uint32_t)w * h);
+    display_endWrite();
+    return;
+  }
+  for (int16_t row = 0; row < h; row++) {
+    display_writePixels(pixels + (int32_t)row * stride, w);
+  }
+  display_endWrite();
+}
+
+static inline void ui_draw_canvas_rect(CuttlefishCanvas16* canvas, int16_t x, int16_t y, int16_t w, int16_t h) {
+  if (!canvas || !display_canvasBuffer(canvas)) return;
+  UI_COLOR_T* pixels = display_canvasBuffer(canvas);
+  int16_t stride = display_canvasWidth(canvas);
+  if (w == stride && h == display_canvasHeight(canvas)) {
+    ui_display_draw_rgb_bitmap(x, y, pixels, w, h);
+    return;
+  }
+  for (int16_t row = 0; row < h; row++) {
+    ui_display_draw_rgb_bitmap(x, y + row, pixels + (int32_t)row * stride, w, 1);
+  }
+}
+
+static inline void ui_push_buffered_scroll_canvas(CuttlefishCanvas16* bufferedScrollCanvas,
+                                                  CuttlefishCanvas16* bufferedScrollRepaintCanvas,
+                                                  int16_t bufferedScrollNode,
+                                                  int16_t bufferedScrollVX,
+                                                  int16_t bufferedScrollVY,
+                                                  int16_t bufferedScrollRepaintY,
+                                                  int16_t bufferedScrollRepaintH,
+                                                  CuttlefishDisplayTarget* drawTarget) {
+  if (bufferedScrollNode < 0 || !bufferedScrollCanvas || !display_canvasBuffer(bufferedScrollCanvas)) return;
+  // Draw scrollbar into the canvas (canvas-local coords: 0,0 = viewport top-left).
+  ui_display_set_target(bufferedScrollCanvas);
+  int16_t si = bufferedScrollNode;
+  int16_t vw = __ui_nodes[si].box.w;
+  int16_t vh = __ui_nodes[si].box.h;
+  if (bufferedScrollRepaintCanvas && bufferedScrollRepaintH > 0) {
+    ui_draw_canvas_rect(bufferedScrollRepaintCanvas, 0, bufferedScrollRepaintY, vw, bufferedScrollRepaintH);
+  }
+  int16_t tx = vw - 4;
+  uint16_t thumbH = (uint32_t)vh * vh / __ui_nodes[si].contentHeight;
+  if (thumbH < 8) thumbH = 8;
+  int16_t maxScroll = __ui_nodes[si].contentHeight - vh;
+  uint16_t thumbY = (uint32_t)(vh - thumbH) * __ui_nodes[si].scrollY / (maxScroll > 0 ? maxScroll : 1);
+  UI_COLOR_T dimFg = (UI_COLOR_T)((__ui_nodes[si].fg >> 1) & UI_DIM_MASK);
+  ui_display_fill_rect(tx, 0, 3, vh, dimFg);
+  ui_display_fill_rect(tx, thumbY, 3, thumbH, __ui_nodes[si].fg);
+  // Record the scrollY this canvas now reflects, so the next scroll frame can
+  // compute its shift delta (Mode B) from scrollY - lastPaintedScrollY.
+  __ui_nodes[si].lastPaintedScrollY = __ui_nodes[si].scrollY;
+  // Push the canvas to the draw target at the viewport position (the
+  // framebuffer when active, else the display directly).
+  ui_display_set_target(drawTarget);
+  ui_push_canvas_rect(bufferedScrollCanvas,
+    bufferedScrollVX, bufferedScrollVY,
+    vw, vh);
+}
+
+// Draw a scroll container's scrollbar directly on the display (Mode C).
+static inline void ui_draw_scrollbar_direct(int16_t si, int16_t vox, int16_t voy) {
+  if (si < 0 || si >= (int16_t)__ui_node_count) return;
+  int16_t vw = __ui_nodes[si].box.w;
+  int16_t vh = __ui_nodes[si].box.h;
+  if (__ui_nodes[si].contentHeight <= vh) return;
+  int16_t tx = vox + vw - 4;
+  uint16_t thumbH = (uint32_t)vh * vh / __ui_nodes[si].contentHeight;
+  if (thumbH < 8) thumbH = 8;
+  int16_t maxScroll = __ui_nodes[si].contentHeight - vh;
+  uint16_t thumbY = (uint32_t)(vh - thumbH) * __ui_nodes[si].scrollY / (maxScroll > 0 ? maxScroll : 1);
+  UI_COLOR_T dimFg = (UI_COLOR_T)((__ui_nodes[si].fg >> 1) & UI_DIM_MASK);
+  ui_display_fill_rect(tx, voy, 3, vh, dimFg);
+  ui_display_fill_rect(tx, (int16_t)(voy + thumbY), 3, thumbH, __ui_nodes[si].fg);
+}
+
+// Per-node dirty marker (called by press handlers and binding evaluation).`;
+}

package/src/ui-engine/runtime-header/color-mono-refresh.ts

@@ -0,0 +1,154 @@
+// Slice of the C++ runtime header (original source lines 304-451).
+// lerp/blend fwd-decls, color-depth selection, mono snap, per-frame refresh dispatch.
+// See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
+export function emitColorMonoRefresh(): string {
+  return `
+
+// ── Color depth → blend/lerp selection ───────────────────────────────────────
+// UI_COLOR_DEPTH is emitted by the UI emitter from the display profile's
+// colorFormat (565 for TFT byte-identity, 888 for rgb666+). The value depth
+// and the blend math MUST switch together: on 565, node fields hold 565 values
+// and ui_blend565 is correct; on 888, node fields hold 888 values and
+// ui_blend888 is correct. Forward-declare the four functions and define the
+// ui_blend/UI_LERP_COLOR macros here (before any call site) so they resolve
+// everywhere; the function bodies are defined later in this header.
+#ifndef UI_COLOR_DEPTH
+#define UI_COLOR_DEPTH 565
+#endif
+// Color value type tracks the depth: 888 holds 24-bit RGB (R<<16|G<<8|B),
+// 565 holds 16-bit. Draw wrappers and locals use UI_COLOR_T so 888 is not
+// narrowed before reaching the HAL. Under 565/mono this is uint16_t and the
+// emitted code is byte-identical with the pre-widening runtime.
+#if UI_COLOR_DEPTH == 888
+  #ifndef UI_COLOR_T
+    #define UI_COLOR_T uint32_t
+  #endif
+  #ifndef UI_DIM_MASK
+    #define UI_DIM_MASK 0x7F7F7Fu   // halve each 8-bit channel independently
+  #endif
+#else
+  #ifndef UI_COLOR_T
+    #define UI_COLOR_T uint16_t
+  #endif
+  #ifndef UI_DIM_MASK
+    #define UI_DIM_MASK 0x7BEFu     // 565 dim mask (top bit clear per channel)
+  #endif
+#endif
+static inline uint16_t ui_blend565(uint16_t fg, uint16_t bg, uint8_t opacity);
+static inline uint32_t ui_blend888(uint32_t fg, uint32_t bg, uint8_t opacity);
+static inline uint16_t lerp_color(uint16_t a, uint16_t b, uint8_t k100);
+static inline uint32_t lerp_color_888(uint32_t a, uint32_t b, uint8_t k100);
+#if UI_COLOR_DEPTH == 888
+  #define ui_blend(fg, bg, op)        ui_blend888((uint32_t)(fg), (uint32_t)(bg), (op))
+  #define UI_LERP_COLOR(a, b, k)      lerp_color_888((uint32_t)(a), (uint32_t)(b), (k))
+#else
+  #define ui_blend(fg, bg, op)        ui_blend565((uint16_t)(fg), (uint16_t)(bg), (op))
+  #define UI_LERP_COLOR(a, b, k)      lerp_color((uint16_t)(a), (uint16_t)(b), (k))
+#endif
+
+// ── 1-bit mono snap (UI_NATIVE_MONO) ─────────────────────────────────────────
+// On a B&W e-ink panel, any color value must resolve to black or white. Node
+// fields are pre-snapped at transpile, but blended/lerped runtime values
+// (opacity, shadows, gradients) need a defensive snap in the draw path. The
+// macro is a no-op on color targets so TFT output is byte-identical.
+#ifdef UI_NATIVE_MONO
+// Snap an RGB888 value to 1-bit mono (white/black) by luminance.
+static inline uint32_t ui_snap_mono(uint32_t c) {
+  uint8_t r = (c >> 16) & 0xff, g = (c >> 8) & 0xff, b = c & 0xff;
+  // Match the transpile-time toMono threshold: (0.299r + 0.587g + 0.114b)/255 >= 0.27.
+  // Integer form: 299r+587g+114b >= 68850 (= 0.27*255*1000). Verified 0 mismatches.
+  return ((uint32_t)(299 * r + 587 * g + 114 * b) >= 68850u) ? 0xffffffu : 0x000000u;
+}
+// Snap an RGB565 value to 1-bit mono. Mono panels run at UI_COLOR_DEPTH 565, so
+// node fields hold 565 values; reconstruct 8-bit channels then apply the threshold.
+// Pre-snapped values (0x0000/0x0001/0xffff) pass through directly — the
+// transpiler resolves #ffffff/#000000 to 0x0001/0x0000 on mono targets.
+static inline uint16_t ui_snap_mono565(uint16_t c) {
+  if (c == 0x0000u) return 0x0000u;
+  if (c == 0x0001u || c == 0xffffu) return 0xffffu;
+  uint8_t r5 = (c >> 11) & 0x1f, g6 = (c >> 5) & 0x3f, b5 = c & 0x1f;
+  uint8_t r = (r5 << 3) | (r5 >> 2), g = (g6 << 2) | (g6 >> 4), b = (b5 << 3) | (b5 >> 2);
+  return ((uint32_t)(299 * r + 587 * g + 114 * b) >= 68850u) ? 0xffffu : 0x0000u;
+}
+#define UI_MAYBE_SNAP_MONO(c)    (ui_snap_mono((uint32_t)(c)))
+#define UI_MAYBE_SNAP_MONO565(c) (ui_snap_mono565((uint16_t)(c)))
+#else
+#define UI_MAYBE_SNAP_MONO(c)    (c)
+#define UI_MAYBE_SNAP_MONO565(c) (c)
+#endif
+
+// ── Per-frame refresh dispatch ──────────────────────────────────────────────
+// Three mutually-exclusive compile-time paths, in priority order:
+//   1. UI_REQUIRES_BACKING_STORE (e-ink): dirty-rect accumulator + partial refresh.
+//   2. UI_BATCH_SPI_WRITES (TFT immediate): one startWrite/endWrite per frame.
+//   3. default (SDL native host): no-ops.
+// Exactly one branch ever compiles — the emitter's guards ensure the first two
+// are never both defined (UI_REQUIRES_BACKING_STORE ⟹ requiresBackingStore,
+// UI_BATCH_SPI_WRITES ⟹ immediate && !requiresBackingStore).
+#if defined(UI_REQUIRES_BACKING_STORE)
+  // e-ink / deferred-partial: dirty-rect accumulator. Each painted node reports
+  // its paint rect; at frame end the union is refreshed as one partial update
+  // via display_partial_refresh.
+  #define UI_REFRESH_MAX_RECTS 16
+  struct UIRect16 { int16_t x, y, w, h; };
+  static UIRect16 __ui_refresh_rects[UI_REFRESH_MAX_RECTS];
+  static uint8_t __ui_refresh_rect_n = 0;
+  static inline void ui_refresh_begin_frame() { __ui_refresh_rect_n = 0; }
+  static inline void ui_refresh_add_rect(int16_t x, int16_t y, int16_t w, int16_t h) {
+    if (w <= 0 || h <= 0) return;
+    if (__ui_refresh_rect_n < UI_REFRESH_MAX_RECTS) {
+      __ui_refresh_rects[__ui_refresh_rect_n].x = x;
+      __ui_refresh_rects[__ui_refresh_rect_n].y = y;
+      __ui_refresh_rects[__ui_refresh_rect_n].w = w;
+      __ui_refresh_rects[__ui_refresh_rect_n].h = h;
+      __ui_refresh_rect_n++;
+    }
+    // TODO Phase 5: coalesce overlapping rects into a tighter union; cap by
+    // refresh budget; trigger a periodic full refresh for ghost clearing.
+  }
+  // Union all accumulated rects and issue one partial refresh of the bounding
+  // region via the shim's display_partial_refresh entry point.
+  static inline void ui_refresh_flush() {
+    if (__ui_refresh_rect_n == 0) return;
+    int16_t x0 = 32767, y0 = 32767, x1 = -32768, y1 = -32768;
+    for (uint8_t i = 0; i < __ui_refresh_rect_n; i++) {
+      const UIRect16& r = __ui_refresh_rects[i];
+      if (r.x < x0) x0 = r.x;
+      if (r.y < y0) y0 = r.y;
+      int16_t rx1 = (int16_t)(r.x + r.w), ry1 = (int16_t)(r.y + r.h);
+      if (rx1 > x1) x1 = rx1;
+      if (ry1 > y1) y1 = ry1;
+    }
+    if (x0 < 0) x0 = 0;
+    if (y0 < 0) y0 = 0;
+    if (x1 > display_width()) x1 = display_width();
+    if (y1 > display_height()) y1 = display_height();
+    if (x1 > x0 && y1 > y0) {
+      display_partial_refresh(x0, y0, (int16_t)(x1 - x0), (int16_t)(y1 - y0));
+    }
+  }
+#elif defined(UI_BATCH_SPI_WRITES)
+  // TFT immediate-refresh batching (CURRENTLY UNUSED — see note below).
+  // Wraps the frame's draws in ONE SPI transaction so all per-node writes share
+  // a single CS-asserted burst. add_rect is a no-op: TFT has no partial-refresh
+  // concept; the per-node draws already target the right pixels.
+  //
+  // NOTE: this branch is left in place but the emitter does NOT define
+  // UI_BATCH_SPI_WRITES by default. The design assumed Adafruit_SPITFT's
+  // startWrite/endWrite are reference-counted (nested calls = no-op for CS),
+  // but the Adafruit_GFX version in this repo is NOT — every endWrite raises
+  // CS unconditionally. So an outer frame startWrite gets closed by the first
+  // inner draw's endWrite → black screen. Re-enable only after either (a)
+  // upgrading to a ref-counted Adafruit_GFX or (b) adding a runtime flag the
+  // inner draw primitives check to skip their own startWrite/endWrite.
+  // See docs/superpowers/specs/2026-07-06-tft-spi-write-batching-design.md.
+  static inline void ui_refresh_begin_frame() { display_startWrite(); }
+  static inline void ui_refresh_add_rect(int16_t x, int16_t y, int16_t w, int16_t h) { (void)x; (void)y; (void)w; (void)h; }
+  static inline void ui_refresh_flush() { display_endWrite(); }
+#else
+  // No batching (e.g. SDL native host render): true no-ops.
+  #define ui_refresh_begin_frame()  ((void)0)
+  #define ui_refresh_add_rect(x, y, w, h) ((void)0)
+  #define ui_refresh_flush()        ((void)0)
+#endif`;
+}

package/src/ui-engine/runtime-header/dirty-scroll-mutators.ts

@@ -0,0 +1,169 @@
+// Slice of the C++ runtime header (original source lines 1548-1710).
+// mark_dirty, subtree dirty, scroll direct prepare/compositor, scroll view dirty/overlap/invalidate.
+// See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
+export function emitDirtyScrollMutators(): string {
+  return `
+static inline void ui_mark_dirty(uint16_t nodeIdx) {
+  if (nodeIdx >= __ui_node_count) return;
+  __ui_nodes[nodeIdx].dirty = 1;
+  if (ui_is_effectively_visible(nodeIdx) &&
+      __ui_nodes[nodeIdx].screenId == __ui_active_screen) {
+    UIRect r;
+    ui_node_current_paint_rect(nodeIdx, &r);
+    if (r.w <= 0 || r.h <= 0) {
+      ui_mark_overlapping_higher_layers_dirty(nodeIdx);
+      return;
+    }
+    uint16_t p = __ui_nodes[nodeIdx].parent;
+    while (p != UI_NO_PARENT && p < __ui_node_count) {
+      if (__ui_nodes[p].scrollable &&
+          !__ui_nodes[p].virtualized &&
+          __ui_nodes[p].contentHeight > __ui_nodes[p].box.h) {
+        UIRect clip = {
+          __ui_nodes[p].box.x,
+          __ui_nodes[p].box.y,
+          __ui_nodes[p].box.w,
+          __ui_nodes[p].box.h
+        };
+        if (!ui_rects_intersect(r.x, r.y, r.w, r.h, clip.x, clip.y, clip.w, clip.h)) {
+          __ui_nodes[nodeIdx].dirty = 0;
+          return;
+        }
+        if (r.x < clip.x ||
+            r.x + r.w > clip.x + clip.w ||
+            r.y < clip.y ||
+            r.y + r.h > clip.y + clip.h) {
+          ui_mark_scroll_view_dirty(p);
+          return;
+        }
+        // Fully inside the viewport, but overflow scroll content is canvas-
+        // composited. Promote to a scroll repaint — otherwise the defer path
+        // drops the child's dirty flag without drawing (e.g. :pressed buttons).
+        ui_mark_scroll_view_dirty(p);
+        return;
+      }
+      p = __ui_nodes[p].parent;
+    }
+  }
+  ui_mark_overlapping_higher_layers_dirty(nodeIdx);
+}
+
+// Set dirty=1 across a scroll subtree WITHOUT the per-child O(n) overlap repair.
+// During scroll the subtree repaints into a freshly-cleared off-screen canvas, so
+// intra-subtree overlap repair is pointless, and scroll children are draw-clipped
+// to the container's viewport box — so all external higher-z neighbors of the
+// viewport are covered by ONE overlap check at the container's paint rect (done by
+// the caller). This drops scroll marking from O(K·n) to O(K + n).
+static inline void ui_mark_subtree_dirty_local(uint16_t scrollNode) {
+  if (scrollNode >= __ui_node_count) return;
+  for (uint16_t c = scrollNode + 1; c < __ui_nodes[scrollNode].subtreeEnd; c++) {
+    __ui_nodes[c].dirty = 1;
+  }
+  __ui_nodes[scrollNode].dirty = 1;
+}
+
+// Mode C strip-only: direct-partial scroll when no viewport canvas fits and the
+// scroll delta is small. Fills only the exposed strip on the display, then marks
+// visible descendants dirty for direct draw — never clears the whole viewport.
+static inline void ui_scroll_direct_prepare(uint16_t s, int16_t* outVX, int16_t* outVY) {
+  int16_t vw = __ui_nodes[s].box.w;
+  int16_t vh = __ui_nodes[s].box.h;
+  int16_t vox = __ui_nodes[s].box.x;
+  int16_t voy = __ui_nodes[s].box.y;
+  UI_COLOR_T scrollBg = __ui_nodes[s].hasBg ? __ui_nodes[s].bg : __ui_nodes[s].clearColor;
+  int16_t deltaY = __ui_nodes[s].scrollY - __ui_nodes[s].lastPaintedScrollY;
+  int16_t absDelta = deltaY < 0 ? -deltaY : deltaY;
+  int16_t stripY = deltaY > 0 ? (int16_t)(vh - absDelta) : 0;
+  ui_display_fill_rect(vox, (int16_t)(voy + stripY), vw, absDelta, scrollBg);
+  for (uint16_t c = s + 1; c < __ui_nodes[s].subtreeEnd; c++) {
+    if (!ui_is_effectively_visible(c) || __ui_nodes[c].screenId != __ui_active_screen) {
+      __ui_nodes[c].dirty = 0;
+      continue;
+    }
+    __ui_nodes[c].dirty = 1;
+    if (__ui_nodes[c].kind == NODE_PROGRESS || __ui_nodes[c].kind == NODE_RANGE) {
+      __ui_nodes[c].lastTextWidth = -1;
+    }
+    __ui_nodes[c].lastTextHeight = 0;
+  }
+  __ui_nodes[s].dirty = 0;
+  if (outVX) *outVX = vox;
+  if (outVY) *outVY = voy;
+}
+
+// Nearest overflow scroll container owning nodeIdx (or nodeIdx itself).
+static inline int16_t ui_overflow_scroll_compositor(uint16_t nodeIdx) {
+  if (nodeIdx >= __ui_node_count) return -1;
+  if (__ui_nodes[nodeIdx].scrollable && !__ui_nodes[nodeIdx].virtualized &&
+      __ui_nodes[nodeIdx].contentHeight > __ui_nodes[nodeIdx].box.h) {
+    return (int16_t)nodeIdx;
+  }
+  uint16_t p = __ui_nodes[nodeIdx].parent;
+  while (p != UI_NO_PARENT && p < __ui_node_count) {
+    if (__ui_nodes[p].scrollable && !__ui_nodes[p].virtualized &&
+        __ui_nodes[p].contentHeight > __ui_nodes[p].box.h) {
+      return (int16_t)p;
+    }
+    p = __ui_nodes[p].parent;
+  }
+  return -1;
+}
+
+static inline void ui_mark_scroll_view_overlaps_dirty(uint16_t scrollNode) {
+  if (scrollNode >= __ui_node_count) return;
+  if (!ui_is_effectively_visible(scrollNode)) return;
+  if (__ui_nodes[scrollNode].screenId != __ui_active_screen) return;
+  UIRect r;
+  ui_node_current_paint_rect(scrollNode, &r);
+  if (r.w <= 0 || r.h <= 0) return;
+  for (uint16_t c = 0; c < __ui_node_count; c++) {
+    if (c == scrollNode) continue;
+    if (c > scrollNode && c < __ui_nodes[scrollNode].subtreeEnd) continue;
+    if (__ui_nodes[c].dirty) continue;
+    if (!ui_is_effectively_visible(c)) continue;
+    if (__ui_nodes[c].screenId != __ui_active_screen) continue;
+    if (!ui_node_draws_before(scrollNode, c)) continue;
+    UIRect cr;
+    ui_node_current_paint_rect(c, &cr);
+    if (cr.w <= 0 || cr.h <= 0) continue;
+    if (ui_rects_intersect(r.x, r.y, r.w, r.h, cr.x, cr.y, cr.w, cr.h)) {
+      __ui_nodes[c].dirty = 1;
+    }
+  }
+}
+
+static inline void ui_mark_scroll_subtree_dirty(uint16_t scrollNode) {
+  ui_mark_subtree_dirty_local(scrollNode);
+  // Single overlap check at the container's paint rect covers every external
+  // higher-z neighbor of the viewport. The container index is the right one to
+  // pass: scroll content lives within the container's stacking context, so
+  // ui_node_draws_before(scrollNode, c) selects exactly the external layers that
+  // should be repaired when the viewport is repainted.
+  ui_mark_overlapping_higher_layers_dirty(scrollNode);
+}
+
+static inline void ui_mark_scroll_view_dirty(uint16_t scrollNode) {
+  if (scrollNode >= __ui_node_count) return;
+  __ui_nodes[scrollNode].dirty = 1;
+  ui_mark_scroll_view_overlaps_dirty(scrollNode);
+}
+
+static inline int16_t ui_scroll_ancestor_for_node(uint16_t nodeIdx) {
+  uint16_t p = __ui_nodes[nodeIdx].parent;
+  while (p != UI_NO_PARENT && p < __ui_node_count) {
+    if (__ui_nodes[p].scrollable) return (int16_t)p;
+    p = __ui_nodes[p].parent;
+  }
+  return -1;
+}
+
+static inline void ui_invalidate_scroll_canvas_for_node(uint16_t nodeIdx) {
+  int16_t scrollParent = ui_scroll_ancestor_for_node(nodeIdx);
+  if (scrollParent < 0) return;
+  if (__ui_nodes[scrollParent].virtualized) return;
+  if (__ui_nodes[scrollParent].contentHeight <= __ui_nodes[scrollParent].box.h) return;
+  int16_t span = __ui_nodes[scrollParent].box.h > 0 ? __ui_nodes[scrollParent].box.h : 1;
+  __ui_nodes[scrollParent].lastPaintedScrollY = __ui_nodes[scrollParent].scrollY - span;
+}
+`;
+}

package/src/ui-engine/runtime-header/display-shim.ts

@@ -0,0 +1,104 @@
+// Slice of the C++ runtime header (original source lines 902-999).
+// ui_display_* target/pixel/bitmap/rect/cursor/text shim layer.
+// See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
+export function emitDisplayShim(): string {
+  return `
+
+static inline CuttlefishDisplayTarget* ui_display_get_target() { return __ui_gfx; }
+static inline void ui_display_set_target(CuttlefishDisplayTarget* target) {
+  __ui_gfx = target ? target : display_defaultTarget();
+}
+static inline void ui_display_use_default_target() {
+  __ui_gfx = display_defaultTarget();
+}
+static inline uint8_t ui_display_is_default_target() {
+  return __ui_gfx == display_defaultTarget();
+}
+static inline int16_t ui_display_target_width() {
+  return display_targetWidth(__ui_gfx);
+}
+static inline int16_t ui_display_target_height() {
+  return display_targetHeight(__ui_gfx);
+}
+static inline int16_t ui_clamp_i16(int16_t value, int16_t lo, int16_t hi) {
+  if (value < lo) return lo;
+  if (value > hi) return hi;
+  return value;
+}
+static inline void ui_display_target_bounds(int16_t* left, int16_t* top, int16_t* right, int16_t* bottom) {
+  if (left) *left = (int16_t)(-__ui_draw_off_x);
+  if (top) *top = (int16_t)(-__ui_draw_off_y);
+  if (right) *right = (int16_t)(ui_display_target_width() - __ui_draw_off_x);
+  if (bottom) *bottom = (int16_t)(ui_display_target_height() - __ui_draw_off_y);
+}
+static inline uint8_t ui_clip_rect_to_display_target(int16_t* x, int16_t* y, int16_t* w, int16_t* h) {
+  if (!x || !y || !w || !h || *w <= 0 || *h <= 0) return 0;
+  int16_t left, top, right, bottom;
+  ui_display_target_bounds(&left, &top, &right, &bottom);
+  int16_t x0 = *x > left ? *x : left;
+  int16_t y0 = *y > top ? *y : top;
+  int16_t x1 = (int16_t)(*x + *w);
+  int16_t y1 = (int16_t)(*y + *h);
+  if (x1 > right) x1 = right;
+  if (y1 > bottom) y1 = bottom;
+  if (x0 >= x1 || y0 >= y1) return 0;
+  *x = x0;
+  *y = y0;
+  *w = (int16_t)(x1 - x0);
+  *h = (int16_t)(y1 - y0);
+  return 1;
+}
+static inline void ui_display_draw_pixel(int16_t x, int16_t y, UI_COLOR_T color) {
+  display_targetDrawPixel(__ui_gfx, x + __ui_draw_off_x, y + __ui_draw_off_y, UI_MAYBE_SNAP_MONO565(color));
+}
+static inline void ui_display_draw_rgb_bitmap(int16_t x, int16_t y, const UI_COLOR_T* bitmap, int16_t w, int16_t h) {
+  display_targetDrawRGBBitmap(__ui_gfx, x + __ui_draw_off_x, y + __ui_draw_off_y, bitmap, w, h);
+}
+static inline void ui_display_fill_rect(int16_t x, int16_t y, int16_t w, int16_t h, UI_COLOR_T color) {
+  display_targetFillRect(__ui_gfx, x + __ui_draw_off_x, y + __ui_draw_off_y, w, h, UI_MAYBE_SNAP_MONO565(color));
+}
+static inline void ui_display_draw_fast_hline(int16_t x, int16_t y, int16_t w, UI_COLOR_T color) {
+  display_targetDrawFastHLine(__ui_gfx, x + __ui_draw_off_x, y + __ui_draw_off_y, w, UI_MAYBE_SNAP_MONO565(color));
+}
+static inline void ui_display_draw_fast_vline(int16_t x, int16_t y, int16_t h, UI_COLOR_T color) {
+  display_targetDrawFastVLine(__ui_gfx, x + __ui_draw_off_x, y + __ui_draw_off_y, h, UI_MAYBE_SNAP_MONO565(color));
+}
+static inline void ui_display_fill_round_rect(int16_t x, int16_t y, int16_t w, int16_t h, int16_t r, UI_COLOR_T color) {
+  display_targetFillRoundRect(__ui_gfx, x + __ui_draw_off_x, y + __ui_draw_off_y, w, h, r, UI_MAYBE_SNAP_MONO565(color));
+}
+static inline void ui_display_draw_rect(int16_t x, int16_t y, int16_t w, int16_t h, UI_COLOR_T color) {
+  display_targetDrawRect(__ui_gfx, x + __ui_draw_off_x, y + __ui_draw_off_y, w, h, UI_MAYBE_SNAP_MONO565(color));
+}
+static inline void ui_display_draw_round_rect(int16_t x, int16_t y, int16_t w, int16_t h, int16_t r, UI_COLOR_T color) {
+  display_targetDrawRoundRect(__ui_gfx, x + __ui_draw_off_x, y + __ui_draw_off_y, w, h, r, UI_MAYBE_SNAP_MONO565(color));
+}
+static inline void ui_display_draw_line(int16_t x0, int16_t y0, int16_t x1, int16_t y1, UI_COLOR_T color) {
+  display_targetDrawLine(__ui_gfx, x0 + __ui_draw_off_x, y0 + __ui_draw_off_y,
+    x1 + __ui_draw_off_x, y1 + __ui_draw_off_y, UI_MAYBE_SNAP_MONO565(color));
+}
+static inline void ui_display_fill_circle(int16_t x, int16_t y, int16_t r, UI_COLOR_T color) {
+  display_targetFillCircle(__ui_gfx, x + __ui_draw_off_x, y + __ui_draw_off_y, r, UI_MAYBE_SNAP_MONO565(color));
+}
+static inline void ui_display_draw_circle(int16_t x, int16_t y, int16_t r, UI_COLOR_T color) {
+  display_targetDrawCircle(__ui_gfx, x + __ui_draw_off_x, y + __ui_draw_off_y, r, UI_MAYBE_SNAP_MONO565(color));
+}
+static inline void ui_display_set_cursor(int16_t x, int16_t y) {
+  display_targetSetCursor(__ui_gfx, x + __ui_draw_off_x, y + __ui_draw_off_y);
+}
+static inline void ui_display_set_text_color(UI_COLOR_T fg, UI_COLOR_T bg) {
+  display_targetSetTextColorBg(__ui_gfx, fg, bg);
+}
+static inline void ui_display_set_text_color_solid(UI_COLOR_T fg) {
+  display_targetSetTextColor(__ui_gfx, fg);
+}
+static inline void ui_display_set_text_size(uint8_t size) {
+  display_targetSetTextSize(__ui_gfx, size);
+}
+static inline void ui_display_set_text_wrap(bool wrap) {
+  display_targetSetTextWrap(__ui_gfx, wrap);
+}
+static inline void ui_display_print(const char* text) {
+  display_targetPrint(__ui_gfx, text);
+}
+`;
+}

package/src/ui-engine/runtime-header/forward-decls.ts

@@ -0,0 +1,137 @@
+// Slice of the C++ runtime header (original source lines 622-752).
+// navigate, canvas/scroll/text/paint/clip/AA/image forward declarations, persistent canvas globals.
+// See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
+export function emitForwardDecls(): string {
+  return `
+static uint8_t __ui_fade_opacity = 100;  // fade-in animation (0=transparent, 100=full)
+static uint16_t __ui_fade_elapsed = 0;
+static uint16_t __ui_fade_duration = 200; // ms
+
+// Early forward declaration: ui_navigate (below) calls ui_release_canvas_state
+// and ui_set_pressed (defined later) during screen changes. Needed on native
+// (single TU, no Arduino auto-prototyper).
+static inline void ui_release_canvas_state();
+static inline void ui_set_pressed(uint16_t nodeIdx, uint8_t pressed);
+static inline void ui_refresh_active_screen_bg_node();
+
+// Navigate to a screen by index. Marks the new screen's nodes dirty + starts fade.
+static inline void ui_navigate(uint8_t screenIdx) {
+  if (screenIdx >= __ui_screen_count || screenIdx == __ui_active_screen) return;
+  __ui_active_screen = screenIdx;
+  ui_refresh_active_screen_bg_node();
+  // Reset scroll/touch state so the old screen's scroll container doesn't
+  // interfere with the new screen. Release any currently-pressed button FIRST:
+  // navigation fires from a button's click handler during touch-down, so the
+  // matching touch-up release would otherwise be suppressed by the reset below
+  // and the button would stay stuck in its :pressed color.
+  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);
+  }
+  __ui_scroll_node = -1;
+  __ui_touch_node = -1;
+  __ui_touch_state = 0;
+  __ui_kb_visible = 0;
+  // Free every persistent canvas so the new screen allocates into a clean,
+  // unfragmented heap. Without this, the previous screen's canvas buffer stays
+  // resident and fragments the heap, so the new screen's buffer can't get a
+  // contiguous block (the "works first, then blanks until reset" symptom).
+  ui_release_canvas_state();
+  // Clear the entire display so old screen content doesn't show. On deferred-
+  // refresh panels (e-ink) a full clear flashes, so skip it — the all-nodes-
+  // dirty marking below drives a full repaint via partial refresh instead.
+#ifndef UI_REFRESH_DEFERRED
+  display_fillScreen(0x0000);
+#endif
+  // Mark all nodes dirty so the new screen fully redraws.
+  for (uint16_t i = 0; i < __ui_node_count; i++) {
+    __ui_nodes[i].dirty = 1;
+    __ui_nodes[i].lastTextHeight = 0;
+    __ui_nodes[i].layoutCacheKey = 0;
+    if (__ui_nodes[i].kind == NODE_PROGRESS || __ui_nodes[i].kind == NODE_RANGE) __ui_nodes[i].lastTextWidth = -1;
+    else __ui_nodes[i].lastTextWidth = 0;
+  }
+}
+extern const uint16_t __ui_font_face_count;
+
+#define UI_NO_PARENT 0xFFFF   // sentinel: out of uint16_t node-index range
+
+// Forward declarations suppress Arduino's auto-prototyper, which would insert
+// prototypes before UIFontFace/UIFontGlyph are declared.
+static inline const UIFontFace* ui_font_face(uint8_t id);
+static inline const UIFontGlyph* ui_font_glyph(const UIFontFace* face, uint16_t codepoint);
+static inline uint8_t ui_font_alpha_at(const UIFontFace* face, const UIFontGlyph* glyph, uint16_t pixelIndex);
+static inline uint16_t ui_asset_text_width(const char* text, const UIFontFace* face);
+static inline uint8_t ui_asset_text_height(const UIFontFace* face);
+static inline uint8_t ui_draw_asset_text(const char* text, int16_t x, int16_t y, UI_COLOR_T fg, UI_COLOR_T bg, uint8_t antialias, uint8_t fontFace);
+static inline uint16_t ui_text_width(const char* text, uint8_t ts, uint8_t fontFace, int8_t letterSpacing);
+struct UITextLine;
+static inline uint8_t ui_text_next_line(const char** cursor, uint16_t maxWidth, uint8_t whiteSpaceMode, uint8_t ts, uint8_t fontFace, int8_t letterSpacing, UITextLine* out);
+static inline void ui_text_layout_metrics(const char* text, uint16_t maxWidth, uint8_t whiteSpaceMode, uint8_t ts, uint8_t fontFace, int8_t letterSpacing, uint8_t lineHeight, uint16_t* outW, uint16_t* outH);
+static inline void ui_invalidate_text_layout_cache(uint16_t nodeIdx);
+static inline uint16_t ui_node_text_max_width(uint16_t nodeIdx);
+static inline void ui_node_text_layout_metrics(uint16_t nodeIdx, uint16_t textMaxW, uint16_t* outW, uint16_t* outH);
+static inline uint8_t ui_rects_intersect(int16_t ax, int16_t ay, int16_t aw, int16_t ah, int16_t bx, int16_t by, int16_t bw, int16_t bh);
+static inline uint8_t ui_is_effectively_visible(uint16_t nodeIdx);
+static inline uint8_t ui_node_draws_before(uint16_t a, uint16_t b);
+static inline void ui_node_paint_rect(uint16_t nodeIdx, int16_t baseX, int16_t baseY, int16_t drawX, int16_t drawY, uint16_t textW, uint16_t textH, UIRect* out);
+static inline void ui_node_current_paint_rect(uint16_t nodeIdx, UIRect* out);
+static inline uint8_t ui_subtree_current_paint_rect(uint16_t nodeIdx, UIRect* out);
+static inline void ui_mark_overlapping_higher_layers_dirty(uint16_t nodeIdx);
+static inline void ui_mark_overlapping_higher_layers_dirty_for_rect(uint16_t nodeIdx, const UIRect* r);
+static inline void ui_mark_scroll_view_dirty(uint16_t scrollNode);
+static inline void ui_release_canvas_state();
+static inline void ui_set_visible(uint16_t nodeIdx, uint8_t visible);
+static inline void ui_invalidate_scroll_canvas_for_node(uint16_t nodeIdx);
+static inline uint8_t ui_clip_rect_to_rect(UIRect* r, const UIRect* clip);
+static inline void ui_fill_rect_clipped(int16_t x, int16_t y, int16_t w, int16_t h, const UIRect* clip, UI_COLOR_T color);
+static inline void ui_hline_clipped(int16_t x, int16_t y, int16_t w, const UIRect* clip, UI_COLOR_T color);
+static inline void ui_vline_clipped(int16_t x, int16_t y, int16_t h, const UIRect* clip, UI_COLOR_T color);
+static inline void ui_draw_rect_outline_clipped(int16_t x, int16_t y, int16_t w, int16_t h, uint8_t style, uint8_t width, const UIRect* clip, UI_COLOR_T color);
+static inline void ui_draw_node_decoration_clipped(uint16_t nodeIdx, int16_t drawY, const UIRect* clip);
+// Forward declarations for functions used before their definition in the
+// single native translation unit (Arduino's auto-prototyper hides this;
+// native emits one TU so explicit forwards are needed).
+static inline int8_t ui_rich_link_hit(uint16_t nodeIdx, int16_t px, int16_t py);
+static inline CuttlefishCanvas16* ui_aa_begin(int16_t w, int16_t h, UI_COLOR_T bg);
+static inline void ui_aa_end(CuttlefishCanvas16* c);
+static inline void ui_aa_push(CuttlefishCanvas16* c, int16_t dx, int16_t dy);
+static inline void ui_aa_line(CuttlefishCanvas16* c, float x0, float y0, float x1, float y1, UI_COLOR_T color);
+static inline void ui_aa_circle(CuttlefishCanvas16* c, int16_t cx, int16_t cy, float r, UI_COLOR_T color);
+static inline void ui_aa_fill_circle(CuttlefishCanvas16* c, int16_t cx, int16_t cy, float r, UI_COLOR_T color);
+static inline uint8_t ui_repair_current_node_paint_with_parent(uint16_t nodeIdx, UIRect* r);
+static inline void ui_clear_node_paint_rect(uint16_t nodeIdx, const UIRect* paintRect);
+static inline uint8_t ui_try_repair_geometry_fill(uint16_t nodeIdx, const UIRect* oldRect);
+static inline void ui_draw_node_border(uint16_t i, int16_t drawX, int16_t drawY, UI_COLOR_T color);
+static inline void ui_draw_node_outline(uint16_t i, int16_t drawX, int16_t drawY);
+static inline void ui_draw_gradient_fill(uint16_t i, int16_t drawY);
+static inline uint8_t ui_rotation_quadrant(int16_t deg);
+static inline int16_t ui_rotated_face_w(uint16_t nodeIdx, int16_t w, int16_t h);
+static inline int16_t ui_rotated_face_h(uint16_t nodeIdx, int16_t w, int16_t h);
+static inline void ui_draw_image_rotated(const UIImage* img, int16_t x, int16_t y, int16_t rotateDeg);
+static inline void ui_draw_image_with_fit(const UIImage* img, int16_t x, int16_t y, int16_t rotateDeg,
+                                          uint8_t fitMode, int16_t targetW, int16_t targetH);
+static inline void ui_draw_scaled_image(const UIImage* img, int16_t x, int16_t y, int16_t rotateDeg,
+                                         int16_t drawW, int16_t drawH);
+
+static CuttlefishDisplayTarget* __ui_gfx = display_defaultTarget();
+// Persistent canvas slots, all freed on screen change (ui_navigate) so each
+// screen starts with a clean heap. Without this, the first screen's canvas
+// buffer stays resident and fragments the heap, so a later screen's buffer
+// can't get a contiguous block — manifesting as that element blanking until a
+// hard reset. File-scoped (not function-static) so ui_release_canvas_state can
+// reach them.
+static CuttlefishCanvas16* __ui_container_canvas = nullptr;  // Mode B shift-and-repair
+static CuttlefishCanvas16* __ui_list_canvas = nullptr;       // virtualized <list> viewport
+static int16_t __ui_list_canvas_node = -1;                   // node currently represented by __ui_list_canvas
+static CuttlefishCanvas16* __ui_node_canvas = nullptr;       // <canvas> element offscreen
+static CuttlefishCanvas16* __ui_repair_canvas = nullptr;     // buffered-paint / exposed-strip
+static int16_t __ui_canvas_fallback_w = 0;                   // dimensions for direct <canvas> fallback
+static int16_t __ui_canvas_fallback_h = 0;
+// Draw offset: normally zero. The <canvas> allocation fallback sets it so
+// callback-local coordinates draw into the node's current display/canvas target.
+static int16_t __ui_draw_off_x = 0;
+static int16_t __ui_draw_off_y = 0;
+
+// Release every persistent canvas so the next screen allocates into a clean`;
+}