@typecad/ui 0.1.0-alpha.2 → 1.0.0-alpha.10

package/dist/ui-engine/runtime-header/tick/flush-phase.js

@@ -5,9 +5,13 @@ export function emitTickFlushPhase() {
     return `
   }
   // ── Framebuffer bulk push ────────────────────────────────────────────────
-  // When a framebuffer was used this frame, flush it to the display in a single
-  // SPI transaction and restore the direct-draw target. No-op without one.
-  if (__ui_fb) {
+  // When a framebuffer was used this frame, publish only its changed bounds.
+  // Local touch updates therefore avoid a full-screen SPI burst (which appears
+  // as a brightness dip on panels without a synchronized frame latch).
+  // Repairs performed before the dirty-node pass (for example transform
+  // geometry cleanup) may update the retained buffer without leaving a node
+  // dirty. The dirty-bounds accumulator is the authoritative publish signal.
+  if (__ui_fb && (__ui_fb_frame_dirty || __ui_fb_dirty)) {
     ui_push_framebuffer();
   }
   ui_display_use_default_target();

package/dist/ui-engine/runtime-header/tick/scroll-canvas-phase.js

@@ -9,7 +9,23 @@ export function emitTickScrollCanvasPhase() {
     ui_push_buffered_scroll_canvas(bufferedScrollCanvas, bufferedScrollRepaintCanvas,
       bufferedScrollNode, bufferedScrollVX, bufferedScrollVY,
       bufferedScrollRepaintY, bufferedScrollRepaintH, __ui_draw_target);
-  } else if (bufferedScrollNode >= 0 && bufferedScrollDirectStrip) {
-    ui_draw_scrollbar_direct(bufferedScrollNode, bufferedScrollVX, bufferedScrollVY);
-    __ui_nodes[bufferedScrollNode].lastPaintedScrollY = __ui_nodes[bufferedScrollNode].scrollY;`;
+  } else if (bufferedScrollNode >= 0 && bufferedScrollBands) {
+    // Band render fallback: the main loop didn't trigger it at the owner's
+    // z-slot (e.g. the owner was filtered out after dispatch). Render now so
+    // the subtree is never left unpainted. ui_render_scroll_bands sets
+    // lastPaintedScrollY itself on success; only the failure fallback (band
+    // canvas wouldn't allocate) needs to record the scrollY here so the next
+    // frame's delta is correct.
+    if (!ui_render_scroll_bands(static_cast<uint16_t>(bufferedScrollNode))) {
+      // No band canvas means there is no coherent frame to submit. Retain the
+      // previous viewport rather than drawing the scrollbar/direct subtree to
+      // the live SPI target, which would reintroduce tearing.
+      if (__ui_scroll_render_locked) __ui_scroll_render_locked[static_cast<uint16_t>(bufferedScrollNode)] = 1;
+      __ui_nodes[bufferedScrollNode].dirty = 0;
+    }
+  } else if (bufferedScrollNode >= 0 && bufferedScrollDirectFull) {
+    // The direct-full path is intentionally disabled for tear-sensitive scroll
+    // rendering. Keep the retained pixels when no compositor is available.
+    if (__ui_scroll_render_locked) __ui_scroll_render_locked[static_cast<uint16_t>(bufferedScrollNode)] = 1;
+    __ui_nodes[bufferedScrollNode].dirty = 0;`;
 }

package/dist/ui-engine/runtime-header/tick/transitions-phase.js

@@ -10,9 +10,10 @@ export function emitTickTransitionsPhase() {
     __ui_trans[i].elapsed += deltaMs;
     uint16_t k = __ui_trans[i].durationMs == 0
       ? 100
-      : (uint16_t)((uint32_t)__ui_trans[i].elapsed * 100 / __ui_trans[i].durationMs);
+      : static_cast<uint16_t>(static_cast<uint32_t>(__ui_trans[i].elapsed > __ui_trans[i].durationMs
+          ? __ui_trans[i].durationMs : __ui_trans[i].elapsed) * 100 / __ui_trans[i].durationMs);
     if (__ui_trans[i].durationMs > 0 && __ui_trans[i].durationMs <= UI_TRANSITION_SNAP_MS) k = 100;
-    uint32_t v = UI_LERP_COLOR(__ui_trans[i].prevValue, __ui_trans[i].targetValue, (uint8_t)k);
+    uint32_t v = UI_LERP_COLOR(__ui_trans[i].prevValue, __ui_trans[i].targetValue, static_cast<uint8_t>(k));
     if (__ui_trans[i].prop == PROP_FG) {
       __ui_nodes[__ui_trans[i].node].fg = v;
     } else {
@@ -44,14 +45,20 @@ export function emitTickTransitionsPhase() {
         ui_keyframe_set_has_scroll_sensitive_geometry(__ui_anims[i].keyframeSet)) {
       continue;
     }
-    __ui_anims[i].elapsed += (uint32_t)deltaMs;
+    __ui_anims[i].elapsed += static_cast<uint32_t>(deltaMs);
     uint32_t elapsedNoDelay = __ui_anims[i].elapsed;
     if (elapsedNoDelay < __ui_anims[i].delayMs) continue;
     elapsedNoDelay -= __ui_anims[i].delayMs;
     // Check iteration limit (finite).
     uint8_t completing = 0;
     if (__ui_anims[i].iterations > 0) {
-      uint32_t totalDuration = (uint32_t)__ui_anims[i].iterations * (uint32_t)__ui_anims[i].durationMs;
+      // Saturate the multiplication so a long duration × iteration count
+      // cannot wrap and complete immediately after ~49 days of uptime.
+      uint32_t totalDuration = static_cast<uint32_t>(__ui_anims[i].iterations) * static_cast<uint32_t>(__ui_anims[i].durationMs);
+      if (__ui_anims[i].durationMs != 0 &&
+          static_cast<uint32_t>(__ui_anims[i].iterations) > 0xFFFFFFFFUL / static_cast<uint32_t>(__ui_anims[i].durationMs)) {
+        totalDuration = 0xFFFFFFFFUL;
+      }
       if (elapsedNoDelay >= totalDuration) {
         elapsedNoDelay = totalDuration;
         completing = 1;
@@ -61,7 +68,7 @@ export function emitTickTransitionsPhase() {
     uint8_t pct = 100;
     if (!completing && __ui_anims[i].durationMs > 0) {
       uint32_t cycleMs = elapsedNoDelay % __ui_anims[i].durationMs;
-      pct = (uint8_t)((uint32_t)cycleMs * 100 / __ui_anims[i].durationMs);
+      pct = static_cast<uint8_t>(static_cast<uint32_t>(cycleMs) * 100 / __ui_anims[i].durationMs);
     }
     // Find surrounding keyframe stops.
     if (__ui_anims[i].keyframeSet >= __ui_keyframe_set_count) continue;
@@ -77,7 +84,7 @@ export function emitTickTransitionsPhase() {
     const UIKeyframeStop* sHi = &ks->stops[hi];
     // Lerp factor between lo and hi.
     uint8_t range = sHi->percent - sLo->percent;
-    uint8_t lerpK = range > 0 ? (uint8_t)((uint16_t)(pct - sLo->percent) * 100 / range) : 0;
+    uint8_t lerpK = range > 0 ? static_cast<uint8_t>(static_cast<uint16_t>(pct - sLo->percent) * 100 / range) : 0;
     // Shape the lerp by the animation's timing function (ease-in-out, etc.).
     // CSS attaches it to the animation and applies it between stops.
     lerpK = ui_ease_lerp_k(__ui_anims[i].timingFunction, lerpK);
@@ -95,7 +102,7 @@ export function emitTickTransitionsPhase() {
     }
     if ((sLo->props & UI_KF_OPACITY) && (sHi->props & UI_KF_OPACITY)) {
       uint8_t newOp = range > 0
-        ? (uint8_t)((int16_t)sLo->opacity + ((int16_t)sHi->opacity - (int16_t)sLo->opacity) * lerpK / 100)
+        ? static_cast<uint8_t>(static_cast<int16_t>(sLo->opacity) + (static_cast<int16_t>(sHi->opacity) - static_cast<int16_t>(sLo->opacity)) * lerpK / 100)
         : sLo->opacity;
       if (newOp != __ui_nodes[n].opacity) { __ui_nodes[n].opacity = newOp; changed = 1; }
     }
@@ -108,10 +115,10 @@ export function emitTickTransitionsPhase() {
     uint8_t hasSizeFrame = (sLo->props & UI_KF_SIZE) && (sHi->props & UI_KF_SIZE);
     if (hasSizeFrame) {
       nextWidth = range > 0
-        ? (int16_t)((int32_t)sLo->width + ((int32_t)sHi->width - (int32_t)sLo->width) * lerpK / 100)
+        ? static_cast<int16_t>(static_cast<int32_t>(sLo->width) + (static_cast<int32_t>(sHi->width) - static_cast<int32_t>(sLo->width)) * lerpK / 100)
         : sLo->width;
       nextHeight = range > 0
-        ? (int16_t)((int32_t)sLo->height + ((int32_t)sHi->height - (int32_t)sLo->height) * lerpK / 100)
+        ? static_cast<int16_t>(static_cast<int32_t>(sLo->height) + (static_cast<int32_t>(sHi->height) - static_cast<int32_t>(sLo->height)) * lerpK / 100)
         : sLo->height;
       if (nextWidth < 0) nextWidth = 0;
       if (nextHeight < 0) nextHeight = 0;
@@ -122,25 +129,25 @@ export function emitTickTransitionsPhase() {
     }
     if ((sLo->props & UI_KF_TRANSFORM) && (sHi->props & UI_KF_TRANSFORM)) {
       int16_t pxX = range > 0
-        ? (int16_t)((int32_t)sLo->transformOffsetX + ((int32_t)sHi->transformOffsetX - (int32_t)sLo->transformOffsetX) * lerpK / 100)
+        ? static_cast<int16_t>(static_cast<int32_t>(sLo->transformOffsetX) + (static_cast<int32_t>(sHi->transformOffsetX) - static_cast<int32_t>(sLo->transformOffsetX)) * lerpK / 100)
         : sLo->transformOffsetX;
       int16_t pxY = range > 0
-        ? (int16_t)((int32_t)sLo->transformOffsetY + ((int32_t)sHi->transformOffsetY - (int32_t)sLo->transformOffsetY) * lerpK / 100)
+        ? static_cast<int16_t>(static_cast<int32_t>(sLo->transformOffsetY) + (static_cast<int32_t>(sHi->transformOffsetY) - static_cast<int32_t>(sLo->transformOffsetY)) * lerpK / 100)
         : sLo->transformOffsetY;
       int16_t pctX = range > 0
-        ? (int16_t)((int32_t)sLo->translatePctX + ((int32_t)sHi->translatePctX - (int32_t)sLo->translatePctX) * lerpK / 100)
+        ? static_cast<int16_t>(static_cast<int32_t>(sLo->translatePctX) + (static_cast<int32_t>(sHi->translatePctX) - static_cast<int32_t>(sLo->translatePctX)) * lerpK / 100)
         : sLo->translatePctX;
       int16_t pctY = range > 0
-        ? (int16_t)((int32_t)sLo->translatePctY + ((int32_t)sHi->translatePctY - (int32_t)sLo->translatePctY) * lerpK / 100)
+        ? static_cast<int16_t>(static_cast<int32_t>(sLo->translatePctY) + (static_cast<int32_t>(sHi->translatePctY) - static_cast<int32_t>(sLo->translatePctY)) * lerpK / 100)
         : sLo->translatePctY;
       int16_t scaleX = range > 0
-        ? (int16_t)((int32_t)sLo->scaleX + ((int32_t)sHi->scaleX - (int32_t)sLo->scaleX) * lerpK / 100)
+        ? static_cast<int16_t>(static_cast<int32_t>(sLo->scaleX) + (static_cast<int32_t>(sHi->scaleX) - static_cast<int32_t>(sLo->scaleX)) * lerpK / 100)
         : sLo->scaleX;
       int16_t scaleY = range > 0
-        ? (int16_t)((int32_t)sLo->scaleY + ((int32_t)sHi->scaleY - (int32_t)sLo->scaleY) * lerpK / 100)
+        ? static_cast<int16_t>(static_cast<int32_t>(sLo->scaleY) + (static_cast<int32_t>(sHi->scaleY) - static_cast<int32_t>(sLo->scaleY)) * lerpK / 100)
         : sLo->scaleY;
       nextRotateDeg = range > 0
-        ? (int16_t)((int32_t)sLo->rotateDeg + ((int32_t)sHi->rotateDeg - (int32_t)sLo->rotateDeg) * lerpK / 100)
+        ? static_cast<int16_t>(static_cast<int32_t>(sLo->rotateDeg) + (static_cast<int32_t>(sHi->rotateDeg) - static_cast<int32_t>(sLo->rotateDeg)) * lerpK / 100)
         : sLo->rotateDeg;
       if (scaleX < 0) scaleX = 0;
       if (scaleY < 0) scaleY = 0;
@@ -148,14 +155,14 @@ export function emitTickTransitionsPhase() {
       int16_t refH = hasSizeFrame ? nextHeight : __ui_anims[i].baseHeight;
       if (refW <= 0) refW = __ui_nodes[n].box.w;
       if (refH <= 0) refH = __ui_nodes[n].box.h;
-      int16_t originPxX = (int16_t)((int32_t)refW * __ui_anims[i].originX / 100);
-      int16_t originPxY = (int16_t)((int32_t)refH * __ui_anims[i].originY / 100);
-      int16_t scaledW = (int16_t)((int32_t)refW * scaleX / 100);
-      int16_t scaledH = (int16_t)((int32_t)refH * scaleY / 100);
-      int16_t scaleOffsetX = originPxX - (int16_t)((int32_t)originPxX * scaleX / 100);
-      int16_t scaleOffsetY = originPxY - (int16_t)((int32_t)originPxY * scaleY / 100);
-      nextTransformX = pxX + (int16_t)((int32_t)refW * pctX / 100) + scaleOffsetX;
-      nextTransformY = pxY + (int16_t)((int32_t)refH * pctY / 100) + scaleOffsetY;
+      int16_t originPxX = static_cast<int16_t>(static_cast<int32_t>(refW) * __ui_anims[i].originX / 100);
+      int16_t originPxY = static_cast<int16_t>(static_cast<int32_t>(refH) * __ui_anims[i].originY / 100);
+      int16_t scaledW = static_cast<int16_t>(static_cast<int32_t>(refW) * scaleX / 100);
+      int16_t scaledH = static_cast<int16_t>(static_cast<int32_t>(refH) * scaleY / 100);
+      int16_t scaleOffsetX = originPxX - static_cast<int16_t>(static_cast<int32_t>(originPxX) * scaleX / 100);
+      int16_t scaleOffsetY = originPxY - static_cast<int16_t>(static_cast<int32_t>(originPxY) * scaleY / 100);
+      nextTransformX = pxX + static_cast<int16_t>(static_cast<int32_t>(refW) * pctX / 100) + scaleOffsetX;
+      nextTransformY = pxY + static_cast<int16_t>(static_cast<int32_t>(refH) * pctY / 100) + scaleOffsetY;
       nextWidth = scaledW < 0 ? 0 : scaledW;
       nextHeight = scaledH < 0 ? 0 : scaledH;
       if (nextTransformX != __ui_nodes[n].transformOffsetX ||

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

@@ -51,6 +51,7 @@ 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
+// (__ui_kb_canvas is declared in forward-decls.ts alongside the other persistent canvases.)
 // 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;
@@ -91,15 +92,15 @@ static int16_t ui_hit_test(int16_t tx, int16_t ty) {
   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);
+    int16_t drawX = ui_draw_x_for_node(static_cast<uint16_t>(i));
+    int16_t drawY = ui_draw_y_for_node(static_cast<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;
+      if (ui_is_point_clipped_by_scroll(static_cast<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
@@ -120,7 +121,7 @@ static int16_t ui_hit_test(int16_t tx, int16_t ty) {
 
 // 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]) {
+  if (node >= 0 && static_cast<uint16_t>(node) < count && table[node]) {
     table[node]();
   }
 }
@@ -164,28 +165,13 @@ static void ui_touch_down(int16_t tx, int16_t ty) {
   // 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;
+  __ui_scroll_node = ui_scroll_node_at(tx, ty);
 #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;
+      ui_set_pressed(static_cast<uint16_t>(node), 1);
     }
     // Track range nodes for horizontal drag
     if (__ui_nodes[node].kind == NODE_RANGE) {
@@ -198,20 +184,22 @@ static void ui_touch_down(int16_t tx, int16_t ty) {
       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 relX = tx - ui_draw_x_for_node(static_cast<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;
+      int16_t nextVal = rMin + (static_cast<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);
+    // Only controls with a visual state change need a dirty repaint on touch-down:
+    // buttons were marked by ui_set_pressed() above and ranges were marked when
+    // their value changed. Links, inputs, checks, radios, selects, and list
+    // containers do not have a pressed state; repainting them here is redundant
+    // and can expose a clear/redraw flash on direct SPI targets. They repaint
+    // after the click/value change (or when scrolling actually begins).
   }
 }
 
@@ -240,21 +228,29 @@ static void ui_touch_up() {
     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_open_keyboard_for_input(static_cast<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);
+        int16_t ndx = __ui_last_touch_x - ui_draw_x_for_node(static_cast<uint16_t>(clickedNode));
+        int16_t ndy = __ui_last_touch_y - ui_draw_y_for_node(static_cast<uint16_t>(clickedNode));
+        int8_t target = ui_rich_link_hit(static_cast<uint16_t>(clickedNode), ndx, ndy);
+        if (target >= 0) ui_navigate(static_cast<uint8_t>(target));
       }
     }
     ui_dispatch(__ui_release_handlers, __ui_click_handler_count, __ui_touch_node);
-    ui_mark_dirty(clickedNode);
+    // Built-in check/radio/select handlers mutate the node value during click
+    // dispatch and need one repaint. Buttons are already dirty from releasing
+    // :pressed; links, lists, inputs, and ordinary callbacks are either handled
+    // by navigation/keyboard state or observed by bindings on the next tick.
+    if (__ui_nodes[clickedNode].kind == NODE_CHECK ||
+        __ui_nodes[clickedNode].kind == NODE_RADIO ||
+        __ui_nodes[clickedNode].kind == NODE_SELECT) {
+      ui_mark_dirty(static_cast<uint16_t>(clickedNode));
+    }
   }
   // Release the pressed button's :pressed state unconditionally — even when a
   // drag/scroll hijacked the gesture (the click above is correctly gated on
@@ -262,13 +258,15 @@ static void ui_touch_up() {
   // 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);
+    ui_set_pressed(static_cast<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++;
+  // Note: explicit '+ 1' instead of '++' — GCC 13+ (IDF v6) deprecates '++'
+  // on volatile-qualified types under -Werror=volatile.
+  __ui_tap_seq = __ui_tap_seq + 1;
   __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
@@ -280,9 +278,9 @@ static void ui_touch_up() {
       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) &&
+      if (totalMove < static_cast<int16_t>(ih / 2) &&
           relY >= 0 && relY < __ui_nodes[n].box.h) {
-        uint16_t itemIdx = (uint16_t)((relY + __ui_nodes[n].scrollY) / ih);
+        uint16_t itemIdx = static_cast<uint16_t>((relY + __ui_nodes[n].scrollY) / ih);
         if (itemIdx < __ui_nodes[n].listCount) {
           __ui_nodes[n].listTapFn(itemIdx);
         }
@@ -346,16 +344,16 @@ static inline void ui_handle_touch(int16_t tx, int16_t ty) {
       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 relX = tx - ui_draw_x_for_node(static_cast<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;
+      int16_t newVal = rMin + (static_cast<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 &&
+        if (__ui_range_node < static_cast<int16_t>(__ui_rangechange_handler_count) &&
             __ui_rangechange_handlers[__ui_range_node]) {
           __ui_rangechange_handlers[__ui_range_node]();
         }
@@ -373,10 +371,17 @@ static inline void ui_handle_touch(int16_t tx, int16_t ty) {
           ui_apply_scroll_delta(__ui_scroll_node, dy);
           __ui_drag_start_y = ty;
 #if UI_SCROLL_DEBUG
+#if defined(ESP32) && defined(ARDUINO)
           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);
+            static_cast<int>(__ui_nodes[__ui_scroll_node].virtualized));
+#else
+          printk("scroll dy=%d sy=%d ov=%d virt=%d\\n",
+            dy, __ui_nodes[__ui_scroll_node].scrollY,
+            __ui_nodes[__ui_scroll_node].overscrollPx,
+            static_cast<int>(__ui_nodes[__ui_scroll_node].virtualized));
+#endif
 #endif
         }
       }

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

@@ -7,7 +7,8 @@ export function emitTypesDefines() {
 #ifndef __TC_UI_RUNTIME
 #define __TC_UI_RUNTIME
 #include <stdint.h>
-#include <string.h>
+#include <cstring>
+#include <new>
 #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
@@ -17,6 +18,17 @@ export function emitTypesDefines() {
 #ifndef UI_MAX_BUFFERED_PAINT_PIXELS
 #define UI_MAX_BUFFERED_PAINT_PIXELS 20000
 #endif
+// Above this many pixels, prefer the band renderer (small ~10KB SRAM canvas,
+// strip-at-a-time) over the repair canvas even when the repair canvas could
+// allocate (e.g. in PSRAM). A large repair canvas (a full-width button is
+// ~15-30KB) has higher alloc/seed/push latency than banding — the per-band
+// push is smaller and the band canvas lives in fast internal SRAM. Set below
+// UI_MAX_BUFFERED_PAINT_PIXELS so large rects band while small repaints keep
+// the fast single-canvas composite. Tune per target; 0 = always prefer the
+// repair canvas when it allocates (the pre-PSRAM behavior).
+#ifndef UI_BAND_PREFER_PIXELS
+#define UI_BAND_PREFER_PIXELS 8000
+#endif
 #ifndef UI_USE_FULL_FRAMEBUFFER
 #define UI_USE_FULL_FRAMEBUFFER 0
 #endif
@@ -69,8 +81,16 @@ export function emitTypesDefines() {
 #ifndef UI_SCROLL_DEBUG
 #define UI_SCROLL_DEBUG 0
 #endif
-#ifndef UI_SCROLL_CANVAS_BUDGET_BYTES
-#define UI_SCROLL_CANVAS_BUDGET_BYTES 88000
+// Band renderer: height (px) of the horizontal band canvas used to composite
+// scroll subtrees tear-free when no viewport canvas fits (no PSRAM / over
+// budget). Each band is vw × UI_STRIP_BAND_HEIGHT. Must be tall enough that a
+// single line of AA text (glyph height ~lineHeight, typically 16-22px at ts=2)
+// fits within one band — if a glyph straddles a band boundary, its anti-
+// aliased edge pixels blend toward the wrong bg in the adjacent band, visible
+// as a clipped/faded text bottom. 32 ensures most fonts fit; at 480px wide
+// that's ~30KB (fits SRAM on most ESP32 targets).
+#ifndef UI_STRIP_BAND_HEIGHT
+#define UI_STRIP_BAND_HEIGHT 32
 #endif
 #if defined(ESP32) || defined(ESP8266)
 #include <Esp.h>

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

@@ -1 +1,10 @@
-export declare function emitRuntimeHeader(): string;
+export interface EmitRuntimeHeaderOptions {
+    /**
+     * True when a native display adapter (AVR, ESP32) is in use. Kept for
+     * backwards compatibility — the CuttlefishGFX slice is now emitted
+     * separately via emitCuttlefishGfx() so it can land BEFORE display adapter
+     * declarations that instantiate CuttlefishGFX by value.
+     */
+    nativeDisplayActive?: boolean;
+}
+export declare function emitRuntimeHeader(opts?: EmitRuntimeHeaderOptions): string;

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

@@ -35,12 +35,17 @@ 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 { emitNodeDrawBody } from "./runtime-header/node-draw-body.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() {
+export function emitRuntimeHeader(opts) {
+    // Note: the CuttlefishGFX slice (emitCuttlefishGfx) is emitted separately
+    // by ui-emitter.ts BEFORE the display adapter declaration. It is NOT
+    // emitted here — passing nativeDisplayActive has no effect.
+    void opts;
     return [
         emitTypesDefines(),
         emitStructs(),
@@ -60,6 +65,7 @@ export function emitRuntimeHeader() {
         emitBlendBodies(),
         emitTextRendering(),
         emitNodeDecoration(),
+        emitNodeDrawBody(),
         emitTickMotionHelpers(),
         emitTick(),
         emitAntialiasing(),

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

@@ -13,7 +13,7 @@ import { parseHtml } from "./html-parser.js";
 import { parseCss, parseFontFaces, parseKeyframes } from "./css-parser.js";
 import { resolveStyles } from "./style-resolver.js";
 import { selectEngine } from "./select-engine.js";
-import { measure } from "./layout-engine.js";
+import { measureWithFonts } from "./layout-engine.js";
 import { lowerUIToCpp } from "./ui-lowering.js";
 import { buildUIFontAssets } from "./font-assets.js";
 import { buildKeyframeSets } from "./keyframes.js";
@@ -27,7 +27,7 @@ export function transpileUI(html, css, opts) {
     // Select layout engine: Yoga for flexbox, BlockLayout as fallback.
     const engine = selectEngine(styled);
     const viewport = { x: 0, y: 0, w: opts.viewport.width, h: opts.viewport.height };
-    const boxes = engine.arrange(styled, viewport, measure);
+    const boxes = engine.arrange(styled, viewport, measureWithFonts(fontAssets));
     const keyframeSets = buildKeyframeSets(rawKeyframes, opts.colorFormat);
     return lowerUIToCpp(styled, boxes, opts.colorFormat, opts.storage, [], rules, undefined, fontAssets, [], new Map(), keyframeSets);
 }

package/dist/ui-engine/ua-stylesheet.js

@@ -6,9 +6,15 @@
 // ---------------------------------------------------------------------------
 import { parseCss } from "./css-parser.js";
 const UA_CSS = `
+/* Browser-like light defaults: dark text on a near-white background.
+   A dark theme overrides these via user CSS (e.g. screen { color: #f0f0f0;
+   background: #1a1a1a }). Without these, screen fg defaults to white
+   (0xFFFF at the model level), making text invisible on light backgrounds. */
 screen {
   display: flex;
   flex-direction: column;
+  color: #1a1a1a;
+  background: #ffffff;
 }
 body {
   display: flex;
@@ -20,14 +26,41 @@ view {
   display: flex;
   flex-direction: column;
 }
+/* Scrollable content area — the standard pattern for multi-screen apps.
+   align-items:center + gap give readable card-style layouts out of the box. */
+.scrollBody {
+  overflow: scroll;
+  flex: 1;
+  align-items: center;
+  gap: 10px;
+}
+/* Header bar (back link + title). flex-direction:row is the expected layout;
+   without it the back link and title stack vertically. */
+.screenHeader {
+  flex-direction: row;
+  align-items: center;
+  gap: 8px;
+}
 button {
-  padding: 4px 10px;
+  padding: 10px 16px;
   border: 1px solid;
+  min-height: 48px;
   text-align: center;
 }
 input {
-  padding: 4px 8px;
+  padding: 8px;
+  border: 1px solid;
+}
+select {
+  padding: 10px 12px;
   border: 1px solid;
+  min-height: 48px;
+}
+check, radio {
+  min-height: 48px;
+}
+range {
+  height: 40px;
 }
 list {
   overflow: scroll;
@@ -39,13 +72,23 @@ a {
 label {
   text-align: left;
 }
+/* h3 is non-bold by default: the runtime bumps textSize for bold text
+   (roughly doubling per-char advance), which wraps multi-word captions
+   like "width / height / min / max" to 3 lines. Normal weight keeps
+   them readable. Users can override with font-weight:bold if needed. */
 h1 { font-size: 24px; font-weight: bold; }
 h2 { font-size: 20px; font-weight: bold; }
-h3 { font-size: 18px; font-weight: bold; }
+h3 { font-size: 18px; font-weight: normal; }
 h4 { font-size: 16px; font-weight: bold; }
 h5 { font-size: 14px; }
 h6 { font-size: 12px; }
 p { font-size: 16px; }
+/* Keyboard structural defaults (the OSK is runtime-generated, not
+   user-authored HTML). Border keeps keys visually separated. Colors
+   are design choices left to user CSS. */
+.ui-key {
+  border: 1px solid;
+}
 `;
 let UA_RULES = null;
 /** Get the parsed UA default rules. Lazily computed, cached. */

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

@@ -21,13 +21,11 @@ export interface LoweredUI {
     imageTables: string;
     /** C++ keyframe data arrays + animation table. */
     keyframeTables: string;
-    /** Compile-time warnings for scroll viewports that exceed the canvas budget. */
-    scrollMemoryDiagnostics: Diagnostic[];
     /** Layout-time diagnostics (viewport overflow, text overflow). Populated by
      *  lowerOnMount after the boxes are computed; empty until then. */
     diagnostics: Diagnostic[];
 }
 type ColorFormat = "rgb565" | "rgb666" | "rgb888" | "mono";
 type Storage = "progmem" | "flash";
-export declare function lowerUIToCpp(root: StyledNode, boxes: Box[], colorFormat: ColorFormat, storage: Storage, keyboards?: KeyboardTemplate[], rules?: CSSRule[], display?: DisplayProfile, fontAssets?: UIFontAssetModel[], allScreens?: StyledNode[], imageAssetIds?: Map<string, number>, keyframeSets?: KeyframeSetModel[], scrollCanvasBudgetBytes?: number): LoweredUI;
+export declare function lowerUIToCpp(root: StyledNode, boxes: Box[], colorFormat: ColorFormat, storage: Storage, keyboards?: KeyboardTemplate[], rules?: CSSRule[], display?: DisplayProfile, fontAssets?: UIFontAssetModel[], allScreens?: StyledNode[], imageAssetIds?: Map<string, number>, keyframeSets?: KeyframeSetModel[]): LoweredUI;
 export {};