@typecad/ui 0.1.0-alpha.1

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

@@ -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() {
+    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`;
+}

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

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

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

@@ -0,0 +1,8 @@
+// Slice of the C++ runtime header (original source lines 5770-5770).
+// Closing #endif of the __TC_UI_RUNTIME guard.
+// See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
+export function emitGuardClose() {
+    return `
+#endif
+`;
+}

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

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

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

@@ -0,0 +1,300 @@
+// Slice of the C++ runtime header (original source lines 1155-1448).
+// Tail of framebuffer block + image rotation/fit/scaled/rotated drawing.
+// See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
+export function emitImageDrawing() {
+    return `
+// ── Full-screen framebuffer (opt-in PSRAM perf experiment) ───────────────────
+// Disabled by default: pushing a full 320×240 frame for a tiny dirty button can
+// look like a global brightness flash on SPI TFTs. Enable only when a target
+// has enough PSRAM and a full-frame repaint is preferable to partial updates.
+static CuttlefishCanvas16* __ui_fb = nullptr;
+static uint8_t __ui_fb_tried = 0;  // 0 = not yet attempted, 1 = alloc attempted
+
+// Get the framebuffer, allocating once (in PSRAM when available). Returns null
+// when PSRAM is absent or the allocation failed — callers fall back to direct.
+static inline CuttlefishCanvas16* ui_get_framebuffer() {
+  if (__ui_fb_tried) return __ui_fb;  // one-time attempt; null means "none"
+  __ui_fb_tried = 1;
+#if UI_USE_FULL_FRAMEBUFFER && defined(ESP32) && defined(BOARD_HAS_PSRAM)
+  if (psramFound()) {
+    int16_t fw = display_width();
+    int16_t fh = display_height();
+    // GFXcanvas16 uses ps_malloc when ESP32 PSRAM malloc is hooked in via the
+    // Arduino core; the allocation succeeds only if PSRAM is really present.
+    __ui_fb = display_createCanvasPsram(fw, fh);
+    if (!__ui_fb || !display_canvasBuffer(__ui_fb)) {
+      // Allocation failed (PSRAM too small / not really mapped) — give up.
+      __ui_fb = nullptr;
+    }
+  }
+#endif
+  return __ui_fb;
+}
+
+// Push the entire framebuffer to the display in one bulk SPI transaction.
+static inline void ui_push_framebuffer() {
+  if (!__ui_fb || !display_canvasBuffer(__ui_fb)) return;
+  int16_t w = display_canvasWidth(__ui_fb);
+  int16_t h = display_canvasHeight(__ui_fb);
+  display_startWrite();
+  display_setAddrWindow(0, 0, w, h);
+  display_writePixels(display_canvasBuffer(__ui_fb), (uint32_t)w * h);
+  display_endWrite();
+}
+
+static inline uint8_t ui_rotation_quadrant(int16_t deg) {
+  int16_t normalized = deg % 360;
+  if (normalized < 0) normalized += 360;
+  if (normalized == 90) return 1;
+  if (normalized == 180) return 2;
+  if (normalized == 270) return 3;
+  return 0;
+}
+
+static inline int16_t ui_rotated_face_w(uint16_t nodeIdx, int16_t w, int16_t h) {
+  if (__ui_nodes[nodeIdx].kind != NODE_IMG &&
+      !(__ui_nodes[nodeIdx].kind == NODE_FILL && __ui_nodes[nodeIdx].gradientEnabled == 0)) return w;
+  uint8_t q = ui_rotation_quadrant(__ui_nodes[nodeIdx].rotateDeg);
+  return (q == 1 || q == 3) ? h : w;
+}
+
+static inline int16_t ui_rotated_face_h(uint16_t nodeIdx, int16_t w, int16_t h) {
+  if (__ui_nodes[nodeIdx].kind != NODE_IMG &&
+      !(__ui_nodes[nodeIdx].kind == NODE_FILL && __ui_nodes[nodeIdx].gradientEnabled == 0)) return h;
+  uint8_t q = ui_rotation_quadrant(__ui_nodes[nodeIdx].rotateDeg);
+  return (q == 1 || q == 3) ? w : h;
+}
+
+// Draw image with object-fit: 0=none, 1=fill, 2=contain, 3=cover, 4=scale-down.
+// The sampler is bounded to the target box first, then quarter-turn rotated.
+// This keeps cover cropped inside the element instead of overpainting siblings.
+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) {
+  if (!img || !img->data || img->w == 0 || img->h == 0 || targetW <= 0 || targetH <= 0) return;
+  int16_t srcW = img->w, srcH = img->h;
+  int16_t drawW = srcW, drawH = srcH;
+  int16_t offX = (targetW - drawW) / 2;
+  int16_t offY = (targetH - drawH) / 2;
+
+  if (fitMode == 1) {
+    drawW = targetW;
+    drawH = targetH;
+    offX = 0;
+    offY = 0;
+  } else if (fitMode == 2 || fitMode == 3 || fitMode == 4) {
+    int32_t scaleX = ((int32_t)targetW * 1000) / srcW;
+    int32_t scaleY = ((int32_t)targetH * 1000) / srcH;
+    if (scaleX < 1) scaleX = 1;
+    if (scaleY < 1) scaleY = 1;
+    int32_t scale = scaleX;
+    if (fitMode == 2) {
+      if (scaleY < scaleX) scale = scaleY;
+    } else if (fitMode == 3) {
+      if (scaleY > scaleX) scale = scaleY;
+    } else {
+      if (scaleY < scaleX) scale = scaleY;
+      if (scale > 1000) scale = 1000;
+    }
+    drawW = (int16_t)((int32_t)srcW * scale / 1000);
+    drawH = (int16_t)((int32_t)srcH * scale / 1000);
+    if (drawW < 1) drawW = 1;
+    if (drawH < 1) drawH = 1;
+    if (fitMode == 3) {
+      if (drawW < targetW) drawW = targetW;
+      if (drawH < targetH) drawH = targetH;
+    }
+    offX = (targetW - drawW) / 2;
+    offY = (targetH - drawH) / 2;
+  }
+
+  uint8_t q = ui_rotation_quadrant(rotateDeg);
+  int16_t clipX = x;
+  int16_t clipY = y;
+  int16_t clipW = (q == 1 || q == 3) ? targetH : targetW;
+  int16_t clipH = (q == 1 || q == 3) ? targetW : targetH;
+  if (!ui_clip_rect_to_display_target(&clipX, &clipY, &clipW, &clipH)) return;
+  int16_t txStart = 0, txEnd = targetW, tyStart = 0, tyEnd = targetH;
+  if (q == 0) {
+    txStart = ui_clamp_i16((int16_t)(clipX - x), 0, targetW);
+    txEnd = ui_clamp_i16((int16_t)(clipX + clipW - x), 0, targetW);
+    tyStart = ui_clamp_i16((int16_t)(clipY - y), 0, targetH);
+    tyEnd = ui_clamp_i16((int16_t)(clipY + clipH - y), 0, targetH);
+  } else if (q == 1) {
+    txStart = ui_clamp_i16((int16_t)(clipY - y), 0, targetW);
+    txEnd = ui_clamp_i16((int16_t)(clipY + clipH - y), 0, targetW);
+    tyStart = ui_clamp_i16((int16_t)(x + targetH - (clipX + clipW)), 0, targetH);
+    tyEnd = ui_clamp_i16((int16_t)(x + targetH - clipX), 0, targetH);
+  } else if (q == 2) {
+    txStart = ui_clamp_i16((int16_t)(x + targetW - (clipX + clipW)), 0, targetW);
+    txEnd = ui_clamp_i16((int16_t)(x + targetW - clipX), 0, targetW);
+    tyStart = ui_clamp_i16((int16_t)(y + targetH - (clipY + clipH)), 0, targetH);
+    tyEnd = ui_clamp_i16((int16_t)(y + targetH - clipY), 0, targetH);
+  } else {
+    txStart = ui_clamp_i16((int16_t)(y + targetW - (clipY + clipH)), 0, targetW);
+    txEnd = ui_clamp_i16((int16_t)(y + targetW - clipY), 0, targetW);
+    tyStart = ui_clamp_i16((int16_t)(clipX - x), 0, targetH);
+    tyEnd = ui_clamp_i16((int16_t)(clipX + clipW - x), 0, targetH);
+  }
+  if (txStart >= txEnd || tyStart >= tyEnd) return;
+  for (int16_t ty = tyStart; ty < tyEnd; ty++) {
+    int16_t localY = ty - offY;
+    if (localY < 0 || localY >= drawH) continue;
+    int16_t srcY = ((int32_t)localY * srcH) / drawH;
+    if (srcY < 0) srcY = 0;
+    if (srcY >= srcH) srcY = srcH - 1;
+    for (int16_t tx = txStart; tx < txEnd; tx++) {
+      int16_t localX = tx - offX;
+      if (localX < 0 || localX >= drawW) continue;
+      int16_t srcX = ((int32_t)localX * srcW) / drawW;
+      if (srcX < 0) srcX = 0;
+      if (srcX >= srcW) srcX = srcW - 1;
+      UI_COLOR_T color = img->data[(int32_t)srcY * srcW + srcX];
+      int16_t dx = tx;
+      int16_t dy = ty;
+      if (q == 1) {
+        dx = targetH - 1 - ty;
+        dy = tx;
+      } else if (q == 2) {
+        dx = targetW - 1 - tx;
+        dy = targetH - 1 - ty;
+      } else if (q == 3) {
+        dx = ty;
+        dy = targetW - 1 - tx;
+      }
+      ui_display_draw_pixel(x + dx, y + dy, color);
+    }
+  }
+}
+
+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) {
+  if (!img || !img->data || img->w == 0 || img->h == 0 || drawW <= 0 || drawH <= 0) return;
+  uint8_t q = ui_rotation_quadrant(rotateDeg);
+  int16_t clipX = x;
+  int16_t clipY = y;
+  int16_t clipW = (q == 1 || q == 3) ? drawH : drawW;
+  int16_t clipH = (q == 1 || q == 3) ? drawW : drawH;
+  if (!ui_clip_rect_to_display_target(&clipX, &clipY, &clipW, &clipH)) return;
+  int16_t dxStart = 0, dxEnd = drawW, dyStart = 0, dyEnd = drawH;
+  if (q == 0) {
+    dxStart = ui_clamp_i16((int16_t)(clipX - x), 0, drawW);
+    dxEnd = ui_clamp_i16((int16_t)(clipX + clipW - x), 0, drawW);
+    dyStart = ui_clamp_i16((int16_t)(clipY - y), 0, drawH);
+    dyEnd = ui_clamp_i16((int16_t)(clipY + clipH - y), 0, drawH);
+  } else if (q == 1) {
+    dxStart = ui_clamp_i16((int16_t)(clipY - y), 0, drawW);
+    dxEnd = ui_clamp_i16((int16_t)(clipY + clipH - y), 0, drawW);
+    dyStart = ui_clamp_i16((int16_t)(x + drawH - (clipX + clipW)), 0, drawH);
+    dyEnd = ui_clamp_i16((int16_t)(x + drawH - clipX), 0, drawH);
+  } else if (q == 2) {
+    dxStart = ui_clamp_i16((int16_t)(x + drawW - (clipX + clipW)), 0, drawW);
+    dxEnd = ui_clamp_i16((int16_t)(x + drawW - clipX), 0, drawW);
+    dyStart = ui_clamp_i16((int16_t)(y + drawH - (clipY + clipH)), 0, drawH);
+    dyEnd = ui_clamp_i16((int16_t)(y + drawH - clipY), 0, drawH);
+  } else {
+    dxStart = ui_clamp_i16((int16_t)(y + drawW - (clipY + clipH)), 0, drawW);
+    dxEnd = ui_clamp_i16((int16_t)(y + drawW - clipY), 0, drawW);
+    dyStart = ui_clamp_i16((int16_t)(clipX - x), 0, drawH);
+    dyEnd = ui_clamp_i16((int16_t)(clipX + clipW - x), 0, drawH);
+  }
+  if (dxStart >= dxEnd || dyStart >= dyEnd) return;
+  if (q == 0) {
+    // Simple case: no rotation, draw with scaling
+    if (drawW == img->w && drawH == img->h) {
+      int16_t rows = (int16_t)(dyEnd - dyStart);
+      int16_t cols = (int16_t)(dxEnd - dxStart);
+      for (int16_t row = 0; row < rows; row++) {
+        ui_display_draw_rgb_bitmap((int16_t)(x + dxStart), (int16_t)(y + dyStart + row),
+          img->data + (int32_t)(dyStart + row) * img->w + dxStart, cols, 1);
+      }
+    } else {
+      // Scale using nearest-neighbor
+      for (int16_t dy = dyStart; dy < dyEnd; dy++) {
+        int16_t srcY = ((int32_t)dy * img->h) / drawH;
+        for (int16_t dx = dxStart; dx < dxEnd; dx++) {
+          int16_t srcX = ((int32_t)dx * img->w) / drawW;
+          UI_COLOR_T color = img->data[(int32_t)srcY * img->w + srcX];
+          ui_display_draw_pixel(x + dx, y + dy, color);
+        }
+      }
+    }
+    return;
+  }
+  for (int16_t dy = dyStart; dy < dyEnd; dy++) {
+    int16_t srcY = ((int32_t)dy * img->h) / drawH;
+    for (int16_t dx = dxStart; dx < dxEnd; dx++) {
+      int16_t srcX = ((int32_t)dx * img->w) / drawW;
+      UI_COLOR_T color = img->data[(int32_t)srcY * img->w + srcX];
+      int16_t rdx = 0, rdy = 0;
+      if (q == 1) {
+        rdx = drawH - 1 - dy;
+        rdy = dx;
+      } else if (q == 2) {
+        rdx = drawW - 1 - dx;
+        rdy = drawH - 1 - dy;
+      } else {
+        rdx = dy;
+        rdy = drawW - 1 - dx;
+      }
+      ui_display_draw_pixel(x + rdx, y + rdy, color);
+    }
+  }
+}
+
+static inline void ui_draw_image_rotated(const UIImage* img, int16_t x, int16_t y, int16_t rotateDeg) {
+   uint8_t q = ui_rotation_quadrant(rotateDeg);
+   int16_t clipX = x;
+   int16_t clipY = y;
+   int16_t clipW = (q == 1 || q == 3) ? img->h : img->w;
+   int16_t clipH = (q == 1 || q == 3) ? img->w : img->h;
+   if (!ui_clip_rect_to_display_target(&clipX, &clipY, &clipW, &clipH)) return;
+   if (q == 0) {
+     int16_t sx0 = ui_clamp_i16((int16_t)(clipX - x), 0, (int16_t)img->w);
+     int16_t sy0 = ui_clamp_i16((int16_t)(clipY - y), 0, (int16_t)img->h);
+     int16_t sw = ui_clamp_i16(clipW, 0, (int16_t)(img->w - sx0));
+     int16_t sh = ui_clamp_i16(clipH, 0, (int16_t)(img->h - sy0));
+     for (int16_t row = 0; row < sh; row++) {
+       ui_display_draw_rgb_bitmap((int16_t)(x + sx0), (int16_t)(y + sy0 + row),
+         img->data + (int32_t)(sy0 + row) * img->w + sx0, sw, 1);
+     }
+     return;
+   }
+   uint16_t sxStart = 0, sxEnd = img->w, syStart = 0, syEnd = img->h;
+   if (q == 1) {
+     sxStart = (uint16_t)ui_clamp_i16((int16_t)(clipY - y), 0, (int16_t)img->w);
+     sxEnd = (uint16_t)ui_clamp_i16((int16_t)(clipY + clipH - y), 0, (int16_t)img->w);
+     syStart = (uint16_t)ui_clamp_i16((int16_t)(x + img->h - (clipX + clipW)), 0, (int16_t)img->h);
+     syEnd = (uint16_t)ui_clamp_i16((int16_t)(x + img->h - clipX), 0, (int16_t)img->h);
+   } else if (q == 2) {
+     sxStart = (uint16_t)ui_clamp_i16((int16_t)(x + img->w - (clipX + clipW)), 0, (int16_t)img->w);
+     sxEnd = (uint16_t)ui_clamp_i16((int16_t)(x + img->w - clipX), 0, (int16_t)img->w);
+     syStart = (uint16_t)ui_clamp_i16((int16_t)(y + img->h - (clipY + clipH)), 0, (int16_t)img->h);
+     syEnd = (uint16_t)ui_clamp_i16((int16_t)(y + img->h - clipY), 0, (int16_t)img->h);
+   } else {
+     sxStart = (uint16_t)ui_clamp_i16((int16_t)(y + img->w - (clipY + clipH)), 0, (int16_t)img->w);
+     sxEnd = (uint16_t)ui_clamp_i16((int16_t)(y + img->w - clipY), 0, (int16_t)img->w);
+     syStart = (uint16_t)ui_clamp_i16((int16_t)(clipX - x), 0, (int16_t)img->h);
+     syEnd = (uint16_t)ui_clamp_i16((int16_t)(clipX + clipW - x), 0, (int16_t)img->h);
+   }
+   if (sxStart >= sxEnd || syStart >= syEnd) return;
+   for (uint16_t sy = syStart; sy < syEnd; sy++) {
+     for (uint16_t sx = sxStart; sx < sxEnd; sx++) {
+       UI_COLOR_T color = img->data[(uint32_t)sy * img->w + sx];
+       int16_t dx = 0;
+       int16_t dy = 0;
+       if (q == 1) {
+         dx = (int16_t)(img->h - 1 - sy);
+         dy = (int16_t)sx;
+       } else if (q == 2) {
+         dx = (int16_t)(img->w - 1 - sx);
+         dy = (int16_t)(img->h - 1 - sy);
+       } else {
+         dx = (int16_t)sy;
+         dy = (int16_t)(img->w - 1 - sx);
+       }
+       ui_display_draw_pixel(x + dx, y + dy, color);
+     }
+   }
+ }
+`;
+}

package/dist/ui-engine/runtime-header/init-press-input.d.ts

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

package/dist/ui-engine/runtime-header/init-press-input.js

@@ -0,0 +1,126 @@
+// Slice of the C++ runtime header (original source lines 2442-2561).
+// ui_init, press/release entry points, pin-watch polling.
+// See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
+export function emitInitPressInput() {
+    return `
+// Initial draw: mark all nodes dirty so the first ui_tick renders everything.
+// Called once in setup() before the loop begins.
+// Also seed each text-bound node's buffer from its flash literal so the first
+// strcmp in ui_tick has a valid baseline (no spurious redraw on frame 1).
+static inline void ui_init(void) {
+  // Allocate the per-node scroll-canvas-OK flag array (once; __ui_node_count
+  // is a compile-time constant known by this point). calloc zeroes it — all
+  // containers start locked until the scroll-container loop proves their
+  // canvas fits.
+  if (!__ui_scroll_canvas_ok && __ui_node_count > 0) {
+    __ui_scroll_canvas_ok = (uint8_t*)calloc(__ui_node_count, sizeof(uint8_t));
+  }
+  if (!__ui_scroll_mem_warned && __ui_node_count > 0) {
+    __ui_scroll_mem_warned = (uint8_t*)calloc(__ui_node_count, sizeof(uint8_t));
+  }
+  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;
+    }
+  }
+  for (uint16_t i = 0; i < __ui_binding_count; i++) {
+    if (__ui_bindings[i].prop == PROP_TEXT && __ui_bindings[i].textFn) {
+      uint16_t n = __ui_bindings[i].node;
+      __ui_nodes[n].hasTextBinding = 1;
+      strncpy(__ui_nodes[n].textBuffer, __ui_nodes[n].text ? __ui_nodes[n].text : "", UI_TEXT_BUF);
+      __ui_nodes[n].textBuffer[UI_TEXT_BUF] = '\\0';
+    }
+  }
+  // Seed virtualized-list runtime state. The fn pointers can't be baked into
+  // the static node initializer: ui.bindList is resolved AFTER ui.mount lowers
+  // the HTML, so the lowering can't see the binding yet. Instead the lowering
+  // emits the UIListBinding table (the binding's fn bodies) and ui_init copies
+  // the pointers onto each <list> node here, then computes the initial count
+  // and contentHeight so the first paint and the scroll clamp bound are correct.
+  for (uint16_t b = 0; b < __ui_list_binding_count; b++) {
+    uint16_t n = __ui_list_bindings[b].node;
+    if (n >= __ui_node_count || !__ui_nodes[n].virtualized) continue;
+    __ui_nodes[n].listCountFn = __ui_list_bindings[b].countFn;
+    __ui_nodes[n].listItemFn = __ui_list_bindings[b].itemFn;
+    __ui_nodes[n].listTapFn = __ui_list_bindings[b].tapFn;
+  }
+  for (uint16_t i = 0; i < __ui_node_count; i++) {
+    if (!__ui_nodes[i].virtualized || !__ui_nodes[i].listCountFn) continue;
+    uint16_t ih = __ui_nodes[i].listItemHeight > 0 ? __ui_nodes[i].listItemHeight : 24;
+    uint16_t cnt = __ui_nodes[i].listCountFn();
+    __ui_nodes[i].listCount = cnt;
+    __ui_nodes[i].contentHeight = (int16_t)((uint32_t)cnt * ih);
+    __ui_nodes[i].scrollY = 0;
+    __ui_nodes[i].overscrollPx = 0;
+    __ui_nodes[i].settling = 0;
+    __ui_nodes[i].lastPaintedScrollY = -(__ui_nodes[i].box.h > 0 ? __ui_nodes[i].box.h : 1);
+  }
+  ui_build_draw_order();
+  ui_build_scroll_owner_table();
+  ui_refresh_active_screen_bg_node();
+}
+
+// Debounce: ignore press/release events within 50ms of the last edge.
+// Mechanical switches bounce (multiple edges in ~5-20ms); without this, the
+// transition gets armed/interrupted dozens of times per physical press.
+static volatile uint32_t __ui_last_edge_time = 0;
+#define UI_DEBOUNCE_MS 50
+
+static inline void ui_set_pressed(uint16_t nodeIdx, uint8_t pressed) {
+  __ui_nodes[nodeIdx].value = pressed ? 1 : 0;
+  ui_mark_dirty(nodeIdx);
+  for (uint16_t i = 0; i < __ui_trans_count; i++) {
+    if (__ui_trans[i].node == nodeIdx) {
+      __ui_trans[i].prevValue = __ui_trans[i].prop == PROP_FG ? __ui_nodes[nodeIdx].fg : __ui_nodes[nodeIdx].bg;
+      __ui_trans[i].targetValue = pressed ? __ui_trans[i].pressedTarget : __ui_trans[i].baseTarget;
+      __ui_trans[i].elapsed = 0;
+      __ui_trans[i].active = 1;
+    }
+  }
+}
+
+// Press / release entry points that node.onPress(pin) lowers to.
+// On press, arm transitions toward the :pressed target color; on release,
+// arm them back toward the base color (interrupt-and-re-lerp from current).
+static inline void ui_on_press(uint16_t nodeIdx) {
+  uint32_t now = millis();
+  if (now - __ui_last_edge_time < UI_DEBOUNCE_MS) return;
+  __ui_last_edge_time = now;
+  ui_set_pressed(nodeIdx, 1);
+}
+static inline void ui_on_release(uint16_t nodeIdx) {
+  uint32_t now = millis();
+  if (now - __ui_last_edge_time < UI_DEBOUNCE_MS) return;
+  __ui_last_edge_time = now;
+  ui_set_pressed(nodeIdx, 0);
+}
+
+// Pin-watch callback type: void fn(void)
+typedef void (*PinWatchCallback)(void);
+
+struct UIPinWatch {
+  uint8_t pin;
+  uint8_t lastState;   // for edge detection
+  PinWatchCallback cb; // fires on falling edge
+};
+
+// Populated by the emit layer from ui.watchPin() calls.
+extern UIPinWatch __ui_pin_watches[];
+extern const uint16_t __ui_pin_watch_count;
+
+// Poll all configured pin-watchers. Called at the start of ui_tick each frame.
+// Detects falling edges with natural debounce from the ~16ms frame rate.
+static inline void ui_poll_inputs() {
+  for (uint16_t i = 0; i < __ui_pin_watch_count; i++) {
+    uint8_t val = digitalRead(__ui_pin_watches[i].pin);
+    if (val == LOW && __ui_pin_watches[i].lastState == HIGH) {
+      if (__ui_pin_watches[i].cb) __ui_pin_watches[i].cb();
+    }
+    __ui_pin_watches[i].lastState = val;
+  }
+}
+`;
+}

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

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