1 Commits

Author	SHA1	Message	Date
Byron Gamatos	64f04565e2	refactor(app): the host seam + carve section practice out of app.js (R3a) (#887) ... static/js/host.js (99) + static/js/section-practice.js (1,214). app.js 9,461 → 8,409. THE FIRST SLICE OUT OF THE STRONGLY-CONNECTED CORE. What is left in app.js is not a tree, it is a cycle: seeding a dependency closure from section-practice, from loops, from count-in, or from the JUCE seek shim all return the SAME 178-function set, and setLoop() and practiceSection() call each other directly. No closure-based carve can cut it at any seed. So it is cut BY NAME, and the calls back into app.js go through a host seam. 61 functions + its own 24 _sectionPractice*/_sectionParents* scalars (read nowhere else) move out. 11 hooks come back in. 4 of those are read-only GETTERS — loopA/loopB/_audioSeekGen/_loopMutationGen are only ever READ here, never written, so app.js keeps owning them and NO state container is needed (a 977-site lift avoided). app.js used to reach IN and reset the module's state by hand (clearLoop() zeroed the selection; changeArrangement() invalidated the parent count). It cannot now — an imported binding is read-only — so those are exported as resetSelection() and invalidateParentCount(). Strictly better: the module owns its own invariants instead of trusting two callers on the far side of the file to zero the right three fields. ═══ THE SILENT-NO-OP PROBLEM, SOLVED ═══ The obvious host seam is an object of no-op defaults. That is a TRAP and we walked into it once: the plugin loader's seam defaulted populateVizPicker to `() => {}`, so a dropped wiring line would have left the viz picker quietly not refreshing with NO test, boot check, or bot noticing. Two layers stop it here: 1. RUNTIME — host.js is a Proxy with NO defaults and NO stubs. Reading an unwired hook THROWS. An unwired hook cannot degrade into a no-op because there is nothing to degrade INTO. configureHost() also rejects a non-function at WIRE time, and refuses to run twice. 2. STATIC — tests/js/host_contract.test.js asserts the hooks the modules USE are exactly the hooks app.js WIRES. This is the layer that matters: a runtime throw only fires if the broken path executes, and the whole danger of a seam is the paths that never run in a smoke test. VERIFIED TO BITE in all three drift directions: drop a hook from configureHost -> fails; rename host.setLoop in the module -> fails; wire a hook nobody uses -> fails. Writing that guard took three tries and each failure is instructive: (a) the configureHost regex anchored `});` at column 0, ran past the indented close, and swallowed app.js's 66-name window contract — 77 "hooks"; (b) an import-stripping regex with `[\s\S]*?` ate 14,000 characters INCLUDING the drift the bite test was meant to catch — a guard with a hole is worse than no guard, because you trust it; (c) `host.js'` in the import path backtracked from `js` to a "hook" called `j`. The bite tests are what surfaced all three. CODEX FOUND A REAL RACE [P2]. configureHost() was inside the async boot function, after several awaits — but the window handlers (onPhraseNext, …) go live during app.js's SYNCHRONOUS module evaluation. A user clicking one in that window would hit "[host] … was read before configureHost() ran". It is now a bare top-level statement sitting immediately before the window contract, so the seam is always wired before a handler can be reached. Verified live: invoking a handler 1.2s in — well before the boot awaits settle — works. VERIFIED. A/B against origin/main in two browsers with a REAL song loaded: popover toggle, practice-mode change, phrase-next, and clearLoop (all of which cross the seam — setLoop/clearLoop/_audioTime/loopA/loopB) — IDENTICAL, zero page errors. Since an unwired hook throws, a live app is itself proof the seam is wired. Harnesses: section_practice_dismiss retargeted; loop_api's clearLoop sandbox gains a resetSelection SPY (not a stub) and ASSERTS it fires — the guarantee is still tested, just through the seam. pytest 2396, node 1040/1040, ESLint 0 (no-cycle clean), tailwind clean, Codex 0. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 20:58:41 +02:00