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

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

@@ -2,30 +2,29 @@
 // scrollbar + buffered scroll canvas push.
 // See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
 export function emitTickScrollCanvasPhase() {
-    return `
-  }
-  // ②b Draw scrollbar + push canvas for the buffered scroll container.
-  if (bufferedScrollNode >= 0 && bufferedScrollCanvas) {
-    ui_push_buffered_scroll_canvas(bufferedScrollCanvas, bufferedScrollRepaintCanvas,
-      bufferedScrollNode, bufferedScrollVX, bufferedScrollVY,
-      bufferedScrollRepaintY, bufferedScrollRepaintH, __ui_draw_target);
-  } 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;
+    return `
+  // ②b Draw scrollbar + push canvas for the buffered scroll container.
+  if (bufferedScrollNode >= 0 && bufferedScrollCanvas) {
+    ui_push_buffered_scroll_canvas(bufferedScrollCanvas, bufferedScrollRepaintCanvas,
+      bufferedScrollNode, bufferedScrollVX, bufferedScrollVY,
+      bufferedScrollRepaintY, bufferedScrollRepaintH, __ui_draw_target);
+  } 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/touch-keyboard-fwd.js

@@ -3,6 +3,7 @@
 // See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
 export function emitTouchKeyboardFwd() {
     return `
+#include <cstdlib>  // abs() for drag-distance thresholds (self-sufficient slice)
 // ── Touch hit-testing + click dispatch ─────────────────────────────────────
 // Radio groups for mutual exclusion
 struct UIRadioGroup {
@@ -13,11 +14,14 @@ extern UIRadioGroup __ui_radio_groups[];
 extern const uint16_t __ui_radio_group_count;
 
 // Forward-declare the click handler type + tables (defined by the emit layer).
-extern void (*__ui_click_handlers[])();
-extern void (*__ui_hold_handlers[])();
-extern void (*__ui_release_handlers[])();
+// The tables are const (flash rodata) — they are never written at runtime.
+extern void (*const __ui_click_handlers[])();
+extern void (*const __ui_hold_handlers[])();
+extern void (*const __ui_release_handlers[])();
 extern void (*__ui_rangechange_handlers[])();
 extern const uint16_t __ui_click_handler_count;
+extern const uint16_t __ui_hold_handler_count;
+extern const uint16_t __ui_release_handler_count;
 extern const uint16_t __ui_rangechange_handler_count;
 
 // Touch state machine: tracks down → hold → up → click lifecycle
@@ -77,6 +81,10 @@ static inline void ui_kb_handle_touch(int16_t tx, int16_t ty);
 static inline void ui_kb_handle_tap(int16_t tx, int16_t ty);
 static inline void ui_kb_key_rect(uint8_t idx, UIRect* out);
 static inline void ui_kb_draw();
+
+// Modal <select> + <drawer> declarations live in forward-decls.ts
+// (emit order: ui_navigate/visibility/ui_init reference them before this module).
+
 static inline void ui_kb_draw_key(uint8_t i);
 static inline void ui_kb_draw_text_row();
 static inline void ui_kb_compute_box();
@@ -85,13 +93,22 @@ static inline void ui_kb_compute_box();
 #define UI_DRAG_THRESHOLD 10
 
 // Hit-test a touch point against all visible nodes (topmost first).
-// Returns the node index of the topmost node that BOTH contains the point
-// AND has a click handler registered. Returns -1 if none.
+// Returns the node the tap TARGETS, resolved like the DOM: the topmost node
+// whose box contains the point, then bubbling to ANCESTORS only. Returns -1
+// if no ancestor of the target is interactive or handler-bearing.
 static int16_t ui_hit_test(int16_t tx, int16_t ty) {
-  int16_t best = -1;
+  // Phase 1 — the event target: the TOPMOST node containing the tap (last in
+  // draw order), regardless of handlers. Filtering for handler-bearing nodes
+  // here let a tap fall through SIBLING layers: a modal card (no handler,
+  // higher z) over a click-to-close scrim (handler) routed every card tap to
+  // the scrim underneath, so any tap dismissed the dialog. In the DOM the
+  // click targets the topmost element and never propagates sideways to a
+  // covered sibling.
+  int16_t target = -1;
   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;
+    if (__ui_nodes[i].disabled) continue;  // HTML disabled: not a tap target
     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 &&
@@ -101,26 +118,29 @@ static int16_t ui_hit_test(int16_t tx, int16_t ty) {
       // 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(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
-      // gets :pressed/transition visual feedback even with no JS onClick wired
-      // (a pure-CSS button like a demo "tap to transition" control).
-      if (__ui_nodes[i].kind == NODE_RANGE || __ui_nodes[i].kind == NODE_INPUT || __ui_nodes[i].kind == NODE_LIST || __ui_nodes[i].kind == NODE_BUTTON || __ui_nodes[i].kind == NODE_CHECK || __ui_nodes[i].kind == NODE_RADIO) {
-        if (best < 0 || ui_node_draws_before(best, i)) best = i;
-        continue;
-      }
-      if (i < __ui_click_handler_count &&
-          (__ui_click_handlers[i] || __ui_hold_handlers[i] || __ui_release_handlers[i])) {
-        if (best < 0 || ui_node_draws_before(best, i)) best = i;
-      }
+      if (target < 0 || ui_node_draws_before(target, i)) target = static_cast<int16_t>(i);
     }
   }
-  return best;
+  // Phase 2 — bubbling: walk from the target up through its ancestors.
+  // Interactive kinds match even with no JS handler wired — NODE_RANGE
+  // (horizontal drag), NODE_INPUT (opens the keyboard), NODE_LIST
+  // (virtualized item tap), and NODE_BUTTON/NODE_CHECK/NODE_RADIO so a
+  // pure-CSS control still gets :pressed/transition visual feedback.
+  int16_t n = target;
+  while (n >= 0) {
+    uint16_t u = static_cast<uint16_t>(n);
+    if (__ui_nodes[u].kind == NODE_RANGE || __ui_nodes[u].kind == NODE_INPUT || __ui_nodes[u].kind == NODE_LIST || __ui_nodes[u].kind == NODE_BUTTON || __ui_nodes[u].kind == NODE_CHECK || __ui_nodes[u].kind == NODE_RADIO) return n;
+    if ((u < __ui_click_handler_count && __ui_click_handlers[u]) ||
+        (u < __ui_hold_handler_count && __ui_hold_handlers[u]) ||
+        (u < __ui_release_handler_count && __ui_release_handlers[u])) return n;
+    if (__ui_nodes[u].parent == UI_NO_PARENT || __ui_nodes[u].parent >= __ui_node_count) break;
+    n = static_cast<int16_t>(__ui_nodes[u].parent);
+  }
+  return -1;
 }
 
 // Dispatch a handler from the given table if registered for the node.
-static void ui_dispatch(void (**table)(), uint16_t count, int16_t node) {
+static void ui_dispatch(void (*const* table)(), uint16_t count, int16_t node) {
   if (node >= 0 && static_cast<uint16_t>(node) < count && table[node]) {
     table[node]();
   }
@@ -150,6 +170,13 @@ static inline void ui_open_keyboard_for_input(uint16_t nodeIdx) {
 
 // Touch down: called when screen is first touched.
 static void ui_touch_down(int16_t tx, int16_t ty) {
+  // Modal <select> list: record the touch position; tap-up routes to the
+  // option rows. No hit-test/press/scroll while the overlay is open.
+  if (__ui_select_menu >= 0) {
+    __ui_touch_state = 1;
+    __ui_touch_down_time = millis();
+    return;
+  }
   int16_t node = ui_hit_test(tx, ty);
   __ui_touch_node = node;
   __ui_touch_state = 1;
@@ -208,6 +235,35 @@ static void ui_touch_up() {
   // Modal keyboard: route tap-up to the keyboard; swallow normal click logic.
   // (Skipped on UI_HIDE_OSK desktop targets — touches pass through to the app,
   // since the editing session is driven by the real keyboard, not the grid.)
+  // Open drawers close on outside taps (device parity with the preview).
+  {
+    int16_t dx0 = __ui_last_touch_x;
+    int16_t dy0 = __ui_last_touch_y;
+    for (uint8_t s = 0; s < __ui_drawer_slots; s++) {
+      if (__ui_drawer_idx[s] < 0 || !__ui_drawer_open[s] || __ui_drawer_progress[s] < 255) continue;
+      uint16_t di = static_cast<uint16_t>(__ui_drawer_idx[s]);
+      // Hit-test the SUBTREE rect: a <dialog> root with absolutely
+      // positioned children lays out at h=0 — the root box made every tap
+      // count as "outside" and closed the dialog immediately.
+      UIRect panelRect;
+      if (!ui_subtree_current_paint_rect(di, &panelRect)) {
+        panelRect.x = ui_draw_x_for_node(di);
+        panelRect.y = ui_draw_y_for_node(di);
+        panelRect.w = __ui_nodes[di].box.w;
+        panelRect.h = __ui_nodes[di].box.h;
+      }
+      if (dx0 < panelRect.x || dx0 >= panelRect.x + panelRect.w ||
+          dy0 < panelRect.y || dy0 >= panelRect.y + panelRect.h) {
+        __ui_drawer_open[s] = 0;
+      }
+    }
+  }
+  if (__ui_select_menu >= 0) {
+    ui_select_menu_tap(__ui_last_touch_x, __ui_last_touch_y);
+    __ui_touch_state = 0;
+    __ui_last_touch_time = millis();
+    return;
+  }
 #if !defined(UI_HIDE_OSK)
   if (__ui_kb_visible) {
     ui_kb_handle_tap(__ui_last_touch_x, __ui_last_touch_y);
@@ -241,7 +297,7 @@ static void ui_touch_up() {
         if (target >= 0) ui_navigate(static_cast<uint8_t>(target));
       }
     }
-    ui_dispatch(__ui_release_handlers, __ui_click_handler_count, __ui_touch_node);
+    ui_dispatch(__ui_release_handlers, __ui_release_handler_count, __ui_touch_node);
     // 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
@@ -389,7 +445,7 @@ static inline void ui_handle_touch(int16_t tx, int16_t ty) {
     if (__ui_touch_state == 1 && __ui_touch_node >= 0 && !__ui_is_dragging) {
       if (now - __ui_touch_down_time >= UI_TOUCH_HOLD_MS) {
         __ui_touch_state = 2;
-        ui_dispatch(__ui_hold_handlers, __ui_click_handler_count, __ui_touch_node);
+        ui_dispatch(__ui_hold_handlers, __ui_hold_handler_count, __ui_touch_node);
       }
     }
   }

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

@@ -2,98 +2,115 @@
 // Guard open, includes, and #define knobs.
 // See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
 export function emitTypesDefines() {
-    return `
-// ── Cuttlefish UI runtime (emit once per TU) ──────────────────────────────
-#ifndef __TC_UI_RUNTIME
-#define __TC_UI_RUNTIME
-#include <stdint.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
-#define UI_WS_NOWRAP 1
-#define UI_WS_PRE 2
-#define UI_WS_PRE_LINE 3
-#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
-#ifndef UI_TRANSITION_SNAP_MS
-#define UI_TRANSITION_SNAP_MS 100
-#endif
-// Scroll physics + capability defaults. The per-TU #define overrides emitted
-// by the UI emitter (from resolveScrollConfig) hit BEFORE this header, so these
-// #ifndef guards adopt the configured values. Spec: 2026-06-28-scroll-engine-rewrite-design.md
-#ifndef UI_SCROLL_MAX_OVERSCROLL
-#define UI_SCROLL_MAX_OVERSCROLL 40
-#endif
-#ifndef UI_SCROLL_STIFFNESS_X10
-#define UI_SCROLL_STIFFNESS_X10 5
-#endif
-#ifndef UI_SCROLL_EDGE_SNAP_PX
-#define UI_SCROLL_EDGE_SNAP_PX 12
-#endif
-#ifndef UI_SCROLL_DRAG_SCALE_X10
-#define UI_SCROLL_DRAG_SCALE_X10 10
-#endif
-#ifndef UI_SCROLL_SETTLE_MS
-#define UI_SCROLL_SETTLE_MS 180
-#endif
-#ifndef UI_SCROLL_DEADBAND_PX
-#define UI_SCROLL_DEADBAND_PX 2
-#endif
-// Capability tier flags (emitted per-TU before this header; defaults = full).
-#ifndef UI_SCROLL_INPUT_TIER_CAPACITIVE
-#define UI_SCROLL_INPUT_TIER_CAPACITIVE 0
-#endif
-#ifndef UI_SCROLL_INPUT_TIER_RESISTIVE
-#define UI_SCROLL_INPUT_TIER_RESISTIVE 0
-#endif
-#ifndef UI_SCROLL_INPUT_TIER_NONE
-#define UI_SCROLL_INPUT_TIER_NONE 0
-#endif
-#ifndef UI_SCROLL_RENDER_TIER_FULL
-#define UI_SCROLL_RENDER_TIER_FULL 1
-#endif
-#ifndef UI_SCROLL_RENDER_TIER_CONSTRAINED
-#define UI_SCROLL_RENDER_TIER_CONSTRAINED 0
-#endif
-#if (UI_SCROLL_INPUT_TIER_CAPACITIVE + UI_SCROLL_INPUT_TIER_RESISTIVE + UI_SCROLL_INPUT_TIER_NONE) == 0
-#define UI_SCROLL_INPUT_TIER_RESISTIVE 1
-#endif
-#define UI_SCROLL_HAS_TOUCH (UI_SCROLL_INPUT_TIER_CAPACITIVE || UI_SCROLL_INPUT_TIER_RESISTIVE)
-#define UI_SCROLL_ELASTIC (UI_SCROLL_RENDER_TIER_FULL)
-// Telemetry: emits per-frame scrollY/overscrollPx/dy over Serial when defined.
-#ifndef UI_SCROLL_DEBUG
-#define UI_SCROLL_DEBUG 0
-#endif
-// 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>
-#endif
+    return `
+// ── Cuttlefish UI runtime (emit once per TU) ──────────────────────────────
+#ifndef __TC_UI_RUNTIME
+#define __TC_UI_RUNTIME
+#include <stdint.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
+#define UI_WS_NOWRAP 1
+#define UI_WS_PRE 2
+#define UI_WS_PRE_LINE 3
+#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
+#ifndef UI_TRANSITION_SNAP_MS
+#define UI_TRANSITION_SNAP_MS 100
+#endif
+// Scroll physics + capability defaults. The per-TU #define overrides emitted
+// by the UI emitter (from resolveScrollConfig) hit BEFORE this header, so these
+// #ifndef guards adopt the configured values. Spec: 2026-06-28-scroll-engine-rewrite-design.md
+#ifndef UI_SCROLL_MAX_OVERSCROLL
+#define UI_SCROLL_MAX_OVERSCROLL 40
+#endif
+#ifndef UI_SCROLL_STIFFNESS_X10
+#define UI_SCROLL_STIFFNESS_X10 5
+#endif
+#ifndef UI_SCROLL_EDGE_SNAP_PX
+#define UI_SCROLL_EDGE_SNAP_PX 12
+#endif
+#ifndef UI_SCROLL_DRAG_SCALE_X10
+#define UI_SCROLL_DRAG_SCALE_X10 10
+#endif
+#ifndef UI_SCROLL_SETTLE_MS
+#define UI_SCROLL_SETTLE_MS 180
+#endif
+#ifndef UI_SCROLL_DEADBAND_PX
+#define UI_SCROLL_DEADBAND_PX 2
+#endif
+// Capability tier flags (emitted per-TU before this header; defaults = full).
+// The default-on check must run BEFORE the per-flag #ifndef defaults below —
+// after them, all three flags are defined 0 and the fallback would redefine
+// UI_SCROLL_INPUT_TIER_RESISTIVE with a different value (ill-formed).
+#if !defined(UI_SCROLL_INPUT_TIER_CAPACITIVE) && !defined(UI_SCROLL_INPUT_TIER_RESISTIVE) && !defined(UI_SCROLL_INPUT_TIER_NONE)
+#define UI_SCROLL_INPUT_TIER_RESISTIVE 1
+#endif
+#ifndef UI_SCROLL_INPUT_TIER_CAPACITIVE
+#define UI_SCROLL_INPUT_TIER_CAPACITIVE 0
+#endif
+#ifndef UI_SCROLL_INPUT_TIER_RESISTIVE
+#define UI_SCROLL_INPUT_TIER_RESISTIVE 0
+#endif
+#ifndef UI_SCROLL_INPUT_TIER_NONE
+#define UI_SCROLL_INPUT_TIER_NONE 0
+#endif
+#ifndef UI_SCROLL_RENDER_TIER_FULL
+#define UI_SCROLL_RENDER_TIER_FULL 1
+#endif
+#ifndef UI_SCROLL_RENDER_TIER_CONSTRAINED
+#define UI_SCROLL_RENDER_TIER_CONSTRAINED 0
+#endif
+#define UI_SCROLL_HAS_TOUCH (UI_SCROLL_INPUT_TIER_CAPACITIVE || UI_SCROLL_INPUT_TIER_RESISTIVE)
+#define UI_SCROLL_ELASTIC (UI_SCROLL_RENDER_TIER_FULL)
+// Telemetry: emits per-frame scrollY/overscrollPx/dy over Serial when defined.
+#ifndef UI_SCROLL_DEBUG
+#define UI_SCROLL_DEBUG 0
+#endif
+// 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).
+// Dirty-rect merging (LVGL refresh-cycle technique): several same-frame
+// dirty nodes whose paint rects are near each other composite as one banded
+// region instead of per-node transactions. Regions cap at the band-
+// compositable pixel budget; singleton rects keep the per-node ladder.
+#ifndef UI_MERGE_INFLATE
+#define UI_MERGE_INFLATE 8
+#endif
+#ifndef UI_MERGE_MAX_REGIONS
+#define UI_MERGE_MAX_REGIONS 6
+#endif
+#ifndef UI_MERGE_MAX_NODES
+#define UI_MERGE_MAX_NODES 12
+#endif
+
+#ifndef UI_STRIP_BAND_HEIGHT
+#define UI_STRIP_BAND_HEIGHT 32
+#endif
+#if defined(ESP32) || defined(ESP8266)
+#include <Esp.h>
+#endif
 `;
 }

package/dist/ui-engine/shadcn-kit.d.ts

@@ -0,0 +1 @@
+export declare const SHADCN_KIT_CSS = "/* ---------------------------------------------------------------------------\n * shadcn-style component kit \u2014 BUILT IN and always included.\n *\n * These tokens + class recipes are prepended to every build and preview\n * automatically, BEFORE your stylesheets, so anything you write overrides\n * them by normal cascade order. No scaffolding, no imports needed: put the\n * classes on native elements and they work.\n *\n * THEMES: a theme is any CSS file. Pre-packaged ones ship with @typecad/ui \u2014\n * import by bare specifier from a <style> block (or the sidecar .ui.css):\n *\n *   @import \"@typecad/ui/themes/blue.css\";   (zinc slate stone gray neutral\n *                                             blue green red)\n *\n * Your own: save a ui.shadcn.com / tweakcn export into the project and\n * @import it by path \u2014 its :root/.dark token blocks override the kit\n * defaults (later definitions win). Both dialects parse \u2014 classic HSL channel triplets and\n * Tailwind-v4 oklch(); alpha in colors is ignored (no blending on bare\n * metal). Dark mode activates with themeClass: 'dark' in the config's\n * display block.\n *\n * Overriding recipes: redefine any class in your own stylesheet; your\n * definition wins.\n *\n * Components (classes over native elements):\n *   Button      <button class=\"btn btn-primary\">Save</button>\n *               variants: -secondary -outline -ghost -destructive\n *               sizes: .btn-sm .btn-lg   full width: .btn-block\n *   Badge       <text class=\"badge badge-secondary\">new</text>\n *               variants: -default(omit) -destructive -outline\n *   Card        <view class=\"card\">\n *                 <view class=\"card-header\">\n *                   <text class=\"card-title\">Title</text>\n *                   <text class=\"card-description\">Subtitle</text>\n *                 </view>\n *                 <view class=\"card-content\">...</view>\n *                 <view class=\"card-footer\">...buttons...</view>\n *               </view>\n *   Input       <input class=\"input\" placeholder=\"...\"/>\n *   Label       <label class=\"form-label\">Name</label>\n *   Row (kit)   <view class=\"row\"> ... </view>   (flex row + gap, for composing)\n *   Validation  .input-error (destructive border) + .field-error hint;\n *               runtime-driven: bind borderColor/visible to a signal\n *   Separator   <hr class=\"separator\"/> (horizontal) or\n *               <hr class=\"vseparator\"/> (vertical; stretches to the row height)\n *   Alert       <view class=\"alert alert-destructive\">\n *                 <text class=\"alert-title\">...</text>\n *                 <text class=\"alert-description\">...</text>\n *               </view>\n *   Skeleton    <view class=\"skeleton\"/>            (pulse while loading)\n *   Spinner     <view class=\"spinner\"><view class=\"spinner-dot\"/></view>\n *               (indeterminate loading: a dot orbiting a ring via pure\n *                transform keyframes \u2014 translate lerps smoothly, unlike\n *                rotate which only renders exact quarter turns)\n *   Dialog      <dialog id=\"d\"><view class=\"dialog-scrim\" on:click={...}/>\n *               <view class=\"dialog-card\"> ... <view class=\"dialog-footer\">\n *               </view></dialog>\n *               (centered modal: programmatic ui.dialog.open(id), scrim tap\n *                closes; same slot machinery as the drawer)\n *   Toast       <toast id=\"t\" side=\"bottom\" duration=\"2500\" class=\"toast\">\n *               ...</toast>  (ui.toast(id) shows it; auto-closes after the\n *               duration; stacks as authored siblings)\n *   Progress    <progress class=\"progress\" value=\"40\"/>\n *   Avatar      <img class=\"avatar\" src=\"face.bmp\"/>\n *   Switch      <check class=\"switch\"/>             (pill container; the\n *               16px indicator is runtime-drawn at the top-left \u2014 best-effort)\n *   Tabs        <view class=\"tabs-list\"><button class=\"tabs-trigger\">..</button>..\n *               <view class=\"tabs-content-area\"><view class=\"tabs-content\">..\n *               (panes toggle via ui.bind(x, 'visible', ...) on a signal)\n *   Accordion   <view class=\"accordion\"><view class=\"accordion-item\">..\n *               (content toggles via ui.bind visible; chevron via text bind)\n *   Table       <table> ... </table>                (UA styles apply; see the\n *               html-table-approximation build note)\n * ------------------------------------------------------------------------- */\n\n:root {\n  --background: #ffffff;\n  --foreground: #09090b;\n  --card: #ffffff;\n  --card-foreground: #09090b;\n  --primary: #18181b;\n  --primary-foreground: #fafafa;\n  --secondary: #f4f4f5;\n  --secondary-foreground: #18181b;\n  --muted: #f4f4f5;\n  --muted-foreground: #71717a;\n  --accent: #f4f4f5;\n  --accent-foreground: #18181b;\n  --destructive: #dc2626;\n  --destructive-foreground: #fafafa;\n  --destructive-background: #fee2e2;\n  --border: #e4e4e7;\n  --input: #e4e4e7;\n  --radius: 8px;\n  --shadow-sm: 0 1px 3px rgb(0 0 0 / 0.1);\n  /* Solid scrim for dialogs \u2014 alpha blending needs a canvas underneath, so\n     the kit uses an opaque near-black that reads as a dimmed backdrop. */\n  --scrim: #101014;\n}\n\n.dark {\n  --background: #09090b;\n  --foreground: #fafafa;\n  --card: #18181b;\n  --card-foreground: #fafafa;\n  --primary: #fafafa;\n  --primary-foreground: #18181b;\n  --secondary: #27272a;\n  --secondary-foreground: #fafafa;\n  --muted: #27272a;\n  --muted-foreground: #a1a1aa;\n  --accent: #27272a;\n  --accent-foreground: #fafafa;\n  --destructive: #ef4444;\n  --destructive-foreground: #09090b;\n  --destructive-background: #451a1a;\n  --border: #27272a;\n  --input: #3f3f46;\n  --radius: 8px;\n}\n\n/* ---- Button ---------------------------------------------------------------- */\n\n.btn {\n  border-radius: var(--radius);\n  padding: 10px 16px;\n  font-weight: bold;\n  transition: background 80ms;\n}\n.btn:pressed { transform: translateY(1px); }\n.btn-primary { background: var(--primary); color: var(--primary-foreground); }\n.btn-secondary { background: var(--secondary); color: var(--secondary-foreground); }\n.btn-outline { background: var(--background); color: var(--foreground); border: 1px solid var(--border); }\n.btn-ghost { color: var(--foreground); }\n.btn-destructive { background: var(--destructive); color: var(--destructive-foreground); }\n.btn-sm { padding: 6px 10px; min-height: 32px; font-size: 12px; }\n.btn-lg { padding: 14px 22px; min-height: 52px; font-size: 18px; }\n.btn-block { align-self: stretch; }\n\n/* ---- Badge ------------------------------------------------------------------ */\n\n.badge {\n  background: var(--primary);\n  color: var(--primary-foreground);\n  padding: 2px 8px;\n  border-radius: 999px;\n  font-size: 12px;\n  text-align: center;\n}\n.badge-secondary { background: var(--secondary); color: var(--secondary-foreground); }\n.badge-destructive { background: var(--destructive); color: var(--destructive-foreground); }\n.badge-outline { background: var(--background); color: var(--foreground); border: 1px solid var(--border); }\n\n/* ---- Layout utility -------------------------------------------------------------\n   Not a shadcn component \u2014 a kit convenience for composing recipes. */\n\n.row { flex-direction: row; align-items: center; gap: 8px; }\n\n/* ---- Card ------------------------------------------------------------------- */\n\n.card {\n  background: var(--card);\n  color: var(--card-foreground);\n  border: 1px solid var(--border);\n  border-radius: var(--radius);\n  box-shadow: var(--shadow-sm);\n  padding: 16px;\n  gap: 8px;\n  align-self: stretch;\n}\n.card-header { gap: 4px; }\n.card-title { font-size: 18px; font-weight: bold; }\n.card-description { font-size: 14px; color: var(--muted-foreground); }\n.card-content { gap: 8px; }\n.card-footer { flex-direction: row; gap: 8px; }\n\n/* ---- Tabs ---------------------------------------------------------------- */\n\n/* Segmented trigger row (shadcn TabsList). Active-trigger styling is driven\n   at runtime by ui.bind background/color bindings in author code \u2014 runtime\n   color swaps are literal hex (compile-time tokens), so pin them to the\n   active theme the way native_demo accents do. */\n.tabs-list {\n  flex-direction: row;\n  gap: 4px;\n  align-self: stretch;\n  background: var(--muted);\n  border-radius: var(--radius);\n  padding: 4px;\n}\n.tabs-trigger {\n  flex-grow: 1;\n  border-radius: calc(var(--radius) - 2px);\n  padding: 6px 10px;\n  min-height: 32px;\n  font-size: 13px;\n  text-align: center;\n}\n/* Fixed-height content region: panes are absolutely stacked inside it and\n   toggled via ui.bind(x, 'visible', ...) \u2014 layout keeps every pane's box,\n   so switching never re-flows. */\n.tabs-content-area {\n  position: relative;\n  align-self: stretch;\n  height: 150px;\n}\n.tabs-content {\n  position: absolute;\n  left: 0;\n  top: 0;\n  right: 0;\n  bottom: 0;\n  gap: 8px;\n}\n\n/* ---- Accordion (single-open) --------------------------------------------- */\n\n/* Stacked collapsible sections. The trigger is a button + chevron row; the\n   content pane toggles via ui.bind(x, 'visible', () => signal === i) \u2014 the\n   same signal pattern as Tabs. The chevron swaps v/^ via a text binding. */\n.accordion {\n  gap: 8px;\n  align-self: stretch;\n}\n.accordion-item {\n  background: var(--card);\n  border: 1px solid var(--border);\n  border-radius: var(--radius);\n}\n.accordion-trigger-row {\n  flex-direction: row;\n  align-items: center;\n  gap: 8px;\n  padding: 10px 12px;\n}\n.accordion-trigger {\n  flex-grow: 1;\n  text-align: left;\n  font-weight: bold;\n  padding: 0;\n  min-height: 20px;\n  /* The UA sheet gives every button a 1px border (border: 1px solid, colored\n     by the foreground token). A trigger is a plain text row on the card \u2014\n     cancel it or each one renders with a bright outline. */\n  border: none;\n}\n.accordion-chevron {\n  color: var(--muted-foreground);\n  font-size: 14px;\n  /* Wide enough for the '^' glyph (advance 12px at 14px size) \u2014 a single\n     char wider than the box wraps to nothing. */\n  width: 16px;\n  text-align: center;\n}\n.accordion-content {\n  padding: 0 12px 10px 12px;\n  gap: 8px;\n}\n\n/* ---- Form controls ----------------------------------------------------------- */\n\n.input {\n  background: var(--background);\n  color: var(--foreground);\n  border: 1px solid var(--input);\n  border-radius: var(--radius);\n}\n.form-label { color: var(--foreground); font-size: 14px; }\n\n/* Switch: pill container. The runtime draws a 16px circular knob that\n   slides with state \u2014 hollow at the left when off, solid at the right when\n   on (a static jump, no travel animation). min-height overrides the UA\n   touch target so the pill stays 26px tall. */\n.switch {\n  width: 44px;\n  height: 26px;\n  /* Override the UA's touch-target min-height (42px on small panels) \u2014 the\n     pill must stay 26px tall to read as a switch, not a checkbox. */\n  min-height: 26px;\n  border-radius: 999px;\n  border: 1px solid var(--border);\n  /* --card, not --muted: on a bare (near-black) page background a --muted\n     track reads as a stray gray box; --card keeps the pill affordance while\n     staying quiet. Swap back to var(--muted) inside lighter containers. */\n  background: var(--card);\n}\n\n/* ---- Checked-state pairs (shadcn data-[state=checked]) ------------------------\n   The ON control carries the primary pair: the switch's TRACK turns primary\n   with a primary-foreground knob, the checkbox face and the radio's selected\n   ring do the same. The select's pair themes the OPTION LIST's selected row\n   with the accent pair (shadcn's SelectItem selected state). These bake at\n   build time from :checked rules (a separate style bucket, like :pressed);\n   the device runtime swaps the pair onto the indicator when the value flips,\n   and the preview draws through the same fields. */\n.switch:checked {\n  background: var(--primary);\n  border-color: var(--primary);\n  color: var(--primary-foreground);\n}\ncheck:checked {\n  background: var(--primary);\n  color: var(--primary-foreground);\n}\nradio:checked {\n  background: var(--primary);\n  color: var(--primary-foreground);\n}\n.select:checked {\n  background: var(--accent);\n  color: var(--accent-foreground);\n}\n\n/* ---- Form validation states -------------------------------------------------- */\n\n/* Static hook: always-invalid styling for hardcoded markup. Runtime-driven\n   validation (recommended) binds the input's borderColor + a .field-error\n   hint's visible/text to a signal \u2014 see the demo's Forms screen. */\n.input-error {\n  border-color: var(--destructive);\n}\n.field-error {\n  color: var(--destructive);\n  font-size: 12px;\n}\n.field-success {\n  color: var(--muted-foreground);\n  font-size: 12px;\n}\n\n/* ---- Separator ---------------------------------------------------------------- */\n\n.separator {\n  height: 1px;\n  background: var(--border);\n  margin: 8px 0;\n}\n/* Vertical: 1px wide, stretches to the row's cross height (shadcn's\n   <Separator orientation=\"vertical\" /> \u2014 flex column + align-self: stretch). */\n.vseparator {\n  width: 1px;\n  height: 100%;\n  align-self: stretch;\n  background: var(--border);\n  margin: 0 8px;\n}\n\n/* ---- Alert -------------------------------------------------------------------- */\n\n.alert {\n  background: var(--background);\n  color: var(--foreground);\n  border: 1px solid var(--border);\n  border-radius: var(--radius);\n  padding: 12px;\n  gap: 4px;\n  align-self: stretch;\n}\n.alert-destructive {\n  background: var(--destructive-background);\n  border: 1px solid var(--destructive);\n  color: var(--destructive);\n}\n.alert-title { font-weight: bold; }\n.alert-description { font-size: 14px; color: var(--muted-foreground); }\n\n/* ---- Skeleton (loading placeholder) --------------------------------------------- */\n\n/* Opacity pulse. If the target display's keyframe support skips opacity,\n   the block still renders as a static muted placeholder. */\n.skeleton {\n  background: var(--muted);\n  border-radius: var(--radius);\n  height: 16px;\n  align-self: stretch;\n  animation: ui-skeleton-pulse 1.2s ease-in-out infinite;\n}\n@keyframes ui-skeleton-pulse {\n  0% { opacity: 1; }\n  50% { opacity: 0.55; }\n  100% { opacity: 1; }\n}\n\n/* ---- Spinner ---------------------------------------------------------------- */\n\n/* Indeterminate loading indicator: a dot orbiting inside a ring, pure\n   transform keyframes. translate() lerps CONTINUOUSLY between stops (unlike\n   rotate(), which only renders exact quarter turns), so the orbit is smooth.\n   The dot is absolute + out of flow; the ring is a fixed square so border\n   clipping stays symmetric. Sizes: change .spinner's width/height and keep\n   the dot inset consistent (orbit travel = inner - dot). */\n.spinner {\n  position: relative;\n  width: 22px;\n  height: 22px;\n  border: 2px solid var(--muted);\n  border-radius: 999px;\n}\n.spinner-dot {\n  position: absolute;\n  /* The dot's BASE position is the orbit's TOP-LEFT corner, not the ring\n     center: the keyframes translate 0..8px from here, and the path only\n     centers when base + travel/2 == ring center (with the 2px border,\n     top/left 2px + border lands the 6px dot at 4,4; its center travels\n     7..15 around the 22px ring's center at 11,11). */\n  top: 2px;\n  left: 2px;\n  width: 6px;\n  height: 6px;\n  background: var(--primary);\n  border-radius: 999px;\n  animation: ui-spinner-orbit 1000ms linear infinite;\n}\n@keyframes ui-spinner-orbit {\n  0%   { transform: translate(0px, 0px); }\n  25%  { transform: translate(8px, 0px); }\n  50%  { transform: translate(8px, 8px); }\n  75%  { transform: translate(0px, 8px); }\n  100% { transform: translate(0px, 0px); }\n}\n/* ---- Dialog ---------------------------------------------------------------- */\n\n/* Centered modal: <dialog> is a centered drawer (side-free) \u2014 programmatic\n   open/close via ui.dialog.open(id)/close(id?), hidden while closed by the\n   runtime (visibility gate for centered panels; offsets can't hide them).\n   The scrim is part of the markup: an absolute full-area view whose tap\n   closes the dialog; the card sits above it. z-index keeps both over page\n   content. */\n.dialog-scrim {\n  position: absolute;\n  left: 0;\n  right: 0;\n  top: 0;\n  bottom: 0;\n  background: var(--scrim);\n  z-index: 30;\n}\n.dialog-card {\n  position: absolute;\n  left: 24px;\n  right: 24px;\n  top: 64px;\n  background: var(--card);\n  color: var(--card-foreground);\n  border: 1px solid var(--border);\n  border-radius: var(--radius);\n  box-shadow: var(--shadow-lg);\n  padding: 16px;\n  gap: 8px;\n  z-index: 31;\n}\n.dialog-footer {\n  flex-direction: row;\n  justify-content: flex-end;\n  gap: 8px;\n}\n\n/* ---- Toast ----------------------------------------------------------------- */\n\n/* Transient notification: <toast side=\"bottom\" duration=\"2500\"> slides from\n   the bottom edge (author-positioned, flush to the edge so the slide fully\n   hides it) and auto-closes after duration ms. Show with ui.toast(id).\n   Sibling toasts stack by author layout; each closes on its own timer. */\n.toast {\n  position: absolute;\n  left: 12px;\n  right: 12px;\n  bottom: 0;\n  background: var(--foreground);\n  color: var(--background);\n  border-radius: var(--radius);\n  padding: 12px;\n  gap: 4px;\n  z-index: 40;\n}\n.toast-title { font-weight: bold; font-size: 14px; }\n.toast-description { font-size: 12px; color: var(--muted-foreground); }\n\n\n\n/* ---- Progress / Avatar ----------------------------------------------------------- */\n\n.progress {\n  height: 12px;\n  border-radius: 999px;\n  background: var(--secondary);\n  border: 1px solid var(--border);\n  color: var(--primary);\n}\n/* Avatar: plain image element. The runtime draws images rectangular \u2014 no\n   rounded clipping \u2014 so no border/radius here (a border would just draw\n   over the image). Wrap in a sized view if you want a frame. */\n";