perf: skip building the candle-mode line overlay when it isn't drawn

[fuller]

Summary

• Skip dead work in candle mode. In steady candle mode the engine built the line overlay's point array every frame (one object per visible candle, or per visible tick plus a closeRefs array on the density-blend branch) — which drawCandleFrame then discarded, because the overlay is only drawn during a line-mode or reveal transition. Now built only when it will be used.
• Consolidate the presence gate. The drawer's "is the overlay visible" calculation and the engine's "should I build its points" check were separate inline expressions sharing a hardcoded 0.01. Both now live in draw/lineOverlay.ts, with a test asserting the invariant that keeps them safe.
• PLAN_MAINT.md — a maintainability survey of src/ for handoff (see below).

Honest note on the perf claim

This measured no CPU delta. Three arms on the Candles tab, iPhone 17 Pro sim, Debug, 3×20s each:

arm	runs	mean
before	65.8 / 65.7 / 64.6	65.4%
after	64.2 / 67.6 / 68.9	66.9%
after (drift control)	63.2 / 65.3 / 65.2	64.6%

The two after arms bracket before, and within-arm spread exceeds the between-arm difference. This PR removes provably dead work rather than making live work faster; the effect is below the measurement floor on a Debug simulator build under host load. It is not a speedup claim.

A second change from the same session — pooled decimation scratch — was written, tested green, then deliberately dropped: it required a 17th positional parameter on drawLine, and paying that for an unmeasurable win was the wrong trade. It's queued in PLAN_MAINT.md item 4 to be redone once drawLine takes an options object.

Test Coverage

engineStep has no tests (1818 lines — the gap documented in PLAN_MAINT.md item 6), so rather than ship untested branch logic, the gate was extracted as a pure predicate and tested directly.

NEW CODE PATHS
==============
[+] src/draw/lineOverlay.ts
    ├── lineOverlayPresence()      [***] 7 tests — thresholds, cubed vs linear reveal,
    │                                    monotonicity, range bounds
    └── shouldBuildLineOverlay()   [***] 5 tests — incl. the invariant grid

[+] src/engine/step.ts
    └── wantLineVisible gate       [***] covered via shouldBuildLineOverlay + on-device

The load-bearing test asserts over a dense grid of both inputs that shouldBuildLineOverlay is true wherever the drawer would draw — i.e. the builder can only skip frames the drawer would ignore. Mutation-checked: narrowing the gate to mirror the drawer's threshold exactly makes 3 tests fail with the offending input pair in the diff.

Tests: 148 → 160 (+12 new), 8 → 9 suites.

Equivalence evidence

The extracted lineOverlayPresence is bit-identical to the previous inline expression across 1,002,001 sampled (lineModeProg, chartReveal) pairs — 0 differing, max delta 0.

Pre-Landing Review

2 issues, both auto-fixed:

• draw/index.ts:756,801,846 — three literal 0.01 comparisons left on the magic number after extracting LINE_OVERLAY_MIN_PRESENCE, recreating the drift risk the extraction removes → now use the constant.
• CHANGELOG.md — entry described only the perf gate, not the extraction → added.

Checked and clear: no skipped side effects across the new branches (closeRefs/refIdx are fully scoped inside the guard); fullLineMode still read; the reveal-padding block is unreachable when the gate is false.

Design Review

No frontend files changed — skipped.

Device verification

Because this adds a new module whose worklets are called from the frame worklet — a shape this repo has been bitten by before (a SharedValue closure that passed every test, then failed on frame 2) — every path was checked on the iOS simulator, not just in jest:

• Steady candle mode (gate false) — renders correctly, well past frame 2
• Line-mode-within-candles (gate true) — line, fill, badge, dashed reference line, live dot all present
• Line tab — unaffected

The last check specifically proves LINE_OVERLAY_MIN_PRESENCE resolves across the module boundary; if it didn't, lp > undefined would be false and the overlay would be absent entirely.

PLAN_MAINT.md

Survey of all 47 files in src/. Seven ranked items with verified line numbers. Highlights:

• engineStep is a ~1700-line function with three inline pipelines; 132 lines (48% of the smaller pipeline) are duplicated, largest identical run 53 lines
• The layout literal is constructed byte-identically 3×
• A real leak: EngineState has eight per-series Maps; four are pruned by copy-pasted loops, and seriesAlpha has the same lifecycle but was never added
• 11 functions take ≥9 positional parameters (worst: 19)
• Coverage is inverted — the three largest files have zero tests

Version

No bump. Nothing user-facing shipped; entries sit under ## [Unreleased]. This repo has no VERSION file — it versions via package.json (currently 0.2.0, released 2026-07-27).

Test plan

• yarn typecheck — exit 0
• yarn lint — exit 0
• yarn test — 160 tests, 9 suites, 0 failures
• Each commit independently valid (bisectable — verified commit 1 has no forward reference)
• iOS simulator: steady candle, line-within-candle, Line tab

🤖 Generated with Claude Code