refactor(highway): carve the PURE geometry primitives into highway-geometry.js (R3c) (#915)

6 functions, 53 lines. highway.js 4,158 -> 4,105. NOT ONE CALL SITE CHANGES.

project, roundRect, bnvNormalizedPoints, teachingFingerLabel, teachingDegreeLabel,
chordHarmonyLabels — the shared primitives every drawing function leans on.

━━━ PURITY IS THE WHOLE POINT OF THIS SLICE ━━━

Every one of these is a pure function of its arguments. None touches hwState. None closes over
the canvas context — roundRect() already took `ctx` explicitly, and the rest need nothing but
numbers. project() reads only the module-level constants from #914.

That matters because createHighway() is a FACTORY: a plugin can build a second highway for its
own panel, so anything holding per-instance state must be PASSED hwState rather than importing
it, or two panels silently share one clock and palette. These six hold no state at all, so
they move VERBATIM — the module boundary is invisible to every caller.

The asserts are mechanical and in the extractor: it REFUSES to move a function whose body
mentions hwState, or that references `ctx` without taking it as a parameter. Purity is
checked, not assumed.

━━━ WHAT IS DELIBERATELY LEFT BEHIND ━━━

The four primitives that DO need hwState — fretX, fillTextReadable, _noteState, _paintGemGlow
— stay in the factory for now. They need an explicit hwState parameter threaded through 53
call sites, which is a real behavioural change and belongs in its own commit rather than
smuggled in beside a provably-identical move. Separating the provable from the risky is the
whole discipline of this epic.

TESTS. Three harnesses brace-match these functions out of the source and run them in a
sandbox; they now read static/js/highway-geometry.js. `export function x` still contains
`function x`, so the extractor needed no change — only the path.

VERIFIED. A/B against origin/main: 15 probes IDENTICAL, zero page errors. PERF GATE PASSES AT
1.91ms against its 12ms budget — and this is the one that could plausibly have cost something:
project() runs for every visible note on every frame and is now a CROSS-MODULE call. It costs
nothing measurable. That is the answer #910 was built to give.

node 1045, pytest 2416, ESLint 0, Codex 0.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

static/js/highway-geometry.js

@@ -0,0 +1,79 @@
+// highway.js's PURE geometry + label primitives.
+//
+// Every function here is a pure function of its arguments. None of them touches hwState, and
+// none closes over the canvas context — roundRect() already took `ctx` explicitly, and the
+// rest need nothing but numbers. project() reads only the module-level constants from
+// ./highway-constants.js.
+//
+// THAT PURITY IS WHY THIS SLICE IS SAFE, and why it is the one to do first. createHighway() is
+// a FACTORY — a plugin can build a second highway for its own panel — so anything holding
+// per-instance state (hwState) must be passed it as an argument rather than importing it, or
+// two panels silently share one clock and palette. These six hold no state at all, so they
+// move VERBATIM: not one call site changes.
+//
+// The primitives that DO need hwState (fretX, fillTextReadable, _noteState, _paintGemGlow)
+// are deliberately left behind. They need an explicit hwState parameter threaded through 53
+// call sites, which is a real change and belongs in its own commit, not smuggled in beside a
+// provably-identical move.
+import { VISIBLE_SECONDS, Z_CAM, Z_MAX } from './highway-constants.js';
+
+// ── Projection ───────────────────────────────────────────────────────
+export function project(tOffset) {
+    if (tOffset > VISIBLE_SECONDS || tOffset < -0.05) return null;
+    if (tOffset < 0) return { y: 0.82 + Math.abs(tOffset) * 0.3, scale: 1.0 };
+
+    const z = tOffset * (Z_MAX / VISIBLE_SECONDS);
+    const denom = z + Z_CAM;
+    if (denom < 0.01) return null;
+    const scale = Z_CAM / denom;
+    const y = 0.82 + (0.08 - 0.82) * (1.0 - scale);
+    return { y, scale };
+}
+
+export function bnvNormalizedPoints(bnv, sus) {
+    if (!Array.isArray(bnv) || bnv.length === 0) return [];
+    // Map each point's time over the NOTE's span [0, sus] so it sits at its
+    // real fraction of the note (a bend that completes before the note ends
+    // draws short of the glyph's right edge). Fall back to the curve's own
+    // t-range only when the note has no usable sustain.
+    if (Number.isFinite(sus) && sus > 0) {
+        return bnv.map(p => ({ x: Math.min(Math.max(p.t / sus, 0), 1), v: p.v }));
+    }
+    const t0 = bnv[0].t;
+    const span = bnv[bnv.length - 1].t - t0;
+    return bnv.map(p => ({ x: span > 0 ? (p.t - t0) / span : 0, v: p.v }));
+}
+
+export function teachingFingerLabel(fg) {
+    if (!Number.isInteger(fg) || fg < 0 || fg > 4) return '';
+    return fg === 0 ? 'T' : String(fg);
+}
+
+export function teachingDegreeLabel(sd) {
+    if (!Number.isInteger(sd) || sd < 0 || sd > 11) return '';
+    return String(sd);
+}
+
+export function chordHarmonyLabels(fn, voicing, caged, guideTones) {
+    const rn = (fn && typeof fn.rn === 'string') ? fn.rn.trim() : '';
+    const vc = (typeof voicing === 'string') ? voicing.trim() : '';
+    const cg = (typeof caged === 'string' && /^[CAGED]$/.test(caged.trim()))
+        ? 'CAGED: ' + caged.trim() : '';
+    const gt = Array.isArray(guideTones)
+        ? guideTones.filter(n => Number.isInteger(n) && n >= 0 && n <= 11) : [];
+    return { rn, voicing: vc, caged: cg, guideTones: gt.length ? 'gt ' + gt.join(',') : '' };
+}
+
+export function roundRect(ctx, x, y, w, h, r) {
+    ctx.beginPath();
+    ctx.moveTo(x + r, y);
+    ctx.lineTo(x + w - r, y);
+    ctx.quadraticCurveTo(x + w, y, x + w, y + r);
+    ctx.lineTo(x + w, y + h - r);
+    ctx.quadraticCurveTo(x + w, y + h, x + w - r, y + h);
+    ctx.lineTo(x + r, y + h);
+    ctx.quadraticCurveTo(x, y + h, x, y + h - r);
+    ctx.lineTo(x, y + r);
+    ctx.quadraticCurveTo(x, y, x + r, y);
+    ctx.closePath();
+}