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

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

@@ -12,10 +12,18 @@ export function emitAntialiasing(): string {
 // then pushed to the display. The ILI9341 has no efficient SPI read-back, so
 // all blending happens in RAM.
 #ifdef UI_AA
+#include <math.h>  // fabs, floor, ceil, sqrtf for AA coverage math
+
+// AA is only useful on RAM-backed targets. Direct SPI targets have no safe
+// read/modify/write surface for coverage blending; callers still get the
+// regular primitive path instead of an allocation plus many tiny pushes.
+static inline uint8_t ui_aa_target_is_ram() {
+  return !ui_display_is_default_target();
+}
 
 // Get (or allocate) a canvas sized to the element being drawn.
 static inline CuttlefishCanvas16* ui_aa_begin(int16_t w, int16_t h, UI_COLOR_T bg) {
-  if (w <= 0 || h <= 0) return nullptr;
+  if (w <= 0 || h <= 0 || !ui_aa_target_is_ram()) return nullptr;
   if (!__ui_aa_canvas || display_canvasWidth(__ui_aa_canvas) < w || display_canvasHeight(__ui_aa_canvas) < h) {
     display_deleteCanvas(__ui_aa_canvas);
     __ui_aa_canvas = display_createCanvas(w > 0 ? w : 1, h > 0 ? h : 1);
@@ -33,7 +41,7 @@ static inline void ui_aa_push(CuttlefishCanvas16* c, int16_t dx, int16_t dy) {
   // or the display directly when not. Row-by-row drawRGBBitmap (no transparent
   // alpha — the AA canvas already has the blended pixels).
   for (int16_t row = 0; row < h; row++) {
-    ui_display_draw_rgb_bitmap(dx, dy + row, display_canvasBuffer(c) + (int32_t)row * w, w, 1);
+    ui_display_draw_rgb_bitmap(dx, dy + row, display_canvasBuffer(c) + static_cast<int32_t>(row) * w, w, 1);
   }
 }
 
@@ -44,16 +52,16 @@ static inline void ui_aa_pixel(CuttlefishCanvas16* c, int16_t x, int16_t y, UI_C
   if (x < 0 || y < 0 || x >= display_canvasWidth(c) || y >= display_canvasHeight(c)) return;
   if (cov >= 255) { display_targetDrawPixel((CuttlefishDisplayTarget*)c, x, y, color); return; }
   UI_COLOR_T bg = display_canvasGetPixel(c, x, y);
-  uint8_t op = (uint8_t)((uint16_t)cov * 100 / 255);
+  uint8_t op = static_cast<uint8_t>(static_cast<uint16_t>(cov) * 100 / 255);
   display_targetDrawPixel((CuttlefishDisplayTarget*)c, x, y, ui_blend(color, bg, op));
 }
 
 // Xiaolin Wu antialiased line. Coordinates are in canvas-local space.
 static inline void ui_aa_line(CuttlefishCanvas16* c, float x0, float y0, float x1, float y1, UI_COLOR_T color) {
   if (!c || !display_canvasBuffer(c)) return;
-  auto ipart = [](float f) { return (int16_t)f; };
-  auto round_f = [](float f) { return (int16_t)(f + 0.5f); };
-  auto fpart = [](float f) { return f - (float)(int16_t)f; };
+  auto ipart = [](float f) { return static_cast<int16_t>(f); };
+  auto round_f = [](float f) { return static_cast<int16_t>(f + 0.5f); };
+  auto fpart = [](float f) { return f - static_cast<float>(static_cast<int16_t>(f)); };
   auto rfpart = [&](float f) { return 1.0f - fpart(f); };
 
   bool steep = fabs(y1 - y0) > fabs(x1 - x0);
@@ -63,17 +71,29 @@ static inline void ui_aa_line(CuttlefishCanvas16* c, float x0, float y0, float x
   float dx = x1 - x0, dy = y1 - y0;
   float gradient = (dx == 0) ? 1.0f : dy / dx;
 
-  int16_t xpx1 = round_f(x0);
-  float xend = x0 + 0.5f * (xpx1 - x0) * (xpx1 - x0 < 0 ? -1 : 0); // simplified
-  float intery = y0 + gradient * (xpx1 - x0);
+  // Handle first endpoint.
+  float xend = static_cast<float>(round_f(x0));
+  float yend = y0 + gradient * (xend - x0);
+  float xgap = rfpart(x0);
+  int16_t xpx1 = static_cast<int16_t>(xend);
+  int16_t ypx1 = ipart(yend);
+  if (steep) {
+    ui_aa_pixel(c, ypx1, xpx1, color, static_cast<uint8_t>(rfpart(yend) * xgap * 255));
+    ui_aa_pixel(c, ypx1 + 1, xpx1, color, static_cast<uint8_t>(fpart(yend) * xgap * 255));
+  } else {
+    ui_aa_pixel(c, xpx1, ypx1, color, static_cast<uint8_t>(rfpart(yend) * xgap * 255));
+    ui_aa_pixel(c, xpx1, ypx1 + 1, color, static_cast<uint8_t>(fpart(yend) * xgap * 255));
+  }
+  float intery = yend + gradient;
 
-  for (int16_t x = xpx1; x <= ipart(x1); x++) {
+  // Main loop.
+  for (int16_t x = xpx1 + 1; x <= static_cast<int16_t>(round_f(x1)) - 1; x++) {
     if (steep) {
-      ui_aa_pixel(c, ipart(intery), x, color, (uint8_t)(rfpart(intery) * 255));
-      ui_aa_pixel(c, ipart(intery) + 1, x, color, (uint8_t)(fpart(intery) * 255));
+      ui_aa_pixel(c, ipart(intery), x, color, static_cast<uint8_t>(rfpart(intery) * 255));
+      ui_aa_pixel(c, ipart(intery) + 1, x, color, static_cast<uint8_t>(fpart(intery) * 255));
     } else {
-      ui_aa_pixel(c, x, ipart(intery), color, (uint8_t)(rfpart(intery) * 255));
-      ui_aa_pixel(c, x, ipart(intery) + 1, color, (uint8_t)(fpart(intery) * 255));
+      ui_aa_pixel(c, x, ipart(intery), color, static_cast<uint8_t>(rfpart(intery) * 255));
+      ui_aa_pixel(c, x, ipart(intery) + 1, color, static_cast<uint8_t>(fpart(intery) * 255));
     }
     intery += gradient;
   }
@@ -84,24 +104,24 @@ static inline void ui_aa_circle(CuttlefishCanvas16* c, int16_t cx, int16_t cy, f
   if (!c || !display_canvasBuffer(c)) return;
   if (r <= 0) return;
   // Walk each scanline from top to bottom of the bounding box.
-  int16_t y0 = (int16_t)floor(cy - r);
-  int16_t y1 = (int16_t)ceil(cy + r);
+  int16_t y0 = static_cast<int16_t>(floor(cy - r));
+  int16_t y1 = static_cast<int16_t>(ceil(cy + r));
   for (int16_t y = y0; y <= y1; y++) {
-    float dy = (float)y - cy;
+    float dy = static_cast<float>(y) - cy;
     float dx = r * r - dy * dy;
     if (dx < 0) continue;
     float halfW = sqrtf(dx);
-    float leftX = (float)cx - halfW;
-    float rightX = (float)cx + halfW;
+    float leftX = static_cast<float>(cx) - halfW;
+    float rightX = static_cast<float>(cx) + halfW;
     // Left edge: blend two pixels at the coverage split.
-    int16_t lx = (int16_t)floor(leftX);
+    int16_t lx = static_cast<int16_t>(floor(leftX));
     float lfrac = leftX - lx;
-    ui_aa_pixel(c, lx, y, color, (uint8_t)((1.0f - lfrac) * 255));
+    ui_aa_pixel(c, lx, y, color, static_cast<uint8_t>((1.0f - lfrac) * 255));
     ui_aa_pixel(c, lx + 1, y, color, 0);  // interior starts here (drawn solid below)
     // Right edge.
-    int16_t rx = (int16_t)floor(rightX);
+    int16_t rx = static_cast<int16_t>(floor(rightX));
     float rfrac = rightX - rx;
-    ui_aa_pixel(c, rx, y, color, (uint8_t)(rfrac * 255));
+    ui_aa_pixel(c, rx, y, color, static_cast<uint8_t>(rfrac * 255));
     ui_aa_pixel(c, rx + 1, y, color, 0);
     // Solid fill between edges (skip the edge pixels already blended).
     for (int16_t x = lx + 1; x < rx; x++) {
@@ -114,21 +134,21 @@ static inline void ui_aa_circle(CuttlefishCanvas16* c, int16_t cx, int16_t cy, f
 static inline void ui_aa_fill_circle(CuttlefishCanvas16* c, int16_t cx, int16_t cy, float r, UI_COLOR_T color) {
   if (!c || !display_canvasBuffer(c)) return;
   if (r <= 0) return;
-  int16_t y0 = (int16_t)floor(cy - r);
-  int16_t y1 = (int16_t)ceil(cy + r);
+  int16_t y0 = static_cast<int16_t>(floor(cy - r));
+  int16_t y1 = static_cast<int16_t>(ceil(cy + r));
   for (int16_t y = y0; y <= y1; y++) {
-    float dy = (float)y - cy;
+    float dy = static_cast<float>(y) - cy;
     float dx = r * r - dy * dy;
     if (dx < 0) continue;
     float halfW = sqrtf(dx);
-    float leftX = (float)cx - halfW;
-    float rightX = (float)cx + halfW;
-    int16_t lx = (int16_t)floor(leftX);
-    int16_t rx = (int16_t)ceil(rightX);
+    float leftX = static_cast<float>(cx) - halfW;
+    float rightX = static_cast<float>(cx) + halfW;
+    int16_t lx = static_cast<int16_t>(floor(leftX));
+    int16_t rx = static_cast<int16_t>(ceil(rightX));
     // Blend left edge.
-    ui_aa_pixel(c, lx, y, color, (uint8_t)((1.0f - (leftX - lx)) * 255));
+    ui_aa_pixel(c, lx, y, color, static_cast<uint8_t>((1.0f - (leftX - lx)) * 255));
     // Blend right edge.
-    ui_aa_pixel(c, rx, y, color, (uint8_t)((rightX - (rx - 1)) * 255));
+    ui_aa_pixel(c, rx, y, color, static_cast<uint8_t>((rightX - (rx - 1)) * 255));
     // Solid interior.
     for (int16_t x = lx + 1; x < rx; x++) {
       if (x >= 0 && x < display_canvasWidth(c) && y >= 0 && y < display_canvasHeight(c)) display_targetDrawPixel((CuttlefishDisplayTarget*)c, x, y, color);

package/src/ui-engine/runtime-header/blend-bodies.ts

@@ -15,9 +15,9 @@ static inline uint16_t ui_blend565(uint16_t fg, uint16_t bg, uint8_t opacity) {
   // Unpack to 8-bit (5-bit → 8-bit: (v << 3) | (v >> 2)).
   uint16_t fr8 = (fr << 3) | (fr >> 2), fg8 = (fg5 << 2) | (fg5 >> 4), fb8 = (fb << 3) | (fb >> 2);
   uint16_t br8 = (br << 3) | (br >> 2), bg8 = (bg5 << 2) | (bg5 >> 4), bb8 = (bb << 3) | (bb >> 2);
-  uint16_t r = (uint16_t)((fr8 * opacity + br8 * (100 - opacity)) / 100);
-  uint16_t g = (uint16_t)((fg8 * opacity + bg8 * (100 - opacity)) / 100);
-  uint16_t b = (uint16_t)((fb8 * opacity + bb8 * (100 - opacity)) / 100);
+  uint16_t r = static_cast<uint16_t>((fr8 * opacity + br8 * (100 - opacity)) / 100);
+  uint16_t g = static_cast<uint16_t>((fg8 * opacity + bg8 * (100 - opacity)) / 100);
+  uint16_t b = static_cast<uint16_t>((fb8 * opacity + bb8 * (100 - opacity)) / 100);
   return ((r >> 3) << 11) | ((g >> 2) << 5) | (b >> 3);
 }
 
@@ -33,7 +33,7 @@ static inline uint32_t ui_blend888(uint32_t fg, uint32_t bg, uint8_t opacity) {
   uint8_t r = (fr * opacity + br * (100 - opacity)) / 100;
   uint8_t g = (fg8 * opacity + bg8 * (100 - opacity)) / 100;
   uint8_t b = (fb * opacity + bb * (100 - opacity)) / 100;
-  return ((uint32_t)r << 16) | ((uint32_t)g << 8) | b;
+  return (static_cast<uint32_t>(r) << 16) | (static_cast<uint32_t>(g) << 8) | b;
 }
 `;
 }

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

@@ -1,5 +1,5 @@
 // Slice of the C++ runtime header (original source lines 753-901).
-// Persistent canvas release/create/get/shift/repair/warn helpers.
+// Persistent canvas release/create/get/shift/repair helpers.
 // See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
 export function emitCanvasHelpers(): string {
   return `
@@ -10,6 +10,8 @@ static inline void ui_release_canvas_state() {
   __ui_list_canvas_node = -1;
   display_deleteCanvas(__ui_node_canvas);      __ui_node_canvas = nullptr;
   display_deleteCanvas(__ui_repair_canvas);    __ui_repair_canvas = nullptr;
+  display_deleteCanvas(__ui_band_canvas);      __ui_band_canvas = nullptr;
+  display_deleteCanvas(__ui_kb_canvas);        __ui_kb_canvas = nullptr;
 }
 
 // Lazily allocate/reuse a viewport-sized canvas for a scroll container. Resizes
@@ -22,7 +24,18 @@ static inline CuttlefishCanvas16* ui_create_canvas_best(int16_t w, int16_t h) {
 #if defined(ESP32) && defined(BOARD_HAS_PSRAM)
   if (psramFound()) {
     CuttlefishCanvas16* c = display_createCanvasPsram(w, h);
-    if (c && display_canvasBuffer(c)) return c;
+    if (c && display_canvasBuffer(c)) {
+      static uint8_t psram_logged = 0;
+      if (!psram_logged) {
+        psram_logged = 1;
+#if defined(ESP32) && defined(ARDUINO)
+        Serial.printf("[psram] canvas %dx%d allocated in PSRAM (free=%u)\n", w, h, ESP.getFreePsram());
+#else
+        printf("[psram] canvas %dx%d allocated in PSRAM\n", w, h);
+#endif
+      }
+      return c;
+    }
     // PSRAM allocation failed (rare — fragmented PSRAM) → fall through to SRAM.
   }
 #endif
@@ -30,63 +43,18 @@ static inline CuttlefishCanvas16* ui_create_canvas_best(int16_t w, int16_t h) {
 }
 
 static inline CuttlefishCanvas16* ui_get_container_canvas(int16_t w, int16_t h) {
-  if (w <= 0 || h <= 0) return nullptr;
-  if (!__ui_container_canvas ||
-      display_canvasWidth(__ui_container_canvas) != w ||
-      display_canvasHeight(__ui_container_canvas) != h) {
-    display_deleteCanvas(__ui_container_canvas);
-    __ui_container_canvas = ui_create_canvas_best(w, h);
-  }
-  return (__ui_container_canvas && display_canvasBuffer(__ui_container_canvas))
-    ? __ui_container_canvas : nullptr;
-}
-
-// Defined after the node table by UI lowering (scroll overflow nodes with ids).
-static inline const char* __ui_scroll_node_id(uint16_t idx);
-
-// Emit a one-time Serial warning when scroll rendering cannot be accurate due
-// to heap limits. reason: 0=canvas alloc failed, 1=viewport exceeds budget,
-// 2=Mode C strip fallback (reduced accuracy).
-static inline void ui_warn_scroll_memory(uint16_t nodeIdx, uint8_t reason) {
-  if (nodeIdx >= __ui_node_count) return;
-  if (!__ui_scroll_mem_warned) return;
-  if (__ui_scroll_mem_warned[nodeIdx]) return;
-  __ui_scroll_mem_warned[nodeIdx] = 1;
-
-  int16_t vw = __ui_nodes[nodeIdx].box.w;
-  int16_t vh = __ui_nodes[nodeIdx].box.h;
-  uint32_t need = (uint32_t)(vw > 0 ? vw : 0) * (uint32_t)(vh > 0 ? vh : 0) * 2u;
-  const char* id = __ui_scroll_node_id(nodeIdx);
-  const char* label = (id && id[0]) ? id : "scroll viewport";
-  const char* reasonText = "scroll canvas allocation failed";
-  if (reason == 1) reasonText = "scroll viewport exceeds compile-time canvas budget";
-  else if (reason == 2) reasonText = "using Mode C strip fallback (smooth scroll canvas unavailable)";
-
-#if defined(ESP32)
-  uint32_t freeHeap = ESP.getFreeHeap();
-  uint32_t maxAlloc = ESP.getMaxAllocHeap();
-  Serial.printf(
-    "[cuttlefish] WARNING: #%s (%dx%d) needs %lu bytes for accurate scroll — %s. "
-    "heap free=%lu max_alloc=%lu budget=%d. "
-    "Shrink the scroll viewport in CSS, trim fonts/images, or use PSRAM.\\n",
-    label, vw, vh, (unsigned long)need, reasonText,
-    (unsigned long)freeHeap, (unsigned long)maxAlloc, UI_SCROLL_CANVAS_BUDGET_BYTES);
-#elif defined(ESP8266)
-  uint32_t freeHeap = ESP.getFreeHeap();
-  Serial.printf(
-    "[cuttlefish] WARNING: #%s (%dx%d) needs %lu bytes for accurate scroll — %s. "
-    "heap free=%lu budget=%d. "
-    "Shrink the scroll viewport in CSS, trim fonts/images, or reduce UI footprint.\\n",
-    label, vw, vh, (unsigned long)need, reasonText,
-    (unsigned long)freeHeap, UI_SCROLL_CANVAS_BUDGET_BYTES);
-#else
-  // Non-Arduino target (e.g. SDL native): no Serial, so use standard-C printf.
-  // The native framework forces <cstdio> so printf is available here.
-  printf(
-    "[cuttlefish] WARNING: #%s (%dx%d) needs %lu bytes for accurate scroll — %s. "
-    "budget=%d. Shrink the scroll viewport in CSS or trim UI assets.\\n",
-    label, vw, vh, (unsigned long)need, reasonText, UI_SCROLL_CANVAS_BUDGET_BYTES);
-#endif
+  // Intentionally returns nullptr: scroll containers always use the band
+  // renderer (ui_render_scroll_bands), not the Mode B viewport canvas.
+  // Mode B holds the whole viewport in one large canvas and pushes it in a
+  // single transaction every frame — on SPI TFTs that full-viewport push
+  // (especially from PSRAM) visibly flashes on child state changes like a
+  // button press. The band renderer composites into a small ~10KB SRAM canvas
+  // strip-by-strip, pushing each band only after it's complete — tear-free and
+  // flash-free regardless of target memory. PSRAM still benefits the other
+  // canvases (list, keyboard, repair); only the scroll viewport deliberately
+  // bypasses it for visual quality.
+  (void)w; (void)h;
+  return nullptr;
 }
 
 // Shift the canvas buffer vertically by deltaY (cheap memmove of existing
@@ -117,16 +85,16 @@ static inline void ui_shift_container_canvas(CuttlefishCanvas16* canvas, int16_t
   // band at the TOP. (Matches the proven pre-rewrite direction.)
   if (deltaY > 0) {
     for (int16_t row = 0; row < h - shift; row++) {
-      memmove(pixels + (int32_t)row * stride,
-              pixels + (int32_t)(row + shift) * stride,
-              (size_t)contentW * sizeof(UI_COLOR_T));
+      memmove(pixels + static_cast<int32_t>(row) * stride,
+              pixels + static_cast<int32_t>(row + shift) * stride,
+              static_cast<size_t>(contentW) * sizeof(UI_COLOR_T));
     }
     if (exposedY) *exposedY = h - shift;
   } else {
     for (int16_t row = h - shift - 1; row >= 0; row--) {
-      memmove(pixels + (int32_t)(row + shift) * stride,
-              pixels + (int32_t)row * stride,
-              (size_t)contentW * sizeof(UI_COLOR_T));
+      memmove(pixels + static_cast<int32_t>(row + shift) * stride,
+              pixels + static_cast<int32_t>(row) * stride,
+              static_cast<size_t>(contentW) * sizeof(UI_COLOR_T));
     }
     if (exposedY) *exposedY = 0;
   }
@@ -139,13 +107,18 @@ static inline void ui_shift_container_canvas(CuttlefishCanvas16* canvas, int16_t
 }
 
 // Repair canvas: parent-seeded background repaints + exposed-strip redraws.
-// Grow-only between navigations so small scroll-delta changes do not allocate
-// and free a new strip canvas during drag.
+// Reused across navigations when size matches; reallocated on exact-size
+// mismatch (a reused larger canvas would keep its old stride, corrupting the
+// pushed pixels — see the inline comment below).
 static inline CuttlefishCanvas16* ui_get_repair_canvas(int16_t w, int16_t h) {
   if (w <= 0 || h <= 0) return nullptr;
+  // Reallocate when size differs at all (not just when growing). A reused
+  // larger canvas keeps its old stride, and ui_push_canvas_rect uses that
+  // stride for row offsets — a mismatch with the caller's expected (w,h)
+  // corrupts the pushed pixels. Exact-size reallocation guarantees stride == w.
   if (!__ui_repair_canvas || !display_canvasBuffer(__ui_repair_canvas) ||
-      display_canvasWidth(__ui_repair_canvas) < w ||
-      display_canvasHeight(__ui_repair_canvas) < h) {
+      display_canvasWidth(__ui_repair_canvas) != w ||
+      display_canvasHeight(__ui_repair_canvas) != h) {
     display_deleteCanvas(__ui_repair_canvas);
     __ui_repair_canvas = ui_create_canvas_best(w, h);
   }

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

@@ -13,12 +13,16 @@ static inline void ui_push_canvas_rect(CuttlefishCanvas16* canvas, int16_t x, in
   // 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) {
+    // The framebuffer is the composition target. Track this publish so a
+    // geometry repair or scroll-canvas repair that does not leave a node dirty
+    // still reaches the panel during the frame-end flush.
+    ui_fb_add_rect(x, y, w, h);
     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);
+      ui_display_draw_rgb_bitmap(x, y + row, pixels + static_cast<int32_t>(row) * stride, w, 1);
     }
     return;
   }
@@ -26,12 +30,12 @@ static inline void ui_push_canvas_rect(CuttlefishCanvas16* canvas, int16_t x, in
   display_setAddrWindow(x, y, w, h);
   if (w == stride) {
     // Full-width: contiguous in buffer, single write.
-    display_writePixels(pixels, (uint32_t)w * h);
+    display_writePixels(pixels, static_cast<uint32_t>(w) * h);
     display_endWrite();
     return;
   }
   for (int16_t row = 0; row < h; row++) {
-    display_writePixels(pixels + (int32_t)row * stride, w);
+    display_writePixels(pixels + static_cast<int32_t>(row) * stride, w);
   }
   display_endWrite();
 }
@@ -45,7 +49,7 @@ static inline void ui_draw_canvas_rect(CuttlefishCanvas16* canvas, int16_t x, in
     return;
   }
   for (int16_t row = 0; row < h; row++) {
-    ui_display_draw_rgb_bitmap(x, y + row, pixels + (int32_t)row * stride, w, 1);
+    ui_display_draw_rgb_bitmap(x, y + row, pixels + static_cast<int32_t>(row) * stride, w, 1);
   }
 }
 
@@ -67,10 +71,14 @@ static inline void ui_push_buffered_scroll_canvas(CuttlefishCanvas16* bufferedSc
     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;
+  uint16_t thumbH = static_cast<uint32_t>(vh) * vh / __ui_nodes[si].contentHeight;
   if (thumbH < 8) thumbH = 8;
+  // Clamp to vh so (vh - thumbH) below can't underflow on a degenerate sub-8px
+  // viewport (which would cast a negative value to a huge uint32_t and place the
+  // thumb off-screen). Matches the guard in ui_render_scroll_bands.
+  if (thumbH > static_cast<uint16_t>(vh)) thumbH = static_cast<uint16_t>(vh);
   int16_t maxScroll = __ui_nodes[si].contentHeight - vh;
-  uint16_t thumbY = (uint32_t)(vh - thumbH) * __ui_nodes[si].scrollY / (maxScroll > 0 ? maxScroll : 1);
+  uint16_t thumbY = static_cast<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);
@@ -87,18 +95,22 @@ static inline void ui_push_buffered_scroll_canvas(CuttlefishCanvas16* bufferedSc
 
 // 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;
+  if (si < 0 || si >= static_cast<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;
+  uint16_t thumbH = static_cast<uint32_t>(vh) * vh / __ui_nodes[si].contentHeight;
   if (thumbH < 8) thumbH = 8;
+  // Clamp to vh so (vh - thumbH) below can't underflow on a degenerate sub-8px
+  // viewport (which would cast a negative value to a huge uint32_t and place the
+  // thumb off-screen). Matches the guard in ui_render_scroll_bands.
+  if (thumbH > static_cast<uint16_t>(vh)) thumbH = static_cast<uint16_t>(vh);
   int16_t maxScroll = __ui_nodes[si].contentHeight - vh;
-  uint16_t thumbY = (uint32_t)(vh - thumbH) * __ui_nodes[si].scrollY / (maxScroll > 0 ? maxScroll : 1);
+  uint16_t thumbY = static_cast<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);
+  ui_display_fill_rect(tx, static_cast<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

@@ -39,11 +39,11 @@ 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))
+  #define ui_blend(fg, bg, op)        ui_blend888(static_cast<uint32_t>(fg), static_cast<uint32_t>(bg), (op))
+  #define UI_LERP_COLOR(a, b, k)      lerp_color_888(static_cast<uint32_t>(a), static_cast<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))
+  #define ui_blend(fg, bg, op)        ui_blend565(static_cast<uint16_t>(fg), static_cast<uint16_t>(bg), (op))
+  #define UI_LERP_COLOR(a, b, k)      lerp_color(static_cast<uint16_t>(a), static_cast<uint16_t>(b), (k))
 #endif
 
 // ── 1-bit mono snap (UI_NATIVE_MONO) ─────────────────────────────────────────
@@ -57,7 +57,7 @@ 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;
+  return (static_cast<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.
@@ -68,10 +68,10 @@ static inline uint16_t ui_snap_mono565(uint16_t c) {
   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;
+  return (static_cast<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)))
+#define UI_MAYBE_SNAP_MONO(c)    (ui_snap_mono(static_cast<uint32_t>(c)))
+#define UI_MAYBE_SNAP_MONO565(c) (ui_snap_mono565(static_cast<uint16_t>(c)))
 #else
 #define UI_MAYBE_SNAP_MONO(c)    (c)
 #define UI_MAYBE_SNAP_MONO565(c) (c)
@@ -115,7 +115,7 @@ static inline uint16_t ui_snap_mono565(uint16_t c) {
       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);
+      int16_t rx1 = static_cast<int16_t>(r.x + r.w), ry1 = static_cast<int16_t>(r.y + r.h);
       if (rx1 > x1) x1 = rx1;
       if (ry1 > y1) y1 = ry1;
     }
@@ -124,7 +124,7 @@ static inline uint16_t ui_snap_mono565(uint16_t c) {
     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));
+      display_partial_refresh(x0, y0, static_cast<int16_t>(x1 - x0), static_cast<int16_t>(y1 - y0));
     }
   }
 #elif defined(UI_BATCH_SPI_WRITES)