From 7fa4cf716e37afb9b8e25f513c7d0c20a64d625c Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Thu, 30 Jul 2026 21:02:59 -0400
Subject: [PATCH 01/37] docs: scroll-layer rendering architecture design
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Promotes the translate-instead-of-re-record technique from the path level
(draw/lineCache.ts) to the picture level, and extends it to the time axis,
which currently has no cache at all and re-lays out every label every frame.

Three independent scroll-layer slots (line, candles, axis), each a cached
SkPicture composited at a per-frame horizontal offset. Constrained by
drawPicture ignoring globalAlpha, so scroll layers are used only at composite
alpha 1 with a live-draw fallback otherwise — the same gate draw/index.ts
already applies to the grid picture.

Records the accepted trade-off on time-axis label fades and the scope note
that lineCache already captures most of the line-side win.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 ...-07-30-scroll-layer-architecture-design.md | 253 ++++++++++++++++++
 1 file changed, 253 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-07-30-scroll-layer-architecture-design.md

diff --git a/docs/superpowers/specs/2026-07-30-scroll-layer-architecture-design.md b/docs/superpowers/specs/2026-07-30-scroll-layer-architecture-design.md
new file mode 100644
index 0000000..8c81b65
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-30-scroll-layer-architecture-design.md
@@ -0,0 +1,253 @@
+# Scroll-layer rendering architecture
+
+**Date:** 2026-07-30
+**Status:** Design approved, not yet implemented
+**Branch:** `perf/scroll-layer-architecture`
+
+## Problem
+
+`useLivelineEngine`'s frame callback re-records a complete `SkPicture` every
+frame, forever. Most of what it records is content whose only per-frame change
+is a horizontal translation: the chart scrolls left because "now" advances.
+
+Two pieces of this are already solved at the *path* level:
+
+- `draw/lineCache.ts:189-206` caches the spline prefix and, on a hit,
+  re-assembles the drawable path as `addPath(prefix)` + `offset(dx, 0)` + two
+  tail cubics — no spline rebuild.
+- `draw/gridLayer.ts` caches the grid as a composited `SkPicture`, replayed
+  with a single `ctx.drawPicture` (`draw/index.ts:219`).
+
+One piece is not solved at all. `draw/timeAxis.ts` has no cache: every frame it
+recomputes the interval, calls `formatTime()` per label (the default formatter
+allocates a `Date` and three `padStart` results *per label per frame*), walks
+and lerps a label `Map`, measures, sorts, resolves overlaps, then issues
+`save/beginPath/moveTo/lineTo/stroke/fillText/restore` per label. Its own source
+comment records the gap: *"rebuilt unconditionally every frame (this function
+has no picture-cache bypass, unlike `drawGrid`)"* (`timeAxis.ts:19-22`).
+
+This design promotes the translate-instead-of-re-record technique from the path
+level to the picture level, and extends it to the time axis.
+
+### Scope note
+
+The incremental win for the line specifically is modest, because `lineCache`
+already captures most of it — roughly a dozen native calls per frame collapse to
+about two. This was raised before the design was accepted and the full
+architecture was chosen deliberately. The largest single win in this design is
+the time axis, which is currently uncached.
+
+## Architecture
+
+### The scroll layer abstraction
+
+A new module, `src/draw/scrollLayer.ts`, provides a generic **scroll layer
+slot**: a cached `SkPicture` recorded in build-time screen coordinates and
+composited each frame at a horizontal offset.
+
+```
+dx = layout.toX(slot.tRef) - slot.xRefAtBuild
+```
+
+This is the identical formula `lineCache.ts:189` uses — recomputed against the
+build-time reference every frame, never accumulated, so there is no drift.
+
+Composition:
+
+```ts
+ctx.save();
+ctx.clipRect(slot.clipX, slot.clipY, slot.clipW, slot.clipH);
+ctx.translate(dx, 0);
+ctx.drawPicture(slot.picture);
+ctx.restore();
+```
+
+Each slot carries its **own** clip region rather than sharing one: `lineScroll`
+and `candleScroll` clip to the plot area, while `axisScroll` clips to the axis
+strip below it (`h - pad.bottom` downward). A single shared chart-area clip
+would erase the axis entirely.
+
+The module is kept free of Skia imports (structural `Picture` type parameter,
+exactly like `gridLayer.ts`) so jest can exercise the key-comparison and `dx`
+logic without the native binding.
+
+### Three instances, not one merged picture
+
+Three independent slots: `lineScroll`, `candleScroll`, `axisScroll`.
+
+- **Z-order.** Today's order is `… → line+fill → timeAxis → dot → …`
+  (`draw/index.ts:253-289`). Merging line and axis into one picture would fuse
+  two non-adjacent z positions.
+- **Independent invalidation.** The line rebuilds on every tick; the axis
+  rebuilds only when a label enters or leaves (roughly every `interval`
+  seconds — about every 5s on a 30s window). Merging would drag the axis into
+  the line's rebuild rate and destroy its entire advantage.
+
+Cost: two extra `drawPicture` calls per frame.
+
+### Layer membership
+
+**Scroll layer** — rebuilt only when its key changes:
+
+| Slot | Contents | Rebuild trigger |
+|---|---|---|
+| `lineScroll` | spline prefix through decimated points `0..N-2`, stroke + fill | tick / range / geometry change |
+| `candleScroll` | closed candle bodies + wicks, batched by bull/bear | new or revised closed candle |
+| `axisScroll` | axis baseline, ticks, labels at full alpha | label enters/leaves, interval change |
+
+**Screen layer** — recorded live every frame, unchanged from today: line tail
+(last data point + live tip), live candle, live dot, pulse ring, momentum
+arrows, particles, shake, badge, value text, crosshair, edge fades. Plus the
+value-space layers that never scroll and are unaffected: grid (already its own
+cached picture), reference line, orderbook.
+
+The static/moving split for line and candles is not new: it is exactly the
+prefix/tail split `lineCache` and `candleCache` already encode.
+
+### Build ordering
+
+Scroll layers are rebuilt **before** `recorder.beginRecording()` opens the
+frame's picture, never during it. This avoids depending on
+`Skia.PictureRecorder()` being safely reentrant while another recording is open,
+and makes the ordering explicit and testable. `useLivelineEngine.ts` gains a
+"rebuild dirty scroll layers" step ahead of the existing recording block.
+
+## The constraint that shapes everything: pictures bake paint
+
+`ctx.drawPicture` ignores `globalAlpha` — documented at `canvas2d.ts:140-143`,
+because Skia's `drawPicture` takes no paint argument. Applying alpha at
+composite time would require `saveLayerAlpha`, which allocates an offscreen
+render target — precisely the Android cost this work exists to avoid.
+
+**Rule: a scroll layer is used only when its composite alpha is exactly 1.**
+Otherwise the engine falls back to today's live-drawing path.
+
+This is an existing pattern, not a new one: `draw/index.ts:218` already gates the
+grid picture on `reveal >= 1` for the same reason. Practically it means the
+reveal morph, the loading/empty crossfade, and scrub dimming all bypass scroll
+layers. Those are transient; the steady state is what is being optimized.
+
+A second consequence: **palette becomes part of every scroll-layer key**, unlike
+the path caches. A picture bakes color, stroke width, and gradient stops that a
+path did not.
+
+## Time axis redesign
+
+Labels and ticks bake at alpha 1. The per-label 50px `edgeAlpha` fade
+(`timeAxis.ts:65-72`) is replaced by a gradient `destination-out` erase over the
+axis strip at both edges, applied in the screen pass after compositing — the same
+technique `drawEdgeFade` already uses for the chart body:
+
+```ts
+ctx.globalCompositeOperation = 'destination-out';
+ctx.fillStyle = <linear gradient, 50px>;
+ctx.fillRect(chartLeft, axisTop, 50, axisH);      // left
+ctx.fillRect(chartRight - 50, axisTop, 50, axisH); // right
+```
+
+Per-label alpha state disappears. Label visibility becomes a pure function of
+position, which also replaces the alpha-based overlap tiebreak
+(`timeAxis.ts:184-198`) with a positional one.
+
+**Accepted behavior change:** during a window transition, label set swaps become
+hard rather than an alpha dissolve. This was chosen explicitly over a
+pixel-identical hybrid design.
+
+`timeAxis.ts` imports `Ctx2D` as a type only, so it is jest-testable with a fake
+context. The redesign is therefore developed test-first.
+
+## Invalidation keys
+
+Following the existing discipline: flat values only, compared field-by-field, no
+allocation per frame.
+
+**`lineScroll`** — reuses `lineCacheHits`'s existing key
+(`kDataRev`, `kDataSource`, `kLen`, `kFirstT`, `kLastT`, `kLastV`, `kMin`,
+`kMax`, `kWindow`, `kH`, `kPadTop`, `kPadBottom`, `kChartW`) plus new
+picture-only dimensions: line color, line width, fill enabled, fill gradient
+stops. Bypassed entirely while `reveal < 1` or scrub dimming is active.
+
+**`candleScroll`** — `candleCache`'s existing key plus `candlesRev`, bull/bear
+body and wick colors, and `candleWidth`.
+
+**`axisScroll`** — `interval`, a cheap visible-label-set identity (count + first
+key + last key), `tRef`, `formatTime` reference equality, `palette.gridLine`,
+`palette.timeLabel`, `pad`, `h`, `w`.
+
+## Risks
+
+**Cull rect (highest).** A picture records with a cull rect in its own
+coordinate space; content outside it may be dropped at record time. Compositing
+at `translate(dx, 0)` then shifts the result. Two mitigations, both applied:
+record each scroll layer with a cull rect expanded to cover the full
+pre-rebuild scroll range, and always `clipRect` to that slot's own region at
+composite time so translated content cannot bleed into the padding, the badge,
+or across the plot/axis boundary.
+
+**Text subpixel jitter.** Compositing at fractional `dx` re-rasterizes glyphs at
+a new subpixel position. Vector content stays crisp, but glyph hinting could
+produce ~1px jitter on axis labels while scrolling. Verify visually; if it
+appears, round `dx` to whole pixels for `axisScroll` only (labels sit at
+computed intervals, so a sub-pixel snap is invisible).
+
+**Alpha-1 gating reduces coverage.** Any chart spending significant time mid-
+reveal, mid-crossfade, or scrub-dimmed gets no benefit. Acceptable: those states
+are transient.
+
+**Blast radius.** Touches `engine/step.ts` (1,813 lines), `draw/index.ts`, and
+every affected draw module's coordinate assumptions. `PLAN_MAINT.md` item 4
+(positional-parameter soup) already blocked one smaller perf change in
+`drawLine`; the scroll-layer parameter is threaded as part of an options object
+rather than a 17th positional parameter.
+
+## Testing
+
+- New `src/draw/__tests__/scrollLayer.test.ts` — key comparison, `dx`
+  computation, rebuild triggering, alpha-1 gating. Fake picture recorders, same
+  pattern as `lineCache.test.ts`.
+- New time-axis tests — label-set selection and positional overlap resolution,
+  using a fake `Ctx2D`.
+- Extend `lineCache.test.ts` / `candleCache.test.ts` for the new palette key
+  dimensions.
+- Per stage: `typecheck`, `lint`, `test` from repo root via the vendored yarn
+  (`node .yarn/releases/yarn-4.11.0.cjs <script>`).
+- Per stage: visual verification on iOS simulator and Android emulator.
+
+## Staging
+
+Four landings, each its own commit so a regression is bisectable.
+
+| Stage | Content | Behavior change |
+|---|---|---|
+| 0 | `draw/scrollLayer.ts` + tests | None — nothing consumes it yet |
+| 1 | `lineScroll` wired into the line pipeline | None expected |
+| 2 | `candleScroll` wired into the candle pipeline | None expected |
+| 3 | `axisScroll` + time-axis redesign | Window-transition label swap becomes hard |
+
+Each stage gates on typecheck + lint + test, plus:
+
+- **iOS CPU A/B** using the established `run-and-profile` protocol: swap only
+  `src/`, 3 runs per arm over fixed 20s windows, drift-control re-measure. FPS
+  cannot show this win — frame pacing caps recording at ~60
+  (`MIN_FRAME_INTERVAL_MS`), so both arms read 60 regardless. Measure CPU time.
+- **Android emulator release build**, with two preconditions checked first,
+  both of which have previously produced false "still slow" signals:
+  `hw.gpu.enabled` in the AVD config, and host `uptime` before each arm.
+
+Emulator relative CPU deltas are meaningful for this work because it is a
+CPU-side change (fewer draw calls recorded per frame). They would *not* be
+meaningful for GPU-compositor-side questions such as `opaque`/TextureView.
+
+Rollback: every stage keeps the live-draw path intact as the alpha<1 fallback,
+so any stage reverts as a single commit.
+
+## Out of scope
+
+- **Declarative `<Group transform>` promotion.** Chosen as an explicit
+  follow-up: land the imperative split first, since the layer boundary is the
+  hard part, then evaluate promoting it.
+- **Multi-series scroll layers.** Multi-series already has per-series
+  `lineCache` slots and is excluded from quiescence. Extending scroll layers
+  per-series is mechanical but multiplies the surface; deferred.
+- **`opaque` / TextureView→SurfaceView.** Independent, GPU-compositor-side, and
+  requires physical Android hardware to evaluate honestly. Tracked separately.

From 3db71f141fb4c795551e8d88299d489c2250a533 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Thu, 30 Jul 2026 21:10:38 -0400
Subject: [PATCH 02/37] feat(draw): scroll-layer slot foundation (stage 0)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Generic cross-frame cache for a scroll layer: an SkPicture recorded once in
build-time screen coordinates and re-composited each frame at a horizontal
offset, instead of re-recorded. Promotes the technique lineCache.ts already
applies at the path level up to the picture level.

Nothing consumes this yet — no behavior change.

Key is a push-built positional array owned by the slot rather than named kFoo
fields: three consumers (line, candles, axis) have barely-overlapping key
dimensions, so named fields would force every consumer's dimensions into this
module. Split numeric/reference arrays because palette colors are strings and
formatter identity is a function reference, and merging them would make the
hot per-frame comparison polymorphic. Zero per-frame allocation — both arrays
live on the slot and are written by index.

dx is always recomputed against the build-time reference, never accumulated
(same invariant as lineCache.ts:166-175).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/draw/__tests__/scrollLayer.test.ts | 448 +++++++++++++++++++++++++
 src/draw/scrollLayer.ts                | 323 ++++++++++++++++++
 2 files changed, 771 insertions(+)
 create mode 100644 src/draw/__tests__/scrollLayer.test.ts
 create mode 100644 src/draw/scrollLayer.ts

diff --git a/src/draw/__tests__/scrollLayer.test.ts b/src/draw/__tests__/scrollLayer.test.ts
new file mode 100644
index 0000000..f3ef569
--- /dev/null
+++ b/src/draw/__tests__/scrollLayer.test.ts
@@ -0,0 +1,448 @@
+import {
+  createScrollLayerSlot,
+  setScrollLayerClip,
+  scrollLayerBeginKey,
+  scrollLayerPushNum,
+  scrollLayerPushRef,
+  scrollLayerKeyHits,
+  scrollLayerCommitKey,
+  scrollLayerBuilt,
+  scrollLayerDx,
+  scrollLayerUsable,
+  type ScrollLayerSlot,
+} from '../scrollLayer';
+import type { ChartLayout, Padding } from '../../types';
+
+// ── Fakes ──────────────────────────────────────────────────────────────────
+
+/** Stand-in for SkPicture. `ScrollLayerSlot` takes Picture as a structural
+ * type parameter precisely so this can be a bare object — no native binding,
+ * same trick lineCache.test.ts uses for SkPath. */
+interface FakePicture {
+  id: number;
+}
+let pictureId = 0;
+function makePicture(): FakePicture {
+  pictureId++;
+  return { id: pictureId };
+}
+
+const PAD: Required<Padding> = { top: 10, right: 20, bottom: 20, left: 10 };
+
+/** Layout matching engineStep's construction (step.ts line-mode branch). */
+function makeLayout(
+  now: number,
+  windowSecs = 60,
+  w = 400,
+  h = 200
+): ChartLayout {
+  const chartW = w - PAD.left - PAD.right;
+  const chartH = h - PAD.top - PAD.bottom;
+  const buffer = 0.05;
+  const rightEdge = now + windowSecs * buffer;
+  const leftEdge = rightEdge - windowSecs;
+  const minVal = 90;
+  const maxVal = 110;
+  const valRange = maxVal - minVal;
+  return {
+    w,
+    h,
+    pad: PAD,
+    chartW,
+    chartH,
+    leftEdge,
+    rightEdge,
+    minVal,
+    maxVal,
+    valRange,
+    toX: (t: number) =>
+      PAD.left + ((t - leftEdge) / (rightEdge - leftEdge)) * chartW,
+    toY: (v: number) => PAD.top + (1 - (v - minVal) / valRange) * chartH,
+  };
+}
+
+/**
+ * A representative consumer's key writer. Real consumers keep their pushes in
+ * one helper exactly like this so there is a single push order to read; the
+ * order must be identical every frame, so nothing here is conditional.
+ */
+function writeKey(
+  slot: ScrollLayerSlot<FakePicture>,
+  opts: {
+    dataRev?: number;
+    len?: number;
+    window?: number;
+    lineColor?: string;
+    formatter?: (v: number) => string;
+  } = {}
+): void {
+  scrollLayerBeginKey(slot);
+  scrollLayerPushNum(slot, opts.dataRev ?? 0);
+  scrollLayerPushNum(slot, opts.len ?? 20);
+  scrollLayerPushNum(slot, opts.window ?? 60);
+  scrollLayerPushRef(slot, opts.lineColor ?? '#3b82f6');
+  scrollLayerPushRef(slot, opts.formatter ?? FORMAT_A);
+}
+
+const FORMAT_A = (v: number) => `$${v}`;
+const FORMAT_B = (v: number) => `$${v}`;
+
+/** Build a slot into the "just rebuilt at `now`" state, keyed with `opts`. */
+function build(
+  now: number,
+  tRef: number,
+  opts: Parameters<typeof writeKey>[1] = {}
+): { slot: ScrollLayerSlot<FakePicture>; layout: ChartLayout } {
+  const slot = createScrollLayerSlot<FakePicture>();
+  const layout = makeLayout(now);
+  writeKey(slot, opts);
+  scrollLayerBuilt(slot, makePicture(), tRef, layout.toX(tRef));
+  return { slot, layout };
+}
+
+// ── Tests ──────────────────────────────────────────────────────────────────
+
+describe('createScrollLayerSlot', () => {
+  it('starts empty: no picture, no committed key, zero clip', () => {
+    const slot = createScrollLayerSlot<FakePicture>();
+    expect(slot.picture).toBeNull();
+    expect(slot.tRef).toBe(0);
+    expect(slot.xRefAtBuild).toBe(0);
+    expect(slot.kNumLen).toBe(0);
+    expect(slot.kRefLen).toBe(0);
+    expect(slot.clipX).toBe(0);
+    expect(slot.clipY).toBe(0);
+    expect(slot.clipW).toBe(0);
+    expect(slot.clipH).toBe(0);
+  });
+});
+
+describe('scrollLayerKeyHits', () => {
+  it('a fresh slot never hits, even with a matching key pushed', () => {
+    const slot = createScrollLayerSlot<FakePicture>();
+    writeKey(slot);
+    scrollLayerCommitKey(slot);
+    writeKey(slot);
+    // Key matches, but there is no picture to composite — validity is
+    // `picture !== null`, same as LineCacheSlot.prefix / GridLayerSlot.picture.
+    expect(scrollLayerKeyHits(slot)).toBe(false);
+  });
+
+  it('hits right after a build with the same inputs', () => {
+    const { slot } = build(1000, 970);
+    writeKey(slot);
+    expect(scrollLayerKeyHits(slot)).toBe(true);
+  });
+
+  it('misses on any single numeric dimension changing', () => {
+    const cases: Parameters<typeof writeKey>[1][] = [
+      { dataRev: 1 },
+      { len: 21 },
+      { window: 120 },
+    ];
+    for (const change of cases) {
+      const { slot } = build(1000, 970);
+      writeKey(slot, change);
+      expect(scrollLayerKeyHits(slot)).toBe(false);
+    }
+  });
+
+  it('misses when a palette color changes (pictures bake paint)', () => {
+    const { slot } = build(1000, 970);
+    writeKey(slot, { lineColor: '#ef4444' });
+    expect(scrollLayerKeyHits(slot)).toBe(false);
+  });
+
+  it('misses when a formatter changes reference, even if behaviourally identical', () => {
+    const { slot } = build(1000, 970);
+    writeKey(slot, { formatter: FORMAT_B });
+    expect(scrollLayerKeyHits(slot)).toBe(false);
+  });
+
+  it('hits for every dimension held at its committed value (no false miss)', () => {
+    const { slot } = build(1000, 970, {
+      dataRev: 7,
+      len: 33,
+      window: 120,
+      lineColor: '#ef4444',
+      formatter: FORMAT_B,
+    });
+    writeKey(slot, {
+      dataRev: 7,
+      len: 33,
+      window: 120,
+      lineColor: '#ef4444',
+      formatter: FORMAT_B,
+    });
+    expect(scrollLayerKeyHits(slot)).toBe(true);
+  });
+
+  it('misses when the key arity changes rather than matching a prefix', () => {
+    const { slot } = build(1000, 970);
+    // Same first three numbers, but a consumer that grew its key.
+    scrollLayerBeginKey(slot);
+    scrollLayerPushNum(slot, 0);
+    scrollLayerPushNum(slot, 20);
+    scrollLayerPushNum(slot, 60);
+    scrollLayerPushNum(slot, 999); // new dimension
+    scrollLayerPushRef(slot, '#3b82f6');
+    scrollLayerPushRef(slot, FORMAT_A);
+    expect(scrollLayerKeyHits(slot)).toBe(false);
+
+    // ...and when it shrinks, including on the ref array.
+    scrollLayerBeginKey(slot);
+    scrollLayerPushNum(slot, 0);
+    scrollLayerPushNum(slot, 20);
+    scrollLayerPushNum(slot, 60);
+    scrollLayerPushRef(slot, '#3b82f6');
+    expect(scrollLayerKeyHits(slot)).toBe(false);
+  });
+
+  it('is read-only: does not commit, so a repeated miss stays a miss', () => {
+    const { slot } = build(1000, 970);
+    const pic = slot.picture;
+    writeKey(slot, { dataRev: 1 });
+    expect(scrollLayerKeyHits(slot)).toBe(false);
+    expect(scrollLayerKeyHits(slot)).toBe(false);
+    expect(slot.picture).toBe(pic);
+    expect(slot.kNum[0]).toBe(0); // committed key untouched
+  });
+
+  it('reuses its arrays across frames — no per-frame allocation', () => {
+    const { slot } = build(1000, 970);
+    const nNum = slot.nNum;
+    const nRef = slot.nRef;
+    const kNum = slot.kNum;
+    for (let i = 0; i < 100; i++) {
+      writeKey(slot, { dataRev: i });
+      scrollLayerKeyHits(slot);
+      scrollLayerCommitKey(slot);
+    }
+    expect(slot.nNum).toBe(nNum);
+    expect(slot.nRef).toBe(nRef);
+    expect(slot.kNum).toBe(kNum);
+    // Arrays grew to the key arity once and stopped there.
+    expect(slot.nNum.length).toBe(3);
+    expect(slot.nRef.length).toBe(2);
+  });
+});
+
+describe('scrollLayerBuilt', () => {
+  it('stores the picture, the reference pair, and commits the key together', () => {
+    const slot = createScrollLayerSlot<FakePicture>();
+    const layout = makeLayout(1000);
+    const pic = makePicture();
+    writeKey(slot, { dataRev: 4 });
+    expect(scrollLayerKeyHits(slot)).toBe(false);
+
+    scrollLayerBuilt(slot, pic, 970, layout.toX(970));
+
+    expect(slot.picture).toBe(pic);
+    expect(slot.tRef).toBe(970);
+    expect(slot.xRefAtBuild).toBe(layout.toX(970));
+    writeKey(slot, { dataRev: 4 });
+    expect(scrollLayerKeyHits(slot)).toBe(true);
+  });
+
+  it('a rebuild replaces the picture and re-anchors the reference', () => {
+    const { slot } = build(1000, 970);
+    const first = slot.picture;
+    const later = makeLayout(1030);
+    const pic2 = makePicture();
+    writeKey(slot, { dataRev: 1 });
+    scrollLayerBuilt(slot, pic2, 1000, later.toX(1000));
+
+    expect(slot.picture).not.toBe(first);
+    expect(slot.tRef).toBe(1000);
+    expect(scrollLayerDx(slot, later)).toBe(0);
+  });
+});
+
+describe('scrollLayerDx', () => {
+  it('is exactly zero on the frame of the build', () => {
+    const { slot, layout } = build(1000, 970);
+    // Not "close to" zero — tRef/xRefAtBuild come from the same toX, so the
+    // subtraction is exactly 0 and consumers can skip the translate entirely.
+    expect(scrollLayerDx(slot, layout)).toBe(0);
+  });
+
+  it('is exactly zero for every tRef, not just a lucky one', () => {
+    for (const tRef of [0, 970, 1000, -500, 1234.5678]) {
+      const { slot, layout } = build(1000, tRef);
+      expect(scrollLayerDx(slot, layout)).toBe(0);
+    }
+  });
+
+  it('moves content left as `now` advances', () => {
+    const { slot } = build(1000, 970);
+    const dx = scrollLayerDx(slot, makeLayout(1005));
+    expect(dx).toBeLessThan(0);
+    // 5s of a 60s window across chartW = 370px.
+    expect(dx).toBeCloseTo((-5 / 60) * 370, 9);
+  });
+
+  it('equals the translation a fresh build at the later time would need', () => {
+    // Ground truth: where tRef sits at the later time, minus where it sat at
+    // build time. The cached picture must land exactly there.
+    const tRef = 970;
+    const buildLayout = makeLayout(1000);
+    const laterLayout = makeLayout(1017.3);
+    const { slot } = build(1000, tRef);
+    expect(scrollLayerDx(slot, laterLayout)).toBeCloseTo(
+      laterLayout.toX(tRef) - buildLayout.toX(tRef),
+      9
+    );
+  });
+
+  it('does not drift over many frames — recomputed, never accumulated', () => {
+    const tRef = 970;
+    const { slot } = build(1000, tRef);
+    const PX_PER_SEC = 370 / 60; // chartW / windowSecs
+
+    // 6,000 frames of *jittered* frame times — the realistic case, since a
+    // real frame callback never gets a clean 1/60s. `naive` models the
+    // tempting `dx += nominalStep` implementation this module forbids.
+    let now = 1000;
+    let naive = 0;
+    let rng = 12345;
+    for (let i = 0; i < 6000; i++) {
+      rng = (rng * 1103515245 + 12345) % 2147483648;
+      // Real frames overrun the nominal interval more often than they beat
+      // it, so the jitter is deliberately biased rather than symmetric.
+      const step = (1 / 60) * (1 + (rng / 2147483648) * 0.5);
+      now += step;
+      naive -= (1 / 60) * PX_PER_SEC; // nominal, not actual
+
+      // The recomputed value is a pure function of this frame's layout, with
+      // no dependence on how many frames preceded it or how long they were.
+      if (i % 250 === 0) {
+        const layout = makeLayout(now);
+        expect(scrollLayerDx(slot, layout)).toBe(
+          layout.toX(tRef) - slot.xRefAtBuild
+        );
+      }
+    }
+
+    const finalLayout = makeLayout(now);
+    const dx = scrollLayerDx(slot, finalLayout);
+    // Exact against a first-principles calculation after 6,000 frames.
+    expect(dx).toBeCloseTo(-(now - 1000) * PX_PER_SEC, 9);
+    // The accumulating version is off by whole pixels — a visibly misaligned
+    // axis. This is the failure mode the doc comment on scrollLayerDx warns
+    // about, and it is why dx takes no per-frame delta parameter.
+    expect(Math.abs(naive - dx)).toBeGreaterThan(1);
+  });
+
+  it('is unaffected by the order frames are evaluated in (pure function of layout)', () => {
+    const { slot } = build(1000, 970);
+    const forward = [1001, 1002, 1003].map((t) =>
+      scrollLayerDx(slot, makeLayout(t))
+    );
+    const backward = [1003, 1002, 1001]
+      .map((t) => scrollLayerDx(slot, makeLayout(t)))
+      .reverse();
+    expect(forward).toEqual(backward);
+  });
+
+  it('absorbs a pad.left shift, which is why pad.left need not be keyed', () => {
+    // dx is a difference of two toX values; a constant x-offset cancels.
+    const { slot, layout } = build(1000, 970);
+    const later = makeLayout(1005);
+    const shifted: ChartLayout = {
+      ...later,
+      toX: (t: number) => later.toX(t) + 25,
+    };
+    const unshifted = scrollLayerDx(slot, later);
+    expect(scrollLayerDx(slot, shifted)).toBeCloseTo(unshifted + 25, 9);
+    expect(scrollLayerDx(slot, layout)).toBe(0);
+  });
+});
+
+describe('clip regions', () => {
+  it('each slot carries its own region — a plot slot and an axis slot differ', () => {
+    const layout = makeLayout(1000);
+    const plot = createScrollLayerSlot<FakePicture>();
+    const axis = createScrollLayerSlot<FakePicture>();
+
+    // Plot area: the chart body.
+    setScrollLayerClip(
+      plot,
+      layout.pad.left,
+      layout.pad.top,
+      layout.chartW,
+      layout.chartH
+    );
+    // Axis strip: `h - pad.bottom` downward. A shared plot-area clip would
+    // erase this entirely, which is the whole reason clips are per-slot.
+    const axisTop = layout.h - layout.pad.bottom;
+    setScrollLayerClip(
+      axis,
+      layout.pad.left,
+      axisTop,
+      layout.chartW,
+      layout.pad.bottom
+    );
+
+    expect(plot.clipY).toBe(10);
+    expect(plot.clipH).toBe(170);
+    expect(axis.clipY).toBe(180);
+    expect(axis.clipH).toBe(20);
+    // Disjoint vertically: the plot clip ends exactly where the axis begins.
+    expect(plot.clipY + plot.clipH).toBe(axis.clipY);
+  });
+
+  it('is not part of the invalidation key — re-clipping keeps the picture', () => {
+    const { slot } = build(1000, 970);
+    const pic = slot.picture;
+    setScrollLayerClip(slot, 10, 10, 370, 170);
+    writeKey(slot);
+    expect(scrollLayerKeyHits(slot)).toBe(true);
+    expect(slot.picture).toBe(pic);
+    setScrollLayerClip(slot, 0, 0, 400, 200);
+    writeKey(slot);
+    expect(scrollLayerKeyHits(slot)).toBe(true);
+  });
+
+  it('bounds a translated picture: content scrolled past the left edge is clipped away', () => {
+    // The clip is the guard against a picture's cull rect being translated
+    // somewhere it was never meant to cover.
+    const layout = makeLayout(1000);
+    const slot = createScrollLayerSlot<FakePicture>();
+    setScrollLayerClip(
+      slot,
+      layout.pad.left,
+      layout.pad.top,
+      layout.chartW,
+      layout.chartH
+    );
+    writeKey(slot);
+    scrollLayerBuilt(slot, makePicture(), 970, layout.toX(970));
+
+    // Content recorded at tRef, composited 30s later.
+    const later = makeLayout(1030);
+    const dx = scrollLayerDx(slot, later);
+    const contentX = slot.xRefAtBuild + dx;
+    expect(contentX).toBeLessThan(slot.clipX); // outside the clip on the left
+    expect(contentX).toBeCloseTo(later.toX(970), 9); // and at the right place
+  });
+});
+
+describe('scrollLayerUsable', () => {
+  it('is false without a picture, whatever the alpha', () => {
+    const slot = createScrollLayerSlot<FakePicture>();
+    expect(scrollLayerUsable(slot, 1)).toBe(false);
+  });
+
+  it('is false below alpha 1 — drawPicture ignores globalAlpha', () => {
+    const { slot } = build(1000, 970);
+    expect(scrollLayerUsable(slot, 0)).toBe(false);
+    expect(scrollLayerUsable(slot, 0.5)).toBe(false);
+    expect(scrollLayerUsable(slot, 0.999)).toBe(false);
+  });
+
+  it('is true at exactly 1, and tolerates a lerp overshoot', () => {
+    const { slot } = build(1000, 970);
+    expect(scrollLayerUsable(slot, 1)).toBe(true);
+    expect(scrollLayerUsable(slot, 1.0001)).toBe(true);
+  });
+});
diff --git a/src/draw/scrollLayer.ts b/src/draw/scrollLayer.ts
new file mode 100644
index 0000000..97bea75
--- /dev/null
+++ b/src/draw/scrollLayer.ts
@@ -0,0 +1,323 @@
+import type { ChartLayout } from '../types';
+
+/**
+ * Generic cross-frame cache for a **scroll layer**: an SkPicture recorded
+ * once in build-time screen coordinates and re-composited every frame at a
+ * horizontal offset, instead of being re-recorded.
+ *
+ * This promotes the technique draw/lineCache.ts already applies at the *path*
+ * level (`addPath(prefix)` + `offset(dx, 0)`) up to the *picture* level. Most
+ * of what the frame callback records is content whose only per-frame change is
+ * that the chart scrolls left because "now" advanced; for that content a
+ * rebuild is pure waste.
+ *
+ * Composition at draw time is always this shape (see `scrollLayerDx`):
+ *
+ * ```ts
+ * ctx.save();
+ * ctx.clipRect(slot.clipX, slot.clipY, slot.clipW, slot.clipH);
+ * ctx.translate(scrollLayerDx(slot, layout), 0);
+ * ctx.drawPicture(slot.picture);
+ * ctx.restore();
+ * ```
+ *
+ * Two invariants future maintainers must not break:
+ *
+ * 1. **Alpha must be exactly 1.** `ctx.drawPicture` ignores `globalAlpha` —
+ *    Skia's drawPicture takes no paint argument (canvas2d.ts:139-143). Fading
+ *    a picture would need `saveLayerAlpha`, which allocates an offscreen
+ *    render target, precisely the Android cost this work exists to avoid. So
+ *    every consumer gates on `scrollLayerUsable(slot, alpha)` and falls back
+ *    to live drawing during the reveal morph, the loading/empty crossfade and
+ *    scrub dimming. draw/index.ts:218 already gates the grid picture on
+ *    `reveal >= 1` for exactly this reason.
+ * 2. **Each slot clips to its OWN region.** `lineScroll`/`candleScroll` clip
+ *    to the plot area; `axisScroll` clips to the axis strip below it
+ *    (`h - pad.bottom` downward). A single shared chart-area clip would erase
+ *    the axis entirely. The clip is also the guard that stops translated
+ *    content from bleeding into the padding, the badge, or across the
+ *    plot/axis boundary — a picture's cull rect lives in its own build-time
+ *    coordinate space, so translating it can carry content into places the
+ *    cull rect never intended to cover.
+ *
+ * A second consequence of caching pictures rather than paths: **palette is
+ * part of every scroll-layer key**. A picture bakes color, stroke width and
+ * gradient stops that a path did not.
+ *
+ * Kept free of Skia imports (`Picture` is a structural type parameter, exactly
+ * like draw/gridLayer.ts) so jest can exercise the key comparison and the `dx`
+ * arithmetic with fake picture objects, with no native binding loaded.
+ */
+
+/**
+ * A key dimension compared by reference/primitive identity rather than as a
+ * number: palette color strings, and formatter functions (`formatTime`,
+ * `formatValue`) whose identity is the only cheap proxy for their behaviour.
+ */
+export type ScrollLayerKeyRef = string | object | null;
+
+/**
+ * ## Why a push-built key array rather than named key fields
+ *
+ * The existing caches (lineCache, gridLayer) spell every key dimension out as
+ * a named `kFoo` field and compare them field-by-field. That is ideal when one
+ * module owns one cache — but this module is shared by three consumers
+ * (`lineScroll`, `candleScroll`, `axisScroll`) whose key dimensions barely
+ * overlap: the line keys on data revision and spline geometry, candles on the
+ * closed-candle revision and candle width, the axis on the tick interval and
+ * the visible label set. Named fields would force every new dimension of any
+ * consumer to be added to this module, i.e. every consumer would either fork
+ * the module or bloat it with fields the other two never read.
+ *
+ * So the key is a **positional array the consumer pushes into**, and the
+ * comparison lives here, written exactly once. A consumer adds a dimension by
+ * adding one `scrollLayerPushNum` call at its own call site; this file does
+ * not change. `kNumLen`/`kRefLen` record how many slots were actually pushed,
+ * so a consumer that changes its own key arity still invalidates correctly
+ * rather than silently comparing a prefix.
+ *
+ * Two arrays, not one, and neither is `unknown[]`:
+ *
+ * - A numeric-only key (the obvious first design) cannot express the two
+ *   dimensions the architecture *requires*: palette colors are strings, and
+ *   formatter identity is a function reference. Hence `nRef`/`kRef`.
+ * - Merging both into a single `unknown[]` would make the per-frame comparison
+ *   loop polymorphic over numbers, strings and functions. Splitting keeps the
+ *   hot numeric loop — which is the overwhelming majority of dimensions —
+ *   monomorphic.
+ *
+ * The cost of the array form versus named fields is that a dimension is
+ * identified by push order, not by name, so **push order must be identical
+ * between the frames being compared**. Consumers must therefore push
+ * unconditionally, never inside an `if`. Each consumer should keep its pushes
+ * in one small `writeXKey(slot, ...)` helper so there is a single push order
+ * to read.
+ *
+ * Zero allocation per frame: both the committed key and the scratch candidate
+ * key are arrays owned by the slot, written in place by index. They grow once,
+ * on the first few frames, and never again.
+ */
+export interface ScrollLayerSlot<Picture> {
+  /** The recorded picture, in build-time screen coordinates. `null` until the
+   * first build; that null is also the slot's validity flag, matching
+   * `LineCacheSlot.prefix` and `GridLayerSlot.picture`. */
+  picture: Picture | null;
+
+  /** The time value whose screen X was captured in `xRefAtBuild`. Anything
+   * with a stable identity across the picture's life works — in practice the
+   * time of the layer's leftmost content. */
+  tRef: number;
+  /** `layout.toX(tRef)` evaluated at build time. */
+  xRefAtBuild: number;
+
+  // Per-slot composite clip, in screen coordinates. See invariant 2 above:
+  // slots do NOT share one region.
+  clipX: number;
+  clipY: number;
+  clipW: number;
+  clipH: number;
+
+  /** Committed numeric key (the inputs the current `picture` was built from). */
+  kNum: number[];
+  kNumLen: number;
+  /** Committed reference/string key. */
+  kRef: ScrollLayerKeyRef[];
+  kRefLen: number;
+
+  /** Scratch numeric key: this frame's candidate, built by `scrollLayerPushNum`. */
+  nNum: number[];
+  nNumLen: number;
+  /** Scratch reference/string key. */
+  nRef: ScrollLayerKeyRef[];
+  nRefLen: number;
+}
+
+export function createScrollLayerSlot<Picture>(): ScrollLayerSlot<Picture> {
+  'worklet';
+  return {
+    picture: null,
+    tRef: 0,
+    xRefAtBuild: 0,
+    clipX: 0,
+    clipY: 0,
+    clipW: 0,
+    clipH: 0,
+    kNum: [],
+    kNumLen: 0,
+    kRef: [],
+    kRefLen: 0,
+    nNum: [],
+    nNumLen: 0,
+    nRef: [],
+    nRefLen: 0,
+  };
+}
+
+// NOTE: worklet declaration order. The worklets babel plugin rewrites
+// 'worklet' function declarations into const-assigned worklet objects
+// (hoisting is lost) and captures each worklet's closure at module evaluation
+// time, so a helper referenced before its own const assignment has run is
+// captured as `undefined` and crashes on the UI thread — see the same NOTE at
+// draw/canvas2d.ts:163-171. Every function below that calls another worklet in
+// this file is therefore declared *after* the one it calls:
+//   scrollLayerCommitKey  →  called by scrollLayerBuilt
+// Keep that ordering if you add anything here.
+
+/**
+ * Sets a slot's composite clip region. Split out from the build so a consumer
+ * can refresh the region on a layout change without discarding the picture:
+ * the clip is applied at composite time and is not baked into the recording,
+ * so it is deliberately NOT part of the invalidation key.
+ */
+export function setScrollLayerClip<Picture>(
+  slot: ScrollLayerSlot<Picture>,
+  x: number,
+  y: number,
+  w: number,
+  h: number
+): void {
+  'worklet';
+  slot.clipX = x;
+  slot.clipY = y;
+  slot.clipW = w;
+  slot.clipH = h;
+}
+
+/**
+ * Starts building this frame's candidate key. Call before any push; every
+ * push for the frame must follow, in the same order every frame.
+ */
+export function scrollLayerBeginKey<Picture>(
+  slot: ScrollLayerSlot<Picture>
+): void {
+  'worklet';
+  slot.nNumLen = 0;
+  slot.nRefLen = 0;
+}
+
+/** Appends one numeric dimension to this frame's candidate key. */
+export function scrollLayerPushNum<Picture>(
+  slot: ScrollLayerSlot<Picture>,
+  v: number
+): void {
+  'worklet';
+  slot.nNum[slot.nNumLen] = v;
+  slot.nNumLen++;
+}
+
+/**
+ * Appends one identity-compared dimension (palette color string, formatter
+ * function) to this frame's candidate key. Compared with `===`, so a
+ * behaviourally-identical but freshly-allocated formatter invalidates — the
+ * same conservative trade gridLayer.ts makes for `kFormatValue`.
+ */
+export function scrollLayerPushRef<Picture>(
+  slot: ScrollLayerSlot<Picture>,
+  v: ScrollLayerKeyRef
+): void {
+  'worklet';
+  slot.nRef[slot.nRefLen] = v;
+  slot.nRefLen++;
+}
+
+/**
+ * Pure, allocation-free predicate: true when the slot holds a picture whose
+ * committed key equals the candidate key just pushed for this frame.
+ *
+ * Read-only — it does not commit. A consumer calls this before doing any
+ * expensive work, exactly as `lineCacheHits` is called before building
+ * `decimated`/`pts`, and this is the ONE place the comparison is written so
+ * the three consumers cannot drift apart.
+ *
+ * Arity is compared first: a consumer that changed how many dimensions it
+ * pushes gets a miss rather than a silent prefix match.
+ */
+export function scrollLayerKeyHits<Picture>(
+  slot: ScrollLayerSlot<Picture>
+): boolean {
+  'worklet';
+  if (slot.picture === null) return false;
+  if (slot.nNumLen !== slot.kNumLen || slot.nRefLen !== slot.kRefLen)
+    return false;
+  for (let i = 0; i < slot.nNumLen; i++) {
+    if (slot.nNum[i] !== slot.kNum[i]) return false;
+  }
+  for (let i = 0; i < slot.nRefLen; i++) {
+    if (slot.nRef[i] !== slot.kRef[i]) return false;
+  }
+  return true;
+}
+
+/** Promotes this frame's candidate key to the committed key (call on rebuild). */
+export function scrollLayerCommitKey<Picture>(
+  slot: ScrollLayerSlot<Picture>
+): void {
+  'worklet';
+  for (let i = 0; i < slot.nNumLen; i++) slot.kNum[i] = slot.nNum[i]!;
+  for (let i = 0; i < slot.nRefLen; i++) slot.kRef[i] = slot.nRef[i]!;
+  slot.kNumLen = slot.nNumLen;
+  slot.kRefLen = slot.nRefLen;
+}
+
+/**
+ * Records a completed rebuild: stores the picture, captures the build-time
+ * reference `dx` will be measured against, and commits the key.
+ *
+ * These three are written together on purpose. `picture` is the slot's
+ * validity flag, and a picture whose `xRefAtBuild` came from a *different*
+ * `toX` than the one that positioned its content would render permanently
+ * offset — a bug with no visible symptom until the chart scrolls. Pass
+ * `xRefAtBuild` from the same `layout.toX(tRef)` call the recording used.
+ */
+export function scrollLayerBuilt<Picture>(
+  slot: ScrollLayerSlot<Picture>,
+  picture: Picture,
+  tRef: number,
+  xRefAtBuild: number
+): void {
+  'worklet';
+  slot.picture = picture;
+  slot.tRef = tRef;
+  slot.xRefAtBuild = xRefAtBuild;
+  scrollLayerCommitKey(slot);
+}
+
+/**
+ * Horizontal offset to composite this slot's picture at, in screen pixels.
+ *
+ * Always recomputed against the build-time reference, **never accumulated**.
+ * This is the identical formula lineCache.ts:189 uses, and the reasoning at
+ * lineCache.ts:166-175 applies unchanged: right after a fresh build, `tRef`
+ * and `xRefAtBuild` come from the very same `layout.toX` this frame, so the
+ * subtraction is exactly 0 with no special-casing; on a reused picture it
+ * recovers the full horizontal scroll since the build in one subtraction, so
+ * per-frame rounding error cannot compound over the thousands of frames a
+ * picture may survive.
+ *
+ * Never rewrite this as `slot.dx += perFrameDelta`. That drifts, and it drifts
+ * slowly enough to pass every test and only show up as a visibly misaligned
+ * axis after a chart has been left running for minutes.
+ */
+export function scrollLayerDx<Picture>(
+  slot: ScrollLayerSlot<Picture>,
+  layout: ChartLayout
+): number {
+  'worklet';
+  return layout.toX(slot.tRef) - slot.xRefAtBuild;
+}
+
+/**
+ * True when the slot may be composited this frame: it holds a picture and the
+ * composite alpha is exactly 1. See invariant 1 above — `drawPicture` ignores
+ * `globalAlpha`, so at alpha < 1 the consumer must fall back to live drawing
+ * rather than compositing at the wrong opacity. `>= 1` rather than `=== 1`
+ * mirrors draw/index.ts:218's `reveal >= 1`, which tolerates a lerp that
+ * overshoots to exactly its target.
+ */
+export function scrollLayerUsable<Picture>(
+  slot: ScrollLayerSlot<Picture>,
+  alpha: number
+): boolean {
+  'worklet';
+  return slot.picture !== null && alpha >= 1;
+}

From 4e8ac3f8d339536c46aea2ab8f0646afed43724d Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Thu, 30 Jul 2026 21:12:38 -0400
Subject: [PATCH 03/37] test: exclude .claude/ from jest module paths
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Agent worktrees under .claude/worktrees/ contain full copies of src/, so jest
was collecting every suite three extra times — 40 suites / 772 tests instead of
11 / 226. Git already excludes the path via .git/info/exclude; jest had no
equivalent rule, which made every verification run during parallel work
silently meaningless.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 package.json | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 09fa39d..d37e5b5 100644
--- a/package.json
+++ b/package.json
@@ -44,7 +44,8 @@
     "preset": "react-native",
     "modulePathIgnorePatterns": [
       "<rootDir>/example/node_modules",
-      "<rootDir>/lib/"
+      "<rootDir>/lib/",
+      "<rootDir>/.claude/"
     ]
   },
   "keywords": [

From 302df29736f844dc83638685e43829d852e02922 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Thu, 30 Jul 2026 21:12:38 -0400
Subject: [PATCH 04/37] feat(draw): time-axis pure layer logic (stage 3a)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Interval selection, label-key generation, overlap resolution and label-set
identity for the cached time-axis scroll layer, extracted as pure worklets with
a type-only Ctx2D import so jest can exercise them. Not wired in yet —
timeAxis.ts, draw/index.ts and engine/step.ts are untouched, so there is no
behavior change.

Overlap resolution is stride decimation on absolute time, not greedy
left-to-right. Greedy is deterministic for fixed input but NOT stable under
scroll: the chain is anchored on whichever label is currently leftmost, so the
frame a label leaves the left edge, every survivor swaps for its neighbour —
a visible flicker once per interval. The old per-label alpha tiebreak was
masking exactly this with a crossfade, and alpha is gone in the new design.
Keeping a label iff round(t/interval) % stride === 0 makes its fate depend only
on its own timestamp, so scrolling can never flip a survivor to a dropout.

Label-set identity carries interval and stride alongside count/first/last:
count+first+last alone collides for real (same span and count, different
stride) and that difference changes the picture.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/draw/__tests__/timeAxisLayer.test.ts | 535 +++++++++++++++++++++++
 src/draw/timeAxisLayer.ts                | 367 ++++++++++++++++
 2 files changed, 902 insertions(+)
 create mode 100644 src/draw/__tests__/timeAxisLayer.test.ts
 create mode 100644 src/draw/timeAxisLayer.ts

diff --git a/src/draw/__tests__/timeAxisLayer.test.ts b/src/draw/__tests__/timeAxisLayer.test.ts
new file mode 100644
index 0000000..537da6f
--- /dev/null
+++ b/src/draw/__tests__/timeAxisLayer.test.ts
@@ -0,0 +1,535 @@
+import {
+  timeAxisInterval,
+  timeAxisLabelKeys,
+  buildTimeAxisLabels,
+  timeAxisStride,
+  timeAxisLabelKept,
+  resolveTimeAxisOverlaps,
+  createTimeAxisLabelSetId,
+  writeTimeAxisLabelSetId,
+  timeAxisLabelSetIdMatches,
+} from '../timeAxisLayer';
+import type { TimeAxisLabel } from '../timeAxisLayer';
+import type { Ctx2D } from '../canvas2d';
+import type { ChartLayout, Padding } from '../../types';
+
+const PAD: Required<Padding> = { top: 10, right: 20, bottom: 24, left: 10 };
+
+/**
+ * A fake `Ctx2D` — a plain object with the font slots and `measureText`.
+ * This is the whole point of the type-only `Ctx2D` import in timeAxisLayer.ts:
+ * no Skia binding is loaded, so jest can drive the real code path.
+ * Width is `charW` per character so label widths are predictable and can be
+ * pushed past the overlap threshold on demand.
+ */
+function makeCtx(charW = 7): Ctx2D {
+  const fonts = {
+    label: 'label',
+    value: 'value',
+    badge: 'badge',
+    crosshair: 'crosshair',
+    orderbook: 'orderbook',
+    empty: 'empty',
+    refLabel: 'refLabel',
+    seriesLabel: 'seriesLabel',
+  };
+  return {
+    fonts,
+    font: fonts.label,
+    measureText: (text: string) => ({ width: text.length * charW }),
+  } as unknown as Ctx2D;
+}
+
+function makeLayout(
+  leftEdge: number,
+  rightEdge: number,
+  w = 400,
+  h = 200
+): ChartLayout {
+  const chartW = w - PAD.left - PAD.right;
+  const chartH = h - PAD.top - PAD.bottom;
+  const span = rightEdge - leftEdge || 1;
+  return {
+    w,
+    h,
+    pad: PAD,
+    chartW,
+    chartH,
+    leftEdge,
+    rightEdge,
+    minVal: 0,
+    maxVal: 1,
+    valRange: 1,
+    toX: (t: number) => PAD.left + ((t - leftEdge) / span) * chartW,
+    toY: (v: number) => PAD.top + (1 - v) * chartH,
+  };
+}
+
+/** Deterministic short formatter — no Date, so tests stay timezone-agnostic
+ * except where the day-alignment branch is deliberately exercised. */
+const fmt = (t: number) => String(Math.round(t));
+
+describe('timeAxisInterval', () => {
+  it('returns the nice interval when it already clears 60px', () => {
+    // 30s window over 600px => 20px/s => 5s ticks are 100px apart.
+    expect(timeAxisInterval(30, 600)).toBe(5);
+  });
+
+  it('doubles until ticks are at least 60px apart on a narrow chart', () => {
+    // 30s over 120px => 4px/s. 5s=20px, 10s=40px, 20s=80px.
+    expect(timeAxisInterval(30, 120)).toBe(20);
+  });
+
+  it('never returns an interval wider than the window itself', () => {
+    // A degenerate/zero-width chart would otherwise loop forever.
+    const interval = timeAxisInterval(60, 0);
+    expect(interval).toBeGreaterThanOrEqual(60);
+    expect(Number.isFinite(interval)).toBe(true);
+  });
+
+  it('is monotonic in window size across a sweep of real windows', () => {
+    const windows = [10, 15, 30, 60, 120, 300, 600, 1800, 3600, 86400, 604800];
+    let prev = 0;
+    for (const win of windows) {
+      const interval = timeAxisInterval(win, 600);
+      expect(interval).toBeGreaterThanOrEqual(prev);
+      prev = interval;
+    }
+  });
+
+  it('yields tick spacing >= 60px whenever the window allows it', () => {
+    const chartW = 370;
+    for (const win of [15, 30, 60, 120, 300, 600, 1800, 3600, 14400, 43200]) {
+      const interval = timeAxisInterval(win, chartW);
+      const spacing = interval * (chartW / win);
+      expect(spacing >= 60 || interval >= win).toBe(true);
+    }
+  });
+
+  it('derives from the target window, not the display window', () => {
+    // The function only takes the target window — the "one-frame flicker at
+    // transition end" bug is structurally impossible. Same target, different
+    // in-flight display windows, same answer.
+    expect(timeAxisInterval(60, 600)).toBe(timeAxisInterval(60, 600));
+  });
+});
+
+describe('timeAxisLabelKeys', () => {
+  it('covers the view plus one interval of buffer on each side', () => {
+    const out: number[] = [];
+    const n = timeAxisLabelKeys(10, 100, 160, out);
+    const times = out.slice(0, n).map((k) => k / 100);
+    expect(times[0]).toBeLessThanOrEqual(100);
+    expect(times[0]).toBeGreaterThanOrEqual(90 - 10);
+    expect(times[times.length - 1]).toBeGreaterThanOrEqual(160);
+    for (let i = 1; i < times.length; i++) {
+      expect(times[i]! - times[i - 1]!).toBeCloseTo(10);
+    }
+  });
+
+  it('emits ascending keys so no sort is needed downstream', () => {
+    const out: number[] = [];
+    const n = timeAxisLabelKeys(5, 1000, 1060, out);
+    for (let i = 1; i < n; i++) expect(out[i]!).toBeGreaterThan(out[i - 1]!);
+  });
+
+  it('aligns to local midnight for day-or-longer intervals', () => {
+    const out: number[] = [];
+    // Three days of view with 1-day ticks.
+    const start = Date.UTC(2026, 0, 10, 13, 45) / 1000;
+    const n = timeAxisLabelKeys(86400, start, start + 3 * 86400, out);
+    expect(n).toBeGreaterThan(0);
+    // The anchor label is exactly local midnight.
+    const first = new Date((out[0]! / 100) * 1000);
+    expect(first.getHours()).toBe(0);
+    expect(first.getMinutes()).toBe(0);
+    expect(first.getSeconds()).toBe(0);
+    expect(first.getMilliseconds()).toBe(0);
+  });
+
+  it('does not local-align sub-day intervals (epoch-multiple instead)', () => {
+    const out: number[] = [];
+    const n = timeAxisLabelKeys(3600, 7000, 14000, out);
+    expect(n).toBeGreaterThan(0);
+    for (let i = 0; i < n; i++) expect((out[i]! / 100) % 3600).toBe(0);
+  });
+
+  it('caps generation at 30 labels', () => {
+    const out: number[] = [];
+    // A wide→narrow transition: 1s ticks across a 10-minute display span.
+    const n = timeAxisLabelKeys(1, 0, 600, out);
+    expect(n).toBe(30);
+  });
+
+  it('reuses the caller array without reallocating', () => {
+    const out: number[] = [];
+    timeAxisLabelKeys(1, 0, 600, out);
+    const long = out.length;
+    const n = timeAxisLabelKeys(60, 0, 120, out);
+    expect(n).toBeLessThan(long);
+    // Stale entries past the returned count are left in place by design.
+    expect(out.length).toBe(long);
+  });
+});
+
+describe('buildTimeAxisLabels', () => {
+  it('culls labels past the right edge and beyond the left slack', () => {
+    const ctx = makeCtx();
+    const layout = makeLayout(0, 60); // chartW 370 => ~6.17px/s
+    const keys: number[] = [];
+    const n = timeAxisLabelKeys(10, 0, 60, keys);
+    const pool: TimeAxisLabel[] = [];
+    const count = buildTimeAxisLabels(ctx, keys, n, layout, fmt, pool);
+
+    const chartLeft = PAD.left;
+    const chartRight = layout.w - PAD.right;
+    for (let i = 0; i < count; i++) {
+      expect(pool[i]!.x).toBeGreaterThanOrEqual(chartLeft - 20);
+      expect(pool[i]!.x).toBeLessThanOrEqual(chartRight);
+    }
+    // The -10s buffer label sits ~62px left of chartLeft and is dropped.
+    expect(count).toBeLessThan(n);
+  });
+
+  it('measures through the passed-in ctx and sets the label font slot', () => {
+    const ctx = makeCtx(9);
+    const seen: string[] = [];
+    const spy = {
+      ...ctx,
+      measureText: (t: string) => {
+        seen.push(t);
+        return { width: t.length * 9 };
+      },
+    } as unknown as Ctx2D;
+    const layout = makeLayout(0, 60);
+    const keys: number[] = [];
+    const n = timeAxisLabelKeys(10, 0, 60, keys);
+    const pool: TimeAxisLabel[] = [];
+    const count = buildTimeAxisLabels(spy, keys, n, layout, fmt, pool);
+
+    expect(seen.length).toBe(count);
+    expect(spy.font).toBe(spy.fonts.label);
+    for (let i = 0; i < count; i++) {
+      expect(pool[i]!.w).toBe(pool[i]!.text.length * 9);
+    }
+  });
+
+  it('reuses pooled entries instead of allocating per rebuild', () => {
+    const ctx = makeCtx();
+    const layout = makeLayout(0, 60);
+    const keys: number[] = [];
+    const pool: TimeAxisLabel[] = [];
+    const n1 = timeAxisLabelKeys(10, 0, 60, keys);
+    buildTimeAxisLabels(ctx, keys, n1, layout, fmt, pool);
+    const identities = pool.slice();
+
+    const layout2 = makeLayout(5, 65);
+    const n2 = timeAxisLabelKeys(10, 5, 65, keys);
+    buildTimeAxisLabels(ctx, keys, n2, layout2, fmt, pool);
+    for (let i = 0; i < identities.length; i++) {
+      expect(pool[i]).toBe(identities[i]);
+    }
+  });
+
+  it('only calls the formatter for labels that survive culling', () => {
+    let calls = 0;
+    const counting = (t: number) => {
+      calls++;
+      return fmt(t);
+    };
+    const ctx = makeCtx();
+    const layout = makeLayout(0, 60);
+    const keys: number[] = [];
+    const n = timeAxisLabelKeys(10, 0, 60, keys);
+    const pool: TimeAxisLabel[] = [];
+    const count = buildTimeAxisLabels(ctx, keys, n, layout, counting, pool);
+    expect(calls).toBe(count);
+  });
+});
+
+describe('timeAxisStride / timeAxisLabelKept', () => {
+  function labelsAt(xs: number[], w: number): TimeAxisLabel[] {
+    return xs.map((x, i) => ({ key: i * 1000, x, text: 'x', w }));
+  }
+
+  it('is 1 when labels comfortably clear each other', () => {
+    expect(timeAxisStride(labelsAt([0, 100, 200, 300], 30), 4)).toBe(1);
+  });
+
+  it('grows to 2 when a label plus the 8px gap exceeds the spacing', () => {
+    // spacing 40, width 34 + 8 = 42 > 40 => stride 2 (84 <= 80? no) ...
+    // 42/40 = 1.05 => ceil 2.
+    expect(timeAxisStride(labelsAt([0, 40, 80, 120, 160], 34), 5)).toBe(2);
+  });
+
+  it('grows further when labels are very dense', () => {
+    const xs = [0, 10, 20, 30, 40, 50, 60, 70];
+    // (44 + 8) / 10 = 5.2 => 6
+    expect(timeAxisStride(labelsAt(xs, 44), xs.length)).toBe(6);
+  });
+
+  it('uses the widest label, not the average', () => {
+    const labels = labelsAt([0, 40, 80, 120], 20);
+    labels[2]!.w = 40; // one wide label forces the whole set to decimate
+    expect(timeAxisStride(labels, 4)).toBe(2);
+  });
+
+  it('uses the tightest adjacent spacing, not the mean', () => {
+    // A DST-shortened step: mostly 100px apart, one pair only 40px apart.
+    const labels = labelsAt([0, 100, 140, 240], 34);
+    expect(timeAxisStride(labels, 4)).toBe(2);
+  });
+
+  it('never exceeds the label count, so something always survives', () => {
+    const xs = [0, 1, 2, 3];
+    const stride = timeAxisStride(labelsAt(xs, 500), xs.length);
+    expect(stride).toBe(4);
+    const labels = labelsAt(xs, 500).map((l, i) => ({ ...l, key: i * 100 }));
+    const out: TimeAxisLabel[] = [];
+    const kept = resolveTimeAxisOverlaps(labels, labels.length, 1, stride, out);
+    expect(kept).toBeGreaterThan(0);
+  });
+
+  it('handles a single label and an empty set', () => {
+    expect(timeAxisStride([], 0)).toBe(1);
+    expect(timeAxisStride(labelsAt([50], 30), 1)).toBe(1);
+  });
+
+  it('keeps every label at stride 1', () => {
+    for (const key of [0, 500, 1000, 123400]) {
+      expect(timeAxisLabelKept(key, 5, 1)).toBe(true);
+    }
+  });
+
+  it('decides purely from the label timestamp, not from scan position', () => {
+    // interval 10s => keys are multiples of 1000 centiseconds.
+    expect(timeAxisLabelKept(0, 10, 2)).toBe(true);
+    expect(timeAxisLabelKept(1000, 10, 2)).toBe(false);
+    expect(timeAxisLabelKept(2000, 10, 2)).toBe(true);
+  });
+
+  it('normalises negative (pre-epoch) indices', () => {
+    expect(timeAxisLabelKept(-2000, 10, 2)).toBe(true);
+    expect(timeAxisLabelKept(-1000, 10, 2)).toBe(false);
+    expect(timeAxisLabelKept(-3000, 10, 3)).toBe(true);
+  });
+});
+
+describe('overlap resolution determinism under scrolling', () => {
+  /** Runs one "frame": generate, build, resolve. Returns the kept keys. */
+  function frame(
+    ctx: Ctx2D,
+    leftEdge: number,
+    rightEdge: number,
+    interval: number,
+    w = 400
+  ): { keys: number[]; stride: number } {
+    const layout = makeLayout(leftEdge, rightEdge, w);
+    const raw: number[] = [];
+    const n = timeAxisLabelKeys(interval, leftEdge, rightEdge, raw);
+    const pool: TimeAxisLabel[] = [];
+    const count = buildTimeAxisLabels(ctx, raw, n, layout, fmt, pool);
+    const stride = timeAxisStride(pool, count);
+    const out: TimeAxisLabel[] = [];
+    const kept = resolveTimeAxisOverlaps(pool, count, interval, stride, out);
+    return { keys: out.slice(0, kept).map((l) => l.key), stride };
+  }
+
+  it('never changes a surviving label back into a dropped one while scrolling', () => {
+    // Wide labels at a tight interval => spacing ~31px vs 44px needed, so
+    // the run genuinely decimates rather than trivially keeping everything.
+    const ctx = makeCtx(9);
+    const interval = 5;
+    const span = 60;
+    // Every key we have ever seen at all, and whether it was kept.
+    const verdicts = new Map<number, boolean>();
+    for (let step = 0; step < 400; step++) {
+      const left = 1000 + step * 0.25; // sub-interval scroll, 100s of travel
+      const { keys } = frame(ctx, left, left + span, interval);
+      const keptSet = new Set(keys);
+      // Rebuild the full visible set to know which keys were considered.
+      const raw: number[] = [];
+      const n = timeAxisLabelKeys(interval, left, left + span, raw);
+      const layout = makeLayout(left, left + span);
+      const pool: TimeAxisLabel[] = [];
+      const count = buildTimeAxisLabels(ctx, raw, n, layout, fmt, pool);
+      for (let i = 0; i < count; i++) {
+        const key = pool[i]!.key;
+        const kept = keptSet.has(key);
+        const prior = verdicts.get(key);
+        if (prior !== undefined) expect(kept).toBe(prior);
+        verdicts.set(key, kept);
+      }
+    }
+    // Sanity: the scenario actually exercised decimation.
+    expect([...verdicts.values()].some((v) => !v)).toBe(true);
+    expect([...verdicts.values()].some((v) => v)).toBe(true);
+  });
+
+  it('keeps the stride constant while scrolling at a fixed zoom', () => {
+    const ctx = makeCtx(9);
+    const strides = new Set<number>();
+    for (let step = 0; step < 200; step++) {
+      const left = 1000 + step * 0.37;
+      strides.add(frame(ctx, left, left + 60, 10).stride);
+    }
+    expect(strides.size).toBe(1);
+  });
+
+  it('is idempotent: the same inputs always produce the same set', () => {
+    const ctx = makeCtx(9);
+    const a = frame(ctx, 1234.5, 1294.5, 10);
+    const b = frame(ctx, 1234.5, 1294.5, 10);
+    expect(a.keys).toEqual(b.keys);
+    expect(a.stride).toBe(b.stride);
+  });
+
+  it('resolved labels never overlap, including the 8px gap', () => {
+    const ctx = makeCtx(9);
+    const interval = 10;
+    for (let step = 0; step < 120; step++) {
+      const left = 500 + step * 0.5;
+      const layout = makeLayout(left, left + 60);
+      const raw: number[] = [];
+      const n = timeAxisLabelKeys(interval, left, left + 60, raw);
+      const pool: TimeAxisLabel[] = [];
+      const count = buildTimeAxisLabels(ctx, raw, n, layout, fmt, pool);
+      const stride = timeAxisStride(pool, count);
+      const out: TimeAxisLabel[] = [];
+      const kept = resolveTimeAxisOverlaps(pool, count, interval, stride, out);
+      for (let i = 1; i < kept; i++) {
+        const prevRight = out[i - 1]!.x + out[i - 1]!.w / 2;
+        const left2 = out[i]!.x - out[i]!.w / 2;
+        expect(left2).toBeGreaterThanOrEqual(prevRight + 8 - 1e-9);
+      }
+    }
+  });
+
+  it('swaps the whole set coherently when the zoom changes', () => {
+    const ctx = makeCtx(9);
+    const dense = frame(ctx, 1000, 1060, 10);
+    const sparse = frame(ctx, 1000, 1060, 20);
+    expect(sparse.keys.length).toBeLessThanOrEqual(dense.keys.length);
+  });
+
+  it('out holds references into labels, never fresh objects', () => {
+    const labels: TimeAxisLabel[] = [0, 1, 2, 3].map((i) => ({
+      key: i * 1000,
+      x: i * 100,
+      text: 't',
+      w: 20,
+    }));
+    const out: TimeAxisLabel[] = [];
+    const kept = resolveTimeAxisOverlaps(labels, 4, 10, 2, out);
+    expect(kept).toBe(2);
+    expect(out[0]).toBe(labels[0]);
+    expect(out[1]).toBe(labels[2]);
+  });
+});
+
+describe('label-set identity', () => {
+  function labels(keys: number[]): TimeAxisLabel[] {
+    return keys.map((key, i) => ({ key, x: i * 50, text: 't', w: 20 }));
+  }
+
+  it('starts unmatched against any real set', () => {
+    const id = createTimeAxisLabelSetId();
+    expect(timeAxisLabelSetIdMatches(id, labels([1000, 2000]), 2, 10, 1)).toBe(
+      false
+    );
+  });
+
+  it('matches after a write with the same set', () => {
+    const id = createTimeAxisLabelSetId();
+    const set = labels([1000, 2000, 3000]);
+    writeTimeAxisLabelSetId(id, set, 3, 10, 1);
+    expect(timeAxisLabelSetIdMatches(id, set, 3, 10, 1)).toBe(true);
+  });
+
+  it('invalidates when a label scrolls in or out', () => {
+    const id = createTimeAxisLabelSetId();
+    writeTimeAxisLabelSetId(id, labels([1000, 2000, 3000]), 3, 10, 1);
+    // One scrolled off the left, one on at the right.
+    expect(
+      timeAxisLabelSetIdMatches(id, labels([2000, 3000, 4000]), 3, 10, 1)
+    ).toBe(false);
+    // Count grew.
+    expect(
+      timeAxisLabelSetIdMatches(id, labels([1000, 2000, 3000, 4000]), 4, 10, 1)
+    ).toBe(false);
+  });
+
+  it('invalidates on an interval change even at identical endpoints', () => {
+    const id = createTimeAxisLabelSetId();
+    writeTimeAxisLabelSetId(id, labels([0, 1000, 2000]), 3, 10, 1);
+    expect(
+      timeAxisLabelSetIdMatches(id, labels([0, 1000, 2000]), 3, 5, 1)
+    ).toBe(false);
+  });
+
+  it('invalidates on a stride change even at identical endpoints', () => {
+    // This is the collision `count + first + last` alone would miss: same
+    // span, same count of *generated* labels, different kept subset.
+    const id = createTimeAxisLabelSetId();
+    writeTimeAxisLabelSetId(id, labels([0, 2000, 4000]), 3, 10, 2);
+    expect(
+      timeAxisLabelSetIdMatches(id, labels([0, 2000, 4000]), 3, 10, 1)
+    ).toBe(false);
+  });
+
+  it('is exact for the arithmetic sets this module generates', () => {
+    // Reconstruct every set produced across a scroll and confirm that no two
+    // distinct sets share an identity.
+    const ctx = makeCtx();
+    const seen = new Map<string, string>();
+    for (let step = 0; step < 300; step++) {
+      const left = 1000 + step * 0.4;
+      const layout = makeLayout(left, left + 60);
+      const raw: number[] = [];
+      const n = timeAxisLabelKeys(10, left, left + 60, raw);
+      const pool: TimeAxisLabel[] = [];
+      const count = buildTimeAxisLabels(ctx, raw, n, layout, fmt, pool);
+      const stride = timeAxisStride(pool, count);
+      const out: TimeAxisLabel[] = [];
+      const kept = resolveTimeAxisOverlaps(pool, count, 10, stride, out);
+      const id = createTimeAxisLabelSetId();
+      writeTimeAxisLabelSetId(id, out, kept, 10, stride);
+      const idStr = `${id.count}|${id.firstKey}|${id.lastKey}|${id.interval}|${id.stride}`;
+      const setStr = out
+        .slice(0, kept)
+        .map((l) => l.key)
+        .join(',');
+      const prior = seen.get(idStr);
+      if (prior !== undefined) expect(setStr).toBe(prior);
+      seen.set(idStr, setStr);
+    }
+    expect(seen.size).toBeGreaterThan(1);
+  });
+
+  it('ignores x positions — those are the scroll layer dx, not a rebuild', () => {
+    const id = createTimeAxisLabelSetId();
+    const a = labels([1000, 2000, 3000]);
+    writeTimeAxisLabelSetId(id, a, 3, 10, 1);
+    const b = labels([1000, 2000, 3000]);
+    for (const l of b) l.x += 37.5;
+    expect(timeAxisLabelSetIdMatches(id, b, 3, 10, 1)).toBe(true);
+  });
+
+  it('does NOT see text changes — the slot must key formatTime separately', () => {
+    // Documented limitation, asserted so it cannot regress silently.
+    const id = createTimeAxisLabelSetId();
+    const a = labels([1000, 2000]);
+    writeTimeAxisLabelSetId(id, a, 2, 10, 1);
+    const b = labels([1000, 2000]);
+    for (const l of b) l.text = 'COMPLETELY DIFFERENT';
+    expect(timeAxisLabelSetIdMatches(id, b, 2, 10, 1)).toBe(true);
+  });
+
+  it('handles the empty set without reading past the end', () => {
+    const id = createTimeAxisLabelSetId();
+    writeTimeAxisLabelSetId(id, [], 0, 10, 1);
+    expect(id.firstKey).toBe(0);
+    expect(id.lastKey).toBe(0);
+    expect(timeAxisLabelSetIdMatches(id, [], 0, 10, 1)).toBe(true);
+  });
+});
diff --git a/src/draw/timeAxisLayer.ts b/src/draw/timeAxisLayer.ts
new file mode 100644
index 0000000..e003b01
--- /dev/null
+++ b/src/draw/timeAxisLayer.ts
@@ -0,0 +1,367 @@
+import type { ChartLayout } from '../types';
+import { niceTimeInterval } from '../math/intervals';
+import type { Ctx2D } from './canvas2d';
+
+/**
+ * Pure label-selection logic for the cached time-axis scroll layer.
+ *
+ * `draw/timeAxis.ts` re-derives all of this every frame at 60fps: the
+ * interval, a `formatTime()` call per label (the default formatter allocates
+ * a `Date` plus three `padStart` results *per label per frame*), a `Map` walk
+ * with per-label alpha lerps, text measurement, a sort, and overlap
+ * resolution. Under the scroll-layer architecture the axis is baked into a
+ * cached `SkPicture` and composited at a horizontal offset, so all of this
+ * runs only when the label set actually changes — roughly once per `interval`
+ * seconds instead of 60 times per second.
+ *
+ * Two deliberate differences from `timeAxis.ts`:
+ *
+ * 1. **No per-label alpha.** Labels bake at alpha 1; the 50px edge fade
+ *    (`timeAxis.ts:65-72`) becomes a gradient `destination-out` erase over the
+ *    axis strip in the screen pass. Label visibility is therefore a pure
+ *    function of position — which is what makes this module testable.
+ * 2. **Positional overlap resolution.** The alpha tiebreak ("keep the
+ *    higher-alpha one", `timeAxis.ts:184-198`) has no meaning without alpha.
+ *    See `timeAxisStride` for the replacement and its determinism argument.
+ *
+ * Skia-free by construction: `Ctx2D` is imported as a **type only**, exactly
+ * like `timeAxis.ts` does, so jest can drive this with a plain fake context.
+ * Do not add a value import from `@shopify/react-native-skia` here — it would
+ * pull the native binding into the test process and this module would become
+ * as untestable as `draw/index.ts`.
+ *
+ * Nothing in this module allocates per call: every producer writes into a
+ * caller-owned array that it grows once and then reuses, the same pooling
+ * discipline `TimeAxisState` already documents.
+ */
+
+/** Minimum on-screen spacing between tick positions, in px. Below this the
+ * interval is doubled. Matches `timeAxis.ts:81`. */
+const MIN_TICK_SPACING_PX = 60;
+
+/** Minimum clear gap between two rendered label boxes, in px. Matches the
+ * `+ 8` slack in `timeAxis.ts:189`. */
+const LABEL_GAP_PX = 8;
+
+/** How far left of the plot area a label may sit and still be built. A label
+ * whose centre is just off the left edge still has its right half visible, so
+ * culling exactly at `chartLeft` would pop it. Matches `timeAxis.ts:161`. */
+const LEFT_CULL_SLACK_PX = 20;
+
+/** Hard cap on generated labels. During a wide→narrow window transition the
+ * target interval can be tiny relative to the currently-displayed span, so the
+ * generation loop is bounded rather than trusted. Matches `timeAxis.ts:102`. */
+const MAX_LABELS = 30;
+
+/** One built label, pooled across rebuilds. `key` is the label's timestamp in
+ * centiseconds (`Math.round(t * 100)`) — the same integer key `timeAxis.ts`
+ * uses, chosen so day-aligned times that land on fractional seconds still
+ * compare exactly. */
+export interface TimeAxisLabel {
+  /** `Math.round(t * 100)` — timestamp in centiseconds. */
+  key: number;
+  /** Build-time screen X. Only valid for the layout it was built with; the
+   * scroll layer re-derives the frame's X by translating the whole picture. */
+  x: number;
+  text: string;
+  /** Measured width via `ctx.measureText`, which is cached upstream by
+   * font slot + string in `canvas2d.ts`. */
+  w: number;
+}
+
+/**
+ * Picks the tick interval in seconds.
+ *
+ * Ported verbatim from `timeAxis.ts:79-83`. Two invariants worth preserving:
+ *
+ * - It is derived from the **target** window, never the interpolating display
+ *   window. Deriving it from the display window makes the interval change
+ *   mid-transition and flicker for one frame when `windowSecs` snaps to
+ *   `targetWindowSecs` at the end of the transition.
+ * - The doubling loop is bounded by `interval < targetWindowSecs`, so a
+ *   degenerate `chartW` (0, or a first-frame layout) cannot spin forever.
+ */
+export function timeAxisInterval(
+  targetWindowSecs: number,
+  chartW: number
+): number {
+  'worklet';
+  const targetPxPerSec = chartW / targetWindowSecs;
+  let interval = niceTimeInterval(targetWindowSecs);
+  while (
+    interval * targetPxPerSec < MIN_TICK_SPACING_PX &&
+    interval < targetWindowSecs
+  ) {
+    interval *= 2;
+  }
+  return interval;
+}
+
+/**
+ * Generates the label timestamps for the current view, plus one interval of
+ * buffer on each side so a label is already built before it scrolls in.
+ *
+ * Ported from `timeAxis.ts:89-106`. Writes ascending centisecond keys into
+ * `out` and returns how many are valid; `out` is grown once and reused, never
+ * reallocated, and entries past the returned count are stale.
+ *
+ * For intervals of a day or more the sequence is anchored to **local**
+ * midnight rather than the UTC epoch, because a "1 Feb" tick drawn at 19:00
+ * the previous day is simply wrong to a user. Note the anchor is applied only
+ * to the first label and the rest step by a fixed `interval`; across a DST
+ * boundary later labels therefore drift an hour off local midnight. That is
+ * existing `timeAxis.ts` behaviour and is preserved deliberately — changing it
+ * belongs in a separate change with its own visual verification.
+ */
+export function timeAxisLabelKeys(
+  interval: number,
+  leftEdge: number,
+  rightEdge: number,
+  out: number[]
+): number {
+  'worklet';
+  const useLocalDays = interval >= 86400;
+  let firstTime: number;
+  if (useLocalDays) {
+    const d = new Date((leftEdge - interval) * 1000);
+    d.setHours(0, 0, 0, 0);
+    firstTime = d.getTime() / 1000;
+  } else {
+    firstTime = Math.ceil((leftEdge - interval) / interval) * interval;
+  }
+
+  let count = 0;
+  for (
+    let t = firstTime;
+    t <= rightEdge + interval && count < MAX_LABELS;
+    t += interval
+  ) {
+    out[count] = Math.round(t * 100);
+    count++;
+  }
+  return count;
+}
+
+/**
+ * Formats and measures the subset of `keys` that is actually on screen.
+ *
+ * Writes into `pool` (grown once, entries reused across rebuilds — a given
+ * slot backs a different label on every rebuild, which is safe because every
+ * field is overwritten) and returns the valid count. Output stays ascending
+ * because `timeAxisLabelKeys` emits ascending keys, so the sort
+ * `timeAxis.ts:176` performs every frame is not needed here.
+ *
+ * `ctx` is used only for `measureText`, which `canvas2d.ts` caches by font
+ * slot + string; the font slot is set here so that cache is keyed correctly.
+ */
+export function buildTimeAxisLabels(
+  ctx: Ctx2D,
+  keys: number[],
+  keyCount: number,
+  layout: ChartLayout,
+  formatTime: (t: number) => string,
+  pool: TimeAxisLabel[]
+): number {
+  'worklet';
+  ctx.font = ctx.fonts.label;
+  const chartLeft = layout.pad.left;
+  const chartRight = layout.w - layout.pad.right;
+
+  let count = 0;
+  for (let i = 0; i < keyCount; i++) {
+    const key = keys[i]!;
+    const x = layout.toX(key / 100);
+    if (x < chartLeft - LEFT_CULL_SLACK_PX || x > chartRight) continue;
+    const text = formatTime(key / 100);
+    const w = ctx.measureText(text).width;
+    const entry = pool[count];
+    if (!entry) {
+      pool[count] = { key, x, text, w };
+    } else {
+      entry.key = key;
+      entry.x = x;
+      entry.text = text;
+      entry.w = w;
+    }
+    count++;
+  }
+  return count;
+}
+
+/**
+ * Chooses the decimation stride that resolves label overlap — the positional
+ * replacement for the alpha tiebreak at `timeAxis.ts:184-198`.
+ *
+ * **Why not greedy left-to-right?** The obvious replacement ("walk sorted by
+ * X, drop anything colliding with the last kept label") is deterministic for a
+ * fixed input but *not* stable under scrolling: the greedy chain is anchored
+ * on whichever label is currently leftmost, so the moment the leftmost label
+ * scrolls out the whole chain shifts by one and every surviving label swaps
+ * for its neighbour. On a continuously scrolling chart that is a visible
+ * flicker once per interval, and it is exactly the failure the old alpha
+ * tiebreak was papering over.
+ *
+ * **The rule instead:** keep a label iff its *absolute* interval index
+ * `round(t / interval)` is a multiple of `stride`. The decision depends only
+ * on the label's own timestamp and on `stride`, never on which labels happen
+ * to be on screen, so a label's fate is identical on every frame it is
+ * visible. Scrolling can never change a surviving label into a dropped one.
+ *
+ * `stride` itself is derived from view-scale quantities — the on-screen
+ * spacing between consecutive ticks and the widest label in the set — not from
+ * scan order. At a fixed zoom the spacing is constant, so `stride` is constant
+ * and the kept set is fully scroll-invariant. The one residual way `stride`
+ * can move without a zoom change is a wider label class scrolling in (`9:59`
+ * → `10:00`). That flips the whole set at once, coherently, which is the
+ * "hard swap" the design already accepts — not a two-label flicker.
+ *
+ * Spacing is taken as the **minimum** adjacent gap rather than the mean so an
+ * irregular step (a DST-shortened day) tightens the stride rather than being
+ * averaged away into an overlap.
+ *
+ * Clamped to `count` so at least one label always survives: keys are
+ * consecutive integer indices, and any `count` consecutive integers contain a
+ * multiple of any stride ≤ `count`.
+ */
+export function timeAxisStride(labels: TimeAxisLabel[], count: number): number {
+  'worklet';
+  if (count < 2) return 1;
+
+  let minSpacing = Infinity;
+  let maxW = 0;
+  for (let i = 0; i < count; i++) {
+    const w = labels[i]!.w;
+    if (w > maxW) maxW = w;
+    if (i > 0) {
+      const gap = labels[i]!.x - labels[i - 1]!.x;
+      if (gap < minSpacing) minSpacing = gap;
+    }
+  }
+
+  // Degenerate geometry (zero or negative spacing) — nothing sensible to
+  // decimate towards, so keep one label rather than loop.
+  if (!(minSpacing > 0)) return count;
+
+  const needed = maxW + LABEL_GAP_PX;
+  let stride = Math.ceil(needed / minSpacing);
+  if (stride < 1) stride = 1;
+  if (stride > count) stride = count;
+  return stride;
+}
+
+/** True when this label survives decimation at `stride`. Pure in the label's
+ * own timestamp — see `timeAxisStride` for why that matters. */
+export function timeAxisLabelKept(
+  key: number,
+  interval: number,
+  stride: number
+): boolean {
+  'worklet';
+  if (stride <= 1) return true;
+  const index = Math.round(key / (100 * interval));
+  // Keys before the epoch give a negative index; JS `%` keeps the sign, so
+  // normalise before comparing or pre-1970 charts would drop everything.
+  return ((index % stride) + stride) % stride === 0;
+}
+
+/**
+ * Applies `timeAxisLabelKept` to a built label list.
+ *
+ * `stride` is passed in rather than derived here because the caller also needs
+ * it for the invalidation key (see `TimeAxisLabelSetId`) and it must be the
+ * same value in both places — deriving it twice invites them to diverge.
+ *
+ * `out` holds **references into `labels`**, never its own objects — the same
+ * contract `TimeAxisState.drawnScratch` documents. Returns the kept count;
+ * entries past it are stale.
+ */
+export function resolveTimeAxisOverlaps(
+  labels: TimeAxisLabel[],
+  count: number,
+  interval: number,
+  stride: number,
+  out: TimeAxisLabel[]
+): number {
+  'worklet';
+  let kept = 0;
+  for (let i = 0; i < count; i++) {
+    const label = labels[i]!;
+    if (!timeAxisLabelKept(label.key, interval, stride)) continue;
+    out[kept] = label;
+    kept++;
+  }
+  return kept;
+}
+
+/**
+ * Cheap identity for the drawn label set, used as part of the `axisScroll`
+ * picture invalidation key.
+ *
+ * **Is `count + firstKey + lastKey` collision-free?** For sets produced by
+ * `timeAxisLabelKeys` + `resolveTimeAxisOverlaps`, yes — and not merely
+ * "cheap and good enough". The generator emits a strictly ascending arithmetic
+ * sequence with step `interval`, and decimation keeps a fixed-stride subset of
+ * it, so `(interval, stride, firstKey, count)` reconstructs the whole set
+ * exactly; `lastKey` is redundant but is retained as a cheap guard against the
+ * one non-arithmetic case, the local-midnight anchor across a DST boundary.
+ * `interval` and `stride` are therefore carried in this identity rather than
+ * assumed — with only `count/first/last` the set genuinely *would* be
+ * ambiguous (same span, different stride).
+ *
+ * What it does **not** cover, by design:
+ *
+ * - **Label text.** Two different formatter outputs for the same timestamps
+ *   compare equal here. The slot key covers this separately by holding
+ *   `formatTime` by reference; a formatter closing over mutable state (a
+ *   locale that changes in place) would slip through both. Callers that swap
+ *   formatting must swap the function identity.
+ * - **Positions.** `x` moves every frame; that is the scroll layer's `dx`
+ *   translation, not a rebuild trigger, and is deliberately absent.
+ */
+export interface TimeAxisLabelSetId {
+  count: number;
+  firstKey: number;
+  lastKey: number;
+  interval: number;
+  stride: number;
+}
+
+export function createTimeAxisLabelSetId(): TimeAxisLabelSetId {
+  'worklet';
+  return { count: 0, firstKey: 0, lastKey: 0, interval: 0, stride: 0 };
+}
+
+/** Writes the identity of `labels[0..count)` into `id` (call on a rebuild). */
+export function writeTimeAxisLabelSetId(
+  id: TimeAxisLabelSetId,
+  labels: TimeAxisLabel[],
+  count: number,
+  interval: number,
+  stride: number
+): void {
+  'worklet';
+  id.count = count;
+  id.firstKey = count > 0 ? labels[0]!.key : 0;
+  id.lastKey = count > 0 ? labels[count - 1]!.key : 0;
+  id.interval = interval;
+  id.stride = stride;
+}
+
+/** True when `labels[0..count)` has the same identity as `id`. Allocation-free
+ * so it is safe to call every frame. */
+export function timeAxisLabelSetIdMatches(
+  id: TimeAxisLabelSetId,
+  labels: TimeAxisLabel[],
+  count: number,
+  interval: number,
+  stride: number
+): boolean {
+  'worklet';
+  return (
+    id.count === count &&
+    id.interval === interval &&
+    id.stride === stride &&
+    id.firstKey === (count > 0 ? labels[0]!.key : 0) &&
+    id.lastKey === (count > 0 ? labels[count - 1]!.key : 0)
+  );
+}

From 1f71eb69c0e81deb045081277dec45aba4d5bda8 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Thu, 30 Jul 2026 21:14:14 -0400
Subject: [PATCH 05/37] docs: Android profiling procedure + release build
 script
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds example build:android:release and docs/android-profiling.md, the Android
counterpart to run-and-profile's iOS CPU A/B discipline. Every command in the
doc is marked verified-on-emulator or explicitly unverified.

Main finding: dumpsys gfxinfo framestats is BLIND to this app and must not be
used as the A/B metric. Measured on a release build over 103 clean frames,
ui_record (the HWUI display-list record pass) p50 = 0.10ms — empty.
SurfaceFlinger --list shows no separate SurfaceView layer, so react-native-skia
presents an externally-updated texture: HWUI composites one quad while all
engine work happens on a thread framestats never samples. The 138ms 'total' is
the engine's own frame pacing, not cost. Recorded as a negative result with a
re-test recipe rather than deleted.

Primary metric is therefore per-thread CPU, with Perfetto for the per-frame
timeline. A rendering change should move the main thread; a delta in mqt_v_js
means the example app's workload changed instead.

Also documents three traps hit during verification: hw.gpu.enabled=no is still
persisted in the liveline_test AVD (the -gpu host launch flag overrides it, and
getprop ro.hardware.egl cannot detect the difference — only the SurfaceFlinger
GLES string can); example/android is expo-prebuild output and untracked, so it
is absent in a git worktree; and this Android 34 build emits 23 framestats
columns, so parsers must key on column name, not index.

Emulator only. Physical-hardware baseline remains open.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 docs/android-profiling.md | 347 ++++++++++++++++++++++++++++++++++++++
 example/package.json      |   1 +
 2 files changed, 348 insertions(+)
 create mode 100644 docs/android-profiling.md

diff --git a/docs/android-profiling.md b/docs/android-profiling.md
new file mode 100644
index 0000000..c14dd5d
--- /dev/null
+++ b/docs/android-profiling.md
@@ -0,0 +1,347 @@
+# Android profiling
+
+How to measure a `src/` rendering change on Android without producing a number
+that is silently wrong.
+
+Companion to `.claude/skills/run-and-profile/SKILL.md` (iOS CPU A/B + simpleperf
+symbol attribution). That skill's Part 2 discipline is the model; this doc ports
+it to Android.
+
+**Package id: `liveline.example`** — no `com.` prefix.
+
+Every command below was executed on the `liveline_test` emulator (Android 34,
+`google_apis`, arm64, Apple M2 host) against a release build on 2026-07-30,
+except where explicitly marked **unverified**.
+
+---
+
+## 0. Why not fps, and why not `gfxinfo` either
+
+The engine paces frames at ~60 (`MIN_FRAME_INTERVAL_MS = 15` in
+`src/engine/constants.ts`). Both arms of any A/B will read 60fps no matter how
+much cheaper each frame got. **Measure frame *time* and CPU, never frame rate.**
+Any procedure that reports fps has measured the pacing constant.
+
+The obvious next reach is `dumpsys gfxinfo <pkg> framestats`. **On this app it
+does not measure the thing you care about** — see §3. It is documented here so
+the next person does not have to rediscover that, but the primary metric is
+per-thread CPU (§4) and the per-frame timeline comes from Perfetto (§5).
+
+---
+
+## 1. Preconditions — check both, every session
+
+Android measurement on this project has been invalidated twice. Both causes are
+invisible in the numbers: you get a plausible-looking result that is simply
+wrong. Run both checks and record the output alongside every number.
+
+### 1a. GPU acceleration is actually on
+
+The `liveline_test` AVD has **`hw.gpu.enabled=no`** persisted in its config
+(still true as of 2026-07-30), which software-renders everything.
+
+```bash
+grep hw.gpu ~/.android/avd/liveline_test.avd/config.ini
+```
+
+**The launch flag overrides the config file** — verified — so the cheap fix is
+to always pass `-gpu host`:
+
+```bash
+emulator -avd liveline_test -gpu host -no-snapshot -no-boot-anim &
+```
+
+Permanent fix, if you prefer not to remember the flag — edit
+`~/.android/avd/liveline_test.avd/config.ini` while the emulator is **not**
+running: set `hw.gpu.enabled=yes` and `hw.gpu.mode=host`.
+
+Either way, **verify from the guest** rather than trusting the flag. Do not use
+`getprop ro.hardware.egl` — it reads `emulation` in both the accelerated and the
+software case and will happily confirm a broken setup. The renderer string is
+the real signal:
+
+```bash
+adb shell dumpsys SurfaceFlinger | grep GLES
+```
+
+Good (host GPU) — names real hardware. Actual output from a correct boot:
+
+```
+GLES: Google (Apple), Android Emulator OpenGL ES Translator (Apple M2), OpenGL ES 3.0 (4.1 Metal - 90.5)
+```
+
+Bad — if the string contains **SwiftShader**, or otherwise names no real GPU,
+you are software-rendering. Stop; do not record a number.
+
+### 1b. Host load
+
+This is a **shared** machine and has been measured at load average 24. Relative
+deltas survive moderate load; absolute numbers do not.
+
+```bash
+uptime
+```
+
+Log it **per arm**. Under ~8 on the 8-core box is workable; above that,
+within-arm spread widens and the comparison stops meaning anything. If the two
+arms ran at meaningfully different load the comparison is void — re-run, don't
+try to correct for it.
+
+---
+
+## 2. Build and install the release APK
+
+Release matters: Debug inflates the Hermes share and adds dev-mode overhead, so
+a Debug A/B overstates JS cost and understates a Skia win. Release also embeds
+the JS bundle, so **no Metro server and no `adb reverse`** — one less variable
+between arms.
+
+`example/android/app/build.gradle` reads `android.enableMinifyInReleaseBuilds`
+(defaults **false**) and the `release` buildType is already signed with the
+**debug keystore**, so this needs no new signing setup.
+
+```bash
+cd example
+npm run build:android:release      # gradlew assembleRelease
+```
+
+Verified: `BUILD SUCCESSFUL in 1m 16s` (warm Gradle cache), producing
+`example/android/app/build/outputs/apk/release/app-release.apk` (~115 MB,
+unminified).
+
+Two setup traps, both hit on first run:
+
+- **`example/android/` is generated by `expo prebuild` and is not tracked by
+  git**, so it is missing in a fresh worktree. Build from the main checkout, or
+  run `npx expo prebuild -p android` first.
+- **`Unable to locate a Java Runtime`** — the Homebrew JDK is installed but not
+  symlinked into `/Library/Java/JavaVirtualMachines`, so `/usr/libexec/java_home`
+  cannot see it and Gradle dies. Export it explicitly:
+
+  ```bash
+  export JAVA_HOME=/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home
+  ```
+
+Install and launch:
+
+```bash
+adb install -r example/android/app/build/outputs/apk/release/app-release.apk
+adb shell am start -n liveline.example/.MainActivity
+```
+
+Use `am start`. The `adb shell monkey -p liveline.example ...` form quoted in
+the iOS skill **fails on this release build** (exits 251, no process starts).
+
+Let it settle ~20s before measuring. Use the default **Line** tab where
+possible: it survives a relaunch with no navigation, removing a variance source.
+
+**Screenshot the baseline arm.** If the old `src/` throws, you are timing a red
+error screen — cheap to render, looks like a huge win.
+
+---
+
+## 3. `gfxinfo framestats` — measured, and blind to this app
+
+Recorded here as a negative result. **Do not use it as the A/B metric.**
+
+```bash
+adb shell dumpsys gfxinfo liveline.example reset     # counters are cumulative
+# ... let the chart animate ~10s ...
+adb shell dumpsys gfxinfo liveline.example framestats > /tmp/fs.csv
+```
+
+Actual measurement, release build, chart animating, 103 clean frames:
+
+```
+total      n=103 p50= 138.46ms p95= 302.42ms
+ui_record  n=103 p50=   0.10ms p95=   1.39ms
+render     n=103 p50=  23.00ms p95=  47.97ms
+gpu        n=103 p50=  22.51ms p95=  47.97ms
+```
+
+**`ui_record` (`SyncQueued - DrawStart`) is 0.10ms.** That is the HWUI
+display-list record pass — and it is empty. Liveline's Skia rendering does not
+go through it. `dumpsys SurfaceFlinger --list` shows no separate SurfaceView
+layer for the app, so react-native-skia is presenting an externally-updated
+texture into the window: HWUI composites one quad (0.1ms) while all the engine
+work happens on a thread framestats never samples.
+
+The other columns are equally untrustworthy here. `total` is measured from
+`IntendedVsync`, so for a *paced* app it mostly counts time the app deliberately
+spent not drawing — 138ms is the pacing, not the cost. The summary histogram
+reports `95th gpu percentile: 4950ms`, an obvious emulator artifact. And
+`Janky frames: 85.92%` is a consequence of pacing to ~60 while HWUI expects
+every vsync, not evidence of a problem.
+
+If you ever need to check whether framestats has become useful (e.g. after a
+react-native-skia rendering-path change), the test is: capture with the chart
+animating and again with it idle. **If `ui_record` p50 does not differ, it is
+still blind.** Parse by column *name* — this Android 34 build emits 23 columns
+(`FrameTimelineVsyncId`, `FrameDeadline`, `FrameInterval`, `FrameStartTime`,
+`CommandSubmissionCompleted` … are interleaved into the classic layout), so
+fixed indices silently read the wrong fields:
+
+```python
+import sys, statistics
+hdr, rows = None, []
+for line in open(sys.argv[1]):
+    line = line.strip()
+    if line.startswith("Flags,"):
+        hdr = [c for c in line.split(",") if c]; continue
+    if hdr is None or not line[:1].isdigit(): continue
+    p = line.split(",")
+    if len(p) < len(hdr): continue
+    r = dict(zip(hdr, [int(x) for x in p[:len(hdr)]]))
+    if r["Flags"] != 0: continue          # non-zero = atypical frame, drop
+    rows.append(r)
+m = {"total":     lambda r: r["FrameCompleted"] - r["IntendedVsync"],
+     "ui_record": lambda r: r["SyncQueued"]     - r["DrawStart"],
+     "render":    lambda r: r["FrameCompleted"] - r["IssueDrawCommandsStart"],
+     "gpu":       lambda r: r["GpuCompleted"]   - r["IssueDrawCommandsStart"]}
+for name, fn in m.items():
+    xs = sorted(fn(r) / 1e6 for r in rows)
+    p95 = xs[min(len(xs) - 1, int(.95 * len(xs)))]
+    print(f"{name:10s} n={len(xs):3d} p50={statistics.median(xs):7.2f}ms p95={p95:7.2f}ms")
+```
+
+All values are absolute nanosecond timestamps on `CLOCK_MONOTONIC` — you
+subtract to get durations. `DequeueBufferDuration` / `QueueBufferDuration` are
+the exceptions, already durations. framestats keeps only the **last 120 frames**,
+so sample close to the activity you care about.
+
+---
+
+## 4. Primary metric — per-thread CPU
+
+This is where Liveline's cost actually shows up. Ports directly from Part 2 of
+the iOS skill; read `utime + stime` (fields 14 and 15 of `/proc/<pid>/stat`, in
+clock ticks, 100/sec) instead of `ps -o cputime`.
+
+```bash
+PID=$(adb shell pidof liveline.example | tr -d '\r')
+cpu(){ adb shell cat /proc/$PID/stat | awk '{print $14+$15}'; }
+A=$(cpu); sleep 20; B=$(cpu)
+echo "$A $B" | awk '{printf "%.1f%%\n", ($2-$1)/100/20*100}'   # % of one core
+```
+
+\>100% is normal (main + RenderThread + JS threads).
+
+**Per-thread is more diagnostic than the process total**, because it separates
+the engine from the example app's own data generation:
+
+```bash
+adb shell 'for t in /proc/'$PID'/task/*; do
+  echo "$(cat $t/comm) $(awk "{print \$14+\$15}" $t/stat)"; done' | sort -k2 -rn | head
+```
+
+Measured shortly after launch (cumulative ticks, release build):
+
+| thread | ticks | what it is |
+|---|---|---|
+| `iveline.example` | 7989 | **main** — the Reanimated UI runtime + Skia draw. This is the engine. |
+| `mqt_v_js` | 3836 | RN JS thread — largely the example app's data generation, not library cost. |
+| `RenderThread` | 2053 | HWUI composite. |
+| `hades` (x2) | 749 | Hermes GC. |
+
+Note `comm` is truncated to 15 chars, so the main thread reads
+`iveline.example` — match on that, not on the full package name.
+
+This split corroborates the simpleperf reference already recorded in the iOS
+skill (main 44.8%, `mqt_v_js` 35.6%, RenderThread 14.0%, hades 4.5%).
+**A rendering change should move the main thread**; if your delta shows up in
+`mqt_v_js` instead, you changed the example app's workload, not the library.
+
+### Derived per-frame cost
+
+`gfxinfo` is blind to the Skia work but its frame *counter* is still a valid
+count of presented frames, so you can turn the CPU number into a per-frame one:
+
+```bash
+adb shell dumpsys gfxinfo liveline.example reset
+A=$(cpu); sleep 20; B=$(cpu)
+FRAMES=$(adb shell dumpsys gfxinfo liveline.example | awk '/Total frames rendered/{print $4}')
+echo "$A $B $FRAMES" | awk '{printf "%.2f ms cpu/frame\n", ($2-$1)*10/$3}'
+```
+
+Because the frame rate is pinned by pacing, this is close to a pure ratio of
+the CPU numbers — treat it as a readability convenience, not independent evidence.
+
+### Symbol-level attribution
+
+Use **simpleperf** — already documented and verified in
+`.claude/skills/run-and-profile/SKILL.md` §"Android — simpleperf", including the
+three traps (`-e cpu-clock` required on emulators, `perf_harden` needs
+`adb root`, sort key is `comm` not `thread`).
+
+---
+
+## 5. Perfetto — the per-frame timeline
+
+Use when you need real per-frame durations rather than an averaged CPU rate.
+Unlike gfxinfo it samples **every thread**, so it sees the Skia work.
+
+```bash
+adb shell perfetto -o /data/misc/perfetto-traces/trace.pftrace -t 15s \
+  sched freq idle am wm gfx view binder_driver
+adb pull /data/misc/perfetto-traces/trace.pftrace /tmp/
+```
+
+Verified working on this emulator (8s run → 13 MB trace). Two notes: pass
+`adb shell -t` if you want Ctrl+C to stop the trace gracefully, and drop `hal`
+from the category list — the run above used the categories exactly as shown.
+
+Open at <https://ui.perfetto.dev>. What to read, in priority order:
+
+1. **The main thread's slices** during the capture — this is the engine, per §4.
+   Its per-frame slice duration is the number a rendering refactor should move.
+2. The **Frame Timeline** track (`ActualFrameTiming` /` ExpectedFrameTiming`)
+   for per-frame actual vs expected duration with jank classification. Interpret
+   its jank flags with the pacing caveat from §3 in mind.
+
+Report **p50 as the headline** (typical per-frame cost) and **p95 alongside**
+(catches GC pauses and spike regressions). **Never report the mean** —
+frame-time distributions are long-tailed and one GC pause moves the mean while
+telling you nothing about typical cost.
+
+---
+
+## 6. A/B protocol
+
+Mirrors the iOS protocol. The discipline is the point — skipping a step is how
+the two earlier invalidated results happened.
+
+1. **Swap only `src/`.** `git checkout <base> -- src/`, restore with
+   `git checkout HEAD -- src/`. Holding `example/` constant isolates the
+   library. Commit or stash first.
+2. **Rebuild the release APK for each arm.** Unlike the iOS Debug flow there is
+   no Metro to pick up `src/` changes — the bundle is embedded, so an unbuilt
+   arm silently measures the *other* arm's code. This is the easiest way to
+   produce a fake null result. (Only the JS bundle changes, so rebuilds are
+   ~1min warm, not a full native build.)
+3. **Screenshot the baseline arm** before measuring (§2).
+4. Relaunch between arms, settle ~20s. Prefer the default Line tab.
+5. **N = 3 runs per arm.** Within-arm spread should be a few percent; much wider
+   means the host is too busy to measure on — stop and come back later.
+6. **Re-measure the first arm at the end** as a drift control. If arm-A-final
+   does not land within the spread of arm-A-initial, the run is void: something
+   drifted (thermal, host load, emulator state) and your "delta" is that drift.
+7. **Log `uptime` per arm** (§1b), and the `dumpsys SurfaceFlinger | grep GLES`
+   line once per emulator boot (§1a). Record both with the numbers.
+
+### Reporting template
+
+```
+date, commit-A -> commit-B, device (emulator liveline_test / hardware model),
+build type (release), GLES renderer string, load per arm
+
+arm         n   main-thread CPU %   process CPU %   p50 frame ms (perfetto)
+A (base)    3
+B (change)  3
+A (drift)   3
+```
+
+State what the measurement does **not** establish. For the emulator: it is a
+gfxstream/Metal translation layer, not a real Adreno/Mali GL driver, so GPU-side
+numbers do not transfer to hardware; and it measures the whole pipeline, so a
+delta cannot be attributed to one change without simpleperf's breakdown.
+**Release on physical Android hardware remains the standing open item.**
diff --git a/example/package.json b/example/package.json
index 2b95a00..6dffc4c 100644
--- a/example/package.json
+++ b/example/package.json
@@ -9,6 +9,7 @@
     "web": "expo start --web",
     "build:ios": "xcodebuild ONLY_ACTIVE_ARCH=YES -workspace ios/LivelineExample.xcworkspace -UseNewBuildSystem=YES -scheme LivelineExample -configuration Debug -sdk iphonesimulator -derivedDataPath ios/build -quiet",
     "build:android": "cd android && ./gradlew assembleDebug -DtestBuildType=debug -Dorg.gradle.jvmargs=-Xmx4g",
+    "build:android:release": "cd android && ./gradlew assembleRelease -Dorg.gradle.jvmargs=-Xmx4g",
     "build:web": "expo export --platform web"
   },
   "dependencies": {

From de8c9a030187892a6f95e5fe56d73691f5cd4ed7 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Thu, 30 Jul 2026 23:25:49 -0400
Subject: [PATCH 06/37] perf(timeAxis): memoize label text; fix off-screen
 label churn
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two changes to drawTimeAxis, both invisible on screen. Per-label alpha,
crossfades, edge fades and the alpha-based overlap tiebreak are all untouched.

1. Label text is memoized by key.

   formatTime(key / 100) is a pure function of key, so a label's text cannot
   change while its key and the formatter both stay the same. The create-labels
   loop nonetheless called the formatter for EVERY target on EVERY frame and
   then overwrote each existing label's text with a byte-identical string. At
   the ~6 labels a 30s window shows, that is ~360 formatter calls per second,
   and defaultFormatTime allocates a Date, three padStart results and a
   template string per call — several thousand short-lived allocations per
   second on the UI thread, producing text that was already correct.

   The formatter now runs only for a key seen for the first time. A formatter
   swap is caught by reference identity (same trade gridLayer.ts makes for
   kFormatValue) and re-texts live labels in place WITHOUT touching their
   alphas, so re-formatting cannot restart a label's fade-in.

2. Still-targeted labels are no longer deleted at alpha 0.

   Found by the new tests, not by reading. `targets` deliberately spans one
   interval beyond each edge, so the buffer keys sit outside the visible
   x-range where edgeAlpha returns 0. Those keys churned: created at alpha 0,
   decayed, deleted, then re-created and re-formatted on the very next frame,
   forever. That is wasted work on its own and it also defeated (1), since
   each re-creation is a genuinely unseen key. Adding `&& !isTarget` to the
   delete parks them at alpha 0 instead — one Map entry (targets is capped at
   30), invisible because the draw pass filters at alpha < 0.02.

Adds src/draw/__tests__/timeAxis.test.ts — this file had no coverage before.
8 tests pinning the memoization, the formatter-swap re-text, that a swap does
not restart fade-in, and that stationary frames after the first cost zero
formatter calls. 12 suites / 234 tests.

Not yet measured on device; this is the change the A/B will be run against.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/draw/__tests__/timeAxis.test.ts | 242 ++++++++++++++++++++++++++++
 src/draw/timeAxis.ts                |  60 +++++--
 src/engine/state.ts                 |   1 +
 3 files changed, 291 insertions(+), 12 deletions(-)
 create mode 100644 src/draw/__tests__/timeAxis.test.ts

diff --git a/src/draw/__tests__/timeAxis.test.ts b/src/draw/__tests__/timeAxis.test.ts
new file mode 100644
index 0000000..d4f5c2a
--- /dev/null
+++ b/src/draw/__tests__/timeAxis.test.ts
@@ -0,0 +1,242 @@
+import { drawTimeAxis, type TimeAxisState } from '../timeAxis';
+import type { ChartLayout, LivelinePalette } from '../../types';
+
+/**
+ * `timeAxis.ts` had no test coverage before this file. It is testable — unlike
+ * `draw/index.ts` — because it imports `Ctx2D` as a *type* only and never pulls
+ * in the native Skia binding, the same property that makes `lineCache.ts` and
+ * `gridLayer.ts` testable.
+ *
+ * These tests exist primarily to pin the label-text memoization: the formatter
+ * must run once per newly-visible key rather than once per key per frame, and
+ * a formatter swap must re-text live labels WITHOUT restarting their fade-in.
+ * Every assertion here is about behavior that is invisible on screen, which is
+ * exactly why it needs a test — a regression would silently reintroduce
+ * thousands of allocations per second with no visual symptom.
+ */
+
+const WINDOW = 30;
+const NOW = 1_700_000_000;
+
+function makeLayout(rightEdge = NOW): ChartLayout {
+  const leftEdge = rightEdge - WINDOW;
+  const pad = { top: 12, right: 80, bottom: 28, left: 12 };
+  const w = 400;
+  const chartW = w - pad.left - pad.right;
+  return {
+    w,
+    h: 300,
+    pad,
+    chartW,
+    chartH: 300 - pad.top - pad.bottom,
+    leftEdge,
+    rightEdge,
+    minVal: 0,
+    maxVal: 100,
+    valRange: 100,
+    toX: (t: number) => pad.left + ((t - leftEdge) / WINDOW) * chartW,
+    toY: (v: number) => v,
+  };
+}
+
+const palette = {
+  gridLine: '#222222',
+  timeLabel: '#888888',
+} as unknown as LivelinePalette;
+
+function makeState(): TimeAxisState {
+  return {
+    labels: new Map(),
+    targetsScratch: new Set(),
+    visibleLabelsScratch: [],
+    drawnScratch: [],
+    labelEntryPool: [],
+    formatTimeRef: null,
+  };
+}
+
+/** Minimal Ctx2D stand-in — only the members drawTimeAxis actually touches. */
+function makeCtx() {
+  const font = { __slot: 'label' };
+  return {
+    fonts: { label: font },
+    font,
+    globalAlpha: 1,
+    strokeStyle: '',
+    fillStyle: '',
+    lineWidth: 1,
+    textAlign: 'left' as const,
+    drawnTexts: [] as string[],
+    save() {},
+    restore() {},
+    beginPath() {},
+    moveTo() {},
+    lineTo() {},
+    stroke() {},
+    measureText(text: string) {
+      return { width: text.length * 6 };
+    },
+    fillText(text: string) {
+      this.drawnTexts.push(text);
+    },
+  };
+}
+
+function run(
+  ctx: ReturnType<typeof makeCtx>,
+  state: TimeAxisState,
+  formatTime: (t: number) => string,
+  rightEdge = NOW,
+  dt = 16.67
+) {
+  drawTimeAxis(
+    ctx as any,
+    makeLayout(rightEdge),
+    palette,
+    WINDOW,
+    WINDOW,
+    formatTime,
+    state,
+    dt
+  );
+}
+
+function countingFormatter() {
+  let calls = 0;
+  const fn = (t: number) => {
+    calls++;
+    return `T${Math.round(t)}`;
+  };
+  return { fn, calls: () => calls };
+}
+
+describe('drawTimeAxis label-text memoization', () => {
+  it('formats each key exactly once across many stationary frames', () => {
+    const ctx = makeCtx();
+    const state = makeState();
+    const f = countingFormatter();
+
+    run(ctx, state, f.fn);
+    const afterFirst = f.calls();
+    expect(afterFirst).toBeGreaterThan(0);
+
+    // Same window, same keys — nothing new should ever need formatting.
+    for (let i = 0; i < 60; i++) run(ctx, state, f.fn);
+
+    expect(f.calls()).toBe(afterFirst);
+  });
+
+  it('formats only the newly-arrived keys as the window scrolls', () => {
+    const ctx = makeCtx();
+    const state = makeState();
+    const f = countingFormatter();
+
+    run(ctx, state, f.fn, NOW);
+    const afterFirst = f.calls();
+
+    // Scroll forward by a full window — every key is new, but each is still
+    // formatted once, not once per frame.
+    const frames = 60;
+    for (let i = 1; i <= frames; i++) {
+      run(ctx, state, f.fn, NOW + (WINDOW * i) / frames);
+    }
+
+    const added = f.calls() - afterFirst;
+    // Bounded well below "one call per key per frame", which is what the
+    // pre-memoization implementation did.
+    expect(added).toBeGreaterThan(0);
+    expect(added).toBeLessThan(frames);
+  });
+
+  it('produces the same text a per-frame formatter would have', () => {
+    const fmt = (t: number) => `T${Math.round(t)}`;
+    const ctx = makeCtx();
+    const state = makeState();
+
+    for (let i = 0; i < 10; i++) run(ctx, state, fmt);
+
+    for (const [key, label] of state.labels) {
+      expect(label.text).toBe(fmt(key / 100));
+    }
+  });
+
+  it('re-texts live labels when the formatter reference changes', () => {
+    const ctx = makeCtx();
+    const state = makeState();
+
+    run(ctx, state, (t) => `A${Math.round(t)}`);
+    expect(state.labels.size).toBeGreaterThan(0);
+    for (const label of state.labels.values()) {
+      expect(label.text.startsWith('A')).toBe(true);
+    }
+
+    run(ctx, state, (t) => `B${Math.round(t)}`);
+    for (const label of state.labels.values()) {
+      expect(label.text.startsWith('B')).toBe(true);
+    }
+  });
+
+  it('does not restart fade-in when the formatter changes', () => {
+    const ctx = makeCtx();
+    const state = makeState();
+
+    // Let alphas rise well above their initial 0.
+    for (let i = 0; i < 30; i++) run(ctx, state, (t) => `A${Math.round(t)}`);
+    const before = new Map(
+      [...state.labels].map(([k, l]) => [k, l.alpha] as const)
+    );
+    expect([...before.values()].some((a) => a > 0.5)).toBe(true);
+
+    // A formatter swap re-texts, but must not touch alpha. Pass dt = 0 so the
+    // lerp cannot advance and any change would be the re-text's fault.
+    run(ctx, state, (t) => `B${Math.round(t)}`, NOW, 0);
+
+    for (const [key, label] of state.labels) {
+      expect(label.alpha).toBe(before.get(key));
+    }
+  });
+
+  it('tracks the formatter reference on the state', () => {
+    const ctx = makeCtx();
+    const state = makeState();
+    expect(state.formatTimeRef).toBeNull();
+
+    const fmt = (t: number) => `T${Math.round(t)}`;
+    run(ctx, state, fmt);
+    expect(state.formatTimeRef).toBe(fmt);
+  });
+
+  it('still draws label text every frame', () => {
+    const ctx = makeCtx();
+    const state = makeState();
+    const fmt = (t: number) => `T${Math.round(t)}`;
+
+    // Warm up so alphas clear the 0.02 visibility floor.
+    for (let i = 0; i < 30; i++) run(ctx, state, fmt);
+    ctx.drawnTexts.length = 0;
+    run(ctx, state, fmt);
+
+    // Memoizing the *text* must not stop it being *drawn* — the labels are
+    // still painted live every frame, which is the whole point of keeping the
+    // per-label alpha animation intact.
+    expect(ctx.drawnTexts.length).toBeGreaterThan(0);
+  });
+});
+
+describe('measured formatter-call counts (pins the win)', () => {
+  it('stationary: one call per target on frame 1, zero thereafter', () => {
+    const ctx = makeCtx();
+    const state = makeState();
+    const f = countingFormatter();
+
+    run(ctx, state, f.fn);
+    const firstFrame = f.calls();
+
+    for (let i = 0; i < 59; i++) run(ctx, state, f.fn);
+
+    // Pre-memoization this was firstFrame * 60. Now the remaining 59 frames
+    // cost nothing at all.
+    expect(f.calls()).toBe(firstFrame);
+    expect(firstFrame).toBe(state.labels.size);
+  });
+});
diff --git a/src/draw/timeAxis.ts b/src/draw/timeAxis.ts
index 6ece4e8..8867e6f 100644
--- a/src/draw/timeAxis.ts
+++ b/src/draw/timeAxis.ts
@@ -31,6 +31,15 @@ export interface TimeAxisState {
    * Also holds references into `labelEntryPool`, never its own objects —
    * `.length = 0` at the top of each use. */
   drawnScratch: TimeLabelEntry[];
+  /** The `formatTime` this state's cached label text was produced with,
+   * compared by reference. `null` before the first frame. Label text is only
+   * recomputed when this changes (or for a key never seen before) — see the
+   * comment at the create-labels loop in `drawTimeAxis` for why that is safe
+   * and what it saves. A formatter closing over mutable state it reads but
+   * does not appear in its own identity will go stale here; every formatter
+   * in this codebase, and the documented contract for the `formatTime` prop,
+   * is a pure function of its argument. */
+  formatTimeRef: ((t: number) => string) | null;
   /** Growable pool of reusable `{x,alpha,text,w}` objects, indexed by
    * position in this frame's visible-label scan (NOT by label key — a
    * given index may back a different label on every frame, which is fine
@@ -105,28 +114,55 @@ export function drawTimeAxis(
     targets.add(Math.round(t * 100));
   }
 
-  // Create or update labels. Text is updated in-place — no crossfade needed
-  // because format changes coincide with scroll transitions where the eye
-  // tracks movement, not text content. By the time labels settle, the text
-  // is already correct so nothing visibly changes on stationary labels.
+  // Create labels for newly-visible keys.
+  //
+  // `formatTime(key / 100)` is a pure function of `key`, so a label's text
+  // cannot change while its key and the formatter both stay the same. This
+  // loop used to call the formatter for EVERY target on EVERY frame and then
+  // overwrite each existing label's text with a byte-identical string. At the
+  // ~6-10 labels a chart typically shows, that is 360-600 formatter calls per
+  // second, and the default formatter (`defaultFormatTime` in Liveline.tsx)
+  // allocates a Date, three padStart results and a template string on each
+  // call — several thousand short-lived allocations per second, on the UI
+  // thread, to recompute text that was already correct.
+  //
+  // The formatter now runs only for a key being seen for the first time.
+  // Text is still updated in place when the *formatter itself* changes,
+  // caught by reference identity — the same conservative trade gridLayer.ts
+  // makes for `kFormatValue`. That re-text deliberately does NOT touch
+  // alphas: a label already on screen must not restart its fade-in just
+  // because the consumer swapped formatters.
+  if (state.formatTimeRef !== formatTime) {
+    state.formatTimeRef = formatTime;
+    for (const [key, label] of state.labels) {
+      label.text = formatTime(key / 100);
+    }
+  }
   for (const key of targets) {
-    const text = formatTime(key / 100);
-    const existing = state.labels.get(key);
-    if (!existing) {
-      state.labels.set(key, { alpha: 0, text });
-    } else {
-      existing.text = text;
+    if (state.labels.get(key) === undefined) {
+      state.labels.set(key, { alpha: 0, text: formatTime(key / 100) });
     }
   }
 
-  // Update alphas
+  // Update alphas.
+  //
+  // The `!isTarget` term on the delete is load-bearing, not defensive.
+  // `targets` deliberately spans one interval beyond each edge (see the
+  // generation loop above), so the buffer keys sit outside the visible
+  // x-range, where `edgeAlpha` returns 0. Without `!isTarget` those keys
+  // churn: created at alpha 0, decayed, deleted, then re-created and
+  // re-formatted on the very next frame, forever — which also defeats the
+  // text memoization above, since each re-creation is a genuinely unseen key.
+  // Keeping a still-targeted label parked at alpha 0 costs one Map entry
+  // (`targets` is capped at 30) and is invisible: the draw pass below filters
+  // at `alpha < 0.02`.
   for (const [key, label] of state.labels) {
     const x = toX(key / 100);
     const isTarget = targets.has(key);
     const target = isTarget ? edgeAlpha(x) : 0;
     let next = lerp(label.alpha, target, FADE, dt);
     if (Math.abs(next - target) < 0.02) next = target;
-    if (next < 0.01 && target === 0) {
+    if (next < 0.01 && target === 0 && !isTarget) {
       state.labels.delete(key);
     } else {
       label.alpha = next;
diff --git a/src/engine/state.ts b/src/engine/state.ts
index 6f2f390..77b76d1 100644
--- a/src/engine/state.ts
+++ b/src/engine/state.ts
@@ -277,6 +277,7 @@ export function createEngineState(
       visibleLabelsScratch: [],
       drawnScratch: [],
       labelEntryPool: [],
+      formatTimeRef: null,
     },
     orderbookState: createOrderbookState(),
     particleState: createParticleState(),

From e2c56d8066675b66977605cae03661825ec49d89 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Fri, 31 Jul 2026 00:39:16 -0400
Subject: [PATCH 07/37] docs(skill): record four A/B traps that voided a real
 measurement
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

All four hit while measuring the timeAxis memoization on 2026-07-30.

- Relaunching resets in-app toggles. The FPS counter was ON for arm 1 (set in
  an earlier session) and OFF for every later arm, because relaunch resets
  React state and it defaults off. An always-on frame callback in one arm and
  not the others cost ~15 points and looked exactly like host drift. The arm
  screenshots are the check: `56 fps` when on, blank `fps` when off.
- Settle is ~50s, not 20. A swapped src/ makes Metro re-bundle; windows opened
  too early read 1-5%, which is the app still loading, not the app being fast.
- Log uptime at the START and END of each arm. Observed 50.7 right after a
  build/install/bundle, draining over minutes; a mid-arm climb is invisible
  when sampled once, and a moving load voids the comparison outright.
- Know the effect size before trusting whole-process CPU. It cannot resolve
  ~1-2k JS allocations/sec on this box.

That last one is now measured rather than assumed. A head-to-head bench of
drawTimeAxis (V8, 20k frames/arm, interleaved, 5 rounds) puts the memoization
at 35.1% faster on the JS half — 5.61us -> 3.64us per frame, distributions
non-overlapping. At 60fps that saves ~0.12ms/sec of JS work, roughly 0.01% of
a core on V8, which is orders of magnitude below what a CPU-time A/B can see.
The device A/B measured null (and slightly negative) for exactly that reason.

Note the bench uses a no-op ctx, so it covers only the JS half of drawTimeAxis.
The ~60-80 Skia JSI calls per frame are NOT measured by it and remain
unquantified.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .claude/skills/run-and-profile/SKILL.md | 30 ++++++++++++++++++++-----
 1 file changed, 24 insertions(+), 6 deletions(-)

diff --git a/.claude/skills/run-and-profile/SKILL.md b/.claude/skills/run-and-profile/SKILL.md
index 90b6d07..96af251 100644
--- a/.claude/skills/run-and-profile/SKILL.md
+++ b/.claude/skills/run-and-profile/SKILL.md
@@ -70,13 +70,31 @@ A/B protocol:
    Commit/stash first.
 2. **Screenshot the baseline arm.** If the old `src/` throws, you're timing a
    red error screen — cheap to render, looks like a huge win.
-3. Relaunch between arms, settle ~20s. Use the default Line tab where possible:
-   it survives a reload with no navigation, removing a variance source.
-4. 3 runs/arm. Within-arm spread should be 2-3 points; much wider means the host
+3. Relaunch between arms, settle **~50s**, not 20 — a swapped `src/` makes Metro
+   re-bundle, and a window opened too early reads 1-5% (the app is still
+   loading, not cheap). Any run that implausibly low is a settle artifact, not
+   data. Use the default Line tab where possible: it survives a reload with no
+   navigation, removing a variance source.
+4. **Relaunching resets in-app toggles — check them per arm.** Burned a full
+   A/B on 2026-07-30: the FPS counter was ON for arm 1 (set in an earlier
+   session) and OFF for every later arm, because relaunch resets React state
+   and it defaults off. That is an always-on frame callback present in one arm
+   and absent in the others — it cost ~15 points and looked exactly like host
+   drift. The arm screenshots are the check: the control reads `56 fps` when on
+   and a blank `fps` when off. Confirm every arm matches before comparing.
+5. 3 runs/arm. Within-arm spread should be 2-3 points; much wider means the host
    is too busy to measure on.
-5. Re-measure the first arm at the end as a drift control.
-6. Log `uptime` per arm — shared 8-core box, has run at load 24. Relative deltas
-   survive moderate load; absolute numbers don't.
+6. Re-measure the first arm at the end as a drift control.
+7. Log `uptime` per arm, **at the start AND end of each arm** — a mid-arm climb
+   is invisible if you only sample once. Shared 8-core box, has run at load 24;
+   observed 50.7 immediately after a build/install/bundle, draining over
+   several minutes. Relative deltas survive moderate load; absolute numbers
+   don't, and a *moving* load voids the comparison outright.
+8. **Know your effect size before trusting this method.** Whole-process CPU
+   cannot resolve a change worth ~1-2k JS allocations/sec — that is inside the
+   noise on this box (measured null, and slightly negative, for the timeAxis
+   memoization on 2026-07-30 despite unit tests proving the work was removed).
+   For allocation-shaped changes, prefer symbol-level sampling over total CPU.
 
 Reference (2026-07-27, iPhone 17 Pro sim, Debug, load ~8-11), `main` 60e493e →
 `perf-hardening` 2fb7ff2: Line 127.8% → 85.4%, Candles 108.5% → 63.5%.

From b6c27a9e8873c9e0d0a3b6662efad14298914180 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Fri, 31 Jul 2026 08:42:32 -0400
Subject: [PATCH 08/37] docs: declarative render shell design
 (react-native-graph-shaped)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Targets react-native-graph's rendering shape — a declarative Skia tree with
continuous motion as a <Group transform> driven by a shared value — while
keeping the blocked-JS-thread guarantee and current visual output.

Feasibility verified in the Skia sources rather than assumed: sksg/
Container.native.ts compiles the tree once on JS and drives all shared-value
prop updates through a Reanimated mapper on the UI thread, and AnimatedProp<T>
= T | {value: T} confirms Group.transform accepts a shared value. Structural
changes are the only thing that touches JS, and this tree has none after mount.

Records the ceiling: variable-count content (axis labels, candles, particles,
orderbook) cannot enter the declarative tree without forfeiting the guarantee,
so it stays inside <Picture> nodes. This is graph-shaped, not a port.

The fill is deliberately not split — it is a semi-transparent gradient polygon,
so abutting seams at ~0.75 AA coverage, overlapping double-darkens, and a
non-AA clip split can gap at fractional dx (and dx cannot be rounded: ~0.17px
of motion per frame would judder). Only the opaque stroke splits cleanly.

States plainly that this is an architecture goal, not a performance one: it
removes about one draw call per frame and will not be measurable, against a
measured baseline where the entire time axis is 4.2% of a core.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../2026-07-31-declarative-shell-design.md    | 135 ++++++++++++++++++
 1 file changed, 135 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-07-31-declarative-shell-design.md

diff --git a/docs/superpowers/specs/2026-07-31-declarative-shell-design.md b/docs/superpowers/specs/2026-07-31-declarative-shell-design.md
new file mode 100644
index 0000000..3637b8f
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-31-declarative-shell-design.md
@@ -0,0 +1,135 @@
+# Declarative render shell (react-native-graph-shaped)
+
+**Date:** 2026-07-31
+**Status:** Design approved, implementation dispatched
+**Branch:** `perf/declarative-shell` (off `e2c56d8`)
+
+## Goal
+
+Match react-native-graph's rendering *shape* — a declarative Skia tree with
+continuous motion expressed as a `<Group transform>` driven by a shared value —
+without losing either of the two things that make Liveline what it is: it keeps
+animating while the JS thread is blocked, and its current visual output.
+
+**This is an architecture goal, not a performance goal.** See "Honest cost"
+below. The CPU case was measured and is weak; the user chose fidelity anyway.
+
+## Target tree
+
+```tsx
+<Canvas>
+  <Group transform={scrollTransform}>   {/* SharedValue<Transforms3d> */}
+    <Picture picture={scrollPicture} />
+  </Group>
+  <Picture picture={screenPicture} />
+</Canvas>
+```
+
+Four nodes, **fixed structure, never reconciled after mount**.
+
+## Why this preserves the blocked-JS-thread guarantee
+
+Verified in `example/node_modules/@shopify/react-native-skia/src/sksg/Container.native.ts:38-62`.
+`NativeReanimatedContainer.redraw()` compiles the declarative tree once on the
+JS thread, collects every shared value used as a prop, and then installs a
+Reanimated mapper:
+
+```js
+this.mapperId = Rea.startMapper(() => {
+  "worklet";
+  sharedRecorder.applyUpdates(sharedValues);
+  nativeDrawOnscreen(nativeId, sharedRecorder, picture);
+}, sharedValues);
+```
+
+So shared-value prop updates run entirely on the UI thread. `redraw()` — the
+only JS-thread step — runs on *structural* change. Our tree has no structural
+change after mount, so nothing touches JS per frame.
+
+`AnimatedProp<T> = T | { value: T }` (`renderer/processors/Animations/Animations.d.ts`)
+confirms every Skia prop accepts a shared value, `<Group transform>` included.
+
+## The ceiling on this approach
+
+Variable-count content **cannot** go in the declarative tree without forfeiting
+the guarantee: axis labels, candles, particles and orderbook bars change their
+element count as data and scroll advance, and each change would require JS
+reconciliation. During a JS block their counts would freeze, where today the
+worklet still generates them.
+
+That content therefore stays inside `<Picture>` nodes, which is why this design
+is "react-native-graph-shaped" rather than a full port. Their model never faces
+this because it has no continuous motion at all.
+
+## What goes in the scroll layer
+
+**`scrollPicture`: the line's prefix _stroke_ only** — the spline through
+decimated points `0..N-2`, rebuilt only on a `lineCache` key miss.
+
+**`screenPicture`: everything else**, including the *entire* fill polygon and
+the tail stroke, drawn live every frame exactly as today.
+
+### Why the fill is deliberately NOT split
+
+The fill is one closed polygon: baseline → up the left edge → along the spline
+→ down to baseline → close (`lineCache.ts:211-222`), and it is a semi-transparent
+gradient (`palette.fillTop`/`fillBottom`). Splitting it at `cutX` gives three bad
+options and no good one:
+
+- **Abut two pieces.** Antialiased coverage on a shared edge sums to ~0.75, not
+  1 — a visible hairline down the fill.
+- **Overlap two pieces.** Semi-transparent overdraw double-darkens a 1px column.
+- **Non-AA clip split.** Tiles exactly only if both sides round the boundary
+  identically; at fractional `dx` a 1px gap or double-draw is possible. And
+  rounding `dx` to whole pixels is not available to us: at a 30s window over
+  ~300px the line moves ~0.17px/frame, so integer quantization would judder.
+
+Keeping the fill whole sidesteps all of it. The **stroke** has no such problem:
+it is opaque, and `drawSplineTail` already continues from `cutX` with the
+prefix's end tangent (`lineCache.ts:197-206`), so the join is C1-continuous and
+any overdraw is identical pixels.
+
+## Honest cost
+
+Because the fill still needs the full path every frame, `lineCache` keeps
+running and this stage removes roughly **one draw call per frame**. It buys the
+architecture, not speed.
+
+For context, measured on this repo 2026-07-30/31: the whole time axis is 4.2% of
+a core (valid ceiling A/B, drift control agreeing to 0.1 points), and the
+timeAxis memoization — a 35% improvement to that function's JS — was
+undetectable on device. A one-draw-call change will not be measurable. Do not
+claim otherwise.
+
+## Alpha gate
+
+`ctx.drawPicture` ignores `globalAlpha` (`canvas2d.ts:139-143`). Whenever the
+line's composite alpha is < 1 — reveal morph, loading/empty crossfade, scrub
+dimming — the engine must fall back to recording **everything** into
+`screenPicture` and leave `scrollPicture` empty, so nothing is composited at the
+wrong opacity. Same gate `draw/index.ts:218` already applies to the grid picture.
+
+## Work split
+
+Two workstreams, deliberately chosen for file disjointness:
+
+| Stream | Files | Deliverable |
+|---|---|---|
+| A — stroke split | `src/draw/lineCache.ts`, `src/draw/line.ts` | Expose the prefix stroke as a separately-drawable path; tail stroke unchanged; fill untouched |
+| B — declarative shell | `src/Liveline.tsx`, `src/useLivelineEngine.ts` | Two-picture + `<Group transform>` tree; engine exposes `scrollPicture` / `screenPicture` / `scrollTransform`. Ships as a structural no-op: `scrollPicture` starts empty. |
+
+Integration (wiring A's prefix stroke into B's `scrollPicture`, plus the alpha
+gate) is a third, sequential step once both land.
+
+## Risks
+
+- **Double-draw.** Once integrated, `screenPicture` must not also draw the
+  prefix stroke. A visual diff at identical data is the check.
+- **Transform units.** `scrollTransform` is `[{ translateX: dx }]` where `dx`
+  is `scrollLayerDx`'s value — screen pixels, recomputed against the build-time
+  reference every frame, never accumulated (`lineCache.ts:166-175`).
+- **Z-order.** Two `<Picture>` siblings must composite in source order. Verify
+  on device, not by assumption.
+- **Text subpixel.** Nothing text-bearing is in the scroll layer in this design,
+  so the jitter risk flagged earlier does not apply yet. It returns if the axis
+  is ever moved in.

From 2e1c4d7bde0278b263ab8a0cfd16ce7a88b04aaa Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Fri, 31 Jul 2026 08:49:16 -0400
Subject: [PATCH 09/37] feat: declarative render shell (two pictures + Group
 transform)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replaces <Canvas><Picture/></Canvas> with react-native-graph's shape:

  <Canvas>
    <Group transform={scrollTransform}>
      <Picture picture={scrollPicture} />
    </Group>
    <Picture picture={screenPicture} />
  </Canvas>

Ships as a STRUCTURAL NO-OP. screenPicture is a pure rename of the old
`picture` and takes the full frame unchanged; scrollPicture is the 1x1 empty
placeholder and nothing records into it yet; scrollTransform is driven from the
frame callback but dx is always 0. Verified pixel-identical on the iOS
simulator — line, gradient fill, grid, badge, pulse ring, reference line and
axis labels all unchanged.

The tree is exactly 4 nodes with no conditionals and no .map(), and must stay
that way. sksg/Container.native.ts compiles the tree once on the JS thread and
then applies shared-value prop updates from a Reanimated mapper on the UI
thread; only a STRUCTURAL change re-enters JS via redraw(). A conditional node
here would silently cost the blocked-JS-thread guarantee, which is the whole
reason the engine exists. A comment above the JSX says so.

LivelineEngine.picture -> screenPicture is not a public API break: index.tsx
exports only Liveline, LivelineTransition and the ./types types, so the engine
interface is internal.

No test covers these two files — both pull in the native Skia binding.
Correctness here rests on typecheck plus the on-device visual check.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/Liveline.tsx         | 15 +++++++++-
 src/useLivelineEngine.ts | 63 ++++++++++++++++++++++++++++++++++++----
 2 files changed, 72 insertions(+), 6 deletions(-)

diff --git a/src/Liveline.tsx b/src/Liveline.tsx
index b461593..3756bf1 100644
--- a/src/Liveline.tsx
+++ b/src/Liveline.tsx
@@ -10,6 +10,7 @@ import {
 } from 'react-native';
 import {
   Canvas,
+  Group,
   Picture,
   Path,
   Line,
@@ -587,8 +588,20 @@ export const Liveline = memo(function LivelineComponent({
           style={[styles.container, style]}
           collapsable={false}
         >
+          {/*
+            Fixed 4-node tree — never reconciled after mount. Every per-frame
+            update is a shared-value *prop* change, which Skia's
+            NativeReanimatedContainer applies from a Reanimated mapper on the
+            UI thread; only a *structural* change would force a JS-thread
+            redraw(). Keep it that way: no conditionals, no .map(), nothing
+            that can add or remove a node, or the chart stops animating while
+            the JS thread is blocked.
+          */}
           <Canvas style={styles.canvas}>
-            <Picture picture={engine.picture} />
+            <Group transform={engine.scrollTransform}>
+              <Picture picture={engine.scrollPicture} />
+            </Group>
+            <Picture picture={engine.screenPicture} />
           </Canvas>
         </View>
       </GestureDetector>
diff --git a/src/useLivelineEngine.ts b/src/useLivelineEngine.ts
index e4a9693..48b130a 100644
--- a/src/useLivelineEngine.ts
+++ b/src/useLivelineEngine.ts
@@ -4,6 +4,7 @@ import {
   Skia,
   type SkPicture,
   type SkHostRect,
+  type Transforms3d,
 } from '@shopify/react-native-skia';
 import {
   runOnJS,
@@ -120,8 +121,28 @@ function makeEmptyPicture(): SkPicture {
 }
 
 export interface LivelineEngine {
-  /** Re-recorded every frame on the UI thread — render via Skia's <Picture> */
-  picture: SharedValue<SkPicture>;
+  /**
+   * The scroll layer: content that is recorded once and then translated
+   * horizontally by `scrollTransform` instead of being re-recorded. Render
+   * inside a `<Group transform={scrollTransform}>`, *below* `screenPicture`.
+   *
+   * Currently always the empty placeholder — the declarative shell ships as a
+   * structural no-op and the line's prefix stroke moves in here in a later
+   * step.
+   */
+  scrollPicture: SharedValue<SkPicture>;
+  /**
+   * The screen layer: everything drawn live, re-recorded every frame on the
+   * UI thread — render via Skia's <Picture>, above the scroll layer.
+   */
+  screenPicture: SharedValue<SkPicture>;
+  /**
+   * Scroll-layer offset, `[{ translateX: dx }]` in screen pixels. Updated on
+   * the UI thread every recorded frame; bind to `<Group transform>` so the
+   * update stays a prop change (UI thread) rather than a structural change
+   * (which would need a JS-thread reconcile).
+   */
+  scrollTransform: SharedValue<Transforms3d>;
   /** Pan gesture driving crosshair scrub — attach with <GestureDetector> */
   gesture: ComposedGesture | GestureType;
   /** Attach to the chart container to feed the engine its size */
@@ -370,7 +391,23 @@ export function useLivelineEngine(
   const cullRect = useSharedValue<SkHostRect | null>(null);
   const size = useSharedValue({ w: 0, h: 0 });
   const hoverX = useSharedValue<number | null>(null);
-  const picture = useSharedValue<SkPicture>(makeEmptyPicture());
+  const screenPicture = useSharedValue<SkPicture>(makeEmptyPicture());
+  // The scroll layer. Nothing records into it yet (the declarative shell
+  // ships as a structural no-op), so it stays the 1×1 empty placeholder and
+  // draws nothing — rendering is pixel-identical to the single-picture tree.
+  const scrollPicture = useSharedValue<SkPicture>(makeEmptyPicture());
+  // `[{ translateX: dx }]`, reassigned by the frame callback below (a shared
+  // value only notifies its mapper on assignment, so this can't be mutated
+  // in place). dx is always 0 for now, but it's written every recorded frame so
+  // the shared-value → <Group transform> plumbing is real rather than a
+  // constant that a later step would have to re-thread.
+  const scrollTransform = useSharedValue<Transforms3d>([{ translateX: 0 }]);
+  // Last dx pushed into `scrollTransform`, so the frame callback can skip the
+  // reassignment (and the array/object allocation it needs) when the offset
+  // hasn't moved. `Transform3d` is a union of single-key objects, so reading
+  // the current translateX back out of `scrollTransform.value` isn't
+  // type-safe; mirroring the scalar here is.
+  const scrollDx = useSharedValue(0);
   const valueText = useSharedValue('');
   const valueColor = useSharedValue('');
 
@@ -480,7 +517,15 @@ export function useLivelineEngine(
       candlesBuf.value,
       multiDataBuf.value
     );
-    picture.value = recorder.finishRecordingAsPicture();
+    screenPicture.value = recorder.finishRecordingAsPicture();
+    // Scroll-layer offset for this frame. Nothing is recorded into
+    // `scrollPicture` yet, so this is always 0 — the write exists so the
+    // shared value is genuinely driven from the frame loop.
+    const dx = 0;
+    if (scrollDx.value !== dx) {
+      scrollDx.value = dx;
+      scrollTransform.value = [{ translateX: dx }];
+    }
     s.lastRecordedW = w;
     s.lastRecordedH = h;
     s.lastFrameTimestamp = now_ms;
@@ -585,5 +630,13 @@ export function useLivelineEngine(
     [size]
   );
 
-  return { picture, gesture, onLayout, valueText, valueColor };
+  return {
+    scrollPicture,
+    screenPicture,
+    scrollTransform,
+    gesture,
+    onLayout,
+    valueText,
+    valueColor,
+  };
 }

From 21c4d9874203d3274d56aec484225c76e376b2f5 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Fri, 31 Jul 2026 08:49:16 -0400
Subject: [PATCH 10/37] feat(draw): expose line prefix stroke separately from
 tail
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Additive: assembleLineTail, slot.scratch, slot.fillScratch and updateLinePaths
are behaviourally untouched, so the combined path still renders identically.

- lineScrollDx(slot, layout) — the one place toX(tRef) - xRefAtBuild is
  written, now shared by the combined path and the split tail so they cannot
  disagree. Same formula as scrollLayer.ts's scrollLayerDx.
- linePrefixPath(slot) — returns slot.prefix as-is, no copy. Confirmed safe:
  assembleLineTail does scratch.addPath(prefix) then offset() on the SCRATCH,
  so the prefix is never translated. Pinned by a test running 200 scrolling
  frames and asserting the prefix's verbs deep-equal their build-time snapshot.
- assembleLineTailStroke(...) — slot-owned tailScratch, moveTo(cutX + dx) plus
  the same two drawSplineTail cubics, in current screen coords.

The tail is re-emitted rather than sliced out of the combined path: composing
it as addPath(tail, extend) would insert a zero-length connector verb and break
verb-for-verb parity with today's output. Two extra cubicTo per frame is
cheaper than that divergence.

The fill is deliberately NOT split — it is a semi-transparent gradient polygon,
so abutting halves seam at ~0.75 AA coverage and overlapping halves
double-darken. See the design doc.

+5 tests (234 -> 239): prefix unmutated over 200 frames, tail scratch allocated
once, tail starts exactly at cutX+dx, combined path equals prefix+tail
verb-for-verb, fill deep-equals today's construction.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/draw/__tests__/lineCache.test.ts | 226 +++++++++++++++++++++++++++
 src/draw/line.ts                     |  49 ++++--
 src/draw/lineCache.ts                | 126 ++++++++++++++-
 3 files changed, 390 insertions(+), 11 deletions(-)

diff --git a/src/draw/__tests__/lineCache.test.ts b/src/draw/__tests__/lineCache.test.ts
index 137e157..6ce364b 100644
--- a/src/draw/__tests__/lineCache.test.ts
+++ b/src/draw/__tests__/lineCache.test.ts
@@ -3,6 +3,9 @@ import {
   updateLinePaths,
   lineCacheHits,
   assembleLineTail,
+  assembleLineTailStroke,
+  linePrefixPath,
+  lineScrollDx,
   MIN_CACHE_POINTS,
   type CachePath,
 } from '../lineCache';
@@ -662,6 +665,229 @@ describe('assembleLineTail (fast path)', () => {
   });
 });
 
+// The split-stroke API the declarative scroll layer consumes: the prefix
+// stroke (build-time coords, moved by a <Group transform>) drawn separately
+// from the tail stroke (current screen coords, drawn live). These tests pin
+// the two invariants the shell depends on — the prefix is never translated
+// in place, and prefix+tail is the same geometry as the combined path — plus
+// the promise that the fill is left exactly as it is today.
+describe('split stroke (prefix / tail)', () => {
+  const NOW = 1000;
+  const N = 20;
+
+  /** Deep snapshot of a fake path's verbs, immune to later mutation. */
+  function snapshot(p: FakePath): Verb[] {
+    return p.verbs.map((v) => ({ op: v.op, c: v.c.slice() }));
+  }
+
+  function builtHarness(): {
+    hz: Harness;
+    data: LivelinePoint[];
+    smooth: number;
+  } {
+    const hz = makeHarness();
+    const data = makeData(N, NOW - 30);
+    const smooth = data[data.length - 1]!.value;
+    update(hz, makeLayout(NOW, 90, 110), data, smooth, NOW, true);
+    return { hz, data, smooth };
+  }
+
+  it('exposes slot.prefix as-is, untranslated and unmutated over many frames', () => {
+    const { hz, data, smooth } = builtHarness();
+    const prefix = hz.slot.prefix as FakePath;
+    expect(linePrefixPath(hz.slot)).toBe(prefix);
+    const atBuild = snapshot(prefix);
+
+    // 200 frames of pure scrolling: a cache hit every frame, both the
+    // combined assembly and the split tail assembly running.
+    for (let f = 1; f <= 200; f++) {
+      const t = NOW + f * 0.0167;
+      const layout = makeLayout(t, 90, 110);
+      expect(
+        lineCacheHits(
+          hz.slot,
+          layout,
+          0,
+          0,
+          data.length,
+          data[0]!.time,
+          data[data.length - 1]!.time,
+          data[data.length - 1]!.value
+        )
+      ).toBe(true);
+      const pts = buildPts(data, layout, smooth, t);
+      assembleLineTail(
+        hz.slot,
+        hz.makePath,
+        layout,
+        true,
+        pts[pts.length - 2]![0],
+        pts[pts.length - 2]![1],
+        pts[pts.length - 1]![0],
+        pts[pts.length - 1]![1],
+        pts[0]![1]
+      );
+      assembleLineTailStroke(
+        hz.slot,
+        hz.makePath,
+        layout,
+        pts[pts.length - 2]![0],
+        pts[pts.length - 2]![1],
+        pts[pts.length - 1]![0],
+        pts[pts.length - 1]![1]
+      );
+    }
+
+    // Byte-identical to the build: offset() lands on the scratch copy, never
+    // on the prefix, so a picture recorded from it stays valid.
+    expect(snapshot(prefix)).toEqual(atBuild);
+    expect(prefix.rewinds).toBe(1);
+    // dx moved (leftwards, as time advances) — the frames really did scroll.
+    expect(
+      lineScrollDx(hz.slot, makeLayout(NOW + 200 * 0.0167, 90, 110))
+    ).toBeLessThan(-1);
+  });
+
+  it('allocates the tail scratch once and reuses it', () => {
+    const { hz, data, smooth } = builtHarness();
+    let made = 0;
+    for (let f = 1; f <= 5; f++) {
+      const t = NOW + f;
+      const layout = makeLayout(t, 90, 110);
+      const pts = buildPts(data, layout, smooth, t);
+      const before = hz.made.length;
+      assembleLineTailStroke(
+        hz.slot,
+        hz.makePath,
+        layout,
+        pts[pts.length - 2]![0],
+        pts[pts.length - 2]![1],
+        pts[pts.length - 1]![0],
+        pts[pts.length - 1]![1]
+      );
+      made += hz.made.length - before;
+    }
+    expect(made).toBe(1); // only the first frame allocated tailScratch
+    expect((hz.slot.tailScratch as FakePath).rewinds).toBe(5);
+  });
+
+  it('starts the tail exactly at cutX + dx with the cached cutY', () => {
+    const { hz, data, smooth } = builtHarness();
+    const later = NOW + 4.2;
+    const layout = makeLayout(later, 90, 110);
+    const pts = buildPts(data, layout, smooth, later);
+    assembleLineTailStroke(
+      hz.slot,
+      hz.makePath,
+      layout,
+      pts[pts.length - 2]![0],
+      pts[pts.length - 2]![1],
+      pts[pts.length - 1]![0],
+      pts[pts.length - 1]![1]
+    );
+
+    const dx = layout.toX(hz.slot.tRef) - hz.slot.xRefAtBuild;
+    expect(lineScrollDx(hz.slot, layout)).toBe(dx);
+    expect(dx).not.toBe(0);
+
+    const tail = (hz.slot.tailScratch as FakePath).verbs;
+    expect(tail[0]!.op).toBe('M');
+    expect(tail[0]!.c[0]!).toBe(hz.slot.cutX + dx);
+    expect(tail[0]!.c[1]!).toBe(hz.slot.cutY);
+    expect(tail.length).toBe(3); // moveTo + two tail cubics
+    expect(tail[1]!.op).toBe('C');
+    expect(tail[2]!.op).toBe('C');
+
+    // The start point is exactly the translated prefix's last on-curve
+    // point, so the two pieces meet with no gap.
+    const prefixVerbs = (hz.slot.prefix as FakePath).verbs;
+    const lastPrefix = prefixVerbs[prefixVerbs.length - 1]!;
+    expect(lastPrefix.c[4]! + dx).toBe(tail[0]!.c[0]!);
+    expect(lastPrefix.c[5]!).toBe(tail[0]!.c[1]!);
+  });
+
+  it('translated prefix + tail is the same geometry as the combined path', () => {
+    const { hz, data, smooth } = builtHarness();
+    const later = NOW + 4.2;
+    const layout = makeLayout(later, 90, 110);
+    const pts = buildPts(data, layout, smooth, later);
+    const args: [number, number, number, number] = [
+      pts[pts.length - 2]![0],
+      pts[pts.length - 2]![1],
+      pts[pts.length - 1]![0],
+      pts[pts.length - 1]![1],
+    ];
+    assembleLineTail(hz.slot, hz.makePath, layout, true, ...args, pts[0]![1]);
+    assembleLineTailStroke(hz.slot, hz.makePath, layout, ...args);
+
+    const dx = lineScrollDx(hz.slot, layout);
+
+    // What the scroll layer draws: prefix recorded at build time, moved by
+    // translateX = dx, then the live tail.
+    const drawn = new FakePath();
+    drawn.addPath(hz.slot.prefix!);
+    drawn.offset(dx, 0);
+    const tailVerbs = (hz.slot.tailScratch as FakePath).verbs;
+    // Skip the tail's leading moveTo — it re-states the point the prefix
+    // already ends on (asserted exactly equal in the test above).
+    for (let i = 1; i < tailVerbs.length; i++) {
+      drawn.verbs.push({ op: tailVerbs[i]!.op, c: tailVerbs[i]!.c.slice() });
+    }
+
+    const combined = (hz.slot.scratch as FakePath).verbs;
+    expect(drawn.verbs.length).toBe(combined.length);
+    for (let i = 0; i < combined.length; i++) {
+      expect(drawn.verbs[i]!.op).toBe(combined[i]!.op);
+      for (let k = 0; k < combined[i]!.c.length; k++) {
+        expect(drawn.verbs[i]!.c[k]!).toBe(combined[i]!.c[k]!);
+      }
+    }
+  });
+
+  it('leaves the fill path byte-identical to the unsplit construction', () => {
+    const { hz, data, smooth } = builtHarness();
+    const later = NOW + 4.2;
+    const layout = makeLayout(later, 90, 110);
+    const pts = buildPts(data, layout, smooth, later);
+    const tipX = pts[pts.length - 1]![0];
+    const firstY = pts[0]![1];
+
+    assembleLineTail(
+      hz.slot,
+      hz.makePath,
+      layout,
+      true,
+      pts[pts.length - 2]![0],
+      pts[pts.length - 2]![1],
+      tipX,
+      pts[pts.length - 1]![1],
+      firstY
+    );
+    // …and the split call, which must not disturb the fill at all.
+    assembleLineTailStroke(
+      hz.slot,
+      hz.makePath,
+      layout,
+      pts[pts.length - 2]![0],
+      pts[pts.length - 2]![1],
+      tipX,
+      pts[pts.length - 1]![1]
+    );
+
+    // Literal re-implementation of the fill block as it stands today.
+    const expected = new FakePath();
+    const baseY = layout.h - layout.pad.bottom;
+    const firstX = layout.toX(hz.slot.tRef);
+    expected.moveTo(firstX, baseY);
+    expected.lineTo(firstX, firstY);
+    expected.addPath(hz.slot.scratch!, undefined, true);
+    expected.lineTo(tipX, baseY);
+    expected.close();
+
+    expect((hz.slot.fillScratch as FakePath).verbs).toEqual(expected.verbs);
+  });
+});
+
 // decimateMinMax's own correctness (including the bucketSecs absolute-grid
 // path) is covered in math/__tests__/math.test.ts, next to its other tests —
 // this file only tests what's specific to the cache built on top of it.
diff --git a/src/draw/line.ts b/src/draw/line.ts
index 7f04cf6..c570df2 100644
--- a/src/draw/line.ts
+++ b/src/draw/line.ts
@@ -67,12 +67,47 @@ function blendColor(c1: string, c2: string, t: number): SkColor {
   return rgbColor(r, g, b, a);
 }
 
-/** Path factory for the line cache — SkPath satisfies CachePath structurally. */
-function makeSkPath(): CachePath {
+/**
+ * Path factory for the line cache — SkPath satisfies CachePath structurally.
+ * Exported so callers that assemble cache paths outside drawLine (the
+ * declarative scroll layer, which records the prefix stroke into a picture
+ * and strokes the tail live) allocate through the same factory.
+ */
+export function makeSkPath(): CachePath {
   'worklet';
   return Skia.Path.Make();
 }
 
+/**
+ * Strokes an already-built cache path with the line's style. Factored out of
+ * `renderCurvePaths` so the split prefix/tail strokes are painted with
+ * byte-identical paint state to the combined path — there is exactly one
+ * place the line's stroke style is written.
+ *
+ * Restores `ctx.globalAlpha` to what it was on entry, so it composes with a
+ * caller that has already scaled alpha (e.g. the scrub dimming).
+ */
+export function strokeLinePath(
+  ctx: Ctx2D,
+  palette: LivelinePalette,
+  stroke: CachePath,
+  lineAlpha: number,
+  strokeColor?: Style2D
+) {
+  'worklet';
+  const baseAlpha = ctx.globalAlpha;
+  ctx.globalAlpha = baseAlpha * lineAlpha;
+  // Cache paths are always real SkPaths at runtime (built by makeSkPath);
+  // CachePath is just the Skia-free structural type for testability.
+  ctx.beginPathFrom(stroke as SkPath);
+  ctx.strokeStyle = strokeColor ?? palette.line;
+  ctx.lineWidth = palette.lineWidth;
+  ctx.lineJoin = 'round';
+  ctx.lineCap = 'round';
+  ctx.stroke();
+  ctx.globalAlpha = baseAlpha;
+}
+
 /**
  * Draw the fill gradient + stroke line from pre-assembled cache paths.
  * Style handling mirrors renderCurve exactly; only the path source differs
@@ -102,16 +137,10 @@ function renderCurvePaths(
     ctx.beginPathFrom(fill as SkPath);
     ctx.fillStyle = grad;
     ctx.fill();
+    ctx.globalAlpha = baseAlpha;
   }
 
-  ctx.globalAlpha = baseAlpha * lineAlpha;
-  ctx.beginPathFrom(stroke as SkPath);
-  ctx.strokeStyle = strokeColor ?? palette.line;
-  ctx.lineWidth = palette.lineWidth;
-  ctx.lineJoin = 'round';
-  ctx.lineCap = 'round';
-  ctx.stroke();
-  ctx.globalAlpha = baseAlpha;
+  strokeLinePath(ctx, palette, stroke, lineAlpha, strokeColor);
 }
 
 /** Draw the fill gradient + stroke line for a set of points. */
diff --git a/src/draw/lineCache.ts b/src/draw/lineCache.ts
index 1c83c31..d317bd2 100644
--- a/src/draw/lineCache.ts
+++ b/src/draw/lineCache.ts
@@ -51,6 +51,10 @@ export interface LineCacheSlot {
   scratch: CachePath | null;
   /** Assembled fill path (valid only when wantFill was true). */
   fillScratch: CachePath | null;
+  /** Tail-only stroke path in CURRENT screen coords: moveTo(cutX + dx, cutY)
+   * then the same two tail cubics `scratch` ends with. Valid only after
+   * `assembleLineTailStroke` (never written by `assembleLineTail`). */
+  tailScratch: CachePath | null;
 
   // Prefix metadata
   tRef: number; // decimated[0].time at build
@@ -89,6 +93,7 @@ export function createLineCacheSlot(): LineCacheSlot {
     prefix: null,
     scratch: null,
     fillScratch: null,
+    tailScratch: null,
     tRef: 0,
     xRefAtBuild: 0,
     cutX: 0,
@@ -153,6 +158,27 @@ export function lineCacheHits(
   );
 }
 
+/**
+ * Horizontal scroll of the cached prefix since it was built, in screen px.
+ *
+ * The ONE place this subtraction is written, so the combined path, the
+ * split-out tail and any caller that translates the prefix itself (the
+ * declarative scroll layer) can never disagree about where the prefix is.
+ * Always recomputed against the build-time reference — never accumulated —
+ * so there is no drift; see the note on `assembleLineTail` below.
+ *
+ * Returns 0 for a slot with no prefix (tRef/xRefAtBuild are both still 0
+ * only by coincidence there, so callers should gate on `slot.prefix`).
+ *
+ * Identical formula to `scrollLayer.ts`'s `scrollLayerDx` — a scroll-layer
+ * slot wrapping the prefix picture takes its `tRef`/`xRefAtBuild` straight
+ * from this slot, and the two then agree by construction.
+ */
+export function lineScrollDx(slot: LineCacheSlot, layout: ChartLayout): number {
+  'worklet';
+  return layout.toX(slot.tRef) - slot.xRefAtBuild;
+}
+
 /**
  * Assembles `slot.scratch` (and `slot.fillScratch` when `wantFill`) from an
  * already-valid `slot.prefix` plus this frame's two live tail points — the
@@ -186,7 +212,7 @@ export function assembleLineTail(
   firstY: number
 ): void {
   'worklet';
-  const dx = layout.toX(slot.tRef) - slot.xRefAtBuild;
+  const dx = lineScrollDx(slot, layout);
 
   // Assemble the stroke path: translated prefix + live tail.
   slot.scratch = ensured(slot.scratch, makePath);
@@ -222,6 +248,104 @@ export function assembleLineTail(
   }
 }
 
+/**
+ * ── Split stroke API (declarative scroll layer) ────────────────────────────
+ *
+ * The declarative render shell wants the line's stroke as two *separately
+ * drawable* pieces: the prefix, recorded once into a picture and moved by a
+ * `<Group transform>`, and the tail, drawn live every frame. This section
+ * adds exactly that, additively — `assembleLineTail` above and its combined
+ * `slot.scratch` / `slot.fillScratch` are untouched and still the only thing
+ * `drawLine` uses.
+ *
+ * Shape of the API, and why:
+ *
+ * - **The prefix is exposed as `slot.prefix` itself** (via `linePrefixPath`
+ *   for a documented, null-checked accessor) rather than as a fresh
+ *   untranslated copy. No copy is needed: `assembleLineTail` translates the
+ *   *scratch* — `scratch.addPath(slot.prefix)` then `scratch.offset(dx, 0)`
+ *   — so the offset lands on the copy inside `scratch`, never on `prefix`.
+ *   `slot.prefix` is written in exactly one place (the miss branch of
+ *   `updateLinePaths`) and is only ever read afterwards, so it stays in
+ *   build-time coordinates for its whole life. A second copy would cost an
+ *   extra native path per slot and one more thing to keep in sync, and would
+ *   buy nothing. The caller supplies the transform: `translateX` =
+ *   `lineScrollDx(slot, layout)`.
+ *
+ * - **The tail gets its own slot-owned scratch** (`slot.tailScratch`) filled
+ *   by `assembleLineTailStroke`, in current screen coordinates, because
+ *   unlike the prefix it has no cached representation to reuse — it is
+ *   rebuilt from this frame's two moving points regardless.
+ *
+ * - **The tail is re-emitted rather than sliced out of `slot.scratch`.**
+ *   Building the combined path as prefix + `addPath(tailScratch, …, true)`
+ *   would insert a zero-length connector verb and stop the combined path
+ *   from being verb-for-verb what it is today; two extra `cubicTo`s per
+ *   frame is the cheaper price. The tail starts at `slot.cutX + dx` with
+ *   `slot.endTangent`, the same arguments `assembleLineTail` passes, so the
+ *   join with the translated prefix is the identical C1-continuous one.
+ *
+ * - **The fill is NOT split**, deliberately. It is one closed
+ *   semi-transparent polygon; abutting two halves leaves a hairline seam
+ *   (antialiased coverage on a shared edge sums to ~0.75), overlapping them
+ *   double-darkens a 1px column, and a non-AA clip split only tiles exactly
+ *   when both sides round a fractional `dx` identically. Whoever consumes
+ *   this API keeps drawing the whole fill live from `slot.fillScratch`.
+ */
+
+/**
+ * The prefix stroke — the spline through decimated points `0..N-2` — in
+ * BUILD-TIME screen coordinates. Null until a prefix has been built.
+ *
+ * Never mutated by translation (see the section comment above), so it is
+ * safe to record into a long-lived picture: the picture stays valid until
+ * the next `lineCacheHits` miss rebuilds the prefix, and the caller moves it
+ * with `lineScrollDx(slot, layout)` on the x axis.
+ */
+export function linePrefixPath(slot: LineCacheSlot): CachePath | null {
+  'worklet';
+  return slot.prefix;
+}
+
+/**
+ * Assembles `slot.tailScratch`: the tail stroke alone, in CURRENT screen
+ * coordinates — `moveTo(slot.cutX + dx, slot.cutY)` followed by the same two
+ * cubics `assembleLineTail` appends to the combined path. Drawing the
+ * translated prefix and this back to back is geometrically identical to
+ * drawing `slot.scratch`; only the leading `moveTo` differs, and it lands
+ * exactly on the translated prefix's last on-curve point.
+ *
+ * Independent of `assembleLineTail` — callers that want both call both.
+ * Caller guarantees `slot.prefix` is non-null (same contract as
+ * `assembleLineTail`).
+ */
+export function assembleLineTailStroke(
+  slot: LineCacheSlot,
+  makePath: () => CachePath,
+  layout: ChartLayout,
+  lastX: number,
+  lastY: number,
+  tipX: number,
+  tipY: number
+): void {
+  'worklet';
+  const dx = lineScrollDx(slot, layout);
+  slot.tailScratch = ensured(slot.tailScratch, makePath);
+  const tail = slot.tailScratch;
+  tail.rewind();
+  tail.moveTo(slot.cutX + dx, slot.cutY);
+  drawSplineTail(
+    tail,
+    slot.cutX + dx,
+    slot.cutY,
+    slot.endTangent,
+    lastX,
+    lastY,
+    tipX,
+    tipY
+  );
+}
+
 /**
  * Key-compare (via `lineCacheHits`) → on miss rebuild the prefix → assemble
  * `slot.scratch` (and `slot.fillScratch` when `wantFill`) for this frame.

From 3bc2d7468665a5a5adf798eb9575eb20fe491e47 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Fri, 31 Jul 2026 08:49:41 -0400
Subject: [PATCH 11/37] docs: fix declarative design omissions found during
 implementation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Stream A caught that src/draw/scrollLayer.ts already exists on this branch
(3db71f1) with the slot type, the dx formula and the alpha gate integration
needs — and that the design doc mentioned none of it, nor listed it in either
workstream's files. Integration should reuse it, not re-derive dx and alpha
handling. Also disambiguates scrollLayerDx (a pure function returning a number)
from scrollTransform (a shared value holding [{translateX}]), which earlier
wording conflated.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../2026-07-31-declarative-shell-design.md    | 26 +++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/docs/superpowers/specs/2026-07-31-declarative-shell-design.md b/docs/superpowers/specs/2026-07-31-declarative-shell-design.md
index 3637b8f..64cf513 100644
--- a/docs/superpowers/specs/2026-07-31-declarative-shell-design.md
+++ b/docs/superpowers/specs/2026-07-31-declarative-shell-design.md
@@ -121,6 +121,32 @@ Two workstreams, deliberately chosen for file disjointness:
 Integration (wiring A's prefix stroke into B's `scrollPicture`, plus the alpha
 gate) is a third, sequential step once both land.
 
+### Reuse `src/draw/scrollLayer.ts` — do not re-derive
+
+**Added 2026-07-31 after stream A flagged the omission.** This branch already
+carries `src/draw/scrollLayer.ts` (commit `3db71f1`, "scroll-layer slot
+foundation"), which provides exactly what integration needs and which the
+original version of this doc failed to mention or place in either workstream's
+file list:
+
+- `ScrollLayerSlot<Picture>` — picture + build-time `tRef`/`xRefAtBuild` +
+  per-slot clip region + a push-built invalidation key.
+- `scrollLayerDx(slot, layout)` — the dx formula, identical to `lineCache.ts`'s
+  `lineScrollDx`. A slot wrapping the line's prefix picture takes its
+  `tRef`/`xRefAtBuild` straight from the line cache slot, so the two agree by
+  construction.
+- `scrollLayerUsable(slot, alpha)` — the alpha≥1 gate described below, already
+  written.
+
+Integration must consume these rather than re-implement dx or alpha handling.
+
+### Naming collision to avoid
+
+`scrollLayerDx(slot, layout)` is a **pure function returning a number**.
+`scrollTransform` is a **shared value holding `[{ translateX }]`** that
+`<Group transform>` reads. Earlier wording in this doc blurred the two; they are
+different things, and the frame callback converts the former into the latter.
+
 ## Risks
 
 - **Double-draw.** Once integrated, `screenPicture` must not also draw the

From 54ed7063759e6c665bb4c8b8e0b1a47be06710db Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Fri, 31 Jul 2026 19:57:05 -0400
Subject: [PATCH 12/37] fix: widen gesture-handler peer range, drop dead files
 entries, document traps
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Four independent cleanups from the best-practices audit.

1. peerDependencies react-native-gesture-handler >=3.0.0 -> >=2.30.0.

   The v3 floor existed only because useLivelineEngine imported the type
   `LegacyComposedGesture`, which is a v3 name. That import was also just
   wrong: this hook always returns a single Gesture.Pan() and never composes,
   so `ComposedGesture | GestureType` was an over-broad union. Narrowed to
   `GestureType`, which exists in both majors.

   The floor mattered because Expo SDK 55 pins ~2.30.0, so every SDK 55
   consumer hit a peer conflict and an expo-doctor failure on install.

   Verified end-to-end, not by inspection: installed react-native-gesture-
   handler@2.30.0 at the repo root and ran the real typecheck. src/ compiles
   clean and all 239 tests pass. Confirmed the test has teeth by re-adding the
   v3-only import under that install and watching it fail with TS2724 "has no
   exported member named 'LegacyComposedGesture'". Two earlier attempts at this
   verification (tsconfig paths override, then installing only into the example
   workspace) silently kept resolving to 3.1.0 and proved nothing.

   The example app stays on 3.1.0 deliberately, so its expo-doctor warning
   remains — that is the example's pin, no longer a library constraint.

2. files[] listed android, ios, cpp, *.podspec and react-native.config.js.
   None of them exist; this is a JS-only library. npm pack still emits 255
   files / 1.3 MB, unchanged.

3. Liveline.tsx documents why `androidWarmup` and `opaque` are NOT set on
   <Canvas>. androidWarmup is a GPU->CPU pixel readback inside onDraw
   (SkiaPictureView.java) and is catastrophic on a continuously-invalidating
   view. `opaque` is what selects SurfaceView over TextureView on Android and
   would likely composite cheaper, but an opaque surface has no destination
   alpha and both drawEdgeFade and drawEmpty composite with destination-out,
   which would erase to black.

4. README documents hoisting config props. Liveline is memo'd with a shallow
   compare, and inline object/function props do more than waste a render: the
   engine mirrors config into a shared value every commit and the frame loop's
   idle detection keys off that object's identity, so a chart fed fresh props
   each render can never go idle. Placed next to the FlatList recipe, which is
   exactly where one row's tick re-renders every row.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 README.md                | 39 +++++++++++++++++++++++++++++++++++++++
 package.json             | 13 +------------
 src/Liveline.tsx         | 17 +++++++++++++++++
 src/useLivelineEngine.ts | 21 ++++++++++++---------
 4 files changed, 69 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index 96178c9..0b879b3 100644
--- a/README.md
+++ b/README.md
@@ -281,6 +281,45 @@ function TickerList({ rows }: { rows: Ticker[] }) {
 }
 ```
 
+#### Hoist object and function props
+
+`Liveline` is wrapped in `React.memo`, and its props are compared shallowly. A
+new object or function identity on every parent render defeats that — and it
+costs more than a wasted render. The engine mirrors its config into a shared
+value on every commit, and the frame loop's idle detection keys off that
+config's object identity, so a chart that receives fresh props each render can
+never go idle even when nothing about it has changed.
+
+This matters most in exactly the list above, where one row's tick re-renders the
+whole list.
+
+```tsx
+// ✗ new identity every render — memo always misses, chart never idles
+<Liveline
+  data={item.data}
+  padding={{ top: 8, right: 60, bottom: 24, left: 8 }}
+  windows={[{ secs: 30, label: '30s' }, { secs: 60, label: '1m' }]}
+  formatValue={(v) => `$${v.toFixed(2)}`}
+/>
+
+// ✓ hoisted to module scope (or useMemo / useCallback if they depend on props)
+const PADDING = { top: 8, right: 60, bottom: 24, left: 8 };
+const WINDOWS = [{ secs: 30, label: '30s' }, { secs: 60, label: '1m' }];
+const formatUsd = (v: number) => {
+  'worklet';
+  return `$${v.toFixed(2)}`;
+};
+
+<Liveline data={item.data} padding={PADDING} windows={WINDOWS} formatValue={formatUsd} />
+```
+
+`data` and `value` are expected to change — that is the live feed, and the
+engine diffs `data` rather than re-sending it. It is the *configuration* props
+that should be stable.
+
+Note that `formatValue` / `formatTime` run on the UI thread and need the
+`'worklet'` directive, which also makes hoisting them the natural choice.
+
 ### `LivelineTransition`
 
 Cross-fades between chart components (e.g. line ↔ candlestick). Children must
diff --git a/package.json b/package.json
index d37e5b5..d149d6a 100644
--- a/package.json
+++ b/package.json
@@ -16,17 +16,6 @@
   "files": [
     "src",
     "lib",
-    "android",
-    "ios",
-    "cpp",
-    "*.podspec",
-    "react-native.config.js",
-    "!ios/build",
-    "!android/build",
-    "!android/gradle",
-    "!android/gradlew",
-    "!android/gradlew.bat",
-    "!android/local.properties",
     "!**/__tests__",
     "!**/__fixtures__",
     "!**/__mocks__",
@@ -97,7 +86,7 @@
     "@shopify/react-native-skia": ">=2.0.0",
     "react": "*",
     "react-native": "*",
-    "react-native-gesture-handler": ">=3.0.0",
+    "react-native-gesture-handler": ">=2.30.0",
     "react-native-reanimated": ">=4.0.0",
     "react-native-worklets": ">=0.3.0"
   },
diff --git a/src/Liveline.tsx b/src/Liveline.tsx
index 3756bf1..bb8c035 100644
--- a/src/Liveline.tsx
+++ b/src/Liveline.tsx
@@ -596,6 +596,23 @@ export const Liveline = memo(function LivelineComponent({
             redraw(). Keep it that way: no conditionals, no .map(), nothing
             that can add or remove a node, or the chart stops animating while
             the JS thread is blocked.
+
+            Two <Canvas> props are deliberately NOT set here:
+
+            - `androidWarmup` — do not enable. It exists to hide a first-frame
+              flash, but SkiaPictureView.java implements it as a GPU→CPU pixel
+              readback inside onDraw (getBitmap -> int[] -> Bitmap.createBitmap
+              -> drawBitmap). On a view that invalidates continuously, as this
+              one does, that is catastrophic.
+            - `opaque` — leaving it false is what makes react-native-skia back
+              this view with a TextureView rather than a SurfaceView (see
+              SkiaBaseView.setOpaque). SurfaceView would very likely composite
+              cheaper on Android, but an opaque surface has no destination
+              alpha, and both drawEdgeFade and drawEmpty composite with
+              `destination-out` — on an opaque surface those erase to black
+              instead of to transparent. Exposing `opaque` as an opt-in for
+              consumers who sit the chart on a solid background is a real
+              option; flipping it by default is not.
           */}
           <Canvas style={styles.canvas}>
             <Group transform={engine.scrollTransform}>
diff --git a/src/useLivelineEngine.ts b/src/useLivelineEngine.ts
index 48b130a..28a1eb9 100644
--- a/src/useLivelineEngine.ts
+++ b/src/useLivelineEngine.ts
@@ -14,14 +14,17 @@ import {
   type SharedValue,
 } from 'react-native-reanimated';
 import { Gesture } from 'react-native-gesture-handler';
-// `Gesture.Pan()` is the classic (pre-v3) builder API, whose composed-gesture
-// result type the package now exposes as `LegacyComposedGesture` — the plain
-// `ComposedGesture` name was reassigned to the new v3 declarative gesture
-// model, which this classic API doesn't produce.
-import type {
-  LegacyComposedGesture as ComposedGesture,
-  GestureType,
-} from 'react-native-gesture-handler';
+// `GestureType` only — deliberately NOT `LegacyComposedGesture`. This hook
+// always returns a single `Gesture.Pan()` and never composes, so the old
+// `ComposedGesture | GestureType` union was over-broad. It also mattered for
+// compatibility: `LegacyComposedGesture` is a gesture-handler v3 name that
+// does not exist in v2, and importing it forced the peerDependency to
+// `>=3.0.0` — which fails `expo-doctor` for every Expo SDK 55 consumer, since
+// that SDK pins `~2.30.0`. `GestureType` exists in both majors (verified
+// against the published 2.30.0 typings), as do every builder method used
+// below: Pan, enabled, activateAfterLongPress, onBegin/onStart/onUpdate/
+// onFinalize.
+import type { GestureType } from 'react-native-gesture-handler';
 import {
   createCanvas2D,
   createSkiaCache,
@@ -144,7 +147,7 @@ export interface LivelineEngine {
    */
   scrollTransform: SharedValue<Transforms3d>;
   /** Pan gesture driving crosshair scrub — attach with <GestureDetector> */
-  gesture: ComposedGesture | GestureType;
+  gesture: GestureType;
   /** Attach to the chart container to feed the engine its size */
   onLayout: (e: LayoutChangeEvent) => void;
   /** Live value text (when showValue) — bind via useAnimatedProps */

From af7424b212dbeda90498f25e39596c5c62505532 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Fri, 31 Jul 2026 22:12:57 -0400
Subject: [PATCH 13/37] feat: wire line prefix stroke into the scroll layer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Completes the declarative shell. The single-series line's prefix stroke is now
recorded once into scrollPicture and translated by <Group transform> instead of
being re-recorded each frame; screenPicture draws the tail stroke, the whole
fill polygon, and everything else. Multi-series and candle mode are untouched
by construction.

Fixes a defect a concurrent review found in 2e1c4d7: `scrollDx` initialised to
0 and `dx` was the literal 0, so the guard `if (scrollDx.value !== dx)` was
`0 !== 0` and the scrollTransform write was UNREACHABLE. The shared-value ->
<Group transform> binding had therefore never executed, which means that
commit's "verified pixel-identical" screenshot proved the tree renders but
proved nothing about the binding it was supposed to de-risk.

That binding is now verified positively, not assumed: forcing dx = scrollDx+40
made the prefix stroke visibly detach and slide 40px clear of the fill, which
simultaneously proves scrollPicture is populated, the transform prop fires on
the UI thread, and there is NO double-draw (no stroke was left behind on the
fill edge, so screenPicture really is drawing the tail only). Probe reverted.

The split is gated on a lineCacheHits hit computed BEFORE drawFrame, so the
picture can never be recorded from a prefix the frame's own screen pass has
already moved past — one re-record per miss, on the following frame.

Alpha gate returns 1 or 0 only, never a partial: drawPicture ignores
globalAlpha, so reveal morph, scrub dimming and degen shake all fall back to
the unchanged combined path.

Z-order note: the prefix stroke now composites below the fill rather than
above. This is a no-op through the public API — theme.ts derives
fillTop/fillBottom from the same rgb as the line, and `color?: string` is the
only colour knob, so the fill hue can never differ from the stroke hue.

Removes src/draw/timeAxisLayer.ts and its 41 tests. It had no consumer
anywhere, shipped to users via files[]/src, and the review found it carried
both a missing worklet-ordering NOTE and a label-set identity that cannot
detect a scale change — with a test asserting that defect was correct.
Recoverable from 302df29 / 82d8f6b on perf/scroll-layer-architecture.

Tests 239 -> 224 (+26 lineScrollLayer, -41 timeAxisLayer). Verified on the iOS
simulator. NOT verified: the scrub fallback path — synthetic input cannot
engage the pan gesture (documented in run-and-profile), so that needs a human.

This is an architecture change, not a speedup. It removes roughly one draw call
per frame against a measured baseline where the entire time axis is 4.2% of a
core.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md                               |  61 +++
 src/draw/__tests__/lineScrollLayer.test.ts | 207 ++++++++
 src/draw/__tests__/timeAxisLayer.test.ts   | 535 ---------------------
 src/draw/line.ts                           |  45 +-
 src/draw/lineCache.ts                      |  17 +
 src/draw/lineScrollLayer.ts                | 122 +++++
 src/draw/timeAxisLayer.ts                  | 367 --------------
 src/engine/lineScrollLayer.ts              | 115 +++++
 src/engine/state.ts                        |  16 +
 src/engine/step.ts                         |  81 +++-
 src/useLivelineEngine.ts                   |  39 +-
 11 files changed, 683 insertions(+), 922 deletions(-)
 create mode 100644 src/draw/__tests__/lineScrollLayer.test.ts
 delete mode 100644 src/draw/__tests__/timeAxisLayer.test.ts
 create mode 100644 src/draw/lineScrollLayer.ts
 delete mode 100644 src/draw/timeAxisLayer.ts
 create mode 100644 src/engine/lineScrollLayer.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 646d360..79adec9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,67 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+### Fixed
+
+- **`react-native-gesture-handler` peer range widened to `>=2.30.0`** (was
+  `>=3.0.0`). The v3 floor existed only because the engine imported a
+  v3-only type name for a union it never used — the hook always returns a
+  single `Gesture.Pan()`, so the return type is now just `GestureType`,
+  which exists in both majors. Expo SDK 55 pins `~2.30.0`, so every SDK 55
+  consumer previously hit a peer conflict and an `expo-doctor` failure on
+  install. Verified by installing 2.30.0 and running the real typecheck, not
+  by inspection.
+
+### Changed
+
+- **Declarative render shell** — the chart now renders as a fixed four-node
+  Skia tree (`<Canvas>` → `<Group transform>` → `<Picture>`, plus a sibling
+  `<Picture>`) instead of a single picture. The structure never changes after
+  mount, so the Reanimated mapper that drives it stays entirely on the UI
+  thread and the "keeps animating while the JS thread is blocked" guarantee
+  is preserved. This is an architecture change, not a performance one — see
+  `docs/superpowers/specs/2026-07-31-declarative-shell-design.md`.
+- **The single-series line's prefix stroke moved into that scroll layer** —
+  the spline through all but the last data point is recorded once into its
+  own `SkPicture` and composited at a horizontal offset via
+  `<Group transform>`, re-recorded only when the line path cache misses; the
+  per-frame screen picture strokes only the tail. The fill polygon is
+  deliberately **not** split (it is one semi-transparent closed shape; every
+  way of cutting it leaves a seam or a double-darkened column) and is still
+  drawn whole every frame. Any frame that can't composite the layer at
+  alpha 1 — the reveal morph, the loading/empty crossfade, scrub dimming,
+  the degen shake — falls back to drawing the whole line live, because
+  `drawPicture` ignores `globalAlpha`. Multi-series and candle mode are
+  untouched and keep drawing the combined path. In accounting terms this
+  removes roughly one draw call per frame; it was not measurable on device
+  and no speedup is claimed for it.
+- **Time-axis labels no longer re-format every frame** — `formatTime` is a
+  pure function of a label's key, but the axis called it for every label on
+  every frame and overwrote each label's text with a byte-identical string
+  (~360 calls/sec at a 30s window, each allocating a `Date` and three
+  `padStart` results with the default formatter). It now runs only for a key
+  seen for the first time; a formatter swap is caught by reference identity
+  and re-texts live labels in place without disturbing their fades. Also
+  fixes a churn bug found by the new tests: labels one interval beyond each
+  edge — deliberately targeted, but at alpha 0 — were deleted and re-created
+  every single frame forever. Purely internal; per-label alpha, crossfades
+  and edge fades are unchanged. Worth ~35% of that function's JS time in
+  isolation, and undetectable on device (the whole time axis is 4.2% of a
+  core).
+
+### Removed
+
+- **`src/draw/timeAxisLayer.ts` and its tests** — pure label-selection logic
+  built for a time-axis scroll layer that was measured, priced and parked
+  rather than adopted, and which nothing imported. Recoverable from
+  `302df29` / `82d8f6b` on `perf/scroll-layer-architecture` if the axis ever
+  moves into a scroll layer. No API change; the module was never exported.
+- **Non-existent `android`, `ios`, `cpp`, `*.podspec` and
+  `react-native.config.js` entries from `files[]`** — this is a JS-only
+  library. `npm pack` output is unchanged (255 files, 1.3 MB).
+
 ## [0.2.1] - 2026-07-28
 
 ### Changed
diff --git a/src/draw/__tests__/lineScrollLayer.test.ts b/src/draw/__tests__/lineScrollLayer.test.ts
new file mode 100644
index 0000000..561a3ef
--- /dev/null
+++ b/src/draw/__tests__/lineScrollLayer.test.ts
@@ -0,0 +1,207 @@
+import { lineScrollLayerAlpha, writeLineScrollKey } from '../lineScrollLayer';
+import {
+  createScrollLayerSlot,
+  scrollLayerBuilt,
+  scrollLayerKeyHits,
+  type ScrollLayerSlot,
+} from '../scrollLayer';
+import { createLineCacheSlot, type LineCacheSlot } from '../lineCache';
+import type { LivelinePalette } from '../../types';
+
+// Stand-in for SkPicture — `ScrollLayerSlot` takes Picture as a structural
+// type parameter so no native binding is needed (same trick as
+// scrollLayer.test.ts).
+interface FakePicture {
+  id: number;
+}
+const PICTURE: FakePicture = { id: 1 };
+
+function makePalette(overrides: Partial<LivelinePalette> = {}) {
+  return {
+    line: '#3b82f6',
+    lineWidth: 2,
+    fillTop: 'rgba(59,130,246,0.12)',
+    fillBottom: 'rgba(59,130,246,0)',
+    gridLine: '#222',
+    gridLabel: '#888',
+    dashLine: '#444',
+    ...overrides,
+  } as LivelinePalette;
+}
+
+/** A line cache slot with a plausible committed key (the fields
+ * `writeLineScrollKey` reads). `prefix` is set so the slot looks built. */
+function makeLineSlot(): LineCacheSlot {
+  const slot = createLineCacheSlot();
+  slot.prefix = {} as LineCacheSlot['prefix'];
+  slot.tRef = 1000;
+  slot.xRefAtBuild = 10;
+  slot.kDataRev = 7;
+  slot.kDataSource = 0;
+  slot.kLen = 120;
+  slot.kFirstT = 1000;
+  slot.kLastT = 1060;
+  slot.kLastV = 101.5;
+  slot.kMin = 90;
+  slot.kMax = 110;
+  slot.kWindow = 60;
+  slot.kH = 200;
+  slot.kPadTop = 10;
+  slot.kPadBottom = 20;
+  slot.kChartW = 370;
+  return slot;
+}
+
+/** Writes the key and commits it against `PICTURE`, i.e. simulates a record. */
+function record(
+  slot: ScrollLayerSlot<FakePicture>,
+  lineSlot: LineCacheSlot,
+  padLeft: number,
+  palette: LivelinePalette
+) {
+  writeLineScrollKey(slot, lineSlot, padLeft, palette);
+  scrollLayerBuilt(slot, PICTURE, lineSlot.tRef, lineSlot.xRefAtBuild);
+}
+
+describe('lineScrollLayerAlpha', () => {
+  it('is 1 only when fully revealed, not scrubbing and not shaking', () => {
+    expect(lineScrollLayerAlpha(1, 0, 0)).toBe(1);
+  });
+
+  it('is 0 during the reveal morph', () => {
+    expect(lineScrollLayerAlpha(0, 0, 0)).toBe(0);
+    expect(lineScrollLayerAlpha(0.999, 0, 0)).toBe(0);
+  });
+
+  it('tolerates a reveal lerp that overshoots its target', () => {
+    // Mirrors scrollLayerUsable's `>= 1` rather than `=== 1`.
+    expect(lineScrollLayerAlpha(1.0001, 0, 0)).toBe(1);
+  });
+
+  it('is 0 for any non-zero scrub, and 1 again once scrub snaps to 0', () => {
+    expect(lineScrollLayerAlpha(1, 0.4, 0)).toBe(0);
+    // updateHoverState snaps scrubAmount to exactly 0 below 0.01, which is
+    // what makes the gate re-enable rather than asymptote.
+    expect(lineScrollLayerAlpha(1, 0, 0)).toBe(1);
+  });
+
+  it('is 0 while the degen shake is translating the frame', () => {
+    expect(lineScrollLayerAlpha(1, 0, 0.2)).toBe(0);
+    expect(lineScrollLayerAlpha(1, 0, 12)).toBe(0);
+  });
+
+  it('never returns a partial alpha — drawPicture cannot fade', () => {
+    const values = [
+      lineScrollLayerAlpha(0.5, 0, 0),
+      lineScrollLayerAlpha(1, 0.5, 0),
+      lineScrollLayerAlpha(1, 0, 1),
+      lineScrollLayerAlpha(1, 0, 0),
+    ];
+    for (const v of values) expect(v === 0 || v === 1).toBe(true);
+  });
+});
+
+describe('writeLineScrollKey', () => {
+  it('hits when nothing has changed since the record', () => {
+    const slot = createScrollLayerSlot<FakePicture>();
+    const lineSlot = makeLineSlot();
+    const palette = makePalette();
+    record(slot, lineSlot, 10, palette);
+
+    writeLineScrollKey(slot, lineSlot, 10, palette);
+    expect(scrollLayerKeyHits(slot)).toBe(true);
+  });
+
+  it('misses before anything has been recorded', () => {
+    const slot = createScrollLayerSlot<FakePicture>();
+    writeLineScrollKey(slot, makeLineSlot(), 10, makePalette());
+    expect(scrollLayerKeyHits(slot)).toBe(false);
+  });
+
+  it.each([
+    ['kDataRev', (s: LineCacheSlot) => (s.kDataRev = 8)],
+    ['kDataSource', (s: LineCacheSlot) => (s.kDataSource = 1)],
+    ['kLen', (s: LineCacheSlot) => (s.kLen = 121)],
+    ['kFirstT', (s: LineCacheSlot) => (s.kFirstT = 1001)],
+    ['kLastT', (s: LineCacheSlot) => (s.kLastT = 1061)],
+    ['kLastV', (s: LineCacheSlot) => (s.kLastV = 101.6)],
+    ['kMin', (s: LineCacheSlot) => (s.kMin = 89)],
+    ['kMax', (s: LineCacheSlot) => (s.kMax = 111)],
+    ['kWindow', (s: LineCacheSlot) => (s.kWindow = 300)],
+    ['kH', (s: LineCacheSlot) => (s.kH = 201)],
+    ['kPadTop', (s: LineCacheSlot) => (s.kPadTop = 11)],
+    ['kPadBottom', (s: LineCacheSlot) => (s.kPadBottom = 21)],
+    ['kChartW', (s: LineCacheSlot) => (s.kChartW = 371)],
+  ])('misses when the line cache key changes: %s', (_name, mutate) => {
+    const slot = createScrollLayerSlot<FakePicture>();
+    const lineSlot = makeLineSlot();
+    const palette = makePalette();
+    record(slot, lineSlot, 10, palette);
+
+    mutate(lineSlot);
+    writeLineScrollKey(slot, lineSlot, 10, palette);
+    expect(scrollLayerKeyHits(slot)).toBe(false);
+  });
+
+  it('misses on a pad.left change — the clip is baked into the picture', () => {
+    // pad.left is deliberately NOT part of the line cache's own key (it is
+    // absorbed by dx), so this dimension can only come from here.
+    const slot = createScrollLayerSlot<FakePicture>();
+    const lineSlot = makeLineSlot();
+    const palette = makePalette();
+    record(slot, lineSlot, 10, palette);
+
+    writeLineScrollKey(slot, lineSlot, 24, palette);
+    expect(scrollLayerKeyHits(slot)).toBe(false);
+  });
+
+  it('misses on a stroke color change — a picture bakes color', () => {
+    const slot = createScrollLayerSlot<FakePicture>();
+    const lineSlot = makeLineSlot();
+    record(slot, lineSlot, 10, makePalette());
+
+    writeLineScrollKey(slot, lineSlot, 10, makePalette({ line: '#ef4444' }));
+    expect(scrollLayerKeyHits(slot)).toBe(false);
+  });
+
+  it('misses on a stroke width change', () => {
+    const slot = createScrollLayerSlot<FakePicture>();
+    const lineSlot = makeLineSlot();
+    record(slot, lineSlot, 10, makePalette());
+
+    writeLineScrollKey(slot, lineSlot, 10, makePalette({ lineWidth: 3 }));
+    expect(scrollLayerKeyHits(slot)).toBe(false);
+  });
+
+  it('ignores palette dimensions the prefix stroke does not bake', () => {
+    // Only `line`/`lineWidth` reach the recording; a grid or fill color
+    // change must not throw the picture away.
+    const slot = createScrollLayerSlot<FakePicture>();
+    const lineSlot = makeLineSlot();
+    record(slot, lineSlot, 10, makePalette());
+
+    writeLineScrollKey(
+      slot,
+      lineSlot,
+      10,
+      makePalette({ gridLine: '#fff', fillTop: 'rgba(0,0,0,0.5)' })
+    );
+    expect(scrollLayerKeyHits(slot)).toBe(true);
+  });
+
+  it('pushes the same number of dimensions every call', () => {
+    // Push order/arity is the field identity for a ScrollLayerSlot key —
+    // a conditional push would silently misalign the comparison.
+    const slot = createScrollLayerSlot<FakePicture>();
+    writeLineScrollKey(slot, makeLineSlot(), 10, makePalette());
+    const numLen = slot.nNumLen;
+    const refLen = slot.nRefLen;
+
+    const other = makeLineSlot();
+    other.kDataSource = 2;
+    other.kLastV = 0;
+    writeLineScrollKey(slot, other, 0, makePalette({ line: '#000' }));
+    expect(slot.nNumLen).toBe(numLen);
+    expect(slot.nRefLen).toBe(refLen);
+  });
+});
diff --git a/src/draw/__tests__/timeAxisLayer.test.ts b/src/draw/__tests__/timeAxisLayer.test.ts
deleted file mode 100644
index 537da6f..0000000
--- a/src/draw/__tests__/timeAxisLayer.test.ts
+++ /dev/null
@@ -1,535 +0,0 @@
-import {
-  timeAxisInterval,
-  timeAxisLabelKeys,
-  buildTimeAxisLabels,
-  timeAxisStride,
-  timeAxisLabelKept,
-  resolveTimeAxisOverlaps,
-  createTimeAxisLabelSetId,
-  writeTimeAxisLabelSetId,
-  timeAxisLabelSetIdMatches,
-} from '../timeAxisLayer';
-import type { TimeAxisLabel } from '../timeAxisLayer';
-import type { Ctx2D } from '../canvas2d';
-import type { ChartLayout, Padding } from '../../types';
-
-const PAD: Required<Padding> = { top: 10, right: 20, bottom: 24, left: 10 };
-
-/**
- * A fake `Ctx2D` — a plain object with the font slots and `measureText`.
- * This is the whole point of the type-only `Ctx2D` import in timeAxisLayer.ts:
- * no Skia binding is loaded, so jest can drive the real code path.
- * Width is `charW` per character so label widths are predictable and can be
- * pushed past the overlap threshold on demand.
- */
-function makeCtx(charW = 7): Ctx2D {
-  const fonts = {
-    label: 'label',
-    value: 'value',
-    badge: 'badge',
-    crosshair: 'crosshair',
-    orderbook: 'orderbook',
-    empty: 'empty',
-    refLabel: 'refLabel',
-    seriesLabel: 'seriesLabel',
-  };
-  return {
-    fonts,
-    font: fonts.label,
-    measureText: (text: string) => ({ width: text.length * charW }),
-  } as unknown as Ctx2D;
-}
-
-function makeLayout(
-  leftEdge: number,
-  rightEdge: number,
-  w = 400,
-  h = 200
-): ChartLayout {
-  const chartW = w - PAD.left - PAD.right;
-  const chartH = h - PAD.top - PAD.bottom;
-  const span = rightEdge - leftEdge || 1;
-  return {
-    w,
-    h,
-    pad: PAD,
-    chartW,
-    chartH,
-    leftEdge,
-    rightEdge,
-    minVal: 0,
-    maxVal: 1,
-    valRange: 1,
-    toX: (t: number) => PAD.left + ((t - leftEdge) / span) * chartW,
-    toY: (v: number) => PAD.top + (1 - v) * chartH,
-  };
-}
-
-/** Deterministic short formatter — no Date, so tests stay timezone-agnostic
- * except where the day-alignment branch is deliberately exercised. */
-const fmt = (t: number) => String(Math.round(t));
-
-describe('timeAxisInterval', () => {
-  it('returns the nice interval when it already clears 60px', () => {
-    // 30s window over 600px => 20px/s => 5s ticks are 100px apart.
-    expect(timeAxisInterval(30, 600)).toBe(5);
-  });
-
-  it('doubles until ticks are at least 60px apart on a narrow chart', () => {
-    // 30s over 120px => 4px/s. 5s=20px, 10s=40px, 20s=80px.
-    expect(timeAxisInterval(30, 120)).toBe(20);
-  });
-
-  it('never returns an interval wider than the window itself', () => {
-    // A degenerate/zero-width chart would otherwise loop forever.
-    const interval = timeAxisInterval(60, 0);
-    expect(interval).toBeGreaterThanOrEqual(60);
-    expect(Number.isFinite(interval)).toBe(true);
-  });
-
-  it('is monotonic in window size across a sweep of real windows', () => {
-    const windows = [10, 15, 30, 60, 120, 300, 600, 1800, 3600, 86400, 604800];
-    let prev = 0;
-    for (const win of windows) {
-      const interval = timeAxisInterval(win, 600);
-      expect(interval).toBeGreaterThanOrEqual(prev);
-      prev = interval;
-    }
-  });
-
-  it('yields tick spacing >= 60px whenever the window allows it', () => {
-    const chartW = 370;
-    for (const win of [15, 30, 60, 120, 300, 600, 1800, 3600, 14400, 43200]) {
-      const interval = timeAxisInterval(win, chartW);
-      const spacing = interval * (chartW / win);
-      expect(spacing >= 60 || interval >= win).toBe(true);
-    }
-  });
-
-  it('derives from the target window, not the display window', () => {
-    // The function only takes the target window — the "one-frame flicker at
-    // transition end" bug is structurally impossible. Same target, different
-    // in-flight display windows, same answer.
-    expect(timeAxisInterval(60, 600)).toBe(timeAxisInterval(60, 600));
-  });
-});
-
-describe('timeAxisLabelKeys', () => {
-  it('covers the view plus one interval of buffer on each side', () => {
-    const out: number[] = [];
-    const n = timeAxisLabelKeys(10, 100, 160, out);
-    const times = out.slice(0, n).map((k) => k / 100);
-    expect(times[0]).toBeLessThanOrEqual(100);
-    expect(times[0]).toBeGreaterThanOrEqual(90 - 10);
-    expect(times[times.length - 1]).toBeGreaterThanOrEqual(160);
-    for (let i = 1; i < times.length; i++) {
-      expect(times[i]! - times[i - 1]!).toBeCloseTo(10);
-    }
-  });
-
-  it('emits ascending keys so no sort is needed downstream', () => {
-    const out: number[] = [];
-    const n = timeAxisLabelKeys(5, 1000, 1060, out);
-    for (let i = 1; i < n; i++) expect(out[i]!).toBeGreaterThan(out[i - 1]!);
-  });
-
-  it('aligns to local midnight for day-or-longer intervals', () => {
-    const out: number[] = [];
-    // Three days of view with 1-day ticks.
-    const start = Date.UTC(2026, 0, 10, 13, 45) / 1000;
-    const n = timeAxisLabelKeys(86400, start, start + 3 * 86400, out);
-    expect(n).toBeGreaterThan(0);
-    // The anchor label is exactly local midnight.
-    const first = new Date((out[0]! / 100) * 1000);
-    expect(first.getHours()).toBe(0);
-    expect(first.getMinutes()).toBe(0);
-    expect(first.getSeconds()).toBe(0);
-    expect(first.getMilliseconds()).toBe(0);
-  });
-
-  it('does not local-align sub-day intervals (epoch-multiple instead)', () => {
-    const out: number[] = [];
-    const n = timeAxisLabelKeys(3600, 7000, 14000, out);
-    expect(n).toBeGreaterThan(0);
-    for (let i = 0; i < n; i++) expect((out[i]! / 100) % 3600).toBe(0);
-  });
-
-  it('caps generation at 30 labels', () => {
-    const out: number[] = [];
-    // A wide→narrow transition: 1s ticks across a 10-minute display span.
-    const n = timeAxisLabelKeys(1, 0, 600, out);
-    expect(n).toBe(30);
-  });
-
-  it('reuses the caller array without reallocating', () => {
-    const out: number[] = [];
-    timeAxisLabelKeys(1, 0, 600, out);
-    const long = out.length;
-    const n = timeAxisLabelKeys(60, 0, 120, out);
-    expect(n).toBeLessThan(long);
-    // Stale entries past the returned count are left in place by design.
-    expect(out.length).toBe(long);
-  });
-});
-
-describe('buildTimeAxisLabels', () => {
-  it('culls labels past the right edge and beyond the left slack', () => {
-    const ctx = makeCtx();
-    const layout = makeLayout(0, 60); // chartW 370 => ~6.17px/s
-    const keys: number[] = [];
-    const n = timeAxisLabelKeys(10, 0, 60, keys);
-    const pool: TimeAxisLabel[] = [];
-    const count = buildTimeAxisLabels(ctx, keys, n, layout, fmt, pool);
-
-    const chartLeft = PAD.left;
-    const chartRight = layout.w - PAD.right;
-    for (let i = 0; i < count; i++) {
-      expect(pool[i]!.x).toBeGreaterThanOrEqual(chartLeft - 20);
-      expect(pool[i]!.x).toBeLessThanOrEqual(chartRight);
-    }
-    // The -10s buffer label sits ~62px left of chartLeft and is dropped.
-    expect(count).toBeLessThan(n);
-  });
-
-  it('measures through the passed-in ctx and sets the label font slot', () => {
-    const ctx = makeCtx(9);
-    const seen: string[] = [];
-    const spy = {
-      ...ctx,
-      measureText: (t: string) => {
-        seen.push(t);
-        return { width: t.length * 9 };
-      },
-    } as unknown as Ctx2D;
-    const layout = makeLayout(0, 60);
-    const keys: number[] = [];
-    const n = timeAxisLabelKeys(10, 0, 60, keys);
-    const pool: TimeAxisLabel[] = [];
-    const count = buildTimeAxisLabels(spy, keys, n, layout, fmt, pool);
-
-    expect(seen.length).toBe(count);
-    expect(spy.font).toBe(spy.fonts.label);
-    for (let i = 0; i < count; i++) {
-      expect(pool[i]!.w).toBe(pool[i]!.text.length * 9);
-    }
-  });
-
-  it('reuses pooled entries instead of allocating per rebuild', () => {
-    const ctx = makeCtx();
-    const layout = makeLayout(0, 60);
-    const keys: number[] = [];
-    const pool: TimeAxisLabel[] = [];
-    const n1 = timeAxisLabelKeys(10, 0, 60, keys);
-    buildTimeAxisLabels(ctx, keys, n1, layout, fmt, pool);
-    const identities = pool.slice();
-
-    const layout2 = makeLayout(5, 65);
-    const n2 = timeAxisLabelKeys(10, 5, 65, keys);
-    buildTimeAxisLabels(ctx, keys, n2, layout2, fmt, pool);
-    for (let i = 0; i < identities.length; i++) {
-      expect(pool[i]).toBe(identities[i]);
-    }
-  });
-
-  it('only calls the formatter for labels that survive culling', () => {
-    let calls = 0;
-    const counting = (t: number) => {
-      calls++;
-      return fmt(t);
-    };
-    const ctx = makeCtx();
-    const layout = makeLayout(0, 60);
-    const keys: number[] = [];
-    const n = timeAxisLabelKeys(10, 0, 60, keys);
-    const pool: TimeAxisLabel[] = [];
-    const count = buildTimeAxisLabels(ctx, keys, n, layout, counting, pool);
-    expect(calls).toBe(count);
-  });
-});
-
-describe('timeAxisStride / timeAxisLabelKept', () => {
-  function labelsAt(xs: number[], w: number): TimeAxisLabel[] {
-    return xs.map((x, i) => ({ key: i * 1000, x, text: 'x', w }));
-  }
-
-  it('is 1 when labels comfortably clear each other', () => {
-    expect(timeAxisStride(labelsAt([0, 100, 200, 300], 30), 4)).toBe(1);
-  });
-
-  it('grows to 2 when a label plus the 8px gap exceeds the spacing', () => {
-    // spacing 40, width 34 + 8 = 42 > 40 => stride 2 (84 <= 80? no) ...
-    // 42/40 = 1.05 => ceil 2.
-    expect(timeAxisStride(labelsAt([0, 40, 80, 120, 160], 34), 5)).toBe(2);
-  });
-
-  it('grows further when labels are very dense', () => {
-    const xs = [0, 10, 20, 30, 40, 50, 60, 70];
-    // (44 + 8) / 10 = 5.2 => 6
-    expect(timeAxisStride(labelsAt(xs, 44), xs.length)).toBe(6);
-  });
-
-  it('uses the widest label, not the average', () => {
-    const labels = labelsAt([0, 40, 80, 120], 20);
-    labels[2]!.w = 40; // one wide label forces the whole set to decimate
-    expect(timeAxisStride(labels, 4)).toBe(2);
-  });
-
-  it('uses the tightest adjacent spacing, not the mean', () => {
-    // A DST-shortened step: mostly 100px apart, one pair only 40px apart.
-    const labels = labelsAt([0, 100, 140, 240], 34);
-    expect(timeAxisStride(labels, 4)).toBe(2);
-  });
-
-  it('never exceeds the label count, so something always survives', () => {
-    const xs = [0, 1, 2, 3];
-    const stride = timeAxisStride(labelsAt(xs, 500), xs.length);
-    expect(stride).toBe(4);
-    const labels = labelsAt(xs, 500).map((l, i) => ({ ...l, key: i * 100 }));
-    const out: TimeAxisLabel[] = [];
-    const kept = resolveTimeAxisOverlaps(labels, labels.length, 1, stride, out);
-    expect(kept).toBeGreaterThan(0);
-  });
-
-  it('handles a single label and an empty set', () => {
-    expect(timeAxisStride([], 0)).toBe(1);
-    expect(timeAxisStride(labelsAt([50], 30), 1)).toBe(1);
-  });
-
-  it('keeps every label at stride 1', () => {
-    for (const key of [0, 500, 1000, 123400]) {
-      expect(timeAxisLabelKept(key, 5, 1)).toBe(true);
-    }
-  });
-
-  it('decides purely from the label timestamp, not from scan position', () => {
-    // interval 10s => keys are multiples of 1000 centiseconds.
-    expect(timeAxisLabelKept(0, 10, 2)).toBe(true);
-    expect(timeAxisLabelKept(1000, 10, 2)).toBe(false);
-    expect(timeAxisLabelKept(2000, 10, 2)).toBe(true);
-  });
-
-  it('normalises negative (pre-epoch) indices', () => {
-    expect(timeAxisLabelKept(-2000, 10, 2)).toBe(true);
-    expect(timeAxisLabelKept(-1000, 10, 2)).toBe(false);
-    expect(timeAxisLabelKept(-3000, 10, 3)).toBe(true);
-  });
-});
-
-describe('overlap resolution determinism under scrolling', () => {
-  /** Runs one "frame": generate, build, resolve. Returns the kept keys. */
-  function frame(
-    ctx: Ctx2D,
-    leftEdge: number,
-    rightEdge: number,
-    interval: number,
-    w = 400
-  ): { keys: number[]; stride: number } {
-    const layout = makeLayout(leftEdge, rightEdge, w);
-    const raw: number[] = [];
-    const n = timeAxisLabelKeys(interval, leftEdge, rightEdge, raw);
-    const pool: TimeAxisLabel[] = [];
-    const count = buildTimeAxisLabels(ctx, raw, n, layout, fmt, pool);
-    const stride = timeAxisStride(pool, count);
-    const out: TimeAxisLabel[] = [];
-    const kept = resolveTimeAxisOverlaps(pool, count, interval, stride, out);
-    return { keys: out.slice(0, kept).map((l) => l.key), stride };
-  }
-
-  it('never changes a surviving label back into a dropped one while scrolling', () => {
-    // Wide labels at a tight interval => spacing ~31px vs 44px needed, so
-    // the run genuinely decimates rather than trivially keeping everything.
-    const ctx = makeCtx(9);
-    const interval = 5;
-    const span = 60;
-    // Every key we have ever seen at all, and whether it was kept.
-    const verdicts = new Map<number, boolean>();
-    for (let step = 0; step < 400; step++) {
-      const left = 1000 + step * 0.25; // sub-interval scroll, 100s of travel
-      const { keys } = frame(ctx, left, left + span, interval);
-      const keptSet = new Set(keys);
-      // Rebuild the full visible set to know which keys were considered.
-      const raw: number[] = [];
-      const n = timeAxisLabelKeys(interval, left, left + span, raw);
-      const layout = makeLayout(left, left + span);
-      const pool: TimeAxisLabel[] = [];
-      const count = buildTimeAxisLabels(ctx, raw, n, layout, fmt, pool);
-      for (let i = 0; i < count; i++) {
-        const key = pool[i]!.key;
-        const kept = keptSet.has(key);
-        const prior = verdicts.get(key);
-        if (prior !== undefined) expect(kept).toBe(prior);
-        verdicts.set(key, kept);
-      }
-    }
-    // Sanity: the scenario actually exercised decimation.
-    expect([...verdicts.values()].some((v) => !v)).toBe(true);
-    expect([...verdicts.values()].some((v) => v)).toBe(true);
-  });
-
-  it('keeps the stride constant while scrolling at a fixed zoom', () => {
-    const ctx = makeCtx(9);
-    const strides = new Set<number>();
-    for (let step = 0; step < 200; step++) {
-      const left = 1000 + step * 0.37;
-      strides.add(frame(ctx, left, left + 60, 10).stride);
-    }
-    expect(strides.size).toBe(1);
-  });
-
-  it('is idempotent: the same inputs always produce the same set', () => {
-    const ctx = makeCtx(9);
-    const a = frame(ctx, 1234.5, 1294.5, 10);
-    const b = frame(ctx, 1234.5, 1294.5, 10);
-    expect(a.keys).toEqual(b.keys);
-    expect(a.stride).toBe(b.stride);
-  });
-
-  it('resolved labels never overlap, including the 8px gap', () => {
-    const ctx = makeCtx(9);
-    const interval = 10;
-    for (let step = 0; step < 120; step++) {
-      const left = 500 + step * 0.5;
-      const layout = makeLayout(left, left + 60);
-      const raw: number[] = [];
-      const n = timeAxisLabelKeys(interval, left, left + 60, raw);
-      const pool: TimeAxisLabel[] = [];
-      const count = buildTimeAxisLabels(ctx, raw, n, layout, fmt, pool);
-      const stride = timeAxisStride(pool, count);
-      const out: TimeAxisLabel[] = [];
-      const kept = resolveTimeAxisOverlaps(pool, count, interval, stride, out);
-      for (let i = 1; i < kept; i++) {
-        const prevRight = out[i - 1]!.x + out[i - 1]!.w / 2;
-        const left2 = out[i]!.x - out[i]!.w / 2;
-        expect(left2).toBeGreaterThanOrEqual(prevRight + 8 - 1e-9);
-      }
-    }
-  });
-
-  it('swaps the whole set coherently when the zoom changes', () => {
-    const ctx = makeCtx(9);
-    const dense = frame(ctx, 1000, 1060, 10);
-    const sparse = frame(ctx, 1000, 1060, 20);
-    expect(sparse.keys.length).toBeLessThanOrEqual(dense.keys.length);
-  });
-
-  it('out holds references into labels, never fresh objects', () => {
-    const labels: TimeAxisLabel[] = [0, 1, 2, 3].map((i) => ({
-      key: i * 1000,
-      x: i * 100,
-      text: 't',
-      w: 20,
-    }));
-    const out: TimeAxisLabel[] = [];
-    const kept = resolveTimeAxisOverlaps(labels, 4, 10, 2, out);
-    expect(kept).toBe(2);
-    expect(out[0]).toBe(labels[0]);
-    expect(out[1]).toBe(labels[2]);
-  });
-});
-
-describe('label-set identity', () => {
-  function labels(keys: number[]): TimeAxisLabel[] {
-    return keys.map((key, i) => ({ key, x: i * 50, text: 't', w: 20 }));
-  }
-
-  it('starts unmatched against any real set', () => {
-    const id = createTimeAxisLabelSetId();
-    expect(timeAxisLabelSetIdMatches(id, labels([1000, 2000]), 2, 10, 1)).toBe(
-      false
-    );
-  });
-
-  it('matches after a write with the same set', () => {
-    const id = createTimeAxisLabelSetId();
-    const set = labels([1000, 2000, 3000]);
-    writeTimeAxisLabelSetId(id, set, 3, 10, 1);
-    expect(timeAxisLabelSetIdMatches(id, set, 3, 10, 1)).toBe(true);
-  });
-
-  it('invalidates when a label scrolls in or out', () => {
-    const id = createTimeAxisLabelSetId();
-    writeTimeAxisLabelSetId(id, labels([1000, 2000, 3000]), 3, 10, 1);
-    // One scrolled off the left, one on at the right.
-    expect(
-      timeAxisLabelSetIdMatches(id, labels([2000, 3000, 4000]), 3, 10, 1)
-    ).toBe(false);
-    // Count grew.
-    expect(
-      timeAxisLabelSetIdMatches(id, labels([1000, 2000, 3000, 4000]), 4, 10, 1)
-    ).toBe(false);
-  });
-
-  it('invalidates on an interval change even at identical endpoints', () => {
-    const id = createTimeAxisLabelSetId();
-    writeTimeAxisLabelSetId(id, labels([0, 1000, 2000]), 3, 10, 1);
-    expect(
-      timeAxisLabelSetIdMatches(id, labels([0, 1000, 2000]), 3, 5, 1)
-    ).toBe(false);
-  });
-
-  it('invalidates on a stride change even at identical endpoints', () => {
-    // This is the collision `count + first + last` alone would miss: same
-    // span, same count of *generated* labels, different kept subset.
-    const id = createTimeAxisLabelSetId();
-    writeTimeAxisLabelSetId(id, labels([0, 2000, 4000]), 3, 10, 2);
-    expect(
-      timeAxisLabelSetIdMatches(id, labels([0, 2000, 4000]), 3, 10, 1)
-    ).toBe(false);
-  });
-
-  it('is exact for the arithmetic sets this module generates', () => {
-    // Reconstruct every set produced across a scroll and confirm that no two
-    // distinct sets share an identity.
-    const ctx = makeCtx();
-    const seen = new Map<string, string>();
-    for (let step = 0; step < 300; step++) {
-      const left = 1000 + step * 0.4;
-      const layout = makeLayout(left, left + 60);
-      const raw: number[] = [];
-      const n = timeAxisLabelKeys(10, left, left + 60, raw);
-      const pool: TimeAxisLabel[] = [];
-      const count = buildTimeAxisLabels(ctx, raw, n, layout, fmt, pool);
-      const stride = timeAxisStride(pool, count);
-      const out: TimeAxisLabel[] = [];
-      const kept = resolveTimeAxisOverlaps(pool, count, 10, stride, out);
-      const id = createTimeAxisLabelSetId();
-      writeTimeAxisLabelSetId(id, out, kept, 10, stride);
-      const idStr = `${id.count}|${id.firstKey}|${id.lastKey}|${id.interval}|${id.stride}`;
-      const setStr = out
-        .slice(0, kept)
-        .map((l) => l.key)
-        .join(',');
-      const prior = seen.get(idStr);
-      if (prior !== undefined) expect(setStr).toBe(prior);
-      seen.set(idStr, setStr);
-    }
-    expect(seen.size).toBeGreaterThan(1);
-  });
-
-  it('ignores x positions — those are the scroll layer dx, not a rebuild', () => {
-    const id = createTimeAxisLabelSetId();
-    const a = labels([1000, 2000, 3000]);
-    writeTimeAxisLabelSetId(id, a, 3, 10, 1);
-    const b = labels([1000, 2000, 3000]);
-    for (const l of b) l.x += 37.5;
-    expect(timeAxisLabelSetIdMatches(id, b, 3, 10, 1)).toBe(true);
-  });
-
-  it('does NOT see text changes — the slot must key formatTime separately', () => {
-    // Documented limitation, asserted so it cannot regress silently.
-    const id = createTimeAxisLabelSetId();
-    const a = labels([1000, 2000]);
-    writeTimeAxisLabelSetId(id, a, 2, 10, 1);
-    const b = labels([1000, 2000]);
-    for (const l of b) l.text = 'COMPLETELY DIFFERENT';
-    expect(timeAxisLabelSetIdMatches(id, b, 2, 10, 1)).toBe(true);
-  });
-
-  it('handles the empty set without reading past the end', () => {
-    const id = createTimeAxisLabelSetId();
-    writeTimeAxisLabelSetId(id, [], 0, 10, 1);
-    expect(id.firstKey).toBe(0);
-    expect(id.lastKey).toBe(0);
-    expect(timeAxisLabelSetIdMatches(id, [], 0, 10, 1)).toBe(true);
-  });
-});
diff --git a/src/draw/line.ts b/src/draw/line.ts
index c570df2..7931e87 100644
--- a/src/draw/line.ts
+++ b/src/draw/line.ts
@@ -7,6 +7,7 @@ import { rgbColor } from '../math/color';
 import {
   lineCacheHits,
   assembleLineTail,
+  assembleLineTailStroke,
   updateLinePaths,
   type CachePath,
   type LineCacheRef,
@@ -203,7 +204,10 @@ function paintLineCurve(
   showFill: boolean,
   lineAlpha: number,
   fillAlpha: number,
-  strokeColor?: Style2D
+  strokeColor?: Style2D,
+  /** Stroke `tailScratch` instead of the combined `scratch` — the prefix is
+   * being composited from the scroll layer picture. See LineCacheRef. */
+  splitStroke: boolean = false
 ) {
   'worklet';
   if (cacheReady && cacheSlot !== undefined) {
@@ -211,7 +215,7 @@ function paintLineCurve(
       ctx,
       layout,
       palette,
-      cacheSlot.scratch!,
+      splitStroke ? cacheSlot.tailScratch! : cacheSlot.scratch!,
       wantFill ? cacheSlot.fillScratch : null,
       lineAlpha,
       fillAlpha,
@@ -416,6 +420,34 @@ export function drawLine(
       );
   }
 
+  // Declarative scroll layer: the caller has already composited the prefix
+  // stroke from a picture, so stroke only the tail here — drawing the prefix
+  // again would double-stroke an antialiased line over itself. Honored only
+  // when the cache is actually in use: the immediate-mode fallback rebuilds
+  // the whole spline and has no separable prefix.
+  //
+  // The last two entries of `pts` are the tail's two moving points in both
+  // branches above — [lastX, tailY], [tipX, tailY] on a hit, and
+  // pts[N-1], pts[N] on a rebuild — which is exactly what
+  // `assembleLineTail` was handed, so the tail-only path joins the
+  // translated prefix at the identical point with the identical tangent.
+  const splitStroke =
+    cacheReady &&
+    pathCache !== undefined &&
+    pathCache.splitPrefixStroke === true;
+  if (splitStroke) {
+    const n = pts.length;
+    assembleLineTailStroke(
+      pathCache!.slot,
+      makeSkPath,
+      layout,
+      pts[n - 2]![0],
+      pts[n - 2]![1],
+      pts[n - 1]![0],
+      pts[n - 1]![1]
+    );
+  }
+
   // Clip line + fill to chart area — during big value jumps the range
   // lerps smoothly so the line may extend beyond the chart bounds.
   // Clipping keeps it tidy while the range catches up.
@@ -437,7 +469,8 @@ export function drawLine(
       showFill,
       lineAlpha,
       fillAlpha,
-      strokeColor
+      strokeColor,
+      splitStroke
     );
     ctx.restore();
 
@@ -456,7 +489,8 @@ export function drawLine(
       showFill,
       lineAlpha,
       fillAlpha,
-      strokeColor
+      strokeColor,
+      splitStroke
     );
     ctx.restore();
   } else {
@@ -471,7 +505,8 @@ export function drawLine(
       showFill,
       lineAlpha,
       fillAlpha,
-      strokeColor
+      strokeColor,
+      splitStroke
     );
   }
 
diff --git a/src/draw/lineCache.ts b/src/draw/lineCache.ts
index d317bd2..0230f7e 100644
--- a/src/draw/lineCache.ts
+++ b/src/draw/lineCache.ts
@@ -42,6 +42,23 @@ export interface LineCacheRef {
   /** Which backing array the points came from: 0 = live buffer,
    * 1 = paused snapshot, 2 = reverse-morph stash. */
   dataSource: number;
+  /**
+   * Declarative scroll layer: when true, the caller is compositing the
+   * prefix stroke itself (from a picture recorded by
+   * engine/lineScrollLayer.ts) and `drawLine` must stroke the **tail only**,
+   * so the prefix isn't drawn twice. The fill is unaffected — it is still
+   * drawn whole, from the combined path.
+   *
+   * Advisory, not a command: `drawLine` honors it only on frames where the
+   * path cache is actually in use (`cacheReady`), since the immediate-mode
+   * fallback has no separable prefix. The caller therefore only sets it when
+   * it has independently confirmed a `lineCacheHits` hit for this frame —
+   * see engine/step.ts, which is also where the alpha gate lives.
+   *
+   * Absent (undefined) for the multi-series and candle pipelines, which draw
+   * the combined path exactly as before.
+   */
+  splitPrefixStroke?: boolean;
 }
 
 export interface LineCacheSlot {
diff --git a/src/draw/lineScrollLayer.ts b/src/draw/lineScrollLayer.ts
new file mode 100644
index 0000000..167a365
--- /dev/null
+++ b/src/draw/lineScrollLayer.ts
@@ -0,0 +1,122 @@
+import type { LivelinePalette } from '../types';
+import type { LineCacheSlot } from './lineCache';
+import {
+  scrollLayerBeginKey,
+  scrollLayerPushNum,
+  scrollLayerPushRef,
+  type ScrollLayerSlot,
+} from './scrollLayer';
+
+/**
+ * Pure logic for the **line prefix scroll layer** — the half of
+ * `draw/scrollLayer.ts`'s contract that is specific to the single-series
+ * line: which frames may composite the layer at all, and what the layer's
+ * invalidation key is.
+ *
+ * The recording itself lives in `engine/lineScrollLayer.ts` (it needs Skia);
+ * this module stays Skia-free so jest can exercise the gate and the key with
+ * plain objects, exactly like `draw/gridLayer.ts` vs `engine/gridLayer.ts`.
+ *
+ * ## What the layer holds
+ *
+ * `lineCache.linePrefixPath(slot)` — the spline through decimated points
+ * `0..N-2`, in build-time screen coordinates — stroked with the line's paint.
+ * Nothing else. The fill polygon and the tail stroke stay in the per-frame
+ * screen picture; see the "Split stroke API" section comment in
+ * `draw/lineCache.ts` for why the fill is deliberately not split.
+ *
+ * ## Z-order note (read before changing the palette contract)
+ *
+ * The scroll layer composites *below* the screen picture, so the prefix
+ * stroke ends up **under** the fill polygon, where today's combined path
+ * draws it **over**. With the built-in theme that is a no-op: `theme.ts`
+ * derives `fillTop`/`fillBottom` as the *line color* at alpha 0.12→0, and
+ * compositing a color over itself is the identity. A caller supplying a
+ * custom palette whose fill hue differs from `palette.line` would see the
+ * lower half of the prefix stroke tinted by up to 12% of that hue. If that
+ * ever needs to be exact, the gate below is where to add the check — do not
+ * try to split the fill (see `lineCache.ts`).
+ */
+
+/**
+ * Composite alpha the prefix stroke would be drawn at this frame, as the
+ * `alpha` argument for `scrollLayerUsable`. Returns 1 only when the whole
+ * line pipeline is at full opacity *and* untransformed, i.e. when
+ * compositing a pre-recorded picture is pixel-identical to drawing live:
+ *
+ * - `chartReveal < 1` — the reveal morph / loading / empty crossfade. The
+ *   line is drawn at a breathing alpha, in a blended color, and its geometry
+ *   depends on `now_ms`; `drawLine` also bypasses the path cache entirely
+ *   there, so there is no stable prefix to record.
+ * - `scrubAmount > 0` — the scrub draws the line twice under two clips, the
+ *   right-hand one dimmed. A single translated picture cannot express that.
+ *   `scrubAmount` snaps to exactly 0 (helpers.ts's `updateHoverState`), so
+ *   this re-enables cleanly rather than asymptoting.
+ * - `shakeAmplitude > 0` — the degen shake translates the whole frame by a
+ *   fresh random offset. `drawFrame` zeroes the amplitude below its own
+ *   threshold, so any non-zero value here means a translate is applied this
+ *   frame and the scroll layer (outside that translate) would tear away
+ *   from the rest of the chart.
+ *
+ * Returns 0, not the true fractional alpha: `scrollLayerUsable` only ever
+ * asks "is this >= 1", and inventing a partial alpha would suggest the
+ * layer could be faded, which `ctx.drawPicture` cannot do (see
+ * `scrollLayer.ts` invariant 1).
+ */
+export function lineScrollLayerAlpha(
+  chartReveal: number,
+  scrubAmount: number,
+  shakeAmplitude: number
+): number {
+  'worklet';
+  if (chartReveal < 1) return 0;
+  if (scrubAmount > 0) return 0;
+  if (shakeAmplitude > 0) return 0;
+  return 1;
+}
+
+/**
+ * Writes this frame's candidate key for the prefix picture: begin, then one
+ * push per dimension, unconditionally and always in this order (the push
+ * order *is* the field identity — see the doc comment on
+ * `ScrollLayerSlot`).
+ *
+ * The key is the line cache slot's **committed** key, verbatim, plus what a
+ * picture bakes that a path does not (stroke color and width) plus
+ * `pad.left`. Keying off the committed key rather than off this frame's raw
+ * inputs is the point: the recorded picture is a rendering of
+ * `slot.prefix`, so it is stale exactly when `slot.prefix` has been rebuilt,
+ * and `slot.kFoo` is precisely the identity `slot.prefix` was built from.
+ * Re-deriving the same dimensions from `layout`/`visible` would be a second
+ * copy of `lineCacheHits` that could drift from the first.
+ *
+ * `pad.left` is the one dimension the line cache deliberately omits (it is a
+ * pure x-shift, absorbed by `dx`) but this layer needs: the composite clip
+ * is baked into the recording at `pad.left - 1`, so a padding change must
+ * re-record.
+ */
+export function writeLineScrollKey<Picture>(
+  slot: ScrollLayerSlot<Picture>,
+  lineSlot: LineCacheSlot,
+  padLeft: number,
+  palette: LivelinePalette
+): void {
+  'worklet';
+  scrollLayerBeginKey(slot);
+  scrollLayerPushNum(slot, lineSlot.kDataRev);
+  scrollLayerPushNum(slot, lineSlot.kDataSource);
+  scrollLayerPushNum(slot, lineSlot.kLen);
+  scrollLayerPushNum(slot, lineSlot.kFirstT);
+  scrollLayerPushNum(slot, lineSlot.kLastT);
+  scrollLayerPushNum(slot, lineSlot.kLastV);
+  scrollLayerPushNum(slot, lineSlot.kMin);
+  scrollLayerPushNum(slot, lineSlot.kMax);
+  scrollLayerPushNum(slot, lineSlot.kWindow);
+  scrollLayerPushNum(slot, lineSlot.kH);
+  scrollLayerPushNum(slot, lineSlot.kPadTop);
+  scrollLayerPushNum(slot, lineSlot.kPadBottom);
+  scrollLayerPushNum(slot, lineSlot.kChartW);
+  scrollLayerPushNum(slot, padLeft);
+  scrollLayerPushNum(slot, palette.lineWidth);
+  scrollLayerPushRef(slot, palette.line);
+}
diff --git a/src/draw/timeAxisLayer.ts b/src/draw/timeAxisLayer.ts
deleted file mode 100644
index e003b01..0000000
--- a/src/draw/timeAxisLayer.ts
+++ /dev/null
@@ -1,367 +0,0 @@
-import type { ChartLayout } from '../types';
-import { niceTimeInterval } from '../math/intervals';
-import type { Ctx2D } from './canvas2d';
-
-/**
- * Pure label-selection logic for the cached time-axis scroll layer.
- *
- * `draw/timeAxis.ts` re-derives all of this every frame at 60fps: the
- * interval, a `formatTime()` call per label (the default formatter allocates
- * a `Date` plus three `padStart` results *per label per frame*), a `Map` walk
- * with per-label alpha lerps, text measurement, a sort, and overlap
- * resolution. Under the scroll-layer architecture the axis is baked into a
- * cached `SkPicture` and composited at a horizontal offset, so all of this
- * runs only when the label set actually changes — roughly once per `interval`
- * seconds instead of 60 times per second.
- *
- * Two deliberate differences from `timeAxis.ts`:
- *
- * 1. **No per-label alpha.** Labels bake at alpha 1; the 50px edge fade
- *    (`timeAxis.ts:65-72`) becomes a gradient `destination-out` erase over the
- *    axis strip in the screen pass. Label visibility is therefore a pure
- *    function of position — which is what makes this module testable.
- * 2. **Positional overlap resolution.** The alpha tiebreak ("keep the
- *    higher-alpha one", `timeAxis.ts:184-198`) has no meaning without alpha.
- *    See `timeAxisStride` for the replacement and its determinism argument.
- *
- * Skia-free by construction: `Ctx2D` is imported as a **type only**, exactly
- * like `timeAxis.ts` does, so jest can drive this with a plain fake context.
- * Do not add a value import from `@shopify/react-native-skia` here — it would
- * pull the native binding into the test process and this module would become
- * as untestable as `draw/index.ts`.
- *
- * Nothing in this module allocates per call: every producer writes into a
- * caller-owned array that it grows once and then reuses, the same pooling
- * discipline `TimeAxisState` already documents.
- */
-
-/** Minimum on-screen spacing between tick positions, in px. Below this the
- * interval is doubled. Matches `timeAxis.ts:81`. */
-const MIN_TICK_SPACING_PX = 60;
-
-/** Minimum clear gap between two rendered label boxes, in px. Matches the
- * `+ 8` slack in `timeAxis.ts:189`. */
-const LABEL_GAP_PX = 8;
-
-/** How far left of the plot area a label may sit and still be built. A label
- * whose centre is just off the left edge still has its right half visible, so
- * culling exactly at `chartLeft` would pop it. Matches `timeAxis.ts:161`. */
-const LEFT_CULL_SLACK_PX = 20;
-
-/** Hard cap on generated labels. During a wide→narrow window transition the
- * target interval can be tiny relative to the currently-displayed span, so the
- * generation loop is bounded rather than trusted. Matches `timeAxis.ts:102`. */
-const MAX_LABELS = 30;
-
-/** One built label, pooled across rebuilds. `key` is the label's timestamp in
- * centiseconds (`Math.round(t * 100)`) — the same integer key `timeAxis.ts`
- * uses, chosen so day-aligned times that land on fractional seconds still
- * compare exactly. */
-export interface TimeAxisLabel {
-  /** `Math.round(t * 100)` — timestamp in centiseconds. */
-  key: number;
-  /** Build-time screen X. Only valid for the layout it was built with; the
-   * scroll layer re-derives the frame's X by translating the whole picture. */
-  x: number;
-  text: string;
-  /** Measured width via `ctx.measureText`, which is cached upstream by
-   * font slot + string in `canvas2d.ts`. */
-  w: number;
-}
-
-/**
- * Picks the tick interval in seconds.
- *
- * Ported verbatim from `timeAxis.ts:79-83`. Two invariants worth preserving:
- *
- * - It is derived from the **target** window, never the interpolating display
- *   window. Deriving it from the display window makes the interval change
- *   mid-transition and flicker for one frame when `windowSecs` snaps to
- *   `targetWindowSecs` at the end of the transition.
- * - The doubling loop is bounded by `interval < targetWindowSecs`, so a
- *   degenerate `chartW` (0, or a first-frame layout) cannot spin forever.
- */
-export function timeAxisInterval(
-  targetWindowSecs: number,
-  chartW: number
-): number {
-  'worklet';
-  const targetPxPerSec = chartW / targetWindowSecs;
-  let interval = niceTimeInterval(targetWindowSecs);
-  while (
-    interval * targetPxPerSec < MIN_TICK_SPACING_PX &&
-    interval < targetWindowSecs
-  ) {
-    interval *= 2;
-  }
-  return interval;
-}
-
-/**
- * Generates the label timestamps for the current view, plus one interval of
- * buffer on each side so a label is already built before it scrolls in.
- *
- * Ported from `timeAxis.ts:89-106`. Writes ascending centisecond keys into
- * `out` and returns how many are valid; `out` is grown once and reused, never
- * reallocated, and entries past the returned count are stale.
- *
- * For intervals of a day or more the sequence is anchored to **local**
- * midnight rather than the UTC epoch, because a "1 Feb" tick drawn at 19:00
- * the previous day is simply wrong to a user. Note the anchor is applied only
- * to the first label and the rest step by a fixed `interval`; across a DST
- * boundary later labels therefore drift an hour off local midnight. That is
- * existing `timeAxis.ts` behaviour and is preserved deliberately — changing it
- * belongs in a separate change with its own visual verification.
- */
-export function timeAxisLabelKeys(
-  interval: number,
-  leftEdge: number,
-  rightEdge: number,
-  out: number[]
-): number {
-  'worklet';
-  const useLocalDays = interval >= 86400;
-  let firstTime: number;
-  if (useLocalDays) {
-    const d = new Date((leftEdge - interval) * 1000);
-    d.setHours(0, 0, 0, 0);
-    firstTime = d.getTime() / 1000;
-  } else {
-    firstTime = Math.ceil((leftEdge - interval) / interval) * interval;
-  }
-
-  let count = 0;
-  for (
-    let t = firstTime;
-    t <= rightEdge + interval && count < MAX_LABELS;
-    t += interval
-  ) {
-    out[count] = Math.round(t * 100);
-    count++;
-  }
-  return count;
-}
-
-/**
- * Formats and measures the subset of `keys` that is actually on screen.
- *
- * Writes into `pool` (grown once, entries reused across rebuilds — a given
- * slot backs a different label on every rebuild, which is safe because every
- * field is overwritten) and returns the valid count. Output stays ascending
- * because `timeAxisLabelKeys` emits ascending keys, so the sort
- * `timeAxis.ts:176` performs every frame is not needed here.
- *
- * `ctx` is used only for `measureText`, which `canvas2d.ts` caches by font
- * slot + string; the font slot is set here so that cache is keyed correctly.
- */
-export function buildTimeAxisLabels(
-  ctx: Ctx2D,
-  keys: number[],
-  keyCount: number,
-  layout: ChartLayout,
-  formatTime: (t: number) => string,
-  pool: TimeAxisLabel[]
-): number {
-  'worklet';
-  ctx.font = ctx.fonts.label;
-  const chartLeft = layout.pad.left;
-  const chartRight = layout.w - layout.pad.right;
-
-  let count = 0;
-  for (let i = 0; i < keyCount; i++) {
-    const key = keys[i]!;
-    const x = layout.toX(key / 100);
-    if (x < chartLeft - LEFT_CULL_SLACK_PX || x > chartRight) continue;
-    const text = formatTime(key / 100);
-    const w = ctx.measureText(text).width;
-    const entry = pool[count];
-    if (!entry) {
-      pool[count] = { key, x, text, w };
-    } else {
-      entry.key = key;
-      entry.x = x;
-      entry.text = text;
-      entry.w = w;
-    }
-    count++;
-  }
-  return count;
-}
-
-/**
- * Chooses the decimation stride that resolves label overlap — the positional
- * replacement for the alpha tiebreak at `timeAxis.ts:184-198`.
- *
- * **Why not greedy left-to-right?** The obvious replacement ("walk sorted by
- * X, drop anything colliding with the last kept label") is deterministic for a
- * fixed input but *not* stable under scrolling: the greedy chain is anchored
- * on whichever label is currently leftmost, so the moment the leftmost label
- * scrolls out the whole chain shifts by one and every surviving label swaps
- * for its neighbour. On a continuously scrolling chart that is a visible
- * flicker once per interval, and it is exactly the failure the old alpha
- * tiebreak was papering over.
- *
- * **The rule instead:** keep a label iff its *absolute* interval index
- * `round(t / interval)` is a multiple of `stride`. The decision depends only
- * on the label's own timestamp and on `stride`, never on which labels happen
- * to be on screen, so a label's fate is identical on every frame it is
- * visible. Scrolling can never change a surviving label into a dropped one.
- *
- * `stride` itself is derived from view-scale quantities — the on-screen
- * spacing between consecutive ticks and the widest label in the set — not from
- * scan order. At a fixed zoom the spacing is constant, so `stride` is constant
- * and the kept set is fully scroll-invariant. The one residual way `stride`
- * can move without a zoom change is a wider label class scrolling in (`9:59`
- * → `10:00`). That flips the whole set at once, coherently, which is the
- * "hard swap" the design already accepts — not a two-label flicker.
- *
- * Spacing is taken as the **minimum** adjacent gap rather than the mean so an
- * irregular step (a DST-shortened day) tightens the stride rather than being
- * averaged away into an overlap.
- *
- * Clamped to `count` so at least one label always survives: keys are
- * consecutive integer indices, and any `count` consecutive integers contain a
- * multiple of any stride ≤ `count`.
- */
-export function timeAxisStride(labels: TimeAxisLabel[], count: number): number {
-  'worklet';
-  if (count < 2) return 1;
-
-  let minSpacing = Infinity;
-  let maxW = 0;
-  for (let i = 0; i < count; i++) {
-    const w = labels[i]!.w;
-    if (w > maxW) maxW = w;
-    if (i > 0) {
-      const gap = labels[i]!.x - labels[i - 1]!.x;
-      if (gap < minSpacing) minSpacing = gap;
-    }
-  }
-
-  // Degenerate geometry (zero or negative spacing) — nothing sensible to
-  // decimate towards, so keep one label rather than loop.
-  if (!(minSpacing > 0)) return count;
-
-  const needed = maxW + LABEL_GAP_PX;
-  let stride = Math.ceil(needed / minSpacing);
-  if (stride < 1) stride = 1;
-  if (stride > count) stride = count;
-  return stride;
-}
-
-/** True when this label survives decimation at `stride`. Pure in the label's
- * own timestamp — see `timeAxisStride` for why that matters. */
-export function timeAxisLabelKept(
-  key: number,
-  interval: number,
-  stride: number
-): boolean {
-  'worklet';
-  if (stride <= 1) return true;
-  const index = Math.round(key / (100 * interval));
-  // Keys before the epoch give a negative index; JS `%` keeps the sign, so
-  // normalise before comparing or pre-1970 charts would drop everything.
-  return ((index % stride) + stride) % stride === 0;
-}
-
-/**
- * Applies `timeAxisLabelKept` to a built label list.
- *
- * `stride` is passed in rather than derived here because the caller also needs
- * it for the invalidation key (see `TimeAxisLabelSetId`) and it must be the
- * same value in both places — deriving it twice invites them to diverge.
- *
- * `out` holds **references into `labels`**, never its own objects — the same
- * contract `TimeAxisState.drawnScratch` documents. Returns the kept count;
- * entries past it are stale.
- */
-export function resolveTimeAxisOverlaps(
-  labels: TimeAxisLabel[],
-  count: number,
-  interval: number,
-  stride: number,
-  out: TimeAxisLabel[]
-): number {
-  'worklet';
-  let kept = 0;
-  for (let i = 0; i < count; i++) {
-    const label = labels[i]!;
-    if (!timeAxisLabelKept(label.key, interval, stride)) continue;
-    out[kept] = label;
-    kept++;
-  }
-  return kept;
-}
-
-/**
- * Cheap identity for the drawn label set, used as part of the `axisScroll`
- * picture invalidation key.
- *
- * **Is `count + firstKey + lastKey` collision-free?** For sets produced by
- * `timeAxisLabelKeys` + `resolveTimeAxisOverlaps`, yes — and not merely
- * "cheap and good enough". The generator emits a strictly ascending arithmetic
- * sequence with step `interval`, and decimation keeps a fixed-stride subset of
- * it, so `(interval, stride, firstKey, count)` reconstructs the whole set
- * exactly; `lastKey` is redundant but is retained as a cheap guard against the
- * one non-arithmetic case, the local-midnight anchor across a DST boundary.
- * `interval` and `stride` are therefore carried in this identity rather than
- * assumed — with only `count/first/last` the set genuinely *would* be
- * ambiguous (same span, different stride).
- *
- * What it does **not** cover, by design:
- *
- * - **Label text.** Two different formatter outputs for the same timestamps
- *   compare equal here. The slot key covers this separately by holding
- *   `formatTime` by reference; a formatter closing over mutable state (a
- *   locale that changes in place) would slip through both. Callers that swap
- *   formatting must swap the function identity.
- * - **Positions.** `x` moves every frame; that is the scroll layer's `dx`
- *   translation, not a rebuild trigger, and is deliberately absent.
- */
-export interface TimeAxisLabelSetId {
-  count: number;
-  firstKey: number;
-  lastKey: number;
-  interval: number;
-  stride: number;
-}
-
-export function createTimeAxisLabelSetId(): TimeAxisLabelSetId {
-  'worklet';
-  return { count: 0, firstKey: 0, lastKey: 0, interval: 0, stride: 0 };
-}
-
-/** Writes the identity of `labels[0..count)` into `id` (call on a rebuild). */
-export function writeTimeAxisLabelSetId(
-  id: TimeAxisLabelSetId,
-  labels: TimeAxisLabel[],
-  count: number,
-  interval: number,
-  stride: number
-): void {
-  'worklet';
-  id.count = count;
-  id.firstKey = count > 0 ? labels[0]!.key : 0;
-  id.lastKey = count > 0 ? labels[count - 1]!.key : 0;
-  id.interval = interval;
-  id.stride = stride;
-}
-
-/** True when `labels[0..count)` has the same identity as `id`. Allocation-free
- * so it is safe to call every frame. */
-export function timeAxisLabelSetIdMatches(
-  id: TimeAxisLabelSetId,
-  labels: TimeAxisLabel[],
-  count: number,
-  interval: number,
-  stride: number
-): boolean {
-  'worklet';
-  return (
-    id.count === count &&
-    id.interval === interval &&
-    id.stride === stride &&
-    id.firstKey === (count > 0 ? labels[0]!.key : 0) &&
-    id.lastKey === (count > 0 ? labels[count - 1]!.key : 0)
-  );
-}
diff --git a/src/engine/lineScrollLayer.ts b/src/engine/lineScrollLayer.ts
new file mode 100644
index 0000000..7b3ae54
--- /dev/null
+++ b/src/engine/lineScrollLayer.ts
@@ -0,0 +1,115 @@
+import { Skia, type SkPicture } from '@shopify/react-native-skia';
+import type { ChartLayout, LivelinePalette, LivelineFonts } from '../types';
+import { createCanvas2D, type SkiaCache } from '../draw/canvas2d';
+import { strokeLinePath } from '../draw/line';
+import { linePrefixPath, type LineCacheSlot } from '../draw/lineCache';
+import {
+  scrollLayerBuilt,
+  scrollLayerKeyHits,
+  type ScrollLayerSlot,
+} from '../draw/scrollLayer';
+import { writeLineScrollKey } from '../draw/lineScrollLayer';
+
+/**
+ * Keeps `slot.picture` — the line's prefix stroke, recorded once in
+ * build-time screen coordinates — up to date, so the declarative shell can
+ * composite it under a `<Group transform={[{ translateX: dx }]}>` instead of
+ * re-stroking it every frame.
+ *
+ * Mirrors `engine/gridLayer.ts` (key check → record → commit); the pure half
+ * — the gate and the key — lives in `draw/lineScrollLayer.ts`.
+ *
+ * ## Rebuild timing
+ *
+ * Called *before* `drawFrame`, and only on frames where `lineCacheHits` has
+ * already reported a hit, so `lineSlot.prefix` is this frame's prefix and
+ * the picture recorded from it is valid for this frame's own composite. The
+ * consequence is that the frame which *misses* — the one where `drawLine`
+ * rebuilds the prefix — draws the whole line live (no split, empty scroll
+ * layer), and the re-record happens on the next frame instead. That is one
+ * re-record per cache miss either way, and it keeps the ordering trivially
+ * safe: the picture is never recorded from a prefix that the frame's own
+ * screen pass has already moved past.
+ *
+ * ## Why the clip is baked in, not applied at composite time
+ *
+ * `draw/scrollLayer.ts`'s invariant 2 has each slot clip to its own region
+ * *at composite time*, because its intended consumer composites with
+ * `ctx.clipRect` + `ctx.translate` + `ctx.drawPicture`. This consumer does
+ * not: it composites through a Skia `<Group transform>` node in the
+ * declarative tree, which applies a matrix and nothing else, and adding a
+ * clip there would mean another node whose rect changes with layout. So the
+ * clip is recorded into the picture, in build-time coordinates, and
+ * `slot.clipX..clipH` stay unused (`setScrollLayerClip` is never called).
+ *
+ * That is sound here specifically because the layer only ever moves
+ * *horizontally*:
+ *
+ * - The top/bottom clip edges are horizontal lines; translating in x leaves
+ *   them exactly where the live clip would put them. They are what actually
+ *   matters — `drawLine`'s clip exists to trim the stroke's half-width when
+ *   a range lerp pins the line to the chart edge.
+ * - The right clip edge travels left with the content, but the prefix ends
+ *   at `cutX`, which is always well left of it (the tail and the live tip
+ *   sit between `cutX` and the plot's right edge), so it can never reach the
+ *   content.
+ * - The left clip edge likewise travels left, letting through content that
+ *   the live clip would have trimmed — but everything left of `pad.left` is
+ *   erased outright by `drawEdgeFade`'s `destination-out` pass in the screen
+ *   picture, which composites over the scroll layer because the two pictures
+ *   share one surface (a transform-only `<Group>` creates no layer).
+ *
+ * Uses its own `SkiaCache` for the same reason `engine/gridLayer.ts` does:
+ * createCanvas2D's pooled paths/paints are only safe to reuse when each
+ * recording builds and flushes before the next starts, and sharing the main
+ * frame's cache across a nested recording would make that an assumption
+ * rather than a guarantee.
+ */
+export function updateLineScrollLayer(
+  slot: ScrollLayerSlot<SkPicture>,
+  lineSlot: LineCacheSlot,
+  layout: ChartLayout,
+  palette: LivelinePalette,
+  layerCache: SkiaCache,
+  fonts: LivelineFonts
+): void {
+  'worklet';
+  writeLineScrollKey(slot, lineSlot, layout.pad.left, palette);
+  if (scrollLayerKeyHits(slot)) return;
+
+  const prefix = linePrefixPath(lineSlot);
+  if (prefix === null) return;
+
+  const recorder = Skia.PictureRecorder();
+  // NO cull rect on purpose. `beginRecording(rect)` installs an
+  // SkRTreeFactory BBH and culls at record time against that rect
+  // (JsiSkPictureRecorder.h:36-38); the no-argument form uses a 2,000,000²
+  // rect and a nullptr BBH. Record-time culling is wrong for content that is
+  // translated *afterwards* — geometry culled against build-time bounds can
+  // be exactly the geometry the transform brings back on screen. The screen
+  // picture keeps its cull rect (it is never transformed); this one must not
+  // have one.
+  const canvas = recorder.beginRecording();
+  const subCtx = createCanvas2D(canvas, fonts, layerCache);
+  // Same clip `drawLine` puts around the combined path — see the header.
+  subCtx.clipRect(
+    layout.pad.left - 1,
+    layout.pad.top,
+    layout.chartW + 2,
+    layout.chartH
+  );
+  // lineAlpha 1 and no color override: the gate in draw/lineScrollLayer.ts
+  // guarantees chartReveal >= 1, which is exactly when `drawLine` strokes at
+  // alpha 1 in the unblended `palette.line`.
+  strokeLinePath(subCtx, palette, prefix, 1);
+
+  // `tRef`/`xRefAtBuild` are taken straight from the line cache slot rather
+  // than recomputed, so `scrollLayerDx` and `lineScrollDx` agree by
+  // construction (see the note on `lineScrollDx`).
+  scrollLayerBuilt(
+    slot,
+    recorder.finishRecordingAsPicture(),
+    lineSlot.tRef,
+    lineSlot.xRefAtBuild
+  );
+}
diff --git a/src/engine/state.ts b/src/engine/state.ts
index 77b76d1..6facba6 100644
--- a/src/engine/state.ts
+++ b/src/engine/state.ts
@@ -10,6 +10,10 @@ import {
   type CandleCacheSlot,
 } from '../draw/candleCache';
 import { createGridLayerSlot, type GridLayerSlot } from '../draw/gridLayer';
+import {
+  createScrollLayerSlot,
+  type ScrollLayerSlot,
+} from '../draw/scrollLayer';
 import { createParticleState, type ParticleState } from '../draw/particles';
 import { createShakeState } from '../draw';
 import { createSkiaCache, type SkiaCache } from '../draw/canvas2d';
@@ -126,6 +130,16 @@ export interface EngineState {
    * deliberately not shared with the main frame's SkiaCache (see
    * engine/gridLayer.ts's doc comment). */
   gridLayerCache: SkiaCache;
+  /** Cross-frame SkPicture of the line's prefix stroke, single-series mode —
+   * the declarative shell's scroll layer, composited under a
+   * `<Group transform>` instead of being re-stroked every frame (see
+   * engine/lineScrollLayer, draw/scrollLayer). Only the single-series line
+   * pipeline populates it; multi-series and candle mode keep drawing the
+   * combined path. */
+  lineScroll: ScrollLayerSlot<SkPicture>;
+  /** Dedicated Skia object cache for the line scroll layer's own
+   * sub-recording — same reasoning as `gridLayerCache` above. */
+  lineScrollCache: SkiaCache;
   /** Cross-frame closed-candle body+wick path cache, candle mode (see
    * draw/candleCache). */
   candleCache: CandleCacheSlot;
@@ -295,6 +309,8 @@ export function createEngineState(
     lineCaches: new Map<string, LineCacheSlot>(),
     gridLayer: createGridLayerSlot<SkPicture>(),
     gridLayerCache: createSkiaCache(),
+    lineScroll: createScrollLayerSlot<SkPicture>(),
+    lineScrollCache: createSkiaCache(),
     candleCache: createCandleCacheSlot(),
 
     scrubAmount: 0,
diff --git a/src/engine/step.ts b/src/engine/step.ts
index c71f7b5..136ebf6 100644
--- a/src/engine/step.ts
+++ b/src/engine/step.ts
@@ -12,6 +12,7 @@ import { detectMomentum } from '../math/momentum';
 import { interpolateAtTime } from '../math/interpolate';
 import { easeInOutCos } from '../math/ease';
 import { filterVisiblePointsInto } from '../math/visible';
+import type { SkPicture } from '@shopify/react-native-skia';
 import type { Ctx2D } from '../draw/canvas2d';
 import {
   drawFrame,
@@ -27,6 +28,10 @@ import type { EngineConfigStep } from './types';
 import type { EngineState } from './state';
 import { drawBadge } from './badge';
 import { updateGridLayer } from './gridLayer';
+import { updateLineScrollLayer } from './lineScrollLayer';
+import { lineCacheHits } from '../draw/lineCache';
+import { lineScrollLayerAlpha } from '../draw/lineScrollLayer';
+import { scrollLayerDx, scrollLayerUsable } from '../draw/scrollLayer';
 import {
   computeAdaptiveSpeed,
   updateWindowTransition,
@@ -67,6 +72,20 @@ import {
 export interface StepOutput {
   /** Hover point to deliver through onHover this frame (undefined = none) */
   emitHover?: HoverPoint;
+  /**
+   * The scroll layer's picture for this frame, or null when nothing may be
+   * composited there and the screen picture already holds the whole frame
+   * (every pipeline except single-series line, and any single-series frame
+   * that fails the alpha gate or the cache check — see
+   * draw/lineScrollLayer.ts). The caller publishes an empty picture for
+   * null; it must never leave a stale picture composited.
+   */
+  scrollPicture: SkPicture | null;
+  /**
+   * `translateX` for the scroll layer, in screen pixels — meaningless (and
+   * always 0) when `scrollPicture` is null.
+   */
+  scrollDx: number;
   /** Live value display text (line mode + showValue), null = leave unchanged */
   valueText: string | null;
   /** Live value display color ('' = default color) */
@@ -143,7 +162,12 @@ export function engineStep(
   multiData: Record<string, LivelinePoint[]>
 ): StepOutput {
   'worklet';
-  const out: StepOutput = { valueText: null, valueColor: null };
+  const out: StepOutput = {
+    valueText: null,
+    valueColor: null,
+    scrollPicture: null,
+    scrollDx: 0,
+  };
 
   const noMotion = cfg.noMotion;
   const hoverPixelX = cfg.scrub ? hoverPixelXRaw : null;
@@ -1705,6 +1729,58 @@ export function engineStep(
     const swingMagnitude =
       valRange > 0 ? Math.min(recentDelta / valRange, 1) : 0;
 
+    // --- Declarative scroll layer: the line's prefix stroke ---------------
+    //
+    // On frames where the prefix provably hasn't changed (a `lineCacheHits`
+    // hit) and the whole line pipeline is at full opacity and untransformed
+    // (`lineScrollLayerAlpha`), the prefix is composited from an SkPicture
+    // under a `<Group transform>` and `drawLine` strokes only the tail. Any
+    // other frame draws the line exactly as before, whole, and publishes an
+    // empty scroll layer — the same both-branches shape the grid picture
+    // uses above, and for the same reason: `ctx.drawPicture` ignores
+    // `globalAlpha`, so a layer that can't be composited at alpha 1 must not
+    // be composited at all.
+    //
+    // Deliberately runs after `updateHoverState` (it reads this frame's
+    // settled `s.scrubAmount`) and before `drawFrame` (which reads
+    // `splitPrefixStroke`). `s.shakeState.amplitude` is read pre-decay,
+    // which is the value `drawFrame`'s own translate will use this frame.
+    const dataSource = dataSourceOf(useStash, s.pausedData !== null);
+    const visLastPoint = visible[visible.length - 1]!;
+    const layerAlpha = lineScrollLayerAlpha(
+      chartReveal,
+      s.scrubAmount,
+      cfg.degenOptions ? s.shakeState.amplitude : 0
+    );
+    let splitPrefixStroke = false;
+    if (
+      layerAlpha >= 1 &&
+      lineCacheHits(
+        s.lineCache,
+        layout,
+        cfg.dataRev,
+        dataSource,
+        visible.length,
+        visible[0]!.time,
+        visLastPoint.time,
+        visLastPoint.value
+      )
+    ) {
+      updateLineScrollLayer(
+        s.lineScroll,
+        s.lineCache,
+        layout,
+        cfg.palette,
+        s.lineScrollCache,
+        fonts
+      );
+      splitPrefixStroke = scrollLayerUsable(s.lineScroll, layerAlpha);
+    }
+    if (splitPrefixStroke) {
+      out.scrollPicture = s.lineScroll.picture;
+      out.scrollDx = scrollLayerDx(s.lineScroll, layout);
+    }
+
     // Draw canvas content (everything except badge)
     drawFrame(ctx, layout, cfg.palette, {
       visible,
@@ -1754,7 +1830,8 @@ export function engineStep(
       lineCache: {
         slot: s.lineCache,
         dataRev: cfg.dataRev,
-        dataSource: dataSourceOf(useStash, s.pausedData !== null),
+        dataSource,
+        splitPrefixStroke,
       },
       gridLayer: s.gridLayer,
     });
diff --git a/src/useLivelineEngine.ts b/src/useLivelineEngine.ts
index 28a1eb9..4044226 100644
--- a/src/useLivelineEngine.ts
+++ b/src/useLivelineEngine.ts
@@ -129,9 +129,11 @@ export interface LivelineEngine {
    * horizontally by `scrollTransform` instead of being re-recorded. Render
    * inside a `<Group transform={scrollTransform}>`, *below* `screenPicture`.
    *
-   * Currently always the empty placeholder — the declarative shell ships as a
-   * structural no-op and the line's prefix stroke moves in here in a later
-   * step.
+   * Holds the single-series line's prefix stroke (the spline through all but
+   * the last data point), re-recorded only when the line path cache misses.
+   * Stays the empty placeholder in multi-series and candle mode, and on any
+   * frame where the line can't be composited at alpha 1 — see
+   * draw/lineScrollLayer.ts.
    */
   scrollPicture: SharedValue<SkPicture>;
   /**
@@ -395,15 +397,19 @@ export function useLivelineEngine(
   const size = useSharedValue({ w: 0, h: 0 });
   const hoverX = useSharedValue<number | null>(null);
   const screenPicture = useSharedValue<SkPicture>(makeEmptyPicture());
-  // The scroll layer. Nothing records into it yet (the declarative shell
-  // ships as a structural no-op), so it stays the 1×1 empty placeholder and
-  // draws nothing — rendering is pixel-identical to the single-picture tree.
+  // The 1×1 do-nothing picture the scroll layer falls back to on every frame
+  // that can't composite it (see StepOutput.scrollPicture). Held in its own
+  // shared value rather than captured from render scope so the frame worklet
+  // reaches it by exactly the same route as any other shared value.
+  const emptyPicture = useSharedValue<SkPicture>(makeEmptyPicture());
+  // The scroll layer — the single-series line's prefix stroke, recorded once
+  // per line-cache miss by engine/lineScrollLayer.ts and translated by
+  // `scrollTransform`. Starts (and, in the multi-series and candle
+  // pipelines, stays) the empty placeholder, which draws nothing.
   const scrollPicture = useSharedValue<SkPicture>(makeEmptyPicture());
   // `[{ translateX: dx }]`, reassigned by the frame callback below (a shared
   // value only notifies its mapper on assignment, so this can't be mutated
-  // in place). dx is always 0 for now, but it's written every recorded frame so
-  // the shared-value → <Group transform> plumbing is real rather than a
-  // constant that a later step would have to re-thread.
+  // in place).
   const scrollTransform = useSharedValue<Transforms3d>([{ translateX: 0 }]);
   // Last dx pushed into `scrollTransform`, so the frame callback can skip the
   // reassignment (and the array/object allocation it needs) when the offset
@@ -521,10 +527,17 @@ export function useLivelineEngine(
       multiDataBuf.value
     );
     screenPicture.value = recorder.finishRecordingAsPicture();
-    // Scroll-layer offset for this frame. Nothing is recorded into
-    // `scrollPicture` yet, so this is always 0 — the write exists so the
-    // shared value is genuinely driven from the frame loop.
-    const dx = 0;
+    // Publish this frame's scroll layer. `null` means the layer must not
+    // composite at all (see StepOutput.scrollPicture) — the empty 1×1
+    // placeholder goes up instead of leaving the previous frame's picture
+    // in place, since the screen picture then already contains the whole
+    // line. Both writes land in this same UI-thread tick as the screen
+    // picture, so the declarative tree's mapper always sees a consistent
+    // pair. Guarded on identity: an unchanged picture must not be
+    // reassigned, or every frame would look like a change to the mapper.
+    const nextScroll = result.scrollPicture ?? emptyPicture.value;
+    if (scrollPicture.value !== nextScroll) scrollPicture.value = nextScroll;
+    const dx = result.scrollDx;
     if (scrollDx.value !== dx) {
       scrollDx.value = dx;
       scrollTransform.value = [{ translateX: dx }];

From 33c23cb02f9c19ae32aa145895aa352c14f20b59 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Sat, 1 Aug 2026 10:14:52 -0400
Subject: [PATCH 14/37] feat: let the scroll transform run at full refresh rate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Picture re-recording stays paced at ~60fps (MIN_FRAME_INTERVAL_MS), but
translating an already-recorded picture is nearly free, so the scroll layer's
<Group transform> now advances on every vsync — 120fps on ProMotion — while
recording cost is unchanged.

This is the actual payoff of putting scroll in a transform. Before this, the
dx write sat BELOW the pacing gate, so the transform was capped at 60 along
with the recording and the split had bought a draw call rather than smoother
motion. A concurrent review flagged exactly that (its finding 10) and it was
right.

The iOS side needed nothing: example/ios/.../Info.plist already carries
CADisableMinimumFrameDurationOnPhone=true (Expo default), without which iOS
hard-caps any app at 60 regardless.

dx cannot simply be recomputed on a skipped vsync — it needs `layout`, which
is computed inside engineStep — so it is linearly extrapolated from the last
two RECORDED frames. Extrapolating observed motion rather than recomputing
from windowSecs/chartW is deliberate: it keeps no copy of the engine's
time-advance rules so it cannot drift out of sync with them, and pause, window
transitions and time-debt catch-up all fall out correctly for free. Every
recorded frame overwrites with the exact value, so error cannot accumulate
past one vsync.

Guarded three ways: only when a scroll layer is actually compositing, only
when a usable rate has been observed, and only across a gap short enough for
that rate to still hold (MAX_SCROLL_EXTRAPOLATION_MS = 20). A quiescence
resume, a return from background or a JS stall leaves the transform untouched
rather than flinging it somewhere it never was.

The math lives in src/engine/scrollExtrapolate.ts rather than inline, so jest
can reach it — useLivelineEngine.ts pulls in the native Skia binding and can't
be unit-tested, and the simulator renders at 60Hz so this branch barely
executes there. A sign error would have shipped invisibly and surfaced only on
real hardware. +13 tests (224 -> 237) covering direction of travel, every
guard boundary, and a 2s 120-vs-60Hz simulation asserting divergence stays
within one frame of motion.

KNOWN CONSEQUENCE, needs real hardware to judge: the prefix now moves at 120Hz
while the tail is re-recorded at 60Hz, so on skipped vsyncs they shear by one
frame of scroll — chartW / (windowSecs * refreshHz), about 0.25px on a 10s
window and 0.08px on 30s. Sub-pixel, but a shimmer at the join rather than a
clean offset. The simulator renders at 60 and cannot show this either way.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../__tests__/scrollExtrapolate.test.ts       | 106 ++++++++++++++++++
 src/engine/constants.ts                       |  13 +++
 src/engine/scrollExtrapolate.ts               |  76 +++++++++++++
 src/engine/state.ts                           |  26 +++++
 src/useLivelineEngine.ts                      |  55 +++++++++
 5 files changed, 276 insertions(+)
 create mode 100644 src/engine/__tests__/scrollExtrapolate.test.ts
 create mode 100644 src/engine/scrollExtrapolate.ts

diff --git a/src/engine/__tests__/scrollExtrapolate.test.ts b/src/engine/__tests__/scrollExtrapolate.test.ts
new file mode 100644
index 0000000..8471dd9
--- /dev/null
+++ b/src/engine/__tests__/scrollExtrapolate.test.ts
@@ -0,0 +1,106 @@
+import { observeScrollRate, extrapolateScrollDx } from '../scrollExtrapolate';
+import { MAX_SCROLL_EXTRAPOLATION_MS } from '../constants';
+
+/**
+ * The call site (useLivelineEngine's frame callback) can't be unit-tested —
+ * it pulls in the native Skia binding — and the simulator renders at 60Hz, so
+ * the paced-out branch this logic serves barely executes there. A sign error
+ * would ship silently and only appear on real ProMotion hardware. Hence these.
+ */
+
+describe('observeScrollRate', () => {
+  it('returns 0 when there is no previous recorded frame', () => {
+    expect(observeScrollRate(0, -1, -5, 16)).toBe(0);
+  });
+
+  it('measures the observed per-ms rate over a normal paced interval', () => {
+    // Chart scrolls left, so dx decreases: -10 -> -20 over 16ms.
+    expect(observeScrollRate(-10, 100, -20, 116)).toBeCloseTo(-10 / 16, 10);
+  });
+
+  it('is negative for leftward scroll and positive for rightward', () => {
+    expect(observeScrollRate(-10, 100, -20, 116)).toBeLessThan(0);
+    expect(observeScrollRate(-20, 100, -10, 116)).toBeGreaterThan(0);
+  });
+
+  it('rejects a non-advancing or backwards clock', () => {
+    expect(observeScrollRate(-10, 100, -20, 100)).toBe(0);
+    expect(observeScrollRate(-10, 100, -20, 90)).toBe(0);
+  });
+
+  it('rejects a gap too long to be a paced interval', () => {
+    // A quiescence resume or return from background: large dx change over a
+    // large gap would otherwise bake in a meaningless rate.
+    const long = MAX_SCROLL_EXTRAPOLATION_MS * 2 + 1;
+    expect(observeScrollRate(-10, 100, -5000, 100 + long)).toBe(0);
+  });
+
+  it('accepts a gap exactly at the bound', () => {
+    const at = MAX_SCROLL_EXTRAPOLATION_MS * 2;
+    expect(observeScrollRate(-10, 100, -20, 100 + at)).not.toBe(0);
+  });
+});
+
+describe('extrapolateScrollDx', () => {
+  it('returns null before any recorded frame', () => {
+    expect(extrapolateScrollDx(0, -1, -0.5, 16)).toBeNull();
+  });
+
+  it('returns null when no rate has been observed', () => {
+    expect(extrapolateScrollDx(-10, 100, 0, 108)).toBeNull();
+  });
+
+  it('advances dx in the direction of travel', () => {
+    // -0.6 px/ms leftward, 8ms after the last record (a 120Hz vsync landing
+    // between two 60Hz records).
+    expect(extrapolateScrollDx(-10, 100, -0.6, 108)).toBeCloseTo(-14.8, 10);
+  });
+
+  it('returns null once the gap outruns the extrapolation window', () => {
+    const past = 100 + MAX_SCROLL_EXTRAPOLATION_MS + 1;
+    expect(extrapolateScrollDx(-10, 100, -0.6, past)).toBeNull();
+  });
+
+  it('accepts a gap exactly at the window bound', () => {
+    const at = 100 + MAX_SCROLL_EXTRAPOLATION_MS;
+    expect(extrapolateScrollDx(-10, 100, -0.6, at)).not.toBeNull();
+  });
+
+  it('rejects a non-advancing or backwards clock', () => {
+    expect(extrapolateScrollDx(-10, 100, -0.6, 100)).toBeNull();
+    expect(extrapolateScrollDx(-10, 100, -0.6, 95)).toBeNull();
+  });
+
+  it('never accumulates: error is bounded by one vsync, not the run', () => {
+    // Simulate 120Hz vsyncs against 60Hz records over 2 seconds of steady
+    // scroll, with the extrapolation deliberately using a slightly stale rate.
+    // Because every record overwrites with the exact value, divergence must
+    // stay within one frame's worth of motion forever.
+    const TRUE_RATE = -0.6; // px/ms
+    const RECORD_MS = 16.67;
+    const VSYNC_MS = 8.33;
+    let dxLast = 0;
+    let tLast = 0;
+    let rate = TRUE_RATE * 0.9; // 10% stale on purpose
+    let worst = 0;
+
+    for (let i = 1; i * VSYNC_MS < 2000; i++) {
+      const now = i * VSYNC_MS;
+      const trueDx = TRUE_RATE * now;
+      const isRecord = now - tLast >= RECORD_MS;
+
+      if (isRecord) {
+        rate = observeScrollRate(dxLast, tLast, trueDx, now);
+        dxLast = trueDx;
+        tLast = now;
+      } else {
+        const dxEx = extrapolateScrollDx(dxLast, tLast, rate, now);
+        if (dxEx !== null) worst = Math.max(worst, Math.abs(dxEx - trueDx));
+      }
+    }
+
+    // One 120Hz frame of motion is 0.6 * 8.33 = 5px; the stale-rate error is a
+    // fraction of that and must never grow beyond it.
+    expect(worst).toBeLessThan(5);
+  });
+});
diff --git a/src/engine/constants.ts b/src/engine/constants.ts
index 13e09f3..a0602a5 100644
--- a/src/engine/constants.ts
+++ b/src/engine/constants.ts
@@ -35,6 +35,19 @@ export const QUIESCENT_FRAME_THRESHOLD = 90;
 // while still roughly halving work on a 120Hz display.
 export const MIN_FRAME_INTERVAL_MS = 15;
 
+// --- Scroll-transform extrapolation window ---
+// On a vsync that frame pacing skips, the scroll layer's translate is
+// extrapolated from the last two recorded frames rather than recomputed (see
+// EngineState.scrollDxRate). That is only sound across a gap of roughly one
+// paced interval; beyond it the stored rate is stale and extrapolating would
+// fling the layer somewhere it never was. Any longer gap — quiescence
+// resuming, the app returning from background, a JS-thread stall — leaves the
+// transform untouched until the next recorded frame supplies an exact value.
+// 20ms is just over one 60Hz interval, so it covers the intended case (a
+// 120Hz vsync landing ~8ms after a record) with margin for jitter, and
+// nothing else.
+export const MAX_SCROLL_EXTRAPOLATION_MS = 20;
+
 // --- Candle-specific constants ---
 export const CANDLE_LERP_SPEED = 0.25;
 // Relative snap threshold for the live candle's OHLC lerp (see step.ts).
diff --git a/src/engine/scrollExtrapolate.ts b/src/engine/scrollExtrapolate.ts
new file mode 100644
index 0000000..4092ae8
--- /dev/null
+++ b/src/engine/scrollExtrapolate.ts
@@ -0,0 +1,76 @@
+import { MAX_SCROLL_EXTRAPOLATION_MS } from './constants';
+
+/**
+ * Scroll-transform extrapolation for paced-out vsyncs.
+ *
+ * Picture re-recording is paced to ~60fps (`MIN_FRAME_INTERVAL_MS`), but
+ * translating an already-recorded picture is nearly free, so the scroll
+ * layer's `<Group transform>` is allowed to advance on every vsync — 120fps on
+ * a ProMotion display. On a vsync the pacing gate skips there is no `layout`
+ * (it is computed inside `engineStep`), so `dx` cannot be recomputed; it is
+ * linearly extrapolated from the last two *recorded* frames instead.
+ *
+ * Extrapolating the observed motion, rather than recomputing from
+ * `windowSecs`/`chartW`, is deliberate: it keeps no copy of the engine's
+ * time-advance rules, so it cannot drift out of sync with them, and pause,
+ * window transitions and time-debt catch-up all come out right for free —
+ * whatever the chart actually did over the last interval is assumed to
+ * continue for the next few milliseconds. Every recorded frame overwrites the
+ * result with the exact value, so error cannot accumulate past one vsync.
+ *
+ * Split into this Skia-free module (mirroring draw/scrollLayer.ts and
+ * draw/gridLayer.ts) specifically so jest can exercise it: the call site lives
+ * in useLivelineEngine.ts, which pulls in the native Skia binding and cannot
+ * be unit-tested — and a sign error or a bad guard here would be invisible on
+ * a 60Hz simulator, only surfacing on real high-refresh hardware.
+ */
+
+/**
+ * Observed dx-per-ms across the last two recorded frames.
+ *
+ * Returns 0 (i.e. "don't extrapolate") unless the gap looks like a genuine
+ * paced interval. A quiescence resume, a return from background or a
+ * JS-thread stall produces a large dx change over a large gap; dividing one
+ * by the other would bake in a meaningless rate that the next skipped vsync
+ * would then apply. The bound is twice the extrapolation window, so an
+ * ordinary paced interval (~16ms) is comfortably inside it while a stall is
+ * not.
+ *
+ * `tPrev < 0` means no previous recorded frame.
+ */
+export function observeScrollRate(
+  dxPrev: number,
+  tPrev: number,
+  dx: number,
+  now: number
+): number {
+  'worklet';
+  if (tPrev < 0) return 0;
+  const gap = now - tPrev;
+  if (gap <= 0 || gap > MAX_SCROLL_EXTRAPOLATION_MS * 2) return 0;
+  return (dx - dxPrev) / gap;
+}
+
+/**
+ * dx for a vsync that will not record, or `null` when the transform should be
+ * left exactly as it is.
+ *
+ * `null` (rather than a fallback number) is the point: leaving the shared
+ * value untouched costs nothing and shows the last correct position, whereas
+ * guessing would move the layer somewhere it never was. Returns `null` when
+ * there is no previous recorded frame, when no usable rate has been observed,
+ * or when the gap has grown past `MAX_SCROLL_EXTRAPOLATION_MS` — beyond that
+ * the stored rate is stale and extrapolating it would fling the layer.
+ */
+export function extrapolateScrollDx(
+  dxLast: number,
+  tLast: number,
+  rate: number,
+  now: number
+): number | null {
+  'worklet';
+  if (tLast < 0 || rate === 0) return null;
+  const gap = now - tLast;
+  if (gap <= 0 || gap > MAX_SCROLL_EXTRAPOLATION_MS) return null;
+  return dxLast + rate * gap;
+}
diff --git a/src/engine/state.ts b/src/engine/state.ts
index 6facba6..36a3442 100644
--- a/src/engine/state.ts
+++ b/src/engine/state.ts
@@ -140,6 +140,29 @@ export interface EngineState {
   /** Dedicated Skia object cache for the line scroll layer's own
    * sub-recording — same reasoning as `gridLayerCache` above. */
   lineScrollCache: SkiaCache;
+
+  // --- Scroll-transform extrapolation (see useLivelineEngine's frame
+  // callback). Picture re-recording is paced to ~60fps, but translating an
+  // already-recorded picture is nearly free, so the scroll transform is
+  // allowed to update on every vsync — 120fps on a ProMotion display. On a
+  // vsync that the pacing gate skips there is no `layout` (it is computed
+  // inside engineStep), so `dx` cannot be recomputed; it is linearly
+  // extrapolated from the last two *recorded* frames instead.
+  //
+  // Extrapolating the observed motion, rather than recomputing from
+  // windowSecs/chartW, is deliberate: it needs no copy of the engine's
+  // time-advance rules, so it cannot drift out of sync with them, and it
+  // handles pause, window transitions and time-debt catch-up for free —
+  // whatever the chart actually did over the last interval is what it is
+  // assumed to keep doing for the next few milliseconds. Every recorded
+  // frame overwrites the extrapolation with the exact value, so error can
+  // never accumulate across more than one skipped vsync.
+  /** dx at the last recorded frame. */
+  scrollDxLast: number;
+  /** Timestamp (ms) of the last recorded frame; -1 before the first. */
+  scrollDxLastT: number;
+  /** Observed dx change per ms across the last two recorded frames. */
+  scrollDxRate: number;
   /** Cross-frame closed-candle body+wick path cache, candle mode (see
    * draw/candleCache). */
   candleCache: CandleCacheSlot;
@@ -311,6 +334,9 @@ export function createEngineState(
     gridLayerCache: createSkiaCache(),
     lineScroll: createScrollLayerSlot<SkPicture>(),
     lineScrollCache: createSkiaCache(),
+    scrollDxLast: 0,
+    scrollDxLastT: -1,
+    scrollDxRate: 0,
     candleCache: createCandleCacheSlot(),
 
     scrubAmount: 0,
diff --git a/src/useLivelineEngine.ts b/src/useLivelineEngine.ts
index 4044226..d48f737 100644
--- a/src/useLivelineEngine.ts
+++ b/src/useLivelineEngine.ts
@@ -43,6 +43,10 @@ import {
   QUIESCENT_FRAME_THRESHOLD,
   MIN_FRAME_INTERVAL_MS,
 } from './engine/constants';
+import {
+  observeScrollRate,
+  extrapolateScrollDx,
+} from './engine/scrollExtrapolate';
 import {
   computeDelta,
   pointsEqual,
@@ -501,6 +505,40 @@ export function useLivelineEngine(
       s.lastFrameTimestamp !== null &&
       now_ms - s.lastFrameTimestamp < MIN_FRAME_INTERVAL_MS
     ) {
+      // Paced out — no re-record this vsync. But translating an
+      // already-recorded picture is nearly free, so the scroll layer's
+      // transform still advances, giving the scrolled content the display's
+      // full refresh rate (120fps on ProMotion) while recording stays at ~60.
+      // This is the point of putting scroll in a <Group transform> at all;
+      // without it the layer would judder in lockstep with the paced
+      // recording and the split would have bought a draw call and nothing
+      // else.
+      //
+      // `dx` cannot be recomputed here — it needs `layout`, which lives
+      // inside engineStep — so it is extrapolated from the last two recorded
+      // frames (see EngineState.scrollDxRate). Guarded three ways: only when
+      // a scroll layer is actually compositing, only when a rate has been
+      // observed, and only across a gap short enough for that rate to still
+      // be true (MAX_SCROLL_EXTRAPOLATION_MS).
+      //
+      // Known consequence: the prefix now moves at 120Hz while the tail is
+      // re-recorded at 60Hz, so on skipped vsyncs they shear by one frame of
+      // scroll — chartW / (windowSecs * refreshHz), i.e. ~0.25px on a 10s
+      // window and ~0.08px on 30s. Sub-pixel, but it is a shimmer at the
+      // join rather than a clean offset. Verify on real 120Hz hardware; the
+      // simulator renders at 60 and cannot show this either way.
+      if (scrollPicture.value !== emptyPicture.value) {
+        const dxEx = extrapolateScrollDx(
+          s.scrollDxLast,
+          s.scrollDxLastT,
+          s.scrollDxRate,
+          now_ms
+        );
+        if (dxEx !== null && scrollDx.value !== dxEx) {
+          scrollDx.value = dxEx;
+          scrollTransform.value = [{ translateX: dxEx }];
+        }
+      }
       return;
     }
 
@@ -538,6 +576,23 @@ export function useLivelineEngine(
     const nextScroll = result.scrollPicture ?? emptyPicture.value;
     if (scrollPicture.value !== nextScroll) scrollPicture.value = nextScroll;
     const dx = result.scrollDx;
+    // Observed dx-per-ms across the last two RECORDED frames, used to
+    // extrapolate the transform on paced-out vsyncs above. Derived from what
+    // the chart actually did rather than from windowSecs/chartW, so pause,
+    // window transitions and time-debt catch-up need no special cases. Only
+    // updated across a gap short enough to be a real paced interval —
+    // otherwise a quiescence or background gap would divide a large dx change
+    // by a large dt and bake in a meaningless rate.
+    s.scrollDxRate = observeScrollRate(
+      s.scrollDxLast,
+      s.scrollDxLastT,
+      dx,
+      now_ms
+    );
+    s.scrollDxLast = dx;
+    s.scrollDxLastT = now_ms;
+    // Exact value always wins over whatever a skipped vsync extrapolated, so
+    // extrapolation error can never accumulate past one frame.
     if (scrollDx.value !== dx) {
       scrollDx.value = dx;
       scrollTransform.value = [{ translateX: dx }];

From 8e674cbf741a07616faa19bab350b594e03ba793 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Sat, 1 Aug 2026 10:39:36 -0400
Subject: [PATCH 15/37] refactor: apply /simplify findings (net -217 lines)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Four independent quality reviews (reuse, simplification, efficiency,
altitude). Three findings were raised by 2-3 reviewers independently; the
efficiency pass corrected the simplification pass on one, which is why item 7
is narrower than first proposed.

Deleted as dead:
- scrollLayer.ts's entire clip API — setScrollLayerClip, clipX/Y/W/H, and the
  header's ctx.clipRect/translate/drawPicture example. None of it executed:
  the sole consumer bakes the clip into the recording and composites through
  <Group transform>. The module's headline example was not how the module was
  used.
- scrollLayerDx. It and lineCache.ts's lineScrollDx had identical bodies and
  BOTH doc comments claimed to be "the ONE place" the subtraction is written.
  ScrollLayerSlot also loses tRef/xRefAtBuild — copied from the line slot, so
  a mirror that could go stale rather than a source.

Simplified:
- The scroll layer's key drops from 16 pushed dimensions to 4. Thirteen were
  copied verbatim from LineCacheSlot's own key to ask one question: has the
  prefix been rebuilt? A monotonic buildRev counter answers it, and is
  strictly MORE correct — the old key would have silently missed a fourteenth
  dimension had one been added to lineCacheHits.
- canCompositeLineScroll replaces lineScrollLayerAlpha, which returned only
  0 or 1 and encoded a transform condition (shake) as an opacity.
- The extrapolation rationale was written four times, three near-verbatim.
  Full text now lives only in scrollExtrapolate.ts.

Fixed:
- The liveness guard compared against a SECOND empty picture, so before the
  first recorded frame it read "layer is live" when nothing was compositing.
  Now a boolean on EngineState, set where the recorded frame already knows.
- scrollTransform.value = [{ translateX: dx }] allocated an array and an
  object per assignment — up to 240/sec at 120Hz on the UI thread, in a
  library that pools paints and rects to avoid exactly this. Now a 3-slot
  preallocated ring, rotate-mutate-assign, zero steady-state allocation.
  (A shared value must be reassigned to notify its mapper, so mutation alone
  is not an option.)
- assembleLineTail no longer builds the combined path when it will be
  discarded — but ONLY when splitting AND there is no fill. With fill on,
  scratch still feeds the fill polygon and is genuinely needed.

Hardened:
- MIN_FRAME_INTERVAL_MS and MAX_SCROLL_EXTRAPOLATION_MS are coupled by two
  inequalities that nothing expressed. Raising the former to 22 — a plausible
  "record at 45fps" tuning — silently reverts the scroll layer to juddering,
  with no test failing and the symptom visible only on 120Hz hardware. Both
  inequalities are now documented and asserted in engine/__tests__/
  constants.test.ts, turning a silent hardware-only regression into a red test.
- QUIESCENT_FRAME_THRESHOLD's comment claimed "~1.5s at 60fps"; it counts
  vsyncs, not recorded frames, so it is ~0.75s on ProMotion. Pre-existing, but
  this branch is the first code that depends on the distinction.

Deliberately NOT done, each for a stated reason:
- Publishing an analytic scrollDxPerMs slope from step.ts to replace
  observeScrollRate. Very likely the better design — exact rather than
  observed, and it would work on the first vsync after a resume where the
  current code freezes — but it is a design change, not a cleanup.
- Extracting makeChartLayout (touches the candle and multi-series pipelines).
- Reusable ctx in canvas2d.ts (~2200 allocs/sec, the largest single win found,
  and entirely pre-existing).
- drawTimeAxis's per-label save()/restore() (~1000 JSI calls/sec, pre-existing).

Tests 237 -> 218: removed tests for deleted code, added constants.test.ts.
Verified on the iOS simulator — rendering unchanged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../2026-07-31-declarative-shell-design.md    |  28 ++
 src/draw/__tests__/lineScrollLayer.test.ts    | 103 +++----
 src/draw/__tests__/scrollLayer.test.ts        | 266 ++----------------
 src/draw/line.ts                              |  18 +-
 src/draw/lineCache.ts                         |  40 ++-
 src/draw/lineScrollLayer.ts                   |  70 ++---
 src/draw/scrollLayer.ts                       | 161 +++--------
 src/draw/timeAxis.ts                          |  39 ++-
 src/engine/__tests__/constants.test.ts        |  42 +++
 src/engine/constants.ts                       |  50 +++-
 src/engine/lineScrollLayer.ts                 |  26 +-
 src/engine/state.ts                           |  26 +-
 src/engine/step.ts                            |  21 +-
 src/useLivelineEngine.ts                      |  97 ++++---
 14 files changed, 420 insertions(+), 567 deletions(-)
 create mode 100644 src/engine/__tests__/constants.test.ts

diff --git a/docs/superpowers/specs/2026-07-31-declarative-shell-design.md b/docs/superpowers/specs/2026-07-31-declarative-shell-design.md
index 64cf513..852c139 100644
--- a/docs/superpowers/specs/2026-07-31-declarative-shell-design.md
+++ b/docs/superpowers/specs/2026-07-31-declarative-shell-design.md
@@ -159,3 +159,31 @@ different things, and the frame callback converts the former into the latter.
 - **Text subpixel.** Nothing text-bearing is in the scroll layer in this design,
   so the jitter risk flagged earlier does not apply yet. It returns if the axis
   is ever moved in.
+
+---
+
+## Addendum 2026-08-01 — what the cleanup pass changed
+
+This document is a dated record of what was decided *before* implementation.
+Two API names it references no longer exist; the design itself is unchanged.
+
+- **`scrollLayerDx` is gone.** It and `lineCache.ts`'s `lineScrollDx` had
+  identical bodies and both doc comments claimed to be the single place the
+  `toX(tRef) - xRefAtBuild` subtraction was written. `lineScrollDx` survives;
+  `ScrollLayerSlot` no longer carries `tRef`/`xRefAtBuild` at all, because they
+  were copied from the line cache slot and could therefore go stale.
+- **`setScrollLayerClip` and the `clipX/clipY/clipW/clipH` fields are gone,**
+  along with the "each slot clips to its OWN region" invariant above. They
+  described an imperative `ctx.clipRect` + `ctx.translate` + `ctx.drawPicture`
+  composite. The implementation composites through `<Group transform>` and
+  bakes the clip into the recording instead, so none of it ever executed.
+- **The scroll layer's invalidation key is four dimensions, not sixteen.** A
+  `buildRev` counter on `LineCacheSlot` replaced the thirteen dimensions that
+  were being copied verbatim out of the line cache's own key — which would have
+  silently missed a fourteenth had one ever been added there.
+
+Also added, and not anticipated here: `MIN_FRAME_INTERVAL_MS` and
+`MAX_SCROLL_EXTRAPOLATION_MS` turn out to be coupled by two inequalities, now
+documented in `engine/constants.ts` and asserted in `engine/__tests__/
+constants.test.ts`. Tuning either alone can silently disable high-refresh
+scrolling in a way only 120Hz hardware would reveal.
diff --git a/src/draw/__tests__/lineScrollLayer.test.ts b/src/draw/__tests__/lineScrollLayer.test.ts
index 561a3ef..836c376 100644
--- a/src/draw/__tests__/lineScrollLayer.test.ts
+++ b/src/draw/__tests__/lineScrollLayer.test.ts
@@ -1,4 +1,4 @@
-import { lineScrollLayerAlpha, writeLineScrollKey } from '../lineScrollLayer';
+import { canCompositeLineScroll, writeLineScrollKey } from '../lineScrollLayer';
 import {
   createScrollLayerSlot,
   scrollLayerBuilt,
@@ -29,26 +29,12 @@ function makePalette(overrides: Partial<LivelinePalette> = {}) {
   } as LivelinePalette;
 }
 
-/** A line cache slot with a plausible committed key (the fields
- * `writeLineScrollKey` reads). `prefix` is set so the slot looks built. */
+/** A line cache slot that looks like it has a built prefix. `buildRev` is
+ * the only field `writeLineScrollKey` reads off it. */
 function makeLineSlot(): LineCacheSlot {
   const slot = createLineCacheSlot();
   slot.prefix = {} as LineCacheSlot['prefix'];
-  slot.tRef = 1000;
-  slot.xRefAtBuild = 10;
-  slot.kDataRev = 7;
-  slot.kDataSource = 0;
-  slot.kLen = 120;
-  slot.kFirstT = 1000;
-  slot.kLastT = 1060;
-  slot.kLastV = 101.5;
-  slot.kMin = 90;
-  slot.kMax = 110;
-  slot.kWindow = 60;
-  slot.kH = 200;
-  slot.kPadTop = 10;
-  slot.kPadBottom = 20;
-  slot.kChartW = 370;
+  slot.buildRev = 7;
   return slot;
 }
 
@@ -60,44 +46,36 @@ function record(
   palette: LivelinePalette
 ) {
   writeLineScrollKey(slot, lineSlot, padLeft, palette);
-  scrollLayerBuilt(slot, PICTURE, lineSlot.tRef, lineSlot.xRefAtBuild);
+  scrollLayerBuilt(slot, PICTURE);
 }
 
-describe('lineScrollLayerAlpha', () => {
-  it('is 1 only when fully revealed, not scrubbing and not shaking', () => {
-    expect(lineScrollLayerAlpha(1, 0, 0)).toBe(1);
+describe('canCompositeLineScroll', () => {
+  it('is true only when fully revealed, not scrubbing and not shaking', () => {
+    expect(canCompositeLineScroll(1, 0, 0)).toBe(true);
   });
 
-  it('is 0 during the reveal morph', () => {
-    expect(lineScrollLayerAlpha(0, 0, 0)).toBe(0);
-    expect(lineScrollLayerAlpha(0.999, 0, 0)).toBe(0);
+  it('is false during the reveal morph', () => {
+    expect(canCompositeLineScroll(0, 0, 0)).toBe(false);
+    expect(canCompositeLineScroll(0.999, 0, 0)).toBe(false);
   });
 
   it('tolerates a reveal lerp that overshoots its target', () => {
     // Mirrors scrollLayerUsable's `>= 1` rather than `=== 1`.
-    expect(lineScrollLayerAlpha(1.0001, 0, 0)).toBe(1);
+    expect(canCompositeLineScroll(1.0001, 0, 0)).toBe(true);
   });
 
-  it('is 0 for any non-zero scrub, and 1 again once scrub snaps to 0', () => {
-    expect(lineScrollLayerAlpha(1, 0.4, 0)).toBe(0);
+  it('is false for any non-zero scrub, and true again once scrub snaps to 0', () => {
+    expect(canCompositeLineScroll(1, 0.4, 0)).toBe(false);
     // updateHoverState snaps scrubAmount to exactly 0 below 0.01, which is
     // what makes the gate re-enable rather than asymptote.
-    expect(lineScrollLayerAlpha(1, 0, 0)).toBe(1);
+    expect(canCompositeLineScroll(1, 0, 0)).toBe(true);
   });
 
-  it('is 0 while the degen shake is translating the frame', () => {
-    expect(lineScrollLayerAlpha(1, 0, 0.2)).toBe(0);
-    expect(lineScrollLayerAlpha(1, 0, 12)).toBe(0);
-  });
-
-  it('never returns a partial alpha — drawPicture cannot fade', () => {
-    const values = [
-      lineScrollLayerAlpha(0.5, 0, 0),
-      lineScrollLayerAlpha(1, 0.5, 0),
-      lineScrollLayerAlpha(1, 0, 1),
-      lineScrollLayerAlpha(1, 0, 0),
-    ];
-    for (const v of values) expect(v === 0 || v === 1).toBe(true);
+  it('is false while the degen shake is translating the frame', () => {
+    // A transform condition, not an opacity one — which is why this predicate
+    // is a boolean rather than an alpha.
+    expect(canCompositeLineScroll(1, 0, 0.2)).toBe(false);
+    expect(canCompositeLineScroll(1, 0, 12)).toBe(false);
   });
 });
 
@@ -118,31 +96,37 @@ describe('writeLineScrollKey', () => {
     expect(scrollLayerKeyHits(slot)).toBe(false);
   });
 
-  it.each([
-    ['kDataRev', (s: LineCacheSlot) => (s.kDataRev = 8)],
-    ['kDataSource', (s: LineCacheSlot) => (s.kDataSource = 1)],
-    ['kLen', (s: LineCacheSlot) => (s.kLen = 121)],
-    ['kFirstT', (s: LineCacheSlot) => (s.kFirstT = 1001)],
-    ['kLastT', (s: LineCacheSlot) => (s.kLastT = 1061)],
-    ['kLastV', (s: LineCacheSlot) => (s.kLastV = 101.6)],
-    ['kMin', (s: LineCacheSlot) => (s.kMin = 89)],
-    ['kMax', (s: LineCacheSlot) => (s.kMax = 111)],
-    ['kWindow', (s: LineCacheSlot) => (s.kWindow = 300)],
-    ['kH', (s: LineCacheSlot) => (s.kH = 201)],
-    ['kPadTop', (s: LineCacheSlot) => (s.kPadTop = 11)],
-    ['kPadBottom', (s: LineCacheSlot) => (s.kPadBottom = 21)],
-    ['kChartW', (s: LineCacheSlot) => (s.kChartW = 371)],
-  ])('misses when the line cache key changes: %s', (_name, mutate) => {
+  it('misses when the prefix has been rebuilt (buildRev moved)', () => {
+    // The one dimension that matters: the picture is a rendering of
+    // `prefix`, so it is stale exactly when `prefix` was rebuilt. One counter
+    // stands in for all 13 of `lineCacheHits`' dimensions, and cannot go
+    // stale when a 14th is added there.
     const slot = createScrollLayerSlot<FakePicture>();
     const lineSlot = makeLineSlot();
     const palette = makePalette();
     record(slot, lineSlot, 10, palette);
 
-    mutate(lineSlot);
+    lineSlot.buildRev++;
     writeLineScrollKey(slot, lineSlot, 10, palette);
     expect(scrollLayerKeyHits(slot)).toBe(false);
   });
 
+  it('hits across changes to the line cache key that did NOT rebuild the prefix', () => {
+    // The scroll key deliberately does not mirror `lineCacheHits`. A cache
+    // key field moving without a rebuild is not a state `updateLinePaths`
+    // produces (a changed key IS a miss IS a rebuild), so tracking it here
+    // would only ever throw away a valid picture.
+    const slot = createScrollLayerSlot<FakePicture>();
+    const lineSlot = makeLineSlot();
+    const palette = makePalette();
+    record(slot, lineSlot, 10, palette);
+
+    lineSlot.kDataRev = 99;
+    lineSlot.kLastV = 0;
+    writeLineScrollKey(slot, lineSlot, 10, palette);
+    expect(scrollLayerKeyHits(slot)).toBe(true);
+  });
+
   it('misses on a pad.left change — the clip is baked into the picture', () => {
     // pad.left is deliberately NOT part of the line cache's own key (it is
     // absorbed by dx), so this dimension can only come from here.
@@ -198,8 +182,7 @@ describe('writeLineScrollKey', () => {
     const refLen = slot.nRefLen;
 
     const other = makeLineSlot();
-    other.kDataSource = 2;
-    other.kLastV = 0;
+    other.buildRev = 99;
     writeLineScrollKey(slot, other, 0, makePalette({ line: '#000' }));
     expect(slot.nNumLen).toBe(numLen);
     expect(slot.nRefLen).toBe(refLen);
diff --git a/src/draw/__tests__/scrollLayer.test.ts b/src/draw/__tests__/scrollLayer.test.ts
index f3ef569..f6b1608 100644
--- a/src/draw/__tests__/scrollLayer.test.ts
+++ b/src/draw/__tests__/scrollLayer.test.ts
@@ -1,17 +1,14 @@
 import {
   createScrollLayerSlot,
-  setScrollLayerClip,
   scrollLayerBeginKey,
   scrollLayerPushNum,
   scrollLayerPushRef,
   scrollLayerKeyHits,
   scrollLayerCommitKey,
   scrollLayerBuilt,
-  scrollLayerDx,
   scrollLayerUsable,
   type ScrollLayerSlot,
 } from '../scrollLayer';
-import type { ChartLayout, Padding } from '../../types';
 
 // ── Fakes ──────────────────────────────────────────────────────────────────
 
@@ -27,40 +24,6 @@ function makePicture(): FakePicture {
   return { id: pictureId };
 }
 
-const PAD: Required<Padding> = { top: 10, right: 20, bottom: 20, left: 10 };
-
-/** Layout matching engineStep's construction (step.ts line-mode branch). */
-function makeLayout(
-  now: number,
-  windowSecs = 60,
-  w = 400,
-  h = 200
-): ChartLayout {
-  const chartW = w - PAD.left - PAD.right;
-  const chartH = h - PAD.top - PAD.bottom;
-  const buffer = 0.05;
-  const rightEdge = now + windowSecs * buffer;
-  const leftEdge = rightEdge - windowSecs;
-  const minVal = 90;
-  const maxVal = 110;
-  const valRange = maxVal - minVal;
-  return {
-    w,
-    h,
-    pad: PAD,
-    chartW,
-    chartH,
-    leftEdge,
-    rightEdge,
-    minVal,
-    maxVal,
-    valRange,
-    toX: (t: number) =>
-      PAD.left + ((t - leftEdge) / (rightEdge - leftEdge)) * chartW,
-    toY: (v: number) => PAD.top + (1 - (v - minVal) / valRange) * chartH,
-  };
-}
-
 /**
  * A representative consumer's key writer. Real consumers keep their pushes in
  * one helper exactly like this so there is a single push order to read; the
@@ -87,33 +50,24 @@ function writeKey(
 const FORMAT_A = (v: number) => `$${v}`;
 const FORMAT_B = (v: number) => `$${v}`;
 
-/** Build a slot into the "just rebuilt at `now`" state, keyed with `opts`. */
-function build(
-  now: number,
-  tRef: number,
-  opts: Parameters<typeof writeKey>[1] = {}
-): { slot: ScrollLayerSlot<FakePicture>; layout: ChartLayout } {
+/** Build a slot into the "just rebuilt" state, keyed with `opts`. */
+function build(opts: Parameters<typeof writeKey>[1] = {}): {
+  slot: ScrollLayerSlot<FakePicture>;
+} {
   const slot = createScrollLayerSlot<FakePicture>();
-  const layout = makeLayout(now);
   writeKey(slot, opts);
-  scrollLayerBuilt(slot, makePicture(), tRef, layout.toX(tRef));
-  return { slot, layout };
+  scrollLayerBuilt(slot, makePicture());
+  return { slot };
 }
 
 // ── Tests ──────────────────────────────────────────────────────────────────
 
 describe('createScrollLayerSlot', () => {
-  it('starts empty: no picture, no committed key, zero clip', () => {
+  it('starts empty: no picture, no committed key', () => {
     const slot = createScrollLayerSlot<FakePicture>();
     expect(slot.picture).toBeNull();
-    expect(slot.tRef).toBe(0);
-    expect(slot.xRefAtBuild).toBe(0);
     expect(slot.kNumLen).toBe(0);
     expect(slot.kRefLen).toBe(0);
-    expect(slot.clipX).toBe(0);
-    expect(slot.clipY).toBe(0);
-    expect(slot.clipW).toBe(0);
-    expect(slot.clipH).toBe(0);
   });
 });
 
@@ -129,7 +83,7 @@ describe('scrollLayerKeyHits', () => {
   });
 
   it('hits right after a build with the same inputs', () => {
-    const { slot } = build(1000, 970);
+    const { slot } = build();
     writeKey(slot);
     expect(scrollLayerKeyHits(slot)).toBe(true);
   });
@@ -141,26 +95,26 @@ describe('scrollLayerKeyHits', () => {
       { window: 120 },
     ];
     for (const change of cases) {
-      const { slot } = build(1000, 970);
+      const { slot } = build();
       writeKey(slot, change);
       expect(scrollLayerKeyHits(slot)).toBe(false);
     }
   });
 
   it('misses when a palette color changes (pictures bake paint)', () => {
-    const { slot } = build(1000, 970);
+    const { slot } = build();
     writeKey(slot, { lineColor: '#ef4444' });
     expect(scrollLayerKeyHits(slot)).toBe(false);
   });
 
   it('misses when a formatter changes reference, even if behaviourally identical', () => {
-    const { slot } = build(1000, 970);
+    const { slot } = build();
     writeKey(slot, { formatter: FORMAT_B });
     expect(scrollLayerKeyHits(slot)).toBe(false);
   });
 
   it('hits for every dimension held at its committed value (no false miss)', () => {
-    const { slot } = build(1000, 970, {
+    const { slot } = build({
       dataRev: 7,
       len: 33,
       window: 120,
@@ -178,7 +132,7 @@ describe('scrollLayerKeyHits', () => {
   });
 
   it('misses when the key arity changes rather than matching a prefix', () => {
-    const { slot } = build(1000, 970);
+    const { slot } = build();
     // Same first three numbers, but a consumer that grew its key.
     scrollLayerBeginKey(slot);
     scrollLayerPushNum(slot, 0);
@@ -199,7 +153,7 @@ describe('scrollLayerKeyHits', () => {
   });
 
   it('is read-only: does not commit, so a repeated miss stays a miss', () => {
-    const { slot } = build(1000, 970);
+    const { slot } = build();
     const pic = slot.picture;
     writeKey(slot, { dataRev: 1 });
     expect(scrollLayerKeyHits(slot)).toBe(false);
@@ -209,7 +163,7 @@ describe('scrollLayerKeyHits', () => {
   });
 
   it('reuses its arrays across frames — no per-frame allocation', () => {
-    const { slot } = build(1000, 970);
+    const { slot } = build();
     const nNum = slot.nNum;
     const nRef = slot.nRef;
     const kNum = slot.kNum;
@@ -228,202 +182,28 @@ describe('scrollLayerKeyHits', () => {
 });
 
 describe('scrollLayerBuilt', () => {
-  it('stores the picture, the reference pair, and commits the key together', () => {
+  it('stores the picture and commits the key together', () => {
     const slot = createScrollLayerSlot<FakePicture>();
-    const layout = makeLayout(1000);
     const pic = makePicture();
     writeKey(slot, { dataRev: 4 });
     expect(scrollLayerKeyHits(slot)).toBe(false);
 
-    scrollLayerBuilt(slot, pic, 970, layout.toX(970));
+    scrollLayerBuilt(slot, pic);
 
     expect(slot.picture).toBe(pic);
-    expect(slot.tRef).toBe(970);
-    expect(slot.xRefAtBuild).toBe(layout.toX(970));
     writeKey(slot, { dataRev: 4 });
     expect(scrollLayerKeyHits(slot)).toBe(true);
   });
 
-  it('a rebuild replaces the picture and re-anchors the reference', () => {
-    const { slot } = build(1000, 970);
+  it('a rebuild replaces the picture', () => {
+    const { slot } = build();
     const first = slot.picture;
-    const later = makeLayout(1030);
     const pic2 = makePicture();
     writeKey(slot, { dataRev: 1 });
-    scrollLayerBuilt(slot, pic2, 1000, later.toX(1000));
+    scrollLayerBuilt(slot, pic2);
 
+    expect(slot.picture).toBe(pic2);
     expect(slot.picture).not.toBe(first);
-    expect(slot.tRef).toBe(1000);
-    expect(scrollLayerDx(slot, later)).toBe(0);
-  });
-});
-
-describe('scrollLayerDx', () => {
-  it('is exactly zero on the frame of the build', () => {
-    const { slot, layout } = build(1000, 970);
-    // Not "close to" zero — tRef/xRefAtBuild come from the same toX, so the
-    // subtraction is exactly 0 and consumers can skip the translate entirely.
-    expect(scrollLayerDx(slot, layout)).toBe(0);
-  });
-
-  it('is exactly zero for every tRef, not just a lucky one', () => {
-    for (const tRef of [0, 970, 1000, -500, 1234.5678]) {
-      const { slot, layout } = build(1000, tRef);
-      expect(scrollLayerDx(slot, layout)).toBe(0);
-    }
-  });
-
-  it('moves content left as `now` advances', () => {
-    const { slot } = build(1000, 970);
-    const dx = scrollLayerDx(slot, makeLayout(1005));
-    expect(dx).toBeLessThan(0);
-    // 5s of a 60s window across chartW = 370px.
-    expect(dx).toBeCloseTo((-5 / 60) * 370, 9);
-  });
-
-  it('equals the translation a fresh build at the later time would need', () => {
-    // Ground truth: where tRef sits at the later time, minus where it sat at
-    // build time. The cached picture must land exactly there.
-    const tRef = 970;
-    const buildLayout = makeLayout(1000);
-    const laterLayout = makeLayout(1017.3);
-    const { slot } = build(1000, tRef);
-    expect(scrollLayerDx(slot, laterLayout)).toBeCloseTo(
-      laterLayout.toX(tRef) - buildLayout.toX(tRef),
-      9
-    );
-  });
-
-  it('does not drift over many frames — recomputed, never accumulated', () => {
-    const tRef = 970;
-    const { slot } = build(1000, tRef);
-    const PX_PER_SEC = 370 / 60; // chartW / windowSecs
-
-    // 6,000 frames of *jittered* frame times — the realistic case, since a
-    // real frame callback never gets a clean 1/60s. `naive` models the
-    // tempting `dx += nominalStep` implementation this module forbids.
-    let now = 1000;
-    let naive = 0;
-    let rng = 12345;
-    for (let i = 0; i < 6000; i++) {
-      rng = (rng * 1103515245 + 12345) % 2147483648;
-      // Real frames overrun the nominal interval more often than they beat
-      // it, so the jitter is deliberately biased rather than symmetric.
-      const step = (1 / 60) * (1 + (rng / 2147483648) * 0.5);
-      now += step;
-      naive -= (1 / 60) * PX_PER_SEC; // nominal, not actual
-
-      // The recomputed value is a pure function of this frame's layout, with
-      // no dependence on how many frames preceded it or how long they were.
-      if (i % 250 === 0) {
-        const layout = makeLayout(now);
-        expect(scrollLayerDx(slot, layout)).toBe(
-          layout.toX(tRef) - slot.xRefAtBuild
-        );
-      }
-    }
-
-    const finalLayout = makeLayout(now);
-    const dx = scrollLayerDx(slot, finalLayout);
-    // Exact against a first-principles calculation after 6,000 frames.
-    expect(dx).toBeCloseTo(-(now - 1000) * PX_PER_SEC, 9);
-    // The accumulating version is off by whole pixels — a visibly misaligned
-    // axis. This is the failure mode the doc comment on scrollLayerDx warns
-    // about, and it is why dx takes no per-frame delta parameter.
-    expect(Math.abs(naive - dx)).toBeGreaterThan(1);
-  });
-
-  it('is unaffected by the order frames are evaluated in (pure function of layout)', () => {
-    const { slot } = build(1000, 970);
-    const forward = [1001, 1002, 1003].map((t) =>
-      scrollLayerDx(slot, makeLayout(t))
-    );
-    const backward = [1003, 1002, 1001]
-      .map((t) => scrollLayerDx(slot, makeLayout(t)))
-      .reverse();
-    expect(forward).toEqual(backward);
-  });
-
-  it('absorbs a pad.left shift, which is why pad.left need not be keyed', () => {
-    // dx is a difference of two toX values; a constant x-offset cancels.
-    const { slot, layout } = build(1000, 970);
-    const later = makeLayout(1005);
-    const shifted: ChartLayout = {
-      ...later,
-      toX: (t: number) => later.toX(t) + 25,
-    };
-    const unshifted = scrollLayerDx(slot, later);
-    expect(scrollLayerDx(slot, shifted)).toBeCloseTo(unshifted + 25, 9);
-    expect(scrollLayerDx(slot, layout)).toBe(0);
-  });
-});
-
-describe('clip regions', () => {
-  it('each slot carries its own region — a plot slot and an axis slot differ', () => {
-    const layout = makeLayout(1000);
-    const plot = createScrollLayerSlot<FakePicture>();
-    const axis = createScrollLayerSlot<FakePicture>();
-
-    // Plot area: the chart body.
-    setScrollLayerClip(
-      plot,
-      layout.pad.left,
-      layout.pad.top,
-      layout.chartW,
-      layout.chartH
-    );
-    // Axis strip: `h - pad.bottom` downward. A shared plot-area clip would
-    // erase this entirely, which is the whole reason clips are per-slot.
-    const axisTop = layout.h - layout.pad.bottom;
-    setScrollLayerClip(
-      axis,
-      layout.pad.left,
-      axisTop,
-      layout.chartW,
-      layout.pad.bottom
-    );
-
-    expect(plot.clipY).toBe(10);
-    expect(plot.clipH).toBe(170);
-    expect(axis.clipY).toBe(180);
-    expect(axis.clipH).toBe(20);
-    // Disjoint vertically: the plot clip ends exactly where the axis begins.
-    expect(plot.clipY + plot.clipH).toBe(axis.clipY);
-  });
-
-  it('is not part of the invalidation key — re-clipping keeps the picture', () => {
-    const { slot } = build(1000, 970);
-    const pic = slot.picture;
-    setScrollLayerClip(slot, 10, 10, 370, 170);
-    writeKey(slot);
-    expect(scrollLayerKeyHits(slot)).toBe(true);
-    expect(slot.picture).toBe(pic);
-    setScrollLayerClip(slot, 0, 0, 400, 200);
-    writeKey(slot);
-    expect(scrollLayerKeyHits(slot)).toBe(true);
-  });
-
-  it('bounds a translated picture: content scrolled past the left edge is clipped away', () => {
-    // The clip is the guard against a picture's cull rect being translated
-    // somewhere it was never meant to cover.
-    const layout = makeLayout(1000);
-    const slot = createScrollLayerSlot<FakePicture>();
-    setScrollLayerClip(
-      slot,
-      layout.pad.left,
-      layout.pad.top,
-      layout.chartW,
-      layout.chartH
-    );
-    writeKey(slot);
-    scrollLayerBuilt(slot, makePicture(), 970, layout.toX(970));
-
-    // Content recorded at tRef, composited 30s later.
-    const later = makeLayout(1030);
-    const dx = scrollLayerDx(slot, later);
-    const contentX = slot.xRefAtBuild + dx;
-    expect(contentX).toBeLessThan(slot.clipX); // outside the clip on the left
-    expect(contentX).toBeCloseTo(later.toX(970), 9); // and at the right place
   });
 });
 
@@ -434,14 +214,14 @@ describe('scrollLayerUsable', () => {
   });
 
   it('is false below alpha 1 — drawPicture ignores globalAlpha', () => {
-    const { slot } = build(1000, 970);
+    const { slot } = build();
     expect(scrollLayerUsable(slot, 0)).toBe(false);
     expect(scrollLayerUsable(slot, 0.5)).toBe(false);
     expect(scrollLayerUsable(slot, 0.999)).toBe(false);
   });
 
   it('is true at exactly 1, and tolerates a lerp overshoot', () => {
-    const { slot } = build(1000, 970);
+    const { slot } = build();
     expect(scrollLayerUsable(slot, 1)).toBe(true);
     expect(scrollLayerUsable(slot, 1.0001)).toBe(true);
   });
diff --git a/src/draw/line.ts b/src/draw/line.ts
index 7931e87..f9f9fab 100644
--- a/src/draw/line.ts
+++ b/src/draw/line.ts
@@ -313,6 +313,13 @@ export function drawLine(
   const isScrubbing = scrubX !== null;
   const visLen = visible.length;
 
+  // The caller's request to stroke only the tail (the scroll layer has already
+  // composited the prefix). Read up here, before the cache branches, purely so
+  // the assembly below can skip building the combined `scratch` path when
+  // nothing will read it — see `assembleLineTail`. Only *honored* on frames
+  // where the cache is actually in use, which is what `splitStroke` below adds.
+  const wantSplitStroke = pathCache?.splitPrefixStroke === true;
+
   // Cross-frame path cache: the key/identity check runs FIRST, before any
   // per-frame array is built. On a hit, decimateMinMax and the O(decimated)
   // interior-points loop (in the miss branch below) are skipped entirely —
@@ -361,7 +368,8 @@ export function drawLine(
       tailY,
       tipX,
       tailY,
-      firstY
+      firstY,
+      wantSplitStroke
     );
     cacheReady = true;
     pts = [
@@ -416,7 +424,8 @@ export function drawLine(
         visLen,
         visible[0]!.time,
         visible[visLen - 1]!.time,
-        visible[visLen - 1]!.value
+        visible[visLen - 1]!.value,
+        wantSplitStroke
       );
   }
 
@@ -431,10 +440,7 @@ export function drawLine(
   // pts[N-1], pts[N] on a rebuild — which is exactly what
   // `assembleLineTail` was handed, so the tail-only path joins the
   // translated prefix at the identical point with the identical tangent.
-  const splitStroke =
-    cacheReady &&
-    pathCache !== undefined &&
-    pathCache.splitPrefixStroke === true;
+  const splitStroke = cacheReady && wantSplitStroke;
   if (splitStroke) {
     const n = pts.length;
     assembleLineTailStroke(
diff --git a/src/draw/lineCache.ts b/src/draw/lineCache.ts
index 0230f7e..27836cb 100644
--- a/src/draw/lineCache.ts
+++ b/src/draw/lineCache.ts
@@ -80,6 +80,19 @@ export interface LineCacheSlot {
   cutY: number;
   endTangent: number; // tangent the prefix actually ended with (post-clamp)
 
+  /**
+   * Monotonic counter bumped every time `prefix` is rebuilt — i.e. in the one
+   * place `slot.prefix` is written, the miss branch of `updateLinePaths`.
+   *
+   * This is the whole invalidation key for anything downstream that caches a
+   * *rendering* of `prefix` (the scroll layer's SkPicture). "Has the prefix
+   * changed since I recorded it?" is exactly one question, and copying the 13
+   * `kFoo` dimensions into a second key to re-answer it is a mirror that goes
+   * stale the moment a 14th dimension is added to `lineCacheHits`. One counter
+   * cannot.
+   */
+  buildRev: number;
+
   // Invalidation key — flat numbers only, compared field-by-field so a
   // per-frame check allocates nothing. Validity is `prefix !== null` (no
   // separate boolean — the two are always written together). `layout.w`
@@ -116,6 +129,7 @@ export function createLineCacheSlot(): LineCacheSlot {
     cutX: 0,
     cutY: 0,
     endTangent: 0,
+    buildRev: 0,
     kDataRev: 0,
     kDataSource: 0,
     kLen: 0,
@@ -187,9 +201,10 @@ export function lineCacheHits(
  * Returns 0 for a slot with no prefix (tRef/xRefAtBuild are both still 0
  * only by coincidence there, so callers should gate on `slot.prefix`).
  *
- * Identical formula to `scrollLayer.ts`'s `scrollLayerDx` — a scroll-layer
- * slot wrapping the prefix picture takes its `tRef`/`xRefAtBuild` straight
- * from this slot, and the two then agree by construction.
+ * The scroll layer (draw/scrollLayer.ts) uses this same function against this
+ * same slot rather than mirroring `tRef`/`xRefAtBuild` into a slot of its own:
+ * its picture is a recording *of* `slot.prefix`, so the picture and the
+ * translated path are the same geometry and must move by the same number.
  */
 export function lineScrollDx(slot: LineCacheSlot, layout: ChartLayout): number {
   'worklet';
@@ -216,6 +231,12 @@ export function lineScrollDx(slot: LineCacheSlot, layout: ChartLayout): number {
  * path: it isn't part of the invalidation key, so — matching the pre-split
  * behavior exactly — it's still recomputed fresh by the caller every frame
  * rather than trusted from a prior build.
+ *
+ * `splitStroke` (the declarative scroll layer is stroking `tailScratch`
+ * instead of `scratch` this frame) makes the combined path *unread as a
+ * stroke* — but NOT unused: the fill polygon is built by extending `scratch`,
+ * so it is only genuinely dead work when there is no fill. Hence the guard is
+ * `splitStroke && !wantFill`, and with fill on the assembly is unchanged.
  */
 export function assembleLineTail(
   slot: LineCacheSlot,
@@ -226,9 +247,11 @@ export function assembleLineTail(
   lastY: number,
   tipX: number,
   tipY: number,
-  firstY: number
+  firstY: number,
+  splitStroke: boolean = false
 ): void {
   'worklet';
+  if (splitStroke && !wantFill) return;
   const dx = lineScrollDx(slot, layout);
 
   // Assemble the stroke path: translated prefix + live tail.
@@ -398,7 +421,9 @@ export function updateLinePaths(
   visLen: number,
   visFirstT: number,
   visLastT: number,
-  visLastV: number
+  visLastV: number,
+  /** Forwarded to `assembleLineTail` — see its doc comment. */
+  splitStroke: boolean = false
 ): boolean {
   'worklet';
   const N = decimated.length;
@@ -417,6 +442,8 @@ export function updateLinePaths(
 
   if (!hit) {
     slot.prefix = ensured(slot.prefix, makePath);
+    // The ONE place `prefix` is written, so the ONE place `buildRev` moves.
+    slot.buildRev++;
     const prefix = slot.prefix;
     prefix.rewind();
     prefix.moveTo(pts[0]![0], pts[0]![1]);
@@ -452,7 +479,8 @@ export function updateLinePaths(
     pts[N - 1]![1],
     pts[N]![0],
     pts[N]![1],
-    pts[0]![1]
+    pts[0]![1],
+    splitStroke
   );
 
   return true;
diff --git a/src/draw/lineScrollLayer.ts b/src/draw/lineScrollLayer.ts
index 167a365..612f639 100644
--- a/src/draw/lineScrollLayer.ts
+++ b/src/draw/lineScrollLayer.ts
@@ -39,10 +39,10 @@ import {
  */
 
 /**
- * Composite alpha the prefix stroke would be drawn at this frame, as the
- * `alpha` argument for `scrollLayerUsable`. Returns 1 only when the whole
- * line pipeline is at full opacity *and* untransformed, i.e. when
- * compositing a pre-recorded picture is pixel-identical to drawing live:
+ * True when the prefix stroke may be composited from a pre-recorded picture
+ * this frame — i.e. when the whole line pipeline is at full opacity *and*
+ * untransformed, so compositing is pixel-identical to drawing live. Three
+ * things disqualify a frame:
  *
  * - `chartReveal < 1` — the reveal morph / loading / empty crossfade. The
  *   line is drawn at a breathing alpha, in a blended color, and its geometry
@@ -58,42 +58,44 @@ import {
  *   frame and the scroll layer (outside that translate) would tear away
  *   from the rest of the chart.
  *
- * Returns 0, not the true fractional alpha: `scrollLayerUsable` only ever
- * asks "is this >= 1", and inventing a partial alpha would suggest the
- * layer could be faded, which `ctx.drawPicture` cannot do (see
- * `scrollLayer.ts` invariant 1).
+ * A boolean, not an alpha: the first two conditions are opacity conditions
+ * and the third is a transform condition, and `scrollLayerUsable` only ever
+ * asks "is this >= 1" anyway. Returning a fraction would suggest the layer
+ * could be faded, which `ctx.drawPicture` cannot do (see `scrollLayer.ts`'s
+ * alpha invariant).
  */
-export function lineScrollLayerAlpha(
+export function canCompositeLineScroll(
   chartReveal: number,
   scrubAmount: number,
   shakeAmplitude: number
-): number {
+): boolean {
   'worklet';
-  if (chartReveal < 1) return 0;
-  if (scrubAmount > 0) return 0;
-  if (shakeAmplitude > 0) return 0;
-  return 1;
+  if (chartReveal < 1) return false;
+  if (scrubAmount > 0) return false;
+  if (shakeAmplitude > 0) return false;
+  return true;
 }
-
 /**
  * Writes this frame's candidate key for the prefix picture: begin, then one
  * push per dimension, unconditionally and always in this order (the push
  * order *is* the field identity — see the doc comment on
  * `ScrollLayerSlot`).
  *
- * The key is the line cache slot's **committed** key, verbatim, plus what a
- * picture bakes that a path does not (stroke color and width) plus
- * `pad.left`. Keying off the committed key rather than off this frame's raw
- * inputs is the point: the recorded picture is a rendering of
- * `slot.prefix`, so it is stale exactly when `slot.prefix` has been rebuilt,
- * and `slot.kFoo` is precisely the identity `slot.prefix` was built from.
- * Re-deriving the same dimensions from `layout`/`visible` would be a second
- * copy of `lineCacheHits` that could drift from the first.
+ * Four dimensions, and no more, because the picture is a rendering of
+ * `lineSlot.prefix` and the only question worth asking is **"has that prefix
+ * been rebuilt since I recorded it?"** `lineSlot.buildRev` answers exactly
+ * that, in one number, from the one place `prefix` is written. Copying the 13
+ * `kFoo` dimensions of `lineCacheHits` in here instead would re-derive the
+ * same answer from a mirror that silently misses any 14th dimension added to
+ * the line cache later.
+ *
+ * The other three are what a *picture* bakes that the path did not:
  *
- * `pad.left` is the one dimension the line cache deliberately omits (it is a
- * pure x-shift, absorbed by `dx`) but this layer needs: the composite clip
- * is baked into the recording at `pad.left - 1`, so a padding change must
- * re-record.
+ * - `palette.lineWidth` / `palette.line` — stroke geometry and color are
+ *   recorded into the picture; the cached path carries neither.
+ * - `pad.left` — deliberately omitted from the line cache's key (it is a
+ *   pure x-shift, absorbed by `dx`), but the composite clip is baked into
+ *   this recording at `pad.left - 1`, so a padding change must re-record.
  */
 export function writeLineScrollKey<Picture>(
   slot: ScrollLayerSlot<Picture>,
@@ -103,19 +105,7 @@ export function writeLineScrollKey<Picture>(
 ): void {
   'worklet';
   scrollLayerBeginKey(slot);
-  scrollLayerPushNum(slot, lineSlot.kDataRev);
-  scrollLayerPushNum(slot, lineSlot.kDataSource);
-  scrollLayerPushNum(slot, lineSlot.kLen);
-  scrollLayerPushNum(slot, lineSlot.kFirstT);
-  scrollLayerPushNum(slot, lineSlot.kLastT);
-  scrollLayerPushNum(slot, lineSlot.kLastV);
-  scrollLayerPushNum(slot, lineSlot.kMin);
-  scrollLayerPushNum(slot, lineSlot.kMax);
-  scrollLayerPushNum(slot, lineSlot.kWindow);
-  scrollLayerPushNum(slot, lineSlot.kH);
-  scrollLayerPushNum(slot, lineSlot.kPadTop);
-  scrollLayerPushNum(slot, lineSlot.kPadBottom);
-  scrollLayerPushNum(slot, lineSlot.kChartW);
+  scrollLayerPushNum(slot, lineSlot.buildRev);
   scrollLayerPushNum(slot, padLeft);
   scrollLayerPushNum(slot, palette.lineWidth);
   scrollLayerPushRef(slot, palette.line);
diff --git a/src/draw/scrollLayer.ts b/src/draw/scrollLayer.ts
index 97bea75..4b6a7ad 100644
--- a/src/draw/scrollLayer.ts
+++ b/src/draw/scrollLayer.ts
@@ -1,5 +1,3 @@
-import type { ChartLayout } from '../types';
-
 /**
  * Generic cross-frame cache for a **scroll layer**: an SkPicture recorded
  * once in build-time screen coordinates and re-composited every frame at a
@@ -11,42 +9,40 @@ import type { ChartLayout } from '../types';
  * that the chart scrolls left because "now" advanced; for that content a
  * rebuild is pure waste.
  *
- * Composition at draw time is always this shape (see `scrollLayerDx`):
+ * Composition happens in the declarative tree, not with canvas calls: the
+ * picture goes under a transform-only Skia `<Group>`, whose `translateX` is
+ * the slot's `dx` (`lineScrollDx` in draw/lineCache.ts for today's one
+ * consumer). See `Liveline.tsx`:
  *
- * ```ts
- * ctx.save();
- * ctx.clipRect(slot.clipX, slot.clipY, slot.clipW, slot.clipH);
- * ctx.translate(scrollLayerDx(slot, layout), 0);
- * ctx.drawPicture(slot.picture);
- * ctx.restore();
+ * ```tsx
+ * <Group transform={scrollTransform}>
+ *   <Picture picture={scrollPicture} />
+ * </Group>
  * ```
  *
- * Two invariants future maintainers must not break:
- *
- * 1. **Alpha must be exactly 1.** `ctx.drawPicture` ignores `globalAlpha` —
- *    Skia's drawPicture takes no paint argument (canvas2d.ts:139-143). Fading
- *    a picture would need `saveLayerAlpha`, which allocates an offscreen
- *    render target, precisely the Android cost this work exists to avoid. So
- *    every consumer gates on `scrollLayerUsable(slot, alpha)` and falls back
- *    to live drawing during the reveal morph, the loading/empty crossfade and
- *    scrub dimming. draw/index.ts:218 already gates the grid picture on
- *    `reveal >= 1` for exactly this reason.
- * 2. **Each slot clips to its OWN region.** `lineScroll`/`candleScroll` clip
- *    to the plot area; `axisScroll` clips to the axis strip below it
- *    (`h - pad.bottom` downward). A single shared chart-area clip would erase
- *    the axis entirely. The clip is also the guard that stops translated
- *    content from bleeding into the padding, the badge, or across the
- *    plot/axis boundary — a picture's cull rect lives in its own build-time
- *    coordinate space, so translating it can carry content into places the
- *    cull rect never intended to cover.
+ * A transform-only `<Group>` creates no layer, so the scroll layer and the
+ * per-frame screen picture share one surface and composite in tree order.
+ * Any clipping the content needs is recorded *into* the picture at build time
+ * (see engine/lineScrollLayer.ts, which explains why that is sound for
+ * horizontal-only motion); this module deliberately holds no clip state.
+ *
+ * The invariant future maintainers must not break: **alpha must be exactly
+ * 1.** `ctx.drawPicture` ignores `globalAlpha` — Skia's drawPicture takes no
+ * paint argument (canvas2d.ts:139-143). Fading a picture would need
+ * `saveLayerAlpha`, which allocates an offscreen render target, precisely the
+ * Android cost this work exists to avoid. So every consumer gates on
+ * `scrollLayerUsable(slot, alpha)` and falls back to live drawing during the
+ * reveal morph, the loading/empty crossfade and scrub dimming.
+ * draw/index.ts:218 already gates the grid picture on `reveal >= 1` for
+ * exactly this reason.
  *
  * A second consequence of caching pictures rather than paths: **palette is
  * part of every scroll-layer key**. A picture bakes color, stroke width and
  * gradient stops that a path did not.
  *
  * Kept free of Skia imports (`Picture` is a structural type parameter, exactly
- * like draw/gridLayer.ts) so jest can exercise the key comparison and the `dx`
- * arithmetic with fake picture objects, with no native binding loaded.
+ * like draw/gridLayer.ts) so jest can exercise the key comparison with fake
+ * picture objects, with no native binding loaded.
  */
 
 /**
@@ -61,13 +57,14 @@ export type ScrollLayerKeyRef = string | object | null;
  *
  * The existing caches (lineCache, gridLayer) spell every key dimension out as
  * a named `kFoo` field and compare them field-by-field. That is ideal when one
- * module owns one cache — but this module is shared by three consumers
- * (`lineScroll`, `candleScroll`, `axisScroll`) whose key dimensions barely
- * overlap: the line keys on data revision and spline geometry, candles on the
- * closed-candle revision and candle width, the axis on the tick interval and
- * the visible label set. Named fields would force every new dimension of any
- * consumer to be added to this module, i.e. every consumer would either fork
- * the module or bloat it with fields the other two never read.
+ * module owns one cache — but this module is **designed for N consumers and
+ * currently has exactly 1** (`lineScroll`; `candleScroll` and `axisScroll` are
+ * plausible future ones). Their key dimensions would barely overlap: the line
+ * keys on whether its prefix was rebuilt, candles on the closed-candle
+ * revision and candle width, the axis on the tick interval and the visible
+ * label set. Named fields would force every new dimension of any consumer to
+ * be added to this module, i.e. every consumer would either fork the module or
+ * bloat it with fields the others never read.
  *
  * So the key is a **positional array the consumer pushes into**, and the
  * comparison lives here, written exactly once. A consumer adds a dimension by
@@ -103,20 +100,6 @@ export interface ScrollLayerSlot<Picture> {
    * `LineCacheSlot.prefix` and `GridLayerSlot.picture`. */
   picture: Picture | null;
 
-  /** The time value whose screen X was captured in `xRefAtBuild`. Anything
-   * with a stable identity across the picture's life works — in practice the
-   * time of the layer's leftmost content. */
-  tRef: number;
-  /** `layout.toX(tRef)` evaluated at build time. */
-  xRefAtBuild: number;
-
-  // Per-slot composite clip, in screen coordinates. See invariant 2 above:
-  // slots do NOT share one region.
-  clipX: number;
-  clipY: number;
-  clipW: number;
-  clipH: number;
-
   /** Committed numeric key (the inputs the current `picture` was built from). */
   kNum: number[];
   kNumLen: number;
@@ -136,12 +119,6 @@ export function createScrollLayerSlot<Picture>(): ScrollLayerSlot<Picture> {
   'worklet';
   return {
     picture: null,
-    tRef: 0,
-    xRefAtBuild: 0,
-    clipX: 0,
-    clipY: 0,
-    clipW: 0,
-    clipH: 0,
     kNum: [],
     kNumLen: 0,
     kRef: [],
@@ -163,26 +140,6 @@ export function createScrollLayerSlot<Picture>(): ScrollLayerSlot<Picture> {
 //   scrollLayerCommitKey  →  called by scrollLayerBuilt
 // Keep that ordering if you add anything here.
 
-/**
- * Sets a slot's composite clip region. Split out from the build so a consumer
- * can refresh the region on a layout change without discarding the picture:
- * the clip is applied at composite time and is not baked into the recording,
- * so it is deliberately NOT part of the invalidation key.
- */
-export function setScrollLayerClip<Picture>(
-  slot: ScrollLayerSlot<Picture>,
-  x: number,
-  y: number,
-  w: number,
-  h: number
-): void {
-  'worklet';
-  slot.clipX = x;
-  slot.clipY = y;
-  slot.clipW = w;
-  slot.clipH = h;
-}
-
 /**
  * Starts building this frame's candidate key. Call before any push; every
  * push for the frame must follow, in the same order every frame.
@@ -227,7 +184,7 @@ export function scrollLayerPushRef<Picture>(
  * Read-only — it does not commit. A consumer calls this before doing any
  * expensive work, exactly as `lineCacheHits` is called before building
  * `decimated`/`pts`, and this is the ONE place the comparison is written so
- * the three consumers cannot drift apart.
+ * consumers cannot drift apart.
  *
  * Arity is compared first: a consumer that changed how many dimensions it
  * pushes gets a miss rather than a silent prefix match.
@@ -260,55 +217,29 @@ export function scrollLayerCommitKey<Picture>(
 }
 
 /**
- * Records a completed rebuild: stores the picture, captures the build-time
- * reference `dx` will be measured against, and commits the key.
- *
- * These three are written together on purpose. `picture` is the slot's
- * validity flag, and a picture whose `xRefAtBuild` came from a *different*
- * `toX` than the one that positioned its content would render permanently
- * offset — a bug with no visible symptom until the chart scrolls. Pass
- * `xRefAtBuild` from the same `layout.toX(tRef)` call the recording used.
+ * Records a completed rebuild: stores the picture and commits the key. The
+ * two are written together on purpose — `picture` is the slot's validity
+ * flag, so committing one without the other would leave the slot advertising
+ * a picture it is stale for (or throwing away a good one).
+ *
+ * The slot deliberately keeps no build-time position reference of its own.
+ * The offset the picture is composited at is the consumer's to supply, from
+ * whatever the recording was made from — for today's one consumer that is
+ * `lineScrollDx(lineSlot, layout)` against the line cache slot the prefix
+ * came from, so the picture and the transform cannot disagree.
  */
 export function scrollLayerBuilt<Picture>(
   slot: ScrollLayerSlot<Picture>,
-  picture: Picture,
-  tRef: number,
-  xRefAtBuild: number
+  picture: Picture
 ): void {
   'worklet';
   slot.picture = picture;
-  slot.tRef = tRef;
-  slot.xRefAtBuild = xRefAtBuild;
   scrollLayerCommitKey(slot);
 }
 
-/**
- * Horizontal offset to composite this slot's picture at, in screen pixels.
- *
- * Always recomputed against the build-time reference, **never accumulated**.
- * This is the identical formula lineCache.ts:189 uses, and the reasoning at
- * lineCache.ts:166-175 applies unchanged: right after a fresh build, `tRef`
- * and `xRefAtBuild` come from the very same `layout.toX` this frame, so the
- * subtraction is exactly 0 with no special-casing; on a reused picture it
- * recovers the full horizontal scroll since the build in one subtraction, so
- * per-frame rounding error cannot compound over the thousands of frames a
- * picture may survive.
- *
- * Never rewrite this as `slot.dx += perFrameDelta`. That drifts, and it drifts
- * slowly enough to pass every test and only show up as a visibly misaligned
- * axis after a chart has been left running for minutes.
- */
-export function scrollLayerDx<Picture>(
-  slot: ScrollLayerSlot<Picture>,
-  layout: ChartLayout
-): number {
-  'worklet';
-  return layout.toX(slot.tRef) - slot.xRefAtBuild;
-}
-
 /**
  * True when the slot may be composited this frame: it holds a picture and the
- * composite alpha is exactly 1. See invariant 1 above — `drawPicture` ignores
+ * composite alpha is exactly 1. See the header invariant — `drawPicture` ignores
  * `globalAlpha`, so at alpha < 1 the consumer must fall back to live drawing
  * rather than compositing at the wrong opacity. `>= 1` rather than `=== 1`
  * mirrors draw/index.ts:218's `reveal >= 1`, which tolerates a lerp that
diff --git a/src/draw/timeAxis.ts b/src/draw/timeAxis.ts
index 8867e6f..d1fb156 100644
--- a/src/draw/timeAxis.ts
+++ b/src/draw/timeAxis.ts
@@ -53,6 +53,31 @@ export interface TimeAxisState {
 }
 
 const FADE = 0.08;
+/** Width of the fade-out band at each end of the axis, in px. */
+const FADE_ZONE = 50;
+
+// NOTE: worklet declaration order — these two are hoisted to module scope
+// (rather than being reallocated as closures on every frame) and are therefore
+// declared BEFORE `drawTimeAxis`, which calls them. See the same NOTE at
+// draw/canvas2d.ts.
+
+/** Label opacity as a function of screen x: 1 in the body of the axis, ramping
+ * to 0 across `FADE_ZONE` px at either end. `chartLeft`/`chartRight` are
+ * parameters rather than captured so this can live at module scope. */
+function edgeAlpha(x: number, chartLeft: number, chartRight: number): number {
+  'worklet';
+  const fromEdge = Math.min(x - chartLeft, chartRight - x);
+  if (fromEdge >= FADE_ZONE) return 1;
+  if (fromEdge <= 0) return 0;
+  return fromEdge / FADE_ZONE;
+}
+
+/** Left-to-right label ordering — the overlap resolution below walks the
+ * labels in screen order. */
+function byX(a: TimeLabelEntry, b: TimeLabelEntry): number {
+  'worklet';
+  return a.x - b.x;
+}
 
 export function drawTimeAxis(
   ctx: Ctx2D,
@@ -69,16 +94,6 @@ export function drawTimeAxis(
   const chartLeft = pad.left;
   const chartRight = layout.w - pad.right;
   const chartW = chartRight - chartLeft;
-  const fadeZone = 50;
-
-  const edgeAlpha = (x: number): number => {
-    const fromLeft = x - chartLeft;
-    const fromRight = chartRight - x;
-    const fromEdge = Math.min(fromLeft, fromRight);
-    if (fromEdge >= fadeZone) return 1;
-    if (fromEdge <= 0) return 0;
-    return fromEdge / fadeZone;
-  };
 
   ctx.font = ctx.fonts.label;
 
@@ -159,7 +174,7 @@ export function drawTimeAxis(
   for (const [key, label] of state.labels) {
     const x = toX(key / 100);
     const isTarget = targets.has(key);
-    const target = isTarget ? edgeAlpha(x) : 0;
+    const target = isTarget ? edgeAlpha(x, chartLeft, chartRight) : 0;
     let next = lerp(label.alpha, target, FADE, dt);
     if (Math.abs(next - target) < 0.02) next = target;
     if (next < 0.01 && target === 0 && !isTarget) {
@@ -209,7 +224,7 @@ export function drawTimeAxis(
     poolIdx++;
     labels.push(entry);
   }
-  labels.sort((a, b) => a.x - b.x);
+  labels.sort(byX);
 
   // Resolve overlaps: when two labels collide, keep the higher-alpha one.
   // This gives a clean one-time crossover (no flickering) because one alpha
diff --git a/src/engine/__tests__/constants.test.ts b/src/engine/__tests__/constants.test.ts
new file mode 100644
index 0000000..0d395cd
--- /dev/null
+++ b/src/engine/__tests__/constants.test.ts
@@ -0,0 +1,42 @@
+import {
+  MIN_FRAME_INTERVAL_MS,
+  MAX_SCROLL_EXTRAPOLATION_MS,
+} from '../constants';
+import { observeScrollRate, extrapolateScrollDx } from '../scrollExtrapolate';
+
+/**
+ * The frame-pacing interval and the scroll-extrapolation window interact, and
+ * nothing else in the codebase would fail if a future tuning broke that
+ * relationship: the symptom is judder on 120Hz hardware, which neither jest
+ * nor the simulator can show. These assert the two inequalities documented in
+ * `constants.ts` directly, so the regression is red instead of silent.
+ */
+describe('frame-pacing / extrapolation constants', () => {
+  it('paces frames faster than the extrapolation window (else the transform freezes)', () => {
+    // A vsync skipped by pacing can land up to one pacing interval after the
+    // last recorded frame. If that could exceed the extrapolation window,
+    // `extrapolateScrollDx` would return null on exactly the frames the
+    // high-refresh scroll layer exists for.
+    expect(MIN_FRAME_INTERVAL_MS).toBeLessThan(MAX_SCROLL_EXTRAPOLATION_MS);
+  });
+
+  it('keeps the extrapolation window under twice the pacing interval', () => {
+    // `observeScrollRate`'s stale-gap bound is MAX_SCROLL_EXTRAPOLATION_MS*2;
+    // an ordinary paced interval must sit comfortably inside it.
+    expect(MAX_SCROLL_EXTRAPOLATION_MS).toBeLessThan(MIN_FRAME_INTERVAL_MS * 2);
+  });
+
+  it('a vsync one pacing interval after a record still gets an extrapolated dx', () => {
+    // The inequalities restated as the behaviour they protect, end to end:
+    // observe a rate across a paced interval, then extrapolate across another.
+    const rate = observeScrollRate(0, 0, -1, MIN_FRAME_INTERVAL_MS);
+    expect(rate).not.toBe(0);
+    const dx = extrapolateScrollDx(
+      -1,
+      MIN_FRAME_INTERVAL_MS,
+      rate,
+      MIN_FRAME_INTERVAL_MS * 2
+    );
+    expect(dx).not.toBeNull();
+  });
+});
diff --git a/src/engine/constants.ts b/src/engine/constants.ts
index a0602a5..f194ffa 100644
--- a/src/engine/constants.ts
+++ b/src/engine/constants.ts
@@ -21,12 +21,41 @@ export const LOADING_ALPHA_SPEED = 0.14;
 export const SERIES_TOGGLE_SPEED = 0.1;
 
 // --- Quiescence (skip picture re-recording when provably static) ---
-// ~1.5s of consecutively-settled frames at 60fps — by then every
-// exponential lerp in the engine (smoothValue, range, badge, grid/time-axis
-// label fades, window transitions) has fully converged, so it's safe to
-// start skipping without any visible discontinuity.
+// 90 consecutively-settled *vsyncs* — ~1.5s on a 60Hz display, ~0.75s on a
+// 120Hz one. It counts vsyncs, not recorded frames, because
+// `s.quiescentFrames++` runs BEFORE the frame-pacing gate below. That is
+// fine: the threshold only needs to be long enough that every exponential
+// lerp in the engine (smoothValue, range, badge, grid/time-axis label fades,
+// window transitions) has fully converged, so a shorter wall-clock delay on
+// high-refresh hardware is still comfortably past convergence. Do not
+// re-describe this as "frames at 60fps" — the distinction matters now that
+// the scroll transform runs on the vsyncs pacing skips.
 export const QUIESCENT_FRAME_THRESHOLD = 90;
 
+// ── Frame-pacing / extrapolation relationship (DO NOT TUNE ONE ALONE) ──────
+//
+// MIN_FRAME_INTERVAL_MS and MAX_SCROLL_EXTRAPOLATION_MS are not independent.
+// Two inequalities must hold, and `constants.test.ts` asserts both:
+//
+//   1. MIN_FRAME_INTERVAL_MS < MAX_SCROLL_EXTRAPOLATION_MS
+//      A paced-out vsync asks `extrapolateScrollDx` for a dx at a gap of up
+//      to one pacing interval past the last recorded frame. If the pacing
+//      interval could exceed the extrapolation window, that request returns
+//      null and the transform freezes on exactly the frames the whole
+//      high-refresh scroll feature exists to smooth.
+//
+//   2. MAX_SCROLL_EXTRAPOLATION_MS < MIN_FRAME_INTERVAL_MS * 2
+//      `observeScrollRate` refuses to derive a rate across a gap longer than
+//      `MAX_SCROLL_EXTRAPOLATION_MS * 2`, so that a stall or a quiescence
+//      resume can't bake in a meaningless rate. For an ordinary paced
+//      interval to stay comfortably inside that bound, the window must be
+//      under twice the pacing interval.
+//
+// Today: 15 < 20 < 30. Five milliseconds of slack. Raising
+// MIN_FRAME_INTERVAL_MS to 22 (a plausible "record at 45fps" tuning) breaks
+// (1) and silently reverts the scroll layer to juddering — visible only on
+// 120Hz hardware, which neither jest nor the simulator has.
+
 // --- Frame pacing (cap picture re-recording on high-refresh displays) ---
 // Below the nominal 60fps interval (1000/60 ≈ 16.67ms) on purpose: at
 // exactly 16.67, vsync jitter alone would intermittently trip the gate on
@@ -38,14 +67,11 @@ export const MIN_FRAME_INTERVAL_MS = 15;
 // --- Scroll-transform extrapolation window ---
 // On a vsync that frame pacing skips, the scroll layer's translate is
 // extrapolated from the last two recorded frames rather than recomputed (see
-// EngineState.scrollDxRate). That is only sound across a gap of roughly one
-// paced interval; beyond it the stored rate is stale and extrapolating would
-// fling the layer somewhere it never was. Any longer gap — quiescence
-// resuming, the app returning from background, a JS-thread stall — leaves the
-// transform untouched until the next recorded frame supplies an exact value.
-// 20ms is just over one 60Hz interval, so it covers the intended case (a
-// 120Hz vsync landing ~8ms after a record) with margin for jitter, and
-// nothing else.
+// engine/scrollExtrapolate.ts, which owns the full rationale). Any gap longer
+// than this leaves the transform untouched until the next recorded frame
+// supplies an exact value. 20ms is just over one 60Hz interval, so it covers
+// the intended case (a 120Hz vsync landing ~8ms after a record) with margin
+// for jitter, and nothing else — see the relationship block above.
 export const MAX_SCROLL_EXTRAPOLATION_MS = 20;
 
 // --- Candle-specific constants ---
diff --git a/src/engine/lineScrollLayer.ts b/src/engine/lineScrollLayer.ts
index 7b3ae54..bbb3487 100644
--- a/src/engine/lineScrollLayer.ts
+++ b/src/engine/lineScrollLayer.ts
@@ -33,14 +33,10 @@ import { writeLineScrollKey } from '../draw/lineScrollLayer';
  *
  * ## Why the clip is baked in, not applied at composite time
  *
- * `draw/scrollLayer.ts`'s invariant 2 has each slot clip to its own region
- * *at composite time*, because its intended consumer composites with
- * `ctx.clipRect` + `ctx.translate` + `ctx.drawPicture`. This consumer does
- * not: it composites through a Skia `<Group transform>` node in the
- * declarative tree, which applies a matrix and nothing else, and adding a
- * clip there would mean another node whose rect changes with layout. So the
- * clip is recorded into the picture, in build-time coordinates, and
- * `slot.clipX..clipH` stay unused (`setScrollLayerClip` is never called).
+ * The composite is a Skia `<Group transform>` node in the declarative tree,
+ * which applies a matrix and nothing else; clipping there would mean another
+ * node whose rect changes with layout. So `drawLine`'s clip is recorded into
+ * the picture instead, in build-time coordinates.
  *
  * That is sound here specifically because the layer only ever moves
  * *horizontally*:
@@ -103,13 +99,9 @@ export function updateLineScrollLayer(
   // alpha 1 in the unblended `palette.line`.
   strokeLinePath(subCtx, palette, prefix, 1);
 
-  // `tRef`/`xRefAtBuild` are taken straight from the line cache slot rather
-  // than recomputed, so `scrollLayerDx` and `lineScrollDx` agree by
-  // construction (see the note on `lineScrollDx`).
-  scrollLayerBuilt(
-    slot,
-    recorder.finishRecordingAsPicture(),
-    lineSlot.tRef,
-    lineSlot.xRefAtBuild
-  );
+  // No position reference is stored on the slot: the picture is a rendering
+  // of `lineSlot.prefix`, so the caller translates it with
+  // `lineScrollDx(lineSlot, layout)` — the same number `assembleLineTail`
+  // offsets the path by, so the two cannot disagree.
+  scrollLayerBuilt(slot, recorder.finishRecordingAsPicture());
 }
diff --git a/src/engine/state.ts b/src/engine/state.ts
index 36a3442..2612efc 100644
--- a/src/engine/state.ts
+++ b/src/engine/state.ts
@@ -141,22 +141,15 @@ export interface EngineState {
    * sub-recording — same reasoning as `gridLayerCache` above. */
   lineScrollCache: SkiaCache;
 
-  // --- Scroll-transform extrapolation (see useLivelineEngine's frame
-  // callback). Picture re-recording is paced to ~60fps, but translating an
-  // already-recorded picture is nearly free, so the scroll transform is
-  // allowed to update on every vsync — 120fps on a ProMotion display. On a
-  // vsync that the pacing gate skips there is no `layout` (it is computed
-  // inside engineStep), so `dx` cannot be recomputed; it is linearly
-  // extrapolated from the last two *recorded* frames instead.
-  //
-  // Extrapolating the observed motion, rather than recomputing from
-  // windowSecs/chartW, is deliberate: it needs no copy of the engine's
-  // time-advance rules, so it cannot drift out of sync with them, and it
-  // handles pause, window transitions and time-debt catch-up for free —
-  // whatever the chart actually did over the last interval is what it is
-  // assumed to keep doing for the next few milliseconds. Every recorded
-  // frame overwrites the extrapolation with the exact value, so error can
-  // never accumulate across more than one skipped vsync.
+  // --- Scroll-transform extrapolation. On a vsync the frame-pacing gate
+  // skips, the scroll layer's translate is extrapolated from the last two
+  // recorded frames instead of recomputed. Full rationale in
+  // engine/scrollExtrapolate.ts, which owns it.
+  /** Whether the last recorded frame published a scroll picture — i.e.
+   * whether there is anything for the extrapolated transform to move. Set
+   * from `result.scrollPicture !== null`, where the answer is already
+   * known. */
+  scrollActive: boolean;
   /** dx at the last recorded frame. */
   scrollDxLast: number;
   /** Timestamp (ms) of the last recorded frame; -1 before the first. */
@@ -334,6 +327,7 @@ export function createEngineState(
     gridLayerCache: createSkiaCache(),
     lineScroll: createScrollLayerSlot<SkPicture>(),
     lineScrollCache: createSkiaCache(),
+    scrollActive: false,
     scrollDxLast: 0,
     scrollDxLastT: -1,
     scrollDxRate: 0,
diff --git a/src/engine/step.ts b/src/engine/step.ts
index 136ebf6..6ecbc5a 100644
--- a/src/engine/step.ts
+++ b/src/engine/step.ts
@@ -29,9 +29,9 @@ import type { EngineState } from './state';
 import { drawBadge } from './badge';
 import { updateGridLayer } from './gridLayer';
 import { updateLineScrollLayer } from './lineScrollLayer';
-import { lineCacheHits } from '../draw/lineCache';
-import { lineScrollLayerAlpha } from '../draw/lineScrollLayer';
-import { scrollLayerDx, scrollLayerUsable } from '../draw/scrollLayer';
+import { lineCacheHits, lineScrollDx } from '../draw/lineCache';
+import { canCompositeLineScroll } from '../draw/lineScrollLayer';
+import { scrollLayerUsable } from '../draw/scrollLayer';
 import {
   computeAdaptiveSpeed,
   updateWindowTransition,
@@ -1733,7 +1733,7 @@ export function engineStep(
     //
     // On frames where the prefix provably hasn't changed (a `lineCacheHits`
     // hit) and the whole line pipeline is at full opacity and untransformed
-    // (`lineScrollLayerAlpha`), the prefix is composited from an SkPicture
+    // (`canCompositeLineScroll`), the prefix is composited from an SkPicture
     // under a `<Group transform>` and `drawLine` strokes only the tail. Any
     // other frame draws the line exactly as before, whole, and publishes an
     // empty scroll layer — the same both-branches shape the grid picture
@@ -1747,14 +1747,14 @@ export function engineStep(
     // which is the value `drawFrame`'s own translate will use this frame.
     const dataSource = dataSourceOf(useStash, s.pausedData !== null);
     const visLastPoint = visible[visible.length - 1]!;
-    const layerAlpha = lineScrollLayerAlpha(
+    const canComposite = canCompositeLineScroll(
       chartReveal,
       s.scrubAmount,
       cfg.degenOptions ? s.shakeState.amplitude : 0
     );
     let splitPrefixStroke = false;
     if (
-      layerAlpha >= 1 &&
+      canComposite &&
       lineCacheHits(
         s.lineCache,
         layout,
@@ -1774,11 +1774,16 @@ export function engineStep(
         s.lineScrollCache,
         fonts
       );
-      splitPrefixStroke = scrollLayerUsable(s.lineScroll, layerAlpha);
+      // `canComposite` is already true inside this branch, so the alpha
+      // argument is 1; `scrollLayerUsable` keeps its alpha-1 contract for a
+      // future consumer that genuinely is alpha-driven.
+      splitPrefixStroke = scrollLayerUsable(s.lineScroll, 1);
     }
     if (splitPrefixStroke) {
       out.scrollPicture = s.lineScroll.picture;
-      out.scrollDx = scrollLayerDx(s.lineScroll, layout);
+      // Same dx the cached prefix path is offset by — the picture IS that
+      // path, rendered (see draw/lineCache.ts's `lineScrollDx`).
+      out.scrollDx = lineScrollDx(s.lineCache, layout);
     }
 
     // Draw canvas content (everything except badge)
diff --git a/src/useLivelineEngine.ts b/src/useLivelineEngine.ts
index d48f737..7b1baed 100644
--- a/src/useLivelineEngine.ts
+++ b/src/useLivelineEngine.ts
@@ -402,25 +402,48 @@ export function useLivelineEngine(
   const hoverX = useSharedValue<number | null>(null);
   const screenPicture = useSharedValue<SkPicture>(makeEmptyPicture());
   // The 1×1 do-nothing picture the scroll layer falls back to on every frame
-  // that can't composite it (see StepOutput.scrollPicture). Held in its own
-  // shared value rather than captured from render scope so the frame worklet
-  // reaches it by exactly the same route as any other shared value.
+  // that can't composite it (see StepOutput.scrollPicture) — and also its
+  // initial value, so there is exactly ONE empty picture. Two distinct ones
+  // would make `scrollPicture.value !== emptyPicture.value` read true before
+  // the first recorded frame, i.e. claim a live scroll layer while nothing
+  // is compositing. Liveness is `EngineState.scrollActive` instead, which the
+  // recorded frame sets from an answer it already has.
   const emptyPicture = useSharedValue<SkPicture>(makeEmptyPicture());
   // The scroll layer — the single-series line's prefix stroke, recorded once
   // per line-cache miss by engine/lineScrollLayer.ts and translated by
   // `scrollTransform`. Starts (and, in the multi-series and candle
   // pipelines, stays) the empty placeholder, which draws nothing.
-  const scrollPicture = useSharedValue<SkPicture>(makeEmptyPicture());
-  // `[{ translateX: dx }]`, reassigned by the frame callback below (a shared
-  // value only notifies its mapper on assignment, so this can't be mutated
-  // in place).
+  const scrollPicture = useSharedValue<SkPicture>(emptyPicture.value);
+  // `[{ translateX: dx }]` — the current transform, always one of the three
+  // buffers in `scrollTransformBufs` below.
   const scrollTransform = useSharedValue<Transforms3d>([{ translateX: 0 }]);
-  // Last dx pushed into `scrollTransform`, so the frame callback can skip the
-  // reassignment (and the array/object allocation it needs) when the offset
-  // hasn't moved. `Transform3d` is a union of single-key objects, so reading
-  // the current translateX back out of `scrollTransform.value` isn't
-  // type-safe; mirroring the scalar here is.
-  const scrollDx = useSharedValue(0);
+  // Preallocated transform buffers, rotated through by `pushScrollDx` below.
+  //
+  // A shared value only notifies its mapper when it is REASSIGNED, never when
+  // its contents are mutated — so `scrollTransform.value = [{ translateX: dx }]`
+  // was the obvious shape, and it allocates an array AND an object on every
+  // assignment: up to 120 assignments/sec on a ProMotion display, 240
+  // short-lived allocations/sec on the UI thread, in a library whose entire
+  // point is to allocate nothing per frame. Guarding on `dx` changing doesn't
+  // help; dx is a continuously varying float, so the guard essentially never
+  // fires while the chart scrolls.
+  //
+  // Rotating through a fixed ring gives both properties at once: the object
+  // identity changes on every assignment (so the mapper always sees a change)
+  // while steady-state allocation is exactly zero. Three slots rather than
+  // two gives two frames of separation before a buffer is reused, so a
+  // consumer still holding last frame's array can't observe it mutate.
+  //
+  // Rejected alternatives: `useDerivedValue` allocates the same array inside
+  // the derivation instead of outside it, and self-assignment
+  // (`x.value = x.value` after mutating) is not a notification contract
+  // Reanimated documents or honors.
+  const scrollTransformBufs = useSharedValue<Transforms3d[]>([
+    [{ translateX: 0 }],
+    [{ translateX: 0 }],
+    [{ translateX: 0 }],
+  ]);
+  const scrollBufIdx = useSharedValue(0);
   const valueText = useSharedValue('');
   const valueColor = useSharedValue('');
 
@@ -516,10 +539,10 @@ export function useLivelineEngine(
       //
       // `dx` cannot be recomputed here — it needs `layout`, which lives
       // inside engineStep — so it is extrapolated from the last two recorded
-      // frames (see EngineState.scrollDxRate). Guarded three ways: only when
-      // a scroll layer is actually compositing, only when a rate has been
-      // observed, and only across a gap short enough for that rate to still
-      // be true (MAX_SCROLL_EXTRAPOLATION_MS).
+      // frames (see engine/scrollExtrapolate.ts). Guarded three ways: only
+      // when a scroll layer is actually compositing, only when a rate has
+      // been observed, and only across a gap short enough for that rate to
+      // still be true (MAX_SCROLL_EXTRAPOLATION_MS).
       //
       // Known consequence: the prefix now moves at 120Hz while the tail is
       // re-recorded at 60Hz, so on skipped vsyncs they shear by one frame of
@@ -527,16 +550,22 @@ export function useLivelineEngine(
       // window and ~0.08px on 30s. Sub-pixel, but it is a shimmer at the
       // join rather than a clean offset. Verify on real 120Hz hardware; the
       // simulator renders at 60 and cannot show this either way.
-      if (scrollPicture.value !== emptyPicture.value) {
+      if (s.scrollActive) {
         const dxEx = extrapolateScrollDx(
           s.scrollDxLast,
           s.scrollDxLastT,
           s.scrollDxRate,
           now_ms
         );
-        if (dxEx !== null && scrollDx.value !== dxEx) {
-          scrollDx.value = dxEx;
-          scrollTransform.value = [{ translateX: dxEx }];
+        if (dxEx !== null) {
+          // Rotate to the next preallocated buffer, mutate it, then assign:
+          // a fresh identity for the mapper with no allocation. See
+          // `scrollTransformBufs`.
+          const i = (scrollBufIdx.value + 1) % 3;
+          scrollBufIdx.value = i;
+          const buf = scrollTransformBufs.value[i]!;
+          (buf[0] as { translateX: number }).translateX = dxEx;
+          scrollTransform.value = buf;
         }
       }
       return;
@@ -575,14 +604,16 @@ export function useLivelineEngine(
     // reassigned, or every frame would look like a change to the mapper.
     const nextScroll = result.scrollPicture ?? emptyPicture.value;
     if (scrollPicture.value !== nextScroll) scrollPicture.value = nextScroll;
+    // Whether a scroll layer is live this frame, recorded where the answer is
+    // already known — the paced-out branch above reads it instead of
+    // comparing two picture shared values (two JSI reads per vsync, and wrong
+    // before the first recorded frame if the placeholders weren't identical).
+    s.scrollActive = result.scrollPicture !== null;
     const dx = result.scrollDx;
     // Observed dx-per-ms across the last two RECORDED frames, used to
-    // extrapolate the transform on paced-out vsyncs above. Derived from what
-    // the chart actually did rather than from windowSecs/chartW, so pause,
-    // window transitions and time-debt catch-up need no special cases. Only
-    // updated across a gap short enough to be a real paced interval —
-    // otherwise a quiescence or background gap would divide a large dx change
-    // by a large dt and bake in a meaningless rate.
+    // extrapolate the transform on paced-out vsyncs above — see
+    // engine/scrollExtrapolate.ts for why the rate is observed rather than
+    // derived, and for the guards.
     s.scrollDxRate = observeScrollRate(
       s.scrollDxLast,
       s.scrollDxLastT,
@@ -592,11 +623,13 @@ export function useLivelineEngine(
     s.scrollDxLast = dx;
     s.scrollDxLastT = now_ms;
     // Exact value always wins over whatever a skipped vsync extrapolated, so
-    // extrapolation error can never accumulate past one frame.
-    if (scrollDx.value !== dx) {
-      scrollDx.value = dx;
-      scrollTransform.value = [{ translateX: dx }];
-    }
+    // extrapolation error can never accumulate past one frame. Same
+    // rotate-mutate-assign as the paced-out branch above.
+    const bufIdx = (scrollBufIdx.value + 1) % 3;
+    scrollBufIdx.value = bufIdx;
+    const buf = scrollTransformBufs.value[bufIdx]!;
+    (buf[0] as { translateX: number }).translateX = dx;
+    scrollTransform.value = buf;
     s.lastRecordedW = w;
     s.lastRecordedH = h;
     s.lastFrameTimestamp = now_ms;

From 788d261b7f432a7be2d7c9cf8b9224aaeeef8f8c Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Sat, 1 Aug 2026 13:23:36 -0400
Subject: [PATCH 16/37] docs(changelog): record the high-refresh scroll
 transform
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Unreleased section predated 33c23cb and 8e674cb. Adds the full-refresh
scroll transform and the coupled frame-timing constants, including the
unverified 120Hz-prefix-vs-60Hz-tail shear — the simulator renders at 60Hz and
cannot show it, so it is recorded as an open question rather than a claim.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 79adec9..aa19da0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -52,6 +52,24 @@ All notable changes to this project will be documented in this file.
   isolation, and undetectable on device (the whole time axis is 4.2% of a
   core).
 
+- **The scroll layer's transform now runs at the display's full refresh
+  rate.** Picture re-recording stays paced at ~60fps, but translating an
+  already-recorded picture is nearly free, so the `<Group transform>` advances
+  on every vsync — 120fps on a ProMotion display — while recording cost is
+  unchanged. On a vsync that pacing skips there is no layout to recompute `dx`
+  from, so it is linearly extrapolated from the last two recorded frames and
+  overwritten with the exact value on the next one; a quiescence resume, a
+  return from background or a JS stall leaves the transform untouched rather
+  than flinging it. Note the consequence: the prefix moves at 120Hz while the
+  tail is re-recorded at 60Hz, so on skipped vsyncs they shear by one frame of
+  scroll — roughly 0.25px on a 10s window, 0.08px on 30s. Sub-pixel, but
+  unverified: the iOS simulator renders at 60Hz and cannot show it either way.
+- **`MIN_FRAME_INTERVAL_MS` and `MAX_SCROLL_EXTRAPOLATION_MS` are coupled** by
+  two inequalities that are now documented in `engine/constants.ts` and
+  asserted in `engine/__tests__/constants.test.ts`. Tuning either alone can
+  silently disable high-refresh scrolling in a way only 120Hz hardware would
+  reveal.
+
 ### Removed
 
 - **`src/draw/timeAxisLayer.ts` and its tests** — pure label-selection logic

From 4f80363f628d4565875d976880329b380526cdd6 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Sat, 1 Aug 2026 13:38:22 -0400
Subject: [PATCH 17/37] chore(lint): ignore .claude/ agent worktrees
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`yarn lint` was reporting 14 errors from files under .claude/worktrees/ —
full repo copies that are not in the working tree. Same trap already fixed for
jest via modulePathIgnorePatterns; git excludes the path via .git/info/exclude.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 eslint.config.mjs | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/eslint.config.mjs b/eslint.config.mjs
index 16b00bb..80ab553 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -24,6 +24,10 @@ export default defineConfig([
     },
   },
   {
-    ignores: ['node_modules/', 'lib/'],
+    // `.claude/` holds agent worktrees, each a full copy of the repo. Without
+    // this, `yarn lint` reports errors from files that are not in the working
+    // tree at all — the same trap `jest.modulePathIgnorePatterns` covers in
+    // package.json. Git already excludes the path via .git/info/exclude.
+    ignores: ['node_modules/', 'lib/', '.claude/'],
   },
 ]);

From 5767ff3ad50e7f5f8e8f3f8ea7664df4b28e3735 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Sat, 1 Aug 2026 13:38:22 -0400
Subject: [PATCH 18/37] refactor(Liveline): extract PillBar; drop the file-wide
 inline-styles disable
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PLAN_MAINT #7. The three control bars (window pills, mode toggle, series
chips) each repeated the same bar chrome and SlidingIndicator wiring.

- <PillBar> owns the shared chrome and the indicator gate.
- useBarStyle(ws, isDark) memoizes the seven style scalars that were being
  recomputed inline on every render — and a live chart re-renders every tick.
- useChipStyle is deliberately separate: chips also branch on
  seriesToggleCompact, which the other two bars know nothing about.

The file-level `eslint-disable react-native/no-inline-styles` is now gone
entirely rather than narrowed.

Deliberately NOT unified: the series bar has no indicator (chips toggle
independently, there is no single active one), and per-button onLayout wiring
stays at the call sites because the two bars key their layout maps differently
(number secs vs string mode) — pulling that in would have needed a render-prop
API costing more coupling than the duplication did.

The <Canvas> subtree is untouched — verified, zero hunks in that region. Its
node structure must stay fixed or the blocked-JS-thread guarantee is lost.

Verified by a style-parity check across all 12 combinations of windowStyle x
theme x seriesToggleCompact, each crossed with active/inactive, hidden/visible
and multi/non-multi, flattened the way RN flattens a style array: all
identical. Not visually verified — repointing Metro would have disturbed four
concurrent agents, and screenshotting the primary checkout would have shown
unmodified code and proved nothing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/Liveline.tsx | 342 +++++++++++++++++++++++++++++------------------
 1 file changed, 209 insertions(+), 133 deletions(-)

diff --git a/src/Liveline.tsx b/src/Liveline.tsx
index bb8c035..4f4bca6 100644
--- a/src/Liveline.tsx
+++ b/src/Liveline.tsx
@@ -1,5 +1,12 @@
-/* eslint-disable react-native/no-inline-styles -- control styles are theme/prop-derived */
-import { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import {
+  memo,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
 import {
   Platform,
   Pressable,
@@ -88,23 +95,163 @@ function SlidingIndicator({
     opacity: ready.value,
   }));
 
-  const inset = rounded ? 3 : 2;
+  const chrome = useMemo(() => {
+    const inset = rounded ? 3 : 2;
+    return {
+      top: inset,
+      bottom: inset,
+      borderRadius: rounded ? 999 : 4,
+      backgroundColor: isDark ? 'rgba(255,255,255,0.06)' : 'rgba(0,0,0,0.035)',
+    };
+  }, [rounded, isDark]);
+
   return (
     <Animated.View
       pointerEvents="none"
-      style={[
-        styles.indicator,
-        {
-          top: inset,
-          bottom: inset,
-          borderRadius: rounded ? 999 : 4,
-          backgroundColor: isDark
+      style={[styles.indicator, chrome, animStyle]}
+    />
+  );
+}
+
+type WindowStyle = NonNullable<LivelineProps['windowStyle']>;
+
+/**
+ * The style scalars every control bar shares, derived from `windowStyle` and
+ * the theme. Memoized on those two inputs so the style objects handed to the
+ * bars are referentially stable across renders (a live chart re-renders on
+ * every tick; these do not change with it).
+ */
+function useBarStyle(ws: WindowStyle, isDark: boolean) {
+  return useMemo(() => {
+    const isText = ws === 'text';
+    const isRounded = ws === 'rounded';
+    const activeColor = isDark ? 'rgba(255,255,255,0.7)' : 'rgba(0,0,0,0.55)';
+    const inactiveColor = isDark
+      ? 'rgba(255,255,255,0.25)'
+      : 'rgba(0,0,0,0.22)';
+    const btnRadius = isRounded ? 999 : 4;
+    return {
+      isText,
+      isRounded,
+      activeColor,
+      inactiveColor,
+      btnRadius,
+      /** The computed half of the bar `<View>` style (see `styles.bar`). */
+      chrome: {
+        gap: isText ? 4 : 2,
+        backgroundColor: isText
+          ? 'transparent'
+          : isDark
+            ? 'rgba(255,255,255,0.03)'
+            : 'rgba(0,0,0,0.02)',
+        borderRadius: isRounded ? 999 : 6,
+        padding: isText ? 0 : isRounded ? 3 : 2,
+      },
+      /** Window-selector pill hit area. */
+      pill: {
+        paddingVertical: isText ? 2 : 3,
+        paddingHorizontal: isText ? 6 : 10,
+        borderRadius: btnRadius,
+      },
+      /** Mode-toggle icon button (pairs with `styles.iconBtn`). */
+      iconBtn: { borderRadius: btnRadius },
+      labelActive: {
+        fontSize: 11,
+        lineHeight: 16,
+        fontWeight: '600' as const,
+        color: activeColor,
+      },
+      labelInactive: {
+        fontSize: 11,
+        lineHeight: 16,
+        fontWeight: '400' as const,
+        color: inactiveColor,
+      },
+    };
+  }, [ws, isDark]);
+}
+
+type BarStyle = ReturnType<typeof useBarStyle>;
+
+/**
+ * Series-chip styles. Separate from `useBarStyle` because they additionally
+ * branch on `seriesToggleCompact`, which the other two bars know nothing about.
+ */
+function useChipStyle(bar: BarStyle, isDark: boolean, compact: boolean) {
+  return useMemo(() => {
+    const { isText, btnRadius, activeColor, inactiveColor } = bar;
+    const labelBase = {
+      fontSize: 11,
+      lineHeight: 16,
+      fontWeight: '500' as const,
+    };
+    return {
+      base: {
+        paddingVertical: compact ? (isText ? 2 : 5) : isText ? 2 : 3,
+        paddingHorizontal: compact ? (isText ? 4 : 7) : isText ? 6 : 8,
+        borderRadius: btnRadius,
+        flexDirection: 'row' as const,
+        alignItems: 'center' as const,
+        gap: compact ? 0 : 4,
+        backgroundColor: isText
+          ? 'transparent'
+          : isDark
             ? 'rgba(255,255,255,0.06)'
             : 'rgba(0,0,0,0.035)',
-        },
-        animStyle,
-      ]}
-    />
+      },
+      /** Applied on top of `base` for a toggled-off series. */
+      off: { backgroundColor: 'transparent', opacity: 0.4 },
+      dot: {
+        width: compact ? 8 : 6,
+        height: compact ? 8 : 6,
+        borderRadius: 999,
+      },
+      label: { ...labelBase, color: activeColor },
+      labelOff: { ...labelBase, color: inactiveColor },
+    };
+  }, [bar, isDark, compact]);
+}
+
+/**
+ * The chrome shared by all three control bars: a self-sizing row with the
+ * theme/`windowStyle`-derived background, radius, padding and gap, optionally
+ * hosting the sliding indicator that tracks the active button.
+ *
+ * Note this lives entirely *above* the `<Canvas>` — see the comment on the
+ * Skia subtree below, whose node structure must stay fixed.
+ */
+function PillBar({
+  bar,
+  isDark,
+  indicator = false,
+  indicatorLayout,
+  faded = false,
+  children,
+}: {
+  bar: BarStyle;
+  isDark: boolean;
+  /** Render a sliding indicator behind the active button. */
+  indicator?: boolean;
+  /** Layout of the currently active button; `undefined` until first measured. */
+  indicatorLayout?: BtnLayout;
+  /** Keep the bar mounted but invisible and untappable. */
+  faded?: boolean;
+  children: ReactNode;
+}) {
+  return (
+    <View
+      pointerEvents={faded ? 'none' : 'auto'}
+      style={[styles.bar, bar.chrome, faded && styles.barFaded]}
+    >
+      {indicator && !bar.isText && (
+        <SlidingIndicator
+          layout={indicatorLayout}
+          rounded={bar.isRounded}
+          isDark={isDark}
+        />
+      )}
+      {children}
+    </View>
   );
 }
 
@@ -355,18 +502,8 @@ export const Liveline = memo(function LivelineComponent({
         : defaultValueColor,
   }));
 
-  const activeColor = isDark ? 'rgba(255,255,255,0.7)' : 'rgba(0,0,0,0.55)';
-  const inactiveColor = isDark ? 'rgba(255,255,255,0.25)' : 'rgba(0,0,0,0.22)';
-  const barBg =
-    ws === 'text'
-      ? 'transparent'
-      : isDark
-        ? 'rgba(255,255,255,0.03)'
-        : 'rgba(0,0,0,0.02)';
-  const barRadius = ws === 'rounded' ? 999 : 6;
-  const barPadding = ws === 'text' ? 0 : ws === 'rounded' ? 3 : 2;
-  const barGap = ws === 'text' ? 4 : 2;
-  const btnRadius = ws === 'rounded' ? 999 : 4;
+  const bar = useBarStyle(ws, isDark);
+  const chip = useChipStyle(bar, isDark, seriesToggleCompact);
 
   const activeMode = lineMode ? 'line' : 'candle';
 
@@ -409,24 +546,12 @@ export const Liveline = memo(function LivelineComponent({
         <View style={[styles.controlsRow, { marginLeft: pad.left }]}>
           {/* Time window controls */}
           {windows && windows.length > 0 && (
-            <View
-              style={[
-                styles.bar,
-                {
-                  gap: barGap,
-                  backgroundColor: barBg,
-                  borderRadius: barRadius,
-                  padding: barPadding,
-                },
-              ]}
+            <PillBar
+              bar={bar}
+              isDark={isDark}
+              indicator
+              indicatorLayout={windowBtnLayouts[activeWindowSecs]}
             >
-              {ws !== 'text' && (
-                <SlidingIndicator
-                  layout={windowBtnLayouts[activeWindowSecs]}
-                  rounded={ws === 'rounded'}
-                  isDark={isDark}
-                />
-              )}
               {windows.map((w) => {
                 const isActive = w.secs === activeWindowSecs;
                 return (
@@ -437,85 +562,64 @@ export const Liveline = memo(function LivelineComponent({
                       setActiveWindowSecs(w.secs);
                       onWindowChange?.(w.secs);
                     }}
-                    style={{
-                      paddingVertical: ws === 'text' ? 2 : 3,
-                      paddingHorizontal: ws === 'text' ? 6 : 10,
-                      borderRadius: btnRadius,
-                    }}
+                    style={bar.pill}
                   >
                     <Animated.Text
-                      style={{
-                        fontSize: 11,
-                        lineHeight: 16,
-                        fontWeight: isActive ? '600' : '400',
-                        color: isActive ? activeColor : inactiveColor,
-                      }}
+                      style={isActive ? bar.labelActive : bar.labelInactive}
                     >
                       {w.label}
                     </Animated.Text>
                   </Pressable>
                 );
               })}
-            </View>
+            </PillBar>
           )}
 
           {/* Mode toggle — separate bar with its own sliding indicator */}
           {onModeChange && (
-            <View
-              style={[
-                styles.bar,
-                {
-                  gap: barGap,
-                  backgroundColor: barBg,
-                  borderRadius: barRadius,
-                  padding: barPadding,
-                },
-              ]}
+            <PillBar
+              bar={bar}
+              isDark={isDark}
+              indicator
+              indicatorLayout={modeBtnLayouts[activeMode]}
             >
-              {ws !== 'text' && (
-                <SlidingIndicator
-                  layout={modeBtnLayouts[activeMode]}
-                  rounded={ws === 'rounded'}
-                  isDark={isDark}
-                />
-              )}
               <Pressable
                 onLayout={(e) => onModeBtnLayout('line', e)}
                 onPress={() => onModeChange('line')}
-                style={[styles.iconBtn, { borderRadius: btnRadius }]}
+                style={[styles.iconBtn, bar.iconBtn]}
               >
                 <LineIcon
-                  color={activeMode === 'line' ? activeColor : inactiveColor}
+                  color={
+                    activeMode === 'line' ? bar.activeColor : bar.inactiveColor
+                  }
                   active={activeMode === 'line'}
                 />
               </Pressable>
               <Pressable
                 onLayout={(e) => onModeBtnLayout('candle', e)}
                 onPress={() => onModeChange('candle')}
-                style={[styles.iconBtn, { borderRadius: btnRadius }]}
+                style={[styles.iconBtn, bar.iconBtn]}
               >
                 <CandleIcon
-                  color={activeMode === 'candle' ? activeColor : inactiveColor}
+                  color={
+                    activeMode === 'candle'
+                      ? bar.activeColor
+                      : bar.inactiveColor
+                  }
                 />
               </Pressable>
-            </View>
+            </PillBar>
           )}
 
-          {/* Series toggle chips */}
+          {/*
+            Series toggle chips. No sliding indicator — chips toggle
+            independently, so there is no single "active" one to track.
+            Rendered from lastSeriesPropRef (not seriesProp) and merely faded
+            out when the chart leaves multi-series mode: unmounting the bar
+            would reflow the controls row and drop the hidden-series state.
+          */}
           {showSeriesToggle && (
-            <View
-              pointerEvents={isMultiSeries ? 'auto' : 'none'}
-              style={[
-                styles.bar,
-                {
-                  gap: barGap,
-                  backgroundColor: barBg,
-                  borderRadius: barRadius,
-                  padding: barPadding,
-                  opacity: isMultiSeries ? 1 : 0,
-                },
-              ]}
-            >
+            <PillBar bar={bar} isDark={isDark} faded={!isMultiSeries}>
               {(lastSeriesPropRef.current ?? []).map((s, si) => {
                 const isHidden = hiddenSeries.has(s.id);
                 const seriesColor =
@@ -524,52 +628,18 @@ export const Liveline = memo(function LivelineComponent({
                   <Pressable
                     key={s.id}
                     onPress={() => handleSeriesToggle(s.id)}
-                    style={{
-                      paddingVertical: seriesToggleCompact
-                        ? ws === 'text'
-                          ? 2
-                          : 5
-                        : ws === 'text'
-                          ? 2
-                          : 3,
-                      paddingHorizontal: seriesToggleCompact
-                        ? ws === 'text'
-                          ? 4
-                          : 7
-                        : ws === 'text'
-                          ? 6
-                          : 8,
-                      borderRadius: btnRadius,
-                      backgroundColor: isHidden
-                        ? 'transparent'
-                        : ws === 'text'
-                          ? 'transparent'
-                          : isDark
-                            ? 'rgba(255,255,255,0.06)'
-                            : 'rgba(0,0,0,0.035)',
-                      opacity: isHidden ? 0.4 : 1,
-                      flexDirection: 'row',
-                      alignItems: 'center',
-                      gap: seriesToggleCompact ? 0 : 4,
-                    }}
+                    style={[chip.base, isHidden && chip.off]}
                   >
                     <View
-                      style={{
-                        width: seriesToggleCompact ? 8 : 6,
-                        height: seriesToggleCompact ? 8 : 6,
-                        borderRadius: 999,
-                        backgroundColor: seriesColor,
-                        opacity: isHidden ? 0.4 : 1,
-                      }}
+                      style={[
+                        chip.dot,
+                        { backgroundColor: seriesColor },
+                        isHidden && styles.dimmed,
+                      ]}
                     />
                     {!seriesToggleCompact && (
                       <Animated.Text
-                        style={{
-                          fontSize: 11,
-                          lineHeight: 16,
-                          fontWeight: '500',
-                          color: isHidden ? inactiveColor : activeColor,
-                        }}
+                        style={isHidden ? chip.labelOff : chip.label}
                       >
                         {s.label ?? s.id}
                       </Animated.Text>
@@ -577,7 +647,7 @@ export const Liveline = memo(function LivelineComponent({
                   </Pressable>
                 );
               })}
-            </View>
+            </PillBar>
           )}
         </View>
       )}
@@ -646,6 +716,12 @@ const styles = StyleSheet.create({
     flexDirection: 'row',
     alignSelf: 'flex-start',
   },
+  barFaded: {
+    opacity: 0,
+  },
+  dimmed: {
+    opacity: 0.4,
+  },
   indicator: {
     position: 'absolute',
   },

From 37da8e3443052d6ae78dd763d20abb0cd3cd80d6 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Sat, 1 Aug 2026 13:38:22 -0400
Subject: [PATCH 19/37] refactor(draw): unify the two cache modules' layout key
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PLAN_MAINT #5. lineCache and candleCache declared overlapping invalidation-key
fields under inconsistent names — kMin/kMax vs kMinVal/kMaxVal for the same
layout.minVal/maxVal. Seven common fields now live in a shared LayoutKey in
pathCache.ts, which already held the precedent (CachePath, ensured).

Allocation-free property preserved and documented: the key object is allocated
once per slot in createXCacheSlot, writeLayoutKey mutates in place on the miss
branch only, and layoutKeyMatches is seven direct === compares with no array,
loop or temporary. A docblock warns against "generalizing" it into a
field-name array — this runs 60-120x/sec on the UI thread.

pathCache.ts stays Skia-free via a structural KeyedLayout subset rather than
importing ChartLayout, mirroring the CachePath precedent, so jest can still
exercise cache logic with fake path recorders.

kDataSource stays per-slot: the doc counted it among the common fields, but it
is not derivable from layout so writeLayoutKey(key, layout) cannot write it.
buildRev semantics untouched, so lineScrollLayer's contract is unchanged.

Zero test edits needed — neither cache test ever referenced a k* field by
name; they drive the public functions and assert on recorded path ops.

Follow-up: draw/gridLayer.ts has a third slot with the same shape and would
fold in cleanly.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/draw/candleCache.ts |  54 +++++++++------------
 src/draw/lineCache.ts   |  58 +++++++++-------------
 src/draw/pathCache.ts   | 104 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 149 insertions(+), 67 deletions(-)

diff --git a/src/draw/candleCache.ts b/src/draw/candleCache.ts
index 2fba3de..4ae4350 100644
--- a/src/draw/candleCache.ts
+++ b/src/draw/candleCache.ts
@@ -1,5 +1,12 @@
 import type { ChartLayout, CandlePoint } from '../types';
-import { ensured, type CachePath } from './pathCache';
+import {
+  ensured,
+  createLayoutKey,
+  writeLayoutKey,
+  layoutKeyMatches,
+  type CachePath,
+  type LayoutKey,
+} from './pathCache';
 
 export type { CachePath } from './pathCache';
 
@@ -81,20 +88,22 @@ export interface CandleCacheSlot {
   // Invalidation key — flat numbers only, compared field-by-field so a
   // per-frame check allocates nothing. Validity is `bullBodies !== null` (no
   // separate boolean — all four paths are always (re)built together).
+  //
+  // The candle-identity half lives here; the layout half is the shared
+  // `LayoutKey` below, the same object type LineCacheSlot embeds — one
+  // spelling of min/max/x-scale/h/pads/chartW for both caches. Nested object,
+  // but allocated once per slot in `createCandleCacheSlot` and overwritten in
+  // place by `writeLayoutKey`, so the per-frame compare still allocates
+  // nothing.
   kCandlesRev: number;
-  kDataSource: number;
+  kDataSource: number; // not layout — stays here, see pathCache.ts LayoutKey
   kCandleWidthSecs: number;
   kClosedCount: number; // count of non-live candles in the frame's candle list
   kFirstClosedTime: number;
   kLastClosedTime: number;
-  kMinVal: number;
-  kMaxVal: number;
-  kWindow: number; // rightEdge - leftEdge (x scale)
-  kH: number;
-  kPadTop: number;
-  kPadBottom: number;
-  kChartW: number;
   kRadius: number; // candleDims' radius — depends on bodyW (zoom level)
+  /** Layout half of the key — see `LayoutKey` in pathCache.ts. */
+  layoutKey: LayoutKey;
 }
 
 /** Below this many closed candles the legacy rebuild is cheap anyway. */
@@ -119,14 +128,8 @@ export function createCandleCacheSlot(): CandleCacheSlot {
     kClosedCount: 0,
     kFirstClosedTime: 0,
     kLastClosedTime: 0,
-    kMinVal: 0,
-    kMaxVal: 0,
-    kWindow: 0,
-    kH: 0,
-    kPadTop: 0,
-    kPadBottom: 0,
-    kChartW: 0,
     kRadius: 0,
+    layoutKey: createLayoutKey(),
   };
 }
 
@@ -212,7 +215,6 @@ export function updateCandleCache(
   }
   if (closedCount < MIN_CACHE_CANDLES) return false;
 
-  const window = layout.rightEdge - layout.leftEdge;
   const hit =
     slot.bullBodies !== null &&
     slot.kCandlesRev === candlesRev &&
@@ -221,14 +223,8 @@ export function updateCandleCache(
     slot.kClosedCount === closedCount &&
     slot.kFirstClosedTime === firstClosedTime &&
     slot.kLastClosedTime === lastClosedTime &&
-    slot.kMinVal === layout.minVal &&
-    slot.kMaxVal === layout.maxVal &&
-    slot.kWindow === window &&
-    slot.kH === layout.h &&
-    slot.kPadTop === layout.pad.top &&
-    slot.kPadBottom === layout.pad.bottom &&
-    slot.kChartW === layout.chartW &&
-    slot.kRadius === radius;
+    slot.kRadius === radius &&
+    layoutKeyMatches(slot.layoutKey, layout);
 
   if (hit) return true;
 
@@ -303,14 +299,8 @@ export function updateCandleCache(
   slot.kClosedCount = closedCount;
   slot.kFirstClosedTime = firstClosedTime;
   slot.kLastClosedTime = lastClosedTime;
-  slot.kMinVal = layout.minVal;
-  slot.kMaxVal = layout.maxVal;
-  slot.kWindow = window;
-  slot.kH = layout.h;
-  slot.kPadTop = layout.pad.top;
-  slot.kPadBottom = layout.pad.bottom;
-  slot.kChartW = layout.chartW;
   slot.kRadius = radius;
+  writeLayoutKey(slot.layoutKey, layout);
 
   return true;
 }
diff --git a/src/draw/lineCache.ts b/src/draw/lineCache.ts
index 27836cb..6e3c02e 100644
--- a/src/draw/lineCache.ts
+++ b/src/draw/lineCache.ts
@@ -4,7 +4,14 @@ import {
   emitSplineSegments,
   drawSplineTail,
 } from '../math/spline';
-import { ensured, type CachePath } from './pathCache';
+import {
+  ensured,
+  createLayoutKey,
+  writeLayoutKey,
+  layoutKeyMatches,
+  type CachePath,
+  type LayoutKey,
+} from './pathCache';
 
 export type { CachePath } from './pathCache';
 
@@ -95,23 +102,23 @@ export interface LineCacheSlot {
 
   // Invalidation key — flat numbers only, compared field-by-field so a
   // per-frame check allocates nothing. Validity is `prefix !== null` (no
-  // separate boolean — the two are always written together). `layout.w`
-  // isn't keyed: it only reaches the drawn geometry through `chartW`
-  // (already keyed) and pad.left (absorbed by `dx`, see below), so it can
-  // never catch an invalidation those don't already catch.
+  // separate boolean — the two are always written together).
+  //
+  // The data-identity half lives here; the layout half is the shared
+  // `LayoutKey` below (min/max, x scale, h, pads, chartW), which the candle
+  // cache embeds too so the two can't drift apart on spelling again. It is a
+  // nested OBJECT but not a nested allocation: `createLineCacheSlot` builds it
+  // once and `writeLayoutKey` overwrites it in place, so the per-frame
+  // `layoutKeyMatches` call is still just number compares.
   kDataRev: number;
-  kDataSource: number;
+  kDataSource: number; // not layout — stays here, see pathCache.ts LayoutKey
   kLen: number; // visible.length
   kFirstT: number; // visible[0].time
   kLastT: number; // visible[len-1].time
   kLastV: number; // visible[len-1].value
-  kMin: number; // layout.minVal (snaps exactly when settled)
-  kMax: number;
-  kWindow: number; // rightEdge - leftEdge (x scale)
-  kH: number;
-  kPadTop: number;
-  kPadBottom: number;
-  kChartW: number;
+  /** Layout half of the key — see `LayoutKey` in pathCache.ts, including why
+   * `layout.w` is deliberately absent. `minVal` snaps exactly when settled. */
+  layoutKey: LayoutKey;
 }
 
 /** Below this many decimated points the legacy rebuild is cheap anyway. */
@@ -136,13 +143,7 @@ export function createLineCacheSlot(): LineCacheSlot {
     kFirstT: 0,
     kLastT: 0,
     kLastV: 0,
-    kMin: 0,
-    kMax: 0,
-    kWindow: 0,
-    kH: 0,
-    kPadTop: 0,
-    kPadBottom: 0,
-    kChartW: 0,
+    layoutKey: createLayoutKey(),
   };
 }
 
@@ -170,7 +171,6 @@ export function lineCacheHits(
   visLastV: number
 ): boolean {
   'worklet';
-  const window = layout.rightEdge - layout.leftEdge;
   return (
     slot.prefix !== null &&
     slot.kDataRev === dataRev &&
@@ -179,13 +179,7 @@ export function lineCacheHits(
     slot.kFirstT === visFirstT &&
     slot.kLastT === visLastT &&
     slot.kLastV === visLastV &&
-    slot.kMin === layout.minVal &&
-    slot.kMax === layout.maxVal &&
-    slot.kWindow === window &&
-    slot.kH === layout.h &&
-    slot.kPadTop === layout.pad.top &&
-    slot.kPadBottom === layout.pad.bottom &&
-    slot.kChartW === layout.chartW
+    layoutKeyMatches(slot.layoutKey, layout)
   );
 }
 
@@ -461,13 +455,7 @@ export function updateLinePaths(
     slot.kFirstT = visFirstT;
     slot.kLastT = visLastT;
     slot.kLastV = visLastV;
-    slot.kMin = layout.minVal;
-    slot.kMax = layout.maxVal;
-    slot.kWindow = layout.rightEdge - layout.leftEdge;
-    slot.kH = layout.h;
-    slot.kPadTop = layout.pad.top;
-    slot.kPadBottom = layout.pad.bottom;
-    slot.kChartW = layout.chartW;
+    writeLayoutKey(slot.layoutKey, layout);
   }
 
   assembleLineTail(
diff --git a/src/draw/pathCache.ts b/src/draw/pathCache.ts
index 8c72efb..78918ae 100644
--- a/src/draw/pathCache.ts
+++ b/src/draw/pathCache.ts
@@ -35,3 +35,107 @@ export function ensured<P extends CachePath>(
   'worklet';
   return cur ?? makePath();
 }
+
+/**
+ * Structural subset of `ChartLayout` that the shared layout key reads, for the
+ * same reason `CachePath` is a structural subset of `SkPath`: this module
+ * stays free of imports the caches don't strictly need, so jest can drive the
+ * key logic with a plain object literal. `ChartLayout` satisfies it.
+ */
+export interface KeyedLayout {
+  h: number;
+  chartW: number;
+  leftEdge: number;
+  rightEdge: number;
+  minVal: number;
+  maxVal: number;
+  pad: { top: number; bottom: number };
+}
+
+/**
+ * The layout half of every cross-frame path cache's invalidation key — the
+ * seven `layout`-derived numbers that `lineCache` and `candleCache` both
+ * keyed on independently (and, before this, under two different spellings:
+ * `kMin`/`kMax` vs `kMinVal`/`kMaxVal` for the same `layout.minVal`/`maxVal`).
+ *
+ * **Flat numbers only, compared field-by-field.** A cache slot allocates one
+ * of these ONCE, at slot construction, and then only ever overwrites its
+ * fields in place; `layoutKeyMatches` reads those fields directly and returns
+ * a boolean. So the per-frame check — which runs 60-120x/sec on the UI thread
+ * — allocates nothing, exactly as it did when the fields were inlined into the
+ * slot. Nesting the object costs one extra property load per field and no
+ * allocation; do NOT "generalize" this into an array of field names plus a
+ * loop, which would trade that for an iteration and defeat the whole point.
+ *
+ * `window` is stored pre-subtracted (`rightEdge - leftEdge`, the x scale)
+ * because that difference — not the two edges — is what the cached geometry
+ * actually depends on: a pure pan moves both edges together and is absorbed by
+ * the caches' `dx` translate, so keying the edges separately would invalidate
+ * on every scrolled frame. `layout.w` is deliberately NOT keyed: it reaches
+ * the drawn geometry only through `chartW` (keyed) and `pad.left` (absorbed by
+ * `dx`), so it can never catch an invalidation those two miss.
+ *
+ * Each cache keeps its OWN data-identity fields (`kDataRev`/`kLen`/`kFirstT`/…
+ * for the line, `kCandlesRev`/`kClosedCount`/`kRadius`/… for candles) on the
+ * slot itself — those are not layout, and no two caches agree on them.
+ */
+export interface LayoutKey {
+  minVal: number;
+  maxVal: number;
+  /** rightEdge - leftEdge (the x scale) — see the note above. */
+  window: number;
+  h: number;
+  padTop: number;
+  padBottom: number;
+  chartW: number;
+}
+
+/** A zeroed layout key. Allocated once per cache slot, never per frame. */
+export function createLayoutKey(): LayoutKey {
+  'worklet';
+  return {
+    minVal: 0,
+    maxVal: 0,
+    window: 0,
+    h: 0,
+    padTop: 0,
+    padBottom: 0,
+    chartW: 0,
+  };
+}
+
+/**
+ * Overwrites `key` in place from `layout` — called only on a cache miss,
+ * alongside the rebuild it is recording. Mutates rather than returning a fresh
+ * object so a rebuild allocates no key.
+ *
+ * Must stay field-for-field in step with `layoutKeyMatches` below; they are
+ * adjacent on purpose so a new dimension cannot be added to one alone.
+ */
+export function writeLayoutKey(key: LayoutKey, layout: KeyedLayout): void {
+  'worklet';
+  key.minVal = layout.minVal;
+  key.maxVal = layout.maxVal;
+  key.window = layout.rightEdge - layout.leftEdge;
+  key.h = layout.h;
+  key.padTop = layout.pad.top;
+  key.padBottom = layout.pad.bottom;
+  key.chartW = layout.chartW;
+}
+
+/**
+ * True when `key` still describes `layout`. Pure, allocation-free, seven
+ * number compares — safe to call every frame before any expensive work.
+ */
+export function layoutKeyMatches(key: LayoutKey, layout: KeyedLayout): boolean {
+  'worklet';
+  return (
+    key.minVal === layout.minVal &&
+    key.maxVal === layout.maxVal &&
+    key.window === layout.rightEdge - layout.leftEdge &&
+    key.h === layout.h &&
+    key.padTop === layout.pad.top &&
+    key.padBottom === layout.pad.bottom &&
+    key.chartW === layout.chartW
+  );
+}

From aef4ddf6024b296129aab08b55d56c1a723a8978 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Sat, 1 Aug 2026 13:38:48 -0400
Subject: [PATCH 20/37] fix(engine): prune seriesAlpha; extract makeLayout
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PLAN_MAINT #3 and #2. #3 carries a real bug fix.

**The bug:** EngineState declares eight per-series Maps. `seriesAlpha` has the
same lifecycle as the four that were pruned — written per series, read in two
places — but was never pruned or cleared anywhere. A long-lived chart whose
series ids churn leaked one entry per dead id, forever.

It leaked *because* pruning was four hand-written near-identical loops, so
adding a fifth map meant remembering to write a fifth loop. Registration now
lives next to the field declarations: `perSeriesMaps(s)` returns the maps that
must be pruned together and `pruneByIds(currentIds, maps)` does it. Adding a
ninth map is one line in one place.

Audited all eight rather than assuming:
- smoothValuesScratch — .clear()-ed every multi frame, correctly excluded
  (a test asserts the exclusion).
- lastMultiStashRevs/lastMultiStashData — their separate prune LOOKS like the
  same lossy size>length proxy, but the insert loop runs before the check, so
  a same-count id swap transiently pushes size above length and the dead id is
  caught. They must stay excluded: they are keyed by the PREVIOUS series set,
  and pruning against live ids would destroy the reverse-morph data.
- pausedMultiData is a ninth map the doc didn't count — a nullable whole-map
  snapshot with no cross-series-set lifetime. Excluded, documented.

Call site confirmed non-per-frame: it sits inside the existing shrink guard,
which already allocated a Set there.

**#2:** the same 16-line ChartLayout literal appeared three times, re-verified
byte-identical on this branch before extracting. toX/toY stay closures — one
allocation per frame per chart, exactly as before — with a comment against
"optimizing" them into shared mutable state, which would alias across the
three pipelines.

No existing test modified.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/engine/__tests__/pruneByIds.test.ts | 101 ++++++++++++++++++++++++
 src/engine/helpers.ts                   |  47 +++++++++++
 src/engine/state.ts                     |  52 ++++++++++++
 src/engine/step.ts                      |  62 +++++----------
 4 files changed, 218 insertions(+), 44 deletions(-)
 create mode 100644 src/engine/__tests__/pruneByIds.test.ts

diff --git a/src/engine/__tests__/pruneByIds.test.ts b/src/engine/__tests__/pruneByIds.test.ts
new file mode 100644
index 0000000..de571e9
--- /dev/null
+++ b/src/engine/__tests__/pruneByIds.test.ts
@@ -0,0 +1,101 @@
+// `EngineState` pulls in the draw layer, which imports Skia's ESM build —
+// untransformed by the react-native jest preset. None of it is exercised by
+// state construction (the Skia handles are all created lazily at draw time),
+// so a bare stub is enough to get the real `createEngineState` under test.
+jest.mock('@shopify/react-native-skia', () => ({
+  Skia: new Proxy({}, { get: () => () => ({}) }) as unknown as Record<
+    string,
+    unknown
+  >,
+  BlendMode: {},
+  ClipOp: {},
+  PaintStyle: {},
+  StrokeCap: {},
+  StrokeJoin: {},
+  TileMode: {},
+  FilterMode: {},
+  MipmapMode: {},
+  FontSlant: {},
+  PathOp: {},
+}));
+
+import {
+  createEngineState,
+  perSeriesMaps,
+  pruneByIds,
+  type EngineState,
+} from '../state';
+
+/**
+ * Per-series maps on `EngineState` are keyed by series id, and a chart whose
+ * series set churns must not accumulate entries for ids that no longer
+ * exist. This used to be four hand-written delete loops in `engineStep`, and
+ * `seriesAlpha` — same lifecycle, same keys — was simply never added to them,
+ * so it grew without bound for the life of the chart.
+ *
+ * These tests pin the registration itself (`perSeriesMaps`) rather than the
+ * call site, because the bug was a missing registration, not a broken loop.
+ */
+function populate(s: EngineState, ids: string[]): void {
+  for (const id of ids) {
+    s.displayValues.set(id, 1);
+    s.seriesAlpha.set(id, 1);
+    s.multiVisibleScratch.set(id, []);
+    // Shape-irrelevant here — pruning only ever looks at keys.
+    s.multiSeriesEntryScratch.set(
+      id,
+      {} as ReturnType<EngineState['multiSeriesEntryScratch']['get']> & object
+    );
+    s.lineCaches.set(
+      id,
+      {} as ReturnType<EngineState['lineCaches']['get']> & object
+    );
+  }
+}
+
+describe('per-series map pruning', () => {
+  it('drops dead ids from every registered map', () => {
+    const s = createEngineState(0, 60, false, 8);
+    populate(s, ['a', 'b', 'c']);
+    for (const map of perSeriesMaps(s)) expect(map.size).toBe(3);
+
+    pruneByIds(new Set(['a']), perSeriesMaps(s));
+
+    for (const map of perSeriesMaps(s)) {
+      expect(map.size).toBe(1);
+      expect([...map.keys()]).toEqual(['a']);
+    }
+  });
+
+  it('registers seriesAlpha — the map that leaked', () => {
+    const s = createEngineState(0, 60, false, 8);
+    populate(s, ['a', 'b']);
+
+    pruneByIds(new Set(['b']), perSeriesMaps(s));
+
+    // Guard against a future map being added to EngineState and silently
+    // left out of the array, which is exactly how seriesAlpha leaked.
+    expect(perSeriesMaps(s)).toContain(s.seriesAlpha);
+    expect(s.seriesAlpha.has('a')).toBe(false);
+    expect(s.seriesAlpha.get('b')).toBe(1);
+  });
+
+  it('keeps ids that are still live and is a no-op when nothing died', () => {
+    const s = createEngineState(0, 60, false, 8);
+    populate(s, ['a', 'b']);
+
+    pruneByIds(new Set(['a', 'b', 'unseen']), perSeriesMaps(s));
+
+    for (const map of perSeriesMaps(s)) expect(map.size).toBe(2);
+  });
+
+  it('leaves the per-frame scratch map out of the pruned set', () => {
+    // smoothValuesScratch is .clear()-ed every multi frame, so pruning it
+    // here would be redundant; assert the registration reflects that rather
+    // than someone adding it later on a hunch.
+    const s = createEngineState(0, 60, false, 8);
+    expect(perSeriesMaps(s)).not.toContain(s.smoothValuesScratch);
+    expect(perSeriesMaps(s)).not.toContain(s.lastMultiStashData);
+    expect(perSeriesMaps(s)).not.toContain(s.lastMultiStashRevs);
+  });
+});
diff --git a/src/engine/helpers.ts b/src/engine/helpers.ts
index c95e37c..18ac799 100644
--- a/src/engine/helpers.ts
+++ b/src/engine/helpers.ts
@@ -251,3 +251,50 @@ export function updateHoverState(
     emitPoint,
   };
 }
+
+/** The three range fields `makeLayout` reads — structurally satisfied by
+ * both `updateRange`'s and `updateCandleRange`'s result objects. */
+export interface LayoutRange {
+  minVal: number;
+  maxVal: number;
+  valRange: number;
+}
+
+/**
+ * Build the per-frame `ChartLayout` shared by all three pipelines (line,
+ * candle, multi-series). Previously this exact literal — closures included
+ * — was written out three times in `engine/step.ts`.
+ *
+ * `toX`/`toY` stay closures on purpose: one allocation per frame per chart,
+ * which is what the inline literals already did. Do NOT "optimize" them
+ * into a shared object with mutable captured state — the three pipelines
+ * would alias each other's edges and range.
+ */
+export function makeLayout(
+  w: number,
+  h: number,
+  pad: Required<Padding>,
+  chartW: number,
+  chartH: number,
+  leftEdge: number,
+  rightEdge: number,
+  range: LayoutRange
+): ChartLayout {
+  'worklet';
+  const { minVal, maxVal, valRange } = range;
+  return {
+    w,
+    h,
+    pad,
+    chartW,
+    chartH,
+    leftEdge,
+    rightEdge,
+    minVal,
+    maxVal,
+    valRange,
+    toX: (t: number) =>
+      pad.left + ((t - leftEdge) / (rightEdge - leftEdge)) * chartW,
+    toY: (v: number) => pad.top + (1 - (v - minVal) / valRange) * chartH,
+  };
+}
diff --git a/src/engine/state.ts b/src/engine/state.ts
index 2612efc..b0f51cc 100644
--- a/src/engine/state.ts
+++ b/src/engine/state.ts
@@ -262,6 +262,58 @@ export interface EngineState {
   lastFrameTimestamp: number | null;
 }
 
+/** The subset of `Map` that {@link pruneByIds} needs — lets one array hold
+ * per-series maps with differently-typed values (`Map<string, V>` is
+ * invariant in `V`, so `Map<string, unknown>[]` would not accept them). */
+export interface PrunableMap {
+  readonly size: number;
+  keys(): IterableIterator<string>;
+  delete(key: string): boolean;
+}
+
+/**
+ * Every per-series map on `EngineState` whose keys are series ids owned by
+ * the *current* multi-series set, and which therefore must be pruned
+ * together when a series is removed. Registration lives here, next to the
+ * field declarations above: adding a new per-series map means adding one
+ * line to this array, not hand-writing another delete loop at the call
+ * site (which is how `seriesAlpha` came to leak).
+ *
+ * Deliberately NOT included, each for its own reason:
+ * - `smoothValuesScratch` — `.clear()`-ed at the top of every multi frame
+ *   (`step.ts`), so it can never hold a dead id past that frame.
+ * - `lastMultiStashRevs` / `lastMultiStashData` — keyed by the *stashed*
+ *   (previous) series set rather than the current one, and pruned on their
+ *   own in the stash-build block in `step.ts`; pruning them against the
+ *   live ids here would throw away the reverse-morph data that block
+ *   exists to keep.
+ * - `pausedMultiData` — a nullable whole-map snapshot, rebuilt on pause and
+ *   set back to `null` on resume, so it has no cross-series-set lifetime.
+ *
+ * Allocates a small array per call; only ever called from the
+ * series-removal branch (guarded by a size check), never per frame.
+ */
+export function perSeriesMaps(s: EngineState): PrunableMap[] {
+  'worklet';
+  return [
+    s.displayValues,
+    s.seriesAlpha,
+    s.multiVisibleScratch,
+    s.multiSeriesEntryScratch,
+    s.lineCaches,
+  ];
+}
+
+/** Delete every entry whose key is not in `currentIds`, from each map. */
+export function pruneByIds(currentIds: Set<string>, maps: PrunableMap[]): void {
+  'worklet';
+  for (const map of maps) {
+    for (const key of map.keys()) {
+      if (!currentIds.has(key)) map.delete(key);
+    }
+  }
+}
+
 export function createEngineState(
   value: number,
   windowSecs: number,
diff --git a/src/engine/step.ts b/src/engine/step.ts
index 6ecbc5a..6828994 100644
--- a/src/engine/step.ts
+++ b/src/engine/step.ts
@@ -26,6 +26,7 @@ import { drawLoading } from '../draw/loading';
 import { drawEmpty } from '../draw/empty';
 import type { EngineConfigStep } from './types';
 import type { EngineState } from './state';
+import { perSeriesMaps, pruneByIds } from './state';
 import { drawBadge } from './badge';
 import { updateGridLayer } from './gridLayer';
 import { updateLineScrollLayer } from './lineScrollLayer';
@@ -37,6 +38,7 @@ import {
   updateWindowTransition,
   updateRange,
   updateHoverState,
+  makeLayout,
 } from './helpers';
 import {
   computeCandleRange,
@@ -778,9 +780,8 @@ export function engineStep(
     s.rangeInited = rangeResult.rangeInited;
     s.displayMin = rangeResult.displayMin;
     s.displayMax = rangeResult.displayMax;
-    const { minVal, maxVal, valRange } = rangeResult;
 
-    const layout: ChartLayout = {
+    const layout: ChartLayout = makeLayout(
       w,
       h,
       pad,
@@ -788,13 +789,8 @@ export function engineStep(
       chartH,
       leftEdge,
       rightEdge,
-      minVal,
-      maxVal,
-      valRange,
-      toX: (t: number) =>
-        pad.left + ((t - leftEdge) / (rightEdge - leftEdge)) * chartW,
-      toY: (v: number) => pad.top + (1 - (v - minVal) / valRange) * chartH,
-    };
+      rangeResult
+    );
 
     // Cross-frame grid picture cache — see engine/gridLayer.ts. Bypassed
     // while the reveal morph is animating: ctx.drawPicture ignores
@@ -1119,23 +1115,12 @@ export function engineStep(
     if (!useMultiStash && s.displayValues.size > effectiveMultiSeries.length) {
       const currentIds = new Set<string>();
       for (const series of effectiveMultiSeries) currentIds.add(series.id);
-      for (const key of s.displayValues.keys()) {
-        if (!currentIds.has(key)) s.displayValues.delete(key);
-      }
-      for (const key of s.lineCaches.keys()) {
-        if (!currentIds.has(key)) s.lineCaches.delete(key);
-      }
-      // Same pruning for the per-series visible-array and MultiSeriesEntry
-      // pools (see EngineState.multiVisibleScratch/multiSeriesEntryScratch)
-      // — both are keyed and repopulated exactly like lineCaches above, so
-      // they need the same cleanup-on-removal treatment to avoid leaking a
-      // growing set of dead series ids forever.
-      for (const key of s.multiVisibleScratch.keys()) {
-        if (!currentIds.has(key)) s.multiVisibleScratch.delete(key);
-      }
-      for (const key of s.multiSeriesEntryScratch.keys()) {
-        if (!currentIds.has(key)) s.multiSeriesEntryScratch.delete(key);
-      }
+      // Every per-series map that is keyed by the current series set is
+      // registered on `perSeriesMaps` in engine/state.ts, next to the field
+      // declarations — including which maps are deliberately excluded and
+      // why. Adding one here is a one-line change there, not another
+      // hand-written delete loop at this call site.
+      pruneByIds(currentIds, perSeriesMaps(s));
     }
 
     // Use first series data for window transition seeding
@@ -1376,9 +1361,8 @@ export function engineStep(
     s.targetMax = rangeResult.targetMax;
     s.displayMin = rangeResult.displayMin;
     s.displayMax = rangeResult.displayMax;
-    const { minVal, maxVal, valRange } = rangeResult;
 
-    const layout: ChartLayout = {
+    const layout: ChartLayout = makeLayout(
       w,
       h,
       pad,
@@ -1386,13 +1370,8 @@ export function engineStep(
       chartH,
       leftEdge,
       rightEdge,
-      minVal,
-      maxVal,
-      valRange,
-      toX: (t: number) =>
-        pad.left + ((t - leftEdge) / (rightEdge - leftEdge)) * chartW,
-      toY: (v: number) => pad.top + (1 - (v - minVal) / valRange) * chartH,
-    };
+      rangeResult
+    );
 
     // Cross-frame grid picture cache — see engine/gridLayer.ts. Bypassed
     // while the reveal morph is animating (ctx.drawPicture ignores
@@ -1643,9 +1622,9 @@ export function engineStep(
     s.targetMax = rangeResult.targetMax;
     s.displayMin = rangeResult.displayMin;
     s.displayMax = rangeResult.displayMax;
-    const { minVal, maxVal, valRange } = rangeResult;
+    const { valRange } = rangeResult;
 
-    const layout: ChartLayout = {
+    const layout: ChartLayout = makeLayout(
       w,
       h,
       pad,
@@ -1653,13 +1632,8 @@ export function engineStep(
       chartH,
       leftEdge,
       rightEdge,
-      minVal,
-      maxVal,
-      valRange,
-      toX: (t: number) =>
-        pad.left + ((t - leftEdge) / (rightEdge - leftEdge)) * chartW,
-      toY: (v: number) => pad.top + (1 - (v - minVal) / valRange) * chartH,
-    };
+      rangeResult
+    );
 
     // Cross-frame grid picture cache — see engine/gridLayer.ts. Bypassed
     // while the reveal morph is animating (ctx.drawPicture ignores

From dffc2002e0c073c7c65478d9c52dc0d75125483b Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Sat, 1 Aug 2026 13:38:48 -0400
Subject: [PATCH 21/37] test(engine): cover quiescence, helpers and
 candleHelpers (+97 tests)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PLAN_MAINT #6 — the prerequisite for the pipeline extraction (#1). Tests
218 -> 319 across the branch.

Written to catch mutations, not for coverage percentage. Each significant test
pins a specific one-line regression, e.g.:
- hover at x=0: `hoverPixelX === null` weakened to `!hoverPixelX` would freeze
  the crosshair mid-drag at the left edge.
- Three "deliberate non-condition" tests in quiescence: adding !cfg.showPulse,
  !cfg.showMomentum or !cfg.orderbookData. Pulse defaults true, so that one
  would silently disable quiescence for nearly every chart.
- Log-space window transition: 10s->40s halfway is 20 (geometric mean),
  asserted `not` 25 — pins logLerp against a linear rewrite.
- 60Hz vs 120Hz convergence, paired with a test proving an uncorrected lerp
  WOULD diverge, so removing the dt term is caught rather than masked.
- 300-frame convergence asserting toBe(40) bit-exactly, paired with a proof
  that an unsnapped exponential never gets there — a residual epsilon
  invalidates the range and grid caches forever.
- candleAtX: an exhaustive 1000-candle sweep over every bucket centre, which
  catches binary-search off-by-ones that spot checks miss.

Also covers computeAdaptiveSpeed and computeCandleRange, which PLAN_MAINT
omitted.

One finding, source deliberately NOT changed: updateCandleRange is not exactly
frame-rate independent. Its lerp is dt-corrected but the adaptive speed is
recomputed from the current gap every frame, so 120Hz re-evaluates the
schedule twice as often and lands slightly ahead (<1% of travel).
engine/helpers.ts's updateRange avoids this by computing its speed once and
passing it in. The test asserts the actual bounded drift rather than an
aspirational exact match, and still catches removal of dt. Worth deciding
later whether the candle pipeline should hoist its speed computation to match.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/engine/__tests__/candleHelpers.test.ts | 628 +++++++++++++++
 src/engine/__tests__/helpers.test.ts       | 887 +++++++++++++++++++++
 src/engine/__tests__/quiescence.test.ts    | 224 ++++++
 3 files changed, 1739 insertions(+)
 create mode 100644 src/engine/__tests__/candleHelpers.test.ts
 create mode 100644 src/engine/__tests__/helpers.test.ts
 create mode 100644 src/engine/__tests__/quiescence.test.ts

diff --git a/src/engine/__tests__/candleHelpers.test.ts b/src/engine/__tests__/candleHelpers.test.ts
new file mode 100644
index 0000000..44f459e
--- /dev/null
+++ b/src/engine/__tests__/candleHelpers.test.ts
@@ -0,0 +1,628 @@
+import {
+  computeCandleRange,
+  candleAtX,
+  updateCandleRange,
+  updateCandleWindowTransition,
+} from '../candleHelpers';
+import {
+  RANGE_LERP_SPEED,
+  RANGE_ADAPTIVE_BOOST,
+  WINDOW_TRANSITION_MS,
+} from '../constants';
+import type { CandlePoint, ChartLayout, Padding } from '../../types';
+
+// ── Fixtures ───────────────────────────────────────────────────────────────
+
+const PAD: Required<Padding> = { top: 0, right: 0, bottom: 0, left: 0 };
+
+const candle = (
+  time: number,
+  low: number,
+  high: number,
+  open = low,
+  close = high
+): CandlePoint => ({ time, open, high, low, close });
+
+type CandleWt = {
+  from: number;
+  to: number;
+  startMs: number;
+  rangeFromMin: number;
+  rangeFromMax: number;
+  rangeToMin: number;
+  rangeToMax: number;
+};
+
+const wtState = (over: Partial<CandleWt> = {}): CandleWt => ({
+  from: 0,
+  to: 60,
+  startMs: 0,
+  rangeFromMin: 0,
+  rangeFromMax: 0,
+  rangeToMin: 0,
+  rangeToMax: 0,
+  ...over,
+});
+
+/** Linear time↔pixel mapping: x = time / 60 over [0, 60000] → [0, 1000]. */
+function makeLayout(
+  leftEdge: number,
+  rightEdge: number,
+  chartW: number
+): ChartLayout {
+  return {
+    w: chartW,
+    h: 200,
+    pad: PAD,
+    chartW,
+    chartH: 200,
+    leftEdge,
+    rightEdge,
+    minVal: 0,
+    maxVal: 100,
+    valRange: 100,
+    toX: (t: number) => ((t - leftEdge) / (rightEdge - leftEdge)) * chartW,
+    toY: (v: number) => 200 - v,
+  };
+}
+
+function naiveLerp(current: number, target: number, speed: number): number {
+  return current + (target - current) * speed;
+}
+
+// ── computeCandleRange ─────────────────────────────────────────────────────
+
+describe('computeCandleRange', () => {
+  it('returns the fixed placeholder range for an empty series', () => {
+    // Infinity would propagate into valRange and NaN out every toY.
+    expect(computeCandleRange([])).toEqual({ min: 99, max: 101 });
+  });
+
+  it('scans lows and highs, not opens and closes', () => {
+    // The wick at 200 and the wick at 10 must both be inside the range even
+    // though no body reaches them.
+    const r = computeCandleRange([candle(0, 10, 200, 100, 110)]);
+    expect(r.min).toBeLessThan(10);
+    expect(r.max).toBeGreaterThan(200);
+  });
+
+  it('applies a 12% margin on both sides', () => {
+    const r = computeCandleRange([candle(0, 100, 200), candle(60, 120, 180)]);
+    // range 100 → margin 12
+    expect(r.min).toBeCloseTo(88, 10);
+    expect(r.max).toBeCloseTo(212, 10);
+  });
+
+  it('never returns an inverted or empty range for real data', () => {
+    const r = computeCandleRange([candle(0, 100, 200)]);
+    expect(r.max).toBeGreaterThan(r.min);
+  });
+
+  it('widens a perfectly flat series to the 0.4 absolute floor, centred on the price', () => {
+    // range 0 → minRange falls back to 0.4 → price ± 0.2.
+    const r = computeCandleRange([candle(0, 100, 100), candle(60, 100, 100)]);
+    expect(r.min).toBe(99.8);
+    expect(r.max).toBe(100.2);
+  });
+
+  it('does NOT apply the 0.4 floor to a tiny-but-nonzero range', () => {
+    // minRange is relative (range * 0.1), so it can never exceed a nonzero
+    // range — a hardcoded absolute floor here would visibly flatten a
+    // low-volatility chart.
+    const r = computeCandleRange([candle(0, 100, 100.001)]);
+    expect(r.max - r.min).toBeLessThan(0.4);
+    expect(r.min).toBeCloseTo(100 - 0.001 * 0.12, 12);
+  });
+
+  it('ignores candle ordering', () => {
+    const a = computeCandleRange([candle(0, 10, 20), candle(60, 5, 30)]);
+    const b = computeCandleRange([candle(60, 5, 30), candle(0, 10, 20)]);
+    expect(a).toEqual(b);
+  });
+});
+
+// ── candleAtX ──────────────────────────────────────────────────────────────
+
+describe('candleAtX', () => {
+  const WIDTH = 60;
+  const layout = makeLayout(0, 60_000, 1000);
+  // Contiguous candles at t = 0, 60, 120, ... ; x = t / 60, so candle i owns
+  // pixels [i, i + 1).
+  const candles: CandlePoint[] = Array.from({ length: 1000 }, (_, i) =>
+    candle(i * WIDTH, i, i + 1)
+  );
+
+  it('finds the right candle for every bucket centre across a 1000-candle series', () => {
+    // An off-by-one in the binary search survives a handful of spot checks
+    // but not an exhaustive sweep.
+    for (let i = 0; i < candles.length; i++) {
+      expect(candleAtX(candles, i + 0.5, WIDTH, layout)).toBe(candles[i]);
+    }
+  });
+
+  it('treats a bucket as [start, start + width): start inclusive, end exclusive', () => {
+    // `time >= c.time + candleWidth` vs `>` decides which candle owns the
+    // shared boundary; getting it wrong makes the crosshair jump a slot.
+    expect(candleAtX(candles, 5, WIDTH, layout)).toBe(candles[5]);
+    expect(candleAtX(candles, 6, WIDTH, layout)).toBe(candles[6]);
+  });
+
+  it('returns null before the first candle', () => {
+    expect(candleAtX(candles, -0.5, WIDTH, layout)).toBeNull();
+  });
+
+  it('returns null past the end of the last candle', () => {
+    expect(candleAtX(candles, 1000.5, WIDTH, layout)).toBeNull();
+  });
+
+  it('returns null inside a gap in the series rather than the nearest neighbour', () => {
+    const gapped = [candle(0, 1, 2), candle(600, 3, 4)];
+    // t = 300 sits in the hole between the two candles.
+    expect(candleAtX(gapped, 5, WIDTH, makeLayout(0, 60_000, 1000))).toBeNull();
+    expect(candleAtX(gapped, 0.5, WIDTH, makeLayout(0, 60_000, 1000))).toBe(
+      gapped[0]
+    );
+  });
+
+  it('returns null for an empty series', () => {
+    expect(candleAtX([], 5, WIDTH, layout)).toBeNull();
+  });
+
+  it('honours left padding when converting pixels to time', () => {
+    const padded: ChartLayout = {
+      ...makeLayout(0, 60_000, 1000),
+      pad: { ...PAD, left: 100 },
+    };
+    // x = 100 must map to leftEdge (t = 0), i.e. the first candle.
+    expect(candleAtX(candles, 100, WIDTH, padded)).toBe(candles[0]);
+    expect(candleAtX(candles, 99, WIDTH, padded)).toBeNull();
+  });
+});
+
+// ── updateCandleRange ──────────────────────────────────────────────────────
+
+describe('updateCandleRange — first frame', () => {
+  it('adopts the computed range verbatim', () => {
+    expect(
+      updateCandleRange(
+        { min: 3, max: 7 },
+        false,
+        -1,
+        -1,
+        false,
+        0,
+        wtState(),
+        300,
+        16.67
+      )
+    ).toEqual({
+      minVal: 3,
+      maxVal: 7,
+      valRange: 4,
+      displayMin: 3,
+      displayMax: 7,
+      rangeInited: true,
+    });
+  });
+
+  it('never reports a zero valRange', () => {
+    const r = updateCandleRange(
+      { min: 5, max: 5 },
+      false,
+      0,
+      0,
+      false,
+      0,
+      wtState(),
+      300,
+      16.67
+    );
+    expect(r.valRange).toBe(0.001);
+  });
+});
+
+describe('updateCandleRange — during a window transition', () => {
+  const wt = wtState({
+    rangeFromMin: 0,
+    rangeFromMax: 100,
+    rangeToMin: 50,
+    rangeToMax: 150,
+  });
+
+  it('blends the captured ranges by progress and ignores the incoming display values', () => {
+    const r = updateCandleRange(
+      { min: 999, max: 999 },
+      true,
+      1234,
+      5678,
+      true,
+      0.25,
+      wt,
+      300,
+      16.67
+    );
+    expect(r.displayMin).toBe(12.5);
+    expect(r.displayMax).toBe(112.5);
+  });
+
+  it('lands exactly on the captured target range at full progress', () => {
+    const r = updateCandleRange(
+      { min: 0, max: 0 },
+      true,
+      0,
+      0,
+      true,
+      1,
+      wt,
+      300,
+      16.67
+    );
+    expect(r.displayMin).toBe(50);
+    expect(r.displayMax).toBe(150);
+  });
+});
+
+describe('updateCandleRange — steady-state lerp', () => {
+  function run(frames: number, dt: number, chartH: number) {
+    let displayMin = 0;
+    let displayMax = 100;
+    for (let i = 0; i < frames; i++) {
+      const r = updateCandleRange(
+        { min: 40, max: 160 },
+        true,
+        displayMin,
+        displayMax,
+        false,
+        0,
+        wtState(),
+        chartH,
+        dt
+      );
+      displayMin = r.displayMin;
+      displayMax = r.displayMax;
+    }
+    return { displayMin, displayMax };
+  }
+
+  it('tracks the same trajectory at 60Hz and 120Hz over the same wall-clock time', () => {
+    // Mid-flight on purpose — after a full second both rates have converged
+    // and the comparison would prove nothing.
+    //
+    // Note this is a *bounded-drift* assertion, not an exact one, and that is
+    // the real behaviour: the underlying lerp is dt-corrected, but the
+    // adaptive `speed` is recomputed from the current gap on every frame, so
+    // the 120Hz run re-evaluates the schedule twice as often and ends a hair
+    // ahead. The residual is well under 1% of the 120-unit range travelled.
+    // The line pipeline (engine/helpers.ts `updateRange`) does not have this
+    // wrinkle because its adaptive speed is computed once and passed in.
+    const at60 = run(6, 1000 / 60, 1e9);
+    const at120 = run(12, 1000 / 120, 1e9);
+    expect(at60.displayMin).toBeGreaterThan(5);
+    expect(at60.displayMin).toBeLessThan(38);
+    expect(Math.abs(at120.displayMin - at60.displayMin)).toBeLessThan(1);
+    expect(Math.abs(at120.displayMax - at60.displayMax)).toBeLessThan(1);
+  });
+
+  it('a lerp with no dt correction WOULD blow that bound by an order of magnitude', () => {
+    // Dropping the dt term from math/lerp keeps the same adaptive schedule but
+    // makes 120Hz arrive roughly twice as fast — ~9 units apart, vs the <1
+    // asserted above.
+    const naive = (frames: number) => {
+      let v = 0;
+      for (let i = 0; i < frames; i++) v = naiveLerp(v, 40, RANGE_LERP_SPEED);
+      return v;
+    };
+    expect(Math.abs(naive(12) - naive(6))).toBeGreaterThan(5);
+  });
+
+  it('snaps to a BIT-EXACT target once inside the sub-pixel threshold', () => {
+    // Exactness is load-bearing: draw/candleCache keys its cached geometry on
+    // displayMin/displayMax, so residual drift means a full rebuild every
+    // frame — the documented main limiter on that cache's hit rate.
+    const { displayMin, displayMax } = run(300, 1000 / 60, 300);
+    expect(displayMin).toBe(40);
+    expect(displayMax).toBe(160);
+  });
+
+  it('accelerates as the gap closes (adaptive speed), so the first frame is the slowest', () => {
+    // gapMin + gapMax spans the whole range on the first frame → gapRatio
+    // clamps to 1 → base speed only. Dropping the adaptive term would make
+    // every frame move by the same fraction.
+    const first = updateCandleRange(
+      { min: 40, max: 160 },
+      true,
+      0,
+      100,
+      false,
+      0,
+      wtState(),
+      1e9,
+      16.67
+    );
+    expect(first.displayMin).toBeCloseTo(40 * RANGE_LERP_SPEED, 6);
+
+    // A tiny gap → gapRatio ≈ 0 → base + full boost.
+    const near = updateCandleRange(
+      { min: 40.0001, max: 160 },
+      true,
+      40,
+      160,
+      false,
+      0,
+      wtState(),
+      1e9,
+      16.67
+    );
+    const movedFraction = (near.displayMin - 40) / 0.0001;
+    expect(movedFraction).toBeCloseTo(
+      RANGE_LERP_SPEED + RANGE_ADAPTIVE_BOOST,
+      4
+    );
+  });
+
+  it('guards the degenerate zero-range divisor', () => {
+    // curRange `|| 1`: without it gapRatio is NaN and the whole range poisons.
+    const r = updateCandleRange(
+      { min: 4, max: 6 },
+      true,
+      5,
+      5,
+      false,
+      0,
+      wtState(),
+      300,
+      16.67
+    );
+    expect(Number.isNaN(r.displayMin)).toBe(false);
+    expect(Number.isNaN(r.displayMax)).toBe(false);
+    expect(r.displayMin).toBeLessThan(5);
+    expect(r.displayMax).toBeGreaterThan(5);
+  });
+});
+
+// ── updateCandleWindowTransition ───────────────────────────────────────────
+
+describe('updateCandleWindowTransition — retargeting', () => {
+  const NOW = 1000;
+  const NOW_MS = 50_000;
+  const BUFFER = 0.05;
+  const WIDTH = 60;
+
+  it('captures the from-window, from-range and start time on a window change', () => {
+    const wt = wtState({ to: 20 });
+    updateCandleWindowTransition(
+      100,
+      wt,
+      /* displayWindow */ 20,
+      /* displayMin */ 90,
+      /* displayMax */ 110,
+      NOW_MS,
+      NOW,
+      [candle(940, 100, 110)],
+      undefined,
+      WIDTH,
+      BUFFER
+    );
+    expect(wt.from).toBe(20);
+    expect(wt.to).toBe(100);
+    expect(wt.startMs).toBe(NOW_MS);
+    expect(wt.rangeFromMin).toBe(90);
+    expect(wt.rangeFromMax).toBe(110);
+  });
+
+  it('includes a candle that STARTS before the target left edge but extends past it', () => {
+    // Target window is [905, 1005]. A candle at t=880 with width 60 ends at
+    // 940, so it is partly on screen — candle visibility is width-adjusted,
+    // unlike line-point visibility. Dropping the `+ candleWidth` term would
+    // drop this candle and lose the 500 high from the target range.
+    const wt = wtState({ to: 20, rangeToMin: -1, rangeToMax: -1 });
+    updateCandleWindowTransition(
+      100,
+      wt,
+      20,
+      90,
+      110,
+      NOW_MS,
+      NOW,
+      [candle(880, 100, 500), candle(940, 100, 110)],
+      undefined,
+      WIDTH,
+      BUFFER
+    );
+    expect(wt.rangeToMax).toBeGreaterThan(500);
+  });
+
+  it('excludes a candle that ends entirely before the target left edge', () => {
+    const wt = wtState({ to: 20, rangeToMin: -1, rangeToMax: -1 });
+    updateCandleWindowTransition(
+      100,
+      wt,
+      20,
+      90,
+      110,
+      NOW_MS,
+      NOW,
+      [candle(700, 100, 9999), candle(940, 100, 110)],
+      undefined,
+      WIDTH,
+      BUFFER
+    );
+    expect(wt.rangeToMax).toBeLessThan(200);
+  });
+
+  it('includes the live candle in the target range', () => {
+    // The live candle is not part of the `candles` array; omitting it from the
+    // scan makes the Y range snap the instant the transition ends.
+    const wt = wtState({ to: 20, rangeToMin: -1, rangeToMax: -1 });
+    updateCandleWindowTransition(
+      100,
+      wt,
+      20,
+      90,
+      110,
+      NOW_MS,
+      NOW,
+      [candle(940, 100, 110)],
+      candle(1000, 100, 400),
+      WIDTH,
+      BUFFER
+    );
+    expect(wt.rangeToMax).toBeGreaterThan(400);
+  });
+
+  it('ignores a live candle that falls outside the target window', () => {
+    const wt = wtState({ to: 20, rangeToMin: -1, rangeToMax: -1 });
+    updateCandleWindowTransition(
+      100,
+      wt,
+      20,
+      90,
+      110,
+      NOW_MS,
+      NOW,
+      [candle(940, 100, 110)],
+      candle(100, 100, 9999),
+      WIDTH,
+      BUFFER
+    );
+    expect(wt.rangeToMax).toBeLessThan(200);
+  });
+
+  it('leaves the previous target range untouched when the target window is empty', () => {
+    const wt = wtState({ to: 20, rangeToMin: 42, rangeToMax: 84 });
+    updateCandleWindowTransition(
+      100,
+      wt,
+      20,
+      90,
+      110,
+      NOW_MS,
+      NOW,
+      [candle(100, 1, 2)],
+      undefined,
+      WIDTH,
+      BUFFER
+    );
+    expect(wt.rangeToMin).toBe(42);
+    expect(wt.rangeToMax).toBe(84);
+  });
+
+  it('does not re-trigger while the same window stays selected', () => {
+    const wt = wtState({ to: 20 });
+    const candles = [candle(940, 100, 110)];
+    updateCandleWindowTransition(
+      100,
+      wt,
+      20,
+      90,
+      110,
+      NOW_MS,
+      NOW,
+      candles,
+      undefined,
+      WIDTH,
+      BUFFER
+    );
+    updateCandleWindowTransition(
+      100,
+      wt,
+      55,
+      1,
+      2,
+      NOW_MS + 300,
+      NOW,
+      candles,
+      undefined,
+      WIDTH,
+      BUFFER
+    );
+    expect(wt.startMs).toBe(NOW_MS);
+    expect(wt.from).toBe(20);
+    expect(wt.rangeFromMin).toBe(90);
+  });
+});
+
+describe('updateCandleWindowTransition — progress curve', () => {
+  const candles = [candle(940, 100, 110)];
+  const start = (wt: CandleWt, target: number, now_ms: number) =>
+    updateCandleWindowTransition(
+      target,
+      wt,
+      10,
+      90,
+      110,
+      now_ms,
+      1000,
+      candles,
+      undefined,
+      60,
+      0.05
+    );
+
+  it('reports the resting window with zero progress when nothing is running', () => {
+    const wt = wtState({ to: 100, startMs: 0 });
+    const r = updateCandleWindowTransition(
+      100,
+      wt,
+      100,
+      90,
+      110,
+      50_000,
+      1000,
+      candles,
+      undefined,
+      60,
+      0.05
+    );
+    expect(r.windowSecs).toBe(100);
+    expect(r.windowTransProgress).toBe(0);
+  });
+
+  it('interpolates the window in LOG space — halfway is the geometric mean', () => {
+    // 10 → 40 at t=0.5 gives 20, not the linear 25. Shares logLerp with the
+    // line pipeline; this pins them to the same curve.
+    const wt = wtState({ to: 10, startMs: 0 });
+    start(wt, 40, 1000);
+    const r = start(wt, 40, 1000 + WINDOW_TRANSITION_MS / 2);
+    expect(r.windowTransProgress).toBeCloseTo(0.5, 12);
+    expect(r.windowSecs).toBeCloseTo(20, 10);
+    expect(r.windowSecs).not.toBeCloseTo(25, 1);
+  });
+
+  it('eases in and out rather than ramping linearly', () => {
+    const wt = wtState({ to: 10, startMs: 0 });
+    start(wt, 40, 1000);
+    const r = start(wt, 40, 1000 + WINDOW_TRANSITION_MS / 4);
+    expect(r.windowTransProgress).toBeCloseTo(0.14644660940672627, 12);
+  });
+
+  it('lands exactly on the target window and clears the transition when time runs out', () => {
+    const wt = wtState({ to: 10, startMs: 0 });
+    start(wt, 40, 1000);
+    const r = start(wt, 40, 1000 + WINDOW_TRANSITION_MS);
+    expect(r.windowSecs).toBe(40);
+    expect(r.windowTransProgress).toBe(0);
+    expect(wt.startMs).toBe(0);
+  });
+
+  it('is wall-clock driven, so 60Hz and 120Hz agree at every shared instant', () => {
+    const START = 1000;
+    const INSTANTS = [1150, 1300, 1450, 1600, 1700];
+    const run = (frameMs: number): number[] => {
+      const wt = wtState({ to: 10, startMs: 0 });
+      start(wt, 40, START);
+      const out: number[] = [];
+      let t = frameMs;
+      for (const instant of INSTANTS) {
+        for (; t < instant; t += frameMs) start(wt, 40, t);
+        out.push(start(wt, 40, instant).windowSecs);
+      }
+      return out;
+    };
+    const at60 = run(1000 / 60);
+    const at120 = run(1000 / 120);
+    expect(at60).toEqual(at120);
+    expect(at60[0]).toBeLessThan(40);
+    expect(at60[0]).toBeGreaterThan(10);
+  });
+});
diff --git a/src/engine/__tests__/helpers.test.ts b/src/engine/__tests__/helpers.test.ts
new file mode 100644
index 0000000..1c2b935
--- /dev/null
+++ b/src/engine/__tests__/helpers.test.ts
@@ -0,0 +1,887 @@
+import {
+  computeAdaptiveSpeed,
+  updateWindowTransition,
+  updateRange,
+  updateHoverState,
+  type WindowTransState,
+} from '../helpers';
+import {
+  ADAPTIVE_SPEED_BOOST,
+  SCRUB_LERP_SPEED,
+  WINDOW_TRANSITION_MS,
+} from '../constants';
+import type { EngineConfigStep } from '../types';
+import type { ChartLayout, LivelinePoint, Padding } from '../../types';
+
+// ── Fixtures ───────────────────────────────────────────────────────────────
+
+const PAD: Required<Padding> = { top: 0, right: 20, bottom: 0, left: 10 };
+
+const pts = (spec: Array<[number, number]>): LivelinePoint[] =>
+  spec.map(([time, value]) => ({ time, value }));
+
+const cfg = (over: Partial<EngineConfigStep> = {}): EngineConfigStep =>
+  ({
+    windowSecs: 60,
+    noMotion: false,
+    exaggerate: false,
+    ...over,
+  }) as EngineConfigStep;
+
+const wtState = (over: Partial<WindowTransState> = {}): WindowTransState => ({
+  from: 0,
+  to: 60,
+  startMs: 0,
+  rangeFromMin: 0,
+  rangeFromMax: 0,
+  rangeToMin: 0,
+  rangeToMax: 0,
+  ...over,
+});
+
+/**
+ * Linear time/value mapping over `[leftEdge, rightEdge] → [pad.left,
+ * pad.left + chartW]`, matching what engine/step.ts builds each frame.
+ */
+function makeLayout(
+  leftEdge: number,
+  rightEdge: number,
+  w: number,
+  chartW: number
+): ChartLayout {
+  return {
+    w,
+    h: 200,
+    pad: PAD,
+    chartW,
+    chartH: 200,
+    leftEdge,
+    rightEdge,
+    minVal: 0,
+    maxVal: 100,
+    valRange: 100,
+    toX: (t: number) =>
+      PAD.left + ((t - leftEdge) / (rightEdge - leftEdge)) * chartW,
+    toY: (v: number) => 200 - v * 2,
+  };
+}
+
+/**
+ * The naive, frame-rate-*dependent* lerp — `current + (target - current) *
+ * speed`, applied once per frame regardless of dt. Several tests below assert
+ * that the real implementation does NOT behave like this.
+ */
+function naiveLerp(current: number, target: number, speed: number): number {
+  return current + (target - current) * speed;
+}
+
+// ── computeAdaptiveSpeed ───────────────────────────────────────────────────
+
+describe('computeAdaptiveSpeed', () => {
+  it('returns exactly 1 (instant snap) under noMotion, ignoring every other input', () => {
+    expect(computeAdaptiveSpeed(500, 1, 0, 10, 0.08, true)).toBe(1);
+    expect(computeAdaptiveSpeed(1, 1, 0, 10, 0.9, true)).toBe(1);
+  });
+
+  it('applies the full boost when the value has not moved at all', () => {
+    // gapRatio 0 → speed = lerpSpeed + boost. Inverting the `1 - gapRatio`
+    // term would give plain lerpSpeed here.
+    expect(computeAdaptiveSpeed(100, 100, 90, 110, 0.08, false)).toBe(
+      0.08 + ADAPTIVE_SPEED_BOOST
+    );
+  });
+
+  it('applies no boost at all when the jump spans the whole visible range', () => {
+    // gapRatio 1 → speed = lerpSpeed exactly: big jumps animate slowly.
+    expect(computeAdaptiveSpeed(120, 100, 90, 110, 0.08, false)).toBe(0.08);
+  });
+
+  it('clamps gapRatio at 1 so an enormous jump never produces a speed below lerpSpeed', () => {
+    // Without Math.min, a 10x-range jump yields a large negative boost and
+    // the display value would run *away* from the target.
+    const speed = computeAdaptiveSpeed(300, 100, 90, 110, 0.08, false);
+    expect(speed).toBe(0.08);
+    expect(speed).toBeGreaterThan(0);
+  });
+
+  it('interpolates linearly between the two extremes', () => {
+    // gap 10, range 20 → gapRatio 0.5 → half the boost.
+    expect(computeAdaptiveSpeed(110, 100, 90, 110, 0.08, false)).toBeCloseTo(
+      0.08 + 0.5 * ADAPTIVE_SPEED_BOOST,
+      12
+    );
+  });
+
+  it('falls back to a range of 1 when the display range is degenerate', () => {
+    // displayMax === displayMin → `|| 1`. Without it this is a divide by
+    // zero: gapRatio becomes NaN and every downstream lerp poisons.
+    const speed = computeAdaptiveSpeed(100.5, 100, 100, 100, 0.08, false);
+    expect(Number.isNaN(speed)).toBe(false);
+    expect(speed).toBeCloseTo(0.08 + 0.5 * ADAPTIVE_SPEED_BOOST, 12);
+  });
+
+  it('is symmetric: the gap is a magnitude, not a signed difference', () => {
+    expect(computeAdaptiveSpeed(105, 100, 90, 110, 0.08, false)).toBe(
+      computeAdaptiveSpeed(95, 100, 90, 110, 0.08, false)
+    );
+  });
+});
+
+// ── updateWindowTransition ─────────────────────────────────────────────────
+
+describe('updateWindowTransition — retargeting', () => {
+  const NOW = 1000;
+  const NOW_MS = 50_000;
+  const BUFFER = 0.05;
+
+  it('captures the from-window, from-range and start time on a window change', () => {
+    const wt = wtState({ to: 20, rangeToMin: -1, rangeToMax: -1 });
+    updateWindowTransition(
+      cfg({ windowSecs: 100 }),
+      wt,
+      /* displayWindow */ 20,
+      /* displayMin */ 90,
+      /* displayMax */ 110,
+      false,
+      NOW_MS,
+      NOW,
+      pts([
+        [990, 100],
+        [1000, 105],
+      ]),
+      105,
+      BUFFER
+    );
+    expect(wt.from).toBe(20);
+    expect(wt.to).toBe(100);
+    expect(wt.startMs).toBe(NOW_MS);
+    expect(wt.rangeFromMin).toBe(90);
+    expect(wt.rangeFromMax).toBe(110);
+  });
+
+  it('seeds the target range from the *target* window, not the current one', () => {
+    // Current window is 20s (covers t >= 985); the new window is 100s (covers
+    // t >= 905). The spike at t=910 is only inside the target window — if the
+    // target range were scanned with the current edges, the Y range would jump
+    // discontinuously the moment the transition finished.
+    const wt = wtState({ to: 20, rangeToMin: -1, rangeToMax: -1 });
+    updateWindowTransition(
+      cfg({ windowSecs: 100 }),
+      wt,
+      20,
+      90,
+      110,
+      false,
+      NOW_MS,
+      NOW,
+      pts([
+        [910, 500],
+        [990, 100],
+        [1000, 105],
+      ]),
+      105,
+      BUFFER
+    );
+    expect(wt.rangeToMax).toBeGreaterThan(500);
+    expect(wt.rangeToMin).toBeLessThan(105);
+  });
+
+  it('excludes points that fall outside the target window entirely', () => {
+    // t=800 is before the target left edge (1005 - 100 = 905) and must not
+    // drag the target range with it.
+    const wt = wtState({ to: 20, rangeToMin: -1, rangeToMax: -1 });
+    updateWindowTransition(
+      cfg({ windowSecs: 100 }),
+      wt,
+      20,
+      90,
+      110,
+      false,
+      NOW_MS,
+      NOW,
+      pts([
+        [800, 9999],
+        [990, 100],
+        [1000, 105],
+      ]),
+      105,
+      BUFFER
+    );
+    expect(wt.rangeToMax).toBeLessThan(200);
+  });
+
+  it('leaves the previously-computed target range untouched when no points are visible', () => {
+    // Documented invariant: rangeTo is only overwritten when the target window
+    // actually contains data. An unconditional assignment would collapse the
+    // Y range onto the current value for an empty window.
+    const wt = wtState({ to: 20, rangeToMin: 42, rangeToMax: 84 });
+    updateWindowTransition(
+      cfg({ windowSecs: 100 }),
+      wt,
+      20,
+      90,
+      110,
+      false,
+      NOW_MS,
+      NOW,
+      pts([[100, 5]]),
+      105,
+      BUFFER
+    );
+    expect(wt.rangeToMin).toBe(42);
+    expect(wt.rangeToMax).toBe(84);
+  });
+
+  it('does not re-trigger while the same window stays selected', () => {
+    const wt = wtState({ to: 20 });
+    const points = pts([
+      [990, 100],
+      [1000, 105],
+    ]);
+    updateWindowTransition(
+      cfg({ windowSecs: 100 }),
+      wt,
+      20,
+      90,
+      110,
+      false,
+      NOW_MS,
+      NOW,
+      points,
+      105,
+      BUFFER
+    );
+    updateWindowTransition(
+      cfg({ windowSecs: 100 }),
+      wt,
+      55,
+      1,
+      2,
+      false,
+      NOW_MS + 300,
+      NOW,
+      points,
+      105,
+      BUFFER
+    );
+    // A restart would move startMs forward and clobber the captured `from`.
+    expect(wt.startMs).toBe(NOW_MS);
+    expect(wt.from).toBe(20);
+    expect(wt.rangeFromMin).toBe(90);
+  });
+});
+
+describe('updateWindowTransition — progress curve', () => {
+  const points = pts([
+    [990, 100],
+    [1000, 105],
+  ]);
+
+  it('snaps straight to the target window under noMotion', () => {
+    const wt = wtState({ to: 20 });
+    const r = updateWindowTransition(
+      cfg({ windowSecs: 100 }),
+      wt,
+      20,
+      90,
+      110,
+      true,
+      50_000,
+      1000,
+      points,
+      105,
+      0.05
+    );
+    expect(r.windowSecs).toBe(100);
+    expect(r.windowTransProgress).toBe(0);
+  });
+
+  it('reports the resting window with zero progress when no transition is running', () => {
+    const wt = wtState({ to: 100, startMs: 0 });
+    const r = updateWindowTransition(
+      cfg({ windowSecs: 100 }),
+      wt,
+      100,
+      90,
+      110,
+      false,
+      50_000,
+      1000,
+      points,
+      105,
+      0.05
+    );
+    expect(r.windowSecs).toBe(100);
+    expect(r.windowTransProgress).toBe(0);
+  });
+
+  it('interpolates the window in LOG space — the halfway point is the geometric mean', () => {
+    // 10s → 40s. easeInOutCos(0.5) === 0.5, so halfway through the duration
+    // logLerp gives sqrt(10 * 40) = 20. A linear lerp would give 25 — this is
+    // the single assertion that pins window morphing to log space.
+    const wt = wtState({ to: 10, startMs: 0 });
+    updateWindowTransition(
+      cfg({ windowSecs: 40 }),
+      wt,
+      10,
+      90,
+      110,
+      false,
+      1000,
+      1000,
+      points,
+      105,
+      0.05
+    );
+    const r = updateWindowTransition(
+      cfg({ windowSecs: 40 }),
+      wt,
+      10,
+      90,
+      110,
+      false,
+      1000 + WINDOW_TRANSITION_MS / 2,
+      1000,
+      points,
+      105,
+      0.05
+    );
+    expect(r.windowTransProgress).toBeCloseTo(0.5, 12);
+    expect(r.windowSecs).toBeCloseTo(20, 10);
+    expect(r.windowSecs).not.toBeCloseTo(25, 1);
+  });
+
+  it('eases in and out — quarter-way through is not a quarter of the way there', () => {
+    const wt = wtState({ to: 10, startMs: 0 });
+    updateWindowTransition(
+      cfg({ windowSecs: 40 }),
+      wt,
+      10,
+      90,
+      110,
+      false,
+      1000,
+      1000,
+      points,
+      105,
+      0.05
+    );
+    const r = updateWindowTransition(
+      cfg({ windowSecs: 40 }),
+      wt,
+      10,
+      90,
+      110,
+      false,
+      1000 + WINDOW_TRANSITION_MS / 4,
+      1000,
+      points,
+      105,
+      0.05
+    );
+    // easeInOutCos(0.25) = (1 - cos(pi/4)) / 2 ≈ 0.14645 — a linear ramp would
+    // report 0.25 here.
+    expect(r.windowTransProgress).toBeCloseTo(0.14644660940672627, 12);
+  });
+
+  it('lands exactly on the configured window and clears the transition when time runs out', () => {
+    const wt = wtState({ to: 10, startMs: 0 });
+    updateWindowTransition(
+      cfg({ windowSecs: 40 }),
+      wt,
+      10,
+      90,
+      110,
+      false,
+      1000,
+      1000,
+      points,
+      105,
+      0.05
+    );
+    const r = updateWindowTransition(
+      cfg({ windowSecs: 40 }),
+      wt,
+      10,
+      90,
+      110,
+      false,
+      1000 + WINDOW_TRANSITION_MS,
+      1000,
+      points,
+      105,
+      0.05
+    );
+    // Exactness matters: logLerp(from, to, 1) is only approximately `to`, and
+    // a residual epsilon here keeps the range/grid caches invalidating forever.
+    expect(r.windowSecs).toBe(40);
+    expect(r.windowTransProgress).toBe(0);
+    expect(wt.startMs).toBe(0);
+  });
+
+  it('is driven by wall clock, so 60Hz and 120Hz stepping agree at every instant', () => {
+    // Sampled at shared instants, with the intervening frames actually
+    // stepped through — so a rewrite that accumulated progress per frame
+    // instead of reading the clock would come out ahead at 120Hz.
+    const START = 1000;
+    const INSTANTS = [1150, 1300, 1450, 1600, 1700];
+    const call = (wt: WindowTransState, now_ms: number) =>
+      updateWindowTransition(
+        cfg({ windowSecs: 40 }),
+        wt,
+        10,
+        90,
+        110,
+        false,
+        now_ms,
+        1000,
+        points,
+        105,
+        0.05
+      ).windowSecs;
+
+    const run = (frameMs: number): number[] => {
+      const wt = wtState({ to: 10, startMs: 0 });
+      call(wt, START);
+      const out: number[] = [];
+      let t = frameMs;
+      for (const instant of INSTANTS) {
+        for (; t < instant; t += frameMs) call(wt, t);
+        out.push(call(wt, instant));
+      }
+      return out;
+    };
+
+    const at60 = run(1000 / 60);
+    const at120 = run(1000 / 120);
+    expect(at60).toEqual(at120);
+    // sanity: the samples are actually mid-flight, not all pinned at 40
+    expect(at60[0]).toBeLessThan(40);
+    expect(at60[0]).toBeGreaterThan(10);
+  });
+});
+
+// ── updateRange ────────────────────────────────────────────────────────────
+
+const RANGE_WT = {
+  from: 0,
+  to: 0,
+  startMs: 0,
+  rangeFromMin: 0,
+  rangeFromMax: 100,
+  rangeToMin: 50,
+  rangeToMax: 150,
+};
+
+describe('updateRange — first frame', () => {
+  it('adopts the computed range verbatim and marks itself inited', () => {
+    const r = updateRange(
+      { min: 3, max: 7 },
+      false,
+      -1,
+      -1,
+      -1,
+      -1,
+      false,
+      0,
+      wtState(),
+      0.08,
+      300,
+      16.67
+    );
+    expect(r).toEqual({
+      minVal: 3,
+      maxVal: 7,
+      valRange: 4,
+      targetMin: 3,
+      targetMax: 7,
+      displayMin: 3,
+      displayMax: 7,
+      rangeInited: true,
+    });
+  });
+
+  it('never reports a zero valRange (it is a divisor for every toY)', () => {
+    const r = updateRange(
+      { min: 5, max: 5 },
+      false,
+      0,
+      0,
+      0,
+      0,
+      false,
+      0,
+      wtState(),
+      0.08,
+      300,
+      16.67
+    );
+    expect(r.valRange).toBe(0.001);
+  });
+});
+
+describe('updateRange — during a window transition', () => {
+  it('blends linearly between the captured from/to ranges by progress alone', () => {
+    const r = updateRange(
+      { min: 999, max: 999 },
+      true,
+      0,
+      0,
+      /* displayMin */ 1234,
+      /* displayMax */ 5678,
+      true,
+      0.25,
+      { ...wtState(), ...RANGE_WT },
+      0.08,
+      300,
+      16.67
+    );
+    // 0 → 50 at 25% = 12.5; 100 → 150 at 25% = 112.5. The incoming
+    // display values are ignored outright while transitioning.
+    expect(r.displayMin).toBe(12.5);
+    expect(r.displayMax).toBe(112.5);
+    expect(r.minVal).toBe(12.5);
+    expect(r.maxVal).toBe(112.5);
+  });
+
+  it('still tracks the computed range as the target for when the transition ends', () => {
+    const r = updateRange(
+      { min: 42, max: 84 },
+      true,
+      0,
+      0,
+      1234,
+      5678,
+      true,
+      0.25,
+      { ...wtState(), ...RANGE_WT },
+      0.08,
+      300,
+      16.67
+    );
+    expect(r.targetMin).toBe(42);
+    expect(r.targetMax).toBe(84);
+  });
+
+  it('reaches the captured target range exactly at full progress', () => {
+    const r = updateRange(
+      { min: 0, max: 0 },
+      true,
+      0,
+      0,
+      0,
+      0,
+      true,
+      1,
+      { ...wtState(), ...RANGE_WT },
+      0.08,
+      300,
+      16.67
+    );
+    expect(r.displayMin).toBe(50);
+    expect(r.displayMax).toBe(150);
+  });
+});
+
+describe('updateRange — steady-state lerp', () => {
+  /** Runs `frames` frames of `dt` ms each, returning the final display range. */
+  function run(frames: number, dt: number, chartH: number) {
+    let displayMin = 0;
+    let displayMax = 100;
+    for (let i = 0; i < frames; i++) {
+      const r = updateRange(
+        { min: 40, max: 160 },
+        true,
+        0,
+        0,
+        displayMin,
+        displayMax,
+        false,
+        0,
+        wtState(),
+        0.08,
+        chartH,
+        dt
+      );
+      displayMin = r.displayMin;
+      displayMax = r.displayMax;
+    }
+    return { displayMin, displayMax };
+  }
+
+  it('is frame-rate independent: 100ms at 60Hz and 100ms at 120Hz land on the same value', () => {
+    // 100ms is deliberately mid-flight — long enough to diverge, short enough
+    // that neither rate has converged (which would make the test vacuous).
+    // chartH is huge so the pixel snap can never mask a difference.
+    const at60 = run(6, 1000 / 60, 1e9);
+    const at120 = run(12, 1000 / 120, 1e9);
+    expect(at60.displayMin).toBeGreaterThan(5);
+    expect(at60.displayMin).toBeLessThan(35);
+    expect(at120.displayMin).toBeCloseTo(at60.displayMin, 8);
+    expect(at120.displayMax).toBeCloseTo(at60.displayMax, 8);
+  });
+
+  it('a naive per-frame lerp WOULD fail that test — the two rates diverge visibly', () => {
+    const naive = (frames: number) => {
+      let v = 0;
+      for (let i = 0; i < frames; i++) v = naiveLerp(v, 40, 0.08);
+      return v;
+    };
+    // Same 100ms of wall clock, double the frames: the dt-blind version is
+    // most of the way there at 120Hz and barely started at 60Hz.
+    expect(Math.abs(naive(12) - naive(6))).toBeGreaterThan(5);
+  });
+
+  it('converges monotonically without overshoot', () => {
+    let displayMin = 0;
+    let prev = -Infinity;
+    for (let i = 0; i < 200; i++) {
+      const r = updateRange(
+        { min: 40, max: 160 },
+        true,
+        0,
+        0,
+        displayMin,
+        100,
+        false,
+        0,
+        wtState(),
+        0.08,
+        1e9,
+        1000 / 60
+      );
+      expect(r.displayMin).toBeGreaterThanOrEqual(prev);
+      expect(r.displayMin).toBeLessThanOrEqual(40);
+      prev = r.displayMin;
+      displayMin = r.displayMin;
+    }
+  });
+
+  it('snaps to a BIT-EXACT target once inside the sub-pixel threshold', () => {
+    // Exactness is the property under test: engine/step.ts's caches key off
+    // displayMin/displayMax, so an epsilon of residual drift rebuilds chart
+    // geometry every single frame forever. `toBeCloseTo` would not catch that.
+    const { displayMin, displayMax } = run(300, 1000 / 60, 300);
+    expect(displayMin).toBe(40);
+    expect(displayMax).toBe(160);
+  });
+
+  it('an unsnapped exponential lerp would never reach the target exactly', () => {
+    // Proves the previous test is testing the snap and not just the lerp.
+    let v = 0;
+    for (let i = 0; i < 300; i++) v = naiveLerp(v, 40, 0.08);
+    expect(v).not.toBe(40);
+    expect(v).toBeLessThan(40);
+  });
+
+  it('keeps a positive snap threshold when the display range is degenerate', () => {
+    // curRange 0 → (0.5 * 0) / chartH === 0 → falls back to 0.001, so a
+    // collapsed range can still converge instead of stalling on a zero
+    // threshold.
+    let displayMin = 5;
+    let displayMax = 5;
+    for (let i = 0; i < 400; i++) {
+      const r = updateRange(
+        { min: 5, max: 5.0005 },
+        true,
+        0,
+        0,
+        displayMin,
+        displayMax,
+        false,
+        0,
+        wtState(),
+        0.08,
+        300,
+        1000 / 60
+      );
+      displayMin = r.displayMin;
+      displayMax = r.displayMax;
+    }
+    expect(displayMax).toBe(5.0005);
+  });
+});
+
+// ── updateHoverState ───────────────────────────────────────────────────────
+
+describe('updateHoverState — hit testing', () => {
+  const W = 210;
+  const CHART_W = 180;
+  const layout = makeLayout(0, 100, W, CHART_W);
+  const visible = pts([
+    [0, 0],
+    [50, 50],
+    [100, 100],
+  ]);
+
+  const call = (
+    hoverPixelX: number | null,
+    scrubAmount = 0,
+    lastHover: { x: number; value: number; time: number } | null = null,
+    now = 100
+  ) =>
+    updateHoverState(
+      hoverPixelX,
+      PAD,
+      W,
+      layout,
+      now,
+      visible,
+      scrubAmount,
+      lastHover,
+      false,
+      0,
+      100,
+      CHART_W
+    );
+
+  it('maps a pixel inside the plot area to an interpolated time and value', () => {
+    const r = call(55);
+    // (55 - 10) / 180 * 100 = 25
+    expect(r.hoverTime).toBe(25);
+    expect(r.hoverValue).toBe(25);
+    expect(r.hoverX).toBe(55);
+    expect(r.isActiveHover).toBe(true);
+  });
+
+  it('includes both padding edges (inclusive bounds)', () => {
+    expect(call(PAD.left).isActiveHover).toBe(true);
+    expect(call(W - PAD.right).isActiveHover).toBe(true);
+  });
+
+  it('rejects a pixel one unit outside either padding edge', () => {
+    expect(call(PAD.left - 1).isActiveHover).toBe(false);
+    expect(call(W - PAD.right + 1).isActiveHover).toBe(false);
+  });
+
+  it('clamps the hover to the live edge so you cannot scrub into the future', () => {
+    // now = 50 → maxHoverX = toX(50) = 100. Dropping the clamp would report
+    // t = 100 / value = 100, i.e. data that does not exist yet.
+    const r = call(190, 0, null, 50);
+    expect(r.hoverX).toBe(100);
+    expect(r.hoverTime).toBe(50);
+    expect(r.hoverValue).toBe(50);
+  });
+
+  it('reports no hover when there is no data to interpolate', () => {
+    const r = updateHoverState(
+      55,
+      PAD,
+      W,
+      layout,
+      100,
+      [],
+      0,
+      null,
+      false,
+      0,
+      100,
+      CHART_W
+    );
+    expect(r.isActiveHover).toBe(false);
+    expect(r.hoverValue).toBeNull();
+    expect(r.emitPoint).toBeNull();
+  });
+
+  it('emits a point carrying the CLAMPED pixel position and its projected y', () => {
+    const r = call(55);
+    expect(r.emitPoint).toEqual({
+      time: 25,
+      value: 25,
+      x: 55,
+      y: layout.toY(25),
+    });
+  });
+
+  it('emits nothing on a frame with no active hover', () => {
+    expect(call(null, 1, { x: 55, value: 25, time: 25 }).emitPoint).toBeNull();
+  });
+});
+
+describe('updateHoverState — scrub fade', () => {
+  const W = 210;
+  const CHART_W = 180;
+  const layout = makeLayout(0, 100, W, CHART_W);
+  const visible = pts([
+    [0, 0],
+    [100, 100],
+  ]);
+
+  const step = (
+    hoverPixelX: number | null,
+    scrubAmount: number,
+    lastHover: { x: number; value: number; time: number } | null,
+    noMotion = false
+  ) =>
+    updateHoverState(
+      hoverPixelX,
+      PAD,
+      W,
+      layout,
+      100,
+      visible,
+      scrubAmount,
+      lastHover,
+      noMotion,
+      0,
+      100,
+      CHART_W
+    );
+
+  it('jumps the scrub amount to exactly 1 / 0 under noMotion', () => {
+    expect(step(55, 0, null, true).scrubAmount).toBe(1);
+    expect(step(null, 1, null, true).scrubAmount).toBe(0);
+  });
+
+  it('reaches exactly 1 after 37 frames of fade-in, and not before', () => {
+    // The scrub lerp is deliberately frame-*count* based (no dt argument), so
+    // the frame count is the behaviour. Lowering SCRUB_LERP_SPEED or adding a
+    // dt term moves this number.
+    let scrub = 0;
+    let firstExact = -1;
+    for (let i = 1; i <= 60; i++) {
+      scrub = step(55, scrub, null).scrubAmount;
+      if (scrub === 1 && firstExact === -1) firstExact = i;
+    }
+    expect(firstExact).toBe(37);
+    // sanity: the raw geometric decay predicts the same frame
+    expect(Math.ceil(Math.log(0.01) / Math.log(1 - SCRUB_LERP_SPEED))).toBe(37);
+  });
+
+  it('reaches exactly 0 on fade-out, so a settled chart can quiesce', () => {
+    // isQuiescentCandidate requires scrubAmount === 0 exactly; without the
+    // `< 0.01 → 0` snap the chart would re-record pictures forever after a
+    // single hover.
+    let scrub = 1;
+    for (let i = 0; i < 60; i++) {
+      scrub = step(null, scrub, { x: 55, value: 25, time: 25 }).scrubAmount;
+    }
+    expect(scrub).toBe(0);
+  });
+
+  it('holds the last hover position while fading out', () => {
+    const last = { x: 55, value: 25, time: 25 };
+    const r = step(null, 0.5, last);
+    expect(r.hoverX).toBe(55);
+    expect(r.hoverValue).toBe(25);
+    expect(r.hoverTime).toBe(25);
+    expect(r.isActiveHover).toBe(false);
+  });
+
+  it('drops the held position once the fade completes', () => {
+    const r = step(null, 0.005, { x: 55, value: 25, time: 25 });
+    expect(r.scrubAmount).toBe(0);
+    expect(r.hoverX).toBeNull();
+    expect(r.hoverValue).toBeNull();
+  });
+
+  it('updates the remembered hover on every active frame', () => {
+    const r = step(100, 1, { x: 55, value: 25, time: 25 });
+    expect(r.lastHover).toEqual({ x: 100, value: 50, time: 50 });
+  });
+
+  it('preserves the incoming lastHover when the pointer leaves the plot area', () => {
+    const last = { x: 55, value: 25, time: 25 };
+    expect(step(PAD.left - 1, 1, last).lastHover).toBe(last);
+  });
+});
diff --git a/src/engine/__tests__/quiescence.test.ts b/src/engine/__tests__/quiescence.test.ts
new file mode 100644
index 0000000..671943b
--- /dev/null
+++ b/src/engine/__tests__/quiescence.test.ts
@@ -0,0 +1,224 @@
+import { isQuiescentCandidate } from '../quiescence';
+import type { EngineState } from '../state';
+import type { EngineConfigStep } from '../types';
+
+// ── Fixtures ───────────────────────────────────────────────────────────────
+//
+// `isQuiescentCandidate` is a pure predicate over a handful of fields, so the
+// fixtures are deliberately narrow casts rather than full engine objects —
+// building a real `EngineState` would drag in the Skia binding and defeat the
+// point of this module being testable at all.
+
+type QuiescentConfigFields = Pick<
+  EngineConfigStep,
+  | 'paused'
+  | 'loading'
+  | 'degenOptions'
+  | 'isMultiSeries'
+  | 'multiSeries'
+  | 'showPulse'
+  | 'showMomentum'
+  | 'orderbookData'
+>;
+
+type QuiescentStateFields = Pick<
+  EngineState,
+  'pauseProgress' | 'scrubAmount' | 'loadingAlpha' | 'chartReveal'
+>;
+
+/** The all-static baseline: every condition satisfied. */
+const cfg = (over: Partial<QuiescentConfigFields> = {}): EngineConfigStep =>
+  ({
+    paused: true,
+    loading: false,
+    ...over,
+  }) as EngineConfigStep;
+
+const state = (over: Partial<QuiescentStateFields> = {}): EngineState =>
+  ({
+    pauseProgress: 1,
+    scrubAmount: 0,
+    loadingAlpha: 0,
+    chartReveal: 1,
+    ...over,
+  }) as EngineState;
+
+describe('isQuiescentCandidate — the all-static baseline', () => {
+  it('returns true when every animatable feature is at rest', () => {
+    expect(isQuiescentCandidate(cfg(), state(), null)).toBe(true);
+  });
+});
+
+describe('isQuiescentCandidate — pause is mandatory', () => {
+  // The most important single assertion in this file: a *live* chart must
+  // never quiesce, however settled every other field looks. Per the module's
+  // own docblock this is deliberate — every other condition below describes a
+  // transient animation, but `paused` describes whether new data can arrive.
+
+  it('returns false when paused is undefined (a live chart)', () => {
+    expect(
+      isQuiescentCandidate(cfg({ paused: undefined }), state(), null)
+    ).toBe(false);
+  });
+
+  it('returns false when paused is explicitly false', () => {
+    expect(isQuiescentCandidate(cfg({ paused: false }), state(), null)).toBe(
+      false
+    );
+  });
+
+  it('requires the pause settle animation to have finished, not merely started', () => {
+    // pauseProgress drives badge alpha, the pulse ring gate and the candle
+    // glow cut-off; anything short of exactly 1 still has motion in it.
+    expect(
+      isQuiescentCandidate(cfg(), state({ pauseProgress: 0.999 }), null)
+    ).toBe(false);
+    expect(isQuiescentCandidate(cfg(), state({ pauseProgress: 1 }), null)).toBe(
+      true
+    );
+  });
+});
+
+describe('isQuiescentCandidate — each break condition independently', () => {
+  it('hover: an active hover at pixel x=0 breaks quiescence', () => {
+    // x=0 is a legitimate hover position at the very left of the canvas. A
+    // falsy check (`!hoverPixelX`) instead of `=== null` would wrongly report
+    // this frame as static and freeze the crosshair mid-drag.
+    expect(isQuiescentCandidate(cfg(), state(), 0)).toBe(false);
+  });
+
+  it('hover: any non-null hover pixel breaks quiescence', () => {
+    expect(isQuiescentCandidate(cfg(), state(), 120)).toBe(false);
+  });
+
+  it('scrub: a partially faded scrub overlay breaks quiescence', () => {
+    expect(
+      isQuiescentCandidate(cfg(), state({ scrubAmount: 0.001 }), null)
+    ).toBe(false);
+  });
+
+  it('loading: cfg.loading breaks quiescence even once its alpha settled', () => {
+    expect(
+      isQuiescentCandidate(
+        cfg({ loading: true }),
+        state({ loadingAlpha: 1 }),
+        null
+      )
+    ).toBe(false);
+  });
+
+  it('loading: a mid-crossfade alpha breaks quiescence even once cfg.loading cleared', () => {
+    // The two loading conditions are not redundant: cfg.loading goes false on
+    // the commit that supplies data, but loadingAlpha keeps fading for ~1s
+    // afterwards. Dropping either check alone leaks a visible crossfade.
+    expect(
+      isQuiescentCandidate(
+        cfg({ loading: false }),
+        state({ loadingAlpha: 0.5 }),
+        null
+      )
+    ).toBe(false);
+  });
+
+  it('reveal: an incomplete chart reveal morph breaks quiescence', () => {
+    expect(
+      isQuiescentCandidate(cfg(), state({ chartReveal: 0.999 }), null)
+    ).toBe(false);
+  });
+
+  it('degen: an empty-but-present degenOptions object breaks quiescence', () => {
+    // degenOptions gates particles and chart shake, both driven by
+    // Math.random() every frame. Presence is what matters, not contents.
+    expect(isQuiescentCandidate(cfg({ degenOptions: {} }), state(), null)).toBe(
+      false
+    );
+  });
+});
+
+describe('isQuiescentCandidate — multi-series needs all three sub-conditions', () => {
+  const series = [{ id: 'a', value: 1, palette: {} as never }];
+
+  it('breaks quiescence only when the flag, the array and a non-empty array all hold', () => {
+    expect(
+      isQuiescentCandidate(
+        cfg({ isMultiSeries: true, multiSeries: series }),
+        state(),
+        null
+      )
+    ).toBe(false);
+  });
+
+  it('stays quiescent when the flag is off even though a series array is present', () => {
+    // Single-series charts carry a stale multiSeries array across a mode
+    // switch; keying off the array alone would permanently disable quiescence
+    // for them.
+    expect(
+      isQuiescentCandidate(
+        cfg({ isMultiSeries: false, multiSeries: series }),
+        state(),
+        null
+      )
+    ).toBe(true);
+  });
+
+  it('stays quiescent when the flag is on but the series array is empty', () => {
+    expect(
+      isQuiescentCandidate(
+        cfg({ isMultiSeries: true, multiSeries: [] }),
+        state(),
+        null
+      )
+    ).toBe(true);
+  });
+
+  it('stays quiescent when the flag is on but the series array is absent', () => {
+    expect(
+      isQuiescentCandidate(
+        cfg({ isMultiSeries: true, multiSeries: undefined }),
+        state(),
+        null
+      )
+    ).toBe(true);
+  });
+});
+
+describe('isQuiescentCandidate — deliberate non-conditions', () => {
+  // These three are documented in quiescence.ts as intentionally absent.
+  // Adding any of them as a condition would silently disable quiescence for
+  // the majority of charts (pulse defaults to true), which is exactly the
+  // "perf cliff with no visual symptom" this module exists to avoid.
+
+  it('showPulse does not break quiescence (the ring is already gated off at full pause)', () => {
+    expect(isQuiescentCandidate(cfg({ showPulse: true }), state(), null)).toBe(
+      true
+    );
+  });
+
+  it('showMomentum does not break quiescence (arrow alpha is forced to 0 at full pause)', () => {
+    expect(
+      isQuiescentCandidate(cfg({ showMomentum: true }), state(), null)
+    ).toBe(true);
+  });
+
+  it('orderbookData does not break quiescence (its labels now run on pausedDt)', () => {
+    expect(
+      isQuiescentCandidate(
+        cfg({ orderbookData: { bids: [], asks: [] } as never }),
+        state(),
+        null
+      )
+    ).toBe(true);
+  });
+});
+
+describe('isQuiescentCandidate — purity', () => {
+  it('mutates neither the config nor the state', () => {
+    const c = cfg({ isMultiSeries: true, multiSeries: [] });
+    const s = state();
+    const cBefore = JSON.stringify(c);
+    const sBefore = JSON.stringify(s);
+    isQuiescentCandidate(c, s, 42);
+    expect(JSON.stringify(c)).toBe(cBefore);
+    expect(JSON.stringify(s)).toBe(sBefore);
+  });
+});

From 6aa05c374479e94b7f0d2c077468c3d0f1c93316 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Sat, 1 Aug 2026 13:59:16 -0400
Subject: [PATCH 22/37] perf(Liveline): keep the controls out of the tick path
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Liveline is memo'd, but a live tick produces a new `data` array so the memo
fails and the WHOLE component re-rendered — including all three control bars
and their style hooks — even though none of the controls' inputs changed. At
the example app's 300ms tick that is ~3 wasted subtree reconciliations/sec; at
its 50ms setting, 20/sec.

Adds a memo boundary at <LivelineControls>, which also calls useBarStyle and
useChipStyle inside itself so those leave the tick path too, with three memo'd
bars behind it. A tick now re-renders Liveline only; React bails at the
boundary, skipping three bars, two style hooks, three SlidingIndicators and
the two icon <Canvas>es.

The two btnLayouts maps were pushed DOWN into the bars that produce them
rather than hoisted into a hook — that state was only ever read by its own
bar, so a measurement now re-renders one bar instead of the whole chart.

The non-obvious part: consumers pass inline arrows (the example app's
onModeChange and onSeriesToggle are both inline, and `series` is rebuilt each
parent render). The parent re-renders every tick, so those props are new
identities every tick and the memo would have failed 100% of the time —
decorative rather than effective. useStableValue projects arrays through a
content signature and useStableHandler is a latest-ref wrapper, so the
guarantee holds regardless of consumer discipline rather than depending on it.

No data, value, candles, series, lineData, liveCandle or engine shared value
crosses the boundary; the chip descriptors deliberately carry id/label/color
only.

Public API unchanged: index.tsx byte-identical, LivelineProps field count
unchanged. The <Canvas> subtree is byte-identical too — verified mechanically,
not by eye, because a conditional node there would silently cost the
blocked-JS-thread guarantee.

NOT verified at runtime: react-test-renderer and @testing-library/react-native
are both absent, so Liveline cannot be mounted in jest, and the running
simulator serves the primary checkout rather than the worktree. The evidence
is a prop-by-prop static argument for tick-stability, not a measured render
count.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/Liveline.tsx | 571 +++++++++++++++++++++++++++++++++--------------
 1 file changed, 403 insertions(+), 168 deletions(-)

diff --git a/src/Liveline.tsx b/src/Liveline.tsx
index 4f4bca6..c44cbb1 100644
--- a/src/Liveline.tsx
+++ b/src/Liveline.tsx
@@ -32,7 +32,12 @@ import Animated, {
   withTiming,
 } from 'react-native-reanimated';
 import { GestureDetector } from 'react-native-gesture-handler';
-import type { LivelineProps, Momentum, DegenOptions } from './types';
+import type {
+  LivelineProps,
+  Momentum,
+  DegenOptions,
+  WindowOption,
+} from './types';
 import { resolveTheme, resolveSeriesPalettes, SERIES_COLORS } from './theme';
 import { makeDefaultFonts } from './draw/fonts';
 import { useLivelineEngine } from './useLivelineEngine';
@@ -63,6 +68,101 @@ interface BtnLayout {
   width: number;
 }
 
+/**
+ * `useMemo` keyed by an explicit signature instead of a dependency array.
+ *
+ * A live chart re-renders on every tick, and consumers build most array props
+ * inline, so those arrays are a new *identity* every tick even when nothing in
+ * them changed. Projecting them through here gives the control bars props that
+ * are referentially stable, which is what lets their `memo` actually bail out.
+ */
+function useStableValue<T>(signature: string, build: () => T): T {
+  const ref = useRef<{ signature: string; value: T } | null>(null);
+  if (ref.current === null || ref.current.signature !== signature) {
+    ref.current = { signature, value: build() };
+  }
+  return ref.current.value;
+}
+
+/**
+ * A referentially stable wrapper around an optional consumer callback. Same
+ * reasoning as `useStableValue`: `onModeChange` &co. are typically inline
+ * arrows, so they are a new function on every consumer render. The wrapper is
+ * created once and always dispatches to the latest prop.
+ */
+function useStableHandler<A extends unknown[]>(
+  fn: ((...args: A) => void) | undefined
+) {
+  const ref = useRef(fn);
+  ref.current = fn;
+  return useCallback((...args: A) => ref.current?.(...args), []);
+}
+
+/**
+ * State for the built-in window selector. Only meaningful when `windows` is
+ * supplied; otherwise the `window` prop stays authoritative and this state
+ * sits inert (kept mounted so it survives `windows` appearing later).
+ */
+function useActiveWindow(
+  windows: WindowOption[] | undefined,
+  windowSecs: number,
+  onWindowChange: ((secs: number) => void) | undefined
+) {
+  const [activeWindowSecs, setActiveWindowSecs] = useState(
+    windows && windows.length > 0 ? windows[0]!.secs : windowSecs
+  );
+  const notify = useStableHandler(onWindowChange);
+  const selectWindow = useCallback(
+    (secs: number) => {
+      setActiveWindowSecs(secs);
+      notify(secs);
+    },
+    [notify]
+  );
+  return {
+    activeWindowSecs,
+    effectiveWindowSecs: windows ? activeWindowSecs : windowSecs,
+    selectWindow,
+  };
+}
+
+/** Which series the user has toggled off, plus the engine-facing id list. */
+function useHiddenSeries(
+  seriesCount: number,
+  onSeriesToggle: ((id: string, visible: boolean) => void) | undefined
+) {
+  const [hiddenSeries, setHiddenSeries] = useState<Set<string>>(new Set());
+  const notify = useStableHandler(onSeriesToggle);
+  // Read through a ref so the toggle handler stays referentially stable as
+  // series come and go — it crosses the `memo` boundary into the chip bar.
+  const countRef = useRef(seriesCount);
+  countRef.current = seriesCount;
+
+  const toggleSeries = useCallback(
+    (id: string) => {
+      setHiddenSeries((prev) => {
+        const next = new Set(prev);
+        if (next.has(id)) {
+          next.delete(id);
+          notify(id, true);
+        } else {
+          // Count visible series — don't hide last one
+          const visibleCount = countRef.current - next.size;
+          if (visibleCount <= 1) return prev;
+          next.add(id);
+          notify(id, false);
+        }
+        return next;
+      });
+    },
+    [notify]
+  );
+
+  const hiddenSeriesIds = useMemo(() => [...hiddenSeries], [hiddenSeries]);
+
+  return { hiddenSeries, hiddenSeriesIds, toggleSeries };
+}
+
 /** Sliding indicator behind the active button in a pill bar. */
 function SlidingIndicator({
   layout,
@@ -282,6 +382,258 @@ function CandleIcon({ color }: { color: string }) {
   );
 }
 
+/** Time-window selector. Owns the button layouts its indicator tracks. */
+const WindowBar = memo(function WindowBarComponent({
+  bar,
+  isDark,
+  windows,
+  activeSecs,
+  onSelect,
+}: {
+  bar: BarStyle;
+  isDark: boolean;
+  windows: WindowOption[];
+  activeSecs: number;
+  onSelect: (secs: number) => void;
+}) {
+  const [layouts, setLayouts] = useState<Record<number, BtnLayout>>({});
+  const onBtnLayout = useCallback((secs: number, e: LayoutChangeEvent) => {
+    const { x, width } = e.nativeEvent.layout;
+    setLayouts((prev) => {
+      const cur = prev[secs];
+      if (cur && cur.x === x && cur.width === width) return prev;
+      return { ...prev, [secs]: { x, width } };
+    });
+  }, []);
+
+  return (
+    <PillBar
+      bar={bar}
+      isDark={isDark}
+      indicator
+      indicatorLayout={layouts[activeSecs]}
+    >
+      {windows.map((w) => {
+        const isActive = w.secs === activeSecs;
+        return (
+          <Pressable
+            key={w.secs}
+            onLayout={(e) => onBtnLayout(w.secs, e)}
+            onPress={() => onSelect(w.secs)}
+            style={bar.pill}
+          >
+            <Animated.Text
+              style={isActive ? bar.labelActive : bar.labelInactive}
+            >
+              {w.label}
+            </Animated.Text>
+          </Pressable>
+        );
+      })}
+    </PillBar>
+  );
+});
+
+/** Line/candle mode toggle — its own bar with its own sliding indicator. */
+const ModeBar = memo(function ModeBarComponent({
+  bar,
+  isDark,
+  activeMode,
+  onSelect,
+}: {
+  bar: BarStyle;
+  isDark: boolean;
+  activeMode: 'line' | 'candle';
+  onSelect: (mode: 'line' | 'candle') => void;
+}) {
+  const [layouts, setLayouts] = useState<Record<string, BtnLayout>>({});
+  const onBtnLayout = useCallback((key: string, e: LayoutChangeEvent) => {
+    const { x, width } = e.nativeEvent.layout;
+    setLayouts((prev) => {
+      const cur = prev[key];
+      if (cur && cur.x === x && cur.width === width) return prev;
+      return { ...prev, [key]: { x, width } };
+    });
+  }, []);
+
+  return (
+    <PillBar
+      bar={bar}
+      isDark={isDark}
+      indicator
+      indicatorLayout={layouts[activeMode]}
+    >
+      <Pressable
+        onLayout={(e) => onBtnLayout('line', e)}
+        onPress={() => onSelect('line')}
+        style={[styles.iconBtn, bar.iconBtn]}
+      >
+        <LineIcon
+          color={activeMode === 'line' ? bar.activeColor : bar.inactiveColor}
+          active={activeMode === 'line'}
+        />
+      </Pressable>
+      <Pressable
+        onLayout={(e) => onBtnLayout('candle', e)}
+        onPress={() => onSelect('candle')}
+        style={[styles.iconBtn, bar.iconBtn]}
+      >
+        <CandleIcon
+          color={activeMode === 'candle' ? bar.activeColor : bar.inactiveColor}
+        />
+      </Pressable>
+    </PillBar>
+  );
+});
+
+/**
+ * What a series chip needs to draw itself — deliberately *not* the series
+ * itself, whose `data`/`value` change on every tick.
+ */
+interface SeriesChip {
+  id: string;
+  label: string;
+  color: string;
+}
+
+/**
+ * Series toggle chips. No sliding indicator — chips toggle independently, so
+ * there is no single "active" one to track.
+ */
+const SeriesChipBar = memo(function SeriesChipBarComponent({
+  bar,
+  chip,
+  isDark,
+  chips,
+  hidden,
+  compact,
+  faded,
+  onToggle,
+}: {
+  bar: BarStyle;
+  chip: ReturnType<typeof useChipStyle>;
+  isDark: boolean;
+  chips: SeriesChip[];
+  hidden: Set<string>;
+  compact: boolean;
+  /** Keep the chips mounted but invisible (chart left multi-series mode). */
+  faded: boolean;
+  onToggle: (id: string) => void;
+}) {
+  return (
+    <PillBar bar={bar} isDark={isDark} faded={faded}>
+      {chips.map((s) => {
+        const isHidden = hidden.has(s.id);
+        return (
+          <Pressable
+            key={s.id}
+            onPress={() => onToggle(s.id)}
+            style={[chip.base, isHidden && chip.off]}
+          >
+            <View
+              style={[
+                chip.dot,
+                { backgroundColor: s.color },
+                isHidden && styles.dimmed,
+              ]}
+            />
+            {!compact && (
+              <Animated.Text style={isHidden ? chip.labelOff : chip.label}>
+                {s.label}
+              </Animated.Text>
+            )}
+          </Pressable>
+        );
+      })}
+    </PillBar>
+  );
+});
+
+/**
+ * The whole controls row, above the chart.
+ *
+ * Memoized, and this is the point of the whole file's shape: a live tick hands
+ * `Liveline` a new `data` array every frame, so `Liveline` itself re-renders
+ * constantly. None of the props below change on a tick, so React bails out
+ * here and the three bars, their style hooks and their `<Canvas>` icons are
+ * skipped entirely. Nothing tick-varying may be added to this prop list.
+ */
+const LivelineControls = memo(function LivelineControlsComponent({
+  windowStyle,
+  isDark,
+  padLeft,
+  windows,
+  activeWindowSecs,
+  onWindowSelect,
+  showModeToggle,
+  activeMode,
+  onModeSelect,
+  showSeriesToggle,
+  seriesChips,
+  seriesFaded,
+  hiddenSeries,
+  seriesToggleCompact,
+  onSeriesToggle,
+}: {
+  windowStyle: WindowStyle;
+  isDark: boolean;
+  padLeft: number;
+  windows: WindowOption[] | undefined;
+  activeWindowSecs: number;
+  onWindowSelect: (secs: number) => void;
+  showModeToggle: boolean;
+  activeMode: 'line' | 'candle';
+  onModeSelect: (mode: 'line' | 'candle') => void;
+  showSeriesToggle: boolean;
+  seriesChips: SeriesChip[];
+  seriesFaded: boolean;
+  hiddenSeries: Set<string>;
+  seriesToggleCompact: boolean;
+  onSeriesToggle: (id: string) => void;
+}) {
+  const bar = useBarStyle(windowStyle, isDark);
+  const chip = useChipStyle(bar, isDark, seriesToggleCompact);
+
+  const showWindows = windows != null && windows.length > 0;
+  if (!showWindows && !showModeToggle && !showSeriesToggle) return null;
+
+  return (
+    <View style={[styles.controlsRow, { marginLeft: padLeft }]}>
+      {showWindows && (
+        <WindowBar
+          bar={bar}
+          isDark={isDark}
+          windows={windows}
+          activeSecs={activeWindowSecs}
+          onSelect={onWindowSelect}
+        />
+      )}
+
+      {showModeToggle && (
+        <ModeBar
+          bar={bar}
+          isDark={isDark}
+          activeMode={activeMode}
+          onSelect={onModeSelect}
+        />
+      )}
+
+      {showSeriesToggle && (
+        <SeriesChipBar
+          bar={bar}
+          chip={chip}
+          isDark={isDark}
+          chips={seriesChips}
+          hidden={hiddenSeries}
+          compact={seriesToggleCompact}
+          faded={seriesFaded}
+          onToggle={onSeriesToggle}
+        />
+      )}
+    </View>
+  );
+});
+
 /**
  * Memoized: in a list of charts (the `active`-prop scenario), unrelated
  * parent re-renders must not re-render every row. Live ticks still pass
@@ -338,13 +690,6 @@ export const Liveline = memo(function LivelineComponent({
   fonts: fontsOverride,
   style,
 }: LivelineProps) {
-  const [windowBtnLayouts, setWindowBtnLayouts] = useState<
-    Record<number, BtnLayout>
-  >({});
-  const [modeBtnLayouts, setModeBtnLayouts] = useState<
-    Record<string, BtnLayout>
-  >({});
-  const [hiddenSeries, setHiddenSeries] = useState<Set<string>>(new Set());
   const lastSeriesPropRef = useRef(seriesProp);
   if (seriesProp && seriesProp.length > 0)
     lastSeriesPropRef.current = seriesProp;
@@ -408,38 +753,16 @@ export const Liveline = memo(function LivelineComponent({
       : {}
     : undefined;
 
-  // Window buttons state
-  const [activeWindowSecs, setActiveWindowSecs] = useState(
-    windows && windows.length > 0 ? windows[0]!.secs : windowSecs
-  );
-  const effectiveWindowSecs = windows ? activeWindowSecs : windowSecs;
+  const { activeWindowSecs, effectiveWindowSecs, selectWindow } =
+    useActiveWindow(windows, windowSecs, onWindowChange);
 
-  // Series toggle handler — prevent hiding the last visible series
-  const handleSeriesToggle = useCallback(
-    (id: string) => {
-      setHiddenSeries((prev) => {
-        const next = new Set(prev);
-        if (next.has(id)) {
-          next.delete(id);
-          onSeriesToggle?.(id, true);
-        } else {
-          // Count visible series — don't hide last one
-          const totalSeries = seriesProp?.length ?? 0;
-          const visibleCount = totalSeries - next.size;
-          if (visibleCount <= 1) return prev;
-          next.add(id);
-          onSeriesToggle?.(id, false);
-        }
-        return next;
-      });
-    },
-    [seriesProp?.length, onSeriesToggle]
+  const { hiddenSeries, hiddenSeriesIds, toggleSeries } = useHiddenSeries(
+    seriesProp?.length ?? 0,
+    onSeriesToggle
   );
 
   const ws = windowStyle ?? 'default';
 
-  const hiddenSeriesIds = useMemo(() => [...hiddenSeries], [hiddenSeries]);
-
   const engine = useLivelineEngine(
     {
       data,
@@ -502,31 +825,32 @@ export const Liveline = memo(function LivelineComponent({
         : defaultValueColor,
   }));
 
-  const bar = useBarStyle(ws, isDark);
-  const chip = useChipStyle(bar, isDark, seriesToggleCompact);
-
   const activeMode = lineMode ? 'line' : 'candle';
 
-  const onWindowBtnLayout = useCallback(
-    (secs: number, e: LayoutChangeEvent) => {
-      const { x, width } = e.nativeEvent.layout;
-      setWindowBtnLayouts((prev) => {
-        const cur = prev[secs];
-        if (cur && cur.x === x && cur.width === width) return prev;
-        return { ...prev, [secs]: { x, width } };
-      });
-    },
-    []
+  // --- Controls-row props ---------------------------------------------------
+  // Everything below exists to keep <LivelineControls/> memo-stable across a
+  // tick: consumers rebuild `windows`/`series` inline and pass inline arrow
+  // callbacks, so those identities churn even when their contents do not.
+  const windowsSignature = windows
+    ? `${windows.length}|${windows.map((w) => `${w.secs}${w.label}`).join('
')}`
+    : '';
+  const stableWindows = useStableValue(windowsSignature, () => windows);
+
+  const chipSource = lastSeriesPropRef.current;
+  const chipSignature = chipSource
+    ? `${chipSource.length}|${chipSource
+        .map((s) => `${s.id}${s.label ?? ''}${s.color ?? ''}`)
+        .join('
')}`
+    : '';
+  const seriesChips = useStableValue(chipSignature, () =>
+    (chipSource ?? []).map((s, si) => ({
+      id: s.id,
+      label: s.label ?? s.id,
+      color: s.color || SERIES_COLORS[si % SERIES_COLORS.length]!,
+    }))
   );
 
-  const onModeBtnLayout = useCallback((key: string, e: LayoutChangeEvent) => {
-    const { x, width } = e.nativeEvent.layout;
-    setModeBtnLayouts((prev) => {
-      const cur = prev[key];
-      if (cur && cur.x === x && cur.width === width) return prev;
-      return { ...prev, [key]: { x, width } };
-    });
-  }, []);
+  const selectMode = useStableHandler(onModeChange);
 
   return (
     <>
@@ -539,118 +863,29 @@ export const Liveline = memo(function LivelineComponent({
         />
       )}
 
-      {/* Control bars row — window pills + mode toggle + series chips side by side */}
-      {((windows && windows.length > 0) ||
-        onModeChange ||
-        showSeriesToggle) && (
-        <View style={[styles.controlsRow, { marginLeft: pad.left }]}>
-          {/* Time window controls */}
-          {windows && windows.length > 0 && (
-            <PillBar
-              bar={bar}
-              isDark={isDark}
-              indicator
-              indicatorLayout={windowBtnLayouts[activeWindowSecs]}
-            >
-              {windows.map((w) => {
-                const isActive = w.secs === activeWindowSecs;
-                return (
-                  <Pressable
-                    key={w.secs}
-                    onLayout={(e) => onWindowBtnLayout(w.secs, e)}
-                    onPress={() => {
-                      setActiveWindowSecs(w.secs);
-                      onWindowChange?.(w.secs);
-                    }}
-                    style={bar.pill}
-                  >
-                    <Animated.Text
-                      style={isActive ? bar.labelActive : bar.labelInactive}
-                    >
-                      {w.label}
-                    </Animated.Text>
-                  </Pressable>
-                );
-              })}
-            </PillBar>
-          )}
-
-          {/* Mode toggle — separate bar with its own sliding indicator */}
-          {onModeChange && (
-            <PillBar
-              bar={bar}
-              isDark={isDark}
-              indicator
-              indicatorLayout={modeBtnLayouts[activeMode]}
-            >
-              <Pressable
-                onLayout={(e) => onModeBtnLayout('line', e)}
-                onPress={() => onModeChange('line')}
-                style={[styles.iconBtn, bar.iconBtn]}
-              >
-                <LineIcon
-                  color={
-                    activeMode === 'line' ? bar.activeColor : bar.inactiveColor
-                  }
-                  active={activeMode === 'line'}
-                />
-              </Pressable>
-              <Pressable
-                onLayout={(e) => onModeBtnLayout('candle', e)}
-                onPress={() => onModeChange('candle')}
-                style={[styles.iconBtn, bar.iconBtn]}
-              >
-                <CandleIcon
-                  color={
-                    activeMode === 'candle'
-                      ? bar.activeColor
-                      : bar.inactiveColor
-                  }
-                />
-              </Pressable>
-            </PillBar>
-          )}
-
-          {/*
-            Series toggle chips. No sliding indicator — chips toggle
-            independently, so there is no single "active" one to track.
-            Rendered from lastSeriesPropRef (not seriesProp) and merely faded
-            out when the chart leaves multi-series mode: unmounting the bar
-            would reflow the controls row and drop the hidden-series state.
-          */}
-          {showSeriesToggle && (
-            <PillBar bar={bar} isDark={isDark} faded={!isMultiSeries}>
-              {(lastSeriesPropRef.current ?? []).map((s, si) => {
-                const isHidden = hiddenSeries.has(s.id);
-                const seriesColor =
-                  s.color || SERIES_COLORS[si % SERIES_COLORS.length]!;
-                return (
-                  <Pressable
-                    key={s.id}
-                    onPress={() => handleSeriesToggle(s.id)}
-                    style={[chip.base, isHidden && chip.off]}
-                  >
-                    <View
-                      style={[
-                        chip.dot,
-                        { backgroundColor: seriesColor },
-                        isHidden && styles.dimmed,
-                      ]}
-                    />
-                    {!seriesToggleCompact && (
-                      <Animated.Text
-                        style={isHidden ? chip.labelOff : chip.label}
-                      >
-                        {s.label ?? s.id}
-                      </Animated.Text>
-                    )}
-                  </Pressable>
-                );
-              })}
-            </PillBar>
-          )}
-        </View>
-      )}
+      {/*
+        Control bars row — window pills + mode toggle + series chips side by
+        side. The chips are driven by lastSeriesPropRef (not seriesProp) and
+        merely faded out when the chart leaves multi-series mode: unmounting
+        the bar would reflow the controls row and drop the hidden-series state.
+      */}
+      <LivelineControls
+        windowStyle={ws}
+        isDark={isDark}
+        padLeft={pad.left}
+        windows={stableWindows}
+        activeWindowSecs={activeWindowSecs}
+        onWindowSelect={selectWindow}
+        showModeToggle={onModeChange != null}
+        activeMode={activeMode}
+        onModeSelect={selectMode}
+        showSeriesToggle={showSeriesToggle}
+        seriesChips={seriesChips}
+        seriesFaded={!isMultiSeries}
+        hiddenSeries={hiddenSeries}
+        seriesToggleCompact={seriesToggleCompact}
+        onSeriesToggle={toggleSeries}
+      />
 
       <GestureDetector gesture={engine.gesture}>
         <View

From af8950e041324ffa5b9e3b6e91722f998337c788 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Sat, 1 Aug 2026 14:02:56 -0400
Subject: [PATCH 23/37] perf(draw): pool orderbook colors, hoist per-frame
 closures
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

**orderbook.ts — the big one.** `mixColor` called `rgbColor`, which does
`new Float32Array([...])` per call, once per active label inside the render
loop. With MAX_LABELS = 50 alive that is up to 3,000 allocations/sec on the UI
thread, in a library that pools paints, paths and rects precisely to avoid
this. candlestick.ts already avoids the identical trap by precomputing
bull/bear colors outside its loop; the orderbook could not, because each
label's blend varies per-label per-frame.

Now a preallocated `colorPool` of MAX_LABELS Float32Array(4) on OrderbookState,
with `mixColorInto(out, from, to, t)` writing in place.

Pooling was chosen over cache-keying deliberately: `colorStrength` is a
continuous per-label-per-frame value (intensity x fadeIn x fadeOut), so
quantizing it to a key would either band a fading label visibly or grow a
cache entry per frame.

Aliasing argument, checked at the call site rather than assumed:
canvas2d's applyStyle calls `paint.setColor(style)` synchronously inside
fillText/strokeText, copying the four floats into Skia's native paint state
before returning. The loop is strictly sequential (mixColorInto -> fillStyle ->
fillText), so the previous value is consumed before the next slot is written,
and each iteration uses a distinct slot indexed by loop position.

**Hoisted per-frame closures** — small individually, but the codebase's whole
discipline is that these do not exist in the frame path:
- draw/index.ts `collapseC` was allocated on EVERY candle frame but only
  invoked during the brief reveal-collapse window; its definition is now gated
  inside that branch.
- candlestick.ts `bodyRect`/`spatialDim` and dot.ts `drawChevrons` hoisted to
  module-level worklets taking their captured values as parameters.

All three hoists verified declared ABOVE their callers — the babel worklet
transform loses const hoisting, so a helper referenced before its own
assignment captures as undefined and crashes ONLY in release Hermes builds,
which neither jest nor the debug simulator catches.

candlestick.test.ts asserts exact native call counts and passes unmodified, so
the call sequence is unchanged.

**crosshair.ts** — drawCrosshair skipped its outline `if (tooltipOutline)`
while drawMultiCrosshair drew it `if (tooltipOutline !== false)`: opposite
defaults for an omitted argument. README and types.ts both document the default
as `true`, so drawCrosshair now matches. No behavior change today (the single
call site passes an explicit boolean) — a latent trap removed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/draw/candlestick.ts | 83 +++++++++++++++++++++++++++++--------
 src/draw/crosshair.ts   |  6 ++-
 src/draw/dot.ts         | 91 ++++++++++++++++++++++++-----------------
 src/draw/index.ts       | 35 ++++++++--------
 src/draw/orderbook.ts   | 53 ++++++++++++++++++++----
 5 files changed, 188 insertions(+), 80 deletions(-)

diff --git a/src/draw/candlestick.ts b/src/draw/candlestick.ts
index 88bc3ac..c4f0250 100644
--- a/src/draw/candlestick.ts
+++ b/src/draw/candlestick.ts
@@ -120,6 +120,48 @@ function roundedRect(
   ctx.closePath();
 }
 
+/**
+ * Draws a candle body's rounded rect at (cx, bodyTop, bodyH). Was a per-call
+ * closure inside drawCandlesticks capturing ctx/halfBody/bodyW/radius —
+ * hoisted to module scope taking those as explicit params instead, since it
+ * runs unconditionally on every drawCandlesticks call (both the batched and
+ * non-batched paths use it) and a fresh closure was being allocated every
+ * candle frame regardless of whether scrub dimming was active.
+ */
+function bodyRectAt(
+  ctx: Ctx2D,
+  cx: number,
+  bodyTop: number,
+  bodyH: number,
+  halfBody: number,
+  bodyW: number,
+  radius: number
+) {
+  'worklet';
+  roundedRect(ctx, cx - halfBody, bodyTop, bodyW, bodyH, radius);
+}
+
+/**
+ * Spatial dimming factor for the non-batched scrub-dimming fallback — a
+ * candle fades the further it sits past the scrub cursor. Was a per-call
+ * closure capturing scrubX/bodyW/scrubDim; hoisted to module scope taking
+ * those as explicit params since it (like bodyRectAt above) was allocated
+ * unconditionally even on frames/paths where it's never invoked (the batched
+ * fast path never calls it).
+ */
+function candleSpatialDim(
+  cx: number,
+  scrubX: number,
+  bodyW: number,
+  scrubDim: number
+): number {
+  'worklet';
+  const dist = cx - scrubX;
+  if (dist <= 0) return 1;
+  const dimT = Math.min(dist / (bodyW * 1.5), 1);
+  return 1 - scrubDim * 0.5 * dimT;
+}
+
 /**
  * Draw OHLC candlesticks with live candle glow + scrub dimming.
  * Respects incoming ctx.globalAlpha for cross-fade/reveal support.
@@ -191,16 +233,6 @@ export function drawCandlesticks(
     ? blendToAccent(BEAR_RGB, accentColor!, accentBlend)
     : rgbColor(BEAR_RGB[0], BEAR_RGB[1], BEAR_RGB[2]);
 
-  const bodyRect = (cx: number, bodyTop: number, bodyH: number) => {
-    roundedRect(ctx, cx - halfBody, bodyTop, bodyW, bodyH, radius);
-  };
-  const spatialDim = (cx: number): number => {
-    const dist = cx - scrubX;
-    if (dist <= 0) return 1;
-    const dimT = Math.min(dist / (bodyW * 1.5), 1);
-    return 1 - scrubDim * 0.5 * dimT;
-  };
-
   let liveCandle: CandlePoint | null = null;
 
   if (canBatch) {
@@ -292,7 +324,15 @@ export function drawCandlesticks(
           if (cx + halfBody < padL || cx - halfBody > padR) continue;
           const bodyTop = toY(Math.max(c.open, c.close));
           const bodyBottom = toY(Math.min(c.open, c.close));
-          bodyRect(cx, bodyTop, Math.max(1, bodyBottom - bodyTop));
+          bodyRectAt(
+            ctx,
+            cx,
+            bodyTop,
+            Math.max(1, bodyBottom - bodyTop),
+            halfBody,
+            bodyW,
+            radius
+          );
           bodyCount++;
         }
         if (bodyCount > 0) {
@@ -341,7 +381,8 @@ export function drawCandlesticks(
 
       const isBull = c.close >= c.open;
       const color = isBull ? bullColor : bearColor;
-      ctx.globalAlpha = baseAlpha * spatialDim(cx);
+      ctx.globalAlpha =
+        baseAlpha * candleSpatialDim(cx, scrubX, bodyW, scrubDim);
 
       const bodyTop = toY(Math.max(c.open, c.close));
       const bodyBottom = toY(Math.min(c.open, c.close));
@@ -367,7 +408,15 @@ export function drawCandlesticks(
 
       ctx.fillStyle = color;
       ctx.beginPath();
-      bodyRect(cx, bodyTop, Math.max(1, bodyBottom - bodyTop));
+      bodyRectAt(
+        ctx,
+        cx,
+        bodyTop,
+        Math.max(1, bodyBottom - bodyTop),
+        halfBody,
+        bodyW,
+        radius
+      );
       ctx.fill();
 
       ctx.globalAlpha = baseAlpha;
@@ -399,7 +448,9 @@ export function drawCandlesticks(
       const wickTop = toY(liveCandle.high);
       const wickBottom = toY(liveCandle.low);
 
-      const candleAlpha = canBatch ? liveAlpha : liveAlpha * spatialDim(cx);
+      const candleAlpha = canBatch
+        ? liveAlpha
+        : liveAlpha * candleSpatialDim(cx, scrubX, bodyW, scrubDim);
       ctx.globalAlpha = baseAlpha * candleAlpha;
 
       ctx.lineCap = 'round';
@@ -421,7 +472,7 @@ export function drawCandlesticks(
 
       ctx.fillStyle = liveColor;
       ctx.beginPath();
-      bodyRect(cx, bodyTop, bodyH);
+      bodyRectAt(ctx, cx, bodyTop, bodyH, halfBody, bodyW, radius);
       ctx.fill();
 
       if (showLivePulse) {
@@ -431,7 +482,7 @@ export function drawCandlesticks(
         ctx.shadowBlur = 8;
         ctx.fillStyle = liveColor;
         ctx.beginPath();
-        bodyRect(cx, bodyTop, bodyH);
+        bodyRectAt(ctx, cx, bodyTop, bodyH, halfBody, bodyW, radius);
         ctx.fill();
         ctx.restore();
       }
diff --git a/src/draw/crosshair.ts b/src/draw/crosshair.ts
index 3548ff8..c15a055 100644
--- a/src/draw/crosshair.ts
+++ b/src/draw/crosshair.ts
@@ -79,8 +79,10 @@ export function drawCrosshair(
 
   ctx.textAlign = 'left';
 
-  // Text outline for readability against the chart
-  if (tooltipOutline) {
+  // Text outline for readability against the chart. Matches drawMultiCrosshair
+  // below and the documented default (types.ts / README: tooltipOutline
+  // defaults to true) — an omitted flag must draw the outline, not skip it.
+  if (tooltipOutline !== false) {
     ctx.strokeStyle = palette.tooltipBg;
     ctx.lineWidth = 3;
     ctx.lineJoin = 'round';
diff --git a/src/draw/dot.ts b/src/draw/dot.ts
index be7e528..5ac7067 100644
--- a/src/draw/dot.ts
+++ b/src/draw/dot.ts
@@ -132,6 +132,58 @@ export function drawSimpleDot(
   ctx.fill();
 }
 
+/**
+ * Draws one chevron stack (up or down) for drawArrows below. Was a per-call
+ * closure inside drawArrows capturing ctx/x/y/palette/baseAlpha/cycle —
+ * hoisted to module scope taking those as explicit params instead, since
+ * drawArrows allocated a fresh closure every frame it ran (60-120x/sec) even
+ * though the closure body itself is identical call to call.
+ */
+function drawChevronStack(
+  ctx: Ctx2D,
+  x: number,
+  y: number,
+  palette: LivelinePalette,
+  baseAlpha: number,
+  cycle: number,
+  dir: -1 | 1,
+  opacity: number
+) {
+  'worklet';
+  if (opacity < 0.01) return;
+  const baseX = x + 19;
+  const baseY = y;
+
+  ctx.save();
+  ctx.strokeStyle = palette.gridLabel;
+  ctx.lineWidth = 2.5;
+  ctx.lineCap = 'round';
+  ctx.lineJoin = 'round';
+
+  for (let i = 0; i < 2; i++) {
+    // Stagger: arrow 0 brightens at t=0, arrow 1 at t=0.2
+    // Both always visible (min 0.3), cascade just brightens each in sequence
+    const start = i * 0.2;
+    const dur = 0.35;
+    const localT = cycle - start;
+    const wave =
+      localT >= 0 && localT < dur ? Math.sin((localT / dur) * Math.PI) : 0;
+    const pulse = 0.3 + 0.7 * wave;
+
+    ctx.globalAlpha = baseAlpha * opacity * pulse;
+
+    const nudge = dir === -1 ? -3 : 3;
+    const cy = baseY + dir * (i * 8 - 4) + nudge;
+    ctx.beginPath();
+    ctx.moveTo(baseX - 5, cy - dir * 3.5);
+    ctx.lineTo(baseX, cy);
+    ctx.lineTo(baseX + 5, cy - dir * 3.5);
+    ctx.stroke();
+  }
+
+  ctx.restore();
+}
+
 /** Draw momentum arrows (chevrons) next to the dot. */
 export function drawArrows(
   ctx: Ctx2D,
@@ -175,43 +227,8 @@ export function drawArrows(
   // UP: bottom arrow fires first, then top (energy moves upward).
   // DOWN: top arrow fires first, then bottom.
   const cycle = (now_ms % 1400) / 1400;
-  const drawChevrons = (dir: -1 | 1, opacity: number) => {
-    if (opacity < 0.01) return;
-    const baseX = x + 19;
-    const baseY = y;
-
-    ctx.save();
-    ctx.strokeStyle = palette.gridLabel;
-    ctx.lineWidth = 2.5;
-    ctx.lineCap = 'round';
-    ctx.lineJoin = 'round';
-
-    for (let i = 0; i < 2; i++) {
-      // Stagger: arrow 0 brightens at t=0, arrow 1 at t=0.2
-      // Both always visible (min 0.3), cascade just brightens each in sequence
-      const start = i * 0.2;
-      const dur = 0.35;
-      const localT = cycle - start;
-      const wave =
-        localT >= 0 && localT < dur ? Math.sin((localT / dur) * Math.PI) : 0;
-      const pulse = 0.3 + 0.7 * wave;
-
-      ctx.globalAlpha = baseAlpha * opacity * pulse;
-
-      const nudge = dir === -1 ? -3 : 3;
-      const cy = baseY + dir * (i * 8 - 4) + nudge;
-      ctx.beginPath();
-      ctx.moveTo(baseX - 5, cy - dir * 3.5);
-      ctx.lineTo(baseX, cy);
-      ctx.lineTo(baseX + 5, cy - dir * 3.5);
-      ctx.stroke();
-    }
-
-    ctx.restore();
-  };
-
-  drawChevrons(-1, arrows.up);
-  drawChevrons(1, arrows.down);
+  drawChevronStack(ctx, x, y, palette, baseAlpha, cycle, -1, arrows.up);
+  drawChevronStack(ctx, x, y, palette, baseAlpha, cycle, 1, arrows.down);
 
   ctx.globalAlpha = baseAlpha;
 }
diff --git a/src/draw/index.ts b/src/draw/index.ts
index 178365c..15148eb 100644
--- a/src/draw/index.ts
+++ b/src/draw/index.ts
@@ -824,22 +824,25 @@ export function drawCandleFrame(
     // OHLC expansion uses smoothstep on reveal — this keeps shape and alpha
     // in sync (at 50% visible, candles are ~50% expanded rather than flat).
     const ohlcScale = reveal * reveal * (3 - 2 * reveal);
-    const collapseC = (c: CandlePoint): CandlePoint =>
-      ohlcScale >= 0.99
-        ? c
-        : {
-            time: c.time,
-            open: c.close + (c.open - c.close) * ohlcScale,
-            high: c.close + (c.high - c.close) * ohlcScale,
-            low: c.close + (c.low - c.close) * ohlcScale,
-            close: c.close,
-          };
-    const revealCandles =
-      ohlcScale < 0.99 ? opts.candles.map(collapseC) : opts.candles;
-    const revealOld =
-      ohlcScale < 0.99 && opts.oldCandles.length > 0
-        ? opts.oldCandles.map(collapseC)
-        : opts.oldCandles;
+    // collapseC is only ever invoked during the brief reveal-collapse window
+    // (ohlcScale < 0.99); gate its allocation behind that same check instead
+    // of building a fresh closure every candle frame regardless of whether
+    // it's used.
+    let revealCandles = opts.candles;
+    let revealOld = opts.oldCandles;
+    if (ohlcScale < 0.99) {
+      const collapseC = (c: CandlePoint): CandlePoint => ({
+        time: c.time,
+        open: c.close + (c.open - c.close) * ohlcScale,
+        high: c.close + (c.high - c.close) * ohlcScale,
+        low: c.close + (c.low - c.close) * ohlcScale,
+        close: c.close,
+      });
+      revealCandles = opts.candles.map(collapseC);
+      if (opts.oldCandles.length > 0) {
+        revealOld = opts.oldCandles.map(collapseC);
+      }
+    }
 
     ctx.save();
     ctx.clipRect(pad.left - 1, pad.top, chartW + 2, chartH);
diff --git a/src/draw/orderbook.ts b/src/draw/orderbook.ts
index 4061394..a14d2af 100644
--- a/src/draw/orderbook.ts
+++ b/src/draw/orderbook.ts
@@ -1,5 +1,4 @@
 import type { LivelinePalette, ChartLayout, OrderbookData } from '../types';
-import { rgbColor } from '../math/color';
 import type { SkColor } from '@shopify/react-native-skia';
 import type { Ctx2D } from './canvas2d';
 
@@ -32,6 +31,11 @@ export interface OrderbookState {
   outlineColorG: number;
   outlineColorB: number;
   outlineColor: string;
+  // Pooled SkColor scratch buffers for the per-label fill blend (mixColorInto
+  // below) — one Float32Array(4) per label slot, mutated in place every
+  // frame instead of allocating a fresh one per label per frame (see
+  // mixColorInto for why reusing these across labels/frames is safe).
+  colorPool: SkColor[];
 }
 
 // NOTE: these consts MUST be declared above createOrderbookState. The
@@ -48,6 +52,10 @@ const MAX_SPEED = 160; // px/s during big activity
 
 export function createOrderbookState(): OrderbookState {
   'worklet';
+  const colorPool: SkColor[] = [];
+  for (let i = 0; i < MAX_LABELS; i++) {
+    colorPool.push(new Float32Array(4) as unknown as SkColor);
+  }
   return {
     labels: [],
     spawnTimer: 0,
@@ -61,19 +69,41 @@ export function createOrderbookState(): OrderbookState {
     outlineColorG: -1,
     outlineColorB: -1,
     outlineColor: '',
+    colorPool,
   };
 }
 
-function mixColor(
-  from: [number, number, number],
-  to: [number, number, number],
+// Blends `from` -> `to` by `t` and writes the RGBA into `out` in place
+// (out is a pooled Float32Array(4) — see OrderbookState.colorPool) instead
+// of allocating a fresh SkColor per call. This runs once per active label
+// per frame (up to MAX_LABELS = 50 times), so at 60fps that's up to ~3,000
+// Float32Array allocations/sec avoided.
+//
+// Aliasing: `out` is safe to mutate and reuse because every write is
+// consumed synchronously before the next write happens. The draw loop below
+// does, per label, in order: mixColorInto(...) -> ctx.fillStyle = fillColor
+// -> ctx.fillText(...). fillText's paint.setColor(style) (see canvas2d.ts's
+// applyStyle) copies the 4 floats into Skia's native paint state
+// synchronously on the same JS-thread call — there is no deferred/async read
+// of the array later. So by the time the loop moves on to the next label and
+// reuses the *next* pool slot (or, next frame, wraps back to slot 0), Skia
+// has already consumed every previously-written value; nothing is reading a
+// stale or in-flight reference to a pool slot. Each iteration also uses a
+// distinct slot (indexed by loop position, not label identity), so there is
+// no intra-frame slot collision either.
+function mixColorInto(
+  out: SkColor,
+  from: readonly [number, number, number],
+  to: readonly [number, number, number],
   t: number
 ): SkColor {
   'worklet';
-  const r = Math.round(from[0] + (to[0] - from[0]) * t);
-  const g = Math.round(from[1] + (to[1] - from[1]) * t);
-  const b = Math.round(from[2] + (to[2] - from[2]) * t);
-  return rgbColor(r, g, b);
+  const o = out as unknown as Float32Array;
+  o[0] = Math.round(from[0] + (to[0] - from[0]) * t) / 255;
+  o[1] = Math.round(from[1] + (to[1] - from[1]) * t) / 255;
+  o[2] = Math.round(from[2] + (to[2] - from[2]) * t) / 255;
+  o[3] = 1;
+  return out;
 }
 
 function formatSize(size: number): string {
@@ -271,7 +301,12 @@ export function drawOrderbook(
 
     const colorStrength = l.intensity * fadeIn * fadeOut;
     const baseColor = l.green ? GREEN : RED;
-    const fillColor = mixColor(baseColor, bg, 1 - colorStrength);
+    const fillColor = mixColorInto(
+      state.colorPool[i]!,
+      baseColor,
+      bg,
+      1 - colorStrength
+    );
 
     ctx.strokeStyle = outlineColor;
     ctx.lineWidth = 4;

From eff31f87e087d53bda3ce988183c9441eb0c283d Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Sat, 1 Aug 2026 14:04:25 -0400
Subject: [PATCH 24/37] fix: refresh yarn.lock for the widened gesture-handler
 peer range
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

54ed706 widened the peerDependency to >=2.30.0 but the lockfile still recorded
>=3.0.0, so `yarn install --immutable` failed with YN0028 — i.e. CI would have
broken on that commit. Caught by an agent that hit it while trying to install.

One line; regenerated rather than hand-edited.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 yarn.lock | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/yarn.lock b/yarn.lock
index 2bb9f06..2ad00c0 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -34,7 +34,7 @@ __metadata:
     "@shopify/react-native-skia": ">=2.0.0"
     react: "*"
     react-native: "*"
-    react-native-gesture-handler: ">=3.0.0"
+    react-native-gesture-handler: ">=2.30.0"
     react-native-reanimated: ">=4.0.0"
     react-native-worklets: ">=0.3.0"
   languageName: unknown

From c24ac65b56c937a5db5b231eed9bb33278aa5ac1 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Sat, 1 Aug 2026 14:05:33 -0400
Subject: [PATCH 25/37] =?UTF-8?q?fix(engine):=20three=20timing=20bugs=20?=
 =?UTF-8?q?=E2=80=94=20quiescence=20debt,=20background=20gap,=20scroll=20r?=
 =?UTF-8?q?ate?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

All three pre-existing or introduced-yesterday, none caught by any gate.

**1. timeDebt over-accrued ~3x per second of quiescence (SEVERE).**
`dt = now_ms - s.lastFrameTimestamp`, and `lastFrameTimestamp` is written in
exactly one place — the recording path. The quiescent early-return credited
`timeDebt += dt/1000` without touching it, so consecutive skipped frames
credited 16.7ms, 33.3, 50, 50, 50... (clamped at MAX_DELTA_MS). At 60Hz that
is ~3.0s of debt per 1s of real time, and it got WORSE at 120Hz.

Pause a chart, leave it 10s, unpause: ~28s of debt instead of 10, so
`now = Date.now()/1000 - timeDebt` puts the chart ~18s further into the past
than when it paused — the window snaps right, then rips forward under
PAUSE_CATCHUP_SPEED_FAST.

Fixed with a second clock, `lastAccrualTimestamp`, advanced on every frame that
credits debt. `lastFrameTimestamp` still is not written in the quiescent
branch, so both of its documented properties survive: the frame that breaks
quiescence still gets one large clamped dt, and the pacing gate still measures
"when did state last actually advance". The two clocks are equal on every
recorded frame and diverge only across skips — exactly the interval that was
being double-counted.

**2. A suspended frame loop lost the whole background interval (HIGH).**
setActive(false) stops accrual; wall-clock does not stop. Resume dt is clamped
to 50ms, so a 60s absence credited 0.05s. A PAUSED chart therefore jumped
forward ~60s on foreground, dumping a minute of data off the left edge.

All setActive calls now route through one path that stamps Date.now() on the
first suspension and credits the elapsed time on resume, scaled by
pauseProgress — so unpaused charts (pauseProgress 0) get exactly zero credit
and keep their correct advance-to-wall-clock behaviour, with no JS-side pause
knowledge required. `active={false}` routes through the same path: a chart
scrolled off a FlatList for a minute had the identical bug.

**3. scrollDx discontinuities poisoned observeScrollRate (introduced 33c23cb).**
dx is an offset OF A PARTICULAR recorded picture. Two consecutive recorded
frames 16ms apart can report -35 then 0 with the line perfectly continuous,
because the prefix was rebuilt in between and the new one already bakes in
that 35px. Differencing them yields +2.1 px/ms describing nothing physical;
the next paced-out vsync would shove the <Group transform> ~35px right and the
following frame would snap it back — a flick per line-cache rebuild, on
high-refresh hardware only. The gap bound could never catch it: a rebuild
happens on an ordinary 16ms frame, inside every timing guard.

observeScrollRate now takes `layerChanged` (scrollActive toggled, or
lineCache.buildRev moved) and returns 0, which makes extrapolateScrollDx
return null — "leave the transform exactly where it is". The guard does not
latch.

+21 tests (319 -> 340). timeAccrual.ts is Skia-free so jest can reach it: 1s/1s
accrual at 60 and 120Hz over 10s and 60s runs, a replay of the OLD arithmetic
asserting the ~28s-per-10s regression, and end-to-end property tests that a
paused chart's displayed instant survives 10s quiescent + 60s backgrounded
while an unpaused one advances by exactly the absence.

NOT tested: the hook wiring itself (native Skia import). Bug 3's symptom needs
120Hz hardware — the simulator is 60Hz and never paces out.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/engine/__tests__/constants.test.ts        |   2 +-
 .../__tests__/scrollExtrapolate.test.ts       |  67 ++++++-
 src/engine/__tests__/timeAccrual.test.ts      | 169 ++++++++++++++++++
 src/engine/scrollExtrapolate.ts               |  24 ++-
 src/engine/state.ts                           |  33 ++++
 src/engine/timeAccrual.ts                     |  78 ++++++++
 src/useLivelineEngine.ts                      | 129 ++++++++++++-
 7 files changed, 481 insertions(+), 21 deletions(-)
 create mode 100644 src/engine/__tests__/timeAccrual.test.ts
 create mode 100644 src/engine/timeAccrual.ts

diff --git a/src/engine/__tests__/constants.test.ts b/src/engine/__tests__/constants.test.ts
index 0d395cd..055dae1 100644
--- a/src/engine/__tests__/constants.test.ts
+++ b/src/engine/__tests__/constants.test.ts
@@ -29,7 +29,7 @@ describe('frame-pacing / extrapolation constants', () => {
   it('a vsync one pacing interval after a record still gets an extrapolated dx', () => {
     // The inequalities restated as the behaviour they protect, end to end:
     // observe a rate across a paced interval, then extrapolate across another.
-    const rate = observeScrollRate(0, 0, -1, MIN_FRAME_INTERVAL_MS);
+    const rate = observeScrollRate(0, 0, -1, MIN_FRAME_INTERVAL_MS, false);
     expect(rate).not.toBe(0);
     const dx = extrapolateScrollDx(
       -1,
diff --git a/src/engine/__tests__/scrollExtrapolate.test.ts b/src/engine/__tests__/scrollExtrapolate.test.ts
index 8471dd9..f25ed11 100644
--- a/src/engine/__tests__/scrollExtrapolate.test.ts
+++ b/src/engine/__tests__/scrollExtrapolate.test.ts
@@ -10,34 +10,83 @@ import { MAX_SCROLL_EXTRAPOLATION_MS } from '../constants';
 
 describe('observeScrollRate', () => {
   it('returns 0 when there is no previous recorded frame', () => {
-    expect(observeScrollRate(0, -1, -5, 16)).toBe(0);
+    expect(observeScrollRate(0, -1, -5, 16, false)).toBe(0);
   });
 
   it('measures the observed per-ms rate over a normal paced interval', () => {
     // Chart scrolls left, so dx decreases: -10 -> -20 over 16ms.
-    expect(observeScrollRate(-10, 100, -20, 116)).toBeCloseTo(-10 / 16, 10);
+    expect(observeScrollRate(-10, 100, -20, 116, false)).toBeCloseTo(
+      -10 / 16,
+      10
+    );
   });
 
   it('is negative for leftward scroll and positive for rightward', () => {
-    expect(observeScrollRate(-10, 100, -20, 116)).toBeLessThan(0);
-    expect(observeScrollRate(-20, 100, -10, 116)).toBeGreaterThan(0);
+    expect(observeScrollRate(-10, 100, -20, 116, false)).toBeLessThan(0);
+    expect(observeScrollRate(-20, 100, -10, 116, false)).toBeGreaterThan(0);
   });
 
   it('rejects a non-advancing or backwards clock', () => {
-    expect(observeScrollRate(-10, 100, -20, 100)).toBe(0);
-    expect(observeScrollRate(-10, 100, -20, 90)).toBe(0);
+    expect(observeScrollRate(-10, 100, -20, 100, false)).toBe(0);
+    expect(observeScrollRate(-10, 100, -20, 90, false)).toBe(0);
   });
 
   it('rejects a gap too long to be a paced interval', () => {
     // A quiescence resume or return from background: large dx change over a
     // large gap would otherwise bake in a meaningless rate.
     const long = MAX_SCROLL_EXTRAPOLATION_MS * 2 + 1;
-    expect(observeScrollRate(-10, 100, -5000, 100 + long)).toBe(0);
+    expect(observeScrollRate(-10, 100, -5000, 100 + long, false)).toBe(0);
   });
 
   it('accepts a gap exactly at the bound', () => {
     const at = MAX_SCROLL_EXTRAPOLATION_MS * 2;
-    expect(observeScrollRate(-10, 100, -20, 100 + at)).not.toBe(0);
+    expect(observeScrollRate(-10, 100, -20, 100 + at, false)).not.toBe(0);
+  });
+
+  // --- Layer identity ---------------------------------------------------
+  //
+  // The gap bound cannot catch these: a prefix rebuild happens on an
+  // ordinary 16ms recorded frame, well inside every timing guard.
+
+  it('refuses to observe a rate across a prefix rebuild', () => {
+    // 35px of scroll accumulated since the last build, then the prefix is
+    // rebuilt: dx snaps to 0 while the rendered line does not move at all.
+    // Unguarded this reads as +2.1 px/ms, which a paced-out vsync would then
+    // apply as a ~35px rightward flick.
+    expect(observeScrollRate(-35, 100, 0, 116.7, false)).toBeCloseTo(
+      35 / 16.7,
+      10
+    );
+    expect(observeScrollRate(-35, 100, 0, 116.7, true)).toBe(0);
+  });
+
+  it('refuses to observe a rate across a compositing toggle', () => {
+    // Layer goes live: last frame's dx was 0 because nothing was compositing.
+    expect(observeScrollRate(0, 100, -35, 116.7, true)).toBe(0);
+    // ...and stops compositing: this frame's dx is 0 for the same reason.
+    expect(observeScrollRate(-35, 100, 0, 116.7, true)).toBe(0);
+  });
+
+  it('suppresses for exactly one frame, then resumes normally', () => {
+    // The guard must not latch: the frame after a rebuild is measured
+    // against the new prefix on both ends, so it is a valid pair again.
+    expect(observeScrollRate(-35, 100, 0, 116.7, true)).toBe(0);
+    expect(observeScrollRate(0, 116.7, -10, 133.4, false)).toBeCloseTo(
+      -10 / 16.7,
+      10
+    );
+  });
+
+  it('a suppressed rate freezes rather than flings the transform', () => {
+    // rate 0 makes extrapolateScrollDx return null, whose contract is
+    // "leave the transform exactly where it is" — the correct behaviour for
+    // the one paced-out vsync following a rebuild.
+    const rate = observeScrollRate(-35, 100, 0, 116.7, true);
+    expect(extrapolateScrollDx(0, 116.7, rate, 125)).toBeNull();
+    // Without the guard it would have shoved the layer ~17px right of a
+    // position the line never occupied.
+    const bogus = observeScrollRate(-35, 100, 0, 116.7, false);
+    expect(extrapolateScrollDx(0, 116.7, bogus, 125)!).toBeGreaterThan(15);
   });
 });
 
@@ -90,7 +139,7 @@ describe('extrapolateScrollDx', () => {
       const isRecord = now - tLast >= RECORD_MS;
 
       if (isRecord) {
-        rate = observeScrollRate(dxLast, tLast, trueDx, now);
+        rate = observeScrollRate(dxLast, tLast, trueDx, now, false);
         dxLast = trueDx;
         tLast = now;
       } else {
diff --git a/src/engine/__tests__/timeAccrual.test.ts b/src/engine/__tests__/timeAccrual.test.ts
new file mode 100644
index 0000000..508c838
--- /dev/null
+++ b/src/engine/__tests__/timeAccrual.test.ts
@@ -0,0 +1,169 @@
+import { accrualDeltaMs, suspendedDebtSec } from '../timeAccrual';
+import { MAX_DELTA_MS, QUIESCENT_FRAME_THRESHOLD } from '../constants';
+
+/**
+ * The call site (useLivelineEngine's frame callback) imports the native Skia
+ * binding and cannot be unit-tested, and the failure mode here — a paused
+ * chart that jumps somewhere it never was — only becomes visible after ten
+ * seconds of a chart doing nothing, which no manual pass reliably catches.
+ * So the accrual arithmetic is exercised here instead, by replaying the frame
+ * loop's skip paths against a fake vsync clock.
+ */
+
+/**
+ * Replays the quiescent branch of the frame callback: one credit per vsync,
+ * measured against the accrual clock, which advances every time.
+ */
+function runQuiescent(seconds: number, hz: number): number {
+  const interval = 1000 / hz;
+  let timeDebt = 0;
+  let lastAccrual: number | null = 0;
+  for (let i = 1; i <= seconds * hz; i++) {
+    const now = i * interval;
+    timeDebt += accrualDeltaMs(lastAccrual, now) / 1000;
+    lastAccrual = now;
+  }
+  return timeDebt;
+}
+
+/**
+ * The pre-fix behaviour, kept as an executable statement of the bug: debt was
+ * measured from `lastFrameTimestamp`, which does NOT move while frames are
+ * skipped, so every skipped frame re-credited the whole span since the last
+ * recorded frame.
+ */
+function runQuiescentAgainstFixedOrigin(seconds: number, hz: number): number {
+  const interval = 1000 / hz;
+  const lastRecorded = 0;
+  let timeDebt = 0;
+  for (let i = 1; i <= seconds * hz; i++) {
+    const now = i * interval;
+    timeDebt += Math.min(now - lastRecorded, MAX_DELTA_MS) / 1000;
+  }
+  return timeDebt;
+}
+
+describe('accrualDeltaMs', () => {
+  it('credits exactly the interval since the last credited frame', () => {
+    expect(accrualDeltaMs(100, 116.7)).toBeCloseTo(16.7, 10);
+    expect(accrualDeltaMs(100, 108.33)).toBeCloseTo(8.33, 10);
+  });
+
+  it('credits nothing before the first frame has recorded', () => {
+    expect(accrualDeltaMs(null, 16.7)).toBe(0);
+  });
+
+  it('credits nothing for a non-advancing or backwards clock', () => {
+    expect(accrualDeltaMs(100, 100)).toBe(0);
+    expect(accrualDeltaMs(100, 90)).toBe(0);
+  });
+
+  it('clamps a stalled interval to MAX_DELTA_MS', () => {
+    expect(accrualDeltaMs(100, 100 + MAX_DELTA_MS + 1)).toBe(MAX_DELTA_MS);
+    expect(accrualDeltaMs(100, 5100)).toBe(MAX_DELTA_MS);
+  });
+});
+
+describe('quiescent accrual accrues real time, not a multiple of it', () => {
+  it('accrues 1s of debt per 1s of quiescence at 60Hz', () => {
+    expect(runQuiescent(10, 60)).toBeCloseTo(10, 6);
+  });
+
+  it('accrues the same at 120Hz — the rate cannot depend on refresh rate', () => {
+    expect(runQuiescent(10, 120)).toBeCloseTo(10, 6);
+    expect(runQuiescent(10, 120)).toBeCloseTo(runQuiescent(10, 60), 6);
+  });
+
+  it('holds over a long pause: 60s of quiescence is 60s of debt', () => {
+    expect(runQuiescent(60, 60)).toBeCloseTo(60, 5);
+  });
+
+  it('is the regression: the fixed-origin version over-accrued ~3x', () => {
+    // 10s paused accrued ~28s of debt, so `Date.now()/1000 - timeDebt` put
+    // the chart ~18s further into the past than when it was paused: the
+    // window snapped right on resume, then ripped forward under
+    // PAUSE_CATCHUP_SPEED_FAST (which the >10s debt threshold selects).
+    const bad = runQuiescentAgainstFixedOrigin(10, 60);
+    expect(bad).toBeGreaterThan(27);
+    expect(bad).toBeLessThan(30);
+    expect(bad / runQuiescent(10, 60)).toBeGreaterThan(2.5);
+    // ...and got worse, not better, on high-refresh hardware.
+    expect(runQuiescentAgainstFixedOrigin(10, 120)).toBeGreaterThan(bad * 1.9);
+  });
+
+  it('credits the quiescence ramp-up too (frames before the threshold)', () => {
+    // Frames below QUIESCENT_FRAME_THRESHOLD still record, so engineStep
+    // credits them off `dt`; this only asserts the constant is a frame count
+    // small enough that the skip path owns the bulk of a long pause.
+    const rampSecs = QUIESCENT_FRAME_THRESHOLD / 60;
+    expect(rampSecs).toBeLessThan(2);
+  });
+});
+
+describe('suspendedDebtSec', () => {
+  it('credits the full absence to a fully paused chart', () => {
+    // 60s backgrounded while paused. Without this the clamped dt contributed
+    // 0.05s and the frozen window jumped ~60s left on foreground.
+    expect(suspendedDebtSec(60_000, 1)).toBe(60);
+  });
+
+  it('credits nothing to an unpaused chart, preserving current behaviour', () => {
+    // pauseProgress 0 is exactly the set of charts that SHOULD advance to
+    // the new wall-clock on resume.
+    expect(suspendedDebtSec(60_000, 0)).toBe(0);
+  });
+
+  it('credits proportionally mid pause-transition', () => {
+    expect(suspendedDebtSec(60_000, 0.5)).toBe(30);
+  });
+
+  it('credits nothing for a zero, negative or backwards interval', () => {
+    expect(suspendedDebtSec(0, 1)).toBe(0);
+    expect(suspendedDebtSec(-5000, 1)).toBe(0);
+  });
+
+  it('never credits more than the elapsed time', () => {
+    // pauseProgress is a 0..1 lerp; a value above 1 must not scale debt up.
+    expect(suspendedDebtSec(60_000, 1.5)).toBe(60);
+  });
+
+  it('leaves a paused chart at the same displayed instant across a suspend', () => {
+    // The property that matters: `now = wallClock - timeDebt` must be
+    // unchanged by an absence, for a paused chart.
+    const wallAtSuspend = 1_700_000_000;
+    let timeDebt = 4; // already paused a while
+    const displayedBefore = wallAtSuspend - timeDebt;
+
+    const awaySecs = 137;
+    timeDebt += suspendedDebtSec(awaySecs * 1000, 1);
+    const displayedAfter = wallAtSuspend + awaySecs - timeDebt;
+
+    expect(displayedAfter).toBeCloseTo(displayedBefore, 10);
+  });
+
+  it('leaves an unpaused chart advanced by exactly the absence', () => {
+    const wallAtSuspend = 1_700_000_000;
+    let timeDebt = 0;
+    const awaySecs = 137;
+    timeDebt += suspendedDebtSec(awaySecs * 1000, 0);
+    const displayedAfter = wallAtSuspend + awaySecs - timeDebt;
+    expect(displayedAfter - wallAtSuspend).toBe(awaySecs);
+  });
+});
+
+describe('the two skip paths compose', () => {
+  it('a chart paused, left quiescent, backgrounded and resumed holds still', () => {
+    // Timeline: paused, 10s on screen going quiescent, 60s backgrounded,
+    // then foregrounded. The displayed instant must not move across ANY of
+    // it — that is the whole contract of `paused`.
+    const wallStart = 1_700_000_000;
+    let timeDebt = 0;
+    const displayedAtPause = wallStart - timeDebt;
+
+    timeDebt += runQuiescent(10, 60);
+    timeDebt += suspendedDebtSec(60_000, 1);
+
+    const wallEnd = wallStart + 10 + 60;
+    expect(wallEnd - timeDebt).toBeCloseTo(displayedAtPause, 4);
+  });
+});
diff --git a/src/engine/scrollExtrapolate.ts b/src/engine/scrollExtrapolate.ts
index 4092ae8..4b52ddc 100644
--- a/src/engine/scrollExtrapolate.ts
+++ b/src/engine/scrollExtrapolate.ts
@@ -36,16 +36,36 @@ import { MAX_SCROLL_EXTRAPOLATION_MS } from './constants';
  * ordinary paced interval (~16ms) is comfortably inside it while a stall is
  * not.
  *
+ * `layerChanged` is the second, subtler guard, and the gap bound does NOT
+ * subsume it. `dx` is an offset *of a particular recorded picture* — it is
+ * meaningful only relative to the prefix that was built when `xRefAtBuild`
+ * was captured. Two consecutive recorded frames 16ms apart can therefore
+ * report `dx = -35` then `dx = 0` with the on-screen line perfectly
+ * continuous, because the prefix was rebuilt in between and the new one
+ * already bakes in that 35px. Differencing those two numbers yields a rate
+ * of +2.1 px/ms that describes nothing physical; the next paced-out vsync
+ * would then shove the `<Group transform>` ~35px to the right, and the
+ * following recorded frame would snap it back — a flick, once per line-cache
+ * rebuild, on high-refresh hardware only. The same applies when the layer
+ * stops or starts compositing: `dx` is 0 on every frame the layer is not
+ * live, so either edge of that toggle differences two unrelated quantities.
+ *
+ * So: no rate is observable across a frame whose layer identity moved. Pass
+ * `true` and this returns 0 — one paced-out vsync leaves the transform
+ * exactly where it was (`extrapolateScrollDx` returns null on rate 0), and
+ * the next recorded frame supplies both an exact dx and an honest rate.
+ *
  * `tPrev < 0` means no previous recorded frame.
  */
 export function observeScrollRate(
   dxPrev: number,
   tPrev: number,
   dx: number,
-  now: number
+  now: number,
+  layerChanged: boolean
 ): number {
   'worklet';
-  if (tPrev < 0) return 0;
+  if (tPrev < 0 || layerChanged) return 0;
   const gap = now - tPrev;
   if (gap <= 0 || gap > MAX_SCROLL_EXTRAPOLATION_MS * 2) return 0;
   return (dx - dxPrev) / gap;
diff --git a/src/engine/state.ts b/src/engine/state.ts
index b0f51cc..86e086d 100644
--- a/src/engine/state.ts
+++ b/src/engine/state.ts
@@ -156,6 +156,19 @@ export interface EngineState {
   scrollDxLastT: number;
   /** Observed dx change per ms across the last two recorded frames. */
   scrollDxRate: number;
+  /**
+   * `lineCache.buildRev` as of the last recorded frame, i.e. WHICH prefix
+   * picture `scrollDxLast` is an offset of.
+   *
+   * `dx` is `layout.toX(tRef) - xRefAtBuild`, so it resets to ~0 the frame
+   * the prefix is rebuilt while the line on screen does not move at all.
+   * Differencing across that frame yields a rate that describes a jump that
+   * never happened — see `observeScrollRate`'s `layerChanged` guard, which
+   * this field feeds. `-1` before the first recorded frame (no slot has
+   * `buildRev` -1, so the first frame always reads as a change; harmless,
+   * since `scrollDxLastT < 0` already suppresses it).
+   */
+  scrollDxBuildRev: number;
   /** Cross-frame closed-candle body+wick path cache, candle mode (see
    * draw/candleCache). */
   candleCache: CandleCacheSlot;
@@ -260,6 +273,24 @@ export interface EngineState {
    * both the quiescence skip and the pacing skip, so it always reflects
    * "when did state last actually advance." */
   lastFrameTimestamp: number | null;
+  /**
+   * `now_ms` as of the last frame that credited `timeDebt` — a SEPARATE
+   * clock from `lastFrameTimestamp`, and deliberately so.
+   *
+   * `lastFrameTimestamp` answers "when did state last advance", which is
+   * exactly what the pacing gate and `dt` want, and exactly what accrual
+   * must not use: the quiescence skip credits debt without advancing state,
+   * so measuring it against a fixed origin makes every consecutive skipped
+   * frame re-count the same interval (see `engine/timeAccrual.ts`). This
+   * field advances on every frame that credits, so credited intervals
+   * tile the timeline exactly once.
+   *
+   * `null` until the first credit. Recorded frames set it too — their
+   * accrual is done inside `engineStep` off `dt` — so the first quiescent
+   * frame after a record measures from that record, not from whenever
+   * quiescence last ended.
+   */
+  lastAccrualTimestamp: number | null;
 }
 
 /** The subset of `Map` that {@link pruneByIds} needs — lets one array hold
@@ -383,6 +414,7 @@ export function createEngineState(
     scrollDxLast: 0,
     scrollDxLastT: -1,
     scrollDxRate: 0,
+    scrollDxBuildRev: -1,
     candleCache: createCandleCacheSlot(),
 
     scrubAmount: 0,
@@ -449,5 +481,6 @@ export function createEngineState(
     lastRecordedH: -1,
 
     lastFrameTimestamp: null,
+    lastAccrualTimestamp: null,
   };
 }
diff --git a/src/engine/timeAccrual.ts b/src/engine/timeAccrual.ts
new file mode 100644
index 0000000..d360a39
--- /dev/null
+++ b/src/engine/timeAccrual.ts
@@ -0,0 +1,78 @@
+import { MAX_DELTA_MS } from './constants';
+
+/**
+ * Time-debt accrual for the frames `engineStep` never sees.
+ *
+ * `s.timeDebt` is how far behind wall-clock the chart is deliberately
+ * running: `now = Date.now()/1000 - timeDebt`. While a chart is paused it
+ * grows at exactly one second per second (`engineStep` does
+ * `timeDebt += dt/1000 * pauseProgress`), which is what keeps the frozen
+ * window frozen instead of sliding left. Get the rate wrong in either
+ * direction and the error is not a glitch, it is a position: over-accrue and
+ * the chart is further into the past than it ever was; under-accrue and it
+ * has silently advanced while "paused".
+ *
+ * Two paths bypass `engineStep` entirely and so must do their own accrual:
+ * the quiescence skip (chart provably static, picture not re-recorded) and
+ * the suspended frame loop (`frame.setActive(false)` on background or
+ * `active={false}`). Both live in `useLivelineEngine.ts`, which imports the
+ * native Skia binding and cannot be unit-tested — and both are wrong only
+ * after ten seconds of nothing happening, which is precisely the class of
+ * bug a manual check does not catch. Hence this Skia-free module, mirroring
+ * `scrollExtrapolate.ts`.
+ */
+
+/**
+ * Milliseconds of real time to credit on a frame that skips `engineStep`.
+ *
+ * The whole point is that `lastAccrualT` is a *separate* clock from
+ * `EngineState.lastFrameTimestamp`, advanced on every frame that credits
+ * debt rather than only on frames that record. Measuring accrual against
+ * `lastFrameTimestamp` instead is the bug this replaces: that field does not
+ * move while frames are being skipped, so consecutive skipped frames measure
+ * 16.7ms, then 33.3ms, then 50, 50, 50… against the same fixed origin and
+ * accrue roughly three seconds of debt per second of real time at 60Hz (and
+ * six at 120Hz). With a clock that advances every credited frame, each frame
+ * contributes exactly its own inter-frame interval, so the sum telescopes to
+ * the elapsed wall-clock regardless of refresh rate.
+ *
+ * Clamped to `MAX_DELTA_MS` for the same reason `dt` is: a single stalled
+ * interval should nudge the chart forward slightly rather than let one
+ * pathological gap dominate the debt. Returns 0 for a null origin (no frame
+ * has recorded yet, so there is no interval to credit) and for a
+ * non-advancing clock.
+ */
+export function accrualDeltaMs(
+  lastAccrualT: number | null,
+  now: number
+): number {
+  'worklet';
+  if (lastAccrualT === null) return 0;
+  const raw = now - lastAccrualT;
+  if (raw <= 0) return 0;
+  return raw > MAX_DELTA_MS ? MAX_DELTA_MS : raw;
+}
+
+/**
+ * Seconds of debt to credit on the first frame after the frame loop resumes,
+ * given the wall-clock milliseconds it was suspended for.
+ *
+ * Scaled by `pauseProgress` — the same factor `engineStep` applies every
+ * frame — so this needs no notion of "was it paused" of its own, and unpaused
+ * charts (`pauseProgress === 0`) get exactly zero, preserving their current,
+ * correct behaviour of simply advancing to the new wall-clock. A chart
+ * mid-pause-transition when it was backgrounded gets the proportional credit
+ * that continuing to run would have given it.
+ *
+ * `pauseProgress` is read from state frozen at suspend time, so it is the
+ * value that governed the whole absence, not a post-hoc guess.
+ */
+export function suspendedDebtSec(
+  pendingMs: number,
+  pauseProgress: number
+): number {
+  'worklet';
+  if (pendingMs <= 0 || pauseProgress <= 0) return 0;
+  const p = pauseProgress > 1 ? 1 : pauseProgress;
+  return (pendingMs / 1000) * p;
+}
diff --git a/src/useLivelineEngine.ts b/src/useLivelineEngine.ts
index 7b1baed..c86941c 100644
--- a/src/useLivelineEngine.ts
+++ b/src/useLivelineEngine.ts
@@ -47,6 +47,7 @@ import {
   observeScrollRate,
   extrapolateScrollDx,
 } from './engine/scrollExtrapolate';
+import { accrualDeltaMs, suspendedDebtSec } from './engine/timeAccrual';
 import {
   computeDelta,
   pointsEqual,
@@ -400,6 +401,17 @@ export function useLivelineEngine(
   const cullRect = useSharedValue<SkHostRect | null>(null);
   const size = useSharedValue({ w: 0, h: 0 });
   const hoverX = useSharedValue<number | null>(null);
+  // Wall-clock milliseconds the frame loop spent suspended, waiting to be
+  // credited to `timeDebt` by the next frame that runs. Written from JS (the
+  // AppState listener / the `active` effect below, which are the only things
+  // that know a suspension happened) and drained on the UI thread.
+  //
+  // A plain number shared value rather than a reach into `state.value`:
+  // EngineState holds Skia handles and is owned by the UI runtime, so the JS
+  // thread must not touch it. Additive (`+=`) so two suspensions that both
+  // land before a frame runs — app backgrounded and then `active={false}`,
+  // say — can't lose one of the intervals.
+  const pendingSuspendedMs = useSharedValue(0);
   const screenPicture = useSharedValue<SkPicture>(makeEmptyPicture());
   // The 1×1 do-nothing picture the scroll layer falls back to on every frame
   // that can't composite it (see StepOutput.scrollPicture) — and also its
@@ -473,6 +485,32 @@ export function useLivelineEngine(
     }
 
     const now_ms = info.timestamp ?? 0;
+
+    // --- Suspended-loop credit. `frame.setActive(false)` stops accrual but
+    // not the wall clock, and `dt` below is clamped to MAX_DELTA_MS, so a
+    // minute in the background would otherwise contribute 50ms of debt
+    // instead of 60s. For an unpaused chart that is right — it *should*
+    // advance to the new wall-clock — and `suspendedDebtSec` preserves that
+    // by scaling on `pauseProgress`, which is 0 for exactly those charts.
+    // For a paused one, the missing debt is the whole absence: without this
+    // the frozen window jumps a minute to the left on foreground, dumping a
+    // minute of data off the left edge of a chart the user paused precisely
+    // so it would hold still.
+    //
+    // Drained before anything else reads `s.timeDebt`, and before the
+    // quiescence gate, so a chart that comes back still-quiescent (the
+    // common case — nothing changed while it was away) is credited too.
+    const pendingMs = pendingSuspendedMs.value;
+    if (pendingMs > 0) {
+      pendingSuspendedMs.value = 0;
+      s.timeDebt += suspendedDebtSec(pendingMs, s.pauseProgress);
+      // Restart the accrual clock at the resume instant. Everything before
+      // now is accounted for by the credit just applied; leaving the stale
+      // pre-suspension origin here would let the first quiescent frame
+      // credit a clamped MAX_DELTA_MS on top of it.
+      s.lastAccrualTimestamp = now_ms;
+    }
+
     // Wall-clock time since the last frame that actually ran engineStep —
     // not info.timeSincePreviousFrame (vsync-to-vsync). These differ once
     // frame pacing (below) starts skipping vsyncs: every lerp() in the
@@ -513,7 +551,28 @@ export function useLivelineEngine(
       // catch-up animation, so skipping without it would change resume
       // behavior. The picture shared value is left untouched — it still
       // holds the last recorded (pixel-identical) frame.
-      s.timeDebt += dt / 1000;
+      //
+      // Measured against `lastAccrualTimestamp`, NOT `dt`. `dt` is measured
+      // from `lastFrameTimestamp`, which by design does not move while
+      // frames are skipped — so `dt` here is the time since the last
+      // *recorded* frame, and re-crediting it every skipped frame counts
+      // the same interval over and over: 16.7ms, 33.3, 50, 50, 50…, roughly
+      // 3s of debt per 1s of real time at 60Hz (6s at 120Hz). The separate
+      // accrual clock advances on every credited frame, so each frame
+      // credits only its own interval and 1s of quiescence costs exactly 1s
+      // of debt at any refresh rate. See engine/timeAccrual.ts.
+      //
+      // Both properties of `lastFrameTimestamp` documented above survive
+      // untouched, because this branch still does not write it:
+      //   1. `dt` on the frame that breaks quiescence is still one large,
+      //      clamped delta covering the whole skipped span — the resume
+      //      frame's lerps still take a single MAX_DELTA_MS step rather
+      //      than a 16ms one.
+      //   2. The pacing gate below still compares against "when state last
+      //      actually advanced", so the frame that breaks quiescence is
+      //      never itself paced out.
+      s.timeDebt += accrualDeltaMs(s.lastAccrualTimestamp, now_ms) / 1000;
+      s.lastAccrualTimestamp = now_ms;
       return;
     }
 
@@ -608,7 +667,18 @@ export function useLivelineEngine(
     // already known — the paced-out branch above reads it instead of
     // comparing two picture shared values (two JSI reads per vsync, and wrong
     // before the first recorded frame if the placeholders weren't identical).
-    s.scrollActive = result.scrollPicture !== null;
+    const scrollActive = result.scrollPicture !== null;
+    // Did the thing `dx` is an offset OF change since the last recorded
+    // frame? Two ways it can: the layer started or stopped compositing (dx
+    // is 0 on every frame it isn't live), or the prefix picture was rebuilt,
+    // which resets dx to ~0 while the line on screen does not move. Either
+    // makes this frame's dx and the last one's incommensurable, so no rate
+    // is observable across the pair — see observeScrollRate's `layerChanged`
+    // parameter. Read before `s.scrollActive` is overwritten below.
+    const buildRev = s.lineCache.buildRev;
+    const layerChanged =
+      scrollActive !== s.scrollActive || buildRev !== s.scrollDxBuildRev;
+    s.scrollActive = scrollActive;
     const dx = result.scrollDx;
     // Observed dx-per-ms across the last two RECORDED frames, used to
     // extrapolate the transform on paced-out vsyncs above — see
@@ -618,10 +688,12 @@ export function useLivelineEngine(
       s.scrollDxLast,
       s.scrollDxLastT,
       dx,
-      now_ms
+      now_ms,
+      layerChanged
     );
     s.scrollDxLast = dx;
     s.scrollDxLastT = now_ms;
+    s.scrollDxBuildRev = buildRev;
     // Exact value always wins over whatever a skipped vsync extrapolated, so
     // extrapolation error can never accumulate past one frame. Same
     // rotate-mutate-assign as the paced-out branch above.
@@ -633,6 +705,12 @@ export function useLivelineEngine(
     s.lastRecordedW = w;
     s.lastRecordedH = h;
     s.lastFrameTimestamp = now_ms;
+    // This frame credited its own debt inside engineStep (off `dt`), so the
+    // accrual clock advances here too — the two are equal on every recorded
+    // frame and diverge only across skips. Keeping them in step here is what
+    // makes the first quiescent frame after a record measure from that
+    // record rather than from whenever quiescence last ended.
+    s.lastAccrualTimestamp = now_ms;
 
     if (result.valueText !== null) valueText.value = result.valueText;
     if (result.valueColor !== null) valueColor.value = result.valueColor;
@@ -660,20 +738,53 @@ export function useLivelineEngine(
   // cycle. The change listener still uses strict `=== 'active'`.
   const appForegroundRef = useRef(AppState.currentState !== 'background');
 
+  // Wall-clock instant the frame loop was suspended, or null while it runs.
+  // `Date.now()` rather than the frame callback's `info.timestamp`: no frame
+  // callback fires while suspended, so there is no UI-thread clock reading
+  // to be had at either end of the interval.
+  const suspendedAtRef = useRef<number | null>(null);
+  // The single place `frame.setActive` is called, so that no suspension can
+  // be entered or left without the elapsed interval being accounted for.
+  // Both suspension causes route through it: backgrounding and
+  // `active={false}` stop accrual identically, and a chart scrolled off a
+  // FlatList for a minute has exactly the same paused-chart-jumps-forward
+  // bug as a backgrounded one.
+  const setFrameActive = useCallback(
+    (next: boolean) => {
+      if (next) {
+        const at = suspendedAtRef.current;
+        if (at !== null) {
+          suspendedAtRef.current = null;
+          // `Math.max(0, ...)` guards a wall clock that stepped backwards
+          // (NTP correction, user changing the device time zone/clock while
+          // the app was away) — never credit negative debt.
+          pendingSuspendedMs.value += Math.max(0, Date.now() - at);
+        }
+      } else if (suspendedAtRef.current === null) {
+        // Only the FIRST transition into suspension stamps the clock: with
+        // two independent causes, `active={false}` while already
+        // backgrounded must not restart the interval and swallow the time
+        // already spent in the background.
+        suspendedAtRef.current = Date.now();
+      }
+      frame.setActive(next);
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- frame and pendingSuspendedMs are identity-stable
+    []
+  );
+
   useEffect(() => {
     const sub = AppState.addEventListener('change', (status) => {
       appForegroundRef.current = status === 'active';
-      frame.setActive(appForegroundRef.current && activePropRef.current);
+      setFrameActive(appForegroundRef.current && activePropRef.current);
     });
     return () => sub.remove();
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- frame is identity-stable
-  }, []);
+  }, [setFrameActive]);
 
   useEffect(() => {
     activePropRef.current = activeProp;
-    frame.setActive(appForegroundRef.current && activeProp);
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- frame is identity-stable
-  }, [activeProp]);
+    setFrameActive(appForegroundRef.current && activeProp);
+  }, [activeProp, setFrameActive]);
 
   // Touch-drag scrub — mirrors the web version's touchmove handling
   // (crosshair follows the finger; releasing fades it out).

From c49bb03cd325ed90779ae09728d52a111bc2aabc Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Sat, 1 Aug 2026 14:10:13 -0400
Subject: [PATCH 26/37] fix(engine/step): blank canvas, stale readout,
 per-frame copies, multi-exit leak
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Six confirmed bugs plus allocation cleanup, from a deep review of the least-
reviewed file in the repo. Adds src/engine/__tests__/step.test.ts — the first
behavioural test of engineStep itself, mocking the draw layer so the engine's
DECISIONS are testable without a Skia binding. Confirmed non-vacuous: reverting
step.ts + state.ts makes 9 of its 14 tests fail.

1. BLANK CANVAS. `visible.length < 2` returned before every draw call, so when
   data existed but nothing was in the window — a stalled feed, or returning
   from background — the recorded picture was literally empty. No grid, no
   empty state, nothing. The multi pipeline already handled the same case
   correctly; single-series now matches it verbatim.

2. STALE LIVE VALUE. `out.valueText` was written only by the single-series
   pipeline, and the hook treats null as "leave unchanged", so `showValue` +
   a switch to candle mode froze the readout on its last line-mode number
   forever. Candle now publishes the same number drawBadge prints two lines
   above (so they cannot disagree); multi publishes an explicit '' since there
   is no single "the" value.

3. `candles.slice()` EVERY CANDLE FRAME on the raw buffer — 60k objects/sec on
   a 500-candle chart at 120Hz — for a consumer that only fires when the user
   changes candle width. Now gated on candlesRev. Subtlety preserved: `.width`
   must still track the previous frame's width every frame, so only the array
   copy is gated.

4. PER-SERIES MAPS NEVER PRUNED ON LEAVING multi mode. All pruning was gated
   inside the multi pipeline, which stops running once isMultiSeries goes
   false — so displayValues, seriesAlpha, the scratch maps and lineCaches
   (which retain SkPaths) all survived. Sibling of the seriesAlpha leak fixed
   in aef4ddf. The agent widened the predicate to cover multi->candle too.

5. A series added while already hidden faded OUT instead of never appearing,
   and briefly widened the Y range. Seeds at target alpha, not 1.

6. REVERSE-MORPH STASH ALIASED THE LIVE CANDLE. `visible.slice()` froze the
   array but its last element IS s.displayCandle, lerped in place every frame,
   so the "frozen" stash kept moving. Now copied into a pooled slot; pooling is
   safe by construction (written only on hasData frames, read only on !hasData).

8. updateGridLayer got raw dt in the line and multi branches while candle
   passed pausedDt and documents why. Fixed both.

9. Per-frame allocations: empty-array sentinels for the points/candles slots,
   pooled scratch for oldVisible and the close-price object. hoverEntries could
   NOT be pooled — it is retained in lastHoverEntries and read on scrub
   fade-out frames — so it starts as a read-only sentinel and allocates only
   inside the active-hover branch.

7 was assessed a FALSE POSITIVE and deliberately not "fixed": cfg is written to
a shared value and therefore deep-cloned into the UI runtime, so cfg.lineData
is a per-commit clone, not the caller's array. Slicing it would add an
unconditional O(n) copy per frame — precisely the bug #3 describes.

state.ts reconciled by 3-way merge: this work and c24ac65 added disjoint field
sets from the same base.

Tests 340 -> 354.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/engine/__tests__/step.test.ts | 402 ++++++++++++++++++++++++++++++
 src/engine/state.ts               |  30 +++
 src/engine/step.ts                | 210 +++++++++++++++-
 3 files changed, 629 insertions(+), 13 deletions(-)
 create mode 100644 src/engine/__tests__/step.test.ts

diff --git a/src/engine/__tests__/step.test.ts b/src/engine/__tests__/step.test.ts
new file mode 100644
index 0000000..b23ca62
--- /dev/null
+++ b/src/engine/__tests__/step.test.ts
@@ -0,0 +1,402 @@
+/**
+ * Behavioural tests for `engineStep`.
+ *
+ * The whole drawing layer is mocked out (`jest.mock` on the modules
+ * `step.ts` calls into), so these exercise the engine's *decisions* — which
+ * draw calls happen, what lands in `StepOutput`, and how `EngineState`
+ * evolves — without needing a Skia binding. Anything that actually needs
+ * Skia geometry stays covered by the per-module tests in `src/draw`.
+ */
+
+jest.mock('@shopify/react-native-skia', () => ({
+  Skia: {
+    PictureRecorder: jest.fn(),
+    XYWHRect: jest.fn(),
+  },
+}));
+
+jest.mock('../../draw', () => {
+  const actual = jest.requireActual('../../draw');
+  return {
+    ...actual,
+    drawFrame: jest.fn(),
+    drawMultiFrame: jest.fn(),
+    drawCandleFrame: jest.fn(),
+    drawEdgeFade: jest.fn(),
+  };
+});
+jest.mock('../../draw/loading', () => ({ drawLoading: jest.fn() }));
+jest.mock('../../draw/empty', () => ({ drawEmpty: jest.fn() }));
+jest.mock('../badge', () => ({ drawBadge: jest.fn() }));
+jest.mock('../gridLayer', () => ({ updateGridLayer: jest.fn() }));
+jest.mock('../lineScrollLayer', () => ({ updateLineScrollLayer: jest.fn() }));
+
+import type {
+  LivelinePoint,
+  LivelinePalette,
+  CandlePoint,
+  LivelineFonts,
+} from '../../types';
+import type { Ctx2D } from '../../draw/canvas2d';
+import type { EngineConfigStep } from '../types';
+import { createEngineState, type EngineState } from '../state';
+import { engineStep } from '../step';
+import {
+  drawFrame,
+  drawMultiFrame,
+  drawCandleFrame,
+  drawEdgeFade,
+} from '../../draw';
+import { drawEmpty } from '../../draw/empty';
+import { drawLoading } from '../../draw/loading';
+
+const W = 400;
+const H = 200;
+const PAD = { top: 10, right: 20, bottom: 20, left: 10 };
+
+const PALETTE: LivelinePalette = {
+  line: '#3b82f6',
+  fillTop: 'rgba(59,130,246,0.3)',
+  fillBottom: 'rgba(59,130,246,0)',
+  dot: '#3b82f6',
+  dotRing: 'rgba(59,130,246,0.3)',
+  gridLine: '#222',
+  gridLabel: '#888',
+  badgeBg: '#3b82f6',
+  badgeText: '#fff',
+  up: '#22c55e',
+  down: '#ef4444',
+} as unknown as LivelinePalette;
+
+const FONTS = {} as unknown as LivelineFonts;
+
+/** Minimal stand-in for the Skia-backed drawing context. `engineStep`
+ * itself only ever touches `ctx.font` / `ctx.fonts` / `ctx.measureText`
+ * (the multi-series label-reserve measurement); everything else goes
+ * through the mocked draw functions. */
+function makeCtx(): Ctx2D {
+  return {
+    font: '',
+    fonts: { seriesLabel: 'label' },
+    measureText: () => ({ width: 10 }),
+  } as unknown as Ctx2D;
+}
+
+function makeCfg(over: Partial<EngineConfigStep> = {}): EngineConfigStep {
+  return {
+    value: 100,
+    palette: PALETTE,
+    windowSecs: 60,
+    lerpSpeed: 0.15,
+    showGrid: false,
+    showBadge: false,
+    showMomentum: false,
+    showFill: false,
+    formatValue: (v: number) => v.toFixed(2),
+    formatTime: (t: number) => String(t),
+    padding: PAD,
+    hasOnHover: false,
+    showPulse: false,
+    scrub: false,
+    active: true,
+    exaggerate: false,
+    badgeTail: false,
+    badgeVariant: 'default' as EngineConfigStep['badgeVariant'],
+    tooltipY: 0,
+    tooltipOutline: false,
+    valueMomentumColor: false,
+    showValue: false,
+    noMotion: true,
+    mode: 'line',
+    dataRev: 1,
+    candlesRev: 1,
+    ...over,
+  } as EngineConfigStep;
+}
+
+function makeState(over: Partial<EngineState> = {}): EngineState {
+  const s = createEngineState(100, 60, false, 60);
+  // Skip the reveal ramp — every test here is about steady state.
+  s.chartReveal = 1;
+  Object.assign(s, over);
+  return s;
+}
+
+function run(
+  s: EngineState,
+  cfg: EngineConfigStep,
+  data: LivelinePoint[] = [],
+  candles: CandlePoint[] = [],
+  multiData: Record<string, LivelinePoint[]> = {}
+) {
+  return engineStep(
+    makeCtx(),
+    cfg,
+    s,
+    W,
+    H,
+    null,
+    16,
+    1000,
+    FONTS,
+    data,
+    candles,
+    multiData
+  );
+}
+
+/** Points spanning `[now - ageSecs - span, now - ageSecs]`. */
+function pointsEnding(ageSecs: number, span = 10, n = 20): LivelinePoint[] {
+  const now = Date.now() / 1000;
+  const out: LivelinePoint[] = [];
+  for (let i = 0; i < n; i++) {
+    out.push({
+      time: now - ageSecs - span + (i / (n - 1)) * span,
+      value: 100 + i,
+    });
+  }
+  return out;
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+
+describe('single-series: no points inside the window', () => {
+  it('draws the empty state + edge fade instead of nothing at all', () => {
+    // Every point is far older than leftEdge (a stalled feed / return from
+    // background), so `visible` comes back empty even though hasData is true.
+    const s = makeState();
+    const out = run(s, makeCfg(), pointsEnding(10_000));
+
+    expect(drawFrame).not.toHaveBeenCalled();
+    expect(drawEmpty).toHaveBeenCalledTimes(1);
+    expect(drawEdgeFade).toHaveBeenCalledTimes(1);
+    expect(out.scrollPicture).toBeNull();
+  });
+
+  it('draws the loading state instead when loadingAlpha is high', () => {
+    const s = makeState({ loadingAlpha: 1 });
+    run(s, makeCfg({ loading: true }), pointsEnding(10_000));
+
+    expect(drawLoading).toHaveBeenCalledTimes(1);
+    expect(drawEmpty).not.toHaveBeenCalled();
+    expect(drawEdgeFade).toHaveBeenCalledTimes(1);
+  });
+
+  it('still draws the chart normally when points are inside the window', () => {
+    const s = makeState();
+    run(s, makeCfg(), pointsEnding(1));
+
+    expect(drawFrame).toHaveBeenCalledTimes(1);
+    expect(drawEmpty).not.toHaveBeenCalled();
+  });
+});
+
+describe('live value readout', () => {
+  it('single-series line mode publishes the formatted value', () => {
+    const s = makeState();
+    const out = run(s, makeCfg({ showValue: true }), pointsEnding(1));
+    expect(out.valueText).toBe('100.00');
+  });
+
+  it('multi-series publishes an explicit blank, not a stale null', () => {
+    const s = makeState();
+    const out = run(
+      s,
+      makeCfg({
+        showValue: true,
+        isMultiSeries: true,
+        multiSeries: [{ id: 'a', value: 100, palette: PALETTE }],
+        multiRevs: { a: 1 },
+      }),
+      [],
+      [],
+      { a: pointsEnding(1) }
+    );
+    expect(drawMultiFrame).toHaveBeenCalledTimes(1);
+    // null would mean "leave unchanged" to useLivelineEngine, freezing
+    // whatever the line pipeline last wrote before the mode switch.
+    expect(out.valueText).toBe('');
+  });
+
+  it('candle mode publishes its own value rather than leaving it stale', () => {
+    const now = Date.now() / 1000;
+    const candles: CandlePoint[] = [
+      { time: now - 120, open: 10, high: 12, low: 9, close: 11 },
+      { time: now - 60, open: 11, high: 13, low: 10, close: 12 },
+    ];
+    const s = makeState();
+    const out = run(
+      s,
+      makeCfg({
+        mode: 'candle',
+        showValue: true,
+        candleWidth: 60,
+        windowSecs: 600,
+      }),
+      [],
+      candles
+    );
+    expect(drawCandleFrame).toHaveBeenCalledTimes(1);
+    expect(out.valueText).not.toBeNull();
+    expect(out.valueText).toBe('12.00');
+  });
+});
+
+describe('multi-series per-series bookkeeping', () => {
+  const multiCfg = (ids: string[], hidden?: string[]) => {
+    const revs: Record<string, number> = {};
+    for (const id of ids) revs[id] = 1;
+    return makeCfg({
+      isMultiSeries: true,
+      multiSeries: ids.map((id) => ({ id, value: 100, palette: PALETTE })),
+      multiRevs: revs,
+      hiddenSeriesIds: hidden,
+      noMotion: false,
+    });
+  };
+
+  const multiPoints = (ids: string[]) => {
+    const out: Record<string, LivelinePoint[]> = {};
+    for (const id of ids) out[id] = pointsEnding(1);
+    return out;
+  };
+
+  it('seeds a series that is already hidden at alpha 0, not 1', () => {
+    const s = makeState();
+    run(s, multiCfg(['a', 'b'], ['b']), [], [], multiPoints(['a', 'b']));
+
+    expect(s.seriesAlpha.get('a')).toBe(1);
+    // Seeding at 1 made a newly-added hidden series flash in and briefly
+    // widen the Y range before fading out.
+    expect(s.seriesAlpha.get('b')).toBe(0);
+  });
+
+  it('still animates an existing series being hidden', () => {
+    const s = makeState();
+    run(s, multiCfg(['a']), [], [], multiPoints(['a']));
+    expect(s.seriesAlpha.get('a')).toBe(1);
+
+    run(s, multiCfg(['a'], ['a']), [], [], multiPoints(['a']));
+    const mid = s.seriesAlpha.get('a')!;
+    expect(mid).toBeGreaterThan(0);
+    expect(mid).toBeLessThan(1);
+  });
+
+  it('prunes every per-series map when the chart leaves multi mode', () => {
+    const s = makeState();
+    run(s, multiCfg(['a', 'b']), [], [], multiPoints(['a', 'b']));
+    expect(s.displayValues.size).toBe(2);
+    expect(s.seriesAlpha.size).toBe(2);
+    expect(s.multiVisibleScratch.size).toBe(2);
+    expect(s.multiSeriesEntryScratch.size).toBe(2);
+
+    // Back to single-series: the multi pipeline stops running, so nothing
+    // inside it can prune these ever again.
+    run(s, makeCfg(), pointsEnding(1));
+
+    expect(s.displayValues.size).toBe(0);
+    expect(s.seriesAlpha.size).toBe(0);
+    expect(s.multiVisibleScratch.size).toBe(0);
+    expect(s.multiSeriesEntryScratch.size).toBe(0);
+    expect(s.lineCaches.size).toBe(0);
+  });
+
+  it('prunes when the chart switches straight to candle mode', () => {
+    const s = makeState();
+    run(s, multiCfg(['a']), [], [], multiPoints(['a']));
+    expect(s.displayValues.size).toBe(1);
+
+    // isMultiSeries deliberately left set — mode alone took the chart out
+    // of the multi pipeline.
+    run(
+      s,
+      makeCfg({
+        mode: 'candle',
+        isMultiSeries: true,
+        multiSeries: [{ id: 'a', value: 100, palette: PALETTE }],
+      }),
+      [],
+      []
+    );
+    expect(s.displayValues.size).toBe(0);
+    expect(s.seriesAlpha.size).toBe(0);
+  });
+
+  it('does not prune while still in multi mode', () => {
+    const s = makeState();
+    run(s, multiCfg(['a', 'b']), [], [], multiPoints(['a', 'b']));
+    run(s, multiCfg(['a', 'b']), [], [], multiPoints(['a', 'b']));
+    expect(s.displayValues.size).toBe(2);
+  });
+});
+
+describe('candle mode', () => {
+  const now = Date.now() / 1000;
+  const closed: CandlePoint[] = [
+    { time: now - 180, open: 10, high: 12, low: 9, close: 11 },
+    { time: now - 120, open: 11, high: 13, low: 10, close: 12 },
+  ];
+  const candleCfg = (over: Partial<EngineConfigStep> = {}) =>
+    makeCfg({
+      mode: 'candle',
+      candleWidth: 60,
+      windowSecs: 600,
+      noMotion: false,
+      ...over,
+    });
+
+  it('only re-copies prevCandleData when candlesRev moves', () => {
+    const s = makeState();
+    run(s, candleCfg({ candlesRev: 1 }), [], closed);
+    const first = s.prevCandleData.candles;
+    expect(first).toHaveLength(2);
+
+    run(s, candleCfg({ candlesRev: 1 }), [], closed);
+    // Same revision — the (unread) copy must be skipped entirely.
+    expect(s.prevCandleData.candles).toBe(first);
+
+    run(s, candleCfg({ candlesRev: 2 }), [], closed);
+    expect(s.prevCandleData.candles).not.toBe(first);
+  });
+
+  it('keeps prevCandleData.width tracking the previous frame width', () => {
+    const s = makeState();
+    run(s, candleCfg({ candlesRev: 1, candleWidth: 60 }), [], closed);
+    expect(s.prevCandleData.width).toBe(60);
+
+    // A width change with no data change must still see the *old* width as
+    // `cwt.oldWidth` — that is what the morph interpolates away from.
+    run(s, candleCfg({ candlesRev: 1, candleWidth: 30 }), [], closed);
+    expect(s.candleWidthTrans.oldWidth).toBe(60);
+    expect(s.prevCandleData.width).toBe(30);
+  });
+
+  it('freezes the live candle in the reverse-morph stash', () => {
+    const s = makeState();
+    const live = { time: now - 30, open: 12, high: 20, low: 5, close: 18 };
+    // Two data frames: the first births the display candle at `open`, the
+    // second lerps it partway toward `live` and stashes it.
+    run(s, candleCfg({ liveCandle: live }), [], closed);
+    run(s, candleCfg({ liveCandle: live }), [], closed);
+
+    const stashed = s.lastLive!;
+    expect(stashed).not.toBeNull();
+    // The stash must own a copy, not the live (in-place lerped) candle.
+    expect(stashed).not.toBe(s.displayCandle);
+    expect(s.lastCandles[s.lastCandles.length - 1]).toBe(stashed);
+    const snapshot = { ...stashed };
+    expect(snapshot.close).not.toBe(live.close);
+
+    // Data disappears → reverse morph. `s.displayCandle` keeps lerping
+    // toward `live`; the stash the morph draws from must not move with it.
+    run(s, candleCfg({ liveCandle: live }), [], []);
+    run(s, candleCfg({ liveCandle: live }), [], []);
+    expect(s.displayCandle!.close).not.toBe(snapshot.close);
+    expect(s.lastLive!.close).toBe(snapshot.close);
+    expect(s.lastLive!.high).toBe(snapshot.high);
+    const lastStashed = s.lastCandles[s.lastCandles.length - 1]!;
+    expect(lastStashed.close).toBe(snapshot.close);
+  });
+});
diff --git a/src/engine/state.ts b/src/engine/state.ts
index 86e086d..227dfa9 100644
--- a/src/engine/state.ts
+++ b/src/engine/state.ts
@@ -242,6 +242,32 @@ export interface EngineState {
     oldWidth: number;
   };
   prevCandleData: { candles: CandlePoint[]; width: number };
+  /** `cfg.candlesRev` the `prevCandleData.candles` copy was taken at, so the
+   * copy is skipped on every frame where the candle buffer hasn't changed
+   * (same mechanism, and same reason, as `lastDataStashRev` above — the only
+   * consumer is the candle-width-change branch, which fires when the *user*
+   * changes candle width). `.width` is still refreshed every frame: it must
+   * always describe the previous frame's width for that branch to read.
+   * -1 (never a real revision) forces the first copy. */
+  prevCandleDataRev: number;
+  /** Pooled frozen copy of the live candle for the reverse-morph stash.
+   * `s.displayCandle` (== `smoothLive`, and the last element of the visible
+   * array) is lerped in place every frame, so `lastCandles = visible.slice()`
+   * alone would leave the "frozen" stash still moving. Safe to pool: it is
+   * only written on `hasData` frames and only read on `!hasData` frames (see
+   * `useStash` in step.ts), which are disjoint. */
+  lastLiveStash: CandlePoint;
+  /** Scratch array for candle mode's per-frame *old*-candles visible build
+   * (the candle-width morph's outgoing set). Reused/refilled like
+   * `candleVisibleScratch`; never retained past the frame — `drawCandleFrame`
+   * reads `oldCandles` synchronously (and `.map()`s it into a fresh array
+   * when the OHLC collapse is active). */
+  candleOldVisibleScratch: CandlePoint[];
+  /** Pooled candle handed to `drawCandleFrame` as `closePriceCandle` — the
+   * raw live candle with its close replaced by the smoothed close. Read
+   * synchronously by `drawClosePrice` and never retained, so one reused
+   * object beats a fresh spread every candle frame. */
+  closePriceScratch: CandlePoint;
   pausedCandles: CandlePoint[] | null;
   pausedLive: CandlePoint | null;
   pausedLineData: LivelinePoint[] | null;
@@ -464,6 +490,10 @@ export function createEngineState(
       oldWidth: candleWidth,
     },
     prevCandleData: { candles: [], width: candleWidth },
+    prevCandleDataRev: -1,
+    lastLiveStash: { time: 0, open: 0, high: 0, low: 0, close: 0 },
+    candleOldVisibleScratch: [],
+    closePriceScratch: { time: 0, open: 0, high: 0, low: 0, close: 0 },
     pausedCandles: null,
     pausedLive: null,
     pausedLineData: null,
diff --git a/src/engine/step.ts b/src/engine/step.ts
index 6828994..6f2d436 100644
--- a/src/engine/step.ts
+++ b/src/engine/step.ts
@@ -115,6 +115,21 @@ const EMPTY_MULTI_POINTS: LivelinePoint[] = [];
  * from the other's call sites; both are read-only. */
 const EMPTY_LINE_POINTS: LivelinePoint[] = [];
 
+/** Stable empty arrays for the *other* mode's slot in the `points` /
+ * `effectiveCandles` pair below — exactly one of the two is real on any
+ * given frame and the unused one is never read past its `.length` check,
+ * so both may share a module-level empty. Read-only, like the two above. */
+const EMPTY_POINTS_SLOT: LivelinePoint[] = [];
+const EMPTY_CANDLES_SLOT: CandlePoint[] = [];
+
+/** Stable empty array for multi-series hover entries on frames with no
+ * active hover — which is nearly all of them. A fresh array is allocated
+ * only inside the active-hover branch, where it is retained in
+ * `s.lastHoverEntries` for the scrub fade-out and so genuinely cannot be
+ * pooled. Read-only (`drawMultiFrame` only reads it). */
+const EMPTY_HOVER_ENTRIES: { color: string; label: string; value: number }[] =
+  [];
+
 /**
  * Look up a multi-series entry's data points. `series` is either a live
  * `cfg.multiSeries` entry (no `.data` — its points live in `multiData`,
@@ -216,8 +231,10 @@ export function engineStep(
     }
   }
 
-  const points = isCandle ? ([] as LivelinePoint[]) : (s.pausedData ?? data);
-  const effectiveCandles = isCandle ? (s.pausedCandles ?? candles) : [];
+  const points = isCandle ? EMPTY_POINTS_SLOT : (s.pausedData ?? data);
+  const effectiveCandles = isCandle
+    ? (s.pausedCandles ?? candles)
+    : EMPTY_CANDLES_SLOT;
   const hasMultiData =
     cfg.isMultiSeries && cfg.multiSeries
       ? cfg.multiSeries.some(
@@ -390,6 +407,30 @@ export function engineStep(
     }
   }
 
+  // Per-series bookkeeping is pruned *inside* the multi pipeline, which
+  // stops running the instant the chart leaves multi-series mode (mode
+  // switch, `isMultiSeries` going false, or the series list emptying out).
+  // Everything keyed by series id then survives indefinitely — including
+  // `lineCaches`, which retains an SkPath per series — so a chart that
+  // toggles multi → single → multi with a different series set accumulates
+  // them. Sibling of the within-multi-mode prune below (PLAN_MAINT #3);
+  // deliberately placed above the loading/empty early return so the
+  // "multiSeries went empty" case is covered too. `displayValues` is
+  // written for every series on every non-stash multi frame, so a non-zero
+  // size is an exact "this chart has multi state to drop" test, and it
+  // becomes 0 on the first frame after the switch — no per-frame work, and
+  // the one `Set` allocation happens only on that transition frame.
+  // Mirrors the multi pipeline's own `else if` condition below, `isCandle`
+  // included — a chart that switches straight from multi to candle mode
+  // while `isMultiSeries` is still set has left the pipeline just as surely.
+  const inMultiPipeline =
+    !isCandle &&
+    ((cfg.isMultiSeries && cfg.multiSeries && cfg.multiSeries.length > 0) ||
+      useMultiStash);
+  if (!inMultiPipeline && s.displayValues.size > 0) {
+    pruneByIds(new Set<string>(), perSeriesMaps(s));
+  }
+
   if (!hasData && !useStash && !useMultiStash) {
     // No chart pipeline — draw loading or empty as the sole visual.
     // Grey loading line for candle mode and multi-series (no single accent color)
@@ -507,7 +548,28 @@ export function engineStep(
     // JS-thread delta applier via `.modify()`); stashing a bare reference
     // would let a later tick silently rewrite `cwt.oldCandles` (read on a
     // future candle-width-change frame) out from under this snapshot.
-    s.prevCandleData = { candles: candles.slice(), width: candleWidthSecs };
+    //
+    // Revision-gated for the same reason as `s.lastData` above: the copy's
+    // only consumer is the `candleWidthSecs !== cwt.toWidth` branch directly
+    // above — i.e. frames where the *user* changed candle width — while this
+    // ran unconditionally, copying the whole buffer every frame. A 500-candle
+    // chart at 120Hz was allocating 60k objects a second and discarding all
+    // of them. `cfg.candlesRev` moves exactly when the buffer does.
+    //
+    // `.width` is deliberately still refreshed every frame (a scalar, no
+    // allocation): the branch above reads it as `cwt.oldWidth`, and its
+    // correctness depends on it holding the *previous* frame's width, not
+    // the width the point copy happens to have been taken at. Mutated in
+    // place rather than replaced so the object identity is stable; the
+    // `.candles` slot is *reassigned* (never spliced) on a new revision, so
+    // a `cwt.oldCandles` reference grabbed earlier still points at the
+    // snapshot it was given.
+    const prevCandleData = s.prevCandleData;
+    if (s.prevCandleDataRev !== cfg.candlesRev) {
+      prevCandleData.candles = candles.slice();
+      s.prevCandleDataRev = cfg.candlesRev;
+    }
+    prevCandleData.width = candleWidthSecs;
 
     // lineModeProg is updated before the early return (see above).
     const lineModeProg = s.lineModeProg;
@@ -719,7 +781,10 @@ export function engineStep(
     ) {
       visible.push(smoothLive);
     }
-    let oldVisible: CandlePoint[] = [];
+    // Reused scratch array (see EngineState.candleOldVisibleScratch) — same
+    // rationale as `visible` above; nothing retains it past this frame.
+    const oldVisible: CandlePoint[] = s.candleOldVisibleScratch;
+    oldVisible.length = 0;
     if (morphT >= 0 && cwt.oldCandles.length > 0) {
       for (const c of cwt.oldCandles) {
         if (c.time + cwt.oldWidth >= leftEdge && c.time <= rightEdge) {
@@ -735,9 +800,32 @@ export function engineStep(
     // corrupt this stash out from under the reverse morph. Mirrors the
     // `s.lastData = points.slice()` copy above and its comment, for the
     // same reason.
+    //
+    // The `.slice()` alone is not enough, though: `visible`'s last element
+    // IS `smoothLive` === `s.displayCandle`, whose OHLC is lerped in place
+    // every frame above — so a copied array full of live references would
+    // still keep moving during the reverse morph, and `s.lastLive` pointed
+    // at the same moving object. Freeze the live candle's *values* too, into
+    // a pooled slot (see EngineState.lastLiveStash). Pooling is safe because
+    // this block only runs while `hasData`, and the stash is only read while
+    // `!hasData` (`useStash`) — disjoint sets of frames.
     if (hasData) {
       s.lastCandles = visible.slice();
-      s.lastLive = smoothLive ?? null;
+      if (smoothLive) {
+        const frozen = s.lastLiveStash;
+        frozen.time = smoothLive.time;
+        frozen.open = smoothLive.open;
+        frozen.high = smoothLive.high;
+        frozen.low = smoothLive.low;
+        frozen.close = smoothLive.close;
+        const li = s.lastCandles.length - 1;
+        if (li >= 0 && s.lastCandles[li] === smoothLive) {
+          s.lastCandles[li] = frozen;
+        }
+        s.lastLive = frozen;
+      } else {
+        s.lastLive = null;
+      }
     }
     const effectiveVisible = useStash ? s.lastCandles : visible;
     const effectiveLive = useStash ? (s.lastLive ?? undefined) : smoothLive;
@@ -995,6 +1083,21 @@ export function engineStep(
     }
 
     // --- Draw ---
+    // Pooled instead of `{ ...rawLive, close: s.closeLineSmooth }` — that
+    // spread allocated a candle every frame in candle mode. Safe: the only
+    // consumer is `drawClosePrice`, reached synchronously from
+    // `drawCandleFrame` below, which reads the fields and never retains the
+    // object (see EngineState.closePriceScratch).
+    let closePriceCandle: CandlePoint | undefined = rawLive;
+    if (s.closeLineSmoothInited && rawLive) {
+      const cp = s.closePriceScratch;
+      cp.time = rawLive.time;
+      cp.open = rawLive.open;
+      cp.high = rawLive.high;
+      cp.low = rawLive.low;
+      cp.close = s.closeLineSmooth;
+      closePriceCandle = cp;
+    }
     drawCandleFrame(ctx, layout, cfg.palette, {
       candles: drawCandles,
       displayCandleWidth,
@@ -1002,10 +1105,7 @@ export function engineStep(
       oldWidth: cwt.oldWidth,
       morphT,
       liveCandle: drawLive,
-      closePriceCandle:
-        s.closeLineSmoothInited && rawLive
-          ? { ...rawLive, close: s.closeLineSmooth }
-          : rawLive,
+      closePriceCandle,
       liveTime: effectiveLive?.time ?? -1,
       liveBirthAlpha: s.liveBirthAlpha,
       liveBullBlend: s.liveBull,
@@ -1064,6 +1164,35 @@ export function engineStep(
       );
     }
 
+    // --- Live value display ---
+    // `out.valueText` used to be written only by the single-series line
+    // pipeline, and `null` means "leave unchanged" to the caller — so a
+    // chart switched from line to candle mode froze its readout on the last
+    // line-mode value forever, and a chart mounted in candle mode showed a
+    // blank one. Publish candle mode's own live value: `lineSmoothValue` is
+    // the same number the badge above prints, so the two can never disagree.
+    if (cfg.showValue) {
+      const displayVal = cfg.valueMomentumColor
+        ? Math.abs(lineSmoothValue)
+        : lineSmoothValue;
+      out.valueText = cfg.formatValue(displayVal);
+      if (cfg.valueMomentumColor) {
+        // Candle mode's direction signal is the live candle's own
+        // bull/bear — the exact thing the chart is already colouring the
+        // candle by — rather than line mode's `detectMomentum` scan, which
+        // would read an overlay array that is deliberately empty on most
+        // candle frames (see `wantLineVisible` above). '' = default colour.
+        const lc = drawLive;
+        out.valueColor = !lc
+          ? ''
+          : lc.close > lc.open
+            ? '#22c55e'
+            : lc.close < lc.open
+              ? '#ef4444'
+              : '';
+      }
+    }
+
     return out;
   } else if (
     (cfg.isMultiSeries && cfg.multiSeries && cfg.multiSeries.length > 0) ||
@@ -1163,8 +1292,14 @@ export function engineStep(
     const hiddenIds = cfg.hiddenSeriesIds;
     const seriesAlphas = s.seriesAlpha;
     for (const series of effectiveMultiSeries) {
-      let alpha = seriesAlphas.get(series.id) ?? 1;
       const target = hiddenIds && hiddenIds.indexOf(series.id) >= 0 ? 0 : 1;
+      // Seed a brand-new id at its *target*, not at 1: a series added while
+      // already in `hiddenSeriesIds` would otherwise start fully opaque and
+      // fade out, flashing in for ~a dozen frames — and, worse, counting
+      // toward the Y-range scan below (which excludes alpha <= 0.01) and
+      // visibly widening the axis while it faded. An id already in the map
+      // keeps its in-flight alpha, so toggling still animates.
+      let alpha = seriesAlphas.get(series.id) ?? target;
       alpha = noMotion
         ? target
         : lerp(alpha, target, SERIES_TOGGLE_SPEED, pausedDt);
@@ -1376,6 +1511,9 @@ export function engineStep(
     // Cross-frame grid picture cache — see engine/gridLayer.ts. Bypassed
     // while the reveal morph is animating (ctx.drawPicture ignores
     // globalAlpha; see the candle-mode branch above for the full reason).
+    // pausedDt (not dt) — the grid layer owns `gridState`'s label crossfades,
+    // and the candle branch documents why they must freeze with pause; this
+    // call site and the single-series one below were the two that didn't.
     if (cfg.showGrid && chartReveal >= 1) {
       updateGridLayer(
         s.gridLayer,
@@ -1383,7 +1521,7 @@ export function engineStep(
         layout,
         cfg.palette,
         cfg.formatValue,
-        dt,
+        pausedDt,
         s.gridLayerCache,
         fonts
       );
@@ -1394,7 +1532,12 @@ export function engineStep(
     let drawHoverX: number | null = null;
     let drawHoverTime: number | null = null;
     let isActiveHover = false;
-    let hoverEntries: { color: string; label: string; value: number }[] = [];
+    // Shared read-only empty until a hover actually happens — see
+    // EMPTY_HOVER_ENTRIES. The array below genuinely can't be pooled: it is
+    // handed to `s.lastHoverEntries` and read back on the scrub fade-out
+    // frames, so a single reused buffer would be cleared out from under it.
+    let hoverEntries: { color: string; label: string; value: number }[] =
+      EMPTY_HOVER_ENTRIES;
 
     if (hoverPx !== null && hoverPx >= pad.left && hoverPx <= w - pad.right) {
       const maxHoverX = layout.toX(now);
@@ -1404,6 +1547,7 @@ export function engineStep(
       drawHoverX = clampedX;
       drawHoverTime = t;
       isActiveHover = true;
+      hoverEntries = [];
 
       for (const entry of seriesEntries) {
         // Skip hidden series from crosshair tooltip
@@ -1510,6 +1654,16 @@ export function engineStep(
       }
     }
 
+    // --- Live value display ---
+    // Multi-series has no single "the" value to show, but leaving
+    // `out.valueText` as `null` means "leave unchanged" to the caller — so a
+    // chart switched from single-series to multi kept displaying whatever
+    // the line pipeline last wrote, forever. Publish an explicit blank.
+    if (cfg.showValue) {
+      out.valueText = '';
+      out.valueColor = '';
+    }
+
     // No badge in multi-series mode
     return out;
   } else {
@@ -1592,6 +1746,32 @@ export function engineStep(
     filterVisiblePointsInto(effectivePoints, leftEdge, filterRight, visible);
 
     if (visible.length < 2) {
+      // Data exists (`hasData` is true, so `chartReveal` is heading to 1 and
+      // the loading/empty early return at the top of the function is not
+      // reached) but none of it lands inside the current window — a stalled
+      // feed, or coming back from background, leaves every point older than
+      // `leftEdge`. Returning here without drawing anything left the recorded
+      // picture completely empty: no grid, no empty state, a fully
+      // transparent chart. Draw the loading/empty fallback + edge fade, which
+      // is exactly what the multi-series pipeline already does for the
+      // identical `seriesEntries.length === 0` case above.
+      if (loadingAlpha > 0.01) {
+        drawLoading(ctx, w, h, pad, cfg.palette, now_ms, loadingAlpha);
+      }
+      if (1 - loadingAlpha > 0.01) {
+        drawEmpty(
+          ctx,
+          w,
+          h,
+          pad,
+          cfg.palette,
+          1 - loadingAlpha,
+          now_ms,
+          false,
+          cfg.emptyText
+        );
+      }
+      drawEdgeFade(ctx, pad.left, h);
       return out;
     }
 
@@ -1638,6 +1818,10 @@ export function engineStep(
     // Cross-frame grid picture cache — see engine/gridLayer.ts. Bypassed
     // while the reveal morph is animating (ctx.drawPicture ignores
     // globalAlpha; see the candle-mode branch above for the full reason).
+    // pausedDt (not dt) — this pipeline already hands `drawFrame` pausedDt,
+    // and `drawFrame`'s own inline `drawGrid` (the reveal < 1 path) drives
+    // the same `gridState` label fades from it, so raw dt here meant the
+    // fades froze or didn't depending purely on which path drew the grid.
     if (cfg.showGrid && chartReveal >= 1) {
       updateGridLayer(
         s.gridLayer,
@@ -1645,7 +1829,7 @@ export function engineStep(
         layout,
         cfg.palette,
         cfg.formatValue,
-        dt,
+        pausedDt,
         s.gridLayerCache,
         fonts
       );

From 03500725d8b070bf35d67b0274398fec6fd8e990 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Sat, 1 Aug 2026 14:25:16 -0400
Subject: [PATCH 27/37] perf(draw): reusable Canvas2D context; drop per-label
 save/restore
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

**Reusable ctx.** createCanvas2D built a fresh ~29-allocation object (23
interface methods, 3 helper closures, the save stack, the dash array) on EVERY
recording — 60/sec per Liveline instance, plus each nested grid/scroll-layer
re-record. It was unavoidable only because every method closed over `canvas`,
which is new per recording. The ctx now lives on SkiaCache and is retargeted:
closures read a mutable `cv` instead of a captured const. Zero allocations on
every call past the first per cache. Signature and return type unchanged, so
no call site moved.

Per-recording state is enumerated in a numbered comment block and reset in one
place (`retarget`): canvas, pooled path contents, the adopted-path pointer,
lineDash, the save stack, fonts, and all 13 style props. The build path routes
through retarget too, so it is the single source of truth and the first
recording is identical to every later one.

CRITICAL invariant, documented on the field: one ctx PER CACHE, never module
scope. Two recordings are live simultaneously — engine/gridLayer.ts and
engine/lineScrollLayer.ts each open a nested recorder during the main frame's
recording, and each already passes its own SkiaCache precisely so pooled
paints cannot alias. One ctx per cache inherits that isolation exactly; a
single shared ctx would let the nested recording scribble into the main one,
intermittently.

**Per-label save/restore in drawTimeAxis.** Each save() allocated a 14-field
StyleSnapshot AND issued a canvas.save() JSI call recording a save/restore
pair into the picture — 6-10 of each per frame, plus 12-20 extra recorded ops.
It only protected four properties the next iteration reassigns unconditionally.
Hoisted the loop-invariant ones; globalAlpha is set per label and restored once
after the loop.

Merged with care rather than copied: the agent's base was `main`, so a file
copy would have silently reverted this branch's label-text memoization,
off-screen churn fix and closure hoists. 3-way merged against main as the base
(clean, zero conflicts) and verified both sides survived. typecheck then caught
what jest could not — the agent's test built a TimeAxisState without the
memoization's formatTimeRef field; tests passed regardless because jest does
not typecheck.

Adds timeAxisCallBudget.test.ts (5 tests) kept separate from timeAxis.test.ts:
disjoint concerns (call budget vs formatter memoization) and different fake-ctx
harnesses. One test asserts saveCount === 0 while >= 3 labels draw, which pins
this change directly.

Verified on the simulator: Line, Candles, Multi, Dashboard, Orderbook. Dashboard
is the strongest case — four concurrent instances means four caches and four
contexts, which is exactly where a shared-ctx aliasing bug would show.

Tests 354 -> 359. yarn install --immutable passes; bob build clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/draw/__tests__/timeAxisCallBudget.test.ts | 240 ++++++++++++++++++
 src/draw/canvas2d.ts                          | 182 +++++++++++--
 src/draw/timeAxis.ts                          |  20 +-
 3 files changed, 411 insertions(+), 31 deletions(-)
 create mode 100644 src/draw/__tests__/timeAxisCallBudget.test.ts

diff --git a/src/draw/__tests__/timeAxisCallBudget.test.ts b/src/draw/__tests__/timeAxisCallBudget.test.ts
new file mode 100644
index 0000000..1852f9a
--- /dev/null
+++ b/src/draw/__tests__/timeAxisCallBudget.test.ts
@@ -0,0 +1,240 @@
+import { drawTimeAxis, type TimeAxisState } from '../timeAxis';
+import type { Ctx2D, Style2D } from '../canvas2d';
+import type { ChartLayout, LivelinePalette, Padding } from '../../types';
+
+// ── Fake Ctx2D recorder ──────────────────────────────────────────────────
+// Covers exactly the methods drawTimeAxis calls. Records the style state at
+// each stroke()/fillText() plus the save()/restore() counts — the thing under
+// test is the per-frame call budget (drawTimeAxis used to save/restore around
+// every single label) and the fact that dropping those pairs didn't change
+// the per-label styling.
+
+interface Call {
+  op: 'stroke' | 'fillText';
+  alpha: number;
+  style: Style2D;
+  lineWidth: number;
+}
+
+const LABEL_W = 30;
+
+class FakeCtx implements Ctx2D {
+  fillStyle: Style2D = '#000000';
+  strokeStyle: Style2D = '#000000';
+  lineWidth = 1;
+  globalAlpha = 1;
+  lineCap: Ctx2D['lineCap'] = 'butt';
+  lineJoin: Ctx2D['lineJoin'] = 'miter';
+  font = {} as Ctx2D['font'];
+  textAlign: Ctx2D['textAlign'] = 'left';
+  textBaseline: Ctx2D['textBaseline'] = 'alphabetic';
+  globalCompositeOperation: Ctx2D['globalCompositeOperation'] = 'source-over';
+  shadowColor: Ctx2D['shadowColor'] = 'rgba(0,0,0,0)';
+  shadowBlur = 0;
+  shadowOffsetY = 0;
+  fonts = { label: {} } as unknown as Ctx2D['fonts'];
+
+  calls: Call[] = [];
+  saveCount = 0;
+  restoreCount = 0;
+  private saved: Partial<FakeCtx>[] = [];
+
+  save() {
+    this.saveCount++;
+    this.saved.push({
+      fillStyle: this.fillStyle,
+      strokeStyle: this.strokeStyle,
+      lineWidth: this.lineWidth,
+      globalAlpha: this.globalAlpha,
+    });
+  }
+  restore() {
+    this.restoreCount++;
+    const s = this.saved.pop();
+    if (s) {
+      this.fillStyle = s.fillStyle!;
+      this.strokeStyle = s.strokeStyle!;
+      this.lineWidth = s.lineWidth!;
+      this.globalAlpha = s.globalAlpha!;
+    }
+  }
+  beginPath() {}
+  beginPathFrom() {}
+  closePath() {}
+  moveTo() {}
+  lineTo() {}
+  bezierCurveTo() {}
+  cubicTo() {}
+  arc() {}
+  arcTo() {}
+  rect() {}
+  fill() {}
+  stroke() {
+    this.calls.push({
+      op: 'stroke',
+      alpha: this.globalAlpha,
+      style: this.strokeStyle,
+      lineWidth: this.lineWidth,
+    });
+  }
+  clipRect() {}
+  fillRect() {}
+  fillText() {
+    this.calls.push({
+      op: 'fillText',
+      alpha: this.globalAlpha,
+      style: this.fillStyle,
+      lineWidth: this.lineWidth,
+    });
+  }
+  strokeText() {}
+  measureText() {
+    return { width: LABEL_W };
+  }
+  setLineDash() {}
+  createLinearGradient() {
+    return {
+      isGradient: true as const,
+      x0: 0,
+      y0: 0,
+      x1: 0,
+      y1: 0,
+      offsets: [],
+      colors: [],
+      addColorStop() {},
+    };
+  }
+  translate() {}
+  drawPicture() {}
+}
+
+const PAD: Required<Padding> = { top: 10, right: 10, bottom: 24, left: 10 };
+
+function makeLayout(w = 600, h = 240): ChartLayout {
+  const chartW = w - PAD.left - PAD.right;
+  const chartH = h - PAD.top - PAD.bottom;
+  const leftEdge = 0;
+  const rightEdge = 300; // 5-minute window
+  return {
+    w,
+    h,
+    pad: PAD,
+    chartW,
+    chartH,
+    leftEdge,
+    rightEdge,
+    minVal: 0,
+    maxVal: 100,
+    valRange: 100,
+    toX: (t: number) =>
+      PAD.left + ((t - leftEdge) / (rightEdge - leftEdge)) * chartW,
+    toY: (v: number) => PAD.top + (1 - v / 100) * chartH,
+  };
+}
+
+const PALETTE = {
+  gridLine: '#333333',
+  timeLabel: '#999999',
+} as unknown as LivelinePalette;
+
+function makeState(): TimeAxisState {
+  return {
+    labels: new Map(),
+    targetsScratch: new Set(),
+    visibleLabelsScratch: [],
+    drawnScratch: [],
+    labelEntryPool: [],
+    // Added by the label-text memoization (see timeAxis.test.ts); null means
+    // "no formatter seen yet", so the first frame formats every label.
+    formatTimeRef: null,
+  };
+}
+
+const WINDOW = 300;
+const formatTime = (t: number) => `t${Math.round(t)}`;
+
+/** Runs `frames` frames against one persistent state so the label alphas
+ * ramp up out of their initial 0, then returns the LAST frame's recorder. */
+function run(frames: number, baseAlpha = 1): FakeCtx {
+  const state = makeState();
+  const layout = makeLayout();
+  let ctx = new FakeCtx();
+  for (let i = 0; i < frames; i++) {
+    ctx = new FakeCtx();
+    ctx.globalAlpha = baseAlpha;
+    // dt is in milliseconds (see math/lerp) — one 60fps frame per iteration.
+    drawTimeAxis(
+      ctx,
+      layout,
+      PALETTE,
+      WINDOW,
+      WINDOW,
+      formatTime,
+      state,
+      16.67
+    );
+  }
+  return ctx;
+}
+
+describe('drawTimeAxis per-frame call budget', () => {
+  it('issues no save()/restore() at all — not one pair per label', () => {
+    const ctx = run(60);
+    const labelCount = ctx.calls.filter((c) => c.op === 'fillText').length;
+
+    expect(labelCount).toBeGreaterThan(2); // the loop actually ran
+    expect(ctx.saveCount).toBe(0);
+    expect(ctx.restoreCount).toBe(0);
+  });
+
+  it('strokes exactly one tick per label, plus the single axis line', () => {
+    const ctx = run(60);
+    const strokes = ctx.calls.filter((c) => c.op === 'stroke').length;
+    const labels = ctx.calls.filter((c) => c.op === 'fillText').length;
+
+    expect(strokes).toBe(labels + 1);
+  });
+});
+
+describe('drawTimeAxis per-label state', () => {
+  it('applies each label its own alpha and leaves globalAlpha at the caller value', () => {
+    const baseAlpha = 0.5;
+    const ctx = run(30, baseAlpha);
+    const texts = ctx.calls.filter((c) => c.op === 'fillText');
+
+    expect(texts.length).toBeGreaterThan(2);
+    for (const c of texts) {
+      expect(c.alpha).toBeGreaterThan(0);
+      expect(c.alpha).toBeLessThanOrEqual(baseAlpha);
+    }
+    // Labels mid-fade differ from each other, so a leaked alpha from the
+    // previous iteration would be visible as a wrong value here.
+    expect(ctx.globalAlpha).toBe(baseAlpha);
+  });
+
+  it('draws every tick with the grid stroke and every label with the label fill', () => {
+    const ctx = run(60);
+
+    for (const c of ctx.calls) {
+      if (c.op === 'stroke') {
+        expect(c.style).toBe(PALETTE.gridLine);
+        expect(c.lineWidth).toBe(1);
+      } else {
+        expect(c.style).toBe(PALETTE.timeLabel);
+      }
+    }
+  });
+
+  it('pairs each label fillText with a tick stroke at the same alpha', () => {
+    const ctx = run(45, 0.8);
+    // calls: [axis-line stroke, (tick stroke, fillText) x N]
+    const rest = ctx.calls.slice(1);
+    expect(rest.length).toBeGreaterThanOrEqual(6);
+    expect(rest.length % 2).toBe(0);
+    for (let i = 0; i < rest.length; i += 2) {
+      expect(rest[i]!.op).toBe('stroke');
+      expect(rest[i + 1]!.op).toBe('fillText');
+      expect(rest[i + 1]!.alpha).toBe(rest[i]!.alpha);
+    }
+  });
+});
diff --git a/src/draw/canvas2d.ts b/src/draw/canvas2d.ts
index 4802b20..30eb481 100644
--- a/src/draw/canvas2d.ts
+++ b/src/draw/canvas2d.ts
@@ -30,6 +30,12 @@ import type { LivelineFonts } from '../types';
 // worklets that capture it (see the closure-capture note below).
 const BLUR_SHADOWS = Platform.OS !== 'android';
 
+// The "no dash" value for the shim's `lineDash` state. Shared module-level
+// constant so retargeting the ctx for a new recording can reset the dash
+// state without allocating a fresh empty array — same INVARIANT as
+// setLineDash's callers: nothing may ever mutate a dash array in place.
+const NO_DASH: number[] = [];
+
 /**
  * A Canvas2D-flavored adapter over Skia's SkCanvas.
  *
@@ -143,6 +149,31 @@ export interface Ctx2D {
   drawPicture(picture: SkPicture): void;
 }
 
+/**
+ * The internal, retargetable flavor of `Ctx2D` stored on `SkiaCache.ctx`.
+ *
+ * `createCanvas2D` used to build a fresh ~36-property object with ~28 method
+ * closures on every recording (60x/sec on the UI thread) purely because every
+ * method closed over the frame's `SkCanvas`. The closures now read a mutable
+ * `cv` instead, so one instance can serve every recording made through a
+ * given cache — `retarget()` points it at the new canvas and resets all
+ * per-recording state.
+ *
+ * `fonts` is re-declared writable here (it's `readonly` on `Ctx2D`, which is
+ * what draw code sees) so `retarget` can swap the font set along with the
+ * canvas.
+ */
+export interface ReusableCtx2D extends Ctx2D {
+  fonts: LivelineFonts;
+  /**
+   * Point this ctx at a new recording canvas and clear every piece of
+   * per-recording state. See the implementation in `createCanvas2D` for the
+   * full enumeration — anything not reset there leaks from one recording
+   * into the next.
+   */
+  retarget(canvas: SkCanvas, fonts: LivelineFonts): void;
+}
+
 interface StyleSnapshot {
   fillStyle: Style2D;
   strokeStyle: Style2D;
@@ -174,9 +205,10 @@ interface StyleSnapshot {
  * Cross-frame cache for Skia objects created by the Canvas2D shim: immutable
  * objects (gradients, dash effects, blur mask filters, parsed colors), plus
  * memoized text measurements (widths, font metrics), plus a pool of the
- * mutable path/paint host objects the shim draws through (see `pool`).
- * `createCanvas2D` is recreated
- * every frame, so this cache must live outside it — the caller
+ * mutable path/paint host objects the shim draws through (see `pool`), plus
+ * the reusable Canvas2D adapter itself (see `ctx`).
+ * Everything here outlives a single recording, so this cache must live
+ * outside `createCanvas2D` — the caller
  * (`useLivelineEngine`) owns one on a `useSharedValue` on the UI runtime and
  * passes it in every frame. Plain string-keyed records only (no Map/WeakMap):
  * this object crosses the Reanimated worklet boundary, which doesn't support
@@ -218,6 +250,22 @@ export interface SkiaCache {
     // "assign now, consume later" gap here to create aliasing risk.
     rect: SkHostRect;
   } | null;
+  /**
+   * The reusable Canvas2D adapter for this cache (see `ReusableCtx2D`), built
+   * lazily on the UI thread by the first `createCanvas2D` call and retargeted
+   * — never rebuilt — on every subsequent one.
+   *
+   * CRITICAL: this lives on the cache, not at module scope, and must stay
+   * there. Recordings nest: `engine/gridLayer.ts` opens its own
+   * `PictureRecorder` *during* the main frame's recording, and it already
+   * passes a separate `SkiaCache` (`EngineState.gridLayerCache`) precisely so
+   * the pooled path/paints can't alias between the two live recordings. One
+   * ctx per cache inherits that isolation exactly: the nested recording gets
+   * its own ctx with its own `cv`, path, save-stack and style state, so it
+   * cannot scribble into the outer one. A single module-global ctx would
+   * retarget the outer recording's canvas out from under it mid-frame.
+   */
+  ctx: ReusableCtx2D | null;
   colors: Record<string, SkColor>;
   colorCount: number;
   gradients: Record<string, SkShader>;
@@ -245,6 +293,7 @@ export function createSkiaCache(): SkiaCache {
   'worklet';
   return {
     pool: null,
+    ctx: null,
     colors: {},
     colorCount: 0,
     gradients: {},
@@ -467,6 +516,22 @@ function baselineDy(
   return -m.ascent; // 'top'
 }
 
+/**
+ * Returns the Canvas2D adapter for `cache`, pointed at `canvas`.
+ *
+ * Despite the name this allocates nothing after the first call per cache: the
+ * ctx (and the path/paint pool it draws through) is stored on the cache and
+ * `retarget`-ed for each new recording, because it used to cost ~31
+ * allocations 60 times a second in a library that pools paints, paths and
+ * rects specifically to avoid that. The name is kept because every call site
+ * reads as "make me a ctx for this recording", which is still exactly what it
+ * does. Two rules follow from the reuse, both enforced by construction:
+ *  - the returned ctx is valid only until the next `createCanvas2D(_, _,
+ *    cache)` with the SAME cache; don't hold one across recordings.
+ *  - concurrently-live recordings (the nested grid-layer recorder inside the
+ *    main frame's) must pass DIFFERENT caches — as they already must for the
+ *    pooled path/paints. See `SkiaCache.ctx`.
+ */
 export function createCanvas2D(
   canvas: SkCanvas,
   fonts: LivelineFonts,
@@ -552,10 +617,36 @@ export function createCanvas2D(
     gradient: ownGradient,
     rect: ownRect,
   } = cache.pool;
-  ownPath.rewind(); // discard last frame's verbs
+
+  // Reuse this cache's adapter if it already has one — see SkiaCache.ctx for
+  // why it hangs off the cache (nested recordings) and `retarget` below for
+  // the per-recording state it clears.
+  const existing = cache.ctx;
+  if (existing !== null) {
+    existing.retarget(canvas, fonts);
+    return existing;
+  }
+
+  // ---- per-recording state (everything `retarget` must reset) ----
+  // 1. the recording canvas itself — every method below reads this mutable
+  //    binding rather than capturing the frame's canvas as a const, which is
+  //    the whole reason this object is reusable at all.
+  let cv = canvas;
+  // 2. the current path: normally the pooled path, but beginPathFrom() can
+  //    adopt a caller-owned one, which must not survive into the next
+  //    recording.
   let path = ownPath;
-  let lineDash: number[] = [];
+  // 3. the dash pattern set by setLineDash().
+  let lineDash: number[] = NO_DASH;
+  // 4. the save()/restore() snapshot stack. Balanced call sites leave it
+  //    empty, but an unbalanced one would otherwise leak a snapshot (and its
+  //    styles) into the next recording via a stray restore().
   const stack: StyleSnapshot[] = [];
+  // 5. the thirteen public style properties + `fonts`, reset on the ctx
+  //    object itself in retarget().
+  // (`cache` and the pooled path/paints/gradient/rect are per-cache, not
+  //  per-recording: the ctx and the pool it draws through always belong to
+  //  the same cache, so they never need reassigning.)
 
   // Applies a fill/stroke style + globalAlpha to a paint. For color strings
   // the string's own alpha is multiplied by globalAlpha; for gradients the
@@ -615,7 +706,7 @@ export function createCanvas2D(
         ? StrokeJoin.Bevel
         : StrokeJoin.Miter;
 
-  const ctx: Ctx2D = {
+  const ctx: ReusableCtx2D = {
     fillStyle: '#000000',
     strokeStyle: '#000000',
     lineWidth: 1,
@@ -631,6 +722,40 @@ export function createCanvas2D(
     shadowOffsetY: 0,
     fonts,
 
+    // Points this adapter at a new recording canvas and resets EVERY piece
+    // of per-recording state, so a reused ctx is indistinguishable from the
+    // freshly-built one this used to be. The enumeration, in order:
+    //   canvas       -> the new one (all methods read `cv`)
+    //   fonts        -> the new set (methods read `this.fonts`)
+    //   pooled path  -> rewound; discards the last recording's verbs
+    //   path         -> back to the pooled path (drops any adopted one)
+    //   lineDash     -> NO_DASH
+    //   stack        -> emptied
+    //   13 styles    -> the same defaults the object literal above declares
+    // Missing any one of these leaks state across recordings — a stuck dash
+    // pattern, a stale gradient, or a wrong alpha in an unrelated layer.
+    retarget(nextCanvas, nextFonts) {
+      cv = nextCanvas;
+      ownPath.rewind();
+      path = ownPath;
+      lineDash = NO_DASH;
+      stack.length = 0;
+      this.fonts = nextFonts;
+      this.fillStyle = '#000000';
+      this.strokeStyle = '#000000';
+      this.lineWidth = 1;
+      this.globalAlpha = 1;
+      this.lineCap = 'butt';
+      this.lineJoin = 'miter';
+      this.font = nextFonts.label;
+      this.textAlign = 'left';
+      this.textBaseline = 'alphabetic';
+      this.globalCompositeOperation = 'source-over';
+      this.shadowColor = 'rgba(0,0,0,0)';
+      this.shadowBlur = 0;
+      this.shadowOffsetY = 0;
+    },
+
     save() {
       stack.push({
         fillStyle: this.fillStyle,
@@ -654,7 +779,7 @@ export function createCanvas2D(
         // place, which no caller in this codebase does.
         lineDash,
       });
-      canvas.save();
+      cv.save();
     },
 
     restore() {
@@ -675,7 +800,7 @@ export function createCanvas2D(
         this.shadowOffsetY = s.shadowOffsetY;
         lineDash = s.lineDash;
       }
-      canvas.restore();
+      cv.restore();
     },
 
     beginPath() {
@@ -766,12 +891,12 @@ export function createCanvas2D(
         );
         // Draw the same path through a translated canvas instead of
         // allocating an offset copy per shadowed fill.
-        canvas.save();
-        canvas.translate(0, this.shadowOffsetY);
-        canvas.drawPath(path, sp);
-        canvas.restore();
+        cv.save();
+        cv.translate(0, this.shadowOffsetY);
+        cv.drawPath(path, sp);
+        cv.restore();
       }
-      canvas.drawPath(path, paint);
+      cv.drawPath(path, paint);
     },
 
     stroke() {
@@ -791,7 +916,7 @@ export function createCanvas2D(
       paint.setPathEffect(
         lineDash.length > 0 ? cachedDash(cache, lineDash) : null
       );
-      canvas.drawPath(path, paint);
+      cv.drawPath(path, paint);
     },
 
     // Every call site clips to an axis-aligned rect built immediately before
@@ -805,7 +930,7 @@ export function createCanvas2D(
     // antialias, so there's no visual cost to the non-AA path.
     clipRect(x, y, w, h) {
       ownRect.setXYWH(x, y, w, h);
-      canvas.clipRect(ownRect, ClipOp.Intersect, false);
+      cv.clipRect(ownRect, ClipOp.Intersect, false);
     },
 
     fillRect(x, y, w, h) {
@@ -817,7 +942,7 @@ export function createCanvas2D(
           : BlendMode.SrcOver
       );
       ownRect.setXYWH(x, y, w, h);
-      canvas.drawRect(ownRect, paint);
+      cv.drawRect(ownRect, paint);
     },
 
     fillText(text, x, y) {
@@ -828,10 +953,10 @@ export function createCanvas2D(
       // this paint is shared with fill()/fillRect() it must not inherit
       // DstOut from a prior destination-out fill.
       paint.setBlendMode(BlendMode.SrcOver);
-      canvas.drawText(
+      cv.drawText(
         text,
-        x + alignDx(cache, fonts, this.font, text, this.textAlign),
-        y + baselineDy(cache, fonts, this.font, this.textBaseline),
+        x + alignDx(cache, this.fonts, this.font, text, this.textAlign),
+        y + baselineDy(cache, this.fonts, this.font, this.textBaseline),
         paint,
         this.font
       );
@@ -849,17 +974,17 @@ export function createCanvas2D(
       // strokeText never dashes; must not inherit a dash from stroke().
       paint.setPathEffect(null);
       paint.setBlendMode(BlendMode.SrcOver);
-      canvas.drawText(
+      cv.drawText(
         text,
-        x + alignDx(cache, fonts, this.font, text, this.textAlign),
-        y + baselineDy(cache, fonts, this.font, this.textBaseline),
+        x + alignDx(cache, this.fonts, this.font, text, this.textAlign),
+        y + baselineDy(cache, this.fonts, this.font, this.textBaseline),
         paint,
         this.font
       );
     },
 
     measureText(text) {
-      return { width: cachedTextWidth(cache, fonts, this.font, text) };
+      return { width: cachedTextWidth(cache, this.fonts, this.font, text) };
     },
 
     // No defensive copy: `segments` used to be sliced here because callers
@@ -904,13 +1029,20 @@ export function createCanvas2D(
     },
 
     translate(dx, dy) {
-      canvas.translate(dx, dy);
+      cv.translate(dx, dy);
     },
 
     drawPicture(picture) {
-      canvas.drawPicture(picture);
+      cv.drawPicture(picture);
     },
   };
 
+  // Run the same reset the reuse path runs, so the first recording is
+  // byte-for-byte identical to every later one (and so the pooled path is
+  // rewound before the first use). The literal's initial values above exist
+  // only to satisfy the type — retarget() is the single source of truth for
+  // the defaults.
+  ctx.retarget(canvas, fonts);
+  cache.ctx = ctx;
   return ctx;
 }
diff --git a/src/draw/timeAxis.ts b/src/draw/timeAxis.ts
index d1fb156..af889a7 100644
--- a/src/draw/timeAxis.ts
+++ b/src/draw/timeAxis.ts
@@ -248,20 +248,28 @@ export function drawTimeAxis(
     drawn.push(label);
   }
 
+  // No save()/restore() per label. Each pair cost a 14-field StyleSnapshot
+  // allocation plus a canvas.save()/restore() JSI round-trip that recorded a
+  // real save/restore layer into the picture — ~500 objects and ~1,000 JSI
+  // calls a second at 6-10 labels/frame — to protect exactly four properties.
+  // globalAlpha is the only one that actually needs restoring afterwards;
+  // strokeStyle/lineWidth are loop-invariant (hoisted here, and identical to
+  // what the axis line above already set), and fillStyle is reassigned
+  // unconditionally by every iteration and by every subsequent draw call in
+  // the frame. Nothing in the body touches the transform or clip, which is
+  // the only other state canvas.save() was protecting.
+  ctx.strokeStyle = palette.gridLine;
+  ctx.lineWidth = 1;
+  ctx.fillStyle = palette.timeLabel;
   for (const label of drawn) {
-    ctx.save();
     ctx.globalAlpha = baseAlpha * label.alpha;
 
-    ctx.strokeStyle = palette.gridLine;
-    ctx.lineWidth = 1;
     ctx.beginPath();
     ctx.moveTo(label.x, lineY);
     ctx.lineTo(label.x, lineY + tickLen);
     ctx.stroke();
 
-    ctx.fillStyle = palette.timeLabel;
     ctx.fillText(label.text, label.x, lineY + tickLen + 14);
-
-    ctx.restore();
   }
+  ctx.globalAlpha = baseAlpha;
 }

From fadd61d33b6a2a51c87f21efebe301429d106643 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Sat, 1 Aug 2026 14:35:56 -0400
Subject: [PATCH 28/37] docs: conformance-check the declarative spec against
 the implementation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Read the spec back and verified it claim by claim against 0350072. All eleven
claims match — the four-node tree with no conditionals, prefix-stroke-only
scroll layer, the fill deliberately unsplit and still built whole, the binary
alpha gate via scrollLayerUsable, dx never accumulated (no `dx +=` anywhere in
src/), no double-draw, no text in the scroll layer, and all three addendum
claims including the 4-dimension key.

The one divergence was omission rather than contradiction: 33c23cb's
high-refresh scroll transform — recording paced at ~60fps while the
<Group transform> advances every vsync, with extrapolation and its three
guards — shipped with no design record at all, despite being the most
consequential runtime behaviour on the branch. Written up now, including the
unverified 120Hz-prefix-vs-60Hz-tail shear, which needs ProMotion hardware the
simulator cannot provide.

Status corrected from "implementation dispatched" to implemented.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../2026-07-31-declarative-shell-design.md    | 66 ++++++++++++++++++-
 1 file changed, 65 insertions(+), 1 deletion(-)

diff --git a/docs/superpowers/specs/2026-07-31-declarative-shell-design.md b/docs/superpowers/specs/2026-07-31-declarative-shell-design.md
index 852c139..94c973c 100644
--- a/docs/superpowers/specs/2026-07-31-declarative-shell-design.md
+++ b/docs/superpowers/specs/2026-07-31-declarative-shell-design.md
@@ -1,7 +1,8 @@
 # Declarative render shell (react-native-graph-shaped)
 
 **Date:** 2026-07-31
-**Status:** Design approved, implementation dispatched
+**Status:** Implemented and verified against this document 2026-08-01
+(see "Conformance check" at the end)
 **Branch:** `perf/declarative-shell` (off `e2c56d8`)
 
 ## Goal
@@ -187,3 +188,66 @@ Also added, and not anticipated here: `MIN_FRAME_INTERVAL_MS` and
 documented in `engine/constants.ts` and asserted in `engine/__tests__/
 constants.test.ts`. Tuning either alone can silently disable high-refresh
 scrolling in a way only 120Hz hardware would reveal.
+
+## Addendum 2 — the high-refresh transform, added after this doc was written
+
+`33c23cb` added behaviour this document does not describe, and it is arguably
+the most consequential runtime change on the branch. Recorded here so the spec
+is not silently incomplete.
+
+**Picture recording stays paced at ~60fps; the scroll transform advances on
+every vsync** — 120fps on a ProMotion display. Translating an already-recorded
+picture is nearly free, so the layer moves at the display's refresh rate while
+recording cost is unchanged. Without this the layer would judder in lockstep
+with the paced recording, and the split would have bought a draw call rather
+than smoother motion.
+
+On a vsync the pacing gate skips there is no `layout` — it is computed inside
+`engineStep` — so `dx` cannot be recomputed and is linearly extrapolated from
+the last two *recorded* frames (`engine/scrollExtrapolate.ts`, Skia-free so
+jest can reach it). Extrapolating observed motion rather than recomputing from
+`windowSecs`/`chartW` keeps no second copy of the engine's time-advance rules,
+so pause, window transitions and time-debt catch-up need no special cases.
+Every recorded frame overwrites with the exact value, so error cannot
+accumulate past one vsync.
+
+Three guards, all load-bearing:
+- Only when a layer is actually compositing (`EngineState.scrollActive`).
+- Only within `MAX_SCROLL_EXTRAPOLATION_MS` of the last recorded frame — a
+  quiescence resume or a JS stall leaves the transform untouched rather than
+  flinging it.
+- **`layerChanged`** — no rate is observable across a frame where the layer's
+  identity moved. `dx` is an offset *of a particular recorded picture*, so two
+  frames 16ms apart can report `-35` then `0` with the line perfectly
+  continuous, because the prefix was rebuilt in between. Differencing those
+  describes a jump that never happened; unguarded, the next paced-out vsync
+  shoves the layer ~35px sideways and the following frame snaps it back. The
+  gap bound cannot catch this — a rebuild happens on an ordinary 16ms frame.
+
+**Known and unverified:** the prefix now moves at 120Hz while the tail is
+re-recorded at 60Hz, so on skipped vsyncs they shear by one frame of scroll —
+`chartW / (windowSecs * refreshHz)`, about 0.25px on a 10s window and 0.08px on
+30s. Sub-pixel, but a shimmer at the join rather than a clean offset. The iOS
+simulator renders at 60Hz and cannot show it either way; this needs real
+ProMotion hardware.
+
+## Conformance check — 2026-08-01
+
+Verified against the implementation at `0350072`, claim by claim:
+
+| Claim | Status |
+|---|---|
+| Four-node tree, no conditionals | matches |
+| `scrollPicture` = prefix stroke only | matches |
+| `screenPicture` = everything else | matches |
+| Fill deliberately not split, still built whole | matches |
+| Alpha gate, binary, via `scrollLayerUsable` | matches |
+| `dx` never accumulated | matches (no `dx +=` anywhere in src/) |
+| No double-draw — split selects tail, not both | matches |
+| Nothing text-bearing in the scroll layer | matches |
+| Addendum 1: `scrollLayerDx` removed | matches |
+| Addendum 1: clip API removed | matches |
+| Addendum 1: key is 4 dimensions | matches (`buildRev`, `padLeft`, `lineWidth`, `line`) |
+
+The one divergence was omission, not contradiction: the high-refresh transform
+above shipped without a design record. Now written down.

From 1d5fd279e772245baaaf4ae5a012bea30a596580 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Sat, 1 Aug 2026 15:03:26 -0400
Subject: [PATCH 29/37] docs(android): record the wrong-Metro trap
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A red screen naming src/engine/state.ts and a for...of helper — both edited
that day — turned out to be a stale Metro on host 8082 whose module map was
corrupted, while the healthy one served iOS on 8083. Same repo, one platform
broken, and the error pointed straight at innocent code.

Also records that adb reverse does NOT apply here: the app connects to
10.0.2.2, the emulator's NAT route to the host, which bypasses reverse
entirely. Mapping the port did nothing and looked like it should have.

Adds the one-command diagnostic — curl each port for the exact bundle URL —
which removes the emulator, the app's cached error screen and your assumptions
in a single step. It took three wrong hypotheses to reach it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 docs/android-profiling.md | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/docs/android-profiling.md b/docs/android-profiling.md
index c14dd5d..cb235b3 100644
--- a/docs/android-profiling.md
+++ b/docs/android-profiling.md
@@ -73,6 +73,44 @@ GLES: Google (Apple), Android Emulator OpenGL ES Translator (Apple M2), OpenGL E
 Bad — if the string contains **SwiftShader**, or otherwise names no real GPU,
 you are software-rendering. Stop; do not record a number.
 
+### 1c. Make sure the app is talking to the Metro you think it is
+
+Cost roughly an hour on 2026-08-01. Symptoms looked exactly like a code bug: a
+red screen reading `Unable to resolve module
+@babel/runtime/helpers/createForOfIteratorHelperLoose from src/engine/state.ts`,
+naming a file edited that same day and a `for...of` construct added that same
+day. It was neither.
+
+Two things conspire here:
+
+- **`adb reverse` does not apply.** The app connects to `10.0.2.2:<port>`,
+  which is the emulator's NAT route to the *host*. `adb reverse` maps *device*
+  localhost to the host, so it is bypassed entirely. Mapping `tcp:8082` did
+  nothing.
+- **A stale Metro can hold the port.** There was a second, older Metro on host
+  8082 whose module map had been corrupted earlier (its own error was
+  `Unable to resolve module expo`). Android hits 8082; iOS was on 8083 and
+  perfectly healthy. Same repo, same files, one platform broken.
+
+The diagnostic that settles it in one command — ask each server directly,
+which removes the emulator, the app's cached error screen and your assumptions
+from the picture:
+
+```bash
+for port in 8081 8082 8083; do
+  printf "%s: " $port
+  curl -s -o /tmp/b.txt -w "%{http_code}\n" -m 240 \
+    "http://localhost:$port/.expo/.virtual-metro-entry.bundle?platform=android&dev=true&lazy=true&app=liveline.example"
+done
+```
+
+200 with ~10MB means that server is healthy. A 500 prints a JSON body naming
+the real failure. Do this BEFORE reading anything into a red screen. And check
+for strays: `lsof -nP -iTCP:8082 -sTCP:LISTEN`.
+
+Generalised: an error naming a file you just edited is not evidence that your
+edit caused it.
+
 ### 1b. Host load
 
 This is a **shared** machine and has been measured at load average 24. Relative

From 52b17a6021cb8709a8954f5328ec979d0227bf59 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Sat, 1 Aug 2026 17:27:11 -0400
Subject: [PATCH 30/37] chore: drop session design docs from the PR
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

docs/superpowers/specs/ held two working documents from the session that
produced this branch. Neither belongs in the repo:

- the scroll-layer architecture design describes the time-axis scroll layer,
  which was measured, priced and PARKED on another branch — it is not in this
  PR at all
- the declarative-shell design is a pre-implementation record whose content is
  now in the code comments and the CHANGELOG

docs/android-profiling.md stays: it is a real procedure with commands someone
will run again, including the two preconditions that have each silently
invalidated an Android measurement on this project before.

Removes the CHANGELOG's pointer to the deleted spec rather than leaving it
dangling.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md                                  |   4 +-
 ...-07-30-scroll-layer-architecture-design.md | 253 ------------------
 .../2026-07-31-declarative-shell-design.md    | 253 ------------------
 3 files changed, 2 insertions(+), 508 deletions(-)
 delete mode 100644 docs/superpowers/specs/2026-07-30-scroll-layer-architecture-design.md
 delete mode 100644 docs/superpowers/specs/2026-07-31-declarative-shell-design.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index aa19da0..771de6f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,8 +22,8 @@ All notable changes to this project will be documented in this file.
   `<Picture>`) instead of a single picture. The structure never changes after
   mount, so the Reanimated mapper that drives it stays entirely on the UI
   thread and the "keeps animating while the JS thread is blocked" guarantee
-  is preserved. This is an architecture change, not a performance one — see
-  `docs/superpowers/specs/2026-07-31-declarative-shell-design.md`.
+  is preserved. This is an architecture change, not a performance one; no
+  speedup is claimed for it.
 - **The single-series line's prefix stroke moved into that scroll layer** —
   the spline through all but the last data point is recorded once into its
   own `SkPicture` and composited at a horizontal offset via
diff --git a/docs/superpowers/specs/2026-07-30-scroll-layer-architecture-design.md b/docs/superpowers/specs/2026-07-30-scroll-layer-architecture-design.md
deleted file mode 100644
index 8c81b65..0000000
--- a/docs/superpowers/specs/2026-07-30-scroll-layer-architecture-design.md
+++ /dev/null
@@ -1,253 +0,0 @@
-# Scroll-layer rendering architecture
-
-**Date:** 2026-07-30
-**Status:** Design approved, not yet implemented
-**Branch:** `perf/scroll-layer-architecture`
-
-## Problem
-
-`useLivelineEngine`'s frame callback re-records a complete `SkPicture` every
-frame, forever. Most of what it records is content whose only per-frame change
-is a horizontal translation: the chart scrolls left because "now" advances.
-
-Two pieces of this are already solved at the *path* level:
-
-- `draw/lineCache.ts:189-206` caches the spline prefix and, on a hit,
-  re-assembles the drawable path as `addPath(prefix)` + `offset(dx, 0)` + two
-  tail cubics — no spline rebuild.
-- `draw/gridLayer.ts` caches the grid as a composited `SkPicture`, replayed
-  with a single `ctx.drawPicture` (`draw/index.ts:219`).
-
-One piece is not solved at all. `draw/timeAxis.ts` has no cache: every frame it
-recomputes the interval, calls `formatTime()` per label (the default formatter
-allocates a `Date` and three `padStart` results *per label per frame*), walks
-and lerps a label `Map`, measures, sorts, resolves overlaps, then issues
-`save/beginPath/moveTo/lineTo/stroke/fillText/restore` per label. Its own source
-comment records the gap: *"rebuilt unconditionally every frame (this function
-has no picture-cache bypass, unlike `drawGrid`)"* (`timeAxis.ts:19-22`).
-
-This design promotes the translate-instead-of-re-record technique from the path
-level to the picture level, and extends it to the time axis.
-
-### Scope note
-
-The incremental win for the line specifically is modest, because `lineCache`
-already captures most of it — roughly a dozen native calls per frame collapse to
-about two. This was raised before the design was accepted and the full
-architecture was chosen deliberately. The largest single win in this design is
-the time axis, which is currently uncached.
-
-## Architecture
-
-### The scroll layer abstraction
-
-A new module, `src/draw/scrollLayer.ts`, provides a generic **scroll layer
-slot**: a cached `SkPicture` recorded in build-time screen coordinates and
-composited each frame at a horizontal offset.
-
-```
-dx = layout.toX(slot.tRef) - slot.xRefAtBuild
-```
-
-This is the identical formula `lineCache.ts:189` uses — recomputed against the
-build-time reference every frame, never accumulated, so there is no drift.
-
-Composition:
-
-```ts
-ctx.save();
-ctx.clipRect(slot.clipX, slot.clipY, slot.clipW, slot.clipH);
-ctx.translate(dx, 0);
-ctx.drawPicture(slot.picture);
-ctx.restore();
-```
-
-Each slot carries its **own** clip region rather than sharing one: `lineScroll`
-and `candleScroll` clip to the plot area, while `axisScroll` clips to the axis
-strip below it (`h - pad.bottom` downward). A single shared chart-area clip
-would erase the axis entirely.
-
-The module is kept free of Skia imports (structural `Picture` type parameter,
-exactly like `gridLayer.ts`) so jest can exercise the key-comparison and `dx`
-logic without the native binding.
-
-### Three instances, not one merged picture
-
-Three independent slots: `lineScroll`, `candleScroll`, `axisScroll`.
-
-- **Z-order.** Today's order is `… → line+fill → timeAxis → dot → …`
-  (`draw/index.ts:253-289`). Merging line and axis into one picture would fuse
-  two non-adjacent z positions.
-- **Independent invalidation.** The line rebuilds on every tick; the axis
-  rebuilds only when a label enters or leaves (roughly every `interval`
-  seconds — about every 5s on a 30s window). Merging would drag the axis into
-  the line's rebuild rate and destroy its entire advantage.
-
-Cost: two extra `drawPicture` calls per frame.
-
-### Layer membership
-
-**Scroll layer** — rebuilt only when its key changes:
-
-| Slot | Contents | Rebuild trigger |
-|---|---|---|
-| `lineScroll` | spline prefix through decimated points `0..N-2`, stroke + fill | tick / range / geometry change |
-| `candleScroll` | closed candle bodies + wicks, batched by bull/bear | new or revised closed candle |
-| `axisScroll` | axis baseline, ticks, labels at full alpha | label enters/leaves, interval change |
-
-**Screen layer** — recorded live every frame, unchanged from today: line tail
-(last data point + live tip), live candle, live dot, pulse ring, momentum
-arrows, particles, shake, badge, value text, crosshair, edge fades. Plus the
-value-space layers that never scroll and are unaffected: grid (already its own
-cached picture), reference line, orderbook.
-
-The static/moving split for line and candles is not new: it is exactly the
-prefix/tail split `lineCache` and `candleCache` already encode.
-
-### Build ordering
-
-Scroll layers are rebuilt **before** `recorder.beginRecording()` opens the
-frame's picture, never during it. This avoids depending on
-`Skia.PictureRecorder()` being safely reentrant while another recording is open,
-and makes the ordering explicit and testable. `useLivelineEngine.ts` gains a
-"rebuild dirty scroll layers" step ahead of the existing recording block.
-
-## The constraint that shapes everything: pictures bake paint
-
-`ctx.drawPicture` ignores `globalAlpha` — documented at `canvas2d.ts:140-143`,
-because Skia's `drawPicture` takes no paint argument. Applying alpha at
-composite time would require `saveLayerAlpha`, which allocates an offscreen
-render target — precisely the Android cost this work exists to avoid.
-
-**Rule: a scroll layer is used only when its composite alpha is exactly 1.**
-Otherwise the engine falls back to today's live-drawing path.
-
-This is an existing pattern, not a new one: `draw/index.ts:218` already gates the
-grid picture on `reveal >= 1` for the same reason. Practically it means the
-reveal morph, the loading/empty crossfade, and scrub dimming all bypass scroll
-layers. Those are transient; the steady state is what is being optimized.
-
-A second consequence: **palette becomes part of every scroll-layer key**, unlike
-the path caches. A picture bakes color, stroke width, and gradient stops that a
-path did not.
-
-## Time axis redesign
-
-Labels and ticks bake at alpha 1. The per-label 50px `edgeAlpha` fade
-(`timeAxis.ts:65-72`) is replaced by a gradient `destination-out` erase over the
-axis strip at both edges, applied in the screen pass after compositing — the same
-technique `drawEdgeFade` already uses for the chart body:
-
-```ts
-ctx.globalCompositeOperation = 'destination-out';
-ctx.fillStyle = <linear gradient, 50px>;
-ctx.fillRect(chartLeft, axisTop, 50, axisH);      // left
-ctx.fillRect(chartRight - 50, axisTop, 50, axisH); // right
-```
-
-Per-label alpha state disappears. Label visibility becomes a pure function of
-position, which also replaces the alpha-based overlap tiebreak
-(`timeAxis.ts:184-198`) with a positional one.
-
-**Accepted behavior change:** during a window transition, label set swaps become
-hard rather than an alpha dissolve. This was chosen explicitly over a
-pixel-identical hybrid design.
-
-`timeAxis.ts` imports `Ctx2D` as a type only, so it is jest-testable with a fake
-context. The redesign is therefore developed test-first.
-
-## Invalidation keys
-
-Following the existing discipline: flat values only, compared field-by-field, no
-allocation per frame.
-
-**`lineScroll`** — reuses `lineCacheHits`'s existing key
-(`kDataRev`, `kDataSource`, `kLen`, `kFirstT`, `kLastT`, `kLastV`, `kMin`,
-`kMax`, `kWindow`, `kH`, `kPadTop`, `kPadBottom`, `kChartW`) plus new
-picture-only dimensions: line color, line width, fill enabled, fill gradient
-stops. Bypassed entirely while `reveal < 1` or scrub dimming is active.
-
-**`candleScroll`** — `candleCache`'s existing key plus `candlesRev`, bull/bear
-body and wick colors, and `candleWidth`.
-
-**`axisScroll`** — `interval`, a cheap visible-label-set identity (count + first
-key + last key), `tRef`, `formatTime` reference equality, `palette.gridLine`,
-`palette.timeLabel`, `pad`, `h`, `w`.
-
-## Risks
-
-**Cull rect (highest).** A picture records with a cull rect in its own
-coordinate space; content outside it may be dropped at record time. Compositing
-at `translate(dx, 0)` then shifts the result. Two mitigations, both applied:
-record each scroll layer with a cull rect expanded to cover the full
-pre-rebuild scroll range, and always `clipRect` to that slot's own region at
-composite time so translated content cannot bleed into the padding, the badge,
-or across the plot/axis boundary.
-
-**Text subpixel jitter.** Compositing at fractional `dx` re-rasterizes glyphs at
-a new subpixel position. Vector content stays crisp, but glyph hinting could
-produce ~1px jitter on axis labels while scrolling. Verify visually; if it
-appears, round `dx` to whole pixels for `axisScroll` only (labels sit at
-computed intervals, so a sub-pixel snap is invisible).
-
-**Alpha-1 gating reduces coverage.** Any chart spending significant time mid-
-reveal, mid-crossfade, or scrub-dimmed gets no benefit. Acceptable: those states
-are transient.
-
-**Blast radius.** Touches `engine/step.ts` (1,813 lines), `draw/index.ts`, and
-every affected draw module's coordinate assumptions. `PLAN_MAINT.md` item 4
-(positional-parameter soup) already blocked one smaller perf change in
-`drawLine`; the scroll-layer parameter is threaded as part of an options object
-rather than a 17th positional parameter.
-
-## Testing
-
-- New `src/draw/__tests__/scrollLayer.test.ts` — key comparison, `dx`
-  computation, rebuild triggering, alpha-1 gating. Fake picture recorders, same
-  pattern as `lineCache.test.ts`.
-- New time-axis tests — label-set selection and positional overlap resolution,
-  using a fake `Ctx2D`.
-- Extend `lineCache.test.ts` / `candleCache.test.ts` for the new palette key
-  dimensions.
-- Per stage: `typecheck`, `lint`, `test` from repo root via the vendored yarn
-  (`node .yarn/releases/yarn-4.11.0.cjs <script>`).
-- Per stage: visual verification on iOS simulator and Android emulator.
-
-## Staging
-
-Four landings, each its own commit so a regression is bisectable.
-
-| Stage | Content | Behavior change |
-|---|---|---|
-| 0 | `draw/scrollLayer.ts` + tests | None — nothing consumes it yet |
-| 1 | `lineScroll` wired into the line pipeline | None expected |
-| 2 | `candleScroll` wired into the candle pipeline | None expected |
-| 3 | `axisScroll` + time-axis redesign | Window-transition label swap becomes hard |
-
-Each stage gates on typecheck + lint + test, plus:
-
-- **iOS CPU A/B** using the established `run-and-profile` protocol: swap only
-  `src/`, 3 runs per arm over fixed 20s windows, drift-control re-measure. FPS
-  cannot show this win — frame pacing caps recording at ~60
-  (`MIN_FRAME_INTERVAL_MS`), so both arms read 60 regardless. Measure CPU time.
-- **Android emulator release build**, with two preconditions checked first,
-  both of which have previously produced false "still slow" signals:
-  `hw.gpu.enabled` in the AVD config, and host `uptime` before each arm.
-
-Emulator relative CPU deltas are meaningful for this work because it is a
-CPU-side change (fewer draw calls recorded per frame). They would *not* be
-meaningful for GPU-compositor-side questions such as `opaque`/TextureView.
-
-Rollback: every stage keeps the live-draw path intact as the alpha<1 fallback,
-so any stage reverts as a single commit.
-
-## Out of scope
-
-- **Declarative `<Group transform>` promotion.** Chosen as an explicit
-  follow-up: land the imperative split first, since the layer boundary is the
-  hard part, then evaluate promoting it.
-- **Multi-series scroll layers.** Multi-series already has per-series
-  `lineCache` slots and is excluded from quiescence. Extending scroll layers
-  per-series is mechanical but multiplies the surface; deferred.
-- **`opaque` / TextureView→SurfaceView.** Independent, GPU-compositor-side, and
-  requires physical Android hardware to evaluate honestly. Tracked separately.
diff --git a/docs/superpowers/specs/2026-07-31-declarative-shell-design.md b/docs/superpowers/specs/2026-07-31-declarative-shell-design.md
deleted file mode 100644
index 94c973c..0000000
--- a/docs/superpowers/specs/2026-07-31-declarative-shell-design.md
+++ /dev/null
@@ -1,253 +0,0 @@
-# Declarative render shell (react-native-graph-shaped)
-
-**Date:** 2026-07-31
-**Status:** Implemented and verified against this document 2026-08-01
-(see "Conformance check" at the end)
-**Branch:** `perf/declarative-shell` (off `e2c56d8`)
-
-## Goal
-
-Match react-native-graph's rendering *shape* — a declarative Skia tree with
-continuous motion expressed as a `<Group transform>` driven by a shared value —
-without losing either of the two things that make Liveline what it is: it keeps
-animating while the JS thread is blocked, and its current visual output.
-
-**This is an architecture goal, not a performance goal.** See "Honest cost"
-below. The CPU case was measured and is weak; the user chose fidelity anyway.
-
-## Target tree
-
-```tsx
-<Canvas>
-  <Group transform={scrollTransform}>   {/* SharedValue<Transforms3d> */}
-    <Picture picture={scrollPicture} />
-  </Group>
-  <Picture picture={screenPicture} />
-</Canvas>
-```
-
-Four nodes, **fixed structure, never reconciled after mount**.
-
-## Why this preserves the blocked-JS-thread guarantee
-
-Verified in `example/node_modules/@shopify/react-native-skia/src/sksg/Container.native.ts:38-62`.
-`NativeReanimatedContainer.redraw()` compiles the declarative tree once on the
-JS thread, collects every shared value used as a prop, and then installs a
-Reanimated mapper:
-
-```js
-this.mapperId = Rea.startMapper(() => {
-  "worklet";
-  sharedRecorder.applyUpdates(sharedValues);
-  nativeDrawOnscreen(nativeId, sharedRecorder, picture);
-}, sharedValues);
-```
-
-So shared-value prop updates run entirely on the UI thread. `redraw()` — the
-only JS-thread step — runs on *structural* change. Our tree has no structural
-change after mount, so nothing touches JS per frame.
-
-`AnimatedProp<T> = T | { value: T }` (`renderer/processors/Animations/Animations.d.ts`)
-confirms every Skia prop accepts a shared value, `<Group transform>` included.
-
-## The ceiling on this approach
-
-Variable-count content **cannot** go in the declarative tree without forfeiting
-the guarantee: axis labels, candles, particles and orderbook bars change their
-element count as data and scroll advance, and each change would require JS
-reconciliation. During a JS block their counts would freeze, where today the
-worklet still generates them.
-
-That content therefore stays inside `<Picture>` nodes, which is why this design
-is "react-native-graph-shaped" rather than a full port. Their model never faces
-this because it has no continuous motion at all.
-
-## What goes in the scroll layer
-
-**`scrollPicture`: the line's prefix _stroke_ only** — the spline through
-decimated points `0..N-2`, rebuilt only on a `lineCache` key miss.
-
-**`screenPicture`: everything else**, including the *entire* fill polygon and
-the tail stroke, drawn live every frame exactly as today.
-
-### Why the fill is deliberately NOT split
-
-The fill is one closed polygon: baseline → up the left edge → along the spline
-→ down to baseline → close (`lineCache.ts:211-222`), and it is a semi-transparent
-gradient (`palette.fillTop`/`fillBottom`). Splitting it at `cutX` gives three bad
-options and no good one:
-
-- **Abut two pieces.** Antialiased coverage on a shared edge sums to ~0.75, not
-  1 — a visible hairline down the fill.
-- **Overlap two pieces.** Semi-transparent overdraw double-darkens a 1px column.
-- **Non-AA clip split.** Tiles exactly only if both sides round the boundary
-  identically; at fractional `dx` a 1px gap or double-draw is possible. And
-  rounding `dx` to whole pixels is not available to us: at a 30s window over
-  ~300px the line moves ~0.17px/frame, so integer quantization would judder.
-
-Keeping the fill whole sidesteps all of it. The **stroke** has no such problem:
-it is opaque, and `drawSplineTail` already continues from `cutX` with the
-prefix's end tangent (`lineCache.ts:197-206`), so the join is C1-continuous and
-any overdraw is identical pixels.
-
-## Honest cost
-
-Because the fill still needs the full path every frame, `lineCache` keeps
-running and this stage removes roughly **one draw call per frame**. It buys the
-architecture, not speed.
-
-For context, measured on this repo 2026-07-30/31: the whole time axis is 4.2% of
-a core (valid ceiling A/B, drift control agreeing to 0.1 points), and the
-timeAxis memoization — a 35% improvement to that function's JS — was
-undetectable on device. A one-draw-call change will not be measurable. Do not
-claim otherwise.
-
-## Alpha gate
-
-`ctx.drawPicture` ignores `globalAlpha` (`canvas2d.ts:139-143`). Whenever the
-line's composite alpha is < 1 — reveal morph, loading/empty crossfade, scrub
-dimming — the engine must fall back to recording **everything** into
-`screenPicture` and leave `scrollPicture` empty, so nothing is composited at the
-wrong opacity. Same gate `draw/index.ts:218` already applies to the grid picture.
-
-## Work split
-
-Two workstreams, deliberately chosen for file disjointness:
-
-| Stream | Files | Deliverable |
-|---|---|---|
-| A — stroke split | `src/draw/lineCache.ts`, `src/draw/line.ts` | Expose the prefix stroke as a separately-drawable path; tail stroke unchanged; fill untouched |
-| B — declarative shell | `src/Liveline.tsx`, `src/useLivelineEngine.ts` | Two-picture + `<Group transform>` tree; engine exposes `scrollPicture` / `screenPicture` / `scrollTransform`. Ships as a structural no-op: `scrollPicture` starts empty. |
-
-Integration (wiring A's prefix stroke into B's `scrollPicture`, plus the alpha
-gate) is a third, sequential step once both land.
-
-### Reuse `src/draw/scrollLayer.ts` — do not re-derive
-
-**Added 2026-07-31 after stream A flagged the omission.** This branch already
-carries `src/draw/scrollLayer.ts` (commit `3db71f1`, "scroll-layer slot
-foundation"), which provides exactly what integration needs and which the
-original version of this doc failed to mention or place in either workstream's
-file list:
-
-- `ScrollLayerSlot<Picture>` — picture + build-time `tRef`/`xRefAtBuild` +
-  per-slot clip region + a push-built invalidation key.
-- `scrollLayerDx(slot, layout)` — the dx formula, identical to `lineCache.ts`'s
-  `lineScrollDx`. A slot wrapping the line's prefix picture takes its
-  `tRef`/`xRefAtBuild` straight from the line cache slot, so the two agree by
-  construction.
-- `scrollLayerUsable(slot, alpha)` — the alpha≥1 gate described below, already
-  written.
-
-Integration must consume these rather than re-implement dx or alpha handling.
-
-### Naming collision to avoid
-
-`scrollLayerDx(slot, layout)` is a **pure function returning a number**.
-`scrollTransform` is a **shared value holding `[{ translateX }]`** that
-`<Group transform>` reads. Earlier wording in this doc blurred the two; they are
-different things, and the frame callback converts the former into the latter.
-
-## Risks
-
-- **Double-draw.** Once integrated, `screenPicture` must not also draw the
-  prefix stroke. A visual diff at identical data is the check.
-- **Transform units.** `scrollTransform` is `[{ translateX: dx }]` where `dx`
-  is `scrollLayerDx`'s value — screen pixels, recomputed against the build-time
-  reference every frame, never accumulated (`lineCache.ts:166-175`).
-- **Z-order.** Two `<Picture>` siblings must composite in source order. Verify
-  on device, not by assumption.
-- **Text subpixel.** Nothing text-bearing is in the scroll layer in this design,
-  so the jitter risk flagged earlier does not apply yet. It returns if the axis
-  is ever moved in.
-
----
-
-## Addendum 2026-08-01 — what the cleanup pass changed
-
-This document is a dated record of what was decided *before* implementation.
-Two API names it references no longer exist; the design itself is unchanged.
-
-- **`scrollLayerDx` is gone.** It and `lineCache.ts`'s `lineScrollDx` had
-  identical bodies and both doc comments claimed to be the single place the
-  `toX(tRef) - xRefAtBuild` subtraction was written. `lineScrollDx` survives;
-  `ScrollLayerSlot` no longer carries `tRef`/`xRefAtBuild` at all, because they
-  were copied from the line cache slot and could therefore go stale.
-- **`setScrollLayerClip` and the `clipX/clipY/clipW/clipH` fields are gone,**
-  along with the "each slot clips to its OWN region" invariant above. They
-  described an imperative `ctx.clipRect` + `ctx.translate` + `ctx.drawPicture`
-  composite. The implementation composites through `<Group transform>` and
-  bakes the clip into the recording instead, so none of it ever executed.
-- **The scroll layer's invalidation key is four dimensions, not sixteen.** A
-  `buildRev` counter on `LineCacheSlot` replaced the thirteen dimensions that
-  were being copied verbatim out of the line cache's own key — which would have
-  silently missed a fourteenth had one ever been added there.
-
-Also added, and not anticipated here: `MIN_FRAME_INTERVAL_MS` and
-`MAX_SCROLL_EXTRAPOLATION_MS` turn out to be coupled by two inequalities, now
-documented in `engine/constants.ts` and asserted in `engine/__tests__/
-constants.test.ts`. Tuning either alone can silently disable high-refresh
-scrolling in a way only 120Hz hardware would reveal.
-
-## Addendum 2 — the high-refresh transform, added after this doc was written
-
-`33c23cb` added behaviour this document does not describe, and it is arguably
-the most consequential runtime change on the branch. Recorded here so the spec
-is not silently incomplete.
-
-**Picture recording stays paced at ~60fps; the scroll transform advances on
-every vsync** — 120fps on a ProMotion display. Translating an already-recorded
-picture is nearly free, so the layer moves at the display's refresh rate while
-recording cost is unchanged. Without this the layer would judder in lockstep
-with the paced recording, and the split would have bought a draw call rather
-than smoother motion.
-
-On a vsync the pacing gate skips there is no `layout` — it is computed inside
-`engineStep` — so `dx` cannot be recomputed and is linearly extrapolated from
-the last two *recorded* frames (`engine/scrollExtrapolate.ts`, Skia-free so
-jest can reach it). Extrapolating observed motion rather than recomputing from
-`windowSecs`/`chartW` keeps no second copy of the engine's time-advance rules,
-so pause, window transitions and time-debt catch-up need no special cases.
-Every recorded frame overwrites with the exact value, so error cannot
-accumulate past one vsync.
-
-Three guards, all load-bearing:
-- Only when a layer is actually compositing (`EngineState.scrollActive`).
-- Only within `MAX_SCROLL_EXTRAPOLATION_MS` of the last recorded frame — a
-  quiescence resume or a JS stall leaves the transform untouched rather than
-  flinging it.
-- **`layerChanged`** — no rate is observable across a frame where the layer's
-  identity moved. `dx` is an offset *of a particular recorded picture*, so two
-  frames 16ms apart can report `-35` then `0` with the line perfectly
-  continuous, because the prefix was rebuilt in between. Differencing those
-  describes a jump that never happened; unguarded, the next paced-out vsync
-  shoves the layer ~35px sideways and the following frame snaps it back. The
-  gap bound cannot catch this — a rebuild happens on an ordinary 16ms frame.
-
-**Known and unverified:** the prefix now moves at 120Hz while the tail is
-re-recorded at 60Hz, so on skipped vsyncs they shear by one frame of scroll —
-`chartW / (windowSecs * refreshHz)`, about 0.25px on a 10s window and 0.08px on
-30s. Sub-pixel, but a shimmer at the join rather than a clean offset. The iOS
-simulator renders at 60Hz and cannot show it either way; this needs real
-ProMotion hardware.
-
-## Conformance check — 2026-08-01
-
-Verified against the implementation at `0350072`, claim by claim:
-
-| Claim | Status |
-|---|---|
-| Four-node tree, no conditionals | matches |
-| `scrollPicture` = prefix stroke only | matches |
-| `screenPicture` = everything else | matches |
-| Fill deliberately not split, still built whole | matches |
-| Alpha gate, binary, via `scrollLayerUsable` | matches |
-| `dx` never accumulated | matches (no `dx +=` anywhere in src/) |
-| No double-draw — split selects tail, not both | matches |
-| Nothing text-bearing in the scroll layer | matches |
-| Addendum 1: `scrollLayerDx` removed | matches |
-| Addendum 1: clip API removed | matches |
-| Addendum 1: key is 4 dimensions | matches (`buildRev`, `padLeft`, `lineWidth`, `line`) |
-
-The one divergence was omission, not contradiction: the high-refresh transform
-above shipped without a design record. Now written down.

From 1360975f65a66070967e6ef806dc9347f0ad69b4 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Sat, 1 Aug 2026 17:43:48 -0400
Subject: [PATCH 31/37] fix(engine/step): publish a blank readout on every
 early return
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

An independent validation pass found the `showValue` fix from c49bb03 was
INCOMPLETE, and that the blank-canvas fix in the same commit widened the same
hole.

Three early returns draw the empty/loading state and bail without publishing
`out.valueText`. Since `null` means "leave unchanged" to the caller, the
readout keeps showing whatever the PREVIOUS mode last wrote:

- the shared no-data return (all modes)
- multi-series with no visible series
- single-series `visible.length < 2` — added by c49bb03 itself

So a chart mounted with no data, or one that loses every point out of the
window, or a switch to a multi-series config whose data has not arrived yet,
still showed a stale price from another mode. That is exactly the bug c49bb03
claimed to close, surviving on the paths where no chart is drawn at all.

Fixed with one `publishBlankValue(out, cfg)` helper called at all three sites
rather than three copies — the reviewer's point was that this is one defect
class in three places. It writes '' (a real value that overwrites) rather than
null, and only when `cfg.showValue` is set, so charts without the readout
publish nothing and cost nothing.

Also closes a coverage gap the same review found: `slot.buildRev++` in
`updateLinePaths` had NO test. It is the sole invalidation signal for the
scroll-layer picture and the input to `observeScrollRate`'s `layerChanged`
guard, yet deleting it failed nothing — `lineScrollLayer.test.ts` bumps the
field by hand, so nothing asserted a real rebuild moves it.

Both fixes mutation-verified rather than assumed:
- removing the three `publishBlankValue` calls fails 2 of the new tests
- removing `slot.buildRev++` fails 3 of the new tests (previously 0)

Tests 359 -> 365.

Note for the record: the new lineCache tests passed jest while FAILING
typecheck (wrong `makeLayout` arity). Jest does not typecheck — green tests
are not a green gate. Same trap as the timeAxis test earlier on this branch.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/draw/__tests__/lineCache.test.ts | 71 ++++++++++++++++++++++++++++
 src/engine/__tests__/step.test.ts    | 44 +++++++++++++++++
 src/engine/step.ts                   | 25 ++++++++++
 3 files changed, 140 insertions(+)

diff --git a/src/draw/__tests__/lineCache.test.ts b/src/draw/__tests__/lineCache.test.ts
index 6ce364b..71bd997 100644
--- a/src/draw/__tests__/lineCache.test.ts
+++ b/src/draw/__tests__/lineCache.test.ts
@@ -891,3 +891,74 @@ describe('split stroke (prefix / tail)', () => {
 // decimateMinMax's own correctness (including the bucketSecs absolute-grid
 // path) is covered in math/__tests__/math.test.ts, next to its other tests —
 // this file only tests what's specific to the cache built on top of it.
+
+// ── buildRev ───────────────────────────────────────────────────────────────
+//
+// `slot.buildRev` is the sole invalidation signal the scroll layer keys on
+// (`writeLineScrollKey` pushes it as dimension 0) and the input to
+// `observeScrollRate`'s `layerChanged` guard. Deleting the `buildRev++` in
+// `updateLinePaths`' miss branch used to break BOTH of those and fail no test:
+// lineScrollLayer.test.ts bumps the field by hand, so nothing asserted that a
+// real rebuild moves it. These close that gap.
+
+describe('buildRev tracks actual prefix rebuilds', () => {
+  const NOW = 1000;
+  const N = 20;
+
+  it('increments on a rebuild and stays put on a cache hit', () => {
+    const hz = makeHarness();
+    const layout = makeLayout(NOW, 0, 100);
+    const data = makeData(N, NOW);
+
+    const start = hz.slot.buildRev;
+    update(hz, layout, data, data[N - 1]!.value, NOW);
+    const afterBuild = hz.slot.buildRev;
+    expect(afterBuild).toBeGreaterThan(start);
+
+    // Same inputs — a hit. The prefix is reused, so the revision must not move,
+    // or the scroll layer would re-record a picture it already has.
+    update(hz, layout, data, data[N - 1]!.value, NOW);
+    expect(hz.slot.buildRev).toBe(afterBuild);
+  });
+
+  it('increments again when new data forces another rebuild', () => {
+    const hz = makeHarness();
+    const layout = makeLayout(NOW, 0, 100);
+    const data = makeData(N, NOW);
+
+    update(hz, layout, data, data[N - 1]!.value, NOW);
+    const afterFirst = hz.slot.buildRev;
+
+    // A new point: different length and last-time, so the key misses.
+    const grown = [...data, { time: NOW + 1, value: data[N - 1]!.value + 1 }];
+    update(
+      hz,
+      layout,
+      grown,
+      grown[grown.length - 1]!.value,
+      NOW + 1,
+      false,
+      1
+    );
+
+    expect(hz.slot.buildRev).toBeGreaterThan(afterFirst);
+  });
+
+  it('moves strictly forward — never reused for a different prefix', () => {
+    // The scroll layer treats equal buildRev as "same picture". If the counter
+    // could ever repeat a value for different geometry, a stale picture would
+    // composite with no visual symptom until it scrolled.
+    const hz = makeHarness();
+    const layout = makeLayout(NOW, 0, 100);
+    const seen = new Set<number>();
+
+    for (let i = 0; i < 12; i++) {
+      const data = makeData(N + i, NOW + i);
+      update(hz, layout, data, data[data.length - 1]!.value, NOW + i, false, i);
+      seen.add(hz.slot.buildRev);
+    }
+
+    // Every rebuild produced a distinct revision.
+    expect(seen.size).toBe(12);
+  });
+});
diff --git a/src/engine/__tests__/step.test.ts b/src/engine/__tests__/step.test.ts
index b23ca62..19eecaf 100644
--- a/src/engine/__tests__/step.test.ts
+++ b/src/engine/__tests__/step.test.ts
@@ -220,6 +220,50 @@ describe('live value readout', () => {
     expect(out.valueText).toBe('');
   });
 
+  // The three early returns that draw the empty/loading state and bail used to
+  // skip the readout publish entirely, so `null` reached the caller and it kept
+  // showing whatever the PREVIOUS mode last wrote — the exact bug the candle and
+  // multi publishes above were added to fix, still live on the paths where no
+  // chart is drawn at all. Found by an independent review AFTER those two
+  // landed, which is why each of the three gets its own test here.
+
+  it('publishes a blank when single-series has no points in the window', () => {
+    const s = makeState();
+    const out = run(
+      s,
+      makeCfg({ showValue: true }),
+      // Points far in the past: real data, but nothing inside the window.
+      pointsEnding(1).map((p) => ({ ...p, time: p.time - 100000 })),
+      []
+    );
+    expect(out.valueText).toBe('');
+  });
+
+  it('publishes a blank when multi-series has no visible series', () => {
+    const s = makeState();
+    const out = run(
+      s,
+      makeCfg({
+        showValue: true,
+        isMultiSeries: true,
+        multiSeries: [{ id: 'a', value: 100, palette: PALETTE }],
+        multiRevs: { a: 1 },
+      }),
+      [],
+      [],
+      { a: [] }
+    );
+    expect(out.valueText).toBe('');
+  });
+
+  it('leaves the readout alone when the consumer never asked for it', () => {
+    // showValue false must publish NOTHING — null keeps the caller from
+    // touching a shared value it does not own, and costs nothing per frame.
+    const s = makeState();
+    const out = run(s, makeCfg({ showValue: false }), [], []);
+    expect(out.valueText).toBeNull();
+  });
+
   it('candle mode publishes its own value rather than leaving it stale', () => {
     const now = Date.now() / 1000;
     const candles: CandlePoint[] = [
diff --git a/src/engine/step.ts b/src/engine/step.ts
index 6f2d436..9ae87f1 100644
--- a/src/engine/step.ts
+++ b/src/engine/step.ts
@@ -154,6 +154,28 @@ function multiSeriesData(
  *
  * Candle mode is not yet ported; it renders the loading/empty fallback.
  */
+/**
+ * Publish a blank live-value readout before an early return.
+ *
+ * `StepOutput.valueText` is `null` by default and the caller treats `null` as
+ * "leave the shared value unchanged" — which is right for the modes that do
+ * not own the readout, but wrong for an early return that draws no chart at
+ * all. Without this, a chart that mounts with no data, loses every point out
+ * of the window, or switches to a multi-series config whose data has not
+ * arrived, keeps displaying whatever number the *previous* mode last wrote,
+ * forever.
+ *
+ * `''` (not `null`) is the point: it is a real value that overwrites the stale
+ * one. Only written when the consumer actually asked for the readout, so
+ * charts without `showValue` publish nothing and cost nothing.
+ */
+function publishBlankValue(out: StepOutput, cfg: EngineConfigStep): void {
+  'worklet';
+  if (!cfg.showValue) return;
+  out.valueText = '';
+  out.valueColor = '';
+}
+
 export function engineStep(
   ctx: Ctx2D,
   cfg: EngineConfigStep,
@@ -464,6 +486,7 @@ export function engineStep(
       );
     }
     drawEdgeFade(ctx, pad.left, h);
+    publishBlankValue(out, cfg);
     return out;
   }
 
@@ -1468,6 +1491,7 @@ export function engineStep(
         );
       }
       drawEdgeFade(ctx, pad.left, h);
+      publishBlankValue(out, cfg);
       return out;
     }
 
@@ -1772,6 +1796,7 @@ export function engineStep(
         );
       }
       drawEdgeFade(ctx, pad.left, h);
+      publishBlankValue(out, cfg);
       return out;
     }
 

From b52d96c1a385aa282ecfe2d06912675b54ea4dc3 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Sun, 2 Aug 2026 21:24:07 -0400
Subject: [PATCH 32/37] docs: fix README peer range; add EAS preview build
 config
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The README's peer table still said `react-native-gesture-handler: >=3.0.0`,
and the prose below it said the library "is not tested against gesture-handler
2.x anymore" — while package.json declares `>=2.30.0` and the CHANGELOG
describes widening it precisely so Expo SDK 55 (which pins ~2.30.0) does not
hit a peer conflict.

So the published README actively contradicted the fix it shipped alongside: an
SDK 55 consumer reading it would conclude their gesture-handler version was
unsupported and either skip the library or needlessly bump gesture-handler,
defeating the whole point of 54ed706. Found by an independent API/docs review.

Table corrected and the prose rewritten to state that both majors are
supported, why the 2.30 floor exists, and that compatibility was verified by
installing 2.30.0 and running the typecheck rather than by inspection. All four
documented peer ranges now match package.json exactly.

Also adds example/eas.json with a `preview` profile (Android APK, iOS device
build) for producing an installable artifact.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 README.md        | 17 +++++++++++------
 example/eas.json | 30 ++++++++++++++++++++++++++++++
 2 files changed, 41 insertions(+), 6 deletions(-)
 create mode 100644 example/eas.json

diff --git a/README.md b/README.md
index 0b879b3..aabcc5e 100644
--- a/README.md
+++ b/README.md
@@ -34,16 +34,21 @@ npm install @shopify/react-native-skia react-native-reanimated react-native-work
 | `@shopify/react-native-skia` | `>=2.0.0` |
 | `react-native-reanimated` | `>=4.0.0` |
 | `react-native-worklets` | `>=0.3.0` |
-| `react-native-gesture-handler` | `>=3.0.0` |
+| `react-native-gesture-handler` | `>=2.30.0` |
 
 Reanimated 4 split its worklets runtime out into the separate
 `react-native-worklets` package (Reanimated itself declares this as its own
 peer dependency as of 4.0.0), so it's required alongside Reanimated here too.
-This library hasn't been tested against Reanimated 3.x. It's also not tested
-against gesture-handler 2.x anymore — this library still uses the classic
-`Gesture.Pan()` builder API (unchanged since v2), which gesture-handler 3.x
-keeps working but marks deprecated in favor of a new hook-based API; a
-migration to the new API is deferred to a future release.
+This library hasn't been tested against Reanimated 3.x.
+
+**gesture-handler 2.30 and 3.x are both supported.** The scrub gesture uses
+the classic `Gesture.Pan()` builder API, which exists unchanged in both majors
+— 3.x keeps it working but marks it deprecated in favour of a new hook-based
+API, and migrating is deferred to a future release. The `>=2.30.0` floor
+matters for Expo: SDK 55 pins `~2.30.0`, so a narrower range would put every
+SDK 55 app into a peer conflict and an `expo-doctor` failure. Compatibility is
+verified by installing 2.30.0 and running the typecheck against it, not by
+inspection.
 
 ### Reanimated Babel plugin
 
diff --git a/example/eas.json b/example/eas.json
new file mode 100644
index 0000000..0a1f2b0
--- /dev/null
+++ b/example/eas.json
@@ -0,0 +1,30 @@
+{
+  "cli": {
+    "version": ">= 21.0.0",
+    "appVersionSource": "remote"
+  },
+  "build": {
+    "preview": {
+      "distribution": "internal",
+      "channel": "preview",
+      "android": {
+        "buildType": "apk"
+      },
+      "ios": {
+        "simulator": false
+      }
+    },
+    "preview-sim": {
+      "distribution": "internal",
+      "ios": {
+        "simulator": true
+      }
+    },
+    "production": {
+      "autoIncrement": true
+    }
+  },
+  "submit": {
+    "production": {}
+  }
+}

From b9e96d44f996e9526775e0b3bfaec5e23465526c Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Sun, 2 Aug 2026 23:30:58 -0400
Subject: [PATCH 33/37] feat(a11y): screen-reader and test-automation support
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The chart is a Skia surface, so VoiceOver and TalkBack previously encountered
an unlabelled blank region — `git grep accessibilit src/` returned zero hits.
For a library whose purpose is displaying a live number, that was the largest
gap between this and something a team would adopt.

Two public props: `accessibilityLabel` (default 'Live chart') and `testID`.
The built-in controls DERIVE their test ids from testID, so Detox/Maestro can
drive the window pills, mode toggle and series chips without further props.

The design constraint, and why the obvious approach was wrong: the live value
lives on the UI thread as a shared value updated 60-120x/sec, while
accessibility props are JS-thread React props. Bridging per frame would
destroy the architecture the whole library exists for.

The implementation does not bridge at all. `engine.valueText` is the LERPED
value — the engine eases toward each incoming number over several frames — so
announcing it would speak an interpolated figure that never existed. The
authoritative number is already a JS-thread prop. So there is no runOnJS, no
extra mapper, and ZERO change to useLivelineEngine.ts or step.ts.

Cost with no screen reader running: one promise and one screenReaderChanged
subscription at mount, then nothing — no interval, no state, no per-frame work.
With a reader active: a 1Hz sample of a ref, committing only when the FORMATTED
string changed (a live feed jitters below display precision constantly;
comparing raw numbers would announce once a second forever). Ticks flow into a
ref, never into state, so the memo boundary added in 6aa05c3 still holds.

Also fixed, and not asked for: the icon-only mode toggle was two entirely
unnamed buttons; compact series chips are bare coloured dots with no text; the
faded-but-mounted series bar was offering a reader controls nobody can see; and
the showValue overlay is a TextInput updating at frame rate that a reader would
have announced continuously — now hidden from assistive tech.

+15 tests (365 -> 380) on the Skia-free announce logic, including the
sub-precision-jitter silence case. Canvas subtree verified byte-identical.

NOT verified with a real screen reader — no VoiceOver session was run. The
zero-cost-when-off and no-re-render-on-tick claims rest on reading the code.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md                        |  31 +++++++
 README.md                           |  46 ++++++++++
 src/Liveline.tsx                    |  92 ++++++++++++++++++++
 src/a11y/__tests__/announce.test.ts | 126 ++++++++++++++++++++++++++++
 src/a11y/announce.ts                | 104 +++++++++++++++++++++++
 src/a11y/useAccessibleValue.ts      |  97 +++++++++++++++++++++
 src/types.ts                        |  12 +++
 7 files changed, 508 insertions(+)
 create mode 100644 src/a11y/__tests__/announce.test.ts
 create mode 100644 src/a11y/announce.ts
 create mode 100644 src/a11y/useAccessibleValue.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 771de6f..45553bf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,37 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+
+- **Accessibility.** The chart is a Skia surface, so a screen reader previously
+  found an unlabelled blank region. `Liveline` now announces itself as an
+  `image` (React Native has no chart role) with a default label of
+  `'Live chart'`, overridable via the new **`accessibilityLabel`** prop, and
+  exposes the live number through `accessibilityValue` — run through the
+  consumer's `formatValue`, with the momentum direction appended
+  (`"64,201.55, rising"`).
+
+  This costs nothing when no screen reader is running. The value is gated on
+  `AccessibilityInfo.isScreenReaderEnabled()` plus its `screenReaderChanged`
+  listener; with no reader active there is no sampling timer, no state and no
+  accessibility value — one boolean test per render, and no UI→JS traffic. The
+  reading is taken from the props already on the JS thread rather than bridged
+  from the engine's UI-thread shared value, so the per-frame render path is
+  untouched and the chart still does not re-render on tick. When a reader *is*
+  active the value is sampled once a second, and readings that format
+  identically are skipped so a still chart stays quiet. `formatValue` is
+  therefore also called on the JS thread, roughly 1Hz, while a reader runs.
+
+  The built-in controls gained labels and selected/checked state — most
+  importantly the icon-only line/candle toggle, which had no text for a reader
+  to fall back on. The live-value overlay (`showValue`) is hidden from
+  assistive tech, since it is a `TextInput` driven at frame rate.
+
+- **`testID`** prop on the chart container. The built-in controls derive their
+  own ids from it (`-window-<secs>`, `-mode-line`, `-mode-candle`,
+  `-series-<id>`), so Detox and Maestro can target the chart and drive its
+  controls.
+
 ### Fixed
 
 - **`react-native-gesture-handler` peer range widened to `>=2.30.0`** (was
diff --git a/README.md b/README.md
index aabcc5e..8586dae 100644
--- a/README.md
+++ b/README.md
@@ -249,6 +249,52 @@ data" empty state is shown.
 | `onHover` | `(point: HoverPoint \| null) => void` | — | Hover callback with `{ time, value, x, y }` |
 | `style` | `StyleProp<ViewStyle>` | — | Container style |
 
+**Accessibility**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `accessibilityLabel` | `string` | `'Live chart'` | Label read by VoiceOver/TalkBack for the chart |
+| `testID` | `string` | — | Test id on the chart container; controls derive ids from it (see below) |
+
+### Accessibility
+
+The chart is drawn with Skia, so without help a screen reader finds nothing but
+an unlabelled blank region. `Liveline` announces itself as an image (React
+Native has no chart role) with `accessibilityLabel`, and exposes the live
+number through `accessibilityValue` — formatted with your `formatValue`, with
+the momentum direction appended:
+
+```
+"BTC/USD, image. 64,201.55, rising"
+```
+
+This costs nothing when no screen reader is running. `Liveline` checks
+`AccessibilityInfo.isScreenReaderEnabled()` and subscribes to
+`screenReaderChanged`; while no reader is active there is no sampling timer, no
+state, and no accessibility value at all. When a reader *is* active the value
+is sampled once a second — a screen reader cannot follow 60 updates a second,
+and restarts its utterance on every change, so a per-frame feed would read as
+an endless stutter. Readings that format identically are skipped, so a still
+chart stays quiet.
+
+Note that `formatValue` is called on the JS thread (about once a second) while
+a screen reader is running, in addition to its usual per-frame call on the UI
+thread. Keep it free of UI-thread-only dependencies.
+
+The window pills, line/candle toggle and series chips carry their own labels
+and selected/checked state. The icon-only mode toggle reads as "Line chart" and
+"Candlestick chart".
+
+**Test ids.** Give the chart a `testID` and the built-in controls derive theirs
+from it, so Detox and Maestro can drive them:
+
+| Element | Test id |
+|---------|---------|
+| Chart container | `${testID}` |
+| Window pill | `${testID}-window-${secs}` |
+| Mode toggle | `${testID}-mode-line`, `${testID}-mode-candle` |
+| Series chip | `${testID}-series-${id}` |
+
 ### Charts in lists
 
 Each `Liveline` runs its own 60fps UI-thread frame loop, so a long list of
diff --git a/src/Liveline.tsx b/src/Liveline.tsx
index c44cbb1..a5a00bb 100644
--- a/src/Liveline.tsx
+++ b/src/Liveline.tsx
@@ -41,6 +41,11 @@ import type {
 import { resolveTheme, resolveSeriesPalettes, SERIES_COLORS } from './theme';
 import { makeDefaultFonts } from './draw/fonts';
 import { useLivelineEngine } from './useLivelineEngine';
+import { resolveLiveValue } from './a11y/announce';
+import {
+  useAccessibleValue,
+  useScreenReaderEnabled,
+} from './a11y/useAccessibleValue';
 
 const AnimatedTextInput = Animated.createAnimatedComponent(TextInput);
 
@@ -341,6 +346,11 @@ function PillBar({
   return (
     <View
       pointerEvents={faded ? 'none' : 'auto'}
+      // A faded bar is invisible and untappable but still mounted, so it must
+      // also be invisible to a screen reader — otherwise the reader offers
+      // controls the sighted user cannot see and nobody can activate.
+      accessibilityElementsHidden={faded}
+      importantForAccessibility={faded ? 'no-hide-descendants' : 'auto'}
       style={[styles.bar, bar.chrome, faded && styles.barFaded]}
     >
       {indicator && !bar.isText && (
@@ -389,12 +399,14 @@ const WindowBar = memo(function WindowBarComponent({
   windows,
   activeSecs,
   onSelect,
+  testID,
 }: {
   bar: BarStyle;
   isDark: boolean;
   windows: WindowOption[];
   activeSecs: number;
   onSelect: (secs: number) => void;
+  testID: string | undefined;
 }) {
   const [layouts, setLayouts] = useState<Record<number, BtnLayout>>({});
   const onBtnLayout = useCallback((secs: number, e: LayoutChangeEvent) => {
@@ -420,6 +432,10 @@ const WindowBar = memo(function WindowBarComponent({
             key={w.secs}
             onLayout={(e) => onBtnLayout(w.secs, e)}
             onPress={() => onSelect(w.secs)}
+            accessibilityRole="button"
+            accessibilityLabel={`${w.label} time window`}
+            accessibilityState={{ selected: isActive }}
+            testID={testID ? `${testID}-window-${w.secs}` : undefined}
             style={bar.pill}
           >
             <Animated.Text
@@ -440,11 +456,13 @@ const ModeBar = memo(function ModeBarComponent({
   isDark,
   activeMode,
   onSelect,
+  testID,
 }: {
   bar: BarStyle;
   isDark: boolean;
   activeMode: 'line' | 'candle';
   onSelect: (mode: 'line' | 'candle') => void;
+  testID: string | undefined;
 }) {
   const [layouts, setLayouts] = useState<Record<string, BtnLayout>>({});
   const onBtnLayout = useCallback((key: string, e: LayoutChangeEvent) => {
@@ -463,9 +481,18 @@ const ModeBar = memo(function ModeBarComponent({
       indicator
       indicatorLayout={layouts[activeMode]}
     >
+      {/*
+        Icon-only buttons: there is no text child for a screen reader to fall
+        back on, so an explicit label is the only thing standing between a
+        reader user and an unnamed button.
+      */}
       <Pressable
         onLayout={(e) => onBtnLayout('line', e)}
         onPress={() => onSelect('line')}
+        accessibilityRole="button"
+        accessibilityLabel="Line chart"
+        accessibilityState={{ selected: activeMode === 'line' }}
+        testID={testID ? `${testID}-mode-line` : undefined}
         style={[styles.iconBtn, bar.iconBtn]}
       >
         <LineIcon
@@ -476,6 +503,10 @@ const ModeBar = memo(function ModeBarComponent({
       <Pressable
         onLayout={(e) => onBtnLayout('candle', e)}
         onPress={() => onSelect('candle')}
+        accessibilityRole="button"
+        accessibilityLabel="Candlestick chart"
+        accessibilityState={{ selected: activeMode === 'candle' }}
+        testID={testID ? `${testID}-mode-candle` : undefined}
         style={[styles.iconBtn, bar.iconBtn]}
       >
         <CandleIcon
@@ -509,6 +540,7 @@ const SeriesChipBar = memo(function SeriesChipBarComponent({
   compact,
   faded,
   onToggle,
+  testID,
 }: {
   bar: BarStyle;
   chip: ReturnType<typeof useChipStyle>;
@@ -519,6 +551,7 @@ const SeriesChipBar = memo(function SeriesChipBarComponent({
   /** Keep the chips mounted but invisible (chart left multi-series mode). */
   faded: boolean;
   onToggle: (id: string) => void;
+  testID: string | undefined;
 }) {
   return (
     <PillBar bar={bar} isDark={isDark} faded={faded}>
@@ -528,6 +561,12 @@ const SeriesChipBar = memo(function SeriesChipBarComponent({
           <Pressable
             key={s.id}
             onPress={() => onToggle(s.id)}
+            // A chip is a toggle, and in compact mode it is a bare coloured
+            // dot with no text at all — so it always carries its own label.
+            accessibilityRole="checkbox"
+            accessibilityLabel={s.label}
+            accessibilityState={{ checked: !isHidden }}
+            testID={testID ? `${testID}-series-${s.id}` : undefined}
             style={[chip.base, isHidden && chip.off]}
           >
             <View
@@ -574,6 +613,7 @@ const LivelineControls = memo(function LivelineControlsComponent({
   hiddenSeries,
   seriesToggleCompact,
   onSeriesToggle,
+  testID,
 }: {
   windowStyle: WindowStyle;
   isDark: boolean;
@@ -590,6 +630,8 @@ const LivelineControls = memo(function LivelineControlsComponent({
   hiddenSeries: Set<string>;
   seriesToggleCompact: boolean;
   onSeriesToggle: (id: string) => void;
+  /** Base id the per-control test ids are derived from (see `Liveline`). */
+  testID: string | undefined;
 }) {
   const bar = useBarStyle(windowStyle, isDark);
   const chip = useChipStyle(bar, isDark, seriesToggleCompact);
@@ -606,6 +648,7 @@ const LivelineControls = memo(function LivelineControlsComponent({
           windows={windows}
           activeSecs={activeWindowSecs}
           onSelect={onWindowSelect}
+          testID={testID}
         />
       )}
 
@@ -615,6 +658,7 @@ const LivelineControls = memo(function LivelineControlsComponent({
           isDark={isDark}
           activeMode={activeMode}
           onSelect={onModeSelect}
+          testID={testID}
         />
       )}
 
@@ -628,6 +672,7 @@ const LivelineControls = memo(function LivelineControlsComponent({
           compact={seriesToggleCompact}
           faded={seriesFaded}
           onToggle={onSeriesToggle}
+          testID={testID}
         />
       )}
     </View>
@@ -688,6 +733,8 @@ export const Liveline = memo(function LivelineComponent({
   seriesToggleCompact = false,
   lineWidth,
   fonts: fontsOverride,
+  accessibilityLabel,
+  testID,
   style,
 }: LivelineProps) {
   const lastSeriesPropRef = useRef(seriesProp);
@@ -852,12 +899,47 @@ export const Liveline = memo(function LivelineComponent({
 
   const selectMode = useStableHandler(onModeChange);
 
+  // --- Accessibility --------------------------------------------------------
+  // The chart is a Skia surface: without this a screen reader finds an
+  // unlabelled blank rectangle. The live number is a UI-thread shared value
+  // updated at frame rate, and accessibility props are JS-thread React props,
+  // so there is deliberately no per-frame bridge between them. Instead the
+  // reading is taken from the props already on this thread (`value` &co.) and
+  // sampled at a speakable ~1Hz — and only while a reader is actually running.
+  //
+  // With no reader (the overwhelmingly common case) `screenReader` is false,
+  // `resolveLiveValue` is never called, no timer exists, no state is committed
+  // and `chartA11yValue` is a stable `undefined`: the cost is one boolean test
+  // per render. Nothing here can make the chart re-render on tick.
+  const screenReader = useScreenReaderEnabled();
+  const chartA11yValue = useAccessibleValue(
+    screenReader,
+    screenReader
+      ? resolveLiveValue({
+          value,
+          mode,
+          lineMode,
+          lineValue,
+          liveCandle,
+          candles,
+        })
+      : null,
+    formatValue
+  );
+
   return (
     <>
       {/* Live value display — above the chart */}
       {showValue && (
         <AnimatedTextInput
           editable={false}
+          // Hidden from assistive tech on purpose. It is a TextInput driven
+          // from the UI thread at frame rate, so a reader would announce it as
+          // a text field whose contents change 60 times a second. The same
+          // number reaches the reader through the chart's accessibilityValue,
+          // at a cadence a person can actually follow.
+          accessibilityElementsHidden
+          importantForAccessibility="no-hide-descendants"
           animatedProps={valueProps}
           style={[styles.valueDisplay, { paddingLeft: pad.left }, valueStyle]}
         />
@@ -885,6 +967,7 @@ export const Liveline = memo(function LivelineComponent({
         hiddenSeries={hiddenSeries}
         seriesToggleCompact={seriesToggleCompact}
         onSeriesToggle={toggleSeries}
+        testID={testID}
       />
 
       <GestureDetector gesture={engine.gesture}>
@@ -892,6 +975,15 @@ export const Liveline = memo(function LivelineComponent({
           onLayout={engine.onLayout}
           style={[styles.container, style]}
           collapsable={false}
+          // Accessibility lives out here, on the container — never inside the
+          // Skia subtree below, whose node structure must stay fixed.
+          // `image` is React Native's conventional role for a rendered
+          // graphic; there is no chart role.
+          accessible
+          accessibilityRole="image"
+          accessibilityLabel={accessibilityLabel ?? 'Live chart'}
+          accessibilityValue={chartA11yValue}
+          testID={testID}
         >
           {/*
             Fixed 4-node tree — never reconciled after mount. Every per-frame
diff --git a/src/a11y/__tests__/announce.test.ts b/src/a11y/__tests__/announce.test.ts
new file mode 100644
index 0000000..f5c3aa0
--- /dev/null
+++ b/src/a11y/__tests__/announce.test.ts
@@ -0,0 +1,126 @@
+import {
+  ANNOUNCE_INTERVAL_MS,
+  announceDirection,
+  nextAnnouncement,
+  resolveLiveValue,
+  type Announcement,
+} from '../announce';
+
+const fmt = (v: number) => v.toFixed(2);
+
+describe('ANNOUNCE_INTERVAL_MS', () => {
+  it('is a human-readable cadence, not a frame cadence', () => {
+    expect(ANNOUNCE_INTERVAL_MS).toBeGreaterThanOrEqual(500);
+  });
+});
+
+describe('resolveLiveValue', () => {
+  it('uses the value prop in line mode', () => {
+    expect(resolveLiveValue({ value: 12.5 })).toBe(12.5);
+    expect(resolveLiveValue({ value: 12.5, mode: 'line' })).toBe(12.5);
+  });
+
+  it('prefers the live candle close in candle mode', () => {
+    expect(
+      resolveLiveValue({
+        value: 1,
+        mode: 'candle',
+        liveCandle: { close: 9 },
+        candles: [{ close: 5 }],
+      })
+    ).toBe(9);
+  });
+
+  it('falls back to the last closed candle when there is no live candle', () => {
+    expect(
+      resolveLiveValue({
+        value: 1,
+        mode: 'candle',
+        candles: [{ close: 5 }, { close: 7 }],
+      })
+    ).toBe(7);
+  });
+
+  it('falls back to the value prop when candle mode has no candles', () => {
+    expect(resolveLiveValue({ value: 1, mode: 'candle', candles: [] })).toBe(1);
+  });
+
+  it('ignores candles once the chart has morphed to line mode', () => {
+    expect(
+      resolveLiveValue({
+        value: 1,
+        mode: 'candle',
+        lineMode: true,
+        lineValue: 3,
+        liveCandle: { close: 9 },
+      })
+    ).toBe(3);
+  });
+
+  it('returns null when no usable number exists', () => {
+    expect(resolveLiveValue({})).toBeNull();
+    expect(resolveLiveValue({ value: Number.NaN })).toBeNull();
+    expect(resolveLiveValue({ value: Number.POSITIVE_INFINITY })).toBeNull();
+  });
+});
+
+describe('announceDirection', () => {
+  it('reports steady for the first reading', () => {
+    expect(announceDirection(null, 5)).toBe('steady');
+  });
+
+  it('reports rising, falling and steady', () => {
+    expect(announceDirection(4, 5)).toBe('rising');
+    expect(announceDirection(6, 5)).toBe('falling');
+    expect(announceDirection(5, 5)).toBe('steady');
+  });
+});
+
+describe('nextAnnouncement', () => {
+  it('returns null when there is nothing to read', () => {
+    expect(nextAnnouncement(null, null, fmt)).toBeNull();
+  });
+
+  it('formats the first reading without a direction', () => {
+    expect(nextAnnouncement(null, 1.5, fmt)).toEqual({
+      value: 1.5,
+      formatted: '1.50',
+      text: '1.50',
+    });
+  });
+
+  it('appends the momentum direction on subsequent readings', () => {
+    const first = nextAnnouncement(null, 1.5, fmt)!;
+    expect(nextAnnouncement(first, 2, fmt)).toEqual({
+      value: 2,
+      formatted: '2.00',
+      text: '2.00, rising',
+    });
+    expect(nextAnnouncement(first, 1, fmt)).toEqual({
+      value: 1,
+      formatted: '1.00',
+      text: '1.00, falling',
+    });
+  });
+
+  it('stays silent when the reading is unchanged', () => {
+    const prev: Announcement = { value: 1.5, formatted: '1.50', text: '1.50' };
+    expect(nextAnnouncement(prev, 1.5, fmt)).toBeNull();
+  });
+
+  it('stays silent on jitter below the formatter precision', () => {
+    // The single most important case: a live feed moves constantly, but a
+    // reader must not be told "1.50, rising" once a second forever.
+    const prev: Announcement = { value: 1.5, formatted: '1.50', text: '1.50' };
+    expect(nextAnnouncement(prev, 1.5004, fmt)).toBeNull();
+    expect(nextAnnouncement(prev, 1.4999, fmt)).toBeNull();
+  });
+
+  it('respects the consumer formatter', () => {
+    expect(nextAnnouncement(null, 1234.5, (v) => `$${v.toFixed(0)}`)).toEqual({
+      value: 1234.5,
+      formatted: '$1235',
+      text: '$1235',
+    });
+  });
+});
diff --git a/src/a11y/announce.ts b/src/a11y/announce.ts
new file mode 100644
index 0000000..ffdffb8
--- /dev/null
+++ b/src/a11y/announce.ts
@@ -0,0 +1,104 @@
+/**
+ * Screen-reader announcement logic — deliberately free of React, React Native
+ * and Skia imports so it is unit-testable and so nothing here can be pulled
+ * into the render path by accident.
+ *
+ * The chart itself is a Skia surface: to a screen reader it is an unlabelled
+ * blank rectangle. The container `<View>` therefore carries the semantics, and
+ * the live number is surfaced through `accessibilityValue.text`.
+ *
+ * Cadence matters. The displayed value is a UI-thread shared value updated at
+ * frame rate; a screen reader cannot consume 60 readings a second and is
+ * actively worse for being handed them (VoiceOver/TalkBack restart their
+ * utterance on every value change, so a per-frame feed reads as an infinite
+ * stutter and never finishes a number). One update per second is the target.
+ */
+
+/** Minimum wall-clock gap between two announced values. */
+export const ANNOUNCE_INTERVAL_MS = 1000;
+
+export type AnnounceDirection = 'rising' | 'falling' | 'steady';
+
+/** One settled reading, as handed to `accessibilityValue.text`. */
+export interface Announcement {
+  /** The raw number this reading was built from. */
+  value: number;
+  /** `value` run through the consumer's `formatValue`. */
+  formatted: string;
+  /** What the screen reader says — `formatted` plus the direction. */
+  text: string;
+}
+
+/**
+ * Everything `resolveLiveValue` may read. A structural subset of
+ * `LivelineProps` rather than the type itself, to keep this module free of the
+ * Skia-flavoured type graph.
+ */
+export interface LiveValueSource {
+  value?: number;
+  mode?: 'line' | 'candle';
+  lineMode?: boolean;
+  lineValue?: number;
+  liveCandle?: { close: number } | undefined;
+  candles?: readonly { close: number }[] | undefined;
+}
+
+const isNum = (v: unknown): v is number =>
+  typeof v === 'number' && Number.isFinite(v);
+
+/**
+ * The number a screen reader should hear, picked from whichever prop is
+ * authoritative for the chart's current mode.
+ *
+ * Note this reads the *props*, not the engine's interpolated shared value. The
+ * engine lerps toward the incoming value over several frames for visual
+ * smoothness; a spoken reading of an in-between frame would be wrong, and the
+ * props are already on the JS thread, so this needs no UI→JS crossing at all.
+ */
+export function resolveLiveValue(src: LiveValueSource): number | null {
+  if (src.mode === 'candle' && !src.lineMode) {
+    const live = src.liveCandle;
+    if (live && isNum(live.close)) return live.close;
+    const candles = src.candles;
+    if (candles && candles.length > 0) {
+      const last = candles[candles.length - 1];
+      if (last && isNum(last.close)) return last.close;
+    }
+  }
+  if (src.lineMode && isNum(src.lineValue)) return src.lineValue;
+  return isNum(src.value) ? src.value : null;
+}
+
+/** Which way the value moved since the previous reading. */
+export function announceDirection(
+  prev: number | null,
+  next: number
+): AnnounceDirection {
+  if (prev === null || prev === next) return 'steady';
+  return next > prev ? 'rising' : 'falling';
+}
+
+/**
+ * The next reading, or `null` when nothing should be announced — either
+ * because there is no value yet, or because the number is unchanged *at the
+ * consumer's display precision* since the last reading.
+ *
+ * The unchanged test is deliberately on the formatted string, not the raw
+ * number: a live feed jitters below the formatter's precision constantly, and
+ * comparing raw numbers would re-announce an apparently identical reading
+ * every second forever. Direction is only computed once the formatted text has
+ * moved, so "rising" always corresponds to a change the listener can hear.
+ */
+export function nextAnnouncement(
+  prev: Announcement | null,
+  value: number | null,
+  format: (v: number) => string
+): Announcement | null {
+  if (value === null) return null;
+  const formatted = format(value);
+  if (prev !== null && prev.formatted === formatted) return null;
+  const direction = announceDirection(prev === null ? null : prev.value, value);
+  const text =
+    direction === 'steady' ? formatted : `${formatted}, ${direction}`;
+  return { value, formatted, text };
+}
diff --git a/src/a11y/useAccessibleValue.ts b/src/a11y/useAccessibleValue.ts
new file mode 100644
index 0000000..7bc9750
--- /dev/null
+++ b/src/a11y/useAccessibleValue.ts
@@ -0,0 +1,97 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { AccessibilityInfo, type AccessibilityValue } from 'react-native';
+import {
+  ANNOUNCE_INTERVAL_MS,
+  nextAnnouncement,
+  type Announcement,
+} from './announce';
+
+/**
+ * Whether a screen reader (VoiceOver / TalkBack) is currently running.
+ *
+ * This is the gate the whole accessibility path hangs off: it costs one
+ * promise and one listener subscription at mount, and nothing at all per
+ * render or per frame. Everything downstream of it is skipped entirely while
+ * it reads `false`, which is the overwhelmingly common case.
+ */
+export function useScreenReaderEnabled(): boolean {
+  const [enabled, setEnabled] = useState(false);
+
+  useEffect(() => {
+    let mounted = true;
+    AccessibilityInfo.isScreenReaderEnabled()
+      .then((value) => {
+        if (mounted) setEnabled(value);
+      })
+      .catch(() => {
+        // A platform that cannot answer is treated as "no reader" — the
+        // chart then behaves exactly as it did before this existed.
+      });
+    const sub = AccessibilityInfo.addEventListener(
+      'screenReaderChanged',
+      (value) => setEnabled(value)
+    );
+    return () => {
+      mounted = false;
+      sub.remove();
+    };
+  }, []);
+
+  return enabled;
+}
+
+/**
+ * A referentially stable `accessibilityValue` carrying the chart's current
+ * reading, or `undefined` when no screen reader is running.
+ *
+ * `value` is read through a ref rather than an effect dependency, and the
+ * sampling timer is only created while `enabled` — so with the reader off this
+ * hook does one boolean test and one ref write per render, allocates nothing,
+ * and registers no timer, no listener and no UI-thread work.
+ *
+ * With the reader on, the timer samples at {@link ANNOUNCE_INTERVAL_MS} and
+ * only commits state when the formatted text actually changed, so a live chart
+ * costs at most one extra React render per second and a still one costs none.
+ * Crucially it does *not* re-render on tick: the chart's ~60Hz updates flow
+ * into a ref, never into state.
+ */
+export function useAccessibleValue(
+  enabled: boolean,
+  value: number | null,
+  format: (v: number) => string
+): AccessibilityValue | undefined {
+  const latest = useRef<number | null>(null);
+  latest.current = enabled ? value : null;
+
+  // `formatValue` is typically an inline arrow on the consumer's side, so its
+  // identity churns every tick. Reading it through a ref keeps it out of the
+  // effect's dependency list — otherwise the sampling timer would be torn
+  // down and rebuilt on every frame.
+  const formatRef = useRef(format);
+  formatRef.current = format;
+
+  const [text, setText] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!enabled) {
+      setText(null);
+      return;
+    }
+    let prev: Announcement | null = null;
+    const sample = () => {
+      const next = nextAnnouncement(prev, latest.current, formatRef.current);
+      if (next === null) return;
+      prev = next;
+      setText(next.text);
+    };
+    sample();
+    const id = setInterval(sample, ANNOUNCE_INTERVAL_MS);
+    return () => clearInterval(id);
+  }, [enabled]);
+
+  // Memoized so the prop identity only changes when the spoken text does —
+  // a fresh object every render would push an accessibility update to the
+  // host view on every tick, which is the exact thing this hook exists to
+  // avoid.
+  return useMemo(() => (text === null ? undefined : { text }), [text]);
+}
diff --git a/src/types.ts b/src/types.ts
index c140ddc..7f3dc23 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -166,6 +166,18 @@ export interface LivelineProps {
   onSeriesToggle?: (id: string, visible: boolean) => void; // Multi-series toggle callback
   seriesToggleCompact?: boolean; // Show only colored dots (no labels) in series toggle (default: false)
 
+  /**
+   * Label read by VoiceOver/TalkBack for the chart itself (default:
+   * `'Live chart'`). The chart is a Skia surface, so a screen reader has no
+   * other way to know what it is; the live value is exposed separately through
+   * `accessibilityValue`, which the component maintains itself.
+   *
+   * React Native has no chart role, so the container is announced as an image.
+   */
+  accessibilityLabel?: string;
+  /** Test identifier on the chart's container view, for Detox/Maestro. */
+  testID?: string;
+
   style?: StyleProp<ViewStyle>;
 }
 

From a4b39c21894e83f13c7a8358dbe2be247d9e3b64 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Sun, 2 Aug 2026 23:40:45 -0400
Subject: [PATCH 34/37] fix(theme): correct 4/8-digit hex parsing; warn instead
 of failing silently
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three defects found by an API/docs review.

1. `parseColorRgb` accepted `#` + 3-8 hex digits but only expanded the 3-digit
   form, so a CSS Color 4 shorthand like `#38fc` produced `parseInt('', 16)` =
   NaN for the blue channel, propagating silently into gradients and paints.
   Now expands 3- and 4-digit, returns only for 6/8, and falls through to the
   grey fallback for any other length rather than mangling a partial parse.
   `color` is typed as a plain string with no documented format restriction,
   so a consumer piping a design token or colour-picker value through it got
   garbage rather than an error.

2. Unparseable input (named colours, garbage) fell back to grey with no signal
   at all. Now warns under __DEV__ naming the offending value.

   The warning is de-duplicated against the last-warned value, which the
   original fix did not do: `parseColorRgb` is called from the FRAME PATH —
   draw/dot.ts parses `palette.line` and `palette.badgeOuterBg` while
   scrub-dimming — so an unconditional warn would fire up to 60 times a second
   for as long as a bad colour was set. That is noisier than the silent
   fallback it replaced. One string compare per call, no allocation, and a bad
   colour still reports exactly once.

3. `LivelineTransition` rendered nothing, silently, when `active` matched no
   child key (a typo, or a conditionally-absent child) — blank chart, no
   signal, self-healing only when `active` later changed to a real key. Now
   warns under __DEV__ naming both the bad value and the keys that DO exist.

Also corrects a comment in theme.ts claiming "Dot — always semantic": the dot
paints from `palette.line` unconditionally, and the eight momentum/glow/badge
palette fields it referred to are computed but read by nothing. The fields are
kept (removing them means touching types.ts and fixtures owned elsewhere) with
an accurate comment instead.

Adds src/__tests__/theme.test.ts (15 tests) — the module had none. Covers
3/4/6/8-digit hex, case, rgb()/rgba(), invalid lengths, named colours, a
NaN-freedom sweep, and that resolveTheme derives fillTop/fillBottom from the
same rgb as `line` (the invariant the scroll-layer z-order relies on).

Tests 380 -> 395.

NOT acted on: the agent also reported resolveTheme has "zero callers" and that
Liveline.tsx never imports theme.ts. That is false — Liveline.tsx:41 imports it
and calls it at 745, 762 and 774. Verified before discarding.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md                |  15 +++++
 README.md                   |   7 ++-
 src/LivelineTransition.tsx  |  16 ++++++
 src/__tests__/theme.test.ts | 106 ++++++++++++++++++++++++++++++++++++
 src/theme.ts                |  71 +++++++++++++++++++-----
 5 files changed, 200 insertions(+), 15 deletions(-)
 create mode 100644 src/__tests__/theme.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 45553bf..d520c36 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -37,6 +37,21 @@ All notable changes to this project will be documented in this file.
 
 ### Fixed
 
+- **`parseColorRgb` (used to derive the palette from the `color` prop) no
+  longer produces `NaN` channels for 4-digit hex shorthand** (`#rgba`, the
+  CSS Color 4 shorthand-with-alpha form, e.g. `"#38fc"`). It also now handles
+  8-digit hex (`#rrggbbaa`) correctly, and rejects any hex length other than
+  3/4/6/8 instead of silently mangling it — both now fall back to the
+  existing grey default. In development, an unparseable `color` (including
+  named CSS colors like `"red"`, which were never supported) logs a warning
+  naming the offending value instead of failing silently into gradients and
+  paints. See the `color` prop docs in the README for the full list of
+  supported formats.
+- **`LivelineTransition` now warns in development when `active` matches no
+  child's `key`.** Previously a typo'd or conditionally-absent `active` value
+  produced a blank chart area with no signal until `active` later changed to
+  a key that does exist. The warning names both the bad value and the keys
+  that are actually available.
 - **`react-native-gesture-handler` peer range widened to `>=2.30.0`** (was
   `>=3.0.0`). The v3 floor existed only because the engine imported a
   v3-only type name for a union it never used — the hook always returns a
diff --git a/README.md b/README.md
index 8586dae..521b280 100644
--- a/README.md
+++ b/README.md
@@ -138,7 +138,7 @@ The component fills its parent container — set a height on the parent. Pass
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `theme` | `'light' \| 'dark'` | `'dark'` | Color scheme |
-| `color` | `string` | `'#3b82f6'` | Accent color — all palette colors derived from this |
+| `color` | `string` | `'#3b82f6'` | Accent color — all palette colors derived from this. Accepts `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb()`, or `rgba()`. Named CSS colors (e.g. `"red"`) are not supported and fall back to grey. |
 | `grid` | `boolean` | `true` | Y-axis grid lines + labels |
 | `badge` | `boolean` | `true` | Value pill tracking chart tip |
 | `badgeVariant` | `'default' \| 'minimal'` | `'default'` | Badge style: accent-colored or white with grey text |
@@ -374,7 +374,10 @@ Note that `formatValue` / `formatTime` run on the UI thread and need the
 ### `LivelineTransition`
 
 Cross-fades between chart components (e.g. line ↔ candlestick). Children must
-have unique `key` props matching possible `active` values.
+have unique `key` props matching possible `active` values. If `active` doesn't
+match any child's key, nothing renders (there is no visible chart until
+`active` changes to a valid key) — in development this logs a warning naming
+the bad value and the keys that are available.
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
diff --git a/src/LivelineTransition.tsx b/src/LivelineTransition.tsx
index 2e911eb..c8154b0 100644
--- a/src/LivelineTransition.tsx
+++ b/src/LivelineTransition.tsx
@@ -68,11 +68,27 @@ export function LivelineTransition({
   style,
 }: LivelineTransitionProps) {
   const childArray = Array.isArray(children) ? children : [children];
+  const childKeys = childArray.map((child) => String(child.key ?? ''));
 
   const [mounted, setMounted] = useState<Set<string>>(() => new Set([active]));
   const [visible, setVisible] = useState(active);
   const prevRef = useRef(active);
 
+  useEffect(() => {
+    if (__DEV__ && !childKeys.includes(active)) {
+      console.warn(
+        `[react-native-liveline] LivelineTransition: active="${active}" does not ` +
+          'match any child key, so nothing will render until "active" changes to ' +
+          `one of the available keys: ${
+            childKeys.length
+              ? childKeys.map((k) => `"${k}"`).join(', ')
+              : '(none — no children have a key prop)'
+          }.`
+      );
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [active, childKeys.join('|')]);
+
   useEffect(() => {
     if (active === prevRef.current) return () => {};
     const oldKey = prevRef.current;
diff --git a/src/__tests__/theme.test.ts b/src/__tests__/theme.test.ts
new file mode 100644
index 0000000..e8b902f
--- /dev/null
+++ b/src/__tests__/theme.test.ts
@@ -0,0 +1,106 @@
+import { parseColorRgb, resolveTheme, resolveSeriesPalettes } from '../theme';
+
+/**
+ * `theme.ts` had no test coverage before this file, despite being pure and
+ * despite `parseColorRgb` silently producing NaN channels on 4-digit hex
+ * shorthand (`#rgba`) before that was fixed — a bad color would previously
+ * flow into gradient/paint strings with no signal until something rendered
+ * wrong on screen. These tests pin the parser's supported formats and the
+ * fallback behavior for everything else.
+ */
+
+describe('parseColorRgb', () => {
+  it('parses 3-digit hex shorthand', () => {
+    expect(parseColorRgb('#f00')).toEqual([255, 0, 0]);
+    expect(parseColorRgb('#0f0')).toEqual([0, 255, 0]);
+  });
+
+  it('parses 6-digit hex', () => {
+    expect(parseColorRgb('#3b82f6')).toEqual([0x3b, 0x82, 0xf6]);
+  });
+
+  it('parses 4-digit hex shorthand (#rgba), ignoring alpha', () => {
+    // This is the CSS Color 4 shorthand-with-alpha form that previously
+    // produced NaN for the blue channel.
+    expect(parseColorRgb('#38fc')).toEqual([0x33, 0x88, 0xff]);
+  });
+
+  it('parses 8-digit hex (#rrggbbaa), ignoring alpha', () => {
+    expect(parseColorRgb('#3b82f680')).toEqual([0x3b, 0x82, 0xf6]);
+  });
+
+  it('is case-insensitive', () => {
+    expect(parseColorRgb('#3B82F6')).toEqual([0x3b, 0x82, 0xf6]);
+  });
+
+  it('parses rgb()', () => {
+    expect(parseColorRgb('rgb(59, 130, 246)')).toEqual([59, 130, 246]);
+  });
+
+  it('parses rgba(), ignoring alpha', () => {
+    expect(parseColorRgb('rgba(59, 130, 246, 0.5)')).toEqual([59, 130, 246]);
+  });
+
+  it('never returns NaN for any supported hex length', () => {
+    for (const c of ['#f00', '#f00f', '#3b82f6', '#3b82f680']) {
+      const [r, g, b] = parseColorRgb(c);
+      expect(Number.isNaN(r)).toBe(false);
+      expect(Number.isNaN(g)).toBe(false);
+      expect(Number.isNaN(b)).toBe(false);
+    }
+  });
+
+  it('falls back to grey for an invalid hex length (not 3/4/6/8)', () => {
+    expect(parseColorRgb('#12345')).toEqual([128, 128, 128]);
+    expect(parseColorRgb('#1234567')).toEqual([128, 128, 128]);
+  });
+
+  it('falls back to grey for named CSS colors', () => {
+    expect(parseColorRgb('red')).toEqual([128, 128, 128]);
+  });
+
+  it('falls back to grey for garbage input', () => {
+    expect(parseColorRgb('not-a-color')).toEqual([128, 128, 128]);
+    expect(parseColorRgb('')).toEqual([128, 128, 128]);
+  });
+});
+
+describe('resolveTheme', () => {
+  it('derives fill colors from the same rgb as the line', () => {
+    // The scroll-layer z-order work depends on fillTop/fillBottom sharing the
+    // exact r/g/b channels that `color` (and therefore `line`) resolves to —
+    // this pins that invariant.
+    const palette = resolveTheme('#3b82f6', 'light');
+    const [r, g, b] = parseColorRgb('#3b82f6');
+    expect(palette.line).toBe('#3b82f6');
+    expect(palette.fillTop).toBe(`rgba(${r}, ${g}, ${b}, 0.08)`);
+    expect(palette.fillBottom).toBe(`rgba(${r}, ${g}, ${b}, 0)`);
+  });
+
+  it('uses a stronger fill opacity in dark mode than light mode', () => {
+    const light = resolveTheme('#3b82f6', 'light');
+    const dark = resolveTheme('#3b82f6', 'dark');
+    expect(light.fillTop).toContain('0.08');
+    expect(dark.fillTop).toContain('0.12');
+  });
+
+  it('does not throw and falls back sanely for an unparseable color', () => {
+    const palette = resolveTheme('not-a-color', 'light');
+    expect(palette.fillTop).toBe('rgba(128, 128, 128, 0.08)');
+  });
+});
+
+describe('resolveSeriesPalettes', () => {
+  it('assigns each series its own color, falling back to the default cycle', () => {
+    const palettes = resolveSeriesPalettes(
+      [
+        { id: 'a', data: [], value: 0, color: '#ff0000' },
+        { id: 'b', data: [], value: 0, color: '' },
+      ],
+      'light'
+    );
+    expect(palettes.get('a')!.line).toBe('#ff0000');
+    // Falls back to SERIES_COLORS[1] when no color is given.
+    expect(palettes.get('b')!.line).toBe('#ef4444');
+  });
+});
diff --git a/src/theme.ts b/src/theme.ts
index 0e2938b..bf9c5cb 100644
--- a/src/theme.ts
+++ b/src/theme.ts
@@ -1,20 +1,53 @@
 import type { ThemeMode, LivelinePalette, LivelineSeries } from './types';
 
-/** Parse any CSS color string to [r, g, b]. Handles hex (#rgb, #rrggbb), rgb(), rgba(). */
+// Last value warned about by `parseColorRgb` below. That function is called
+// from the frame path (`draw/dot.ts` parses `palette.line` and
+// `palette.badgeOuterBg` while scrub-dimming), so an unconditional dev warning
+// would fire up to 60 times a second for as long as a bad colour is set —
+// noisier than the silent fallback it replaced. One string compare per call,
+// no allocation, and a bad colour still reports exactly once.
+let lastWarnedColor = '';
+
+/**
+ * Parse any CSS color string to [r, g, b].
+ *
+ * Supported formats: `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb()`, `rgba()`.
+ * Named CSS colors (e.g. `"red"`) are NOT supported and fall back to grey —
+ * pass a hex or rgb()/rgba() string instead.
+ *
+ * Unparseable input falls back to mid-grey `[128, 128, 128]` rather than
+ * throwing, so a bad color never crashes rendering; in development this logs
+ * a warning naming the offending value.
+ */
 export function parseColorRgb(color: string): [number, number, number] {
   'worklet';
-  const hex = color.match(/^#([0-9a-f]{3,8})$/i);
+  const hex = color.match(/^#([0-9a-f]+)$/i);
   if (hex) {
     let h = hex[1]!;
-    if (h.length === 3) h = h[0]! + h[0]! + h[1]! + h[1]! + h[2]! + h[2]!;
-    return [
-      parseInt(h.slice(0, 2), 16),
-      parseInt(h.slice(2, 4), 16),
-      parseInt(h.slice(4, 6), 16),
-    ];
+    if (h.length === 3 || h.length === 4) {
+      // Expand shorthand: #rgb -> #rrggbb, #rgba -> #rrggbbaa (alpha ignored).
+      h = h[0]! + h[0]! + h[1]! + h[1]! + h[2]! + h[2]!;
+    }
+    if (h.length === 6 || h.length === 8) {
+      return [
+        parseInt(h.slice(0, 2), 16),
+        parseInt(h.slice(2, 4), 16),
+        parseInt(h.slice(4, 6), 16),
+      ];
+    }
+    // Invalid digit count (not 3/4/6/8) — fall through to the grey fallback
+    // below rather than silently mangling a partial parse.
+  } else {
+    const rgb = color.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/);
+    if (rgb) return [+rgb[1]!, +rgb[2]!, +rgb[3]!];
+  }
+  if (__DEV__ && color !== lastWarnedColor) {
+    lastWarnedColor = color;
+    console.warn(
+      `[react-native-liveline] parseColorRgb: unrecognized color "${color}" — ` +
+        'expected #rgb, #rgba, #rrggbb, #rrggbbaa, rgb(), or rgba(). Falling back to grey.'
+    );
   }
-  const rgb = color.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/);
-  if (rgb) return [+rgb[1]!, +rgb[2]!, +rgb[3]!];
   return [128, 128, 128];
 }
 
@@ -25,7 +58,11 @@ function rgba(r: number, g: number, b: number, a: number): string {
 
 /**
  * Derive a full palette from a single accent color + theme mode.
- * Momentum colors are always semantic green/red regardless of accent.
+ *
+ * Note: `dotUp`/`dotDown`/`dotFlat`/`glowUp`/`glowDown`/`glowFlat`/`badgeBg`/
+ * `badgeText` are computed here but not read by the current renderer (see
+ * comments below) — the dot and badge paint from `line`/`badgeOuterBg`/
+ * `tooltipText` instead. Momentum is not currently expressed as dot color.
  */
 export function resolveTheme(color: string, mode: ThemeMode): LivelinePalette {
   'worklet';
@@ -45,7 +82,12 @@ export function resolveTheme(color: string, mode: ThemeMode): LivelinePalette {
     gridLine: isDark ? 'rgba(255, 255, 255, 0.06)' : 'rgba(0, 0, 0, 0.06)',
     gridLabel: isDark ? 'rgba(255, 255, 255, 0.4)' : 'rgba(0, 0, 0, 0.35)',
 
-    // Dot — always semantic
+    // Dot — NOT currently read by the renderer. `src/draw/dot.ts` paints the
+    // live dot unconditionally from `palette.line`; these fields are kept
+    // (rather than removed) only because `LivelinePalette` is a shared type
+    // consumed by src/draw/* and src/engine/*, and the surface required to
+    // safely drop them is out of this file's scope. Do not treat these as
+    // "the dot's momentum color" — that behavior does not exist today.
     dotUp: '#22c55e',
     dotDown: '#ef4444',
     dotFlat: color,
@@ -53,7 +95,10 @@ export function resolveTheme(color: string, mode: ThemeMode): LivelinePalette {
     glowDown: 'rgba(239, 68, 68, 0.18)',
     glowFlat: rgba(r, g, b, 0.12),
 
-    // Badge
+    // Badge — `badgeBg`/`badgeText` below are likewise unused by the
+    // renderer; `src/engine/badge.ts` sources its fill/text colors from
+    // `badgeOuterBg`, `line`, and `tooltipText` instead. Kept for the same
+    // reason as the dot fields above.
     badgeOuterBg: isDark
       ? 'rgba(40, 40, 40, 0.95)'
       : 'rgba(255, 255, 255, 0.95)',

From bd9b693ff33ca9dafd3c001218b367f343fe0fb8 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Sun, 2 Aug 2026 23:54:37 -0400
Subject: [PATCH 35/37] test(engine): characterization suite for engineStep
 (+42)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The safety net for PLAN_MAINT #1 — extracting three inline pipelines from a
~1,900-line function that share one EngineState. Existing coverage was 17
regression tests pinning bugs fixed today; this pins the surface.

Asserts EngineState field values, which draw functions ran, how many times,
and in what ORDER (via jest invocationCallOrder merged across nine mocks).
Deliberately never asserts argument tuples — a concurrent refactor is
reshaping those signatures, and tuple assertions would break for reasons
unrelated to correctness.

Covers: golden 5-frame sequences per pipeline (~16-22 EngineState fields each,
explicit toEqual rather than snapshot files); the full six-direction mode
transition matrix plus a line->multi->line round trip; and the ordering
invariants that are load-bearing but currently only documented in comments —
the scroll-layer gate running after updateHoverState and before drawFrame,
grid-before-draw in all three pipelines, and pausedDt at all three
updateGridLayer sites.

12 mutations applied, run, reverted — 12 caught. One (flipping the line
pipeline's window buffer) escaped the first draft because the buffer lands on
no EngineState field; a group reading layout.rightEdge off the call closed it.
Independently re-verified here: mutating one pausedDt to dt fails exactly the
grid-dt test.

THREE FINDINGS FOR THE REFACTOR, all pinned as-is on purpose so the extraction
changes them deliberately rather than by accident:

- `rangeInited` is ONE flag shared by all three pipelines, and it is a real
  stale-state leak. After line->candle, updateCandleRange sees it already true
  and LERPS the Y range away from the line's range instead of snapping to the
  candle's. Symmetric for candle->multi. If the extraction gives each pipeline
  its own range state, two tests here will fail — that failure is the signal.
- Cleanup is asymmetric: the five per-series maps are pruned on leaving multi
  mode, but nothing prunes candle state or line state on exit.
- drawMultiFrame gets raw dt while drawFrame/drawCandleFrame get pausedDt. An
  extraction that unifies the three call sites silently changes multi-series
  pause behaviour.

Also documents what resisted characterization: the scroll-layer gate is
unreachable under a mocked draw layer (lineCacheHits needs a prefix only the
real drawFrame builds), so the mock had to write the cache slot — without that
every scroll-layer test would have been vacuously green. A trap for anyone
extending this file.

Tests 395 -> 437. No source file touched.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../__tests__/stepCharacterization.test.ts    | 1420 +++++++++++++++++
 1 file changed, 1420 insertions(+)
 create mode 100644 src/engine/__tests__/stepCharacterization.test.ts

diff --git a/src/engine/__tests__/stepCharacterization.test.ts b/src/engine/__tests__/stepCharacterization.test.ts
new file mode 100644
index 0000000..0d59415
--- /dev/null
+++ b/src/engine/__tests__/stepCharacterization.test.ts
@@ -0,0 +1,1420 @@
+/**
+ * Characterization tests for `engineStep` — the safety net for PLAN_MAINT #1
+ * (extracting the three inline pipelines out of the ~1,900-line function).
+ *
+ * These are deliberately NOT regression tests for known bugs (that is what
+ * `step.test.ts` is). They pin the *surface*: what the engine's state looks
+ * like after a fixed sequence of frames, which draw calls happen in which
+ * order, and — the part nobody had covered — what survives a mode switch.
+ * `engineStep`'s three pipelines share one `EngineState`, so "stale state
+ * leaking between pipelines" is the highest-value bug class here and the
+ * extraction is exactly the operation that could introduce or hide it.
+ *
+ * ## How these assert, and why
+ *
+ * Never on the argument tuple handed to a mocked draw function — those
+ * signatures are being converted to options objects. Assertions are on:
+ *   - `EngineState` field values after N deterministic frames (the richest
+ *     and most refactor-stable signal),
+ *   - which draw functions ran, how many times, and in what order,
+ *   - `StepOutput` fields,
+ *   - and, where one argument is genuinely load-bearing, that ONE argument.
+ *
+ * ## Determinism
+ *
+ * `engineStep` reads `Date.now()` (three sites, one per pipeline) and nothing
+ * else non-deterministic — no `Math.random` (the only randomness in the render
+ * path lives in `draw/orderbook` + `draw/particles`, both behind the mocked
+ * draw layer). `Date.now` is stubbed to a fake clock that advances in lockstep
+ * with `now_ms`, so every number below is reproducible.
+ */
+
+jest.mock('@shopify/react-native-skia', () => ({
+  Skia: {
+    PictureRecorder: jest.fn(),
+    XYWHRect: jest.fn(),
+  },
+}));
+
+jest.mock('../../draw', () => {
+  const actual = jest.requireActual('../../draw');
+  return {
+    ...actual,
+    drawFrame: jest.fn(),
+    drawMultiFrame: jest.fn(),
+    drawCandleFrame: jest.fn(),
+    drawEdgeFade: jest.fn(),
+  };
+});
+jest.mock('../../draw/loading', () => ({ drawLoading: jest.fn() }));
+jest.mock('../../draw/empty', () => ({ drawEmpty: jest.fn() }));
+jest.mock('../badge', () => ({ drawBadge: jest.fn() }));
+jest.mock('../gridLayer', () => ({ updateGridLayer: jest.fn() }));
+jest.mock('../lineScrollLayer', () => ({ updateLineScrollLayer: jest.fn() }));
+
+import type {
+  LivelinePoint,
+  LivelinePalette,
+  CandlePoint,
+  LivelineFonts,
+  DegenOptions,
+} from '../../types';
+import type { Ctx2D } from '../../draw/canvas2d';
+import type { EngineConfigStep } from '../types';
+import { createEngineState, type EngineState } from '../state';
+import { engineStep, type StepOutput } from '../step';
+import {
+  drawFrame,
+  drawMultiFrame,
+  drawCandleFrame,
+  drawEdgeFade,
+} from '../../draw';
+import { drawEmpty } from '../../draw/empty';
+import { drawLoading } from '../../draw/loading';
+import { drawBadge } from '../badge';
+import { updateGridLayer } from '../gridLayer';
+import { updateLineScrollLayer } from '../lineScrollLayer';
+import { writeLayoutKey } from '../../draw/pathCache';
+import type { ChartLayout } from '../../types';
+
+// ── Fixed world ──────────────────────────────────────────────────────────
+
+const W = 400;
+const H = 200;
+const PAD = { top: 10, right: 20, bottom: 20, left: 10 };
+const DT = 16;
+/** Wall clock origin. Chosen round so the derived timestamps below are exact
+ * in float64 and the golden numbers stay stable. */
+const START_MS = 1_700_000_000_000;
+const NOW_S = START_MS / 1000;
+/**
+ * One window width for every config AND for the initial `EngineState`, so no
+ * test here ever starts a window transition. That is deliberate: window
+ * transitions are already covered by `helpers.test.ts`, and leaving one
+ * running across a mode switch would smear its own lerp over the
+ * cross-pipeline state these tests are actually about.
+ */
+const WINDOW = 600;
+
+const PALETTE: LivelinePalette = {
+  line: '#3b82f6',
+  lineWidth: 2,
+  fillTop: 'rgba(59,130,246,0.3)',
+  fillBottom: 'rgba(59,130,246,0)',
+  dot: '#3b82f6',
+  dotRing: 'rgba(59,130,246,0.3)',
+  gridLine: '#222',
+  gridLabel: '#888',
+  badgeBg: '#3b82f6',
+  badgeText: '#fff',
+  up: '#22c55e',
+  down: '#ef4444',
+} as unknown as LivelinePalette;
+
+const PALETTE_B: LivelinePalette = {
+  ...PALETTE,
+  line: '#f59e0b',
+} as unknown as LivelinePalette;
+
+const FONTS = {} as unknown as LivelineFonts;
+
+/** Fake clock backing the stubbed `Date.now`. Advanced by the driver. */
+let clockMs = START_MS;
+
+function makeCtx(): Ctx2D {
+  return {
+    font: '',
+    fonts: { seriesLabel: 'label' },
+    measureText: () => ({ width: 10 }),
+  } as unknown as Ctx2D;
+}
+
+function makeCfg(over: Partial<EngineConfigStep> = {}): EngineConfigStep {
+  return {
+    value: 100,
+    palette: PALETTE,
+    windowSecs: WINDOW,
+    lerpSpeed: 0.15,
+    showGrid: false,
+    showBadge: false,
+    showMomentum: false,
+    showFill: false,
+    formatValue: (v: number) => v.toFixed(2),
+    formatTime: (t: number) => String(t),
+    padding: PAD,
+    hasOnHover: false,
+    showPulse: false,
+    scrub: false,
+    active: true,
+    exaggerate: false,
+    badgeTail: false,
+    badgeVariant: 'default' as EngineConfigStep['badgeVariant'],
+    tooltipY: 0,
+    tooltipOutline: false,
+    valueMomentumColor: false,
+    showValue: false,
+    noMotion: false,
+    mode: 'line',
+    dataRev: 1,
+    candlesRev: 1,
+    ...over,
+  } as EngineConfigStep;
+}
+
+function makeState(over: Partial<EngineState> = {}): EngineState {
+  const s = createEngineState(100, WINDOW, false, 60);
+  // Skip the reveal ramp — the golden sequences are about steady state, and
+  // chartReveal < 1 disables both the grid picture cache and the scroll layer.
+  s.chartReveal = 1;
+  Object.assign(s, over);
+  return s;
+}
+
+interface FrameArgs {
+  data?: LivelinePoint[];
+  candles?: CandlePoint[];
+  multiData?: Record<string, LivelinePoint[]>;
+  hoverX?: number | null;
+}
+
+/** One frame. Advances the fake clock by `DT` afterwards, so `now_ms` and
+ * `Date.now()` stay in lockstep exactly as they do in the real frame
+ * callback. */
+function frame(
+  s: EngineState,
+  cfg: EngineConfigStep,
+  args: FrameArgs = {}
+): StepOutput {
+  const out = engineStep(
+    makeCtx(),
+    cfg,
+    s,
+    W,
+    H,
+    args.hoverX ?? null,
+    DT,
+    clockMs,
+    FONTS,
+    args.data ?? [],
+    args.candles ?? [],
+    args.multiData ?? {}
+  );
+  clockMs += DT;
+  return out;
+}
+
+// ── Deterministic fixtures ───────────────────────────────────────────────
+
+/** `n` points ending exactly at `NOW_S - endAgo`, spanning `span` seconds,
+ * values walking a fixed ramp. No dependence on the real wall clock. */
+function linePoints(
+  n = 20,
+  span = 500,
+  endAgo = 0,
+  base = 100,
+  slope = 0.5
+): LivelinePoint[] {
+  const out: LivelinePoint[] = [];
+  for (let i = 0; i < n; i++) {
+    out.push({
+      time: NOW_S - endAgo - span + (i / (n - 1)) * span,
+      value: base + i * slope,
+    });
+  }
+  return out;
+}
+
+/** Five closed 60s candles ending one candle before `NOW_S`. */
+function closedCandles(): CandlePoint[] {
+  const out: CandlePoint[] = [];
+  for (let i = 5; i >= 1; i--) {
+    const o = 100 + i;
+    out.push({
+      time: NOW_S - i * 60,
+      open: o,
+      high: o + 2,
+      low: o - 1,
+      close: o + 1,
+    });
+  }
+  return out;
+}
+
+const LIVE_CANDLE: CandlePoint = {
+  time: NOW_S,
+  open: 101,
+  high: 108,
+  low: 99,
+  close: 106,
+};
+
+// ── Draw-mock call ordering ──────────────────────────────────────────────
+
+/** Every mocked draw entry point, by name. Deliberately keyed by *identity*
+ * of the call, never by arguments — the draw signatures are mid-conversion
+ * to options objects and argument tuples must not be pinned here. */
+function namedMocks(): [string, jest.Mock][] {
+  return [
+    ['drawFrame', drawFrame as unknown as jest.Mock],
+    ['drawMultiFrame', drawMultiFrame as unknown as jest.Mock],
+    ['drawCandleFrame', drawCandleFrame as unknown as jest.Mock],
+    ['drawEdgeFade', drawEdgeFade as unknown as jest.Mock],
+    ['drawLoading', drawLoading as unknown as jest.Mock],
+    ['drawEmpty', drawEmpty as unknown as jest.Mock],
+    ['drawBadge', drawBadge as unknown as jest.Mock],
+    ['updateGridLayer', updateGridLayer as unknown as jest.Mock],
+    ['updateLineScrollLayer', updateLineScrollLayer as unknown as jest.Mock],
+  ];
+}
+
+/**
+ * The flat sequence of draw-layer calls since the last `clearAllMocks`, in
+ * true invocation order (jest stamps every mock call with a process-global
+ * increasing id, so this is exact across different mocks).
+ */
+function callSequence(): string[] {
+  const events: { order: number; name: string }[] = [];
+  for (const [name, fn] of namedMocks()) {
+    for (const order of fn.mock.invocationCallOrder)
+      events.push({ order, name });
+  }
+  events.sort((a, b) => a.order - b.order);
+  return events.map((e) => e.name);
+}
+
+// ── State snapshots ──────────────────────────────────────────────────────
+
+/** Round to 6dp so the goldens are readable and not float-noise-sensitive. */
+const r = (n: number) => Math.round(n * 1e6) / 1e6;
+
+function commonSnapshot(s: EngineState) {
+  return {
+    displayMin: r(s.displayMin),
+    displayMax: r(s.displayMax),
+    displayWindow: r(s.displayWindow),
+    rangeInited: s.rangeInited,
+    chartReveal: r(s.chartReveal),
+    pauseProgress: r(s.pauseProgress),
+    timeDebt: r(s.timeDebt),
+    loadingAlpha: r(s.loadingAlpha),
+    scrubAmount: r(s.scrubAmount),
+    /** Offset from the clock origin, so the golden is a small number. */
+    frozenNowOffset: r(s.frozenNow - NOW_S),
+  };
+}
+
+function lineSnapshot(s: EngineState) {
+  return {
+    ...commonSnapshot(s),
+    displayValue: r(s.displayValue),
+    targetMin: r(s.targetMin),
+    targetMax: r(s.targetMax),
+    visibleLen: s.visibleScratch.length,
+    lastDataLen: s.lastData.length,
+    lastDataStashRev: s.lastDataStashRev,
+  };
+}
+
+function candleSnapshot(s: EngineState) {
+  const dc = s.displayCandle;
+  return {
+    ...commonSnapshot(s),
+    displayCandle: dc
+      ? {
+          open: r(dc.open),
+          high: r(dc.high),
+          low: r(dc.low),
+          close: r(dc.close),
+        }
+      : null,
+    liveBirthAlpha: r(s.liveBirthAlpha),
+    liveBull: r(s.liveBull),
+    lineSmoothClose: r(s.lineSmoothClose),
+    lineSmoothInited: s.lineSmoothInited,
+    closeLineSmooth: r(s.closeLineSmooth),
+    closeLineSmoothInited: s.closeLineSmoothInited,
+    lineModeProg: r(s.lineModeProg),
+    lineDensityProg: r(s.lineDensityProg),
+    prevCandleDataRev: s.prevCandleDataRev,
+    prevCandleWidth: s.prevCandleData.width,
+    cwtToWidth: s.candleWidthTrans.toWidth,
+    cwtOldWidth: s.candleWidthTrans.oldWidth,
+    visibleCandleLen: s.candleVisibleScratch.length,
+    lastCandlesLen: s.lastCandles.length,
+    hasLastLive: s.lastLive !== null,
+  };
+}
+
+function multiSnapshot(s: EngineState) {
+  return {
+    ...commonSnapshot(s),
+    targetMin: r(s.targetMin),
+    targetMax: r(s.targetMax),
+    displayValues: Object.fromEntries(
+      [...s.displayValues].map(([k, v]) => [k, r(v)])
+    ),
+    seriesAlpha: Object.fromEntries(
+      [...s.seriesAlpha].map(([k, v]) => [k, r(v)])
+    ),
+    multiVisibleIds: [...s.multiVisibleScratch.keys()].sort(),
+    multiEntryIds: [...s.multiSeriesEntryScratch.keys()].sort(),
+    seriesEntriesLen: s.seriesEntriesScratch.length,
+    lastMultiSeriesLen: s.lastMultiSeries.length,
+    stashDataIds: [...s.lastMultiStashData.keys()].sort(),
+  };
+}
+
+/** Every per-series map `engineStep` keys by series id, by size. `pruneByIds`
+ * (via `perSeriesMaps`) is supposed to empty all five together. */
+function perSeriesSizes(s: EngineState) {
+  return {
+    displayValues: s.displayValues.size,
+    seriesAlpha: s.seriesAlpha.size,
+    multiVisibleScratch: s.multiVisibleScratch.size,
+    multiSeriesEntryScratch: s.multiSeriesEntryScratch.size,
+    lineCaches: s.lineCaches.size,
+  };
+}
+
+// ── Config builders per pipeline ─────────────────────────────────────────
+
+const lineCfg = (over: Partial<EngineConfigStep> = {}) => makeCfg(over);
+
+const candleCfg = (over: Partial<EngineConfigStep> = {}) =>
+  makeCfg({
+    mode: 'candle',
+    candleWidth: 60,
+    liveCandle: LIVE_CANDLE,
+    ...over,
+  });
+
+const multiCfg = (
+  ids: string[],
+  over: Partial<EngineConfigStep> = {},
+  hidden?: string[]
+) => {
+  const revs: Record<string, number> = {};
+  for (const id of ids) revs[id] = 1;
+  return makeCfg({
+    isMultiSeries: true,
+    multiSeries: ids.map((id, i) => ({
+      id,
+      value: 100 + i * 10,
+      palette: i === 0 ? PALETTE : PALETTE_B,
+    })),
+    multiRevs: revs,
+    hiddenSeriesIds: hidden,
+    ...over,
+  });
+};
+
+const multiPoints = (ids: string[]): Record<string, LivelinePoint[]> => {
+  const out: Record<string, LivelinePoint[]> = {};
+  ids.forEach((id, i) => {
+    out[id] = linePoints(20, 500, 0, 100 + i * 10, 0.5 + i * 0.25);
+  });
+  return out;
+};
+
+beforeEach(() => {
+  clockMs = START_MS;
+  jest.clearAllMocks();
+  // clearAllMocks keeps implementations; the ordering tests install their own,
+  // so reset them explicitly to no-ops here.
+  (drawFrame as unknown as jest.Mock).mockImplementation(() => {});
+  (updateLineScrollLayer as unknown as jest.Mock).mockImplementation(() => {});
+  jest.spyOn(Date, 'now').mockImplementation(() => clockMs);
+});
+
+afterEach(() => {
+  jest.restoreAllMocks();
+});
+
+// ═════════════════════════════════════════════════════════════════════════
+// 1. Golden frame sequences, one per pipeline
+// ═════════════════════════════════════════════════════════════════════════
+
+describe('golden frame sequence: single-series line', () => {
+  it('reproduces the exact engine state after 5 frames', () => {
+    const s = makeState();
+    const cfg = lineCfg({ value: 120, showGrid: true, showBadge: true });
+    const data = linePoints();
+    for (let i = 0; i < 5; i++) frame(s, cfg, { data });
+
+    // Mutation caught: any change to the value lerp, the range lerp, the
+    // window buffer, the visible-point filter bounds or the stash revision
+    // gate moves at least one of these numbers.
+    expect(lineSnapshot(s)).toEqual({
+      displayMin: 98.830506,
+      displayMax: 110.915278,
+      displayWindow: 600,
+      rangeInited: true,
+      chartReveal: 1,
+      pauseProgress: 0,
+      timeDebt: 0,
+      loadingAlpha: 0,
+      scrubAmount: 0,
+      frozenNowOffset: 0.064,
+      displayValue: 111.018301,
+      targetMin: 98.677804,
+      targetMax: 112.340497,
+      visibleLen: 20,
+      lastDataLen: 20,
+      lastDataStashRev: 1,
+    });
+  });
+
+  it('reproduces the exact draw-call sequence for 2 frames', () => {
+    const s = makeState();
+    const cfg = lineCfg({ showGrid: true, showBadge: true });
+    const data = linePoints();
+    frame(s, cfg, { data });
+    frame(s, cfg, { data });
+
+    // Order is load-bearing: the grid picture is refreshed before the frame
+    // that composites it, and the badge is drawn into the same canvas after
+    // the chart so it sits on top.
+    expect(callSequence()).toEqual([
+      'updateGridLayer',
+      'drawFrame',
+      'drawBadge',
+      'updateGridLayer',
+      'drawFrame',
+      'drawBadge',
+    ]);
+    expect(drawEmpty).not.toHaveBeenCalled();
+    expect(drawLoading).not.toHaveBeenCalled();
+    expect(drawEdgeFade).not.toHaveBeenCalled();
+  });
+
+  it('publishes no scroll layer while the line cache is cold', () => {
+    // drawFrame is mocked, so it never builds `s.lineCache.prefix`; the gate
+    // must therefore never fire, and `scrollPicture` must stay null rather
+    // than going stale.
+    const s = makeState();
+    const cfg = lineCfg();
+    const data = linePoints();
+    const out = frame(s, cfg, { data });
+    expect(updateLineScrollLayer).not.toHaveBeenCalled();
+    expect(out.scrollPicture).toBeNull();
+    expect(out.scrollDx).toBe(0);
+  });
+
+  it('lerps the displayed value toward cfg.value across frames', () => {
+    // Mutation caught: swapping `pausedDt` for `dt`, or dropping the
+    // VALUE_SNAP_THRESHOLD snap, in the single-series value lerp.
+    const s = makeState({ displayValue: 100 });
+    const cfg = lineCfg({ value: 200 });
+    const data = linePoints();
+    const seen: number[] = [];
+    for (let i = 0; i < 3; i++) {
+      frame(s, cfg, { data });
+      seen.push(r(s.displayValue));
+    }
+    expect(seen).toEqual([114.442967, 126.79994, 137.3722]);
+  });
+});
+
+describe('golden frame sequence: candle', () => {
+  it('reproduces the exact engine state after 5 frames', () => {
+    const s = makeState();
+    const cfg = candleCfg({ showGrid: true });
+    const candles = closedCandles();
+    for (let i = 0; i < 5; i++) frame(s, cfg, { candles });
+
+    // Mutation caught: any change to the live-candle OHLC lerp, the
+    // bull/bear blend, the close-line smoothing, the candle range lerp, the
+    // width-transition bookkeeping or the reverse-morph stash.
+    expect(candleSnapshot(s)).toEqual({
+      displayMin: 99.003322,
+      displayMax: 107.880468,
+      displayWindow: 600,
+      rangeInited: true,
+      chartReveal: 1,
+      pauseProgress: 0,
+      timeDebt: 0,
+      loadingAlpha: 0,
+      scrubAmount: 0,
+      frozenNowOffset: 0.064,
+      displayCandle: {
+        open: 101,
+        high: 105.680314,
+        low: 99.662767,
+        close: 104.343081,
+      },
+      liveBirthAlpha: 0.657291,
+      liveBull: 0.729268,
+      lineSmoothClose: 106,
+      lineSmoothInited: true,
+      closeLineSmooth: 106,
+      closeLineSmoothInited: true,
+      lineModeProg: 0,
+      lineDensityProg: 0,
+      prevCandleDataRev: 1,
+      prevCandleWidth: 60,
+      cwtToWidth: 60,
+      cwtOldWidth: 60,
+      visibleCandleLen: 6,
+      lastCandlesLen: 6,
+      hasLastLive: true,
+    });
+  });
+
+  it('reproduces the exact draw-call sequence for 2 frames', () => {
+    const s = makeState();
+    const cfg = candleCfg({ showGrid: true, showBadge: true });
+    const candles = closedCandles();
+    frame(s, cfg, { candles });
+    frame(s, cfg, { candles });
+
+    // No drawBadge: the candle pipeline gates the badge on
+    // `lineModeProg > 0.5`, and this chart is not morphing to line mode.
+    // No drawEdgeFade either — that is an early-return-only call.
+    expect(callSequence()).toEqual([
+      'updateGridLayer',
+      'drawCandleFrame',
+      'updateGridLayer',
+      'drawCandleFrame',
+    ]);
+    expect(drawFrame).not.toHaveBeenCalled();
+    expect(drawBadge).not.toHaveBeenCalled();
+  });
+
+  it('never publishes a scroll layer', () => {
+    // The scroll layer is single-series-line-only. A refactor that hoists the
+    // gate above the pipeline split would break this.
+    const s = makeState();
+    const out = frame(s, candleCfg(), { candles: closedCandles() });
+    expect(out.scrollPicture).toBeNull();
+    expect(out.scrollDx).toBe(0);
+    expect(updateLineScrollLayer).not.toHaveBeenCalled();
+  });
+
+  it('drives the line-mode morph and draws the badge past the halfway point', () => {
+    // lineModeProg is advanced from `now_ms` (LINE_MORPH_MS), independent of
+    // dt, and the badge gate is `> 0.5`. Mutation caught: moving the
+    // lineModeProg update inside the pipeline (it currently runs before the
+    // loading/empty early return, on purpose) or changing the badge gate.
+    const s = makeState();
+    const candles = closedCandles();
+    const cfg = candleCfg({ lineMode: true, showBadge: true });
+    frame(s, cfg, { candles });
+    expect(r(s.lineModeProg)).toBe(0);
+    expect(drawBadge).not.toHaveBeenCalled();
+
+    // LINE_MORPH_MS is 500ms at the time of writing; jump the clock past its
+    // midpoint rather than hard-coding frame counts.
+    clockMs += 400;
+    frame(s, cfg, { candles });
+    expect(s.lineModeProg).toBeGreaterThan(0.5);
+    expect(drawBadge).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('golden frame sequence: multi-series', () => {
+  it('reproduces the exact engine state after 5 frames', () => {
+    const s = makeState();
+    const cfg = multiCfg(['a', 'b'], { showGrid: true });
+    const md = multiPoints(['a', 'b']);
+    for (let i = 0; i < 5; i++) frame(s, cfg, { multiData: md });
+
+    // Mutation caught: any change to the per-series value lerp, the series
+    // alpha ramp, the union range scan, the scratch-pool keying, or the
+    // stash revision gate.
+    expect(multiSnapshot(s)).toEqual({
+      displayMin: 98.86,
+      displayMax: 125.96,
+      displayWindow: 600,
+      rangeInited: true,
+      chartReveal: 1,
+      pauseProgress: 0,
+      timeDebt: 0,
+      loadingAlpha: 0,
+      scrubAmount: 0,
+      frozenNowOffset: 0.064,
+      targetMin: 98.86,
+      targetMax: 125.96,
+      displayValues: { a: 100, b: 110 },
+      seriesAlpha: { a: 1, b: 1 },
+      multiVisibleIds: ['a', 'b'],
+      multiEntryIds: ['a', 'b'],
+      seriesEntriesLen: 2,
+      lastMultiSeriesLen: 2,
+      stashDataIds: ['a', 'b'],
+    });
+  });
+
+  it('reproduces the exact draw-call sequence for 2 frames', () => {
+    const s = makeState();
+    const cfg = multiCfg(['a', 'b'], { showGrid: true, showBadge: true });
+    const md = multiPoints(['a', 'b']);
+    frame(s, cfg, { multiData: md });
+    frame(s, cfg, { multiData: md });
+
+    // No drawBadge at all: multi-series has no single value to badge. A
+    // refactor that shares one badge call across pipelines would fail here.
+    expect(callSequence()).toEqual([
+      'updateGridLayer',
+      'drawMultiFrame',
+      'updateGridLayer',
+      'drawMultiFrame',
+    ]);
+    expect(drawBadge).not.toHaveBeenCalled();
+    expect(drawFrame).not.toHaveBeenCalled();
+  });
+
+  it('never publishes a scroll layer', () => {
+    const s = makeState();
+    const out = frame(s, multiCfg(['a']), { multiData: multiPoints(['a']) });
+    expect(out.scrollPicture).toBeNull();
+    expect(out.scrollDx).toBe(0);
+    expect(updateLineScrollLayer).not.toHaveBeenCalled();
+  });
+
+  it('pools one visible array and one entry object per series, forever', () => {
+    // The scratch pools are keyed by series id and reused in place. Identity,
+    // not contents — a refactor that reallocates per frame would regress the
+    // allocation win the pools exist for and this catches it.
+    const s = makeState();
+    const cfg = multiCfg(['a', 'b']);
+    const md = multiPoints(['a', 'b']);
+    frame(s, cfg, { multiData: md });
+    const visA = s.multiVisibleScratch.get('a');
+    const entryA = s.multiSeriesEntryScratch.get('a');
+    frame(s, cfg, { multiData: md });
+    expect(s.multiVisibleScratch.get('a')).toBe(visA);
+    expect(s.multiSeriesEntryScratch.get('a')).toBe(entryA);
+  });
+});
+
+// ═════════════════════════════════════════════════════════════════════════
+// 2. Mode-transition matrix
+// ═════════════════════════════════════════════════════════════════════════
+
+/**
+ * The six transitions between the three pipelines. For each: run the outgoing
+ * pipeline to a settled state, switch, and assert both that the incoming
+ * pipeline produced correct output AND what the outgoing pipeline left behind.
+ *
+ * These deliberately pin the *current* behaviour including its leaks — the
+ * point of a characterization test is that the refactor reproduces today's
+ * engine exactly, whatever today's engine does. Where a leak is pinned it is
+ * called out in a comment so the refactor can decide to fix it on purpose
+ * rather than by accident.
+ */
+describe('mode transitions', () => {
+  /** Enough frames for every lerp in the pipeline to hit its snap threshold,
+   * so the "before" state of each transition is an exact, readable number
+   * rather than a point on a curve. */
+  const SETTLE = 200;
+  const settleLine = (s: EngineState, frames = SETTLE) => {
+    const cfg = lineCfg({ value: 120 });
+    const data = linePoints();
+    for (let i = 0; i < frames; i++) frame(s, cfg, { data });
+  };
+  const settleCandle = (s: EngineState, frames = SETTLE) => {
+    const cfg = candleCfg();
+    const candles = closedCandles();
+    for (let i = 0; i < frames; i++) frame(s, cfg, { candles });
+  };
+  const settleMulti = (s: EngineState, frames = SETTLE) => {
+    const cfg = multiCfg(['a', 'b']);
+    const md = multiPoints(['a', 'b']);
+    for (let i = 0; i < frames; i++) frame(s, cfg, { multiData: md });
+  };
+
+  it('line → candle: candle pipeline runs, line pipeline stops', () => {
+    const s = makeState();
+    settleLine(s);
+    expect(s.displayMax).toBe(122.4);
+    jest.clearAllMocks();
+
+    frame(s, candleCfg(), { candles: closedCandles() });
+
+    expect(callSequence()).toEqual(['drawCandleFrame']);
+    expect(drawFrame).not.toHaveBeenCalled();
+    // Candle state is now live.
+    expect(s.displayCandle).not.toBeNull();
+    expect(s.lastCandles.length).toBe(6);
+    expect(s.prevCandleDataRev).toBe(1);
+  });
+
+  it('line → candle: the range is NOT re-snapped, it lerps from the line range', () => {
+    // `rangeInited` is one shared flag across all three pipelines, so the
+    // candle pipeline inherits the line's displayMin/displayMax and lerps
+    // away from them instead of snapping to the candle range on frame 1.
+    // This is the single clearest instance of the shared-state coupling the
+    // refactor has to preserve (or deliberately change).
+    const s = makeState();
+    settleLine(s);
+    expect(s.rangeInited).toBe(true);
+    // The settled single-series range (padded by computeRange).
+    expect(s.displayMin).toBe(97.6);
+    expect(s.displayMax).toBe(122.4);
+
+    frame(s, candleCfg(), { candles: closedCandles() });
+
+    // The candle range settles at 97.92..109.08 (asserted directly in the
+    // candle→multi test below). A fresh `rangeInited === false` would snap
+    // straight there on this first frame; instead the range is still most of
+    // the way back at the line's, one lerp step in.
+    expect(s.displayMax).not.toBe(109.08);
+    expect(s.displayMax).toBeLessThan(122.4);
+    expect(s.displayMax).toBeGreaterThan(109.08);
+  });
+
+  it('line → candle: the line stash and displayValue survive the switch', () => {
+    // Nothing prunes single-series state on the way out — pinning it so the
+    // refactor cannot silently start (or stop) clearing it.
+    const s = makeState();
+    settleLine(s);
+    expect(s.lastData.length).toBe(20);
+    expect(s.displayValue).toBe(120);
+
+    frame(s, candleCfg(), { candles: closedCandles() });
+
+    expect(s.lastData.length).toBe(20);
+    expect(s.lastDataStashRev).toBe(1);
+    expect(s.displayValue).toBe(120);
+  });
+
+  it('candle → line: line pipeline runs, candle per-candle state persists', () => {
+    const s = makeState();
+    settleCandle(s);
+    const displayCandle = s.displayCandle;
+    expect(displayCandle).not.toBeNull();
+    jest.clearAllMocks();
+
+    frame(s, lineCfg({ value: 120 }), { data: linePoints() });
+
+    expect(callSequence()).toEqual(['drawFrame', 'drawBadge']);
+    expect(drawCandleFrame).not.toHaveBeenCalled();
+    // Candle state is frozen, not cleared: the candle pipeline is the only
+    // thing that writes it and it is no longer running.
+    expect(s.displayCandle).toBe(displayCandle);
+    expect(s.lastCandles.length).toBe(6);
+    expect(s.lastLive).not.toBeNull();
+    expect(s.lineSmoothInited).toBe(true);
+    expect(s.closeLineSmoothInited).toBe(true);
+    expect(s.prevCandleData.width).toBe(60);
+  });
+
+  it('candle → line: lineModeProg freezes rather than continuing to advance', () => {
+    // The lineModeProg block is inside `if (isCandle)`, above the early
+    // return. In line mode it does not run at all, so the morph freezes
+    // wherever it was. A refactor that lifts that block out of the isCandle
+    // guard would break this.
+    const s = makeState();
+    const candles = closedCandles();
+    const cfg = candleCfg({ lineMode: true });
+    frame(s, cfg, { candles });
+    clockMs += 200;
+    frame(s, cfg, { candles });
+    const mid = s.lineModeProg;
+    expect(mid).toBeGreaterThan(0);
+    expect(mid).toBeLessThan(1);
+
+    clockMs += 1000;
+    frame(s, lineCfg({ value: 120 }), { data: linePoints() });
+    expect(s.lineModeProg).toBe(mid);
+  });
+
+  it('line → multi: multi state is seeded fresh, line state persists', () => {
+    const s = makeState();
+    settleLine(s);
+    expect(perSeriesSizes(s)).toEqual({
+      displayValues: 0,
+      seriesAlpha: 0,
+      multiVisibleScratch: 0,
+      multiSeriesEntryScratch: 0,
+      lineCaches: 0,
+    });
+    jest.clearAllMocks();
+
+    frame(s, multiCfg(['a', 'b']), { multiData: multiPoints(['a', 'b']) });
+
+    expect(callSequence()).toEqual(['drawMultiFrame']);
+    // Seeded from cfg on the first multi frame, not from the line pipeline.
+    expect([...s.displayValues.keys()].sort()).toEqual(['a', 'b']);
+    expect(s.seriesAlpha.get('a')).toBe(1);
+    expect(s.seriesAlpha.get('b')).toBe(1);
+    // The single-series stash is untouched by the multi pipeline.
+    expect(s.lastData.length).toBe(20);
+    expect(s.displayValue).toBe(120);
+  });
+
+  it('multi → line: every per-series map is emptied on the first line frame', () => {
+    const s = makeState();
+    settleMulti(s);
+    expect(perSeriesSizes(s)).toEqual({
+      displayValues: 2,
+      seriesAlpha: 2,
+      multiVisibleScratch: 2,
+      multiSeriesEntryScratch: 2,
+      lineCaches: 0,
+    });
+    jest.clearAllMocks();
+
+    frame(s, lineCfg({ value: 120 }), { data: linePoints() });
+
+    // Mutation caught: dropping any map from `perSeriesMaps`, or moving the
+    // `!inMultiPipeline` prune below the loading/empty early return.
+    expect(perSeriesSizes(s)).toEqual({
+      displayValues: 0,
+      seriesAlpha: 0,
+      multiVisibleScratch: 0,
+      multiSeriesEntryScratch: 0,
+      lineCaches: 0,
+    });
+    expect(callSequence()).toEqual(['drawFrame', 'drawBadge']);
+  });
+
+  it('multi → line: the reverse-morph stash is cleared but its rev cache is not', () => {
+    // `lastMultiSeries` is emptied by the `hasData && !isMultiSeries` clear;
+    // `lastMultiStashData`/`lastMultiStashRevs` are deliberately excluded
+    // from `perSeriesMaps` and nothing else touches them, so they survive.
+    // Pinned because it is exactly the kind of asymmetry an extraction can
+    // accidentally "tidy up".
+    const s = makeState();
+    settleMulti(s);
+    expect(s.lastMultiSeries.length).toBe(2);
+    expect([...s.lastMultiStashData.keys()].sort()).toEqual(['a', 'b']);
+
+    frame(s, lineCfg({ value: 120 }), { data: linePoints() });
+
+    expect(s.lastMultiSeries).toEqual([]);
+    expect([...s.lastMultiStashData.keys()].sort()).toEqual(['a', 'b']);
+    expect([...s.lastMultiStashRevs.keys()].sort()).toEqual(['a', 'b']);
+  });
+
+  it('candle → multi: multi runs, candle state persists, no candle draw', () => {
+    const s = makeState();
+    settleCandle(s);
+    const lastCandles = s.lastCandles;
+    jest.clearAllMocks();
+
+    frame(s, multiCfg(['a', 'b']), { multiData: multiPoints(['a', 'b']) });
+
+    expect(callSequence()).toEqual(['drawMultiFrame']);
+    expect(s.displayValues.size).toBe(2);
+    expect(s.lastCandles).toBe(lastCandles);
+    expect(s.displayCandle).not.toBeNull();
+  });
+
+  it('candle → multi: the multi range lerps from the candle range, not a snap', () => {
+    // Same shared `rangeInited` coupling as line → candle, in the other
+    // direction and through the *other* range updater (`updateRange` rather
+    // than `updateCandleRange`) — both read the one flag.
+    const s = makeState();
+    settleCandle(s);
+    expect(s.displayMin).toBe(97.92);
+    expect(s.displayMax).toBe(109.08);
+
+    frame(s, multiCfg(['a', 'b']), { multiData: multiPoints(['a', 'b']) });
+
+    // The multi range settles at 98.86..125.96 (asserted directly in the
+    // multi golden above). A snap would land exactly there on this frame.
+    expect(s.displayMax).not.toBe(125.96);
+    expect(s.displayMax).toBeGreaterThan(109.08);
+    expect(s.displayMax).toBeLessThan(125.96);
+  });
+
+  it('multi → candle: per-series maps are pruned even with isMultiSeries still set', () => {
+    const s = makeState();
+    settleMulti(s);
+    expect(perSeriesSizes(s).displayValues).toBe(2);
+    jest.clearAllMocks();
+
+    // `isMultiSeries`/`multiSeries` deliberately left set — `mode: 'candle'`
+    // alone takes the chart out of the multi pipeline, and the prune's
+    // `!isCandle` term is what makes that work.
+    frame(
+      s,
+      candleCfg({
+        isMultiSeries: true,
+        multiSeries: [{ id: 'a', value: 100, palette: PALETTE }],
+      }),
+      { candles: closedCandles() }
+    );
+
+    expect(perSeriesSizes(s)).toEqual({
+      displayValues: 0,
+      seriesAlpha: 0,
+      multiVisibleScratch: 0,
+      multiSeriesEntryScratch: 0,
+      lineCaches: 0,
+    });
+    expect(callSequence()).toEqual(['drawCandleFrame']);
+  });
+
+  it('multi → candle: lastMultiSeries survives (only single-series data clears it)', () => {
+    // The `hasData && !cfg.isMultiSeries` clear lives in the non-candle
+    // branch of the stash block, so it never runs in candle mode.
+    const s = makeState();
+    settleMulti(s);
+    expect(s.lastMultiSeries.length).toBe(2);
+
+    frame(s, candleCfg(), { candles: closedCandles() });
+
+    expect(s.lastMultiSeries.length).toBe(2);
+  });
+
+  it('round trip line → multi → line leaves no per-series residue', () => {
+    // The accumulation case PLAN_MAINT #3 is about: a chart that oscillates
+    // between modes must not grow its per-series maps.
+    const s = makeState();
+    settleLine(s);
+    settleMulti(s);
+    settleLine(s);
+    expect(perSeriesSizes(s)).toEqual({
+      displayValues: 0,
+      seriesAlpha: 0,
+      multiVisibleScratch: 0,
+      multiSeriesEntryScratch: 0,
+      lineCaches: 0,
+    });
+
+    // ...and a different series set on the way back in does not resurrect
+    // the old ids.
+    frame(s, multiCfg(['c']), { multiData: multiPoints(['c']) });
+    expect([...s.displayValues.keys()]).toEqual(['c']);
+    expect([...s.seriesAlpha.keys()]).toEqual(['c']);
+  });
+
+  it("every transition publishes the incoming pipeline's own readout", () => {
+    // `valueText: null` means "leave unchanged" to the caller, so each
+    // pipeline must write its own on a mode switch or the readout freezes on
+    // the previous mode's number. One assertion per direction.
+    const s = makeState();
+    const data = linePoints();
+    const md = multiPoints(['a', 'b']);
+    const candles = closedCandles();
+    const V = { showValue: true };
+
+    let line = frame(s, lineCfg({ ...V, value: 120 }), { data });
+    for (let i = 0; i < 40; i++) {
+      line = frame(s, lineCfg({ ...V, value: 120 }), { data });
+    }
+    expect(line.valueText).toBe('120.00');
+
+    const candle = frame(s, candleCfg(V), { candles });
+    expect(candle.valueText).toBe('106.00');
+
+    const multi = frame(s, multiCfg(['a', 'b'], V), { multiData: md });
+    expect(multi.valueText).toBe('');
+
+    const backToLine = frame(s, lineCfg({ ...V, value: 120 }), { data });
+    expect(backToLine.valueText).toBe('120.00');
+
+    const backToCandle = frame(s, candleCfg(V), { candles });
+    expect(backToCandle.valueText).toBe('106.00');
+
+    const multiFromCandle = frame(s, multiCfg(['a', 'b'], V), {
+      multiData: md,
+    });
+    expect(multiFromCandle.valueText).toBe('');
+  });
+});
+
+// ═════════════════════════════════════════════════════════════════════════
+// 3. Ordering invariants
+// ═════════════════════════════════════════════════════════════════════════
+
+/**
+ * Prime the single-series line-path cache the way the real `drawFrame` would,
+ * so the scroll-layer gate can actually fire under the mocked draw layer.
+ * Reads only `layout` (arg 1) and the two options-object fields the gate's
+ * key is built from — no positional tuple is assumed beyond `ctx, layout`,
+ * which is not being changed.
+ */
+const FAKE_PREFIX = { fake: 'prefix' };
+const FAKE_PICTURE = { fake: 'picture' };
+
+function primeLineCache(s: EngineState) {
+  (drawFrame as unknown as jest.Mock).mockImplementation(
+    (
+      _ctx: unknown,
+      layout: ChartLayout,
+      _palette: unknown,
+      opts: {
+        visible: LivelinePoint[];
+        lineCache: { dataRev: number; dataSource: number };
+      }
+    ) => {
+      const slot = s.lineCache;
+      const vis = opts.visible;
+      slot.prefix = FAKE_PREFIX as never;
+      slot.kDataRev = opts.lineCache.dataRev;
+      slot.kDataSource = opts.lineCache.dataSource;
+      slot.kLen = vis.length;
+      slot.kFirstT = vis[0]!.time;
+      slot.kLastT = vis[vis.length - 1]!.time;
+      slot.kLastV = vis[vis.length - 1]!.value;
+      writeLayoutKey(slot.layoutKey, layout);
+    }
+  );
+  (updateLineScrollLayer as unknown as jest.Mock).mockImplementation(() => {
+    s.lineScroll.picture = FAKE_PICTURE as never;
+  });
+}
+
+describe('ordering invariants (single-series scroll-layer gate)', () => {
+  const scrollCfg = (over: Partial<EngineConfigStep> = {}) =>
+    lineCfg({ scrub: true, value: 120, noMotion: true, ...over });
+
+  it('composites the scroll layer once the line cache is warm', () => {
+    // Baseline for the two ordering tests below: without this passing, their
+    // "not called" assertions would be vacuous.
+    const s = makeState();
+    primeLineCache(s);
+    const data = linePoints();
+    const cfg = scrollCfg();
+
+    const first = frame(s, cfg, { data });
+    expect(updateLineScrollLayer).not.toHaveBeenCalled();
+    expect(first.scrollPicture).toBeNull();
+
+    const second = frame(s, cfg, { data });
+    expect(updateLineScrollLayer).toHaveBeenCalledTimes(1);
+    expect(second.scrollPicture).toBe(FAKE_PICTURE);
+    expect(typeof second.scrollDx).toBe('number');
+  });
+
+  it("runs the gate AFTER updateHoverState — it reads this frame's settled scrubAmount", () => {
+    // Mutation caught: moving the `canCompositeLineScroll` block above the
+    // `updateHoverState` call. It would then read the *previous* frame's
+    // scrubAmount (0 here) and composite a layer on a frame where the scrub
+    // draws the line twice under two clips — a visible tear.
+    const s = makeState();
+    primeLineCache(s);
+    const data = linePoints();
+    const cfg = scrollCfg();
+
+    frame(s, cfg, { data });
+    frame(s, cfg, { data });
+    expect(updateLineScrollLayer).toHaveBeenCalledTimes(1);
+    expect(s.scrubAmount).toBe(0);
+
+    // Hover starts THIS frame. Pre-frame scrubAmount is 0; updateHoverState
+    // settles it to 1 (noMotion). The gate must see the 1.
+    const hovered = frame(s, cfg, { data, hoverX: 200 });
+    expect(s.scrubAmount).toBe(1);
+    expect(updateLineScrollLayer).toHaveBeenCalledTimes(1);
+    expect(hovered.scrollPicture).toBeNull();
+    expect(hovered.scrollDx).toBe(0);
+  });
+
+  it('runs the gate BEFORE drawFrame — it reads the pre-decay shake amplitude', () => {
+    // `drawFrame` zeroes `shakeState.amplitude` below its own threshold, so
+    // the gate reading it *after* the draw would see 0 on a frame that is in
+    // fact translated, and composite a scroll layer that tears away from the
+    // rest of the chart. The mocked drawFrame stands in for that decay.
+    const s = makeState();
+    primeLineCache(s);
+    const decaying = (
+      drawFrame as unknown as jest.Mock
+    ).getMockImplementation()!;
+    (drawFrame as unknown as jest.Mock).mockImplementation(
+      (...args: never[]) => {
+        decaying(...args);
+        s.shakeState.amplitude = 0;
+      }
+    );
+
+    const data = linePoints();
+    const cfg = scrollCfg({
+      degenOptions: { enabled: true } as unknown as DegenOptions,
+    });
+
+    frame(s, cfg, { data });
+    const control = frame(s, cfg, { data });
+    expect(control.scrollPicture).toBe(FAKE_PICTURE);
+    expect(updateLineScrollLayer).toHaveBeenCalledTimes(1);
+
+    // A shaking frame: amplitude is non-zero going in, zeroed by drawFrame.
+    s.shakeState.amplitude = 5;
+    const shaking = frame(s, cfg, { data });
+    expect(s.shakeState.amplitude).toBe(0);
+    expect(updateLineScrollLayer).toHaveBeenCalledTimes(1);
+    expect(shaking.scrollPicture).toBeNull();
+  });
+
+  it('ignores the shake amplitude entirely when degenOptions is off', () => {
+    // The gate passes `cfg.degenOptions ? amplitude : 0` — a stale amplitude
+    // from a chart that used to have degen mode on must not permanently
+    // disable the scroll layer.
+    const s = makeState({ shakeState: { amplitude: 5, angle: 0 } as never });
+    primeLineCache(s);
+    const data = linePoints();
+    const cfg = scrollCfg();
+
+    frame(s, cfg, { data });
+    const out = frame(s, cfg, { data });
+    expect(out.scrollPicture).toBe(FAKE_PICTURE);
+  });
+});
+
+describe('ordering invariants (grid layer)', () => {
+  /** The `dt` argument index in `updateGridLayer(slot, state, layout,
+   * palette, formatValue, dt, cache, fonts)`. Asserted by index rather than
+   * by tuple so a signature change elsewhere in the call does not break it. */
+  const DT_ARG = 5;
+
+  const pausedState = () => makeState({ pauseProgress: 1, timeDebt: 0 });
+
+  it('hands the grid layer pausedDt, not raw dt, in every pipeline', () => {
+    // Mutation caught: replacing `pausedDt` with `dt` at any of the three
+    // updateGridLayer call sites. `gridState`'s label crossfades must freeze
+    // with the pause, and two of the three sites got this wrong historically.
+    const cases: [string, () => void][] = [
+      [
+        'line',
+        () => {
+          const s = pausedState();
+          frame(s, lineCfg({ showGrid: true, paused: true, value: 120 }), {
+            data: linePoints(),
+          });
+        },
+      ],
+      [
+        'candle',
+        () => {
+          const s = pausedState();
+          frame(s, candleCfg({ showGrid: true, paused: true }), {
+            candles: closedCandles(),
+          });
+        },
+      ],
+      [
+        'multi',
+        () => {
+          const s = pausedState();
+          frame(s, multiCfg(['a', 'b'], { showGrid: true, paused: true }), {
+            multiData: multiPoints(['a', 'b']),
+          });
+        },
+      ],
+    ];
+
+    for (const [name, run] of cases) {
+      jest.clearAllMocks();
+      run();
+      const mock = updateGridLayer as unknown as jest.Mock;
+      expect(mock).toHaveBeenCalledTimes(1);
+      // pauseProgress is pinned at 1, so pausedDt === 0 while dt === 16.
+      expect([name, mock.mock.calls[0]![DT_ARG]]).toEqual([name, 0]);
+    }
+  });
+
+  it('skips the grid picture cache entirely while the reveal morph runs', () => {
+    // `chartReveal >= 1` gates all three call sites — ctx.drawPicture ignores
+    // globalAlpha, so a cached picture would snap to full opacity mid-fade.
+    const s = makeState({ chartReveal: 0.5 });
+    frame(s, lineCfg({ showGrid: true, value: 120 }), { data: linePoints() });
+    expect(updateGridLayer).not.toHaveBeenCalled();
+    expect(drawFrame).toHaveBeenCalledTimes(1);
+  });
+
+  it('runs the grid layer before the frame draw in all three pipelines', () => {
+    // Note the line pipeline's trailing `drawBadge`: it is called
+    // unconditionally there (the badge decides its own visibility inside),
+    // unlike candle mode, which gates the call on `lineModeProg > 0.5`.
+    const cases: [string, () => void, string[]][] = [
+      [
+        'line',
+        () => {
+          const s = makeState();
+          frame(s, lineCfg({ showGrid: true, value: 120 }), {
+            data: linePoints(),
+          });
+        },
+        ['updateGridLayer', 'drawFrame', 'drawBadge'],
+      ],
+      [
+        'candle',
+        () => {
+          const s = makeState();
+          frame(s, candleCfg({ showGrid: true }), { candles: closedCandles() });
+        },
+        ['updateGridLayer', 'drawCandleFrame'],
+      ],
+      [
+        'multi',
+        () => {
+          const s = makeState();
+          frame(s, multiCfg(['a', 'b'], { showGrid: true }), {
+            multiData: multiPoints(['a', 'b']),
+          });
+        },
+        ['updateGridLayer', 'drawMultiFrame'],
+      ],
+    ];
+    for (const [name, run, expected] of cases) {
+      jest.clearAllMocks();
+      run();
+      expect([name, callSequence()]).toEqual([name, expected]);
+    }
+  });
+});
+
+describe('per-pipeline window buffer', () => {
+  /**
+   * The right-edge buffer (how much empty room the chart leaves past `now`,
+   * as a fraction of the window) is chosen independently by each of the three
+   * pipelines and lands nowhere on `EngineState` — the only observable is the
+   * `layout` handed to the draw call. So this reads ONE thing off ONE
+   * argument: `layout.rightEdge`, at the argument index the layout has always
+   * occupied (`ctx, layout, …`). Nothing about the options object is touched.
+   *
+   * `s.frozenNow` is exactly the `now` the layout was built from on a
+   * non-stash frame, so `rightEdge - frozenNow` recovers `windowSecs *
+   * buffer` without the test needing its own clock arithmetic.
+   */
+  const bufferOf = (mock: unknown, s: EngineState) => {
+    const calls = (mock as jest.Mock).mock.calls;
+    const layout = calls[calls.length - 1]![1] as ChartLayout;
+    return r((layout.rightEdge - s.frozenNow) / WINDOW);
+  };
+
+  it('single-series line: 0.05 with a badge, 0.015 without', () => {
+    // Mutation caught: swapping WINDOW_BUFFER / WINDOW_BUFFER_NO_BADGE in the
+    // line pipeline. Nothing in EngineState moves when that happens.
+    const data = linePoints();
+    const withBadge = makeState();
+    frame(withBadge, lineCfg({ showBadge: true }), { data });
+    expect(bufferOf(drawFrame, withBadge)).toBe(0.05);
+
+    const without = makeState();
+    frame(without, lineCfg({ showBadge: false }), { data });
+    expect(bufferOf(drawFrame, without)).toBe(0.015);
+  });
+
+  it('single-series line: widens to fit momentum arrows next to the badge', () => {
+    // `max(baseBuffer, 37 / chartW)` — chartW is 370 here, so 0.1 wins.
+    const s = makeState();
+    frame(s, lineCfg({ showBadge: true, showMomentum: true }), {
+      data: linePoints(),
+    });
+    expect(bufferOf(drawFrame, s)).toBe(0.1);
+  });
+
+  it('multi-series: same badge-driven choice as single-series', () => {
+    const md = multiPoints(['a', 'b']);
+    const withBadge = makeState();
+    frame(withBadge, multiCfg(['a', 'b'], { showBadge: true }), {
+      multiData: md,
+    });
+    expect(bufferOf(drawMultiFrame, withBadge)).toBe(0.05);
+
+    const without = makeState();
+    frame(without, multiCfg(['a', 'b'], { showBadge: false }), {
+      multiData: md,
+    });
+    expect(bufferOf(drawMultiFrame, without)).toBe(0.015);
+
+    // ...but NOT the momentum-arrow widening, which is single-series only.
+    const arrows = makeState();
+    frame(
+      arrows,
+      multiCfg(['a', 'b'], { showBadge: true, showMomentum: true }),
+      { multiData: md }
+    );
+    expect(bufferOf(drawMultiFrame, arrows)).toBe(0.05);
+  });
+
+  it('candle: always the no-badge buffer, even with showBadge on', () => {
+    // The badge is only ever visible during the line morph, so the candle
+    // pipeline hard-codes CANDLE_BUFFER_NO_BADGE rather than reading
+    // cfg.showBadge at all.
+    const candles = closedCandles();
+    const withBadge = makeState();
+    frame(withBadge, candleCfg({ showBadge: true }), { candles });
+    expect(bufferOf(drawCandleFrame, withBadge)).toBe(0.015);
+
+    const without = makeState();
+    frame(without, candleCfg({ showBadge: false }), { candles });
+    expect(bufferOf(drawCandleFrame, without)).toBe(0.015);
+  });
+});
+
+describe('ordering invariants (per-pipeline dt contract)', () => {
+  /** Read one property off the options object rather than the whole tuple —
+   * the tuple is being reshaped, this property is not. */
+  const optsDt = (mock: unknown) => {
+    const calls = (mock as jest.Mock).mock.calls;
+    const last = calls[calls.length - 1]!;
+    return (last[last.length - 1] as { dt: number }).dt;
+  };
+
+  it('line and candle draw with pausedDt; multi draws with raw dt', () => {
+    // A real asymmetry in today's engine, not an accident of these tests:
+    // drawFrame and drawCandleFrame are handed `pausedDt` (their orderbook /
+    // grid sub-drawers must freeze with the pause) while drawMultiFrame gets
+    // raw `dt`. Pinned so an extraction that unifies the three call sites has
+    // to change this test on purpose.
+    const data = linePoints();
+    const candles = closedCandles();
+    const md = multiPoints(['a', 'b']);
+
+    const sLine = makeState({ pauseProgress: 1 });
+    frame(sLine, lineCfg({ paused: true, value: 120 }), { data });
+    expect(optsDt(drawFrame)).toBe(0);
+
+    const sCandle = makeState({ pauseProgress: 1 });
+    frame(sCandle, candleCfg({ paused: true }), { candles });
+    expect(optsDt(drawCandleFrame)).toBe(0);
+
+    const sMulti = makeState({ pauseProgress: 1 });
+    frame(sMulti, multiCfg(['a', 'b'], { paused: true }), { multiData: md });
+    expect(optsDt(drawMultiFrame)).toBe(DT);
+  });
+});
+
+// ═════════════════════════════════════════════════════════════════════════
+// 4. Shared early-return surface
+// ═════════════════════════════════════════════════════════════════════════
+
+describe('early returns', () => {
+  it('the no-data return draws empty + edge fade and nothing else, in order', () => {
+    const s = makeState({ chartReveal: 0 });
+    const out = frame(s, lineCfg({ showGrid: true, showBadge: true }));
+
+    expect(callSequence()).toEqual(['drawEmpty', 'drawEdgeFade']);
+    expect(out.scrollPicture).toBeNull();
+    // The prune runs ABOVE this return on purpose (so "multiSeries went
+    // empty" is covered); nothing else does.
+    expect(updateGridLayer).not.toHaveBeenCalled();
+  });
+
+  it('the multi "no visible series" return draws empty + edge fade, in order', () => {
+    const s = makeState();
+    const out = frame(s, multiCfg(['a'], { showValue: true }), {
+      multiData: { a: [] },
+    });
+    expect(callSequence()).toEqual(['drawEmpty', 'drawEdgeFade']);
+    expect(out.valueText).toBe('');
+    expect(drawMultiFrame).not.toHaveBeenCalled();
+  });
+
+  it('the single-series "no points in window" return draws empty + edge fade', () => {
+    const s = makeState();
+    const out = frame(s, lineCfg({ showValue: true, showGrid: true }), {
+      data: linePoints(20, 10, 100_000),
+    });
+    expect(callSequence()).toEqual(['drawEmpty', 'drawEdgeFade']);
+    expect(out.valueText).toBe('');
+    expect(drawFrame).not.toHaveBeenCalled();
+  });
+
+  it('crossfades loading over empty rather than picking one', () => {
+    // Both are drawn while loadingAlpha sits between the two thresholds, and
+    // loading is drawn first (it composites under the empty text).
+    const s = makeState({ loadingAlpha: 0.5, chartReveal: 0 });
+    frame(s, lineCfg({ loading: true }));
+    expect(callSequence()).toEqual([
+      'drawLoading',
+      'drawEmpty',
+      'drawEdgeFade',
+    ]);
+  });
+});

From 7f7c953a086f45445e0bbc916c50df3568f01427 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Mon, 3 Aug 2026 08:36:32 -0400
Subject: [PATCH 36/37] refactor: options structs for the widest signatures
 (PLAN_MAINT #4)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Not cosmetic — this width already blocked real work. A pooled-decimation
optimisation was REVERTED rather than add a 17th positional parameter to
drawLine. At 15 parameters, adjacent same-typed arguments are silently
swappable and the compiler cannot help; drawLine alone passed six consecutive
numbers.

  drawLine          15 -> 4     lineCacheHits        8 -> 3
  drawCandlesticks  15 -> 3     updateLinePaths     13 -> 7
  engineStep        12 -> 4     updateHoverState    12 -> 7
  updateRange       12 -> 7     updateWindowTrans   11 -> 8
  updateCandleCache 10 -> 8     paintLineCurve      12 -> 10

Two mechanisms, chosen per function. Where the parameters were a genuine bag
of unrelated per-frame values: a POOLED args struct on EngineState, created
once in createEngineState and overwritten in place — the precedent
multiSeriesEntryScratch already sets. Where the list was re-deriving fields of
an object the function already received: just pass that object.

The naive version of this change would have been a regression. These run
60-120x/sec on the UI thread, so an options object allocated per call is
exactly the per-frame allocation this codebase pools paints, paths and rects
to avoid. Net effect is the opposite: THREE per-frame object literals removed
(two in step.ts, plus one per visible series per frame in drawMultiFrame),
zero added. Verified by scanning every added non-test line for object/array
literals — the only ones are in the create* functions, which run once per
chart.

Behaviour-preserving, and that is verified rather than asserted: the 42
characterization tests added in bd9b693 pass unchanged. They pin EngineState
values, draw-call counts and call ORDER across all three pipelines, so a
behavioural drift would have shown. Re-confirmed they still have teeth after
the signature change by mutating one pausedDt to dt and watching exactly the
grid-dt test fail.

Non-mechanical bits worth knowing:
- lineCacheHits now derives its key from `visible`, so it indexes it. The
  short-circuit order was restructured so the null-prefix and length/rev
  checks run BEFORE any indexing — an empty array can never reach the index.
- FrameInputs moved to engine/types.ts: defining it in step.ts made state.ts
  import from step.ts, which imports state.ts at runtime. Type-only so it was
  erased, but not a cycle worth leaving for a bundler to trip over.
- s.lineCacheRef and s.lineDrawArgs are now shared across all three pipelines.
  Safe because exactly one pipeline draws per frame and every call site writes
  ALL fields before calling — checked at each of the three drawLine sites and
  both drawCandlesticks sites, and documented on the fields.
- One test got structurally WEAKER and was strengthened rather than accepted:
  lineCache.test.ts asserted kLen by passing an impossible length once the key
  is derived. Replaced with an extra INTERIOR point (same first/last), which
  isolates kLen exactly, plus three previously-untested derived fields.

Deliberately left: updateCandleWindowTransition (19) and updateCandleRange
(14) in candleHelpers.ts — the worst offenders, but out of the scope given.
The WindowTransInputs/RangeInputs pattern ports directly and they are the
obvious next increment.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/draw/__tests__/candleCache.test.ts        |  16 +-
 src/draw/__tests__/candlestick.test.ts        | 101 +++++--
 src/draw/__tests__/lineCache.test.ts          | 172 +++--------
 src/draw/candleCache.ts                       |  13 +-
 src/draw/candlestick.ts                       | 118 ++++++--
 src/draw/index.ts                             | 207 +++++++------
 src/draw/line.ts                              | 195 +++++++-----
 src/draw/lineCache.ts                         |  86 +++---
 src/engine/__tests__/helpers.test.ts          | 286 ++++++++++--------
 src/engine/__tests__/step.test.ts             |  25 +-
 .../__tests__/stepCharacterization.test.ts    |  29 +-
 src/engine/helpers.ts                         |  73 +++--
 src/engine/state.ts                           |  70 ++++-
 src/engine/step.ts                            | 113 +++----
 src/engine/types.ts                           |  42 +++
 src/useLivelineEngine.ts                      |  28 +-
 16 files changed, 892 insertions(+), 682 deletions(-)

diff --git a/src/draw/__tests__/candleCache.test.ts b/src/draw/__tests__/candleCache.test.ts
index a8c9eba..77be648 100644
--- a/src/draw/__tests__/candleCache.test.ts
+++ b/src/draw/__tests__/candleCache.test.ts
@@ -173,16 +173,14 @@ function update(
 ): boolean {
   const { bodyW, radius } = candleDims(layout, candleWidthSecs);
   return updateCandleCache(
-    hz.slot,
+    { slot: hz.slot, dataSource, candlesRev },
     hz.makePath,
     layout,
     candles,
     candleWidthSecs,
     liveTime,
     bodyW,
-    radius,
-    dataSource,
-    candlesRev
+    radius
   );
 }
 
@@ -388,31 +386,27 @@ describe('updateCandleCache', () => {
     const hz = makeHarness();
     expect(
       updateCandleCache(
-        hz.slot,
+        { slot: hz.slot, dataSource: 0, candlesRev: 0 },
         hz.makePath,
         layout,
         candles,
         4,
         liveTime,
         bodyW,
-        1.5,
-        0,
-        0
+        1.5
       )
     ).toBe(true);
     expect((hz.slot.bullBodies as FakePath).rewinds).toBe(1);
 
     expect(
       updateCandleCache(
-        hz.slot,
+        { slot: hz.slot, dataSource: 0, candlesRev: 0 },
         hz.makePath,
         layout,
         candles,
         4,
         liveTime,
         bodyW,
-        0,
-        0,
         0
       )
     ).toBe(true);
diff --git a/src/draw/__tests__/candlestick.test.ts b/src/draw/__tests__/candlestick.test.ts
index c416773..0c17996 100644
--- a/src/draw/__tests__/candlestick.test.ts
+++ b/src/draw/__tests__/candlestick.test.ts
@@ -1,4 +1,8 @@
-import { drawCandlesticks } from '../candlestick';
+import {
+  drawCandlesticks,
+  createCandleDrawArgs,
+  type CandleDrawArgs,
+} from '../candlestick';
 import type { Ctx2D, Style2D } from '../canvas2d';
 import type { ChartLayout, CandlePoint, Padding } from '../../types';
 
@@ -134,6 +138,13 @@ function makeCandles(count: number, t0 = 10): CandlePoint[] {
   return out;
 }
 
+/** Build a `CandleDrawArgs` from the factory defaults plus the fields a test
+ * actually varies. Production pools one instance on `EngineState`; a test
+ * allocating one per call is fine and keeps each case self-describing. */
+function args(over: Partial<CandleDrawArgs>): CandleDrawArgs {
+  return Object.assign(createCandleDrawArgs(), over);
+}
+
 describe('drawCandlesticks batching', () => {
   it('batches a mixed bull/bear set into a handful of fill/stroke calls, not one per candle', () => {
     const ctx = new FakeCtx();
@@ -142,13 +153,13 @@ describe('drawCandlesticks batching', () => {
     drawCandlesticks(
       ctx,
       layout,
-      candles,
-      4,
-      -1, // liveTime — no candle matches, so there's no "live" candle this frame
-      0,
-      0, // pauseProgress
-      0,
-      0 // scrubX=0, scrubDim=0 — no scrub, batching applies
+      args({
+        candles,
+        candleWidthSecs: 4,
+        // no candle matches, so there's no "live" candle this frame
+        liveTime: -1,
+        // scrubX=0, scrubDim=0 — no scrub, batching applies
+      })
     );
 
     const fills = ctx.calls.filter((c) => c.op === 'fill');
@@ -167,7 +178,17 @@ describe('drawCandlesticks batching', () => {
     const liveTime = candles[candles.length - 1]!.time;
     // pauseProgress=1 suppresses the live-candle glow (tested separately
     // below) so the fill count here is exactly batched-groups + live-body.
-    drawCandlesticks(ctx, layout, candles, 4, liveTime, 0, 1, 0, 0, 1, 0.5);
+    drawCandlesticks(
+      ctx,
+      layout,
+      args({
+        candles,
+        candleWidthSecs: 4,
+        liveTime,
+        pauseProgress: 1,
+        liveBullBlend: 0.5,
+      })
+    );
 
     const fills = ctx.calls.filter((c) => c.op === 'fill');
     // 9 non-live candles (5 bull, 4 bear) → 2 batched body fills, plus the
@@ -185,30 +206,26 @@ describe('drawCandlesticks batching', () => {
     drawCandlesticks(
       active,
       layout,
-      candles,
-      4,
-      liveTime,
-      0,
-      0 /* pauseProgress */,
-      0,
-      0,
-      1,
-      0.5
+      args({
+        candles,
+        candleWidthSecs: 4,
+        liveTime,
+        pauseProgress: 0,
+        liveBullBlend: 0.5,
+      })
     );
 
     const paused = new FakeCtx();
     drawCandlesticks(
       paused,
       layout,
-      candles,
-      4,
-      liveTime,
-      0,
-      1 /* pauseProgress */,
-      0,
-      0,
-      1,
-      0.5
+      args({
+        candles,
+        candleWidthSecs: 4,
+        liveTime,
+        pauseProgress: 1,
+        liveBullBlend: 0.5,
+      })
     );
 
     const activeFills = active.calls.filter((c) => c.op === 'fill').length;
@@ -221,7 +238,11 @@ describe('drawCandlesticks batching', () => {
     const layout = makeLayout();
     // Window is [0,100]; put every candle far outside it.
     const candles = makeCandles(5, 10000);
-    drawCandlesticks(ctx, layout, candles, 4, -1, 0, 0, 0, 0);
+    drawCandlesticks(
+      ctx,
+      layout,
+      args({ candles, candleWidthSecs: 4, liveTime: -1 })
+    );
     expect(ctx.calls.length).toBe(0);
   });
 
@@ -230,7 +251,17 @@ describe('drawCandlesticks batching', () => {
     const layout = makeLayout();
     const candles = makeCandles(6);
     // scrubX > 0 and scrubDim > 0.01 activates the per-candle fallback path.
-    drawCandlesticks(ctx, layout, candles, 4, -1, 0, 0, 50, 0.5);
+    drawCandlesticks(
+      ctx,
+      layout,
+      args({
+        candles,
+        candleWidthSecs: 4,
+        liveTime: -1,
+        scrubX: 50,
+        scrubDim: 0.5,
+      })
+    );
 
     const fills = ctx.calls.filter((c) => c.op === 'fill');
     // One fill per (visible) non-live candle — not batched.
@@ -241,7 +272,17 @@ describe('drawCandlesticks batching', () => {
     const ctx = new FakeCtx();
     const layout = makeLayout();
     const candles = makeCandles(6);
-    drawCandlesticks(ctx, layout, candles, 4, -1, 0, 0, 50, 0.8);
+    drawCandlesticks(
+      ctx,
+      layout,
+      args({
+        candles,
+        candleWidthSecs: 4,
+        liveTime: -1,
+        scrubX: 50,
+        scrubDim: 0.8,
+      })
+    );
 
     const fillAlphas = ctx.calls
       .filter((c) => c.op === 'fill')
diff --git a/src/draw/__tests__/lineCache.test.ts b/src/draw/__tests__/lineCache.test.ts
index 71bd997..68d3869 100644
--- a/src/draw/__tests__/lineCache.test.ts
+++ b/src/draw/__tests__/lineCache.test.ts
@@ -161,21 +161,29 @@ function update(
 ): boolean {
   const pts = buildPts(data, layout, smoothValue, now);
   return updateLinePaths(
-    hz.slot,
+    { slot: hz.slot, dataRev, dataSource },
     hz.makePath,
     layout,
     data,
     pts,
     wantFill,
-    dataRev,
-    dataSource,
-    data.length,
-    data[0]!.time,
-    data[data.length - 1]!.time,
-    data[data.length - 1]!.value
+    data
   );
 }
 
+/** `lineCacheHits` against a harness slot. The data-identity half of the key
+ * is derived from `data` itself now, so a test varies a key field by varying
+ * the points it passes. */
+function hits(
+  hz: Harness,
+  layout: ChartLayout,
+  data: LivelinePoint[],
+  dataRev = 0,
+  dataSource = 0
+): boolean {
+  return lineCacheHits({ slot: hz.slot, dataRev, dataSource }, layout, data);
+}
+
 // ── Tests ──────────────────────────────────────────────────────────────────
 
 describe('updateLinePaths', () => {
@@ -382,9 +390,7 @@ describe('lineCacheHits', () => {
   it('is false on a fresh slot (no prefix built yet)', () => {
     const hz = makeHarness();
     const layout = makeLayout(NOW, 90, 110);
-    expect(
-      lineCacheHits(hz.slot, layout, 0, 0, N, NOW - 30, NOW - 1, 100)
-    ).toBe(false);
+    expect(hits(hz, layout, makeData(N, NOW - 30))).toBe(false);
   });
 
   it('is true right after a build, with the same key inputs', () => {
@@ -394,18 +400,7 @@ describe('lineCacheHits', () => {
     const layout = makeLayout(NOW, 90, 110);
     expect(update(hz, layout, data, smooth, NOW)).toBe(true);
 
-    expect(
-      lineCacheHits(
-        hz.slot,
-        layout,
-        0,
-        0,
-        data.length,
-        data[0]!.time,
-        data[data.length - 1]!.time,
-        data[data.length - 1]!.value
-      )
-    ).toBe(true);
+    expect(hits(hz, layout, data)).toBe(true);
   });
 
   it('stays true at a later `now` with an unchanged layout/data (pure time advance)', () => {
@@ -415,18 +410,7 @@ describe('lineCacheHits', () => {
     update(hz, makeLayout(NOW, 90, 110), data, smooth, NOW);
 
     const laterLayout = makeLayout(NOW + 4.2, 90, 110);
-    expect(
-      lineCacheHits(
-        hz.slot,
-        laterLayout,
-        0,
-        0,
-        data.length,
-        data[0]!.time,
-        data[data.length - 1]!.time,
-        data[data.length - 1]!.value
-      )
-    ).toBe(true);
+    expect(hits(hz, laterLayout, data)).toBe(true);
   });
 
   it('is false when any key input changes (dataRev, dataSource, range, window, size, len)', () => {
@@ -436,64 +420,37 @@ describe('lineCacheHits', () => {
     const layout = makeLayout(NOW, 90, 110);
     update(hz, layout, data, smooth, NOW);
 
-    const firstT = data[0]!.time;
     const lastT = data[data.length - 1]!.time;
     const lastV = data[data.length - 1]!.value;
 
-    expect(
-      lineCacheHits(hz.slot, layout, 1, 0, data.length, firstT, lastT, lastV)
-    ).toBe(false); // dataRev
-    expect(
-      lineCacheHits(hz.slot, layout, 0, 1, data.length, firstT, lastT, lastV)
-    ).toBe(false); // dataSource
-    expect(
-      lineCacheHits(
-        hz.slot,
-        makeLayout(NOW, 89, 110),
-        0,
-        0,
-        data.length,
-        firstT,
-        lastT,
-        lastV
-      )
-    ).toBe(false); // range min
-    expect(
-      lineCacheHits(
-        hz.slot,
-        makeLayout(NOW, 90, 110, 120),
-        0,
-        0,
-        data.length,
-        firstT,
-        lastT,
-        lastV
-      )
-    ).toBe(false); // window
-    expect(
-      lineCacheHits(
-        hz.slot,
-        makeLayout(NOW, 90, 110, 60, 500),
-        0,
-        0,
-        data.length,
-        firstT,
-        lastT,
-        lastV
-      )
-    ).toBe(false); // canvas size
-    expect(
-      lineCacheHits(
-        hz.slot,
-        layout,
-        0,
-        0,
-        data.length + 1,
-        firstT,
-        lastT,
-        lastV
-      )
-    ).toBe(false); // len
+    expect(hits(hz, layout, data, 1, 0)).toBe(false); // dataRev
+    expect(hits(hz, layout, data, 0, 1)).toBe(false); // dataSource
+    expect(hits(hz, makeLayout(NOW, 89, 110), data)).toBe(false); // range min
+    expect(hits(hz, makeLayout(NOW, 90, 110, 120), data)).toBe(false); // window
+    expect(hits(hz, makeLayout(NOW, 90, 110, 60, 500), data)).toBe(false); // size
+
+    // len, isolated: one extra INTERIOR point, so firstT/lastT/lastV are all
+    // unchanged and only kLen can be doing the invalidating.
+    const oneLonger = [
+      ...data.slice(0, -1),
+      { time: lastT - 0.5, value: lastV },
+      data[data.length - 1]!,
+    ];
+    expect(hits(hz, layout, oneLonger)).toBe(false); // len
+
+    // The three point-derived fields, one at a time.
+    const firstMoved = [
+      { time: data[0]!.time - 1, value: data[0]!.value },
+      ...data.slice(1),
+    ];
+    expect(hits(hz, layout, firstMoved)).toBe(false); // firstT
+    const lastMoved = [...data.slice(0, -1), { time: lastT + 1, value: lastV }];
+    expect(hits(hz, layout, lastMoved)).toBe(false); // lastT
+    const lastRevalued = [
+      ...data.slice(0, -1),
+      { time: lastT, value: lastV + 1 },
+    ];
+    expect(hits(hz, layout, lastRevalued)).toBe(false); // lastV
   });
 
   it('is allocation-free and read-only (no new paths, slot untouched)', () => {
@@ -505,16 +462,7 @@ describe('lineCacheHits', () => {
     const madeAfterBuild = hz.made.length;
     const prefixVerbsBefore = (hz.slot.prefix as FakePath).verbs.length;
 
-    lineCacheHits(
-      hz.slot,
-      layout,
-      0,
-      0,
-      data.length,
-      data[0]!.time,
-      data[data.length - 1]!.time,
-      data[data.length - 1]!.value
-    );
+    hits(hz, layout, data);
 
     expect(hz.made.length).toBe(madeAfterBuild);
     expect((hz.slot.prefix as FakePath).verbs.length).toBe(prefixVerbsBefore);
@@ -549,18 +497,7 @@ describe('assembleLineTail (fast path)', () => {
     // branch does, without ever constructing decimated/pts.
     const fast = makeHarness();
     update(fast, buildLayout, data, smooth, NOW, true);
-    expect(
-      lineCacheHits(
-        fast.slot,
-        laterLayout,
-        0,
-        0,
-        data.length,
-        data[0]!.time,
-        data[data.length - 1]!.time,
-        data[data.length - 1]!.value
-      )
-    ).toBe(true);
+    expect(hits(fast, laterLayout, data)).toBe(true);
 
     const pts = buildPts(data, laterLayout, smooth, later);
     const madeBeforeAssemble = fast.made.length;
@@ -703,18 +640,7 @@ describe('split stroke (prefix / tail)', () => {
     for (let f = 1; f <= 200; f++) {
       const t = NOW + f * 0.0167;
       const layout = makeLayout(t, 90, 110);
-      expect(
-        lineCacheHits(
-          hz.slot,
-          layout,
-          0,
-          0,
-          data.length,
-          data[0]!.time,
-          data[data.length - 1]!.time,
-          data[data.length - 1]!.value
-        )
-      ).toBe(true);
+      expect(hits(hz, layout, data)).toBe(true);
       const pts = buildPts(data, layout, smooth, t);
       assembleLineTail(
         hz.slot,
diff --git a/src/draw/candleCache.ts b/src/draw/candleCache.ts
index 4ae4350..7ff409e 100644
--- a/src/draw/candleCache.ts
+++ b/src/draw/candleCache.ts
@@ -190,18 +190,23 @@ function roundedRectOnPath(
  * upstream conditions gate that.
  */
 export function updateCandleCache(
-  slot: CandleCacheSlot,
+  /** Slot + this frame's data-identity inputs (revision, backing array).
+   * Taken as the whole ref the caller already holds rather than as three
+   * loose arguments, so the slot can never be paired with another frame's
+   * revision by a mis-ordered call. */
+  ref: CandleCacheRef,
   makePath: () => CachePath,
   layout: ChartLayout,
   candles: CandlePoint[],
   candleWidthSecs: number,
   liveTime: number,
   bodyW: number,
-  radius: number,
-  dataSource: number,
-  candlesRev: number
+  radius: number
 ): boolean {
   'worklet';
+  const slot = ref.slot;
+  const dataSource = ref.dataSource;
+  const candlesRev = ref.candlesRev;
   // Scan closed-candle identity (no allocation): count + first/last time.
   let closedCount = 0;
   let firstClosedTime = 0;
diff --git a/src/draw/candlestick.ts b/src/draw/candlestick.ts
index c4f0250..0c67118 100644
--- a/src/draw/candlestick.ts
+++ b/src/draw/candlestick.ts
@@ -27,6 +27,73 @@ const EMPTY_DASH: number[] = [];
 const BULL_RGB = [34, 197, 94] as const;
 const BEAR_RGB = [239, 68, 68] as const;
 
+/**
+ * Everything `drawCandlesticks` needs beyond `ctx` and `layout`.
+ *
+ * **Pooled, not allocated per call** — same contract as `LineDrawArgs` in
+ * draw/line.ts, and for the same reason: this runs on the UI thread every
+ * frame, and it previously took thirteen positional arguments of which eight
+ * were consecutive numbers. One instance lives on `EngineState`
+ * (`createCandleDrawArgs`) and callers overwrite fields in place.
+ */
+export interface CandleDrawArgs {
+  candles: CandlePoint[];
+  /** Candle period in seconds — drives body width and the X of each body. */
+  candleWidthSecs: number;
+  /** `time` of the currently-forming candle, or -1 for none. */
+  liveTime: number;
+  /** `performance.now()` — drives the live candle's pulse. */
+  now_ms: number;
+  /** 0 = playing, 1 = fully paused; gates the live pulse off. */
+  pauseProgress: number;
+  /** Scrub cursor X in px (0 when not scrubbing). */
+  scrubX: number;
+  /** 0 = not scrubbing, 1 = fully scrubbing. Non-zero disables batching. */
+  scrubDim: number;
+  /** Alpha for the live candle only (birth fade-in). */
+  liveAlpha: number;
+  /** Bear→bull blend for the live candle, or -1 to use its own direction. */
+  liveBullBlend: number;
+  /** Accent color to blend candle colors toward during the line-mode morph. */
+  accentColor?: string;
+  /** How much of `accentColor` to mix in (0 = none). */
+  accentBlend: number;
+  /** Cross-frame cache for closed-candle body+wick geometry (see
+   * draw/candleCache.ts). Only consulted along the canBatch fast path —
+   * caller must not set this during scrub-dimming (canBatch is already
+   * false then), candle-width morph, mid line-mode-morph, or the reveal
+   * OHLC-collapse window; see draw/index.ts's drawCandleFrame for where
+   * those bypasses are wired. */
+  cache?: CandleCacheRef;
+  /** Real SkPath factory, supplied by the caller so this Skia-adjacent-but-
+   * import-free module never imports the real `Skia` object itself (this
+   * file is exercised directly by candlestick.test.ts under jest, which
+   * can't parse @shopify/react-native-skia's ESM build — see draw/index.ts,
+   * which owns the runtime import, same as line.ts does for the line cache). */
+  makePath?: () => CachePath;
+}
+
+/** Allocate one pooled `CandleDrawArgs`. Defaults match the old positional
+ * defaults, so callers only write the fields they actually vary. */
+export function createCandleDrawArgs(): CandleDrawArgs {
+  'worklet';
+  return {
+    candles: [],
+    candleWidthSecs: 0,
+    liveTime: -1,
+    now_ms: 0,
+    pauseProgress: 0,
+    scrubX: 0,
+    scrubDim: 0,
+    liveAlpha: 1,
+    liveBullBlend: -1,
+    accentColor: undefined,
+    accentBlend: 0,
+    cache: undefined,
+    makePath: undefined,
+  };
+}
+
 /** Blend bear→bull by t (0=bear, 1=bull), as an RGB tuple — lets a caller
  * (the live candle) combine this with a further accent blend without a
  * lossy SkColor→RGB round-trip. */
@@ -182,34 +249,23 @@ function candleSpatialDim(
 export function drawCandlesticks(
   ctx: Ctx2D,
   layout: ChartLayout,
-  candles: CandlePoint[],
-  candleWidthSecs: number,
-  liveTime: number,
-  now_ms: number,
-  pauseProgress: number,
-  scrubX: number,
-  scrubDim: number,
-  liveAlpha: number = 1,
-  liveBullBlend: number = -1,
-  accentColor?: string,
-  accentBlend: number = 0,
-  /** Cross-frame cache for closed-candle body+wick geometry (see
-   * draw/candleCache.ts). Only consulted along the canBatch fast path —
-   * caller must not pass this during scrub-dimming (canBatch is already
-   * false then), candle-width morph, mid line-mode-morph, or the reveal
-   * OHLC-collapse window; see draw/index.ts's drawCandleFrame for where
-   * those bypasses are wired. */
-  cache?: CandleCacheRef,
-  /** Real SkPath factory, supplied by the caller so this Skia-adjacent-but-
-   * import-free module never imports the real `Skia` object itself (this
-   * file is exercised directly by candlestick.test.ts under jest, which
-   * can't parse @shopify/react-native-skia's ESM build — see draw/index.ts,
-   * which owns the runtime import, same as line.ts does for the line cache). */
-  makePath?: () => CachePath
+  /** Pooled per-frame inputs — see `CandleDrawArgs`. Read synchronously and
+   * never retained, so a caller drawing two candle sets in one frame (the
+   * width-morph cross-fade) may refill and reuse one instance. */
+  a: CandleDrawArgs
 ) {
   'worklet';
+  const candles = a.candles;
   if (candles.length === 0) return;
 
+  const candleWidthSecs = a.candleWidthSecs;
+  const liveTime = a.liveTime;
+  const scrubX = a.scrubX;
+  const scrubDim = a.scrubDim;
+  const liveAlpha = a.liveAlpha;
+  const liveBullBlend = a.liveBullBlend;
+  const accentColor = a.accentColor;
+  const accentBlend = a.accentBlend;
   const { toX, toY } = layout;
   const { bodyW, wickW, radius } = candleDims(layout, candleWidthSecs);
   const halfBody = bodyW / 2;
@@ -220,8 +276,10 @@ export function drawCandlesticks(
   // threshold the dot's pulse ring uses (draw/index.ts) — without this,
   // this Math.sin(now_ms) term never settles, and candle mode could never
   // reach quiescence (see engine/quiescence.ts).
-  const showLivePulse = pauseProgress < 0.5;
-  const livePulse = showLivePulse ? 0.12 + Math.sin(now_ms * 0.004) * 0.08 : 0;
+  const showLivePulse = a.pauseProgress < 0.5;
+  const livePulse = showLivePulse
+    ? 0.12 + Math.sin(a.now_ms * 0.004) * 0.08
+    : 0;
   const baseAlpha = ctx.globalAlpha;
   const hasAccent = !!accentColor && accentBlend > 0.01;
   const canBatch = !(scrubDim > 0.01 && scrubX > 0);
@@ -240,20 +298,20 @@ export function drawCandlesticks(
     ctx.lineCap = 'round';
     ctx.lineWidth = wickW;
 
+    const cache = a.cache;
+    const makePath = a.makePath;
     const cacheReady =
       cache !== undefined &&
       makePath !== undefined &&
       updateCandleCache(
-        cache.slot,
+        cache,
         makePath,
         layout,
         candles,
         candleWidthSecs,
         liveTime,
         bodyW,
-        radius,
-        cache.dataSource,
-        cache.candlesRev
+        radius
       );
 
     if (cacheReady) {
diff --git a/src/draw/index.ts b/src/draw/index.ts
index 15148eb..cb15ba2 100644
--- a/src/draw/index.ts
+++ b/src/draw/index.ts
@@ -12,7 +12,7 @@ import { Skia, type SkPicture } from '@shopify/react-native-skia';
 import type { Ctx2D } from './canvas2d';
 import { drawGrid, type GridState } from './grid';
 import type { GridLayerSlot } from './gridLayer';
-import { drawLine } from './line';
+import { drawLine, type LineDrawArgs } from './line';
 import { lineOverlayPresence, LINE_OVERLAY_MIN_PRESENCE } from './lineOverlay';
 import {
   createLineCacheSlot,
@@ -29,6 +29,7 @@ import { drawOrderbook, type OrderbookState } from './orderbook';
 import { drawParticles, spawnOnSwing, type ParticleState } from './particles';
 import {
   drawCandlesticks,
+  type CandleDrawArgs,
   drawClosePrice,
   drawCandleCrosshair,
   drawLineModeCrosshair,
@@ -169,6 +170,9 @@ export interface DrawOptions {
   lineCache?: LineCacheRef;
   /** Cross-frame grid picture cache (see draw/gridLayer, engine/gridLayer) */
   gridLayer?: GridLayerSlot<SkPicture>;
+  /** Pooled scratch struct this frame's `drawLine` call is filled into —
+   * owned by `EngineState`, never allocated here. See `LineDrawArgs`. */
+  lineArgs: LineDrawArgs;
 }
 
 /**
@@ -250,23 +254,20 @@ export function drawFrame(
 
   // 3. Line + fill (with scrub dimming + reveal morphing)
   const scrubX = opts.scrubAmount > 0.05 ? opts.hoverX : null;
-  const pts = drawLine(
-    ctx,
-    layout,
-    palette,
-    opts.visible,
-    opts.smoothValue,
-    opts.now,
-    opts.showFill,
-    scrubX,
-    opts.scrubAmount,
-    reveal,
-    opts.now_ms,
-    1,
-    false,
-    1,
-    opts.lineCache
-  );
+  const lineArgs = opts.lineArgs;
+  lineArgs.visible = opts.visible;
+  lineArgs.smoothValue = opts.smoothValue;
+  lineArgs.now = opts.now;
+  lineArgs.showFill = opts.showFill;
+  lineArgs.scrubX = scrubX;
+  lineArgs.scrubAmount = opts.scrubAmount;
+  lineArgs.chartReveal = reveal;
+  lineArgs.now_ms = opts.now_ms;
+  lineArgs.colorBlend = 1;
+  lineArgs.skipDashLine = false;
+  lineArgs.fillScale = 1;
+  lineArgs.pathCache = opts.lineCache;
+  const pts = drawLine(ctx, layout, palette, lineArgs);
 
   // 4. Time axis — same timing as grid
   {
@@ -444,6 +445,14 @@ export interface MultiSeriesDrawOptions {
   multiDataSource?: number;
   /** Cross-frame grid picture cache (see draw/gridLayer, engine/gridLayer) */
   gridLayer?: GridLayerSlot<SkPicture>;
+  /** Pooled scratch struct the per-series `drawLine` calls are filled into —
+   * owned by `EngineState`, refilled once per series, never allocated here.
+   * See `LineDrawArgs`. */
+  lineArgs: LineDrawArgs;
+  /** Pooled `LineCacheRef` for the per-series cache lookup, same deal — its
+   * `slot` is repointed each iteration instead of allocating a ref per
+   * series per frame. Omit to disable the per-series cache entirely. */
+  lineCacheRef?: LineCacheRef;
 }
 
 /**
@@ -511,37 +520,37 @@ export function drawMultiFrame(
     // interior revision invalidates just that series' cache — the key's
     // len/firstT/lastT/lastV heuristic can't see interior changes on its own.
     let cacheRef: LineCacheRef | undefined;
-    if (opts.lineCaches !== undefined) {
+    if (opts.lineCaches !== undefined && opts.lineCacheRef !== undefined) {
       let slot = opts.lineCaches.get(s.id);
       if (slot === undefined) {
         slot = createLineCacheSlot();
         opts.lineCaches.set(s.id, slot);
       }
-      cacheRef = {
-        slot,
-        dataRev: s.dataRev,
-        dataSource: opts.multiDataSource ?? 0,
-      };
+      // Pooled ref (see MultiSeriesDrawOptions.lineCacheRef) repointed at
+      // this series' slot, rather than a fresh literal per series per frame.
+      // Safe because `drawLine` reads it synchronously and retains nothing.
+      cacheRef = opts.lineCacheRef;
+      cacheRef.slot = slot;
+      cacheRef.dataRev = s.dataRev;
+      cacheRef.dataSource = opts.multiDataSource ?? 0;
+      cacheRef.splitPrefixStroke = false;
     }
     ctx.save();
     if (combinedAlpha < 1) ctx.globalAlpha = combinedAlpha;
-    const pts = drawLine(
-      ctx,
-      layout,
-      s.palette,
-      s.visible,
-      s.smoothValue,
-      opts.now,
-      false, // no fill
-      scrubX,
-      opts.scrubAmount,
-      reveal,
-      opts.now_ms,
-      1,
-      false,
-      1,
-      cacheRef
-    );
+    const lineArgs = opts.lineArgs;
+    lineArgs.visible = s.visible;
+    lineArgs.smoothValue = s.smoothValue;
+    lineArgs.now = opts.now;
+    lineArgs.showFill = false; // no fill
+    lineArgs.scrubX = scrubX;
+    lineArgs.scrubAmount = opts.scrubAmount;
+    lineArgs.chartReveal = reveal;
+    lineArgs.now_ms = opts.now_ms;
+    lineArgs.colorBlend = 1;
+    lineArgs.skipDashLine = false;
+    lineArgs.fillScale = 1;
+    lineArgs.pathCache = cacheRef;
+    const pts = drawLine(ctx, layout, s.palette, lineArgs);
     ctx.restore();
     if (pts && pts.length > 0) {
       allPts.push({
@@ -707,6 +716,13 @@ export interface CandleDrawOptions {
    * line-mode morph in progress — see the gating right before the
    * drawCandlesticks call in the `else` branch. */
   candleCache?: CandleCacheRef;
+  /** Pooled scratch struct this frame's `drawLine` call is filled into —
+   * owned by `EngineState`, never allocated here. See `LineDrawArgs`. */
+  lineArgs: LineDrawArgs;
+  /** Pooled scratch struct the `drawCandlesticks` calls are filled into —
+   * refilled between the two halves of the width-morph cross-fade. See
+   * `CandleDrawArgs`. */
+  candleArgs: CandleDrawArgs;
 }
 
 /**
@@ -757,22 +773,21 @@ export function drawCandleFrame(
     const scrubX = opts.scrubAmount > 0.05 ? opts.hoverX : null;
     ctx.save();
     ctx.globalAlpha = lp;
-    linePts = drawLine(
-      ctx,
-      layout,
-      palette,
-      opts.lineVisible,
-      opts.lineSmoothValue,
-      opts.now,
-      opts.lineModeProg > 0.01,
-      scrubX,
-      opts.scrubAmount,
-      opts.chartReveal,
-      opts.now_ms,
-      colorBlend,
-      !fullLineMode,
-      opts.lineModeProg // fillScale — fill fades smoothly with line mode transition
-    );
+    const lineArgs = opts.lineArgs;
+    lineArgs.visible = opts.lineVisible;
+    lineArgs.smoothValue = opts.lineSmoothValue;
+    lineArgs.now = opts.now;
+    lineArgs.showFill = opts.lineModeProg > 0.01;
+    lineArgs.scrubX = scrubX;
+    lineArgs.scrubAmount = opts.scrubAmount;
+    lineArgs.chartReveal = opts.chartReveal;
+    lineArgs.now_ms = opts.now_ms;
+    lineArgs.colorBlend = colorBlend;
+    lineArgs.skipDashLine = !fullLineMode;
+    // fill fades smoothly with the line mode transition
+    lineArgs.fillScale = opts.lineModeProg;
+    lineArgs.pathCache = undefined;
+    linePts = drawLine(ctx, layout, palette, lineArgs);
     ctx.restore();
   }
 
@@ -847,39 +862,32 @@ export function drawCandleFrame(
     ctx.save();
     ctx.clipRect(pad.left - 1, pad.top, chartW + 2, chartH);
     const accentCol = lp > LINE_OVERLAY_MIN_PRESENCE ? palette.line : undefined;
+    // Fields shared by every drawCandlesticks call below; the per-call
+    // differences are written immediately before each call.
+    const ca = opts.candleArgs;
+    ca.now_ms = opts.now_ms;
+    ca.pauseProgress = opts.pauseProgress;
+    ca.scrubX = opts.hoverX ?? 0;
+    ca.scrubDim = opts.scrubAmount;
+    ca.accentColor = accentCol;
+    ca.accentBlend = lp;
+    ca.cache = undefined;
+    ca.makePath = undefined;
     if (opts.morphT >= 0 && revealOld.length > 0) {
       ctx.globalAlpha = (1 - opts.morphT) * candleAlpha;
-      drawCandlesticks(
-        ctx,
-        layout,
-        revealOld,
-        opts.oldWidth,
-        -1,
-        opts.now_ms,
-        opts.pauseProgress,
-        opts.hoverX ?? 0,
-        opts.scrubAmount,
-        1,
-        -1,
-        accentCol,
-        lp
-      );
+      ca.candles = revealOld;
+      ca.candleWidthSecs = opts.oldWidth;
+      ca.liveTime = -1;
+      ca.liveAlpha = 1;
+      ca.liveBullBlend = -1;
+      drawCandlesticks(ctx, layout, ca);
       ctx.globalAlpha = opts.morphT * candleAlpha;
-      drawCandlesticks(
-        ctx,
-        layout,
-        revealCandles,
-        opts.displayCandleWidth,
-        opts.liveCandle?.time ?? -1,
-        opts.now_ms,
-        opts.pauseProgress,
-        opts.hoverX ?? 0,
-        opts.scrubAmount,
-        opts.liveBirthAlpha,
-        opts.liveBullBlend,
-        accentCol,
-        lp
-      );
+      ca.candles = revealCandles;
+      ca.candleWidthSecs = opts.displayCandleWidth;
+      ca.liveTime = opts.liveCandle?.time ?? -1;
+      ca.liveAlpha = opts.liveBirthAlpha;
+      ca.liveBullBlend = opts.liveBullBlend;
+      drawCandlesticks(ctx, layout, ca);
       ctx.globalAlpha = 1;
     } else {
       if (candleAlpha < 1) ctx.globalAlpha = candleAlpha;
@@ -898,23 +906,14 @@ export function drawCandleFrame(
         opts.candleCache && revealCandles === opts.candles && lineModeSettled
           ? opts.candleCache
           : undefined;
-      drawCandlesticks(
-        ctx,
-        layout,
-        revealCandles,
-        opts.displayCandleWidth,
-        opts.liveCandle?.time ?? -1,
-        opts.now_ms,
-        opts.pauseProgress,
-        opts.hoverX ?? 0,
-        opts.scrubAmount,
-        opts.liveBirthAlpha,
-        opts.liveBullBlend,
-        accentCol,
-        lp,
-        candleCache,
-        candleCache ? makeCandlePath : undefined
-      );
+      ca.candles = revealCandles;
+      ca.candleWidthSecs = opts.displayCandleWidth;
+      ca.liveTime = opts.liveCandle?.time ?? -1;
+      ca.liveAlpha = opts.liveBirthAlpha;
+      ca.liveBullBlend = opts.liveBullBlend;
+      ca.cache = candleCache;
+      ca.makePath = candleCache ? makeCandlePath : undefined;
+      drawCandlesticks(ctx, layout, ca);
     }
     ctx.restore();
   }
diff --git a/src/draw/line.ts b/src/draw/line.ts
index f9f9fab..731188b 100644
--- a/src/draw/line.ts
+++ b/src/draw/line.ts
@@ -11,7 +11,6 @@ import {
   updateLinePaths,
   type CachePath,
   type LineCacheRef,
-  type LineCacheSlot,
 } from './lineCache';
 import type { Ctx2D, Style2D } from './canvas2d';
 import {
@@ -31,6 +30,72 @@ import {
 const DASH_4_4: number[] = [4, 4];
 const EMPTY_DASH: number[] = [];
 
+/**
+ * Everything `drawLine` needs beyond the three long-lived objects every draw
+ * module takes (`ctx`, `layout`, `palette`).
+ *
+ * **This is a pooled struct, not a per-call literal.** `drawLine` runs on the
+ * UI thread 60–120×/sec and previously took these twelve values as positional
+ * arguments — six of them consecutive numbers, silently transposable. Bundling
+ * them fixes that, but only if the bundle itself isn't allocated per frame, so
+ * exactly one instance lives on `EngineState` (`createLineDrawArgs`, mirroring
+ * `multiSeriesEntryScratch`) and every call site overwrites the fields it
+ * cares about in place. `drawLine` reads it synchronously and never retains
+ * it, so a single instance is safe even across the multi-series loop, which
+ * refills it once per series.
+ *
+ * New inputs go here as a field. That is the point: the previous shape made a
+ * 16th positional parameter expensive enough that a pooled-scratch change was
+ * reverted rather than pay for it.
+ */
+export interface LineDrawArgs {
+  /** Visible points, oldest → newest. */
+  visible: LivelinePoint[];
+  /** Smoothed live value — drives the last point's Y and the live tip. */
+  smoothValue: number;
+  /** Engine's `Date.now()/1000` for this frame; the live tip's X. */
+  now: number;
+  /** Draw the gradient fill under the line. */
+  showFill: boolean;
+  /** Scrub cursor X in px, or null when not scrubbing. */
+  scrubX: number | null;
+  /** 0 = not scrubbing, 1 = fully scrubbing (lerped). */
+  scrubAmount: number;
+  /** 0 = loading squiggly, 1 = fully revealed data line. */
+  chartReveal: number;
+  /** `performance.now()` — drives the loading breath/scroll during reveal. */
+  now_ms: number;
+  /** Scales the accent-color mix; 0 forces the grey loading color. */
+  colorBlend: number;
+  /** Skip the dashed current-price line (candle mode draws its own). */
+  skipDashLine: boolean;
+  /** Extra multiplier on the fill's alpha (line↔candle morph). */
+  fillScale: number;
+  /** Cross-frame path cache; undefined disables caching for this call. */
+  pathCache?: LineCacheRef;
+}
+
+/** Allocate one pooled `LineDrawArgs` (see the interface). Defaults match the
+ * old positional-parameter defaults, so a caller only has to write the fields
+ * it actually varies. */
+export function createLineDrawArgs(): LineDrawArgs {
+  'worklet';
+  return {
+    visible: [],
+    smoothValue: 0,
+    now: 0,
+    showFill: false,
+    scrubX: null,
+    scrubAmount: 0,
+    chartReveal: 1,
+    now_ms: 0,
+    colorBlend: 1,
+    skipDashLine: false,
+    fillScale: 1,
+    pathCache: undefined,
+  };
+}
+
 /** Parse a CSS color to [r, g, b, a]. Handles hex, rgb(), rgba(). */
 function parseRgba(color: string): [number, number, number, number] {
   'worklet';
@@ -150,7 +215,9 @@ function renderCurve(
   layout: ChartLayout,
   palette: LivelinePalette,
   pts: [number, number][],
-  showFill: boolean,
+  /** Already folded together with the alpha test by the caller — see
+   * `drawLine`'s `wantFill`. */
+  wantFill: boolean,
   lineAlpha: number = 1,
   fillAlpha: number = 1,
   strokeColor?: Style2D
@@ -159,7 +226,7 @@ function renderCurve(
   const { h, pad } = layout;
   const baseAlpha = ctx.globalAlpha;
 
-  if (showFill && fillAlpha > 0.01) {
+  if (wantFill && fillAlpha > 0.01) {
     ctx.globalAlpha = baseAlpha * fillAlpha;
     const grad = ctx.createLinearGradient(0, pad.top, 0, h - pad.bottom);
     grad.addColorStop(0, palette.fillTop);
@@ -197,26 +264,28 @@ function paintLineCurve(
   ctx: Ctx2D,
   layout: ChartLayout,
   palette: LivelinePalette,
-  cacheReady: boolean,
-  cacheSlot: LineCacheSlot | undefined,
-  wantFill: boolean,
+  /** The cache path to stroke, or null to rebuild the spline from `pts`.
+   * Resolving "cache hit? which of the slot's three paths?" once in `drawLine`
+   * — instead of re-deriving it from `cacheReady`/`cacheSlot`/`splitStroke` at
+   * each of the three call sites — is what lets this take two paths instead of
+   * four booleans. */
+  stroke: CachePath | null,
+  /** The cache fill path, or null for no fill / no cache. */
+  fill: CachePath | null,
   pts: [number, number][],
-  showFill: boolean,
+  wantFill: boolean,
   lineAlpha: number,
   fillAlpha: number,
-  strokeColor?: Style2D,
-  /** Stroke `tailScratch` instead of the combined `scratch` — the prefix is
-   * being composited from the scroll layer picture. See LineCacheRef. */
-  splitStroke: boolean = false
+  strokeColor?: Style2D
 ) {
   'worklet';
-  if (cacheReady && cacheSlot !== undefined) {
+  if (stroke !== null) {
     renderCurvePaths(
       ctx,
       layout,
       palette,
-      splitStroke ? cacheSlot.tailScratch! : cacheSlot.scratch!,
-      wantFill ? cacheSlot.fillScratch : null,
+      stroke,
+      fill,
       lineAlpha,
       fillAlpha,
       strokeColor
@@ -227,7 +296,7 @@ function paintLineCurve(
       layout,
       palette,
       pts,
-      showFill,
+      wantFill,
       lineAlpha,
       fillAlpha,
       strokeColor
@@ -239,20 +308,19 @@ export function drawLine(
   ctx: Ctx2D,
   layout: ChartLayout,
   palette: LivelinePalette,
-  visible: LivelinePoint[],
-  smoothValue: number,
-  now: number,
-  showFill: boolean,
-  scrubX: number | null,
-  scrubAmount: number = 0,
-  chartReveal: number = 1,
-  now_ms: number = 0,
-  colorBlend: number = 1,
-  skipDashLine: boolean = false,
-  fillScale: number = 1,
-  pathCache?: LineCacheRef
+  /** Pooled per-frame inputs — see `LineDrawArgs`. Read synchronously and
+   * never retained, so the caller may reuse one instance across calls. */
+  a: LineDrawArgs
 ): [number, number][] | undefined {
   'worklet';
+  const visible = a.visible;
+  const smoothValue = a.smoothValue;
+  const now = a.now;
+  const scrubX = a.scrubX;
+  const scrubAmount = a.scrubAmount;
+  const chartReveal = a.chartReveal;
+  const now_ms = a.now_ms;
+  const pathCache = a.pathCache;
   const { h, pad, toX, toY, chartW, chartH } = layout;
   const incomingAlpha = ctx.globalAlpha;
 
@@ -293,20 +361,20 @@ export function drawLine(
   // Computed before the cache check below — wantFill only needs these, not
   // the point arrays — so a cache hit never waits on the point-array work.
   let lineAlpha = 1;
-  let fillAlpha = fillScale;
+  let fillAlpha = a.fillScale;
   if (chartReveal < 1) {
     const breath = loadingBreath(now_ms);
     lineAlpha = breath + (1 - breath) * chartReveal;
-    fillAlpha = chartReveal * fillScale;
+    fillAlpha = chartReveal * a.fillScale;
   }
-  const wantFill = showFill && fillAlpha > 0.01;
+  const wantFill = a.showFill && fillAlpha > 0.01;
 
   // Blend line color: grey at reveal=0, accent by reveal≈0.3.
   // colorBlend scales the accent mix — 0 forces grey (used during reverse morph
   // so the line fades to the loading squiggly color instead of flashing blue).
-  const colorT = Math.min(1, chartReveal * 3) * colorBlend;
+  const colorT = Math.min(1, chartReveal * 3) * a.colorBlend;
   const strokeColor =
-    chartReveal < 1 || colorBlend < 1
+    chartReveal < 1 || a.colorBlend < 1
       ? blendColor(palette.gridLabel, palette.line, colorT)
       : undefined;
 
@@ -339,16 +407,7 @@ export function drawLine(
     pathCache !== undefined &&
     chartReveal >= 1 &&
     visLen > 0 &&
-    lineCacheHits(
-      pathCache.slot,
-      layout,
-      pathCache.dataRev,
-      pathCache.dataSource,
-      visLen,
-      visible[0]!.time,
-      visible[visLen - 1]!.time,
-      visible[visLen - 1]!.value
-    )
+    lineCacheHits(pathCache, layout, visible)
   ) {
     const visLast = visible[visLen - 1]!;
     const lastX = toX(visLast.time);
@@ -413,19 +472,13 @@ export function drawLine(
       pathCache !== undefined &&
       chartReveal >= 1 &&
       updateLinePaths(
-        pathCache.slot,
+        pathCache,
         makeSkPath,
         layout,
         decimated,
         pts,
         wantFill,
-        pathCache.dataRev,
-        pathCache.dataSource,
-        visLen,
-        visible[0]!.time,
-        visible[visLen - 1]!.time,
-        visible[visLen - 1]!.value,
-        wantSplitStroke
+        visible
       );
   }
 
@@ -454,6 +507,16 @@ export function drawLine(
     );
   }
 
+  // Which paths this frame's strokes read, resolved once. All three
+  // paintLineCurve calls below are the same drawing with different clips and
+  // alpha, so the source selection can't differ between them — hoisting it
+  // makes that structural rather than a convention three argument lists have
+  // to keep agreeing on.
+  const slot = cacheReady ? pathCache?.slot : undefined;
+  const strokePath =
+    slot === undefined ? null : splitStroke ? slot.tailScratch! : slot.scratch!;
+  const fillPath = slot === undefined || !wantFill ? null : slot.fillScratch;
+
   // Clip line + fill to chart area — during big value jumps the range
   // lerps smoothly so the line may extend beyond the chart bounds.
   // Clipping keeps it tidy while the range catches up.
@@ -468,15 +531,13 @@ export function drawLine(
       ctx,
       layout,
       palette,
-      cacheReady,
-      pathCache?.slot,
-      wantFill,
+      strokePath,
+      fillPath,
       pts,
-      showFill,
+      wantFill,
       lineAlpha,
       fillAlpha,
-      strokeColor,
-      splitStroke
+      strokeColor
     );
     ctx.restore();
 
@@ -488,15 +549,13 @@ export function drawLine(
       ctx,
       layout,
       palette,
-      cacheReady,
-      pathCache?.slot,
-      wantFill,
+      strokePath,
+      fillPath,
       pts,
-      showFill,
+      wantFill,
       lineAlpha,
       fillAlpha,
-      strokeColor,
-      splitStroke
+      strokeColor
     );
     ctx.restore();
   } else {
@@ -504,15 +563,13 @@ export function drawLine(
       ctx,
       layout,
       palette,
-      cacheReady,
-      pathCache?.slot,
-      wantFill,
+      strokePath,
+      fillPath,
       pts,
-      showFill,
+      wantFill,
       lineAlpha,
       fillAlpha,
-      strokeColor,
-      splitStroke
+      strokeColor
     );
   }
 
@@ -521,7 +578,7 @@ export function drawLine(
 
   // Dashed current-price line — morphs from center during reveal (fades in late,
   // so the center-vs-squiggly difference is imperceptible by the time it's visible)
-  if (!skipDashLine) {
+  if (!a.skipDashLine) {
     const realCurrentY = Math.max(
       pad.top,
       Math.min(h - pad.bottom, toY(smoothValue))
diff --git a/src/draw/lineCache.ts b/src/draw/lineCache.ts
index 6e3c02e..32f50a7 100644
--- a/src/draw/lineCache.ts
+++ b/src/draw/lineCache.ts
@@ -159,26 +159,41 @@ export function createLineCacheSlot(): LineCacheSlot {
  * the expensive per-frame work is needed at all, and `updateLinePaths` below
  * calls the exact same function on its (already-built) inputs, so the two
  * checks can never drift apart.
+ *
+ * The data-identity half of the key is derived here from `ref` (the slot plus
+ * this frame's revision/source) and from `visible` itself, rather than being
+ * passed as six loose arguments — four of which were adjacent numbers a
+ * caller could silently transpose. Deriving them in the one place that
+ * compares them also means a caller cannot compute them differently from the
+ * way `updateLinePaths` writes them.
+ *
+ * Precondition: `visible` is non-empty (every caller already gates on it).
  */
 export function lineCacheHits(
-  slot: LineCacheSlot,
+  ref: LineCacheRef,
   layout: ChartLayout,
-  dataRev: number,
-  dataSource: number,
-  visLen: number,
-  visFirstT: number,
-  visLastT: number,
-  visLastV: number
+  visible: LivelinePoint[]
 ): boolean {
   'worklet';
+  const slot = ref.slot;
+  // Ordered so nothing is dereferenced before the cheap disqualifiers run:
+  // `visible` is only indexed once the slot is known valid and the length
+  // already matches, which rules out the empty array (no valid slot can
+  // have kLen 0 — see MIN_CACHE_POINTS).
+  if (slot.prefix === null) return false;
+  const n = visible.length;
+  if (
+    slot.kLen !== n ||
+    slot.kDataRev !== ref.dataRev ||
+    slot.kDataSource !== ref.dataSource
+  ) {
+    return false;
+  }
+  const last = visible[n - 1]!;
   return (
-    slot.prefix !== null &&
-    slot.kDataRev === dataRev &&
-    slot.kDataSource === dataSource &&
-    slot.kLen === visLen &&
-    slot.kFirstT === visFirstT &&
-    slot.kLastT === visLastT &&
-    slot.kLastV === visLastV &&
+    slot.kFirstT === visible[0]!.time &&
+    slot.kLastT === last.time &&
+    slot.kLastV === last.value &&
     layoutKeyMatches(slot.layoutKey, layout)
   );
 }
@@ -404,35 +419,27 @@ export function assembleLineTailStroke(
  * `assembleLineTail` without ever building `decimated`/`pts`.
  */
 export function updateLinePaths(
-  slot: LineCacheSlot,
+  ref: LineCacheRef,
   makePath: () => CachePath,
   layout: ChartLayout,
   decimated: LivelinePoint[],
   pts: [number, number][],
   wantFill: boolean,
-  dataRev: number,
-  dataSource: number,
-  visLen: number,
-  visFirstT: number,
-  visLastT: number,
-  visLastV: number,
-  /** Forwarded to `assembleLineTail` — see its doc comment. */
-  splitStroke: boolean = false
+  /** The frame's visible points — the data-identity half of the cache key is
+   * derived from this, see `lineCacheHits`. Non-empty by construction here:
+   * `decimated` is a subset of it and already passed the MIN_CACHE_POINTS
+   * check above. */
+  visible: LivelinePoint[]
 ): boolean {
   'worklet';
   const N = decimated.length;
   if (N < MIN_CACHE_POINTS) return false;
 
-  const hit = lineCacheHits(
-    slot,
-    layout,
-    dataRev,
-    dataSource,
-    visLen,
-    visFirstT,
-    visLastT,
-    visLastV
-  );
+  const slot = ref.slot;
+  // Forwarded to `assembleLineTail` — see its doc comment, and
+  // `LineCacheRef.splitPrefixStroke` for why it is advisory.
+  const splitStroke = ref.splitPrefixStroke === true;
+  const hit = lineCacheHits(ref, layout, visible);
 
   if (!hit) {
     slot.prefix = ensured(slot.prefix, makePath);
@@ -449,12 +456,13 @@ export function updateLinePaths(
     slot.cutY = pts[prefixCount - 1]![1];
     slot.tRef = decimated[0]!.time;
     slot.xRefAtBuild = pts[0]![0];
-    slot.kDataRev = dataRev;
-    slot.kDataSource = dataSource;
-    slot.kLen = visLen;
-    slot.kFirstT = visFirstT;
-    slot.kLastT = visLastT;
-    slot.kLastV = visLastV;
+    const visLast = visible[visible.length - 1]!;
+    slot.kDataRev = ref.dataRev;
+    slot.kDataSource = ref.dataSource;
+    slot.kLen = visible.length;
+    slot.kFirstT = visible[0]!.time;
+    slot.kLastT = visLast.time;
+    slot.kLastV = visLast.value;
     writeLayoutKey(slot.layoutKey, layout);
   }
 
diff --git a/src/engine/__tests__/helpers.test.ts b/src/engine/__tests__/helpers.test.ts
index 1c2b935..7cca945 100644
--- a/src/engine/__tests__/helpers.test.ts
+++ b/src/engine/__tests__/helpers.test.ts
@@ -138,10 +138,12 @@ describe('updateWindowTransition — retargeting', () => {
     const wt = wtState({ to: 20, rangeToMin: -1, rangeToMax: -1 });
     updateWindowTransition(
       cfg({ windowSecs: 100 }),
-      wt,
-      /* displayWindow */ 20,
-      /* displayMin */ 90,
-      /* displayMax */ 110,
+      {
+        windowTransition: wt,
+        displayWindow: 20,
+        displayMin: 90,
+        displayMax: 110,
+      },
       false,
       NOW_MS,
       NOW,
@@ -167,10 +169,12 @@ describe('updateWindowTransition — retargeting', () => {
     const wt = wtState({ to: 20, rangeToMin: -1, rangeToMax: -1 });
     updateWindowTransition(
       cfg({ windowSecs: 100 }),
-      wt,
-      20,
-      90,
-      110,
+      {
+        windowTransition: wt,
+        displayWindow: 20,
+        displayMin: 90,
+        displayMax: 110,
+      },
       false,
       NOW_MS,
       NOW,
@@ -192,10 +196,12 @@ describe('updateWindowTransition — retargeting', () => {
     const wt = wtState({ to: 20, rangeToMin: -1, rangeToMax: -1 });
     updateWindowTransition(
       cfg({ windowSecs: 100 }),
-      wt,
-      20,
-      90,
-      110,
+      {
+        windowTransition: wt,
+        displayWindow: 20,
+        displayMin: 90,
+        displayMax: 110,
+      },
       false,
       NOW_MS,
       NOW,
@@ -217,10 +223,12 @@ describe('updateWindowTransition — retargeting', () => {
     const wt = wtState({ to: 20, rangeToMin: 42, rangeToMax: 84 });
     updateWindowTransition(
       cfg({ windowSecs: 100 }),
-      wt,
-      20,
-      90,
-      110,
+      {
+        windowTransition: wt,
+        displayWindow: 20,
+        displayMin: 90,
+        displayMax: 110,
+      },
       false,
       NOW_MS,
       NOW,
@@ -240,10 +248,12 @@ describe('updateWindowTransition — retargeting', () => {
     ]);
     updateWindowTransition(
       cfg({ windowSecs: 100 }),
-      wt,
-      20,
-      90,
-      110,
+      {
+        windowTransition: wt,
+        displayWindow: 20,
+        displayMin: 90,
+        displayMax: 110,
+      },
       false,
       NOW_MS,
       NOW,
@@ -253,10 +263,7 @@ describe('updateWindowTransition — retargeting', () => {
     );
     updateWindowTransition(
       cfg({ windowSecs: 100 }),
-      wt,
-      55,
-      1,
-      2,
+      { windowTransition: wt, displayWindow: 55, displayMin: 1, displayMax: 2 },
       false,
       NOW_MS + 300,
       NOW,
@@ -281,10 +288,12 @@ describe('updateWindowTransition — progress curve', () => {
     const wt = wtState({ to: 20 });
     const r = updateWindowTransition(
       cfg({ windowSecs: 100 }),
-      wt,
-      20,
-      90,
-      110,
+      {
+        windowTransition: wt,
+        displayWindow: 20,
+        displayMin: 90,
+        displayMax: 110,
+      },
       true,
       50_000,
       1000,
@@ -300,10 +309,12 @@ describe('updateWindowTransition — progress curve', () => {
     const wt = wtState({ to: 100, startMs: 0 });
     const r = updateWindowTransition(
       cfg({ windowSecs: 100 }),
-      wt,
-      100,
-      90,
-      110,
+      {
+        windowTransition: wt,
+        displayWindow: 100,
+        displayMin: 90,
+        displayMax: 110,
+      },
       false,
       50_000,
       1000,
@@ -322,10 +333,12 @@ describe('updateWindowTransition — progress curve', () => {
     const wt = wtState({ to: 10, startMs: 0 });
     updateWindowTransition(
       cfg({ windowSecs: 40 }),
-      wt,
-      10,
-      90,
-      110,
+      {
+        windowTransition: wt,
+        displayWindow: 10,
+        displayMin: 90,
+        displayMax: 110,
+      },
       false,
       1000,
       1000,
@@ -335,10 +348,12 @@ describe('updateWindowTransition — progress curve', () => {
     );
     const r = updateWindowTransition(
       cfg({ windowSecs: 40 }),
-      wt,
-      10,
-      90,
-      110,
+      {
+        windowTransition: wt,
+        displayWindow: 10,
+        displayMin: 90,
+        displayMax: 110,
+      },
       false,
       1000 + WINDOW_TRANSITION_MS / 2,
       1000,
@@ -355,10 +370,12 @@ describe('updateWindowTransition — progress curve', () => {
     const wt = wtState({ to: 10, startMs: 0 });
     updateWindowTransition(
       cfg({ windowSecs: 40 }),
-      wt,
-      10,
-      90,
-      110,
+      {
+        windowTransition: wt,
+        displayWindow: 10,
+        displayMin: 90,
+        displayMax: 110,
+      },
       false,
       1000,
       1000,
@@ -368,10 +385,12 @@ describe('updateWindowTransition — progress curve', () => {
     );
     const r = updateWindowTransition(
       cfg({ windowSecs: 40 }),
-      wt,
-      10,
-      90,
-      110,
+      {
+        windowTransition: wt,
+        displayWindow: 10,
+        displayMin: 90,
+        displayMax: 110,
+      },
       false,
       1000 + WINDOW_TRANSITION_MS / 4,
       1000,
@@ -388,10 +407,12 @@ describe('updateWindowTransition — progress curve', () => {
     const wt = wtState({ to: 10, startMs: 0 });
     updateWindowTransition(
       cfg({ windowSecs: 40 }),
-      wt,
-      10,
-      90,
-      110,
+      {
+        windowTransition: wt,
+        displayWindow: 10,
+        displayMin: 90,
+        displayMax: 110,
+      },
       false,
       1000,
       1000,
@@ -401,10 +422,12 @@ describe('updateWindowTransition — progress curve', () => {
     );
     const r = updateWindowTransition(
       cfg({ windowSecs: 40 }),
-      wt,
-      10,
-      90,
-      110,
+      {
+        windowTransition: wt,
+        displayWindow: 10,
+        displayMin: 90,
+        displayMax: 110,
+      },
       false,
       1000 + WINDOW_TRANSITION_MS,
       1000,
@@ -428,10 +451,12 @@ describe('updateWindowTransition — progress curve', () => {
     const call = (wt: WindowTransState, now_ms: number) =>
       updateWindowTransition(
         cfg({ windowSecs: 40 }),
-        wt,
-        10,
-        90,
-        110,
+        {
+          windowTransition: wt,
+          displayWindow: 10,
+          displayMin: 90,
+          displayMax: 110,
+        },
         false,
         now_ms,
         1000,
@@ -476,15 +501,17 @@ const RANGE_WT = {
 describe('updateRange — first frame', () => {
   it('adopts the computed range verbatim and marks itself inited', () => {
     const r = updateRange(
+      {
+        windowTransition: wtState(),
+        rangeInited: false,
+        targetMin: -1,
+        targetMax: -1,
+        displayMin: -1,
+        displayMax: -1,
+      },
       { min: 3, max: 7 },
       false,
-      -1,
-      -1,
-      -1,
-      -1,
-      false,
       0,
-      wtState(),
       0.08,
       300,
       16.67
@@ -503,15 +530,17 @@ describe('updateRange — first frame', () => {
 
   it('never reports a zero valRange (it is a divisor for every toY)', () => {
     const r = updateRange(
+      {
+        windowTransition: wtState(),
+        rangeInited: false,
+        targetMin: 0,
+        targetMax: 0,
+        displayMin: 0,
+        displayMax: 0,
+      },
       { min: 5, max: 5 },
       false,
       0,
-      0,
-      0,
-      0,
-      false,
-      0,
-      wtState(),
       0.08,
       300,
       16.67
@@ -523,15 +552,17 @@ describe('updateRange — first frame', () => {
 describe('updateRange — during a window transition', () => {
   it('blends linearly between the captured from/to ranges by progress alone', () => {
     const r = updateRange(
+      {
+        windowTransition: { ...wtState(), ...RANGE_WT },
+        rangeInited: true,
+        targetMin: 0,
+        targetMax: 0,
+        displayMin: /* displayMin */ 1234,
+        displayMax: /* displayMax */ 5678,
+      },
       { min: 999, max: 999 },
       true,
-      0,
-      0,
-      /* displayMin */ 1234,
-      /* displayMax */ 5678,
-      true,
       0.25,
-      { ...wtState(), ...RANGE_WT },
       0.08,
       300,
       16.67
@@ -546,15 +577,17 @@ describe('updateRange — during a window transition', () => {
 
   it('still tracks the computed range as the target for when the transition ends', () => {
     const r = updateRange(
+      {
+        windowTransition: { ...wtState(), ...RANGE_WT },
+        rangeInited: true,
+        targetMin: 0,
+        targetMax: 0,
+        displayMin: 1234,
+        displayMax: 5678,
+      },
       { min: 42, max: 84 },
       true,
-      0,
-      0,
-      1234,
-      5678,
-      true,
       0.25,
-      { ...wtState(), ...RANGE_WT },
       0.08,
       300,
       16.67
@@ -565,15 +598,17 @@ describe('updateRange — during a window transition', () => {
 
   it('reaches the captured target range exactly at full progress', () => {
     const r = updateRange(
+      {
+        windowTransition: { ...wtState(), ...RANGE_WT },
+        rangeInited: true,
+        targetMin: 0,
+        targetMax: 0,
+        displayMin: 0,
+        displayMax: 0,
+      },
       { min: 0, max: 0 },
       true,
-      0,
-      0,
-      0,
-      0,
-      true,
       1,
-      { ...wtState(), ...RANGE_WT },
       0.08,
       300,
       16.67
@@ -590,15 +625,17 @@ describe('updateRange — steady-state lerp', () => {
     let displayMax = 100;
     for (let i = 0; i < frames; i++) {
       const r = updateRange(
+        {
+          windowTransition: wtState(),
+          rangeInited: true,
+          targetMin: 0,
+          targetMax: 0,
+          displayMin: displayMin,
+          displayMax: displayMax,
+        },
         { min: 40, max: 160 },
-        true,
-        0,
-        0,
-        displayMin,
-        displayMax,
         false,
         0,
-        wtState(),
         0.08,
         chartH,
         dt
@@ -637,15 +674,17 @@ describe('updateRange — steady-state lerp', () => {
     let prev = -Infinity;
     for (let i = 0; i < 200; i++) {
       const r = updateRange(
+        {
+          windowTransition: wtState(),
+          rangeInited: true,
+          targetMin: 0,
+          targetMax: 0,
+          displayMin: displayMin,
+          displayMax: 100,
+        },
         { min: 40, max: 160 },
-        true,
-        0,
-        0,
-        displayMin,
-        100,
         false,
         0,
-        wtState(),
         0.08,
         1e9,
         1000 / 60
@@ -682,15 +721,17 @@ describe('updateRange — steady-state lerp', () => {
     let displayMax = 5;
     for (let i = 0; i < 400; i++) {
       const r = updateRange(
+        {
+          windowTransition: wtState(),
+          rangeInited: true,
+          targetMin: 0,
+          targetMax: 0,
+          displayMin: displayMin,
+          displayMax: displayMax,
+        },
         { min: 5, max: 5.0005 },
-        true,
-        0,
-        0,
-        displayMin,
-        displayMax,
         false,
         0,
-        wtState(),
         0.08,
         300,
         1000 / 60
@@ -722,17 +763,12 @@ describe('updateHoverState — hit testing', () => {
   ) =>
     updateHoverState(
       hoverPixelX,
-      PAD,
-      W,
       layout,
       now,
       visible,
       scrubAmount,
       lastHover,
-      false,
-      0,
-      100,
-      CHART_W
+      false
     );
 
   it('maps a pixel inside the plot area to an interpolated time and value', () => {
@@ -764,20 +800,7 @@ describe('updateHoverState — hit testing', () => {
   });
 
   it('reports no hover when there is no data to interpolate', () => {
-    const r = updateHoverState(
-      55,
-      PAD,
-      W,
-      layout,
-      100,
-      [],
-      0,
-      null,
-      false,
-      0,
-      100,
-      CHART_W
-    );
+    const r = updateHoverState(55, layout, 100, [], 0, null, false);
     expect(r.isActiveHover).toBe(false);
     expect(r.hoverValue).toBeNull();
     expect(r.emitPoint).toBeNull();
@@ -815,17 +838,12 @@ describe('updateHoverState — scrub fade', () => {
   ) =>
     updateHoverState(
       hoverPixelX,
-      PAD,
-      W,
       layout,
       100,
       visible,
       scrubAmount,
       lastHover,
-      noMotion,
-      0,
-      100,
-      CHART_W
+      noMotion
     );
 
   it('jumps the scrub amount to exactly 1 / 0 under noMotion', () => {
diff --git a/src/engine/__tests__/step.test.ts b/src/engine/__tests__/step.test.ts
index 19eecaf..c339acb 100644
--- a/src/engine/__tests__/step.test.ts
+++ b/src/engine/__tests__/step.test.ts
@@ -129,20 +129,17 @@ function run(
   candles: CandlePoint[] = [],
   multiData: Record<string, LivelinePoint[]> = {}
 ) {
-  return engineStep(
-    makeCtx(),
-    cfg,
-    s,
-    W,
-    H,
-    null,
-    16,
-    1000,
-    FONTS,
-    data,
-    candles,
-    multiData
-  );
+  const frame = s.frameInputs;
+  frame.w = W;
+  frame.h = H;
+  frame.hoverPixelX = null;
+  frame.dt = 16;
+  frame.now_ms = 1000;
+  frame.fonts = FONTS;
+  frame.data = data;
+  frame.candles = candles;
+  frame.multiData = multiData;
+  return engineStep(makeCtx(), cfg, s, frame);
 }
 
 /** Points spanning `[now - ageSecs - span, now - ageSecs]`. */
diff --git a/src/engine/__tests__/stepCharacterization.test.ts b/src/engine/__tests__/stepCharacterization.test.ts
index 0d59415..4f0b365 100644
--- a/src/engine/__tests__/stepCharacterization.test.ts
+++ b/src/engine/__tests__/stepCharacterization.test.ts
@@ -185,20 +185,21 @@ function frame(
   cfg: EngineConfigStep,
   args: FrameArgs = {}
 ): StepOutput {
-  const out = engineStep(
-    makeCtx(),
-    cfg,
-    s,
-    W,
-    H,
-    args.hoverX ?? null,
-    DT,
-    clockMs,
-    FONTS,
-    args.data ?? [],
-    args.candles ?? [],
-    args.multiData ?? {}
-  );
+  // `engineStep` takes a pooled FrameInputs struct rather than 12 positional
+  // args (PLAN_MAINT #4). Fill the engine's own pooled instance in place, the
+  // same way useLivelineEngine's frame callback does, so these tests exercise
+  // the real calling convention and allocate nothing per frame either.
+  const fi = s.frameInputs;
+  fi.w = W;
+  fi.h = H;
+  fi.hoverPixelX = args.hoverX ?? null;
+  fi.dt = DT;
+  fi.now_ms = clockMs;
+  fi.fonts = FONTS;
+  fi.data = args.data ?? [];
+  fi.candles = args.candles ?? [];
+  fi.multiData = args.multiData ?? {};
+  const out = engineStep(makeCtx(), cfg, s, fi);
   clockMs += DT;
   return out;
 }
diff --git a/src/engine/helpers.ts b/src/engine/helpers.ts
index 18ac799..2ec8648 100644
--- a/src/engine/helpers.ts
+++ b/src/engine/helpers.ts
@@ -23,6 +23,32 @@ export interface WindowTransState {
   rangeToMax: number;
 }
 
+/**
+ * The slice of `EngineState` the window transition reads and writes. Declared
+ * as its own narrow interface rather than taking `EngineState` itself: these
+ * helpers get handed the engine state object directly (structural typing —
+ * `engineStep` just passes `s`), so no allocation is involved, but the
+ * signature still says exactly which four fields are in play.
+ */
+export interface WindowTransInputs {
+  windowTransition: WindowTransState;
+  displayWindow: number;
+  displayMin: number;
+  displayMax: number;
+}
+
+/** The slice of `EngineState` the Y-range smoothing reads. Same rationale as
+ * `WindowTransInputs`. The updated values come back on the result object,
+ * which the caller writes back — unchanged from before. */
+export interface RangeInputs {
+  windowTransition: WindowTransState;
+  rangeInited: boolean;
+  targetMin: number;
+  targetMax: number;
+  displayMin: number;
+  displayMax: number;
+}
+
 /** Lerp display value with adaptive speed — slow for big jumps, fast for small ticks. */
 export function computeAdaptiveSpeed(
   value: number,
@@ -42,10 +68,9 @@ export function computeAdaptiveSpeed(
 /** Update window transition state, returning current display window and transition progress. */
 export function updateWindowTransition(
   cfg: EngineConfigStep,
-  wt: WindowTransState,
-  displayWindow: number,
-  displayMin: number,
-  displayMax: number,
+  /** The engine state — see `WindowTransInputs`. `windowTransition` is
+   * mutated in place, exactly as the old `wt` argument was. */
+  s: WindowTransInputs,
   noMotion: boolean,
   now_ms: number,
   now: number,
@@ -54,8 +79,11 @@ export function updateWindowTransition(
   buffer: number
 ): { windowSecs: number; windowTransProgress: number } {
   'worklet';
+  const wt = s.windowTransition;
+  const displayMin = s.displayMin;
+  const displayMax = s.displayMax;
   if (wt.to !== cfg.windowSecs) {
-    wt.from = displayWindow;
+    wt.from = s.displayWindow;
     wt.to = cfg.windowSecs;
     wt.startMs = now_ms;
     wt.rangeFromMin = displayMin;
@@ -102,15 +130,12 @@ export function updateWindowTransition(
 
 /** Smooth Y range with lerp. During window transitions, interpolates between pre-computed ranges. */
 export function updateRange(
+  /** The engine state — see `RangeInputs`. Read only; the new values come
+   * back on the result object for the caller to write back. */
+  s: RangeInputs,
   computedRange: { min: number; max: number },
-  rangeInited: boolean,
-  targetMin: number,
-  targetMax: number,
-  displayMin: number,
-  displayMax: number,
   isTransitioning: boolean,
   windowTransProgress: number,
-  wt: WindowTransState,
   adaptiveSpeed: number,
   chartH: number,
   dt: number
@@ -125,7 +150,12 @@ export function updateRange(
   rangeInited: boolean;
 } {
   'worklet';
-  if (!rangeInited) {
+  const wt = s.windowTransition;
+  let targetMin = s.targetMin;
+  let targetMax = s.targetMax;
+  let displayMin = s.displayMin;
+  let displayMax = s.displayMax;
+  if (!s.rangeInited) {
     return {
       minVal: computedRange.min,
       maxVal: computedRange.max,
@@ -179,22 +209,27 @@ export interface HoverStateResult {
   emitPoint: HoverPoint | null;
 }
 
-/** Compute hover position, interpolated value, and scrub amount. */
+/**
+ * Compute hover position, interpolated value, and scrub amount.
+ *
+ * Took `pad`, `w`, `leftEdge`, `rightEdge` and `chartW` as five extra
+ * positional arguments alongside `layout` — every one of them a field of the
+ * `layout` it was handed (see `makeLayout`, which is built from exactly those
+ * values). Reading them off `layout` costs nothing, removes five arguments,
+ * and makes it impossible to hand this function a layout and a set of edges
+ * that disagree.
+ */
 export function updateHoverState(
   hoverPixelX: number | null,
-  pad: Required<Padding>,
-  w: number,
   layout: ChartLayout,
   now: number,
   visible: LivelinePoint[],
   scrubAmount: number,
   lastHover: { x: number; value: number; time: number } | null,
-  noMotion: boolean,
-  leftEdge: number,
-  rightEdge: number,
-  chartW: number
+  noMotion: boolean
 ): HoverStateResult {
   'worklet';
+  const { pad, w, leftEdge, rightEdge, chartW } = layout;
   let hoverValue: number | null = null;
   let hoverTime: number | null = null;
   let hoverChartX: number | null = null;
diff --git a/src/engine/state.ts b/src/engine/state.ts
index 227dfa9..a9c0323 100644
--- a/src/engine/state.ts
+++ b/src/engine/state.ts
@@ -1,13 +1,25 @@
 import type { SkPath, SkPicture } from '@shopify/react-native-skia';
-import type { LivelinePoint, LivelinePalette, CandlePoint } from '../types';
+import type {
+  LivelinePoint,
+  LivelinePalette,
+  CandlePoint,
+  LivelineFonts,
+} from '../types';
 import type { ArrowState, ShakeState, MultiSeriesEntry } from '../draw';
 import type { GridState } from '../draw/grid';
 import type { TimeAxisState } from '../draw/timeAxis';
 import { createOrderbookState, type OrderbookState } from '../draw/orderbook';
-import { createLineCacheSlot, type LineCacheSlot } from '../draw/lineCache';
+import {
+  createLineCacheSlot,
+  type LineCacheSlot,
+  type LineCacheRef,
+} from '../draw/lineCache';
+import { createLineDrawArgs, type LineDrawArgs } from '../draw/line';
+import { createCandleDrawArgs, type CandleDrawArgs } from '../draw/candlestick';
 import {
   createCandleCacheSlot,
   type CandleCacheSlot,
+  type CandleCacheRef,
 } from '../draw/candleCache';
 import { createGridLayerSlot, type GridLayerSlot } from '../draw/gridLayer';
 import {
@@ -18,7 +30,7 @@ import { createParticleState, type ParticleState } from '../draw/particles';
 import { createShakeState } from '../draw';
 import { createSkiaCache, type SkiaCache } from '../draw/canvas2d';
 import type { WindowTransState } from './helpers';
-import type { EngineConfigStep } from './types';
+import type { EngineConfigStep, FrameInputs } from './types';
 
 export interface BadgeState {
   displayW: number; // current lerped text width (0 = uninited)
@@ -119,6 +131,21 @@ export interface EngineState {
   badge: BadgeState;
   /** Cross-frame line SkPath cache, single-series mode (see draw/lineCache) */
   lineCache: LineCacheSlot;
+  /** Pooled `LineCacheRef` — the (slot, dataRev, dataSource,
+   * splitPrefixStroke) bundle `lineCacheHits`/`drawLine` take. Overwritten in
+   * place each frame instead of allocating a fresh literal, and repointed at
+   * each series' own slot inside the multi-series loop (`drawMultiFrame`
+   * reads it synchronously per series and retains nothing). Starts pointing
+   * at `lineCache` above, which is the single-series pipeline's slot. */
+  lineCacheRef: LineCacheRef;
+  /** Pooled argument struct for `drawLine` — see `LineDrawArgs`. One
+   * instance, refilled before every call (including once per series in
+   * multi-series mode); only one pipeline draws per frame, and `drawLine`
+   * never retains it. Same pooling rationale as `multiSeriesEntryScratch`. */
+  lineDrawArgs: LineDrawArgs;
+  /** Pooled argument struct for `drawCandlesticks` — see `CandleDrawArgs`.
+   * Refilled between the two halves of the candle-width cross-fade. */
+  candleDrawArgs: CandleDrawArgs;
   /** Per-series line path caches, multi-series mode — keyed by series id,
    * pruned alongside displayValues when series are removed */
   lineCaches: Map<string, LineCacheSlot>;
@@ -172,6 +199,15 @@ export interface EngineState {
   /** Cross-frame closed-candle body+wick path cache, candle mode (see
    * draw/candleCache). */
   candleCache: CandleCacheSlot;
+  /** Pooled `FrameInputs` for `engineStep` — the caller (useLivelineEngine's
+   * frame worklet) overwrites its fields each frame and hands it straight
+   * back in, so the twelve-argument call became a four-argument one without
+   * adding a per-frame allocation. See `FrameInputs` in engine/step.ts. */
+  frameInputs: FrameInputs;
+  /** Pooled `CandleCacheRef` — the (slot, dataSource, candlesRev) bundle
+   * `drawCandlesticks`/`updateCandleCache` take. Overwritten in place each
+   * candle frame instead of allocating a fresh literal. */
+  candleCacheRef: CandleCacheRef;
 
   // Hover state
   scrubAmount: number;
@@ -378,6 +414,10 @@ export function createEngineState(
   candleWidth: number
 ): EngineState {
   'worklet';
+  // Built before the literal so `lineCacheRef` can point at the very same
+  // slot object rather than a copy.
+  const lineCache = createLineCacheSlot();
+  const candleCache = createCandleCacheSlot();
   return {
     displayValue: value,
     displayValues: new Map<string, number>(),
@@ -430,7 +470,10 @@ export function createEngineState(
       pathW: -1,
       pathTail: false,
     },
-    lineCache: createLineCacheSlot(),
+    lineCache: lineCache,
+    lineCacheRef: { slot: lineCache, dataRev: 0, dataSource: 0 },
+    lineDrawArgs: createLineDrawArgs(),
+    candleDrawArgs: createCandleDrawArgs(),
     lineCaches: new Map<string, LineCacheSlot>(),
     gridLayer: createGridLayerSlot<SkPicture>(),
     gridLayerCache: createSkiaCache(),
@@ -441,7 +484,24 @@ export function createEngineState(
     scrollDxLastT: -1,
     scrollDxRate: 0,
     scrollDxBuildRev: -1,
-    candleCache: createCandleCacheSlot(),
+    candleCache: candleCache,
+    frameInputs: {
+      w: 0,
+      h: 0,
+      hoverPixelX: null,
+      dt: 0,
+      now_ms: 0,
+      // Every field is filled by the caller before the first `engineStep`;
+      // the placeholders here exist only so the struct is fully shaped at
+      // creation rather than growing properties later. There is no "empty"
+      // `LivelineFonts` to seed with — the real one is supplied by the frame
+      // worklet, which is the only thing that ever reads this.
+      fonts: null as unknown as LivelineFonts,
+      data: [],
+      candles: [],
+      multiData: {},
+    },
+    candleCacheRef: { slot: candleCache, dataSource: 0, candlesRev: 0 },
 
     scrubAmount: 0,
     lastHover: null,
diff --git a/src/engine/step.ts b/src/engine/step.ts
index 9ae87f1..b6cf5d1 100644
--- a/src/engine/step.ts
+++ b/src/engine/step.ts
@@ -4,7 +4,6 @@ import type {
   Momentum,
   HoverPoint,
   CandlePoint,
-  LivelineFonts,
 } from '../types';
 import { lerp } from '../math/lerp';
 import { computeRange } from '../math/range';
@@ -24,7 +23,7 @@ import {
 import { shouldBuildLineOverlay } from '../draw/lineOverlay';
 import { drawLoading } from '../draw/loading';
 import { drawEmpty } from '../draw/empty';
-import type { EngineConfigStep } from './types';
+import type { EngineConfigStep, FrameInputs } from './types';
 import type { EngineState } from './state';
 import { perSeriesMaps, pruneByIds } from './state';
 import { drawBadge } from './badge';
@@ -180,27 +179,16 @@ export function engineStep(
   ctx: Ctx2D,
   cfg: EngineConfigStep,
   s: EngineState,
-  w: number,
-  h: number,
-  hoverPixelXRaw: number | null,
-  dt: number,
-  now_ms: number,
-  fonts: LivelineFonts,
-  /** Line-mode data points — synced via its own delta-updated shared value. */
-  data: LivelinePoint[],
-  /** Candles — synced via its own delta-updated shared value; empty array
-   * (never undefined) when there is no candle data, matching the `?? []`
-   * fallback this replaces at every read site below. */
-  candles: CandlePoint[],
-  /** Multi-series data points, keyed by series id — synced via its own
-   * delta-updated shared value (one buffer per series), same rationale as
-   * `data`/`candles` above but keyed since series can be added/removed
-   * independently. `cfg.multiSeries` entries carry id/value/palette/label
-   * only; look up a series' points here (or via `multiSeriesData` below,
-   * which also handles the reverse-morph stash case). */
-  multiData: Record<string, LivelinePoint[]>
+  /** This frame's varying inputs — see `FrameInputs`. Pooled on `EngineState`
+   * as `s.frameInputs`; the caller fills it in place and passes it, so the
+   * struct costs no allocation per frame. */
+  frame: FrameInputs
 ): StepOutput {
   'worklet';
+  // Destructured to the names the body below already uses. Local bindings
+  // only — nothing is copied and nothing is allocated.
+  const { w, h, dt, now_ms, fonts, data, candles, multiData } = frame;
+  const hoverPixelXRaw = frame.hoverPixelX;
   const out: StepOutput = {
     valueText: null,
     valueColor: null,
@@ -1121,6 +1109,15 @@ export function engineStep(
       cp.close = s.closeLineSmooth;
       closePriceCandle = cp;
     }
+    // Pooled ref (EngineState.candleCacheRef) refilled in place, rather than
+    // a fresh literal every candle frame.
+    const candleCacheRef = s.candleCacheRef;
+    candleCacheRef.slot = s.candleCache;
+    candleCacheRef.dataSource = dataSourceOf(
+      useStash,
+      s.pausedCandles !== null
+    );
+    candleCacheRef.candlesRev = cfg.candlesRev;
     drawCandleFrame(ctx, layout, cfg.palette, {
       candles: drawCandles,
       displayCandleWidth,
@@ -1161,11 +1158,9 @@ export function engineStep(
       // allowing smooth fade-out during empty→live (loadingAlpha is 0).
       showEmptyOverlay: !(cfg.loading ?? false) && loadingAlpha < 0.01,
       gridLayer: s.gridLayer,
-      candleCache: {
-        slot: s.candleCache,
-        dataSource: dataSourceOf(useStash, s.pausedCandles !== null),
-        candlesRev: cfg.candlesRev,
-      },
+      candleCache: candleCacheRef,
+      lineArgs: s.lineDrawArgs,
+      candleArgs: s.candleDrawArgs,
     });
 
     // Badge in candle mode — only when in line mode (lineModeProg > 0.5)
@@ -1337,10 +1332,7 @@ export function engineStep(
       multiSeriesData(firstSeries, multiData);
     const windowResult = updateWindowTransition(
       cfg,
-      transition,
-      s.displayWindow,
-      s.displayMin,
-      s.displayMax,
+      s,
       noMotion,
       now_ms,
       now,
@@ -1502,15 +1494,10 @@ export function engineStep(
     };
     const adaptiveSpeed = cfg.lerpSpeed + ADAPTIVE_SPEED_BOOST * 0.5;
     const rangeResult = updateRange(
+      s,
       computedRange,
-      s.rangeInited,
-      s.targetMin,
-      s.targetMax,
-      s.displayMin,
-      s.displayMax,
       isWindowTransitioning,
       windowTransProgress,
-      transition,
       adaptiveSpeed,
       chartH,
       pausedDt
@@ -1656,6 +1643,8 @@ export function engineStep(
       lineCaches: s.lineCaches,
       multiDataSource: dataSourceOf(useMultiStash, s.pausedMultiData !== null),
       gridLayer: s.gridLayer,
+      lineArgs: s.lineDrawArgs,
+      lineCacheRef: s.lineCacheRef,
     });
 
     // During reverse morph (chart → loading/empty), overlay the empty text
@@ -1739,10 +1728,7 @@ export function engineStep(
     const now = useStash ? s.frozenNow : Date.now() / 1000 - s.timeDebt;
     const windowResult = updateWindowTransition(
       cfg,
-      transition,
-      s.displayWindow,
-      s.displayMin,
-      s.displayMax,
+      s,
       noMotion,
       now_ms,
       now,
@@ -1809,15 +1795,10 @@ export function engineStep(
     );
     const isWindowTransitioning = transition.startMs > 0;
     const rangeResult = updateRange(
+      s,
       computedRange,
-      s.rangeInited,
-      s.targetMin,
-      s.targetMax,
-      s.displayMin,
-      s.displayMax,
       isWindowTransitioning,
       windowTransProgress,
-      transition,
       adaptiveSpeed,
       chartH,
       pausedDt
@@ -1866,17 +1847,12 @@ export function engineStep(
     // Hover + scrub
     const hoverResult = updateHoverState(
       hoverPixelX,
-      pad,
-      w,
       layout,
       now,
       visible,
       s.scrubAmount,
       s.lastHover,
-      noMotion,
-      leftEdge,
-      rightEdge,
-      chartW
+      noMotion
     );
     s.scrubAmount = hoverResult.scrubAmount;
     s.lastHover = hoverResult.lastHover;
@@ -1929,26 +1905,22 @@ export function engineStep(
     // `splitPrefixStroke`). `s.shakeState.amplitude` is read pre-decay,
     // which is the value `drawFrame`'s own translate will use this frame.
     const dataSource = dataSourceOf(useStash, s.pausedData !== null);
-    const visLastPoint = visible[visible.length - 1]!;
     const canComposite = canCompositeLineScroll(
       chartReveal,
       s.scrubAmount,
       cfg.degenOptions ? s.shakeState.amplitude : 0
     );
+    // Pooled ref (EngineState.lineCacheRef), refilled in place — the same
+    // object is handed to `drawFrame` below as `lineCache`, so the predicate
+    // here and the cache `drawLine` consults are provably the same inputs,
+    // and neither costs an allocation.
+    const lineCacheRef = s.lineCacheRef;
+    lineCacheRef.slot = s.lineCache;
+    lineCacheRef.dataRev = cfg.dataRev;
+    lineCacheRef.dataSource = dataSource;
+    lineCacheRef.splitPrefixStroke = false;
     let splitPrefixStroke = false;
-    if (
-      canComposite &&
-      lineCacheHits(
-        s.lineCache,
-        layout,
-        cfg.dataRev,
-        dataSource,
-        visible.length,
-        visible[0]!.time,
-        visLastPoint.time,
-        visLastPoint.value
-      )
-    ) {
+    if (canComposite && lineCacheHits(lineCacheRef, layout, visible)) {
       updateLineScrollLayer(
         s.lineScroll,
         s.lineCache,
@@ -1962,6 +1934,7 @@ export function engineStep(
       // future consumer that genuinely is alpha-driven.
       splitPrefixStroke = scrollLayerUsable(s.lineScroll, 1);
     }
+    lineCacheRef.splitPrefixStroke = splitPrefixStroke;
     if (splitPrefixStroke) {
       out.scrollPicture = s.lineScroll.picture;
       // Same dx the cached prefix path is offset by — the picture IS that
@@ -2015,13 +1988,9 @@ export function engineStep(
       chartReveal,
       pauseProgress,
       now_ms,
-      lineCache: {
-        slot: s.lineCache,
-        dataRev: cfg.dataRev,
-        dataSource,
-        splitPrefixStroke,
-      },
+      lineCache: lineCacheRef,
       gridLayer: s.gridLayer,
+      lineArgs: s.lineDrawArgs,
     });
 
     // During morph (chart ↔ empty), overlay the gradient gap + text on
diff --git a/src/engine/types.ts b/src/engine/types.ts
index 4937002..bde7436 100644
--- a/src/engine/types.ts
+++ b/src/engine/types.ts
@@ -8,6 +8,7 @@ import type {
   DegenOptions,
   BadgeVariant,
   CandlePoint,
+  LivelineFonts,
 } from '../types';
 
 /**
@@ -128,3 +129,44 @@ export type EngineConfigStep = Omit<
    */
   multiRevs?: Record<string, number>;
 };
+
+/**
+ * The per-frame inputs to `engineStep` that are neither the drawing context,
+ * the config, nor the engine state — the canvas size, this frame's timing and
+ * hover pixel, the fonts, and the three delta-synced data buffers.
+ *
+ * These were nine positional parameters (twelve in total), including two
+ * adjacent `number` pairs — `w, h` and `dt, now_ms` — that a caller could
+ * transpose with no type error and no test failure, only a wrong-looking
+ * chart. As a struct they are named at the call site.
+ *
+ * **Pooled, not allocated per frame**: one instance lives on `EngineState`
+ * (`frameInputs`), which the caller fills in place. `engineStep` destructures
+ * it on entry and never retains it.
+ */
+export interface FrameInputs {
+  /** Canvas width in px. */
+  w: number;
+  /** Canvas height in px. */
+  h: number;
+  /** Hover/scrub pixel X, or null when the finger is off the chart. */
+  hoverPixelX: number | null;
+  /** Delta time in ms since the last drawn frame. */
+  dt: number;
+  /** `performance.now()` for this frame. */
+  now_ms: number;
+  fonts: LivelineFonts;
+  /** Line-mode data points — synced via its own delta-updated shared value. */
+  data: LivelinePoint[];
+  /** Candles — synced via its own delta-updated shared value; empty array
+   * (never undefined) when there is no candle data, matching the `?? []`
+   * fallback this replaced at every read site below. */
+  candles: CandlePoint[];
+  /** Multi-series data points, keyed by series id — synced via its own
+   * delta-updated shared value (one buffer per series), same rationale as
+   * `data`/`candles` above but keyed since series can be added/removed
+   * independently. `cfg.multiSeries` entries carry id/value/palette/label
+   * only; look up a series' points here (or via `multiSeriesData` below,
+   * which also handles the reverse-morph stash case). */
+  multiData: Record<string, LivelinePoint[]>;
+}
diff --git a/src/useLivelineEngine.ts b/src/useLivelineEngine.ts
index c86941c..42020d2 100644
--- a/src/useLivelineEngine.ts
+++ b/src/useLivelineEngine.ts
@@ -638,20 +638,20 @@ export function useLivelineEngine(
     const recorder = Skia.PictureRecorder();
     const canvas = recorder.beginRecording(cullRect.value);
     const ctx = createCanvas2D(canvas, fonts, skiaCache.value);
-    const result = engineStep(
-      ctx,
-      c,
-      s,
-      w,
-      h,
-      hoverX.value,
-      dt,
-      now_ms,
-      fonts,
-      dataBuf.value,
-      candlesBuf.value,
-      multiDataBuf.value
-    );
+    // Pooled per-frame input struct (EngineState.frameInputs) refilled in
+    // place — see `FrameInputs`. Named fields instead of twelve positional
+    // arguments, at no allocation cost.
+    const frameInputs = s.frameInputs;
+    frameInputs.w = w;
+    frameInputs.h = h;
+    frameInputs.hoverPixelX = hoverX.value;
+    frameInputs.dt = dt;
+    frameInputs.now_ms = now_ms;
+    frameInputs.fonts = fonts;
+    frameInputs.data = dataBuf.value;
+    frameInputs.candles = candlesBuf.value;
+    frameInputs.multiData = multiDataBuf.value;
+    const result = engineStep(ctx, c, s, frameInputs);
     screenPicture.value = recorder.finishRecordingAsPicture();
     // Publish this frame's scroll layer. `null` means the layer must not
     // composite at all (see StepOutput.scrollPicture) — the empty 1×1

From 0f0e02a7fcd6b5ccbcbf4a2a5891e80e6898f936 Mon Sep 17 00:00:00 2001
From: Andrew Fuller <andrew_fuller@outlook.com>
Date: Mon, 3 Aug 2026 17:55:38 -0400
Subject: [PATCH 37/37] fix: dispose retired SkPictures, serialize suspend
 credit, prune hidden series

Review findings from the pre-merge pass on PR #2:

- Retire-then-dispose every replaced SkPicture (screen ~60/sec, grid and
  scroll layers per rebuild) one frame after its successor composites,
  instead of leaving native pictures to the UI runtime's GC.
- Accumulate suspended-time credit via runOnUI so the += and the frame
  callback's drain are serialized on one runtime (double-credit race on
  fast background/foreground flaps).
- Prune hiddenSeries against live series ids: a removed-then-re-added
  series no longer returns hidden, and dead ids no longer let the
  last-visible-series guard be defeated into a blank chart.
- Move the parseColorRgb dev-warn dedupe off a worklet-captured module
  binding onto the runtime's own global.
- Document (README/CHANGELOG) that formatValue/formatTime must be pure:
  label text is cached per tick and re-evaluated on formatter identity
  change, not per frame.
- Type-pair drawMultiFrame's lineCaches/lineCacheRef so passing one
  without the other can't silently disable caching; pool the pairing on
  EngineState (no per-frame literal).
- Mechanical: scroll ring-buffer size as a named constant; shared
  useBtnLayouts hook; signature builders get a reference pre-check and
  keep control-byte delimiters; unit tests for mixColorInto (+4).

Gates: tsc, eslint, jest 25 suites / 441 tests (characterization suite
unchanged), yarn install --immutable, bob build. Verified live on the
iOS simulator with the dispose path active every frame.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 CHANGELOG.md                         |  33 +++++++
 README.md                            |  14 ++-
 src/Liveline.tsx                     | 130 ++++++++++++++++++++-------
 src/draw/__tests__/orderbook.test.ts |  52 +++++++++++
 src/draw/gridLayer.ts                |   5 ++
 src/draw/index.ts                    |  28 +++---
 src/draw/orderbook.ts                |   2 +-
 src/draw/scrollLayer.ts              |  10 +++
 src/engine/gridLayer.ts              |   4 +
 src/engine/state.ts                  |  58 +++++++++++-
 src/engine/step.ts                   |   5 +-
 src/theme.ts                         |  38 +++++---
 src/useLivelineEngine.ts             |  63 ++++++++++---
 13 files changed, 365 insertions(+), 77 deletions(-)
 create mode 100644 src/draw/__tests__/orderbook.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d520c36..ef20955 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,39 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Fixed
+
+- **Native `SkPicture`s are now disposed, not left to GC.** The screen picture
+  is replaced every recorded frame (~60/sec) and the grid/scroll layer
+  pictures on every rebuild; each replacement dropped a native picture whose
+  tiny JS wrapper gave the garbage collector no reason to hurry. Every swap
+  site now retires the outgoing picture and `dispose()`s it one frame later,
+  once the tree has composited its replacement — bounding native memory on
+  exactly the long-running live charts the library targets.
+- **Suspended-time credit is race-free.** The wall-clock interval accrued
+  while the frame loop was suspended was added from the JS thread while the
+  UI thread drained the same shared value — a fast background/foreground flap
+  could double-credit an interval and leave a paused chart further in the
+  past than it ever was. Both writes now run serialized on the UI runtime.
+- **Removed series no longer haunt the toggle state.** A series removed from
+  `series` and later re-added came back hidden, and its dead id still counted
+  against the "don't hide the last visible series" guard, which could
+  therefore be defeated into a blank chart. Hidden ids are now pruned when
+  the series list changes.
+- The unrecognized-color dev warning no longer mutates a module-level
+  binding from the UI runtime (worklet-captured bindings are per-runtime
+  copies); the dedupe flag lives on the runtime's own global instead.
+
+### Changed
+
+- **`formatValue` / `formatTime` must be pure functions of their input.**
+  Axis and grid label text is cached per tick and re-evaluated when the
+  formatter's identity changes, not every frame (a per-frame `Date` +
+  string-format per label was measurable UI-thread churn). Formatters that
+  read ambient state — relative time, a captured mutable locale — now render
+  stale text; pass a new function instance to invalidate. Documented in the
+  README.
+
 ### Added
 
 - **Accessibility.** The chart is a Skia surface, so a screen reader previously
diff --git a/README.md b/README.md
index 521b280..5f17135 100644
--- a/README.md
+++ b/README.md
@@ -489,9 +489,9 @@ the bad value and the keys that are available.
 This port keeps the same SDK shape as [liveline](https://github.com/benjitaylor/liveline)
 but a few props differ because of the native/worklet environment:
 
-- **`formatValue` / `formatTime` must be worklets.** They run every frame on
-  the UI thread, not the JS thread. Add the `'worklet'` directive as the
-  first line of the function:
+- **`formatValue` / `formatTime` must be worklets.** They run on the UI
+  thread, not the JS thread. Add the `'worklet'` directive as the first line
+  of the function:
 
   ```tsx
   <Liveline
@@ -506,6 +506,14 @@ but a few props differ because of the native/worklet environment:
 
   The defaults (`v.toFixed(2)` and `HH:MM:SS`) are already worklets.
 
+  **They must also be pure functions of their input.** Label text is cached
+  per axis tick / grid line and re-computed only when the formatter's
+  *identity* changes, not every frame — so a formatter that reads anything
+  besides its argument (relative time like `"5s ago"`, a mutable
+  locale/timezone captured by closure) will render stale text. If the
+  formatting rule changes, pass a new function instance to invalidate the
+  cache.
+
 - **`style` is a React Native `ViewStyle`**, not `CSSProperties`. There is no
   `className` or `cursor` prop — those were web-only (CSS class + cursor
   affordance), and don't apply on native.
diff --git a/src/Liveline.tsx b/src/Liveline.tsx
index a5a00bb..664869e 100644
--- a/src/Liveline.tsx
+++ b/src/Liveline.tsx
@@ -73,6 +73,26 @@ interface BtnLayout {
   width: number;
 }
 
+/**
+ * Per-button on-screen frames, keyed by the button's own selector value
+ * (window seconds, mode name, …), for a `PillBar`'s sliding indicator to
+ * track. Shared by `WindowBar` and `ModeBar` — only the key type differs.
+ */
+function useBtnLayouts<K extends string | number>() {
+  const [layouts, setLayouts] = useState<Record<K, BtnLayout>>(
+    {} as Record<K, BtnLayout>
+  );
+  const onBtnLayout = useCallback((key: K, e: LayoutChangeEvent) => {
+    const { x, width } = e.nativeEvent.layout;
+    setLayouts((prev) => {
+      const cur = prev[key];
+      if (cur && cur.x === x && cur.width === width) return prev;
+      return { ...prev, [key]: { x, width } };
+    });
+  }, []);
+  return [layouts, onBtnLayout] as const;
+}
+
 /**
  * `useMemo` keyed by an explicit signature instead of a dependency array.
  *
@@ -89,6 +109,41 @@ function useStableValue<T>(signature: string, build: () => T): T {
   return ref.current.value;
 }
 
+/**
+ * Signature string for `useStableValue`, computed from an array's contents.
+ * Skips recomputing (and the per-render `.map`/`.join` allocation) unless
+ * the array's reference — or, as a mutate-in-place guard, its length —
+ * actually changed. Uses ' ' as both the field and entry delimiter so no
+ * label/id value can forge a collision with an adjacent field.
+ */
+function useArraySignature<T>(
+  arr: readonly T[] | undefined,
+  fields: (item: T) => Array<string | number>
+): string {
+  const cache = useRef<{
+    arr: readonly T[];
+    length: number;
+    sig: string;
+  } | null>(null);
+  if (!arr) return '';
+  if (
+    cache.current &&
+    cache.current.arr === arr &&
+    cache.current.length === arr.length
+  ) {
+    return cache.current.sig;
+  }
+  // \x00 / \x01 delimiters, NOT spaces: labels are consumer strings and can
+  // contain any printable character, so only control bytes make entry and
+  // field boundaries unforgeable — `[{label: 'a b'}]` must never collide
+  // with `[{label: 'a'}, {label: 'b'}]`.
+  const sig = `${arr.length}|${arr
+    .map((item) => fields(item).join('\x00'))
+    .join('\x01')}`;
+  cache.current = { arr, length: arr.length, sig };
+  return sig;
+}
+
 /**
  * A referentially stable wrapper around an optional consumer callback. Same
  * reasoning as `useStableValue`: `onModeChange` &co. are typically inline
@@ -133,15 +188,36 @@ function useActiveWindow(
 
 /** Which series the user has toggled off, plus the engine-facing id list. */
 function useHiddenSeries(
-  seriesCount: number,
+  seriesIds: string[],
   onSeriesToggle: ((id: string, visible: boolean) => void) | undefined
 ) {
   const [hiddenSeries, setHiddenSeries] = useState<Set<string>>(new Set());
   const notify = useStableHandler(onSeriesToggle);
   // Read through a ref so the toggle handler stays referentially stable as
   // series come and go — it crosses the `memo` boundary into the chip bar.
-  const countRef = useRef(seriesCount);
-  countRef.current = seriesCount;
+  const idsRef = useRef(seriesIds);
+  idsRef.current = seriesIds;
+
+  // Drop hidden ids for series that left the `series` prop. Without this a
+  // removed-then-re-added series comes back hidden, and stale ids would
+  // otherwise inflate `next.size` below, letting the last-visible guard be
+  // defeated by ids that no longer count as series at all.
+  // \x00 delimiter for the same reason as useArraySignature: ids are
+  // consumer strings, so any printable delimiter can be forged into a
+  // collision that would suppress the prune.
+  const idsSignature = seriesIds.join('\x00');
+  useEffect(() => {
+    const live = new Set(idsRef.current);
+    setHiddenSeries((prev) => {
+      let changed = false;
+      const next = new Set<string>();
+      for (const id of prev) {
+        if (live.has(id)) next.add(id);
+        else changed = true;
+      }
+      return changed ? next : prev;
+    });
+  }, [idsSignature]);
 
   const toggleSeries = useCallback(
     (id: string) => {
@@ -151,8 +227,12 @@ function useHiddenSeries(
           next.delete(id);
           notify(id, true);
         } else {
-          // Count visible series — don't hide last one
-          const visibleCount = countRef.current - next.size;
+          // Count only live ids — don't hide the last visible series
+          const liveHiddenCount = idsRef.current.reduce(
+            (n, sid) => n + (next.has(sid) ? 1 : 0),
+            0
+          );
+          const visibleCount = idsRef.current.length - liveHiddenCount;
           if (visibleCount <= 1) return prev;
           next.add(id);
           notify(id, false);
@@ -408,15 +488,7 @@ const WindowBar = memo(function WindowBarComponent({
   onSelect: (secs: number) => void;
   testID: string | undefined;
 }) {
-  const [layouts, setLayouts] = useState<Record<number, BtnLayout>>({});
-  const onBtnLayout = useCallback((secs: number, e: LayoutChangeEvent) => {
-    const { x, width } = e.nativeEvent.layout;
-    setLayouts((prev) => {
-      const cur = prev[secs];
-      if (cur && cur.x === x && cur.width === width) return prev;
-      return { ...prev, [secs]: { x, width } };
-    });
-  }, []);
+  const [layouts, onBtnLayout] = useBtnLayouts<number>();
 
   return (
     <PillBar
@@ -464,15 +536,7 @@ const ModeBar = memo(function ModeBarComponent({
   onSelect: (mode: 'line' | 'candle') => void;
   testID: string | undefined;
 }) {
-  const [layouts, setLayouts] = useState<Record<string, BtnLayout>>({});
-  const onBtnLayout = useCallback((key: string, e: LayoutChangeEvent) => {
-    const { x, width } = e.nativeEvent.layout;
-    setLayouts((prev) => {
-      const cur = prev[key];
-      if (cur && cur.x === x && cur.width === width) return prev;
-      return { ...prev, [key]: { x, width } };
-    });
-  }, []);
+  const [layouts, onBtnLayout] = useBtnLayouts<string>();
 
   return (
     <PillBar
@@ -803,8 +867,12 @@ export const Liveline = memo(function LivelineComponent({
   const { activeWindowSecs, effectiveWindowSecs, selectWindow } =
     useActiveWindow(windows, windowSecs, onWindowChange);
 
+  const seriesIds = useMemo(
+    () => seriesProp?.map((s) => s.id) ?? [],
+    [seriesProp]
+  );
   const { hiddenSeries, hiddenSeriesIds, toggleSeries } = useHiddenSeries(
-    seriesProp?.length ?? 0,
+    seriesIds,
     onSeriesToggle
   );
 
@@ -878,17 +946,15 @@ export const Liveline = memo(function LivelineComponent({
   // Everything below exists to keep <LivelineControls/> memo-stable across a
   // tick: consumers rebuild `windows`/`series` inline and pass inline arrow
   // callbacks, so those identities churn even when their contents do not.
-  const windowsSignature = windows
-    ? `${windows.length}|${windows.map((w) => `${w.secs}${w.label}`).join('
')}`
-    : '';
+  const windowsSignature = useArraySignature(windows, (w) => [w.secs, w.label]);
   const stableWindows = useStableValue(windowsSignature, () => windows);
 
   const chipSource = lastSeriesPropRef.current;
-  const chipSignature = chipSource
-    ? `${chipSource.length}|${chipSource
-        .map((s) => `${s.id}${s.label ?? ''}${s.color ?? ''}`)
-        .join('
')}`
-    : '';
+  const chipSignature = useArraySignature(chipSource, (s) => [
+    s.id,
+    s.label ?? '',
+    s.color ?? '',
+  ]);
   const seriesChips = useStableValue(chipSignature, () =>
     (chipSource ?? []).map((s, si) => ({
       id: s.id,
diff --git a/src/draw/__tests__/orderbook.test.ts b/src/draw/__tests__/orderbook.test.ts
new file mode 100644
index 0000000..dc6bb6a
--- /dev/null
+++ b/src/draw/__tests__/orderbook.test.ts
@@ -0,0 +1,52 @@
+import { mixColorInto } from '../orderbook';
+import type { SkColor } from '@shopify/react-native-skia';
+
+// ── Fakes ──────────────────────────────────────────────────────────────────
+
+/** Stand-in for SkColor — a bare Float32Array(4), same pool shape as
+ * OrderbookState.colorPool. No Skia binding needed since mixColorInto only
+ * writes normalized floats into it. */
+function makeColor(): SkColor {
+  return new Float32Array(4) as unknown as SkColor;
+}
+
+const FROM: [number, number, number] = [34, 197, 94]; // GREEN
+const TO: [number, number, number] = [239, 68, 68]; // RED
+
+describe('mixColorInto', () => {
+  it('t=0 writes `from` normalized to 0-1, alpha 1', () => {
+    const out = mixColorInto(makeColor(), FROM, TO, 0);
+    const o = out as unknown as Float32Array;
+    expect(o[0]).toBeCloseTo(34 / 255);
+    expect(o[1]).toBeCloseTo(197 / 255);
+    expect(o[2]).toBeCloseTo(94 / 255);
+    expect(o[3]).toBe(1);
+  });
+
+  it('t=1 writes `to` normalized to 0-1, alpha 1', () => {
+    const out = mixColorInto(makeColor(), FROM, TO, 1);
+    const o = out as unknown as Float32Array;
+    expect(o[0]).toBeCloseTo(239 / 255);
+    expect(o[1]).toBeCloseTo(68 / 255);
+    expect(o[2]).toBeCloseTo(68 / 255);
+    expect(o[3]).toBe(1);
+  });
+
+  it('mid t blends and rounds each channel to an int before normalizing', () => {
+    const out = mixColorInto(makeColor(), FROM, TO, 0.5);
+    const o = out as unknown as Float32Array;
+    // r: 34 + (239-34)*0.5 = 136.5 -> round 137
+    expect(o[0]).toBeCloseTo(137 / 255);
+    // g: 197 + (68-197)*0.5 = 132.5 -> round 133
+    expect(o[1]).toBeCloseTo(133 / 255);
+    // b: 94 + (68-94)*0.5 = 81 -> round 81
+    expect(o[2]).toBeCloseTo(81 / 255);
+    expect(o[3]).toBe(1);
+  });
+
+  it('returns the same `out` reference it was given (in-place write, no alloc)', () => {
+    const out = makeColor();
+    const result = mixColorInto(out, FROM, TO, 0.5);
+    expect(result).toBe(out);
+  });
+});
diff --git a/src/draw/gridLayer.ts b/src/draw/gridLayer.ts
index 86656ab..e32d9f1 100644
--- a/src/draw/gridLayer.ts
+++ b/src/draw/gridLayer.ts
@@ -15,6 +15,10 @@ import type { ChartLayout, LivelinePalette } from '../types';
 
 export interface GridLayerSlot<Picture> {
   picture: Picture | null;
+  /** Pictures this slot replaced, awaiting `dispose()` — drained by
+   * `disposeRetired` (engine/state.ts) at the top of the next frame. The
+   * slot can't reach `EngineState`, so it carries its own bin. */
+  retired: Picture[];
   /** Consecutive frames the key has matched. Compared against
    * QUIESCENT_FRAME_THRESHOLD by the caller — grid label fades are
    * documented (engine/quiescence.ts) to converge well under that many
@@ -40,6 +44,7 @@ export function createGridLayerSlot<Picture>(): GridLayerSlot<Picture> {
   'worklet';
   return {
     picture: null,
+    retired: [],
     settledFrames: 0,
     kMinVal: 0,
     kMaxVal: 0,
diff --git a/src/draw/index.ts b/src/draw/index.ts
index cb15ba2..bc3809a 100644
--- a/src/draw/index.ts
+++ b/src/draw/index.ts
@@ -439,8 +439,6 @@ export interface MultiSeriesDrawOptions {
   now_ms: number;
   /** Primary palette (from first series) for grid/axis/crosshair colors */
   primaryPalette: LivelinePalette;
-  /** Per-series line path caches, keyed by series id (see draw/lineCache) */
-  lineCaches?: Map<string, LineCacheSlot>;
   /** Which backing arrays series data came from: 0 live / 1 paused / 2 stash */
   multiDataSource?: number;
   /** Cross-frame grid picture cache (see draw/gridLayer, engine/gridLayer) */
@@ -449,10 +447,18 @@ export interface MultiSeriesDrawOptions {
    * owned by `EngineState`, refilled once per series, never allocated here.
    * See `LineDrawArgs`. */
   lineArgs: LineDrawArgs;
-  /** Pooled `LineCacheRef` for the per-series cache lookup, same deal — its
-   * `slot` is repointed each iteration instead of allocating a ref per
-   * series per frame. Omit to disable the per-series cache entirely. */
-  lineCacheRef?: LineCacheRef;
+  /** Per-series line path cache (see draw/lineCache). `caches` and `ref` are
+   * required together — a ref with no caches map (or vice versa) can't do
+   * anything, so the pairing is one optional property instead of two, to
+   * rule out silently losing caching by passing only one. Omit entirely to
+   * disable the per-series cache. */
+  lineCache?: {
+    /** Keyed by series id */
+    caches: Map<string, LineCacheSlot>;
+    /** Pooled `LineCacheRef`, `slot` repointed each iteration instead of
+     * allocating a ref per series per frame. */
+    ref: LineCacheRef;
+  };
 }
 
 /**
@@ -520,16 +526,16 @@ export function drawMultiFrame(
     // interior revision invalidates just that series' cache — the key's
     // len/firstT/lastT/lastV heuristic can't see interior changes on its own.
     let cacheRef: LineCacheRef | undefined;
-    if (opts.lineCaches !== undefined && opts.lineCacheRef !== undefined) {
-      let slot = opts.lineCaches.get(s.id);
+    if (opts.lineCache !== undefined) {
+      let slot = opts.lineCache.caches.get(s.id);
       if (slot === undefined) {
         slot = createLineCacheSlot();
-        opts.lineCaches.set(s.id, slot);
+        opts.lineCache.caches.set(s.id, slot);
       }
-      // Pooled ref (see MultiSeriesDrawOptions.lineCacheRef) repointed at
+      // Pooled ref (see MultiSeriesDrawOptions.lineCache.ref) repointed at
       // this series' slot, rather than a fresh literal per series per frame.
       // Safe because `drawLine` reads it synchronously and retains nothing.
-      cacheRef = opts.lineCacheRef;
+      cacheRef = opts.lineCache.ref;
       cacheRef.slot = slot;
       cacheRef.dataRev = s.dataRev;
       cacheRef.dataSource = opts.multiDataSource ?? 0;
diff --git a/src/draw/orderbook.ts b/src/draw/orderbook.ts
index a14d2af..3a44fde 100644
--- a/src/draw/orderbook.ts
+++ b/src/draw/orderbook.ts
@@ -91,7 +91,7 @@ export function createOrderbookState(): OrderbookState {
 // stale or in-flight reference to a pool slot. Each iteration also uses a
 // distinct slot (indexed by loop position, not label identity), so there is
 // no intra-frame slot collision either.
-function mixColorInto(
+export function mixColorInto(
   out: SkColor,
   from: readonly [number, number, number],
   to: readonly [number, number, number],
diff --git a/src/draw/scrollLayer.ts b/src/draw/scrollLayer.ts
index 4b6a7ad..fd0b79c 100644
--- a/src/draw/scrollLayer.ts
+++ b/src/draw/scrollLayer.ts
@@ -99,6 +99,11 @@ export interface ScrollLayerSlot<Picture> {
    * first build; that null is also the slot's validity flag, matching
    * `LineCacheSlot.prefix` and `GridLayerSlot.picture`. */
   picture: Picture | null;
+  /** Pictures this slot replaced, awaiting `dispose()` — drained by
+   * `disposeRetired` (engine/state.ts) one frame after replacement, once the
+   * tree has composited the successor. The slot can't reach `EngineState`,
+   * so it carries its own bin (mirrors `GridLayerSlot.retired`). */
+  retired: Picture[];
 
   /** Committed numeric key (the inputs the current `picture` was built from). */
   kNum: number[];
@@ -119,6 +124,7 @@ export function createScrollLayerSlot<Picture>(): ScrollLayerSlot<Picture> {
   'worklet';
   return {
     picture: null,
+    retired: [],
     kNum: [],
     kNumLen: 0,
     kRef: [],
@@ -233,6 +239,10 @@ export function scrollLayerBuilt<Picture>(
   picture: Picture
 ): void {
   'worklet';
+  // Retire (don't drop) the outgoing picture — it may still be composited
+  // by the declarative tree until this frame's publish lands, so it is
+  // disposed one frame later by disposeRetired (engine/state.ts), not here.
+  if (slot.picture !== null) slot.retired.push(slot.picture);
   slot.picture = picture;
   scrollLayerCommitKey(slot);
 }
diff --git a/src/engine/gridLayer.ts b/src/engine/gridLayer.ts
index 5722c5a..5749da2 100644
--- a/src/engine/gridLayer.ts
+++ b/src/engine/gridLayer.ts
@@ -49,6 +49,10 @@ export function updateGridLayer(
   );
   const subCtx = createCanvas2D(canvas, fonts, gridCache);
   drawGrid(subCtx, layout, palette, formatValue, gridState, dt);
+  // Retire (don't drop) the outgoing picture: its JS wrapper is tiny but
+  // the native picture is not, and this re-records every frame while the
+  // key churns. Disposed next frame by disposeRetired (engine/state.ts).
+  if (slot.picture !== null) slot.retired.push(slot.picture);
   slot.picture = recorder.finishRecordingAsPicture();
   writeGridLayerKey(slot, layout, palette, formatValue);
   slot.settledFrames = hit ? slot.settledFrames + 1 : 0;
diff --git a/src/engine/state.ts b/src/engine/state.ts
index a9c0323..8f32464 100644
--- a/src/engine/state.ts
+++ b/src/engine/state.ts
@@ -149,6 +149,24 @@ export interface EngineState {
   /** Per-series line path caches, multi-series mode — keyed by series id,
    * pruned alongside displayValues when series are removed */
   lineCaches: Map<string, LineCacheSlot>;
+  /** Pooled `{ caches, ref }` pairing handed to `drawMultiFrame` (see
+   * MultiSeriesDrawOptions.lineCache, which requires the two together).
+   * Both members are the stable `lineCaches`/`lineCacheRef` objects above,
+   * so this is built once here rather than as a fresh literal every
+   * multi-series frame at the call site. */
+  multiLineCache: { caches: Map<string, LineCacheSlot>; ref: LineCacheRef };
+  /** Screen pictures replaced by a newer recording, awaiting `dispose()`.
+   * The screen picture is swapped every recorded frame (~60/sec), and the
+   * grid and scroll layers swap theirs on every rebuild — each swap drops a
+   * native SkPicture whose JS wrapper is tiny, so waiting on the UI
+   * runtime's GC lets tens of native pictures per second pile up on a live
+   * feed. Instead every swap site retires the outgoing picture (this array
+   * for the screen picture; `GridLayerSlot.retired` / `ScrollLayerSlot.retired`
+   * for the layer caches, which never see `EngineState`), and
+   * `disposeRetired` drains all three at the top of the next frame
+   * callback — by which point the declarative tree has composited the
+   * replacement, so nothing retired can still be on screen. */
+  retiredPictures: SkPicture[];
   /** Cross-frame grid (gridlines + Y-axis labels) SkPicture cache (see
    * engine/gridLayer). Single shared instance across modes since only one
    * mode draws per frame. */
@@ -415,9 +433,16 @@ export function createEngineState(
 ): EngineState {
   'worklet';
   // Built before the literal so `lineCacheRef` can point at the very same
-  // slot object rather than a copy.
+  // slot object rather than a copy — and so `multiLineCache` can pair the
+  // very same map and ref the literal stores.
   const lineCache = createLineCacheSlot();
   const candleCache = createCandleCacheSlot();
+  const lineCacheRef: LineCacheRef = {
+    slot: lineCache,
+    dataRev: 0,
+    dataSource: 0,
+  };
+  const lineCaches = new Map<string, LineCacheSlot>();
   return {
     displayValue: value,
     displayValues: new Map<string, number>(),
@@ -471,10 +496,12 @@ export function createEngineState(
       pathTail: false,
     },
     lineCache: lineCache,
-    lineCacheRef: { slot: lineCache, dataRev: 0, dataSource: 0 },
+    lineCacheRef,
     lineDrawArgs: createLineDrawArgs(),
     candleDrawArgs: createCandleDrawArgs(),
-    lineCaches: new Map<string, LineCacheSlot>(),
+    lineCaches,
+    multiLineCache: { caches: lineCaches, ref: lineCacheRef },
+    retiredPictures: [],
     gridLayer: createGridLayerSlot<SkPicture>(),
     gridLayerCache: createSkiaCache(),
     lineScroll: createScrollLayerSlot<SkPicture>(),
@@ -574,3 +601,28 @@ export function createEngineState(
     lastAccrualTimestamp: null,
   };
 }
+
+/**
+ * Dispose every picture retired on a PREVIOUS frame — the screen picture's
+ * bin plus the grid and scroll layer slots' own bins (see
+ * `EngineState.retiredPictures`). Called at the top of the frame callback,
+ * before anything records: entries are pushed mid-frame, after this ran, so
+ * every entry drained here has survived at least one full vsync and the tree
+ * has composited its replacement.
+ *
+ * `dispose()` releases only the JS wrapper's reference; a retired grid or
+ * scroll picture that an earlier screen recording embedded via
+ * `drawPicture` stays alive through that recording's own native ref.
+ */
+export function disposeRetired(s: EngineState): void {
+  'worklet';
+  const screen = s.retiredPictures;
+  for (let i = 0; i < screen.length; i++) screen[i]!.dispose();
+  screen.length = 0;
+  const grid = s.gridLayer.retired;
+  for (let i = 0; i < grid.length; i++) grid[i]!.dispose();
+  grid.length = 0;
+  const scroll = s.lineScroll.retired;
+  for (let i = 0; i < scroll.length; i++) scroll[i]!.dispose();
+  scroll.length = 0;
+}
diff --git a/src/engine/step.ts b/src/engine/step.ts
index b6cf5d1..1967667 100644
--- a/src/engine/step.ts
+++ b/src/engine/step.ts
@@ -1640,11 +1640,12 @@ export function engineStep(
       pauseProgress,
       now_ms,
       primaryPalette: cfg.palette,
-      lineCaches: s.lineCaches,
       multiDataSource: dataSourceOf(useMultiStash, s.pausedMultiData !== null),
       gridLayer: s.gridLayer,
       lineArgs: s.lineDrawArgs,
-      lineCacheRef: s.lineCacheRef,
+      // Pooled pairing (see EngineState.multiLineCache) — a literal here
+      // would allocate once per multi-series frame.
+      lineCache: s.multiLineCache,
     });
 
     // During reverse morph (chart → loading/empty), overlay the empty text
diff --git a/src/theme.ts b/src/theme.ts
index bf9c5cb..b9ed783 100644
--- a/src/theme.ts
+++ b/src/theme.ts
@@ -1,12 +1,28 @@
 import type { ThemeMode, LivelinePalette, LivelineSeries } from './types';
 
-// Last value warned about by `parseColorRgb` below. That function is called
-// from the frame path (`draw/dot.ts` parses `palette.line` and
-// `palette.badgeOuterBg` while scrub-dimming), so an unconditional dev warning
-// would fire up to 60 times a second for as long as a bad colour is set —
-// noisier than the silent fallback it replaced. One string compare per call,
-// no allocation, and a bad colour still reports exactly once.
-let lastWarnedColor = '';
+/**
+ * Dev-only warning for an unparseable colour, deduped by last value.
+ *
+ * `parseColorRgb` is called from the frame path (`draw/dot.ts` parses
+ * `palette.line` and `palette.badgeOuterBg` while scrub-dimming), so an
+ * unconditional warning would fire up to 60 times a second for as long as a
+ * bad colour is set. The dedupe flag lives on `globalThis`, NOT in a
+ * module-level `let`: this runs as a worklet on the UI runtime, where the
+ * plugin captures module bindings per-runtime — a captured `let` is at best
+ * a stale per-runtime copy and at worst not writable at all. The global is
+ * per-runtime too (so a bad colour can warn once on each runtime that parses
+ * it), which is the acceptable cost of not mutating captured state.
+ */
+function warnUnrecognizedColor(color: string): void {
+  'worklet';
+  const g = globalThis as { __livelineWarnedColor?: string };
+  if (g.__livelineWarnedColor === color) return;
+  g.__livelineWarnedColor = color;
+  console.warn(
+    `[react-native-liveline] parseColorRgb: unrecognized color "${color}" — ` +
+      'expected #rgb, #rgba, #rrggbb, #rrggbbaa, rgb(), or rgba(). Falling back to grey.'
+  );
+}
 
 /**
  * Parse any CSS color string to [r, g, b].
@@ -41,12 +57,8 @@ export function parseColorRgb(color: string): [number, number, number] {
     const rgb = color.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/);
     if (rgb) return [+rgb[1]!, +rgb[2]!, +rgb[3]!];
   }
-  if (__DEV__ && color !== lastWarnedColor) {
-    lastWarnedColor = color;
-    console.warn(
-      `[react-native-liveline] parseColorRgb: unrecognized color "${color}" — ` +
-        'expected #rgb, #rgba, #rrggbb, #rrggbbaa, rgb(), or rgba(). Falling back to grey.'
-    );
+  if (__DEV__) {
+    warnUnrecognizedColor(color);
   }
   return [128, 128, 128];
 }
diff --git a/src/useLivelineEngine.ts b/src/useLivelineEngine.ts
index 42020d2..9e8446d 100644
--- a/src/useLivelineEngine.ts
+++ b/src/useLivelineEngine.ts
@@ -8,6 +8,7 @@ import {
 } from '@shopify/react-native-skia';
 import {
   runOnJS,
+  runOnUI,
   useFrameCallback,
   useReducedMotion,
   useSharedValue,
@@ -31,7 +32,11 @@ import {
   type SkiaCache,
 } from './draw/canvas2d';
 import { engineStep } from './engine/step';
-import { createEngineState, type EngineState } from './engine/state';
+import {
+  createEngineState,
+  disposeRetired,
+  type EngineState,
+} from './engine/state';
 import type {
   EngineConfig,
   EngineConfigStep,
@@ -73,6 +78,13 @@ const EMPTY_CANDLES: CandlePoint[] = [];
 // previously-seen data (a series appearing for the first time).
 const EMPTY_POINTS: LivelinePoint[] = [];
 
+/** Size of the preallocated scroll-transform ring (`scrollTransformBufs`
+ * below). Three rather than two gives two frames of separation before a
+ * buffer is reused, so a consumer still holding last frame's array can't
+ * observe it mutate. Ties the array length to both `%` rotations — resize
+ * here, nowhere else. */
+const SCROLL_TRANSFORM_BUF_COUNT = 3;
+
 /**
  * Strip `data`/`candles` off the caller's config for mirroring into `cfg`
  * — they're synced through their own delta-updated shared values instead
@@ -402,9 +414,11 @@ export function useLivelineEngine(
   const size = useSharedValue({ w: 0, h: 0 });
   const hoverX = useSharedValue<number | null>(null);
   // Wall-clock milliseconds the frame loop spent suspended, waiting to be
-  // credited to `timeDebt` by the next frame that runs. Written from JS (the
-  // AppState listener / the `active` effect below, which are the only things
-  // that know a suspension happened) and drained on the UI thread.
+  // credited to `timeDebt` by the next frame that runs. The JS side (the
+  // AppState listener / the `active` effect below, the only things that know
+  // a suspension happened) computes the interval but accumulates it via
+  // `runOnUI`, so every read-modify-write — the `+=` and the frame
+  // callback's drain to 0 — happens serialized on the UI runtime.
   //
   // A plain number shared value rather than a reach into `state.value`:
   // EngineState holds Skia handles and is owned by the UI runtime, so the JS
@@ -450,11 +464,11 @@ export function useLivelineEngine(
   // the derivation instead of outside it, and self-assignment
   // (`x.value = x.value` after mutating) is not a notification contract
   // Reanimated documents or honors.
-  const scrollTransformBufs = useSharedValue<Transforms3d[]>([
-    [{ translateX: 0 }],
-    [{ translateX: 0 }],
-    [{ translateX: 0 }],
-  ]);
+  const scrollTransformBufs = useSharedValue<Transforms3d[]>(
+    Array.from({ length: SCROLL_TRANSFORM_BUF_COUNT }, () => [
+      { translateX: 0 },
+    ])
+  );
   const scrollBufIdx = useSharedValue(0);
   const valueText = useSharedValue('');
   const valueColor = useSharedValue('');
@@ -484,6 +498,13 @@ export function useLivelineEngine(
       state.value = s;
     }
 
+    // Dispose pictures retired on previous frames (screen, grid layer,
+    // scroll layer — see EngineState.retiredPictures). First thing, before
+    // any recording: entries are pushed later in the callback, so everything
+    // drained here is at least one vsync old and its replacement has
+    // composited.
+    disposeRetired(s);
+
     const now_ms = info.timestamp ?? 0;
 
     // --- Suspended-loop credit. `frame.setActive(false)` stops accrual but
@@ -620,7 +641,7 @@ export function useLivelineEngine(
           // Rotate to the next preallocated buffer, mutate it, then assign:
           // a fresh identity for the mapper with no allocation. See
           // `scrollTransformBufs`.
-          const i = (scrollBufIdx.value + 1) % 3;
+          const i = (scrollBufIdx.value + 1) % SCROLL_TRANSFORM_BUF_COUNT;
           scrollBufIdx.value = i;
           const buf = scrollTransformBufs.value[i]!;
           (buf[0] as { translateX: number }).translateX = dxEx;
@@ -652,6 +673,11 @@ export function useLivelineEngine(
     frameInputs.candles = candlesBuf.value;
     frameInputs.multiData = multiDataBuf.value;
     const result = engineStep(ctx, c, s, frameInputs);
+    // Retire the outgoing screen picture — replaced every recorded frame,
+    // so leaving it to GC is ~60 native pictures/sec of pressure (see
+    // EngineState.retiredPictures). Still composited until this assignment
+    // lands, hence retire-now/dispose-next-frame rather than dispose here.
+    s.retiredPictures.push(screenPicture.value);
     screenPicture.value = recorder.finishRecordingAsPicture();
     // Publish this frame's scroll layer. `null` means the layer must not
     // composite at all (see StepOutput.scrollPicture) — the empty 1×1
@@ -697,7 +723,7 @@ export function useLivelineEngine(
     // Exact value always wins over whatever a skipped vsync extrapolated, so
     // extrapolation error can never accumulate past one frame. Same
     // rotate-mutate-assign as the paced-out branch above.
-    const bufIdx = (scrollBufIdx.value + 1) % 3;
+    const bufIdx = (scrollBufIdx.value + 1) % SCROLL_TRANSFORM_BUF_COUNT;
     scrollBufIdx.value = bufIdx;
     const buf = scrollTransformBufs.value[bufIdx]!;
     (buf[0] as { translateX: number }).translateX = dx;
@@ -758,7 +784,20 @@ export function useLivelineEngine(
           // `Math.max(0, ...)` guards a wall clock that stepped backwards
           // (NTP correction, user changing the device time zone/clock while
           // the app was away) — never credit negative debt.
-          pendingSuspendedMs.value += Math.max(0, Date.now() - at);
+          const creditMs = Math.max(0, Date.now() - at);
+          if (creditMs > 0) {
+            // Accumulate ON the UI runtime, where the frame callback's
+            // drain (`pendingSuspendedMs.value = 0`) also runs. A JS-side
+            // `+=` is a cross-thread read-modify-write: a fast
+            // background/foreground flap could read a value the UI thread
+            // had already drained but not yet propagated back, re-adding an
+            // interval that was already credited. On the UI runtime both
+            // writers are serialized and the race is gone.
+            runOnUI((ms: number) => {
+              'worklet';
+              pendingSuspendedMs.value += ms;
+            })(creditMs);
+          }
         }
       } else if (suspendedAtRef.current === null) {
         // Only the FIRST transition into suspension stamps the clock: with