@typecad/ui 1.0.0-alpha.11 → 1.0.0-alpha.13

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

@@ -3,21 +3,40 @@
 // See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
 export function emitBlendBodies(): string {
   return `
+// Blend LUTs (LVGL draw-unit trick, memory-frugal variant): two 256-entry
+// per-channel tables rebuilt only when the opacity level CHANGES. Blends
+// typically run per-pixel at a fixed opacity (skeleton pulse frame, one
+// shadow pass, a glyph's coverage step), so the table amortizes to one
+// rebuild per pass and every pixel becomes three array lookups instead of
+// three multiply-divide rounds. Total cost: 513 bytes of static RAM.
+static uint8_t __ui_blend_lut_fg[256];
+static uint8_t __ui_blend_lut_bg[256];
+static uint8_t __ui_blend_lut_opacity = 255; // 255 = never built (valid range 0..100)
+static inline void ui_blend_lut_build(uint8_t opacity) {
+  if (__ui_blend_lut_opacity == opacity) return;
+  for (int16_t v = 0; v < 256; v++) {
+    __ui_blend_lut_fg[v] = static_cast<uint8_t>((v * opacity) / 100);
+    __ui_blend_lut_bg[v] = static_cast<uint8_t>((v * (100 - opacity)) / 100);
+  }
+  __ui_blend_lut_opacity = opacity;
+}
+
 static inline uint16_t ui_blend565(uint16_t fg, uint16_t bg, uint8_t opacity) {
   if (opacity >= 100) return fg;
   if (opacity == 0) return bg;
-  // Blend in 888 internally for higher precision: unpack 565→888 (replicating
+  ui_blend_lut_build(opacity);
+  // Blend in 888 internally for higher precision: unpack 565->888 (replicating
   // high bits), blend at 8-bit, then re-quantize to 565. This produces smoother
-  // intermediate values for AA text edges, opacity, shadows, and gradients —
+  // intermediate values for AA text edges, opacity, shadows, and gradients --
   // the 565-channel blend (32 red levels) was too coarse and showed banding.
   uint8_t fr = (fg >> 11) & 0x1F, fg5 = (fg >> 5) & 0x3F, fb = fg & 0x1F;
   uint8_t br = (bg >> 11) & 0x1F, bg5 = (bg >> 5) & 0x3F, bb = bg & 0x1F;
-  // Unpack to 8-bit (5-bit → 8-bit: (v << 3) | (v >> 2)).
+  // 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 = 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);
+  uint16_t r = static_cast<uint16_t>(__ui_blend_lut_fg[fr8] + __ui_blend_lut_bg[br8]);
+  uint16_t g = static_cast<uint16_t>(__ui_blend_lut_fg[fg8] + __ui_blend_lut_bg[bg8]);
+  uint16_t b = static_cast<uint16_t>(__ui_blend_lut_fg[fb8] + __ui_blend_lut_bg[bb8]);
   return ((r >> 3) << 11) | ((g >> 2) << 5) | (b >> 3);
 }
 
@@ -28,11 +47,12 @@ static inline uint16_t ui_blend565(uint16_t fg, uint16_t bg, uint8_t opacity) {
 static inline uint32_t ui_blend888(uint32_t fg, uint32_t bg, uint8_t opacity) {
   if (opacity >= 100) return fg;
   if (opacity == 0) return bg;
+  ui_blend_lut_build(opacity);
   uint8_t fr = (fg >> 16) & 0xff, fg8 = (fg >> 8) & 0xff, fb = fg & 0xff;
   uint8_t br = (bg >> 16) & 0xff, bg8 = (bg >> 8) & 0xff, bb = bg & 0xff;
-  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;
+  uint8_t r = static_cast<uint8_t>(__ui_blend_lut_fg[fr] + __ui_blend_lut_bg[br]);
+  uint8_t g = static_cast<uint8_t>(__ui_blend_lut_fg[fg8] + __ui_blend_lut_bg[bg8]);
+  uint8_t b = static_cast<uint8_t>(__ui_blend_lut_fg[fb] + __ui_blend_lut_bg[bb]);
   return (static_cast<uint32_t>(r) << 16) | (static_cast<uint32_t>(g) << 8) | b;
 }
 `;

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

@@ -29,13 +29,16 @@ static inline CuttlefishCanvas16* ui_create_canvas_best(int16_t w, int16_t h) {
       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());
+        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);
+        printf("[psram] canvas %dx%d allocated in PSRAM\\n", w, h);
 #endif
       }
       return c;
     }
+    // Object allocated but its pixel buffer failed — free the object before
+    // falling through to SRAM so it isn't leaked.
+    display_deleteCanvas(c);
     // PSRAM allocation failed (rare — fragmented PSRAM) → fall through to SRAM.
   }
 #endif

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

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

@@ -347,6 +347,17 @@ void CuttlefishGFX::fillCircleHelper(int16_t x0, int16_t y0, int16_t r, uint8_t
 }
 
 void CuttlefishGFX::drawRoundRect(int16_t x, int16_t y, int16_t w, int16_t h, int16_t r, uint16_t color) {
+  if (w <= 0 || h <= 0) return;
+  if (r <= 0) {
+    drawRect(x, y, w, h, color);
+    return;
+  }
+  // CSS border-radius semantics: radii larger than half the shorter side
+  // collapse to a pill/box (the preview host-gfx clamps identically). Kit
+  // styles lower border-radius:9999px to r=255; without this clamp the
+  // corner arcs overgrow the box instead of forming a true pill.
+  const int16_t halfMin = static_cast<int16_t>((w < h ? w : h) / 2);
+  if (r > halfMin) r = halfMin;
   drawFastHLine(x + r,     y,         w - 2 * r, color); // Top
   drawFastHLine(x + r,     y + h - 1, w - 2 * r, color); // Bottom
   drawFastVLine(x,         y + r,     h - 2 * r, color); // Left
@@ -358,7 +369,17 @@ void CuttlefishGFX::drawRoundRect(int16_t x, int16_t y, int16_t w, int16_t h, in
 }
 
 void CuttlefishGFX::fillRoundRect(int16_t x, int16_t y, int16_t w, int16_t h, int16_t r, uint16_t color) {
+  if (w <= 0 || h <= 0) return;
+  if (r <= 0) {
+    fillRect(x, y, w, h, color);
+    return;
+  }
+  const int16_t halfMin = static_cast<int16_t>((w < h ? w : h) / 2);
+  if (r > halfMin) r = halfMin;
   fillRect(x + r, y, w - 2 * r, h, color);
+  // h - 2*r - 1 stays unclamped: for a perfect pill (h == 2r) it is -1 and the
+  // helper's +1+delta lands the arc lines exactly on the box (the preview
+  // host-gfx passes the same unclamped value).
   fillCircleHelper(x + w - r - 1, y + r, r, 1, h - 2 * r - 1, color);
   fillCircleHelper(x + r,         y + r, r, 2, h - 2 * r - 1, color);
 }