@typecad/ui 0.1.0-alpha.1

package/src/ui-engine/rich-layout.ts

@@ -0,0 +1,257 @@
+import { whiteSpaceMode, WhiteSpaceMode } from "./text-layout.js";
+
+export interface RichSegment {
+  /** Index into the source runs[] this segment came from. A run that wraps
+   *  across multiple lines produces one segment per line, all with the same
+   *  runIndex. */
+  runIndex: number;
+  text: string;
+  /** Offset from the line's left edge (pre-alignment). */
+  x: number;
+  width: number;
+}
+export interface RichLine {
+  segments: RichSegment[];
+  /** Sum of segment widths + inter-word spaces on this line (no trailing space). */
+  width: number;
+  /** Tallest run height on this line. */
+  height: number;
+  /** Tallest ascent on this line (for baseline alignment). */
+  ascent: number;
+}
+export interface RichLayoutResult {
+  lines: RichLine[];
+  /** Max line width. */
+  width: number;
+  /** Sum of line heights. */
+  height: number;
+}
+
+export interface LayoutRun {
+  text: string;
+  hardBreak?: boolean;
+  /** Measure a string at THIS run's style (font/size advance). */
+  measureText: (s: string) => number;
+  /** Rendered content height of this run's font (e.g. 8*textSize). */
+  height: number;
+  /** Ascent of this run's font (e.g. 7*textSize). */
+  ascent: number;
+}
+
+/** Greedy multi-run wrapper. Generalizes the single-string wrap to a sequence
+ *  of styled runs: each candidate is measured with its OWN measureText, breaks
+ *  happen at spaces and at run boundaries, and per-segment geometry is recorded
+ *  so the draw layer and link hit-test know where each run sits on each line.
+ *
+ *  Whitespace handling mirrors text-layout.ts: `normal` collapses runs of
+ *  whitespace and wraps on word boundaries; `nowrap` keeps one line; `pre`
+ *  preserves whitespace and breaks only on hard breaks/newlines; `pre-line`
+ *  collapses spaces but keeps newlines. Per-run text is normalized within the
+ *  run; a space straddling a run boundary collapses to one (owned by the
+ *  earlier run). */
+export function layoutRuns(
+  runs: LayoutRun[],
+  options: { maxWidth?: number; whiteSpace?: string },
+): RichLayoutResult {
+  const mode = whiteSpaceMode(options.whiteSpace);
+  const maxWidth = options.maxWidth && options.maxWidth > 0 ? Math.trunc(options.maxWidth) : undefined;
+  const canWrap = mode !== "nowrap" && mode !== "pre" && maxWidth !== undefined;
+
+  // Tokenize each run into words (split on spaces), preserving which run + the
+  // run's measure function. Each word carries `spaceBefore`: true when source
+  // whitespace preceded it (within the run, or trailing whitespace of the
+  // previous run before this run's first word). This keeps placement faithful
+  // to source whitespace — adjacent runs with no whitespace between them join
+  // with no separator.
+  type Word = { runIndex: number; text: string; mt: (s: string) => number; h: number; a: number; spaceBefore: boolean };
+  type Break = { runIndex: number; mt: (s: string) => number; h: number; a: number };
+  type Token = { kind: "word"; w: Word } | { kind: "break"; b: Break };
+  const tokens: Token[] = [];
+  let prevRunTrailingSpace = false;  // did the previous run's text end with whitespace?
+  runs.forEach((run, runIndex) => {
+    if (run.hardBreak) {
+      tokens.push({ kind: "break", b: { runIndex, mt: run.measureText, h: run.height, a: run.ascent } });
+      prevRunTrailingSpace = false;
+      return;
+    }
+    const text = normalizeRunText(run.text, mode);
+    const leadingSpace = /^\s/.test(run.text);
+    if (mode === "pre") {
+      // Preserve internal newlines as hard breaks; keep text segments between.
+      const parts = text.split("\n");
+      parts.forEach((part, i) => {
+        if (part) tokens.push({ kind: "word", w: { runIndex, text: part, mt: run.measureText, h: run.height, a: run.ascent, spaceBefore: i === 0 ? (leadingSpace || prevRunTrailingSpace) : false } });
+        if (i < parts.length - 1) tokens.push({ kind: "break", b: { runIndex, mt: run.measureText, h: run.height, a: run.ascent } });
+      });
+      prevRunTrailingSpace = /\s$/.test(text);
+      return;
+    }
+    // normal / nowrap / pre-line: split on whitespace runs into words.
+    const words = text.split(/\s+/).filter(Boolean);
+    words.forEach((w, i) => {
+      // Internal words (i > 0) had whitespace before them within the run.
+      // The first word (i === 0) has a space before only if the run's text
+      // started with whitespace OR the previous run ended with whitespace.
+      const spaceBefore = i > 0 ? true : (leadingSpace || prevRunTrailingSpace);
+      tokens.push({ kind: "word", w: { runIndex, text: w, mt: run.measureText, h: run.height, a: run.ascent, spaceBefore } });
+    });
+    prevRunTrailingSpace = /\s$/.test(run.text);
+  });
+
+  const lines: RichLine[] = [];
+  // Current line state.
+  let segs: RichSegment[] = [];
+  let lineW = 0;
+  let lineH = 0;
+  let lineA = 0;
+  // Current in-progress segment for a run (accumulating words of the same run
+  // on the current line, joined by spaces).
+  let cur: { runIndex: number; text: string; mt: (s: string) => number; h: number; a: number } | null = null;
+
+  const flushCurrent = () => {
+    if (cur) {
+      segs.push({ runIndex: cur.runIndex, text: cur.text, x: lineW, width: cur.mt(cur.text) });
+      lineW += cur.mt(cur.text);
+      cur = null;
+    }
+  };
+  const commitLine = (minHeight = 0, minAscent = 0) => {
+    flushCurrent();
+    lineH = Math.max(lineH, minHeight);
+    lineA = Math.max(lineA, minAscent);
+    lines.push({ segments: segs, width: lineW, height: lineH, ascent: lineA });
+    segs = [];
+    lineW = 0;
+    lineH = 0;
+    lineA = 0;
+  };
+
+  for (const tok of tokens) {
+    if (tok.kind === "break") {
+      commitLine(tok.b.h, tok.b.a);
+      continue;
+    }
+    const word = tok.w;
+    // A space precedes this word when the source had whitespace before it
+    // (word.spaceBefore) AND we're not at the very start of a line (standard
+    // whitespace collapsing trims a leading space on a fresh line). The space
+    // is measured with the run that owns the word being added.
+    const atLineStart = cur === null && lineW === 0;
+    const wantSpace = word.spaceBefore && !atLineStart;
+    const sameRun = cur !== null && cur.runIndex === word.runIndex;
+
+    if (sameRun) {
+      // Extending the current segment: "cur word" (space included only if wanted).
+      if (wantSpace) {
+        const candidate = cur!.text + " " + word.text;
+        // lineW holds only committed/flushed width + separator spaces; the
+        // in-progress segment `cur` is NOT yet in lineW (only flushCurrent
+        // adds it). So the true line width after extending cur is lineW plus
+        // the candidate's full width — not lineW minus cur plus candidate
+        // (that would under-count by cur's width and fail to wrap intra-run).
+        const candidateW = lineW + cur!.mt(candidate);
+        if (canWrap && candidateW > maxWidth! && cur!.text) {
+          commitLine();
+          cur = { runIndex: word.runIndex, text: word.text, mt: word.mt, h: word.h, a: word.a };
+          lineH = word.h; lineA = word.a;
+        } else {
+          cur!.text = candidate;
+          lineH = Math.max(lineH, word.h);
+          lineA = Math.max(lineA, word.a);
+        }
+      } else {
+        // No space: append directly (adjacent words with no source whitespace).
+        const candidate = cur!.text + word.text;
+        const candidateW = lineW + cur!.mt(candidate);
+        if (canWrap && candidateW > maxWidth! && cur!.text) {
+          commitLine();
+          cur = { runIndex: word.runIndex, text: word.text, mt: word.mt, h: word.h, a: word.a };
+          lineH = word.h; lineA = word.a;
+        } else {
+          cur!.text = candidate;
+          lineH = Math.max(lineH, word.h);
+          lineA = Math.max(lineA, word.a);
+        }
+      }
+    } else {
+      // Different run (or first word on the line).
+      const spaceW = wantSpace ? word.mt(" ") : 0;
+      const wordW = word.mt(word.text);
+      if (cur) flushCurrent();
+      if (canWrap && lineW + spaceW + wordW > maxWidth! && lineW > 0) {
+        // Doesn't fit: wrap to a new line. (Space suppressed at line start.)
+        commitLine();
+        if (canWrap && wordW > maxWidth!) {
+          const parts = splitLongWord(word.text, maxWidth!, word.mt);
+          for (let i = 0; i < parts.length; i++) {
+            if (i < parts.length - 1) {
+              segs.push({ runIndex: word.runIndex, text: parts[i], x: 0, width: word.mt(parts[i]) });
+              lines.push({ segments: segs, width: word.mt(parts[i]), height: word.h, ascent: word.a });
+              segs = [];
+            } else {
+              cur = { runIndex: word.runIndex, text: parts[i], mt: word.mt, h: word.h, a: word.a };
+              lineW = 0;
+              lineH = word.h; lineA = word.a;
+            }
+          }
+        } else {
+          cur = { runIndex: word.runIndex, text: word.text, mt: word.mt, h: word.h, a: word.a };
+          lineH = word.h; lineA = word.a;
+        }
+      } else if (canWrap && wordW > maxWidth!) {
+        // Single word longer than the whole line: split char-by-char.
+        if (lineW > 0) commitLine();
+        const parts = splitLongWord(word.text, maxWidth!, word.mt);
+        for (let i = 0; i < parts.length; i++) {
+          if (i < parts.length - 1) {
+            segs.push({ runIndex: word.runIndex, text: parts[i], x: 0, width: word.mt(parts[i]) });
+            lines.push({ segments: segs, width: word.mt(parts[i]), height: word.h, ascent: word.a });
+            segs = [];
+          } else {
+            cur = { runIndex: word.runIndex, text: parts[i], mt: word.mt, h: word.h, a: word.a };
+            lineW = 0;
+            lineH = word.h; lineA = word.a;
+          }
+        }
+      } else {
+        // Place the separator space (advances lineW, not a segment) then start
+        // a new in-progress segment for this word.
+        lineW += spaceW;
+        cur = { runIndex: word.runIndex, text: word.text, mt: word.mt, h: word.h, a: word.a };
+        lineH = Math.max(lineH, word.h);
+        lineA = Math.max(lineA, word.a);
+      }
+    }
+  }
+  commitLine();
+
+  const width = lines.reduce((m, l) => Math.max(m, l.width), 0);
+  const height = lines.reduce((s, l) => s + l.height, 0);
+  return { lines, width, height };
+}
+
+/** Character-by-character break of a single word longer than maxWidth. Returns
+ *  the pieces (each <= maxWidth). Mirrors text-layout.ts splitLongWord but
+ *  returns plain strings (geometry computed by the caller). */
+function splitLongWord(word: string, maxWidth: number, mt: (s: string) => number): string[] {
+  const out: string[] = [];
+  let current = "";
+  for (const ch of word) {
+    const next = current + ch;
+    if (current && mt(next) > maxWidth) {
+      out.push(current);
+      current = ch;
+    } else {
+      current = next;
+    }
+  }
+  if (current) out.push(current);
+  return out;
+}
+
+function normalizeRunText(text: string, mode: WhiteSpaceMode): string {
+  const nl = text.replace(/\r\n?/g, "\n");
+  if (mode === "pre") return nl;
+  if (mode === "pre-line") return nl.replace(/[ \t\f\v]+/g, " ");
+  return nl.replace(/\s+/g, " ");
+}

package/src/ui-engine/run-types.ts

@@ -0,0 +1,14 @@
+import { CSSProperty } from "./css-parser.js";
+
+/** A resolver-side rich-text run: one piece of styled inline text within a
+ *  text node's `runs[]`. The run's `style` holds the inherited-or-overridden
+ *  keys; the parent text node's resolved style is the base, the inline
+ *  element's own matched rules and the styling-tag defaults layer on top. */
+export interface TextRun {
+  text: string;
+  style: Partial<CSSProperty>;
+  /** Resolved screen target if this run came from an <a href="#screenId">. */
+  href?: string;
+  /** <br> sentinel: forces a hard line break (no text rendered). */
+  hardBreak?: boolean;
+}

package/src/ui-engine/runtime-header/antialiasing.ts

@@ -0,0 +1,141 @@
+// Slice of the C++ runtime header (original source lines 5299-5433).
+// AA subsystem: begin/push/pixel/line/circle/fill.
+// See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
+export function emitAntialiasing(): string {
+  return `
+  ui_refresh_flush();
+}
+
+// ── Antialiasing subsystem (offscreen canvas + coverage blending) ──────────
+// Enabled via #define UI_AA 1 (from display profile antialias:true).
+// Shapes are rendered to a GFXcanvas16, edges blended via getPixel read-back,
+// then pushed to the display. The ILI9341 has no efficient SPI read-back, so
+// all blending happens in RAM.
+#ifdef UI_AA
+
+// Get (or allocate) a canvas sized to the element being drawn.
+static inline CuttlefishCanvas16* ui_aa_begin(int16_t w, int16_t h, UI_COLOR_T bg) {
+  if (w <= 0 || h <= 0) return nullptr;
+  if (!__ui_aa_canvas || display_canvasWidth(__ui_aa_canvas) < w || display_canvasHeight(__ui_aa_canvas) < h) {
+    display_deleteCanvas(__ui_aa_canvas);
+    __ui_aa_canvas = display_createCanvas(w > 0 ? w : 1, h > 0 ? h : 1);
+  }
+  if (!__ui_aa_canvas || !display_canvasBuffer(__ui_aa_canvas)) return nullptr;
+  display_canvasFillScreen(__ui_aa_canvas, bg);
+  return __ui_aa_canvas;
+ }
+
+// Push the canvas rect to the display at (dx, dy).
+static inline void ui_aa_push(CuttlefishCanvas16* c, int16_t dx, int16_t dy) {
+  if (!c || !display_canvasBuffer(c)) return;
+  int16_t w = display_canvasWidth(c), h = display_canvasHeight(c);
+  // Push via __ui_gfx so the AA output goes to the scroll canvas when active,
+  // or the display directly when not. Row-by-row drawRGBBitmap (no transparent
+  // alpha — the AA canvas already has the blended pixels).
+  for (int16_t row = 0; row < h; row++) {
+    ui_display_draw_rgb_bitmap(dx, dy + row, display_canvasBuffer(c) + (int32_t)row * w, w, 1);
+  }
+}
+
+// Blend a pixel at integer coords with a coverage fraction (0-255).
+static inline void ui_aa_pixel(CuttlefishCanvas16* c, int16_t x, int16_t y, UI_COLOR_T color, uint8_t cov) {
+  if (!c || !display_canvasBuffer(c)) return;
+  if (cov == 0) return;
+  if (x < 0 || y < 0 || x >= display_canvasWidth(c) || y >= display_canvasHeight(c)) return;
+  if (cov >= 255) { display_targetDrawPixel((CuttlefishDisplayTarget*)c, x, y, color); return; }
+  UI_COLOR_T bg = display_canvasGetPixel(c, x, y);
+  uint8_t op = (uint8_t)((uint16_t)cov * 100 / 255);
+  display_targetDrawPixel((CuttlefishDisplayTarget*)c, x, y, ui_blend(color, bg, op));
+}
+
+// Xiaolin Wu antialiased line. Coordinates are in canvas-local space.
+static inline void ui_aa_line(CuttlefishCanvas16* c, float x0, float y0, float x1, float y1, UI_COLOR_T color) {
+  if (!c || !display_canvasBuffer(c)) return;
+  auto ipart = [](float f) { return (int16_t)f; };
+  auto round_f = [](float f) { return (int16_t)(f + 0.5f); };
+  auto fpart = [](float f) { return f - (float)(int16_t)f; };
+  auto rfpart = [&](float f) { return 1.0f - fpart(f); };
+
+  bool steep = fabs(y1 - y0) > fabs(x1 - x0);
+  if (steep) { float t = x0; x0 = y0; y0 = t; t = x1; x1 = y1; y1 = t; }
+  if (x0 > x1) { float t = x0; x0 = x1; x1 = t; t = y0; y0 = y1; y1 = t; }
+
+  float dx = x1 - x0, dy = y1 - y0;
+  float gradient = (dx == 0) ? 1.0f : dy / dx;
+
+  int16_t xpx1 = round_f(x0);
+  float xend = x0 + 0.5f * (xpx1 - x0) * (xpx1 - x0 < 0 ? -1 : 0); // simplified
+  float intery = y0 + gradient * (xpx1 - x0);
+
+  for (int16_t x = xpx1; x <= ipart(x1); x++) {
+    if (steep) {
+      ui_aa_pixel(c, ipart(intery), x, color, (uint8_t)(rfpart(intery) * 255));
+      ui_aa_pixel(c, ipart(intery) + 1, x, color, (uint8_t)(fpart(intery) * 255));
+    } else {
+      ui_aa_pixel(c, x, ipart(intery), color, (uint8_t)(rfpart(intery) * 255));
+      ui_aa_pixel(c, x, ipart(intery) + 1, color, (uint8_t)(fpart(intery) * 255));
+    }
+    intery += gradient;
+  }
+}
+
+// Antialiased circle outline. cx,cy,r are in canvas-local space.
+static inline void ui_aa_circle(CuttlefishCanvas16* c, int16_t cx, int16_t cy, float r, UI_COLOR_T color) {
+  if (!c || !display_canvasBuffer(c)) return;
+  if (r <= 0) return;
+  // Walk each scanline from top to bottom of the bounding box.
+  int16_t y0 = (int16_t)floor(cy - r);
+  int16_t y1 = (int16_t)ceil(cy + r);
+  for (int16_t y = y0; y <= y1; y++) {
+    float dy = (float)y - cy;
+    float dx = r * r - dy * dy;
+    if (dx < 0) continue;
+    float halfW = sqrtf(dx);
+    float leftX = (float)cx - halfW;
+    float rightX = (float)cx + halfW;
+    // Left edge: blend two pixels at the coverage split.
+    int16_t lx = (int16_t)floor(leftX);
+    float lfrac = leftX - lx;
+    ui_aa_pixel(c, lx, y, color, (uint8_t)((1.0f - lfrac) * 255));
+    ui_aa_pixel(c, lx + 1, y, color, 0);  // interior starts here (drawn solid below)
+    // Right edge.
+    int16_t rx = (int16_t)floor(rightX);
+    float rfrac = rightX - rx;
+    ui_aa_pixel(c, rx, y, color, (uint8_t)(rfrac * 255));
+    ui_aa_pixel(c, rx + 1, y, color, 0);
+    // Solid fill between edges (skip the edge pixels already blended).
+    for (int16_t x = lx + 1; x < rx; x++) {
+      if (x >= 0 && x < display_canvasWidth(c)) display_targetDrawPixel((CuttlefishDisplayTarget*)c, x, y, color);
+    }
+  }
+}
+
+// Antialiased filled circle.
+static inline void ui_aa_fill_circle(CuttlefishCanvas16* c, int16_t cx, int16_t cy, float r, UI_COLOR_T color) {
+  if (!c || !display_canvasBuffer(c)) return;
+  if (r <= 0) return;
+  int16_t y0 = (int16_t)floor(cy - r);
+  int16_t y1 = (int16_t)ceil(cy + r);
+  for (int16_t y = y0; y <= y1; y++) {
+    float dy = (float)y - cy;
+    float dx = r * r - dy * dy;
+    if (dx < 0) continue;
+    float halfW = sqrtf(dx);
+    float leftX = (float)cx - halfW;
+    float rightX = (float)cx + halfW;
+    int16_t lx = (int16_t)floor(leftX);
+    int16_t rx = (int16_t)ceil(rightX);
+    // Blend left edge.
+    ui_aa_pixel(c, lx, y, color, (uint8_t)((1.0f - (leftX - lx)) * 255));
+    // Blend right edge.
+    ui_aa_pixel(c, rx, y, color, (uint8_t)((rightX - (rx - 1)) * 255));
+    // Solid interior.
+    for (int16_t x = lx + 1; x < rx; x++) {
+      if (x >= 0 && x < display_canvasWidth(c) && y >= 0 && y < display_canvasHeight(c)) display_targetDrawPixel((CuttlefishDisplayTarget*)c, x, y, color);
+    }
+  }
+}
+
+#endif // UI_AA
+`;
+}

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

@@ -0,0 +1,39 @@
+// Slice of the C++ runtime header (original source lines 2962-2994).
+// ui_blend565/ui_blend888 bodies. Tiny slice sitting between touch and text in source.
+// See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
+export function emitBlendBodies(): string {
+  return `
+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
+  // high bits), blend at 8-bit, then re-quantize to 565. This produces smoother
+  // 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)).
+  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 = (uint16_t)((fr8 * opacity + br8 * (100 - opacity)) / 100);
+  uint16_t g = (uint16_t)((fg8 * opacity + bg8 * (100 - opacity)) / 100);
+  uint16_t b = (uint16_t)((fb8 * opacity + bb8 * (100 - opacity)) / 100);
+  return ((r >> 3) << 11) | ((g >> 2) << 5) | (b >> 3);
+}
+
+// Blend two RGB888 colors by opacity (0-100). Added for Phase 2 (RGB888/RGB666
+// targets); unused in Phase 1, whose TFT path keeps 565 node values and blends
+// via ui_blend565 above. Kept alongside so the 888 path is ready when the
+// descriptor routes emit through resolveColor888.
+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;
+  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;
+  return ((uint32_t)r << 16) | ((uint32_t)g << 8) | b;
+}
+`;
+}

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

@@ -0,0 +1,155 @@
+// Slice of the C++ runtime header (original source lines 753-901).
+// Persistent canvas release/create/get/shift/repair/warn helpers.
+// See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
+export function emitCanvasHelpers(): string {
+  return `
+// heap. Called from ui_navigate. Safe with null pointers.
+static inline void ui_release_canvas_state() {
+  display_deleteCanvas(__ui_container_canvas); __ui_container_canvas = nullptr;
+  display_deleteCanvas(__ui_list_canvas);      __ui_list_canvas = nullptr;
+  __ui_list_canvas_node = -1;
+  display_deleteCanvas(__ui_node_canvas);      __ui_node_canvas = nullptr;
+  display_deleteCanvas(__ui_repair_canvas);    __ui_repair_canvas = nullptr;
+}
+
+// Lazily allocate/reuse a viewport-sized canvas for a scroll container. Resizes
+// when the container's box changes; returns null if allocation fails (caller
+// falls back to Mode C direct redraw). Only used on full render tiers.
+// Prefers PSRAM when available (ESP32 + BOARD_HAS_PSRAM + psramFound) so large
+// viewport canvases (e.g. 116KB+ for a full-width scroll region on a 480x320
+// panel) don't exhaust internal SRAM. Falls back to internal SRAM otherwise.
+static inline CuttlefishCanvas16* ui_create_canvas_best(int16_t w, int16_t h) {
+#if defined(ESP32) && defined(BOARD_HAS_PSRAM)
+  if (psramFound()) {
+    CuttlefishCanvas16* c = display_createCanvasPsram(w, h);
+    if (c && display_canvasBuffer(c)) return c;
+    // PSRAM allocation failed (rare — fragmented PSRAM) → fall through to SRAM.
+  }
+#endif
+  return display_createCanvas(w, h);
+}
+
+static inline CuttlefishCanvas16* ui_get_container_canvas(int16_t w, int16_t h) {
+  if (w <= 0 || h <= 0) return nullptr;
+  if (!__ui_container_canvas ||
+      display_canvasWidth(__ui_container_canvas) != w ||
+      display_canvasHeight(__ui_container_canvas) != h) {
+    display_deleteCanvas(__ui_container_canvas);
+    __ui_container_canvas = ui_create_canvas_best(w, h);
+  }
+  return (__ui_container_canvas && display_canvasBuffer(__ui_container_canvas))
+    ? __ui_container_canvas : nullptr;
+}
+
+// Defined after the node table by UI lowering (scroll overflow nodes with ids).
+static inline const char* __ui_scroll_node_id(uint16_t idx);
+
+// Emit a one-time Serial warning when scroll rendering cannot be accurate due
+// to heap limits. reason: 0=canvas alloc failed, 1=viewport exceeds budget,
+// 2=Mode C strip fallback (reduced accuracy).
+static inline void ui_warn_scroll_memory(uint16_t nodeIdx, uint8_t reason) {
+  if (nodeIdx >= __ui_node_count) return;
+  if (!__ui_scroll_mem_warned) return;
+  if (__ui_scroll_mem_warned[nodeIdx]) return;
+  __ui_scroll_mem_warned[nodeIdx] = 1;
+
+  int16_t vw = __ui_nodes[nodeIdx].box.w;
+  int16_t vh = __ui_nodes[nodeIdx].box.h;
+  uint32_t need = (uint32_t)(vw > 0 ? vw : 0) * (uint32_t)(vh > 0 ? vh : 0) * 2u;
+  const char* id = __ui_scroll_node_id(nodeIdx);
+  const char* label = (id && id[0]) ? id : "scroll viewport";
+  const char* reasonText = "scroll canvas allocation failed";
+  if (reason == 1) reasonText = "scroll viewport exceeds compile-time canvas budget";
+  else if (reason == 2) reasonText = "using Mode C strip fallback (smooth scroll canvas unavailable)";
+
+#if defined(ESP32)
+  uint32_t freeHeap = ESP.getFreeHeap();
+  uint32_t maxAlloc = ESP.getMaxAllocHeap();
+  Serial.printf(
+    "[cuttlefish] WARNING: #%s (%dx%d) needs %lu bytes for accurate scroll — %s. "
+    "heap free=%lu max_alloc=%lu budget=%d. "
+    "Shrink the scroll viewport in CSS, trim fonts/images, or use PSRAM.\\n",
+    label, vw, vh, (unsigned long)need, reasonText,
+    (unsigned long)freeHeap, (unsigned long)maxAlloc, UI_SCROLL_CANVAS_BUDGET_BYTES);
+#elif defined(ESP8266)
+  uint32_t freeHeap = ESP.getFreeHeap();
+  Serial.printf(
+    "[cuttlefish] WARNING: #%s (%dx%d) needs %lu bytes for accurate scroll — %s. "
+    "heap free=%lu budget=%d. "
+    "Shrink the scroll viewport in CSS, trim fonts/images, or reduce UI footprint.\\n",
+    label, vw, vh, (unsigned long)need, reasonText,
+    (unsigned long)freeHeap, UI_SCROLL_CANVAS_BUDGET_BYTES);
+#else
+  // Non-Arduino target (e.g. SDL native): no Serial, so use standard-C printf.
+  // The native framework forces <cstdio> so printf is available here.
+  printf(
+    "[cuttlefish] WARNING: #%s (%dx%d) needs %lu bytes for accurate scroll — %s. "
+    "budget=%d. Shrink the scroll viewport in CSS or trim UI assets.\\n",
+    label, vw, vh, (unsigned long)need, reasonText, UI_SCROLL_CANVAS_BUDGET_BYTES);
+#endif
+}
+
+// Shift the canvas buffer vertically by deltaY (cheap memmove of existing
+// pixels), then fill the exposed band with bg. Reports the exposed band via
+// *exposedY/*exposedH so the caller can redraw only that strip (Mode B).
+static inline void ui_shift_container_canvas(CuttlefishCanvas16* canvas, int16_t deltaY, UI_COLOR_T bg,
+                                             int16_t* exposedY, int16_t* exposedH) {
+  if (exposedY) *exposedY = 0;
+  if (exposedH) *exposedH = 0;
+  if (!canvas || !display_canvasBuffer(canvas)) return;
+  int16_t w = display_canvasWidth(canvas);
+  int16_t h = display_canvasHeight(canvas);
+  int16_t shift = deltaY < 0 ? -deltaY : deltaY;
+  if (shift <= 0 || shift >= h) {
+    display_canvasFillScreen(canvas, bg);
+    if (exposedY) *exposedY = 0;
+    if (exposedH) *exposedH = h;
+    return;
+  }
+  UI_COLOR_T* pixels = display_canvasBuffer(canvas);
+  int16_t stride = display_canvasWidth(canvas);
+  // Reserve the rightmost 4px gutter so the memmove never smears scrollbar
+  // pixels; the gutter is repainted separately by ui_draw_scrollbar.
+  int16_t contentW = w > 4 ? w - 4 : w;
+  // deltaY > 0: scrollY increased → finger moved up → content moves up.
+  // Cached rows shift toward LOWER indices; the exposed band is at the BOTTOM.
+  // deltaY < 0: content moves down → rows shift toward higher indices; exposed
+  // band at the TOP. (Matches the proven pre-rewrite direction.)
+  if (deltaY > 0) {
+    for (int16_t row = 0; row < h - shift; row++) {
+      memmove(pixels + (int32_t)row * stride,
+              pixels + (int32_t)(row + shift) * stride,
+              (size_t)contentW * sizeof(UI_COLOR_T));
+    }
+    if (exposedY) *exposedY = h - shift;
+  } else {
+    for (int16_t row = h - shift - 1; row >= 0; row--) {
+      memmove(pixels + (int32_t)(row + shift) * stride,
+              pixels + (int32_t)row * stride,
+              (size_t)contentW * sizeof(UI_COLOR_T));
+    }
+    if (exposedY) *exposedY = 0;
+  }
+  int16_t fillY = deltaY > 0 ? h - shift : 0;
+  display_canvasFillRect(canvas, 0, fillY, contentW, shift, bg);
+  if (w > contentW) {
+    display_canvasFillRect(canvas, contentW, 0, w - contentW, h, bg);
+  }
+  if (exposedH) *exposedH = shift;
+}
+
+// Repair canvas: parent-seeded background repaints + exposed-strip redraws.
+// Grow-only between navigations so small scroll-delta changes do not allocate
+// and free a new strip canvas during drag.
+static inline CuttlefishCanvas16* ui_get_repair_canvas(int16_t w, int16_t h) {
+  if (w <= 0 || h <= 0) return nullptr;
+  if (!__ui_repair_canvas || !display_canvasBuffer(__ui_repair_canvas) ||
+      display_canvasWidth(__ui_repair_canvas) < w ||
+      display_canvasHeight(__ui_repair_canvas) < h) {
+    display_deleteCanvas(__ui_repair_canvas);
+    __ui_repair_canvas = ui_create_canvas_best(w, h);
+  }
+  return (__ui_repair_canvas && display_canvasBuffer(__ui_repair_canvas))
+    ? __ui_repair_canvas : nullptr;
+}`;
+}