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

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

@@ -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() {
     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/dist/ui-engine/runtime-header/canvas-scrollbar.js

@@ -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/dist/ui-engine/runtime-header/color-mono-refresh.js

@@ -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)

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

@@ -0,0 +1 @@
+export declare function emitCuttlefishGfx(active: boolean): string;