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

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

@@ -1,121 +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);
-  // 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).`;
-}
+// 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/dirty-scroll-mutators.ts

@@ -1,188 +1,188 @@
-// Slice of the C++ runtime header (original source lines 1548-1710).
-// mark_dirty, subtree dirty, scroll direct prepare/compositor, scroll view dirty/overlap/invalidate.
-// See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
-export function emitDirtyScrollMutators(): string {
-  return `
-static inline void ui_mark_dirty(uint16_t nodeIdx) {
-  if (nodeIdx >= __ui_node_count) return;
-  __ui_nodes[nodeIdx].dirty = 1;
-  if (ui_is_effectively_visible(nodeIdx) &&
-      __ui_nodes[nodeIdx].screenId == __ui_active_screen) {
-    UIRect r;
-    ui_node_current_paint_rect(nodeIdx, &r);
-    if (r.w <= 0 || r.h <= 0) {
-      ui_mark_overlapping_higher_layers_dirty(nodeIdx);
-      return;
-    }
-    uint16_t p = __ui_nodes[nodeIdx].parent;
-    while (p != UI_NO_PARENT && p < __ui_node_count) {
-      if (__ui_nodes[p].scrollable &&
-          !__ui_nodes[p].virtualized &&
-          __ui_nodes[p].contentHeight > __ui_nodes[p].box.h) {
-        UIRect clip = {
-          __ui_nodes[p].box.x,
-          __ui_nodes[p].box.y,
-          __ui_nodes[p].box.w,
-          __ui_nodes[p].box.h
-        };
-        if (!ui_rects_intersect(r.x, r.y, r.w, r.h, clip.x, clip.y, clip.w, clip.h)) {
-          __ui_nodes[nodeIdx].dirty = 0;
-          return;
-        }
-        if (r.x < clip.x ||
-            r.x + r.w > clip.x + clip.w ||
-            r.y < clip.y ||
-            r.y + r.h > clip.y + clip.h) {
-          ui_mark_scroll_view_dirty(p);
-          return;
-        }
-        // Fully inside the viewport: leave the CHILD dirty. The dirty loop's
-        // scroll defer lets fully-contained children repaint through their own
-        // buffered paint (one atomic push; the retained scroll canvas is
-        // invalidated after the draw). Promoting here recomposed the whole
-        // viewport per dirty tick — fine for a rare :pressed button, but with
-        // keyframe animations marking children (and their overlapping higher
-        // layers) at frame rate it turned every animation frame into a
-        // full-viewport canvas push — constant tearing on no-TE SPI panels.
-      }
-      p = __ui_nodes[p].parent;
-    }
-  }
-  ui_mark_overlapping_higher_layers_dirty(nodeIdx);
-}
-
-// Set dirty=1 across a scroll subtree WITHOUT the per-child O(n) overlap repair.
-// During scroll the subtree repaints into a freshly-cleared off-screen canvas, so
-// intra-subtree overlap repair is pointless, and scroll children are draw-clipped
-// to the container's viewport box — so all external higher-z neighbors of the
-// viewport are covered by ONE overlap check at the container's paint rect (done by
-// the caller). This drops scroll marking from O(K·n) to O(K + n).
-static inline void ui_mark_subtree_dirty_local(uint16_t scrollNode) {
-  if (scrollNode >= __ui_node_count) return;
-  for (uint16_t c = scrollNode + 1; c < __ui_nodes[scrollNode].subtreeEnd; c++) {
-    __ui_nodes[c].dirty = 1;
-  }
-  __ui_nodes[scrollNode].dirty = 1;
-}
-
-// Mode C strip-only: direct-partial scroll when no viewport canvas fits and the
-// scroll delta is small. Fills only the exposed strip on the display, then marks
-// only the descendants that intersect that strip dirty for direct draw — mirroring
-// the Mode B canvas repair path. Never clears the whole viewport, and never marks
-// the whole subtree dirty (AGENTS.md: keep scroll drag invalidation small — a
-// 1-pixel drag must not repaint every visible child).
-static inline void ui_scroll_direct_prepare(uint16_t s, int16_t* outVX, int16_t* outVY) {
-  int16_t vw = __ui_nodes[s].box.w;
-  int16_t vh = __ui_nodes[s].box.h;
-  int16_t vox = __ui_nodes[s].box.x;
-  int16_t voy = __ui_nodes[s].box.y;
-  UI_COLOR_T scrollBg = __ui_nodes[s].hasBg ? __ui_nodes[s].bg : __ui_nodes[s].clearColor;
-  int16_t deltaY = __ui_nodes[s].scrollY - __ui_nodes[s].lastPaintedScrollY;
-  int16_t absDelta = deltaY < 0 ? -deltaY : deltaY;
-  int16_t stripY = deltaY > 0 ? static_cast<int16_t>(vh - absDelta) : 0;
-  ui_display_fill_rect(vox, static_cast<int16_t>(voy + stripY), vw, absDelta, scrollBg);
-  // Only descendants whose paint rect intersects the exposed strip need
-  // repainting; the rest keep their last-painted pixels (the strip background
-  // fill already covered the vacated band). Clear stale dirty flags on the
-  // others so a flag set by a prior frame (or a sibling promotion) doesn't
-  // trigger a needless repaint.
-  UIRect exposed = { vox, static_cast<int16_t>(voy + stripY), vw, absDelta };
-  for (uint16_t c = s + 1; c < __ui_nodes[s].subtreeEnd; c++) {
-    if (!ui_is_effectively_visible(c) || __ui_nodes[c].screenId != __ui_active_screen) {
-      __ui_nodes[c].dirty = 0;
-      continue;
-    }
-    UIRect cr;
-    ui_node_current_paint_rect(c, &cr);
-    if (cr.w > 0 && cr.h > 0 &&
-        ui_rects_intersect(cr.x, cr.y, cr.w, cr.h, exposed.x, exposed.y, exposed.w, exposed.h)) {
-      __ui_nodes[c].dirty = 1;
-      if (__ui_nodes[c].kind == NODE_PROGRESS || __ui_nodes[c].kind == NODE_RANGE) {
-        __ui_nodes[c].lastTextWidth = -1;
-      }
-      __ui_nodes[c].lastTextHeight = 0;
-    } else {
-      __ui_nodes[c].dirty = 0;
-    }
-  }
-  __ui_nodes[s].dirty = 0;
-  if (outVX) *outVX = vox;
-  if (outVY) *outVY = voy;
-}
-
-// Nearest overflow scroll container owning nodeIdx (or nodeIdx itself).
-static inline int16_t ui_overflow_scroll_compositor(uint16_t nodeIdx) {
-  if (nodeIdx >= __ui_node_count) return -1;
-  if (__ui_nodes[nodeIdx].scrollable && !__ui_nodes[nodeIdx].virtualized &&
-      __ui_nodes[nodeIdx].contentHeight > __ui_nodes[nodeIdx].box.h) {
-    return static_cast<int16_t>(nodeIdx);
-  }
-  uint16_t p = __ui_nodes[nodeIdx].parent;
-  while (p != UI_NO_PARENT && p < __ui_node_count) {
-    if (__ui_nodes[p].scrollable && !__ui_nodes[p].virtualized &&
-        __ui_nodes[p].contentHeight > __ui_nodes[p].box.h) {
-      return static_cast<int16_t>(p);
-    }
-    p = __ui_nodes[p].parent;
-  }
-  return -1;
-}
-
-static inline void ui_mark_scroll_view_overlaps_dirty(uint16_t scrollNode) {
-  if (scrollNode >= __ui_node_count) return;
-  if (!ui_is_effectively_visible(scrollNode)) return;
-  if (__ui_nodes[scrollNode].screenId != __ui_active_screen) return;
-  UIRect r;
-  ui_node_current_paint_rect(scrollNode, &r);
-  if (r.w <= 0 || r.h <= 0) return;
-  for (uint16_t c = 0; c < __ui_node_count; c++) {
-    if (c == scrollNode) continue;
-    if (c > scrollNode && c < __ui_nodes[scrollNode].subtreeEnd) continue;
-    if (__ui_nodes[c].dirty) continue;
-    if (!ui_is_effectively_visible(c)) continue;
-    if (__ui_nodes[c].screenId != __ui_active_screen) continue;
-    if (!ui_node_draws_before(scrollNode, c)) continue;
-    UIRect cr;
-    ui_node_current_paint_rect(c, &cr);
-    if (cr.w <= 0 || cr.h <= 0) continue;
-    if (ui_rects_intersect(r.x, r.y, r.w, r.h, cr.x, cr.y, cr.w, cr.h)) {
-      __ui_nodes[c].dirty = 1;
-    }
-  }
-}
-
-static inline void ui_mark_scroll_subtree_dirty(uint16_t scrollNode) {
-  ui_mark_subtree_dirty_local(scrollNode);
-  // Single overlap check at the container's paint rect covers every external
-  // higher-z neighbor of the viewport. The container index is the right one to
-  // pass: scroll content lives within the container's stacking context, so
-  // ui_node_draws_before(scrollNode, c) selects exactly the external layers that
-  // should be repaired when the viewport is repainted.
-  ui_mark_overlapping_higher_layers_dirty(scrollNode);
-}
-
-static inline void ui_mark_scroll_view_dirty(uint16_t scrollNode) {
-  if (scrollNode >= __ui_node_count) return;
-  __ui_nodes[scrollNode].dirty = 1;
-  ui_mark_scroll_view_overlaps_dirty(scrollNode);
-}
-
-static inline int16_t ui_scroll_ancestor_for_node(uint16_t nodeIdx) {
-  uint16_t p = __ui_nodes[nodeIdx].parent;
-  while (p != UI_NO_PARENT && p < __ui_node_count) {
-    if (__ui_nodes[p].scrollable) return static_cast<int16_t>(p);
-    p = __ui_nodes[p].parent;
-  }
-  return -1;
-}
-
-static inline void ui_invalidate_scroll_canvas_for_node(uint16_t nodeIdx) {
-  int16_t scrollParent = ui_scroll_ancestor_for_node(nodeIdx);
-  if (scrollParent < 0) return;
-  if (__ui_nodes[scrollParent].virtualized) return;
-  if (__ui_nodes[scrollParent].contentHeight <= __ui_nodes[scrollParent].box.h) return;
-  int16_t span = __ui_nodes[scrollParent].box.h > 0 ? __ui_nodes[scrollParent].box.h : 1;
-  __ui_nodes[scrollParent].lastPaintedScrollY = __ui_nodes[scrollParent].scrollY - span;
-}
-`;
-}
+// Slice of the C++ runtime header (original source lines 1548-1710).
+// mark_dirty, subtree dirty, scroll direct prepare/compositor, scroll view dirty/overlap/invalidate.
+// See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
+export function emitDirtyScrollMutators(): string {
+  return `
+static inline void ui_mark_dirty(uint16_t nodeIdx) {
+  if (nodeIdx >= __ui_node_count) return;
+  __ui_nodes[nodeIdx].dirty = 1;
+  if (ui_is_effectively_visible(nodeIdx) &&
+      __ui_nodes[nodeIdx].screenId == __ui_active_screen) {
+    UIRect r;
+    ui_node_current_paint_rect(nodeIdx, &r);
+    if (r.w <= 0 || r.h <= 0) {
+      ui_mark_overlapping_higher_layers_dirty(nodeIdx);
+      return;
+    }
+    uint16_t p = __ui_nodes[nodeIdx].parent;
+    while (p != UI_NO_PARENT && p < __ui_node_count) {
+      if (__ui_nodes[p].scrollable &&
+          !__ui_nodes[p].virtualized &&
+          __ui_nodes[p].contentHeight > __ui_nodes[p].box.h) {
+        UIRect clip = {
+          __ui_nodes[p].box.x,
+          __ui_nodes[p].box.y,
+          __ui_nodes[p].box.w,
+          __ui_nodes[p].box.h
+        };
+        if (!ui_rects_intersect(r.x, r.y, r.w, r.h, clip.x, clip.y, clip.w, clip.h)) {
+          __ui_nodes[nodeIdx].dirty = 0;
+          return;
+        }
+        if (r.x < clip.x ||
+            r.x + r.w > clip.x + clip.w ||
+            r.y < clip.y ||
+            r.y + r.h > clip.y + clip.h) {
+          ui_mark_scroll_view_dirty(p);
+          return;
+        }
+        // Fully inside the viewport: leave the CHILD dirty. The dirty loop's
+        // scroll defer lets fully-contained children repaint through their own
+        // buffered paint (one atomic push; the retained scroll canvas is
+        // invalidated after the draw). Promoting here recomposed the whole
+        // viewport per dirty tick — fine for a rare :pressed button, but with
+        // keyframe animations marking children (and their overlapping higher
+        // layers) at frame rate it turned every animation frame into a
+        // full-viewport canvas push — constant tearing on no-TE SPI panels.
+      }
+      p = __ui_nodes[p].parent;
+    }
+  }
+  ui_mark_overlapping_higher_layers_dirty(nodeIdx);
+}
+
+// Set dirty=1 across a scroll subtree WITHOUT the per-child O(n) overlap repair.
+// During scroll the subtree repaints into a freshly-cleared off-screen canvas, so
+// intra-subtree overlap repair is pointless, and scroll children are draw-clipped
+// to the container's viewport box — so all external higher-z neighbors of the
+// viewport are covered by ONE overlap check at the container's paint rect (done by
+// the caller). This drops scroll marking from O(K·n) to O(K + n).
+static inline void ui_mark_subtree_dirty_local(uint16_t scrollNode) {
+  if (scrollNode >= __ui_node_count) return;
+  for (uint16_t c = scrollNode + 1; c < __ui_nodes[scrollNode].subtreeEnd; c++) {
+    __ui_nodes[c].dirty = 1;
+  }
+  __ui_nodes[scrollNode].dirty = 1;
+}
+
+// Mode C strip-only: direct-partial scroll when no viewport canvas fits and the
+// scroll delta is small. Fills only the exposed strip on the display, then marks
+// only the descendants that intersect that strip dirty for direct draw — mirroring
+// the Mode B canvas repair path. Never clears the whole viewport, and never marks
+// the whole subtree dirty (AGENTS.md: keep scroll drag invalidation small — a
+// 1-pixel drag must not repaint every visible child).
+static inline void ui_scroll_direct_prepare(uint16_t s, int16_t* outVX, int16_t* outVY) {
+  int16_t vw = __ui_nodes[s].box.w;
+  int16_t vh = __ui_nodes[s].box.h;
+  int16_t vox = __ui_nodes[s].box.x;
+  int16_t voy = __ui_nodes[s].box.y;
+  UI_COLOR_T scrollBg = __ui_nodes[s].hasBg ? __ui_nodes[s].bg : __ui_nodes[s].clearColor;
+  int16_t deltaY = __ui_nodes[s].scrollY - __ui_nodes[s].lastPaintedScrollY;
+  int16_t absDelta = deltaY < 0 ? -deltaY : deltaY;
+  int16_t stripY = deltaY > 0 ? static_cast<int16_t>(vh - absDelta) : 0;
+  ui_display_fill_rect(vox, static_cast<int16_t>(voy + stripY), vw, absDelta, scrollBg);
+  // Only descendants whose paint rect intersects the exposed strip need
+  // repainting; the rest keep their last-painted pixels (the strip background
+  // fill already covered the vacated band). Clear stale dirty flags on the
+  // others so a flag set by a prior frame (or a sibling promotion) doesn't
+  // trigger a needless repaint.
+  UIRect exposed = { vox, static_cast<int16_t>(voy + stripY), vw, absDelta };
+  for (uint16_t c = s + 1; c < __ui_nodes[s].subtreeEnd; c++) {
+    if (!ui_is_effectively_visible(c) || __ui_nodes[c].screenId != __ui_active_screen) {
+      __ui_nodes[c].dirty = 0;
+      continue;
+    }
+    UIRect cr;
+    ui_node_current_paint_rect(c, &cr);
+    if (cr.w > 0 && cr.h > 0 &&
+        ui_rects_intersect(cr.x, cr.y, cr.w, cr.h, exposed.x, exposed.y, exposed.w, exposed.h)) {
+      __ui_nodes[c].dirty = 1;
+      if (__ui_nodes[c].kind == NODE_PROGRESS || __ui_nodes[c].kind == NODE_RANGE) {
+        __ui_nodes[c].lastTextWidth = -1;
+      }
+      __ui_nodes[c].lastTextHeight = 0;
+    } else {
+      __ui_nodes[c].dirty = 0;
+    }
+  }
+  __ui_nodes[s].dirty = 0;
+  if (outVX) *outVX = vox;
+  if (outVY) *outVY = voy;
+}
+
+// Nearest overflow scroll container owning nodeIdx (or nodeIdx itself).
+static inline int16_t ui_overflow_scroll_compositor(uint16_t nodeIdx) {
+  if (nodeIdx >= __ui_node_count) return -1;
+  if (__ui_nodes[nodeIdx].scrollable && !__ui_nodes[nodeIdx].virtualized &&
+      __ui_nodes[nodeIdx].contentHeight > __ui_nodes[nodeIdx].box.h) {
+    return static_cast<int16_t>(nodeIdx);
+  }
+  uint16_t p = __ui_nodes[nodeIdx].parent;
+  while (p != UI_NO_PARENT && p < __ui_node_count) {
+    if (__ui_nodes[p].scrollable && !__ui_nodes[p].virtualized &&
+        __ui_nodes[p].contentHeight > __ui_nodes[p].box.h) {
+      return static_cast<int16_t>(p);
+    }
+    p = __ui_nodes[p].parent;
+  }
+  return -1;
+}
+
+static inline void ui_mark_scroll_view_overlaps_dirty(uint16_t scrollNode) {
+  if (scrollNode >= __ui_node_count) return;
+  if (!ui_is_effectively_visible(scrollNode)) return;
+  if (__ui_nodes[scrollNode].screenId != __ui_active_screen) return;
+  UIRect r;
+  ui_node_current_paint_rect(scrollNode, &r);
+  if (r.w <= 0 || r.h <= 0) return;
+  for (uint16_t c = 0; c < __ui_node_count; c++) {
+    if (c == scrollNode) continue;
+    if (c > scrollNode && c < __ui_nodes[scrollNode].subtreeEnd) continue;
+    if (__ui_nodes[c].dirty) continue;
+    if (!ui_is_effectively_visible(c)) continue;
+    if (__ui_nodes[c].screenId != __ui_active_screen) continue;
+    if (!ui_node_draws_before(scrollNode, c)) continue;
+    UIRect cr;
+    ui_node_current_paint_rect(c, &cr);
+    if (cr.w <= 0 || cr.h <= 0) continue;
+    if (ui_rects_intersect(r.x, r.y, r.w, r.h, cr.x, cr.y, cr.w, cr.h)) {
+      __ui_nodes[c].dirty = 1;
+    }
+  }
+}
+
+static inline void ui_mark_scroll_subtree_dirty(uint16_t scrollNode) {
+  ui_mark_subtree_dirty_local(scrollNode);
+  // Single overlap check at the container's paint rect covers every external
+  // higher-z neighbor of the viewport. The container index is the right one to
+  // pass: scroll content lives within the container's stacking context, so
+  // ui_node_draws_before(scrollNode, c) selects exactly the external layers that
+  // should be repaired when the viewport is repainted.
+  ui_mark_overlapping_higher_layers_dirty(scrollNode);
+}
+
+static inline void ui_mark_scroll_view_dirty(uint16_t scrollNode) {
+  if (scrollNode >= __ui_node_count) return;
+  __ui_nodes[scrollNode].dirty = 1;
+  ui_mark_scroll_view_overlaps_dirty(scrollNode);
+}
+
+static inline int16_t ui_scroll_ancestor_for_node(uint16_t nodeIdx) {
+  uint16_t p = __ui_nodes[nodeIdx].parent;
+  while (p != UI_NO_PARENT && p < __ui_node_count) {
+    if (__ui_nodes[p].scrollable) return static_cast<int16_t>(p);
+    p = __ui_nodes[p].parent;
+  }
+  return -1;
+}
+
+static inline void ui_invalidate_scroll_canvas_for_node(uint16_t nodeIdx) {
+  int16_t scrollParent = ui_scroll_ancestor_for_node(nodeIdx);
+  if (scrollParent < 0) return;
+  if (__ui_nodes[scrollParent].virtualized) return;
+  if (__ui_nodes[scrollParent].contentHeight <= __ui_nodes[scrollParent].box.h) return;
+  int16_t span = __ui_nodes[scrollParent].box.h > 0 ? __ui_nodes[scrollParent].box.h : 1;
+  __ui_nodes[scrollParent].lastPaintedScrollY = __ui_nodes[scrollParent].scrollY - span;
+}
+`;
+}