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

package/src/ui-engine/runtime-header/tick/scroll-canvas-phase.ts

@@ -1,31 +1,30 @@
-// Slice of the C++ runtime header (original source lines 5279-5287).
-// scrollbar + buffered scroll canvas push.
-// See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
-export function emitTickScrollCanvasPhase(): string {
-  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;`;
-}
+// Slice of the C++ runtime header (original source lines 5279-5287).
+// scrollbar + buffered scroll canvas push.
+// See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
+export function emitTickScrollCanvasPhase(): string {
+  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/src/ui-engine/runtime-header/touch-keyboard-fwd.ts

@@ -3,6 +3,7 @@
 // See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
 export function emitTouchKeyboardFwd(): string {
   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/src/ui-engine/runtime-header/types-defines.ts

@@ -1,99 +1,116 @@
-// Slice of the C++ runtime header (original source lines 17-89).
-// Guard open, includes, and #define knobs.
-// See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
-export function emitTypesDefines(): string {
-  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
-`;
-}
+// Slice of the C++ runtime header (original source lines 17-89).
+// Guard open, includes, and #define knobs.
+// See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
+export function emitTypesDefines(): string {
+  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
+`;
+}