450 Commits

This Branch

This Branch

All Branches

Author	SHA1	Message	Date
3 people	0a6e0309e5	fix(tailwind): stop the dev server rewriting a tracked file (#911) (#918) ... The runtime stylesheet moves to CONFIG_DIR. static/tailwind.min.css is never written again. ━━━ TWO DIFFERENT THINGS WERE SHARING ONE PATH ━━━ static/tailwind.min.css a BUILD ARTEFACT. Committed, image-baked, generated by scanning the in-tree plugins only. CI's tailwind-fresh check verifies it. the RUNTIME sheet PER-INSTALL STATE. Additionally scans whatever the user installed into FEEDBACK_PLUGINS_DIR, so it differs machine to machine. Writing the second over the first meant that MERELY RUNNING THE DEV SERVER from a git checkout silently modified a tracked file. `git add -A` then swept a 100KB reshuffle of minified CSS into the commit and ci/tailwind-fresh went red with a diff that explains nothing — on a PR whose real change touched no Tailwind classes at all. It also wrote app state into the app directory, which is read-only in some deploys. A new route serves the runtime sheet when there is one and falls back to the committed one otherwise. It is registered BEFORE the /static mount, which would otherwise swallow the path. ━━━ A PERSISTED SHEET MUST NOT OUTLIVE ITS REASON (Codex [P2] x2) ━━━ 1. THE USER REMOVES THEIR PLUGINS. Startup only rebuilds when user plugins exist, so nothing would ever overwrite the stale sheet — and it still carries classes for plugins that are gone. With no user plugins the COMMITTED sheet is complete by definition. Guarded. 2. THE APP IS UPGRADED, and my first guard for this was WRONG. I compared mtimes. Codex: that is not a freshness signal across install methods — archives and container images routinely PRESERVE SOURCE MTIMES, so a just-shipped stylesheet can carry an OLDER timestamp than a runtime sheet a user built days ago. The mtime check then calls the stale one FRESH and it masks the new core CSS indefinitely — permanently, if no Tailwind toolchain is present to trigger a rebuild. Freshness is decided by CONTENT now. Each runtime build stamps a sidecar with the sha256 of the committed sheet it was made from. Core ships new CSS -> that file changes -> the hash changes -> the runtime sheet is correctly judged stale. Timestamps only gesture at the question that hashing answers. Falling back to the committed sheet is always safe: at worst it lacks a just-installed plugin's classes for the seconds until the async rebuild lands. VERIFIED END TO END. Ran the real dev server with 3 plugins installed: it rebuilt Tailwind over them (123,291 bytes), wrote the sheet + sidecar to CONFIG_DIR, still served /static/ tailwind.min.css at 200 — and `git diff` on the tracked file came back CLEAN. 8 tests. Bite-tested: reverting to the shared path fails 3, dropping the staleness guards fails 2 more. pytest 2425, pyflakes 0, Codex 0. Closes #911 Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 13:25:16 +02:00
3 people	36cf77dc44	refactor(highway): carve the 2D drawing layer into highway-draw.js (R3c) (#917) ... 18 functions, 1,245 lines. highway.js 3,972 -> 2,727 (-31%). The biggest R3c slice: notes, sustains, chords, strum groups, unison bends and lyrics — everything the default renderer paints each frame. ━━━ MUTABILITY, NOT LOCATION, DECIDES WHERE A THING BELONGS ━━━ Three per-instance caches came out with this slice, and they are why it needed care: _frameMismatchWarned a warn-once Set of chord ids (feedBack#88) _chordRenderInfo a WeakMap of chord -> chain info _lyricMeasureCache Map<fontSize, Map<text, width>> All three are MUTATED. Left at module scope they would be SHARED ACROSS PANELS — one highway's lyric widths and chord chains stomping another's, silently, with nothing throwing. createHighway() is a factory (the constitution publishes window.createHighway so a plugin can build a second highway), so they are lifted onto hwState, which is exactly what hwState is for. The shimmer LUT went the OTHER way — to MODULE scope in highway-geometry.js. It is a deterministic xorshift table, byte-for-byte identical for every instance, so sharing it is not merely safe but BETTER: built once for the page rather than once per panel. Same slice, opposite directions, decided entirely by whether the thing mutates. ━━━ MY SCRIPT WAS WRONG TWICE. THE GATES CAUGHT BOTH. ━━━ 1. HAND-LISTED THE MOVE SET. I listed 10 functions and missed six that drawChords needs (_ensureChordRenderCache, bsearchChords, getChordTemplateInfo, _computeChordBox, _updateFretLinePreview, _drawFretLineChordPreview). The no-undef gate named every one. The set is now DERIVED from the dependency closure — 18, not 10. 2. JUDGED PURITY TOO EARLY, and this one is subtle. I classified _computeChordBox as pure because its ORIGINAL body never mentions hwState. Then the call-site rewriter injected `fretX(hwState, …)` INTO it — fretX takes hwState now (#916) — leaving a function that references an hwState it was never given. Purity has to be judged from the body AS IT WILL BE, so the classifier iterates to a fixed point: a function needs hwState if it mentions it, OR calls anything that now takes it. That moved _computeChordBox to the stateful side. VERIFIED. A/B against origin/main: IDENTICAL, zero page errors. The PLUGIN BUNDLE contract is byte-identical (b.fretX arity 3, b.getNoteState arity 2, both stable references, both correct under the old calling convention). PERF GATE PASSES AT 1.92ms against its 12ms budget — and this is the slice that could really have cost something: the ENTIRE per-frame drawing path is now cross-module. It costs nothing measurable. TESTS. highway_teaching_marks follows strumGroupBuckets to the new module. The two source-shape harnesses now read highway.js AND every static/js/highway-*.js, rather than being re-pinned at whichever file currently holds a function — re-pinning breaks again next time, and a shape assertion that silently stops finding its target is indistinguishable from one that passes. node 1045, pytest 2416, ESLint 0, no-undef 0, Codex 0. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 13:00:29 +02:00
3 people	12eb73aee9	refactor(highway): carve the STATEFUL primitives, threading hwState explicitly (R3c) (#916) ... fretX, fillTextReadable, _noteState, _paintGemGlow -> static/js/highway-state-primitives.js. 50 call sites rewritten. highway.js 4,105 -> 3,965. The first slice that changes signatures. Each of these four gains hwState as an explicit FIRST PARAMETER. ━━━ hwState IS A PARAMETER, NOT AN IMPORT ━━━ createHighway() is a FACTORY. The constitution publishes window.createHighway so a plugin can build a SECOND highway for its own panel, and highway.js says so itself. Import hwState as a module singleton and two panels silently share one clock, one render scale, one string palette — each driving the other. Nothing throws. The picture is just wrong, in a way no test would catch. (The exact opposite of the app.js carve, where player-state.js and library-state.js ARE module singletons — correctly, because there is exactly one app. Same epic, same language, opposite answer, decided entirely by whether the thing is a factory.) ━━━ THE PLUGIN BUNDLE NEARLY BROKE, SILENTLY ━━━ The renderer bundle hands two of these STRAIGHT TO PLUGINS: b.fretX = fretX; b.getNoteState = _noteState; // stable reference highway_3d calls both EVERY FRAME, with the old arity. Handing out the new 3-arg versions would have passed `note` where hwState belongs — no throw, no error, just wrong geometry and wrong judgment state INSIDE A PLUGIN, which no core test would ever see. Green CI, broken 3D highway. So hwState is bound ONCE per instance, in the factory, and the bundle hands out those views. A per-frame arrow would have fixed the arity and reintroduced exactly the per-frame allocation the bundle's stable-reference contract (feedBack#254) exists to prevent. b.project needs none of this — project() is pure and its arity never changed. VERIFIED IN A BROWSER, against the real bundle, on both builds: fretX arity 3 3 (NOT 4 — the bound view preserves it) getNoteState arity 2 2 fretX(5,1,800) in 0..800 True True getNoteState null w/o provider True True getNoteState honours provider True True fretX is a stable reference True True IDENTICAL. Without the bound views fretX would have reported arity 4 and computed garbage. Also caught on the way: my generated module imported STRING_BRIGHT_FALLBACK, a name highway-constants.js does not export. ESLint does not flag that — but importing a name a module does not export is a runtime SyntaxError that kills the WHOLE module. These four need no constants at all; the import is gone. TESTS. highway_note_state pins the signature AND the stable-reference contract — it caught the bundle break. Retargeted at the module and the new arity; both contracts still asserted, and the "no fresh arrow per frame" rule is now asserted explicitly rather than implied by `getNoteState: _noteState`. PERF GATE PASSES AT 1.94ms against its 12ms budget — fretX and _noteState are now CROSS-MODULE calls, per note, per frame. It costs nothing measurable. node 1045, pytest 2416, ESLint 0, Codex 0. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 12:42:38 +02:00
3 people	1a386c272d	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>	2026-07-12 12:31:56 +02:00
3 people	8e89b39ad3	refactor(highway): carve the constants into static/js/highway-constants.js (R3c) (#914) ... 29 constants, 190 lines. highway.js 4,267 -> 4,158. The first real slice, and the one that every later one imports. ━━━ WHY ONLY THE CONSTANTS MAY LIVE AT MODULE SCOPE ━━━ createHighway() is a FACTORY, not a singleton. The constitution publishes window.createHighway precisely so a plugin can build a SECOND highway for its own panel, and highway.js already says so at the top of the closure: // R3c: per-instance mutable state in one object, so extracted renderer/ws // modules can close over it as a factory arg without cross-panel sharing. So hwState — all 79 mutable properties — must NEVER become a module-level singleton: two highways would silently share it, and one panel would drive the other's clock, scale and colour tables. Extracted functions will take it as an ARGUMENT. That is the OPPOSITE of the app.js carve, where a single state container (player-state.js, library-state.js) was exactly right, because there is exactly one app. Same epic, same language, opposite answer — because one is a singleton and the other is a factory. These 29 are pure literals: numbers, strings and colour tables, never reassigned, never mutated. Sharing them across instances is not merely safe, it is what you want — one copy of the shimmer LUT bounds and the string palettes rather than one per panel. Anything with a runtime dependency (document, window, performance, localStorage) stays in the factory; checked, and none of these has one. ESLint now knows static/highway.js is a module. It could not have known before this commit: the flip (#913) changed the SCRIPT TAG, but the file had no import/export yet, so it still parsed as a script and lint stayed green. The first `import` is what makes the config wrong. TESTS. Four source-shape harnesses asserted `const _AUTO_SCALE_MIN = …` etc. lived in highway.js. They now read highway.js AND every static/js/highway-*.js — deliberately, rather than being re-pinned at whichever file currently holds a constant. Re-pinning just breaks again on the next carve, and a source-shape assertion that silently stops finding its target is indistinguishable from one that passes. Bite-tested: renaming two constants away fails them. VERIFIED. A/B against origin/main: 15 probes IDENTICAL, zero page errors. AND THE PERF GATE PASSES AT 1.97ms against its 12ms budget — which is the point of having built it (#910) first: these constants moved from closure scope to module scope, and V8 does not treat those identically. It does here. Now I know rather than hope. node 1045, pytest 2416, ESLint 0, Codex 0. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 12:24:40 +02:00
3 people	c6963fdf30	refactor(highway): flip highway.js to an ES module (R3c) (#913) ... Two lines. index.html: defer -> type="module". highway.js: one explicit assignment. highway.js can now `import`, which is the whole point — the carve can begin. ━━━ THE ONE THING THE FLIP ACTUALLY BREAKS: window.createHighway ━━━ A top-level `function createHighway()` in a CLASSIC script IMPLICITLY becomes window.createHighway. In a module it does not — module declarations are module-scoped, and the name vanishes from the global object the instant the tag grows type="module". The constitution names window.createHighway as PUBLIC EXTENSION CONTRACT (alongside window.playSong / showScreen / feedBack). NOTHING IN-TREE CALLS IT. That is exactly why this would have shipped: the only consumers are third-party plugins rendering their own highway panel, and I cannot grep those. Green CI, green tests, and a broken plugin API. Verified by removing the assignment and reloading: flip WITHOUT an explicit assignment: window.createHighway === undefined <-- gone flip WITH it: window.createHighway === function So it is assigned explicitly now — same object, same behaviour, no longer an accident of how the file happens to be loaded. ━━━ AND A CORRECTION TO #912 ━━━ #912 (merged) rewrote 73 bare `highway.x` -> `window.highway.x` on the stated grounds that the flip would turn every one of them into a ReferenceError. HAVING NOW ACTUALLY FLIPPED IT, THAT WAS WRONG. highway.js already did `window.highway = highway`, which puts the name on the GLOBAL OBJECT — and bare-identifier resolution falls back to the global object whether or not a lexical global binding exists. Measured on both builds: bare `highway` resolves either way. #912 is defensible as hygiene and it does not hurt, but it was not a precondition and it fixed no latent bug. A correction is posted on the PR so its commit message does not mislead. The real hazard was the factory, not the instance — same class of breakage, wrong name. ORDERING is unchanged: classic-defer and non-async type="module" share ONE post-parse execution queue, in document order, so highway.js keeps its position at index.html:1244. VERIFIED. A/B against origin/main: 15 probes IDENTICAL, zero page errors — window.highway, window.createHighway, the full API surface, a real song playing, the chart clock advancing, and the seek->setTime sync. THE PERF GATE PASSES at 1.85ms against its 12ms budget (module evaluation costs nothing at render time), which is exactly what #910 was built to tell me. node 1045, pytest 2416, ESLint 0, Codex 0. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 12:07:28 +02:00
3 people	d9fa6d3f55	refactor(highway): make the highway global explicit before the module flip (R3c) (#912) ... 73 bare `highway.x` references -> `window.highway.x`, across app.js and 10 other files. Provably a NO-OP today. It is the precondition for flipping highway.js to a module. ━━━ WHY THIS HAS TO LAND FIRST ━━━ highway.js is a CLASSIC script. Its top-level `const highway = createHighway()` therefore creates a GLOBAL LEXICAL BINDING — visible as a bare name to every other classic script AND to every ES module. 73 call sites quietly rely on that. The moment highway.js becomes a module, that binding is gone. `const` in a module is module-scoped, not global. Every one of those 73 sites becomes a ReferenceError, and the flip is impossible until they say what they mean. `window.highway = highway` is already set, to the same object, on the same line. So this is an identity rewrite — verified in the browser below. ━━━ THE REWRITE BIT ME THREE TIMES. REGEX IS NOT ENOUGH FOR THIS. ━━━ 1. A SHADOWED LOCAL. capabilities/note-detection.js does `const highway = window.highway`. Its 9 bare uses are LOCAL and already correct; a blind rewrite would have emitted `const window.highway = window.highway`. Excluded. 2. HALF-CONVERTED GUARDS — the dangerous one. Six sites read `typeof highway !== 'undefined' && highway && typeof highway.setTime === 'function'`. The regex converted the CONSEQUENT and left the TEST, which is WORSE than not touching them: after the flip `typeof highway` is 'undefined', so each guard is PERMANENTLY FALSE and the code behind it silently never runs. transport.js's was the seek->setTime sync: the chart clock would have quietly desynced after every seek, with nothing failing. All six now test window.highway. 3. TWO MORE BARE REFERENCES, found by Codex [P2] and confirmed by an AST scan: app.js:3114 and :3176 use `highway && typeof window.highway.getSections === 'function'`. My grep searched for `typeof highway`, not `highway &&`. After the flip these throw, the catch swallows it, and the editor silently falls back to a ±4s edit window and arrangement 0. Regex missed a shadow, a half-conversion, and two bare reads. The final check is an AST pass that resolves scopes and reports every `highway` identifier not bound locally. It now reports ZERO. VERIFIED. A/B against origin/main in two browsers, 15 probes, IDENTICAL, zero page errors: window.highway is the same object as the bare global, the whole API surface resolves, a real song plays, the chart clock advances, getPerf().drawMs > 0 — and `seek syncs chart` passes, which is the exact guard I nearly broke in (2). node 1045, pytest 2416, ESLint 0, Codex 0. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 11:56:07 +02:00
3 people	23ecddc721	test(highway): the R3c perf gate — measure the render loop before carving it (R3c) (#910) ... highway.getPerf() (additive) + tests/browser/highway-perf-baseline.spec.ts. No behaviour change. This lands BEFORE highway.js is touched, because a perf-gated refactor without a perf gate is just a refactor. ━━━ FRAME RATE IS THE WRONG THING TO MEASURE ━━━ The highway AUTO-SCALES. When the smoothed draw cost passes _DRAW_BUDGET_HI_MS (12ms) it LOWERS THE RENDER RESOLUTION to protect the frame rate (#654). Exactly right for players — and it means a real perf regression does NOT show up as dropped frames. It shows up as a BLURRIER PICTURE at a perfectly healthy 60fps. Benchmark fps and you measure the feedback loop, not the renderer, and conclude nothing changed while the image quietly degrades. So the gate pins the scale (setRenderScale(1) + setMinRenderScale(1), which clamps autoScale to [1,1]) and measures drawMs — the renderer's own cost. None of that was reachable before: neither drawMs nor the effective scale escaped the closure. Hence getPerf(). The threshold is the app's OWN: _DRAW_BUDGET_HI_MS is the cost at which the highway itself starts sacrificing resolution in production. Exceeding it is not an arbitrary benchmark line — it is the renderer failing its own budget. Current cost ~2.2ms, so ~5x headroom: far more than headless-CI variance, far less than any regression worth shipping. ━━━ I WROTE THIS GATE WRONG THREE TIMES. EACH TIME IT PASSED. ━━━ 1. VACUOUS ASSERTION. First cut asserted "the auto-scaler wasn't forced to intervene", i.e. effectiveScale == 1. I injected a 10x regression (drawMs 2.4 -> 22.4ms, nearly DOUBLE the budget) and it PASSED. Of course it did: setMinRenderScale(1) sets the scaler's FLOOR to 1, so effectiveScale CANNOT drop below it. The very pinning that stops the scaler hiding a regression also stops it ever reporting one. A guard that cannot fail. 2. MEASURING AN IDLE RENDERER (Codex [P2]). playSong() takes ~3-4s to actually start — it is fetching and decoding stems. My "if not playing after 2s, togglePlay()" fired BEFORE autoplay, started playback, and then the app's own autoplay toggled it straight back to PAUSED. The renderer idled through the entire measurement. Now it WAITS for playback rather than racing it, and asserts the chart clock advanced DURING the sampling window — not merely at some point beforehand, which the first fix would have accepted. 3. UNENCODED FILENAME (Codex [P2]). playSong() decodes its argument before building the /ws/highway path, so every real caller passes encodeURIComponent(filename) (app.js:2879, 4137). Raw, a name containing # ? % or / yields an invalid WebSocket URL, the song never loads — and on those libraries the gate would have silently measured an idle renderer instead of failing. Every one of those bugs made the gate PASS. That is the whole hazard of a perf test: it fails safe in the wrong direction. BITE-TESTED, and this is the only reason I trust it: a 10x regression injected into the draw path FAILS the gate under live playback (22.0ms vs the 12ms budget) and the clean build passes at ~2.1ms with the chart clock advancing 5.6s across the sample. node 1045, pytest 2412, ESLint 0, Codex 0. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 11:36:11 +02:00
3 people	79825af28e	fix(demo): the janitor re-entry guard actually works now (#902) (#909) ... The guard in startup_events() read: if getenv_compat("FEEDBACK_DEMO_MODE") or getenv_compat("FEEDBACK_DEMO_MODE") == "1" \ and not _DEMO_JANITOR_STARTED: `and` binds tighter than `or`, so that is `A or (B and C)`. The not-already-started half never ran when the env var was truthy — the only case that reaches it at all. A second startup started a SECOND janitor thread, overwrote the handle, and shutdown then joined only the last: the first leaked and kept firing registered hooks hourly, forever. The guard now lives INSIDE start_janitor(). A caller cannot get operator precedence wrong if there is nothing left for it to get wrong. ━━━ THREE WAYS TO WRITE THIS GUARD WRONG. I HIT ALL THREE. ━━━ 1. NO GUARD — the original bug. Double-start, orphaned thread. 2. GUARD ON THE FLAG (`if _DEMO_JANITOR_STARTED: return`). Codex [P2]. stop_janitor() DELIBERATELY leaves that flag True when a hook outruns its join timeout, so that a later startup cannot spawn a janitor beside a live one. But the hook usually finishes a moment later: the thread exits and the flag is stale. A flag-keyed guard then refuses to start a replacement for the rest of the process — demo cleanup silently dead. (The original bug accidentally MASKED this by always starting.) 3. GUARD ON LIVENESS ALONE (`if thread.is_alive(): return`). Codex [P2], second pass. A timed-out stop leaves the old thread ALIVE BUT DOOMED — its stop event is set and it exits as soon as its current hook returns. Treating that as a running janitor skips the replacement, and we are back at (2) a second later. So: a janitor counts as running only if its thread is alive AND it has not been told to stop. ━━━ AND EACH JANITOR NOW OWNS ITS STOP EVENT ━━━ start_janitor() used to `_DEMO_JANITOR_STOP.clear()` a single SHARED Event. Start a replacement while a doomed thread is still finishing a hook and that clear RESURRECTS it: it loops back to wait(), sees the flag cleared, and carries on. Two janitors — the exact bug we started from. A fresh Event per janitor makes it impossible; the old thread waits on its own event, which stays set, so it can only exit. Env semantics UNCHANGED, verified across every value ("", "1", "0", "true", "false", "off"): the old expression and demo_mode_enabled() agree on all of them. The only behavioural change is the idempotency fix. FOUR tests, and each of the three wrong guards fails a different subset: no guard -> 2 fail (double start; orphaned thread) guard on the flag -> 2 fail (never restarts after a timed-out stop) liveness alone -> 1 fail (no replacement for a doomed janitor) liveness + not-stopping -> all pass pytest 2416, pyflakes 0, Codex 0. Closes #902 Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 11:30:53 +02:00
OmikronApexandGitHub	db3ca34fcb	Merge pull request #906 from got-feedBack/fix/loopback-raw-audio ... fix(static): raw stereo loopback capture — no voice-call DSP (tin-can fix)	2026-07-12 01:51:17 +02:00
OmikronApexandClaude Fable 5	34215fbd32	fix(static): request raw stereo audio for the loopback capture track ... Chromium treats a getDisplayMedia audio track as a voice call by default: echo cancellation, noise suppression, auto gain control and mono downmix. Music through that pipeline is the tester-reported "tin can" sound on ASIO/exclusive outputs. Request the raw path explicitly (EC/NS/AGC off, stereo, 48 kHz) — all constraints are best-effort so unsupported ones degrade silently instead of failing the capture. The [asio-diag] loopback line now dumps track.getSettings() so logs prove which processing actually applied. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-07-12 01:46:03 +02:00
3 people	f5d448af5c	refactor(server): carve demo mode into lib/demo_mode.py (R3b) (#903) ... lib/demo_mode.py (342). server.py 1,870 -> 1,649. The read-only request guard (its 96-entry blocked-route table + the middleware) and the hourly session janitor (registry, hook runner, thread). Bodies VERBATIM. THE MIDDLEWARE NEEDS `app`, SO THE MODULE TAKES IT. _demo_mode_guard is an @app.middleware("http") and cannot exist without an app object. Rather than have a module under lib/ reach for a global, it exposes install(app) and server.py — which owns the app — hands it over. The janitor is symmetrical: start_janitor() / stop_janitor(), called from server.py's startup and shutdown hooks, where the process lifecycle actually lives. register_demo_janitor_hook IS PART OF THE PLUGIN CONTRACT. It is a key in plugin_context, so plugins hold it as a LIVE REFERENCE from setup(). server.py imports this exact object and puts it in the dict unchanged — identity preserved, and tests/test_plugin_context_contract.py (#898, merged) fails if that ever stops being true. This is the first carve that guard has actually protected. ━━━ stop_janitor()'s ORDER IS LOAD-BEARING ━━━ The obvious way to write it — clear the "started" flag, then join — is WRONG, and I wrote it that way first. server.py's original deliberately returns EARLY, leaving _DEMO_JANITOR_STARTED True and the thread handle intact, when the thread outlives the join: # Leave _DEMO_JANITOR_STARTED True so a new janitor is not # spawned by a subsequent startup while the old one is alive. Clearing the flag first quietly reintroduces exactly the double-janitor leak the flag exists to prevent. Preserved byte-for-byte, and the reason is now written down at the function rather than only at its single call site. ━━━ A BUG MOVED VERBATIM, ON PURPOSE ━━━ if getenv_compat("FEEDBACK_DEMO_MODE") or getenv_compat("FEEDBACK_DEMO_MODE") == "1" \ and not _DEMO_JANITOR_STARTED: `and` binds tighter than `or`, so this is `A or (B and C)` — the not-already-started re-entry guard is DEAD whenever the env var is truthy, which is the only case that runs. A second startup leaks a janitor thread (the handle is overwritten, so shutdown joins only the last). Verified. Preserved exactly and filed as issue #902: a carve whose whole value is being provably behaviour-neutral is not the place to change behaviour. pyflakes caught three more missing imports on the way in (uuid, warnings x2). Five carves, ten missing imports, every one a NameError on a live path. pytest 2399, pyflakes 0, Codex 0. Refs #48 Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 01:32:46 +02:00
3 people	8f014e6a30	refactor(server): carve the library scanner into lib/scan.py (R3b) (#901) ... lib/scan.py (326). server.py 2,098 -> 1,870. The background scan, its spawn ProcessPoolExecutor, and the kick/runner plumbing that serialises passes. Bodies VERBATIM except the seam reads. Everything shared is read LATE off appstate — the same contract every module in lib/routers/ uses, and it is not cosmetic: tests monkeypatch CONFIG_DIR and swap meta_db, so a value captured at import time pins the wrong one for the life of the process. CONFIG_DIR -> appstate.config_dir meta_db -> appstate.meta_db _default_settings -> appstate.default_settings() _stat_for_cache -> appstate.stat_for_cache() ━━━ THE SCAN STATUS IS REBOUND, NOT MUTATED ━━━ _background_scan does `global _scan_status; _scan_status = {**INIT, ...}` at every stage transition. It REPLACES the dict; it never updates it in place. So nothing may hold that dict by value — a reference captured once goes permanently stale at the first stage change and would report "listing" forever while the scan ran to completion. Hence `scan.status()`, a getter, and hence appstate publishes scan_status as a CALLABLE. appstate.py already said so in a comment; this is the code that makes it true. (Same for the plugin_context entry, which was already `lambda: dict(_scan_status)` — late-bound, so it survives the move unchanged. The contract test from #898 covers it.) ━━━ appstate.server_root: A TRAP CLOSED PERMANENTLY ━━━ _background_scan seeds the builtin content, which needs the directory holding server.py. `Path(__file__).resolve().parent` is correct in server.py and silently WRONG anywhere under lib/ — it yields lib/, which holds no docs/ or data/ — and it fails by finding NOTHING rather than by raising, so the seeds would just quietly never run. lib/builtin_content.py (#900) closed that by taking the root as a parameter. This adds the other half: server.py publishes it ONCE as appstate.server_root, so no module under lib/ ever has a reason to derive it. Documented at the slot. pyflakes caught two more missing imports on the way in (loosefolder_mod, enrichment) — each a NameError on a live scan path, and the suite would have handed them over one failure at a time. It stays part of every server.py slice. TESTS. The two scan fixtures (test_settings_api::scan_module, test_feedpak_extension::scan_server) patched server._make_scan_executor to swap the spawn pool for an in-process ThreadPool; they now patch it on lib/scan.py. Worth noting WHY that still works: the fixtures re-import `server` per test, but `scan` stays cached in sys.modules — and it picks up the fresh CONFIG_DIR anyway, because the appstate reads are late-bound. The seam is doing exactly the job it was built for. ━━━ TEST ISOLATION: A REGRESSION THE CARVE ITSELF CREATED (Codex [P2]) ━━━ background_scan() deliberately NEVER sets running=False — ownership of that flag lives in _scan_runner, so a kick_scan() racing the terminal write cannot observe a stale False and start a second runner. Correct in production. But the scan fixtures call background_scan() DIRECTLY, skipping the runner. That was harmless while the state lived on `server`, which the fixtures RE-IMPORT per test. It is NOT harmless now: `scan` stays cached in sys.modules across sys.modules.pop("server"), so the status dict OUTLIVES the test. One direct call leaves the shared scanner marked "running" forever, and every later scan or rescan returns "already in progress" and quietly does nothing. Verified: after a direct call, kick_scan() returns False and starts no scan at all. The suite passed anyway, on ordering luck — which is exactly how this class of bug ships. tests/conftest.py::reset_scan_state now snapshots and restores lib/scan.py's module state around the two fixtures that drive it directly. pytest 2398, pyflakes 0, Codex 0. Refs #48 Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 01:26:02 +02:00
3 people	6b8f79dd9a	fix(server): a raising tuning provider no longer takes down get_merged() for everyone (#899) (#904) ... One word. server.py's TuningProviderRegistry.get_merged(): except Exception: - logger.exception("tuning provider %r raised during get_merged()", provider_id) + log.exception("tuning provider %r raised during get_merged()", provider_id) There is no `logger` in server.py — the module logger is `log`. So the handler written to swallow-and-report a bad provider instead raised NameError from inside the except, and that NameError propagated out of get_merged(). The effect was the exact OPPOSITE of what the handler is for: one misbehaving plugin took the whole merged-tunings call down for every other provider, AND the traceback named the wrong problem ("name 'logger' is not defined" rather than the provider that actually blew up). Doubly silent: nothing was ever logged either, because the logging call was the thing that crashed. Found by pyflakes while carving server.py (R3b). It survived because NOTHING exercised the failure path — no test ever had a provider raise. That is the whole reason this class of bug is invisible: it lives only on error paths, so the suite is green and the feature is broken exactly when it matters. tests/test_tuning_provider_isolation.py is that path: * a raising provider must not lose the HEALTHY providers' tunings, nor the defaults * and the failure must actually be LOGGED — swallowing is only acceptable if it reports Bite-tested: restoring `logger` fails both. (The log assertion attaches caplog's handler to the feedBack logger directly. It sets propagate=False, so pytest's root capture sees nothing from it — test_plugins.py has a capture_logger() for this, but it is not importable here: pyproject pins pythonpath to [".", "lib"], so `tests` is not a package. Three lines beat churning 21 call sites in an unrelated file to convert that helper into a fixture.) pytest 2410, pyflakes 0 undefined names in server.py, Codex 0. Closes #899 Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 01:25:08 +02:00
3 people	70dbe45e27	refactor(server): carve builtin-content seeding into lib/builtin_content.py (R3b) (#900) ... lib/builtin_content.py (321 lines moved). server.py 2,418 -> 2,098. The calibration/diagnostic sloppaks and the starter library: _copy_builtin_packs, _write_builtin_pack, the two seed helpers, their source tables, and the seed marker. ━━━ THE ONE SIGNATURE CHANGE, AND WHY THE CARVE IS UNSAFE WITHOUT IT ━━━ server.py has: def _feedBack_server_root() -> Path: return Path(__file__).resolve().parent That is correct IN server.py: the repo root in dev, resources/feedBack when bundled — the tree that actually holds docs/ and data/. Move that body into lib/ unchanged and it keeps working, silently, and returns lib/. There is no docs/diagnostics under lib/, so every seed would find nothing, log "source missing" at debug, and return. Nothing raises. Nothing fails. The starter library simply never appears, and the calibration sloppak is never seeded — on a fresh install, in the field. A verbatim move whose MEANING changed because __file__ did. So this module cannot compute a root: `server_root` is a PARAMETER, and server.py — the only place that legitimately knows where it lives — passes it in. The trap is now structurally impossible rather than merely avoided. (_copy_builtin_packs already took the root that way; the two seed helpers now do too.) Everything else is byte-identical. CONFIG_DIR is read late as appstate.config_dir and the DLC root through dlc_paths._get_dlc_dir — the same seam every router in lib/routers/ uses, late-bound because tests monkeypatch it. ━━━ PYFLAKES FOUND THREE MISSING IMPORTS THE TESTS WOULD HAVE FOUND ONE AT A TIME ━━━ The moved code uses `secrets`, `stat` and `tempfile`; none was in my import block. Each is a NameError on a live path. `python3 -m pyflakes` names all three in one shot — this is the Python twin of the no-undef gate that guarded every frontend carve, and it should run on every server.py slice from here. It also flagged a PRE-EXISTING one I deliberately did not touch: server.py's TuningProviderRegistry.get_merged() calls `logger.exception(...)` in an except handler and there is no `logger` in the module (it is `log`). So a raising tuning provider takes down the merged-tunings call for everyone, with a NameError naming the wrong problem. Filed as issue #899 rather than smuggled into a carve whose whole value is being behaviour-neutral. The constants lost their underscore prefix: they cross a module boundary now (the seed tests read them), so `_BUILTIN_STARTER_SOURCES` was a lie. pytest 2397, pyflakes 0, Codex 0. Guarded by the plugin_context contract test (#898). Refs #48 Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 00:50:50 +02:00
3 people	1cef01d02c	test(plugins): pin the plugin_context contract before carving server.py (R3b) (#898) ... tests/test_plugin_context_contract.py (3 tests). No production code changes. server.py is about to be carved apart around startup_events(), and `plugin_context` — the 20-key dict handed to every plugin's setup() — is built inline inside it. Issue #48 flagged this while planning the split and asked for exactly this guard: "Plugin context[...] are passed as live references into already-loaded plugins. Refactoring must preserve the exact callables — moving them to a new module is fine, but renaming or wrapping them breaks third-party plugins. We'd want a 'plugin context unchanged' assertion in CI." It never got written. Writing it FIRST, because a key silently dropped or renamed by a move is invisible to every other test in the suite — nothing in-tree reads most of these — and would break plugins at runtime, in the field. This is the backend's version of the window contract, and the frontend carve just taught me what that costs: 43 of library.js's exports were referenced ONLY from app.js's top-level window block, invisible to any call-graph scan, and trusting the scan would have shipped a dead A-Z rail with CI fully green. A contract only external code reads has to be pinned BY NAME, before the move, not after. THE SURFACE IS BIGGER THAN server.py's DICT. Shipped plugins read `log` and `load_sibling`, and neither is in it — plugins/__init__.py layers them on per-plugin. A test pinning only server.py's 18 keys would have missed both. ━━━ CODEX CAUGHT ME WRITING A VACUOUS ASSERTION ━━━ My first identity test built a dict locally and called setup() on it — asserting `dict(x)['k'] is x['k']`, which is trivially true and blind to everything the loader does. [P2], and correct. It now drives the REAL plugins.load_plugins() with a probe plugin, which matters: the loader DOES deliberately wrap one key (register_library_provider is scoped per-plugin so a plugin cannot forge owner attribution and impersonate another). The test pins that single intentional exception so it cannot quietly become two. Codex then caught [P2] number two: my hand-rolled teardown restored only PLUGINS_DIR and LOADED_PLUGINS, while load_plugins() also mutates sys.path, sys.modules and PENDING_PLUGINS — order- and environment-dependent. tests/test_plugins.py already had a fixture that does this properly, so `reset_plugin_state` moved to tests/conftest.py: ONE copy, shared, rather than a second that will drift. BITE-TESTED IN FIVE DIRECTIONS — drop a key, rename a key, drop a per-plugin key, wrap extract_meta in the loader (all key names intact, identity broken), and remove the register_library_provider scoping (the impersonation guard). Each fails. pytest 2399, Codex 0. Refs #48 Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 00:29:48 +02:00
3 people	756588678b	fix(plugins): make a module plugin actually re-evaluate on reload (#879) (#897) ... A plugin reload silently did nothing for scriptType:"module" plugins. ES modules are evaluated ONCE PER URL PER DOCUMENT, so re-inserting a <script type="module"> whose src the module map has already seen fires `load` without re-running the body — and the loader then recorded the reload as applied. A no-op that reported success. THE ISSUE UNDERSTATES IT. #879 says "upgrades are fine — a new version yields a new URL". That is true of screen.js and FALSE of the plugin. I drove a real browser through install(1.0.0) -> upgrade(1.1.0) -> rollback(1.0.0), counting evaluations of src/main.js: ONE. Not three, not two. The upgrade re-runs the one-line screen.js shim at its new ?v= URL; the shim does `import './src/main.js'`; a relative specifier resolves against the base URL WITH THE QUERY DROPPED; that is the same URL as before; the module map hands back the already-evaluated v1.0.0 module. The plugin's own code never re-ran. Busting the entry point cannot fix this, whatever token you hang off it. So the token goes in the PATH: /api/plugins/<id>/g/<n>/screen.js. From there './src/main.js' resolves to /api/plugins/<id>/g/<n>/src/main.js — every relative import inherits it, at every depth, for free. No import-specifier rewriting (which could never see `import(expr)` anyway). Same browser drive after the fix: THREE evaluations. Keyed on the plugin ID, not id@version: EVERY re-load of a module plugin needs a fresh path, not just a rollback. First load keeps the stable ?v= URL, so the ETag/304 live-edit caching the R0 rails depend on is untouched. Classic-script plugins are not affected and never take a /g/ path. ━━━ A PATH REWRITE, NOT TWO MIRRORED ROUTES ━━━ Codex caught this, and it was right. The token shifts the BASE URL, so EVERYTHING the module graph resolves relatively moves with it — not only imports. `new URL('../assets/worklet.js', import.meta.url)` from /api/plugins/x/g/1/src/main.js resolves to /api/plugins/x/g/1/assets/worklet.js. Mirroring only screen.js and src/ would have fixed imports and 404'd every asset, worklet and wasm file the graph reaches — and would have broken again the next time someone added a plugin route. So the /g/<token> segment is STRIPPED BEFORE ROUTING. Every plugin route, present and future, works under the prefix with no extra wiring. The token is opaque and never joined into a filesystem path, so containment still rests entirely on the same safe_join. Codex then caught a [P3] in that: eagerly re-encoding raw_path with latin-1 raises UnicodeEncodeError on a valid plugin file like src/工具.js, 500ing a request the plain route serves fine. raw_path is informational and Starlette routes on scope["path"], so the mutation is simply gone — and leaving raw_path as the client sent it is more truthful for logs anyway. TESTS. tests/js/plugin_module_rollback.test.js (5) + 8 in test_plugin_src_route.py: identical bytes under the prefix, the whole graph one and two levels deep, ASSETS (the Codex [P2]), every plugin route, non-ASCII filenames (the [P3]), an opaque token, and containment asserted as PARITY with the un-prefixed route rather than a guessed 404 — `../screen.js` legitimately 200s on both, because the URL normalises before routing. All bite-tested: reverting the fix fails the rollback tests, disabling the rewrite fails the asset tests. Two harnesses re-anchored on `script.src = _pluginScriptUrl(` — the URL literal they keyed on now lives in the helper, further down the file, so their slice ran off the end. node 1045, pytest 2404, ESLint 0, Codex 0. Closes #879 Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 00:19:59 +02:00
3 people	bd830328f0	refactor(app): carve the library out of app.js (R3a) (#896) ... static/js/library.js (1,988) + static/js/library-state.js (29) — bodies VERBATIM. app.js 6,313 -> 4,451. THE BIGGEST SLICE OF THE CARVE: 145 declarations, ~1,900 lines, 30% of what was left. The grid, the artist tree, the A-Z rail, filters, pagination, selection, favourites, the scan banner, and the library-provider plumbing. A LOW module: it imports only leaves (./dom.js, ./format.js, ./library-state.js, ./tuning-display.js — all four import nothing themselves) and needs ZERO host hooks. It calls nothing in app.js. That is not luck; it is why this cluster was picked. Two entry points that WOULD have dragged the playback core in were left behind in app.js: * syncLibrarySong reaches showScreen/playSong * _handleLibArrowNav Enter on a selected row plays the song Both are one hop from the library, and app.js is the root, so it imports from both sides for free. Pulling them in swallows playSong, showScreen and the whole remaining core — I measured it: the closure jumps from 145 declarations to 189. library-state.js holds exactly FIVE fields. An imported binding is read-only, and of the library's outward bindings only these five are genuinely WRITTEN from outside — by showScreen, deleteSongFromModal and syncLibrarySong, none of which can move in. The other 23 are read-only from outside, so they stay plain exports (ES live bindings mean app.js still sees every reassignment). ━━━ THE EXPORT LIST NEARLY SHIPPED A DEAD A-Z RAIL ━━━ 59 exports — and 43 of them CANNOT be found by a call-graph scan. They are referenced only from app.js's TOP-LEVEL statements: the Object.assign(window, {...}) contract and the scattered window.X = X lines, which live outside every function, so a closure walk over declarations never sees them. Among them are the four handler names app.js composes AT RUNTIME into onclick="" strings — filterTreeLetter, filterFavTreeLetter, goTreePage, goFavTreePage — the library A-Z rail and its pagination. No static tool can see those at all. Had I trusted the call-graph, the rail would have died silently on click with nothing failing in CI. ━━━ AND MY OWN SCANNER LIED ━━━ The cycle-risk pass reported "(none)" for this carve. It was wrong, and it could not have been right: a dangling `else if` bound to an inner `if` instead of the outer chain, so its `imported` map was ALWAYS empty and the check reported clean no matter what. A guard that cannot fail is worse than no guard. Fixed, and it then found the real edges — dom.js, format.js, tuning-display.js, library-state.js. All four are leaves, so the carve is genuinely acyclic; I just now know it instead of assuming it. (The AST rewriter had its own trap: `MAP[name]` with an object literal and name === 'constructor' hits Object.prototype.constructor — truthy — and it happily rewrote `constructor(id)` into `L.function Object() { [native code] }(id)`. Every identifier in the file is looked up, so the lookup must not see the prototype chain. It is a Map now.) TESTS. legacy_shim_hits SPLIT (loadLibraryProviders + setLibraryProvider -> the module; syncLibrarySong stayed in app.js). v3_library_refresh now reads app.js AND the module, rather than being re-pinned to whichever file happens to hold the emit this week. VERIFIED. A/B against origin/main in two browsers: the whole window contract, cards render, grid/tree/sort/filter/clear round-trip — and, specifically, the A-Z rail: 28 onclick handlers composed at runtime, identical on both, and a real .click() on a letter works. IDENTICAL on all 33 + 7 probes, no new page errors. pytest 2396, node 1040/1040, host contract 2/2, ESLint 0 (no-cycle clean). Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 23:30:30 +02:00
3 people	09f7e450a5	refactor(app): give formatTime a home — a leaf format.js, one fewer host hook (R3a) (#895) ... static/js/format.js (17). One function. Retires the formatTime hook: 12 -> 11. WHY A MODULE FOR ONE FUNCTION. formatTime was a host hook — loops.js and section-practice.js both reached back through the seam for it. It is ALSO, by pure accident of who calls it, inside the dependency closure of the library carve that comes next. Leaving it there would have made loops.js and section-practice.js import the LIBRARY in order to format a timestamp — nonsense, and a cycle waiting to happen. Same rule as the transport carve: a hook is a cycle you agreed to live with; an import is a dependency you actually have. formatTime has a real owner. It just isn't app.js, and it certainly isn't the library. Give it a home and both consumers import it directly. A leaf on purpose. Anything else that turns out to be a shared pure formatter belongs here too; nothing does yet (I checked — formatBadge, _safeImageUrl and _fetchJsonOrThrow have no callers outside the library), so nothing else is here. node 1040/1040, host contract 2/2, ESLint 0. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 23:27:17 +02:00
3 people	8bec8d2466	refactor(app): carve the playback transport out of app.js — and RETIRE 8 host hooks (R3a) (#894) ... static/js/transport.js (377) — bodies VERBATIM. app.js 6,643 → 6,316. THIS IS THE FIRST CARVE THAT SUBTRACTS HOOKS INSTEAD OF ADDING THEM. Every carve before this one added host hooks: a module pulled out of app.js still had to call back into it. But four modules were all reaching through the seam for the SAME handful of names — _audioSeek, _audioTime, setPlayButtonState, _songEventPayload, jucePlayer. Those names have an owner, and it isn't app.js. Give them one, and the consumers import them directly: count-in.js 5 hooks -> 0 (host import deleted) juce-audio.js 4 hooks -> 0 (host import deleted) loops.js 6 hooks -> 4 section-practice.js 10 hooks -> 7 ---------------------------------------------------------- configureHost() 20 hooks -> 12 A hook is a cycle you agreed to live with. An import is a dependency you actually have. Prefer the import whenever the name has a real owner. _audioSeekGen now stays PRIVATE. It has exactly one writer — _resetAudioSeekState(), which moved with it — so readers get audioSeekGen() and nobody outside can desync it. Strictly better than the hook it replaces, which handed out a getter and left the writer behind in app.js. THE SCAN HAD A HOLE, AND IT BIT. Picking the carve by dependency closure over app.js's own top-level decls said this cluster was downward-closed. It wasn't: _currentPlaybackSnapshot reads loopA/loopB — which live in ./js/loops.js, and loops.js imports transport. The scan saw nothing, because loopA STOPPED BEING an app.js decl the moment loops.js was carved out. Any dependency scan of a partly-carved monolith has to resolve the imports too, or it will confidently hand you a cycle. Added that pass; it found exactly one back-edge, and _currentPlaybackSnapshot stays in app.js (as does restartCurrentSong, which calls _cancelCountIn). app.js is the root — it imports both sides for free. TESTS. Four harnesses retargeted (play_button_reroute_guard, song_event_payload, song_seek -> transport.js; playback_app_adapter SPLIT, since _installPlaybackTransportAdapter stayed behind). The two CENSUS tests — "≥8 song:* emit sites", "every seek callsite passes a reason" — now scan app.js AND every static/js/*.js, not one file. Pointed at a single file, their count silently shrinks as code leaves, which reads as "someone deleted an emit" or, worse, passes while genuinely missing sites. Both bite-tested: stripping a _songEventPayload() from an emit and adding a reason-less _audioSeek() each fail the suite. VERIFIED. A/B against origin/main, real song, real playback: song:play payload is exactly {audioT, chartT, perfNow, time}; song:seek carries reason "seek-by" with finite from/to; all five song:* events fire; seekBy advances the clock; restartCurrentSong returns to zero; the play button's aria-pressed tracks state. IDENTICAL on all 21 probes, zero page errors. pytest 2396, node 1040/1040, host contract 2/2, ESLint 0 (no-cycle clean), Codex 0. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 23:26:35 +02:00
3 people	8d0e270345	refactor(app): carve the JUCE/desktop audio shims out of app.js (R3a) (#893) ... * refactor(app): carve resume-session out of app.js (R3a) static/js/resume-session.js (157) — the snapshot taken when you leave a song and the pill that offers it back. Bodies VERBATIM. app.js 7,727 → 7,601. Fifth slice out of the strongly-connected core. ONE hook (playSong) + a currentFilename getter. S.pendingResume JOINS THE CONTAINER — on demand, exactly as intended. app.js WRITES it (playSong({ resume }) arms it; the song:ready listener consumes it) while this module reads it, so it cannot be a plain export: an imported binding is read-only. Same reason isPlaying is there. The container grows one field per carve that needs it, never speculatively. THE CONTRACT TEST CAUGHT THE MISSING HOOK, again on a path nothing executes: "playSong is read by a module but never wired by app.js — it would throw at runtime". Second time it has caught a real wiring gap the moment it appeared. A REAL TRAP, worth remembering: I first did the S.pendingResume rewrite by feeding acorn's identifier RANGES from node into python, and it corrupted the file (`_pS.pendingResume null;`). **Acorn's offsets are UTF-16 code units; Python's string indices are code points.** static/app.js contains emoji, so every offset past one drifts. Do an AST-driven rewrite in the SAME language that produced the offsets. `node --check` caught it; a silent version of that bug is very easy to imagine. VERIFIED. A/B against origin/main in two browsers, real song: the window API (resumeLastSession / _snapshotResumeSession / _readResumeSession / _clearResumeSession), snapshot, read-back, and clear — IDENTICAL, zero page errors. HONEST LIMIT: my probe never got the snapshot to actually PERSIST (there is a guard beyond the 3s minimum position that a scripted playSong does not satisfy), so that path is verified only as identical-to-main, not as observed-working. The real coverage is tests/browser/resume-session.spec.ts, which drives the flow properly. Zero harnesses broke. 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> * refactor(app): carve the JUCE/desktop audio shims out of app.js (R3a) static/js/juce-audio.js (994) — bodies VERBATIM. app.js 7,603 → 6,643. THE LARGEST SINGLE SLICE of the whole carve phase: 960 lines, ~13% of what was left. Three self-installing IIFEs: _installJuceEngineRoutingWatcher (444) routes a song to the JUCE engine or HTML5 as the desktop output enters/leaves exclusive/ASIO _installRendererBusFeeder (337) feeds the highway renderer bus from whichever transport is actually running _installJuceAudioElementShim (156) patches audio.play/pause so the rest of the app keeps talking to the <audio> element while JUCE owns the transport They EXPORT NOTHING — all three publish through `window.*` (_juceMode, _reevaluateJuceRouting, _reevaluateRendererBus, …). So app.js needs only a side-effect import plus the one binding it actually uses (_resetJuceAudioShimChain, which the shim IIFE assigns). THE ORDERING QUESTION, CHECKED RATHER THAN ASSUMED. Importing this module runs the IIFEs EARLIER than before: imports evaluate ahead of app.js's body, and therefore ahead of configureHost(). A hook read at IIFE-execution time would THROW. So I walked the AST at IIFE-body depth to see what they actually touch when they run: nothing but listener registration, and `audio.play`/`audio.pause` patching — and `audio` is itself an imported module now. Verified in the browser: both are patched on the carved build exactly as on main, which proves the shim installs correctly at its new, earlier point. (Had I got this wrong, host.js throws loudly rather than silently misbehaving — which is the whole reason it has no no-op defaults.) VERIFIED. A/B against origin/main in two browsers: the entire window.* surface the IIFEs publish (_juceMode, _juceOutputIsExclusive, _reevaluateJuceRouting, _reevaluateRendererBus, _clearJuceRerouteMemo), audio.play/pause patched, a real song loading and togglePlay driving the public mirror — IDENTICAL, zero page errors. Harnesses: juce_engine_reroute (19 tests) + renderer_bus_feeder (13) slice the IIFEs by signature — retargeted, and each sandbox gains a `host` object routed at its EXISTING stubs so every assertion holds unchanged. test_plugin_runtime_idempotence is SPLIT: 3 of its 4 source-asserts stayed in app.js, the sm.emit('song:resume') one moved. 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> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 22:44:03 +02:00
3 people	dc429ecd16	refactor(app): carve the player controls out of app.js (R3a) (#891) ... static/js/player-controls.js (229) — the speed + mastery sliders and the four playback-preference reads (autoplay-exit, up-next, countdown-before-song, confirm-exit). Bodies VERBATIM. app.js 7,914 → 7,727. The fourth slice out of the strongly-connected core, and by far the easiest: ONE hook (handleSliderInput) and NO shared mutable state. The three groups are the same surface — the controls under the highway — and the preference reads are the one-line localStorage lookups half of app.js consults before deciding whether to auto-start, show the Up Next pill, run a count-in, or confirm on exit. They travel with the controls that set them. Zero missed members on the first build (the no-undef pass was clean), which is the first time that has happened in this phase. TWO HARNESSES ARE SPLIT, and both taught something: * speed_reset spans BOTH files — playSong (app.js) resets the speed controls (module). Its presence GUARDS still read `src.includes('function setSpeed')` against app.js, so once the code moved they silently evaluated FALSE and the helpers were quietly dropped from the sandbox. A guard that disables itself is worse than no guard. Repointed at the file the code actually lives in. * Its `host.handleSliderInput` stub had to route at the sandbox's EXISTING spy, not a fresh `() => {}`. The test asserts the slider was actually refreshed (`deepEqual(__sliderInputs, ['speed-slider'])`); a fresh stub swallows the call and the assertion passes VACUOUSLY. Same failure mode as a no-op host default — the thing this whole seam design exists to prevent. * autoplay_exit is split too: _autoplayExitEnabled moved, but the auto-exit machinery around it (_clearAutoExit, holdAutoExit, _resolvePlayerOrigin) stayed. VERIFIED. A/B against origin/main in two browsers, real song: setSpeed(0.75) -> playbackRate 0.75; applySpeedPreset(100) -> 1; the speed slider; setMastery; setAutoplayExit / setCountdownBeforeSong / setShowUpNext — IDENTICAL, zero page errors. pytest 2396, node 1040/1040, ESLint 0 (no-cycle clean), tailwind clean. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 22:12:34 +02:00
3 people	11f8c36b61	refactor(app): carve count-in (and the song-credits overlay) out of app.js (R3a) (#890) ... static/js/count-in.js (389) — bodies VERBATIM. app.js 8,223 → 7,913. The third slice out of the strongly-connected core, and the first that WRITES shared state rather than only reading it. #889's container is what makes it possible. imports: loops (setLoop/loopA/loopB — a count-in inside an A-B loop must begin at A), audio-el, player-state, host hooks : _audioSeek, setPlayButtonState, _songEventPayload, togglePlay + a jucePlayer getter Nothing imports count-in back — app.js and section-practice both reach it through the seam — so the graph stays acyclic. app.js's autoplay path used to reach IN and set this module's credits timers itself (_creditsTimer, _creditsHideOnPlay) and read _countingIn. It cannot now, and should not have to, so the module exports the OPERATIONS instead — armCreditsHideOnPlay(), scheduleCreditsHide(), holdCreditsThen(start), isCountingIn() — and owns its own timer invariants. Third time this has happened (section-practice's resetSelection, loops' state) and each time the constraint produced better code than was there before: the module keeps its own promises instead of trusting a caller 6,000 lines away to zero the right fields. THE no-undef GATE FOUND FIVE MISSED MEMBERS, one at a time: showSongCreditsOverlay and startSongCountIn (my name regex matched startCountIn, not startSongCountIn), then _creditLineLabel, _CREDITS_MAX_MS, and _CREDIT_ROLE_VERBS. A call-graph closure does not see a const table; only the undefined-symbol pass does. AND A REAL TRAP: I computed _CREDIT_ROLE_VERBS's span against the ALREADY-MODIFIED app.js and applied it to the clean one — the line numbers had drifted, so the slice would have cut somewhere else entirely. Recomputed every span from the clean file with acorn. Never carry line numbers across an edit. VERIFIED. A/B against origin/main in two browsers with a real song: playback state, the public feedBack.isPlaying mirror, audio position, cancel-count-in — IDENTICAL, zero page errors. Unit coverage moved with the code: loop_restart's count-in cancellation-token test and the 5 song_credits_overlay tests now read count-in.js; loop_restart's sandbox gains a `host` object routed at its EXISTING stubs, so every assertion is unchanged. HONEST LIMIT: I could not make the count-in OVERLAY actually render headlessly — its autoplay path needs a fresh-load _pendingAutostart that a scripted playSong() never arms. Behaviour is identical to main on every probe and the unit tests cover the logic, but the on-screen 1-2-3-4 and the credits card want a human look. 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 22:05:22 +02:00
3 people	5fb28d5c5a	refactor(app): lift the shared player state onto a container (R3a) (#889) ... static/js/player-state.js — one exported object, two fields. app.js's 70 reference sites rewritten. Provably a no-op; nothing shrinks. WHY NOW. Every slice carved out of app.js so far only ever READ the state it shared (loopA/loopB, _audioSeekGen, currentFilename), so a read-only getter hook was enough and no container was needed — twice I checked and twice I got away with it. That runs out at count-in: it genuinely WRITES `isPlaying` (it starts and stops playback, 4 sites) and `lastAudioTime` (2). `import { isPlaying }` then `isPlaying = true` THROWS — an imported binding cannot be assigned to. So the state has to live on an object: `S.isPlaying = true` is a property write, and works from any module holding the same S. Same shape stems, studio, and editor all converged on. DELIBERATELY SMALL. app.js has ~104 top-level `let` scalars; lifting all of them is a ~977-site rewrite for no benefit, because most are private to one cluster and travel with it. Only what a carved module must WRITE goes here. Add on demand. THE REWRITE IS AST-DRIVEN, NOT TEXTUAL — and that is not fussiness. Of 100 textual occurrences of these two names, only 70 resolve to the module binding: * 22 are member accesses (`someObj.isPlaying`, `window.feedBack.isPlaying`) * 4 are the LOCAL PARAMETER of `function setPlayButtonState(isPlaying)` — a blind replace yields `function setPlayButtonState(S.isPlaying)` * 1 is an object key * 2 are shorthand properties `{ isPlaying }`, which must become `{ isPlaying: S.isPlaying }` — and acorn gives a shorthand's key and value the SAME range, so rewriting both produced `isPlaying: S.isPlaying: S.isPlaying` until I deduped by range A find-and-replace corrupts all 29. The rewrite walks the AST, skips shadows, member properties and keys, and replaces identifier RANGES. `window.feedBack.isPlaying` — the PUBLIC mirror — is a different thing and is untouched. Two test sandboxes stub it; those were left alone deliberately. VERIFIED WITH REAL PLAYBACK. A/B against origin/main in two browsers, real song: togglePlay -> the public mirror goes true -> false -> true across two toggles, the audio element's paused state follows, seekBy works — IDENTICAL, zero page errors. Harnesses: 8 vm-sandbox suites slice playback code out of app.js and now see S.isPlaying — juce_engine_reroute, loop_restart, play_button_reroute_guard, playback_app_adapter, song_restart, song_seek, speed_reset, and the python idempotence source-assert. Each gets the same container in its sandbox; every assertion is unchanged. pytest 2396, node 1040/1040, ESLint 0, tailwind clean, Codex 0. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 21:52:51 +02:00
3 people	cb236e6c04	refactor(app): carve the A–B loop out of app.js (R3a) (#888) ... static/js/loops.js (261) — bodies VERBATIM. app.js 8,421 → 8,224. The second slice out of the strongly-connected core. It OWNS the loop state — loopA, loopB, _loopMutationGen. Nothing outside writes them: restartCurrentSong() looked like it did, but it declares its own local `let loopA/loopB` shadows, so the module-level bindings only ever change in setLoop / setLoopStart / setLoopEnd / clearLoop. All four move here. No state container. DIRECTION IS THE WHOLE DESIGN. loops and section-practice are mutually dependent — the SCC in miniature. clearLoop() must drop section-practice's selection, and practiceSection() must call setLoop(). Both edges cannot be imports or no-cycle (rightly) rejects it. So: section-practice -> reaches loops through the HOST SEAM (host.setLoop, …) loops -> imports section-practice DIRECTLY section-practice is the higher-level feature — a consumer of loops, not the reverse — so it is the one that takes the indirection. app.js hands the loop module's exports across into the seam for it. Graph stays acyclic; no-cycle passes. THE CONTRACT TEST EARNED ITS KEEP IMMEDIATELY. It failed on the first build with "these hooks are wired by app.js but no module reads them: playSong". My dependency scan had counted a mention of playSong() inside a COMMENT in loops.js as a real call. Wired but unused is precisely the "fossil of a rename" case the test exists for — and it caught it on a path no test executes. VERIFIED BY DRIVING BOTH SIDES OF THE SEAM. A/B against origin/main in two browsers, real song loaded: * setLoop(5,12) -> true; getLoop() -> 5,12 — IDENTICAL * clearLoop() (loops -> section-practice, a direct import) -> getLoop() -> null,null — IDENTICAL * onPhraseNext() (section-practice -> loops, ACROSS THE SEAM) -> ok — IDENTICAL * loadSavedLoop / saveCurrentLoop / deleteSelectedLoop on window — IDENTICAL * zero page errors either side. An unwired hook throws, so a live app is itself proof the seam is wired. Harness: loop_api extracts the loop helpers by signature — retargeted to loops.js, `export` stripped for the vm sandbox, and the sandbox's existing _audioSeek / _audioTime / formatTime spies are now routed through a `host` object so every assertion holds unchanged, just through the indirection the real code uses. It is SPLIT: one test still reads app.js for the window.feedBack API surface, which stayed. pytest 2396, node 1040/1040, ESLint 0 (no-cycle clean), tailwind clean. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 21:32:31 +02:00
3 people	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
3 people	f53d566dbc	refactor(app): give the <audio> element a module of its own (R3a) (#886) ... static/js/audio-el.js — one exported const. app.js's diff is 5 lines. This is a HINGE, not a carve: nothing shrinks, but almost everything left in app.js is blocked behind it. WHY. `audio` is `document.getElementById('audio')` with 162 references in app.js and 173 outside any one cluster. Every remaining cluster measured — settings, app-updates, count-in (208 fns), exit-confirm (212), library-render (220) — lists `audio` among its inbound symbols, because they all touch playback and playback reaches for the element directly. A module that needs it cannot import app.js to get it (that closes a cycle and fails import-x/no-cycle), so today the only way to carve any of them would be a host seam — the exact thing #878 had to build and #880 had to tear out. WHY IT'S SAFE. `audio` is a `const` and is NEVER reassigned anywhere in core, so a read-only import binding is exactly right and no state container is needed. The 162 call sites are untouched — the binding keeps its name, it is just imported instead of declared. (Contrast the reassigned scalars — isPlaying, _avOffsetMs — which CANNOT be shared this way: an imported binding cannot be written to. Those still need containers, and that is the next problem, not this one.) TIMING. app.js is <script type="module">, so it evaluates after the HTML is parsed and its imports evaluate just before its body — the same moment app.js used to run this exact lookup. If the element had not been in the document, `audio` would be null and app.js's top-level `audio.addEventListener(...)` calls would throw and kill the module. They don't. VERIFIED WITH REAL PLAYBACK, not a boot check. A/B against origin/main in two browsers: app alive with zero page errors (which is itself the proof the import resolved), #audio is an AUDIO element, togglePlay/seekBy live, and playSong() on a real library song sets audio.src and the element reports a duration — IDENTICAL on both sides. pytest 2396, node 1038/1038, 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:44:01 +02:00
3 people	b5dd585d25	refactor(app): carve settings backup + plugin updates out of app.js (R3a) (#885) ... Two leaves, one PR. app.js 9,651 → 9,457. static/js/settings-io.js (155) — exportSettings + importSettings, the Settings backup bundle. Imports nothing. The two-phase rationale comment (server first and atomic; then a best-effort localStorage merge) is the contract and moved with the code. plugin-updates → INTO static/js/plugin-loader.js, not a module of its own. checkPluginUpdates + updatePlugin are plugin MANAGEMENT; they belong with the code that loads plugins. A new file for 50 lines would have been a file for its own sake. All four are inline handlers on the Settings screen and already in app.js's window contract, so app.js re-exposes the imported bindings unchanged. VERIFIED BY DRIVING BOTH FLOWS. A/B against origin/main in two browsers: * checkPluginUpdates() -> hits the API and settles the button back to "Check for Updates" — IDENTICAL * exportSettings() -> POSTs /api/settings/export and writes "Exported feedBack-settings…" to #backup-status — IDENTICAL (fetch intercepted so the assertion is on the real call, not a stub) * all four resolve on window — IDENTICAL * zero console/page errors either side Zero harnesses broke. pytest 2396, node 1038/1038, ESLint 0, tailwind clean, Codex 0. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 19:42:54 +02:00
3 people	d47883c5e5	refactor(app): carve the tuning-display helpers out of app.js (R3a) (#884) ... static/js/tuning-display.js (228 lines) — bodies VERBATIM. app.js 9,838 → 9,650. A LEAF: imports nothing. Tuning NAME resolution (Drop D / Eb Standard / raw-offset fallback), bass detection, effective string count, and the target FREQUENCIES + note names the tuner checks against. Pure functions over a small MIDI/note-name table; the 3 _TUNING_* tables are read nowhere else and move in. NOT A SLICE — a node-level extract. The span 2309-2535 INTERLEAVES the functions with the `window.*` / `window.feedBack.*` assignments that publish them, and one of those is `window.feedBack = window.feedBack || {}` — the BUS BOOTSTRAP, not tuning code at all. Every ExpressionStatement stays exactly where it was; only the 16 functions and 3 tables move. app.js re-exposes the imported bindings from the same lines, so the public surface and its ordering are untouched (constitution II names window.feedBack). app.js -> { plugin-loader, viz, diagnostics-export, dom, highway-colors, tuning-display } HARNESSES — 4 broke, and 3 of them broke in the SAME informative way: they sliced app.js from `function isBassArrangement(` UP TO the marker `window.feedBack.parseRawTuningOffsets = parseRawTuningOffsets;` — an end-marker that (correctly) stayed behind in app.js. The module is now nothing BUT the tuning helpers, so there is no block to slice: they read it whole and strip `export ` so the vm sandbox still evaluates it as a script. tuner_auto_open is SPLIT — its autoplay-gate test still reads app.js, so it keeps APP_JS and gains TUNING_JS. Retargeting its path wholesale (my first attempt) silently pointed the autoplay test at the wrong file. VERIFIED BY DRIVING THE CONTRACT. A/B against origin/main in two browsers, through the real window surface: displayTuningName -> "E Standard" / "Drop D" / "Eb Standard", parseRawTuningOffsets('-2,0,0,0,0,0') -> [-2,0,0,0,0,0], isBassArrangement, effectiveStringCount, displayTuningTargets, and window.feedBack.displayTuningName / .songTuningContext — IDENTICAL on both, zero console/page errors either side. pytest 2396, node 1038/1038, ESLint 0, tailwind-fresh clean, Codex 0. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 19:37:44 +02:00
3 people	ebbfc8da6f	refactor(app): carve the highway string-colours out of app.js (R3a) (#883) ... static/js/highway-colors.js (601 lines) — bodies VERBATIM. app.js 10,415 → 9,837. Under 10k. DECOMPOSED, not sliced. The "settings" blob measured 47 fns / 19 inbound and was not carvable as-is. Seeding the closure from a FUNCTION (initHighwayColors) found only 18 fns and left 4 HWC_* constants used outside it — i.e. the seed was wrong, not the cluster. Re-seeding from the STATE (every function touching HWC_*/`_hwc*`) found the true cluster: 45 top-level nodes, lines 2751-3331, CONTIGUOUS, with ZERO foreign nodes inside the span. INBOUND: 0. EXPORTS: 2 (initHighwayColors, hwcInitSettingsUI). The other 43 symbols — the HWC_* tables, the 12 presets, the theme store, the share codec, the picker handlers, the window.feedBack.highwayColors facade — are used nowhere else in core and stay private. No inline on*= handlers here (the Settings buttons are wired by addEventListener inside hwcInitSettingsUI), so nothing needed re-exposing on window. The three bus listeners register inside initHighwayColors, which app.js calls — not at module top level — so no ordering change. THE no-undef GATE EARNED ITS KEEP. My closure said INBOUND=0; the module actually uses `uiPrompt` (the "name this theme" prompt). It was missed because uiPrompt is no longer an app.js DECLARATION — it's an IMPORT BINDING (from #882's dom.js), and I was collecting declarations only. `no-undef` with typeof:true caught it. => Lesson for the next carve: seed `tops` from ImportDeclaration bindings too. => And it VALIDATES carving dom.js early: this module just imports uiPrompt from it. Had dom.js still been stranded in app.js, this carve would have needed a host seam. app.js -> { plugin-loader, viz, diagnostics-export, dom, highway-colors } plugin-loader -> viz highway-colors -> dom viz, diagnostics-export, dom -> (leaves) VERIFIED BY DRIVING THE FACADE. A/B against origin/main in two browsers: window.feedBack.highwayColors installed, identical method surface, 12 presets, identical default slot colours, and a share-code encode→decode round-trip returning #112233 — IDENTICAL on both, zero console/page errors either side. Harnesses: highway_colors_facade + highway_string_colors retargeted (both brace-extract blocks out of the source by signature). pytest 2396, node 1038/1038, ESLint 0, tailwind-fresh clean, Codex 0. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 19:22:14 +02:00
3 people	14b4058bc6	refactor(app): carve the DOM/modal primitives out of app.js (R3a) (#882) ... static/js/dom.js (203 lines) — esc, _escAttr, _isElementVisible, _trapFocusInModal, _confirmDialog, uiPrompt. Bodies VERBATIM. app.js 10,593 → 10,414. A GATHER, not a slice — the six lived in six different places (108, 635, 659, 2617, 2623, 8892). They belong together because they are the BOTTOM of the UI stack: `esc` alone has 25 call sites and `_escAttr` 23, and every later carve that renders HTML will need them. That is the actual point of doing this one now. Give them a home and the next carve imports them; leave them in app.js and the next carve that renders HTML has to invent a host seam to reach back into app.js — exactly the trap the plugin-loader carve had to work around until the viz layer became a module. This is the cheapest possible way to stop that recurring. app.js -> { plugin-loader, viz, diagnostics-export, dom } plugin-loader -> viz viz, diagnostics-export, dom -> (nothing) Zero imports. Six exports (every one is used outside the cluster). VERIFIED BY DRIVING THE MODALS, not just booting — they are interactive, so a green suite says little. A/B against origin/main in two browsers: * window.uiPrompt / _confirmDialog / _trapFocusInModal all resolve * uiPrompt() mounts its modal, accepts typed input, and resolves with the typed value ('typed') — IDENTICAL on both * _confirmDialog() mounts and resolves true on confirm — IDENTICAL * zero console/page errors either side pytest 2396, node 1038/1038, ESLint 0, tailwind-fresh clean, Codex 0. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 18:59:44 +02:00
3 people	bfb31a8b89	refactor(app): carve the diagnostics-bundle export out of app.js (R3a) (#881) ... static/js/diagnostics-export.js (280 lines) — bodies VERBATIM. app.js 10,858 → 10,592. Chosen BY MEASUREMENT, not by eye. Ran the transitive closure over four candidate clusters and took the one with the smallest interface: diagnostics 7 fns 235 lines span 4110-4378 imports 1 exports 2 shortcuts-modal 5 fns 235 lines span 104-9897 imports 4 exports 5 settings+updates 47 fns 1012 lines span 1409-7636 imports 19 exports 30 library-render 220 fns 4064 lines span 20-10536 imports 126 exports 117 diagnostics is contiguous and nearly closed; its one inbound symbol (_DIAG_FILE_LABELS) lives inside the region and is read only by _renderDiagPreview, so it moves in and the module ends up a LEAF — imports nothing. app.js -> { plugin-loader, viz, diagnostics-export } plugin-loader -> viz viz, diagnostics-export -> (nothing) Exports exactly 2: previewDiagnostics + exportDiagnostics, both already in app.js's window contract (they're inline handlers in the Settings screen) — so app.js keeps re-exposing them, now as imported bindings. The preview renderer, the file-label table, and the byte/HTML formatters are used NOWHERE else in core and stay private. VERIFIED BY DRIVING IT, not just booting. Zero harnesses broke — because the diagnostics export flow had NO source-level test at all, which is exactly why a green suite proves nothing here. So the flow was exercised for real: A/B against origin/main in two browsers, window.previewDiagnostics() invoked, the preview container rendered identical content on both, both entry points resolve on window, zero console/page errors either side. pytest 2396, node 1038/1038, ESLint 0, tailwind-fresh clean, Codex 0. NOTE for the next carve: library-render is NOT a cluster — 220 functions and 126 inbound symbols is most of app.js entangled together. It cannot be carved as a unit; it needs decomposing from the inside first. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 18:52:47 +02:00
3 people	a222b45c02	refactor(app): carve the viz layer out of app.js — and delete the loader seam (R3a) (#880) ... static/js/viz.js (770 lines) — the viz picker, renderer selection, Auto-match, the WebGL2 probe, the 3D-promotion nag, the notation hints. Bodies VERBATIM. app.js 11,603 → 10,857. THE SEAM IS GONE. #878's plugin-loader needed configurePluginLoader({ populateVizPicker }) purely because _populateVizPicker lived in app.js and importing app.js would have closed a cycle. viz.js is a LEAF — it imports NOTHING — so plugin-loader now imports _populateVizPicker straight from it. The _host object, the configure function, its loud-default guard, and the wiring line in app.js are all deleted. The second carve simplifies the first. app.js -> { plugin-loader, viz } plugin-loader -> viz viz -> (nothing) NOT A PURE MOVE — one listener block had to be SPLIT. app.js had a single top-level `if (window.feedBack) { … }` registering four handlers, and only two were viz. song:loaded / arrangement:changed / song:ready (the mastery slider) stay in app.js and now call the imported _autoMatchViz / _maybeShowNotationViewHint. The viz:reverted handler MOVES, because it REASSIGNS _cancelPendingAutoLabel and an imported binding is read-only — `_cancelPendingAutoLabel = null` would throw if the listener stayed behind while the state moved. ORDER CHECKED, NOT ASSUMED: viz.js's song:ready listener now registers BEFORE app.js's own (imports evaluate first). Safe — _pendingPromotionNag is only ever set inside _populateVizPicker, which runs at boot/plugin-refresh, never from inside the other song:ready handler, so the two are independent. VERIFIED — the listeners are the risk here, so they were DRIVEN, not just booted. A/B against origin/main in two browsers: * viz picker: 6 options (auto|default|venue|drum_highway_3d|keys_highway_3d| highway_3d), selected highway_3d, Auto label — IDENTICAL. This alone proves plugin-loader's direct import of viz.js works. * emit('viz:reverted') -> picker resets to default, localStorage resets to default, the warning logs — IDENTICAL. The MOVED listener fires. * emit('song:ready') -> mastery slider enables, no throw — IDENTICAL. The SPLIT listener still does both halves. * plugin screens, module injections, 37 capability participants — IDENTICAL. * zero console/page errors on both. pytest 2396, node 1038/1038, ESLint 0, tailwind-fresh clean. no-cycle re-bitten on the 3-module graph (viz -> plugin-loader fails). Codex preflight raised a [P2] claiming viz.js's top-level bus guards would be false because "app.js only creates the event bus later" — FALSE POSITIVE. app.js does not create the bus; capabilities.js does, from its own <script type="module"> at index.html:122, and module scripts execute in document order, so the bus exists long before app.js's import graph evaluates. Instrumented the setter: by viz.js's turn `window.feedBack.on` is already a function, and the viz:reverted listener is provably attached (firing it resets the picker). The ordering is also enforced by test_app_shell_loads_capability_registry_before_app_runtime. Harnesses: 5 tests retargeted to viz.js across legacy_shim_hits, venue_scene_3d, venue_viz (each SPLIT — their non-viz tests still read app.js). Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 18:41:52 +02:00
4 people	5b904706d0	feat(audio): loopback feeder mode + static no-cache — all app audio under exclusive/ASIO (#877) ... * feat(audio): route feedpak full-mix natively under exclusive output Song playback runs through the renderer, which WASAPI-exclusive (and ASIO) output silences. Route single-mix feedpaks (stem-less original_audio packs AND single-stem packs) onto the engine's backing transport when the output device type is exclusive-style, and migrate back to HTML5 when it isn't. Extends /api/audio-local-path to resolve /api/sloppak/.../file/... URLs via the same containment guards as serve_sloppak_file. Multi-stem packs stay on the WebAudio path (Phase 2). Includes [feedpak-route] transition-gated diagnostics logging. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(audio): renderer-bus feeder — mix renderer song audio into engine output (Phase 2) Under exclusive-style output the native backing transport (Phase 1, #824) carries loose /audio/ songs and feedpak full-mixes, but not the stems plugin's multi-stem WebAudio graph or tracks JUCE rejected. The feeder taps the renderer-side master with an AudioWorklet, re-points the owning AudioContext at a null sink so it keeps rendering without a device, and pushes ~10 ms chunks over IPC into the desktop engine's renderer bus (feedBack-desktop#90 follow-up). Inert in the Docker sphere and in shared mode. Validated by the fix12 tester spike: null-sink rendering works, clocks hold, no overflow. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(diag): --debug ASIO routing diagnostics in static bundle Gated on window.feedBackDesktop.audio.debugEnabled() (desktop --debug); inert in the Docker sphere and normal desktop runs. - [asio-diag] getCurrentDevice= full device object on outputType change (catches ASIO drivers reporting a non-'ASIO' type name) - [asio-diag] renderer-bus: full feeder decision vector, change-gated (running/exclusive/stems/juceMode/elementSong/want/mode) - [asio-diag] setSink: every sink flip with ctx state + rate Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(audio): loopback feeder mode — all app audio under exclusive/ASIO Tester-confirmed (2026-07-11 log): song previews and other plugin-private audio bypass the per-surface feeder taps and leak to the default WASAPI device under ASIO output. Also confirmed: the element capture path poisons itself when highway_3d already owns #audio's one-shot MediaElementSource (InvalidStateError with _elCtx assigned pre-throw → TypeError every later tick). - New preferred mode 'loopback': one getDisplayMedia frame-audio capture (desktop main answers with the app's own frame) covers song, previews, and UI sounds for the whole exclusive session — engages even with no song loaded. Local playback silenced via suppressLocalAudioPlayback, page-mute IPC fallback otherwise. - Sticky fallback to the existing stems/element surface modes when capture is unavailable (old desktop main, denied, Docker sphere). - Element capture: assign module state only after the whole chain succeeds; close the context on failure — collision now retries clean. - Failed engage now disables the bus and tears down loopback (no more bus-enabled-with-no-producer stranding). - Tests: 12 (5 new — loopback engage/preference/mute-fallback/sticky fallback, collision retry). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(audio): loopback feeder mode — all app audio under exclusive/ASIO Tester-confirmed (2026-07-11 log): song previews and other plugin-private audio bypass the per-surface feeder taps and leak to the default WASAPI device under ASIO output. Also confirmed: the element capture path poisons itself when highway_3d already owns #audio's one-shot MediaElementSource (InvalidStateError with _elCtx assigned pre-throw → TypeError every later tick). - New preferred mode 'loopback': one getDisplayMedia frame-audio capture (desktop main answers with the app's own frame) covers song, previews, and UI sounds for the whole exclusive session — engages even with no song loaded. Local playback silenced via suppressLocalAudioPlayback, page-mute IPC fallback otherwise. - Sticky fallback to the existing stems/element surface modes when capture is unavailable (old desktop main, denied, Docker sphere). - Element capture: assign module state only after the whole chain succeeds; close the context on failure — collision now retries clean. - Failed engage now disables the bus and tears down loopback (no more bus-enabled-with-no-producer stranding). - Tests: 12 (5 new — loopback engage/preference/mute-fallback/sticky fallback, collision retry). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(audio): close loopback capture context on teardown (release tap worklet) The loopback context was reused across engages (_lbCtx || new), but teardown only stopped the stream + deactivated the tap — never closing the context or detaching the worklet node. Each exclusive<->shared switch orphaned a live tap worklet on the long-lived context. Use a fresh context per session and close it on disengage. Adds a test asserting the context is closed on teardown. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(diag): install-time + uncaught-error diagnostics for the reroute chain 2026-07-11 tester log showed the routing watcher and renderer-bus feeder never installed (zero [feedpak-route]/[renderer-bus] lines) plus an uncaught SyntaxError with no source location — nothing in the log said why. New: - global error/unhandledrejection tap logging message + filename:line:col (error events carry the location even for parse errors in other scripts) - explicit install / NOT-installed lines for watcher and feeder (incl. loopback capability probe) - DOMException detail (name/message/stack head) in the feeder retry warn — the console-message forward stringified it to [object DOMException] Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(static): force conditional revalidation on /static (Cache-Control: no-cache) Without Cache-Control Chromium's heuristic freshness (10% of file age) serves /static/app.js from disk cache for hours-to-days without revalidating. Desktop consequence: a new build's window ran the previous build's app.js — the 2026-07-11 ASIO investigation traced 'routing watcher never installed' + a stems module-plugin SyntaxError to exactly this (stale loader predating scriptType support). no-cache keeps caching but revalidates via ETag — unchanged files still cost only a 304. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(diag): gate install-time + uncaught-error [asio-diag] lines on --debug The error tap and install lines from the previous diag commit were unconditional. Now: error/rejection taps check _asioDiagEnabled() at event time; install lines log deferred once the async debugEnabled() resolves true. The NOT-installed anomaly lines stay bridge-gated (window.feedBackDesktop present) instead — a broken bridge can't deliver the debug flag, they fire at most once, and only in the broken state they exist to witness. Docker sphere: fully silent. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com> Co-authored-by: Byron Gamatos <xasiklas@gmail.com>	2026-07-11 18:22:25 +02:00
3 people	38772f604a	refactor(app): carve the plugin loader out of app.js into static/js/ (R3a) (#878) ... The first carve, and deliberately the riskiest: app.js IS the plugin loader (the R0 host rails), so it goes first while the module graph is still one edge deep. static/js/plugin-loader.js (829 lines) — bodies VERBATIM. app.js 12,217 → 11,439. Core's first `static/js/` module, exactly as constitution II anticipates. CLOSURE (measured with acorn, not regex — brace-matching stripped source drifted): the block at app.js:11246-12031 is contiguous and self-contained. It needs only TWO things from the rest of app.js, and exports only TWO: exports: loadPlugins (the window contract), bootstrapPluginsAndUi (boot) inbound: window.showScreen — already the public host contract (constitution II), so it is called through `window`, not re-coupled as an import _populateVizPicker — injected via configurePluginLoader() WHY A SEAM, NOT AN IMPORT. plugin-loader must not import app.js: app.js imports it, so that would close a cycle. I checked whether _populateVizPicker could just move into the module instead (which would delete the seam entirely) — it drags 9 further symbols (_canRun3D, _autoMatchViz, _showPromotionNag, …), i.e. a whole viz cluster. That is its own carve, so the seam stays. THE SEAM'S DEFAULT IS LOUD, ON PURPOSE. A no-op stub is the classic silent failure for this pattern (see the editor's setHostHooks trap, hit twice): drop the wiring call and the loader keeps working while the viz picker quietly stops refreshing — no test, no boot check says a word. The default now console.errors, so the smoke harness catches it. VERIFIED BY BITE TEST: removing configurePluginLoader() from app.js surfaces "[plugin-loader] host seam not configured" at boot. The seam IS exercised on the plugin-startup path, so an unwired hook cannot pass silently. no-cycle is now LIVE on core's own graph for the first time. eslint.config.js gains `static/app.js` + `static/js/**` to the module block — app.js now `import`s, so parsing it as a script would be a syntax error. VERIFIED BY BITE TEST: making plugin-loader import app.js back fails with "Dependency cycle detected". HARNESSES (the R3a note said budget one conversion per carve — it was five): retargeted capability_inspector_nav, plugin_hydration_wipe, plugin_loader_script_type, plugin_style_injection, legacy_shim_hits (SPLIT — one test needs the loader, one still needs app.js) + test_plugin_runtime_idempotence. legacy_shim_hits was missed by a symbol-name grep because it greps for a code STRING; only the failing run found it. test_capability_events' NEGATIVE asserts now span app.js + the loader — carving code out of app.js would otherwise make them vacuous instead of failing. VERIFIED: A/B against origin/main in two browsers — mounted plugin screens, 14 loaded plugin scripts, the 3 module plugins injected as <script type="module">, 37 capability participants, 14 shims, window.loadPlugins: IDENTICAL, zero console/page errors on both. /static/js/plugin-loader.js serves 200; R0 rails intact (src/main.js 200, conditional GET 304, script_type passthrough). pytest 2396, node 1032/1032, ESLint 0, Codex 0. Codex preflight caught a REAL [P1] first pass: static/js/plugin-loader.js was untracked, so a checkout would have served an app.js importing a nonexistent module — a failed static import kills the whole module and every window handler with it. Now tracked. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 18:18:00 +02:00
3 people	92c86f5393	refactor(ui): load app.js as an ES module (R3a) (#876) ... One attribute. #871/#872/#874/#875 exist to make this line safe. app.js's 385 top-level `function` declarations stop being implicit `window` properties: 87 stay reachable via the explicit contract (#874's Object.assign block + the 47 pre-existing `window.X = X` assignments), and 298 become module-private. Verified NO unexposed name is read from outside app.js. Strict mode (modules are always strict) checked ahead of the flip: app.js parses clean as `sourceType: module` (no octal, dup params, `with`), and has no implicit globals, no `eval`/`new Function`, no top-level `this`. `registerShortcut` is called bare at 15 top-level sites but is assigned at `window.registerShortcut` (app.js:10387) before its first call (10648), and a bare identifier in a module still resolves through the global object — verified `typeof window.registerShortcut === 'function'` in the browser. HARD GATE — app.js IS the plugin loader: - /api/plugins script_type passthrough: editor/stems/studio = "module" - /api/plugins/stems/src/main.js -> 200; conditional GET -> 304 (live-edit ETag) - deep graph: stems/src/transport.js, editor/src/state.js -> 200 - window.loadPlugins present; 5 plugin screens mount; the 3 migrated plugins injected as <script type="module"> - 37 capability participants, 14 compatibility shims, bus + capabilities v1 Every one of the shell's 336 inline handlers resolves on window under module scope, and the A-Z rail / pagination execute 6/6 with no ReferenceError. A/B against origin/main: the ONLY unresolvable handler is `editorToggleStemMixer`, which is equally broken on main (a dead handler in the editor plugin — not defined anywhere in its source; pre-existing, flagged separately). Codex preflight raised a [P1] claiming restartCurrentSong / requestExitSong / editRegionInEditor / returnToEditorFromHighway would ReferenceError — FALSE POSITIVE. It scanned only #874's new Object.assign block and missed app.js's 47 scattered `window.X = X` assignments; all four are at app.js:7086/7204/8492/8511 and all four resolve as `function` in the browser with app.js loaded as a module. pytest 2396, node 1032/1032, ESLint 0 errors, tailwind-fresh clean. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 17:38:33 +02:00
3 people	c223ace419	refactor(ui): load the capabilities as ES modules (R3a) (#875) ... The 12 capability <script> tags become type="module". No JS changes — the capability scripts already self-register on the window.feedBack bus, version-negotiate (`capabilities.version !== 1` → bail), and self-guard for idempotency. They never import or call app.js; it is pure pub/sub. Verified they export nothing by name: no top-level declaration in capabilities.js or capabilities/*.js is read by any other script, so losing global scope costs nothing. This is the first REAL exercise of the ordering fix from #872. A module defers to after HTML parse, so the capabilities now execute AFTER the document is parsed — while app.js still calls `window.feedBack.on(...)` at its top level. That only works because #872 put every classic script into the same deferred queue, where document order IS execution order: capabilities.js (line 122) still runs before app.js (line 1237). Had app.js stayed a plain classic script it would have run during parse, hit a bare `{}`, and died on `.on is not a function`. A/B against origin/main, 11 probes — capabilities.version, registered participants (37), compatibility shims (14), the bus, workingTuning, theme, setViz/showScreen/playSong, mounted plugin screens: IDENTICAL, zero console/page errors on both. 12 module tags served and executed; pytest 2396, node 1032/1032, ESLint 0, Codex 0. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 17:15:38 +02:00
3 people	ff7e855e35	refactor(app): make app.js's window contract explicit — 66 names (R3a) (#874) ... app.js is a classic script, so each of its 385 top-level `function foo()` decls is implicitly a property of `window`. As an ES module it will not be — module scope is not global scope — and every name reached from outside this file would silently vanish. This adds the explicit `window.*` assignments BEFORE the flip. Provably a NO-OP: all 66 are top-level function declarations, so while app.js is still a classic script `Object.assign(window, {...})` only re-assigns what `window` already has. That is what makes it safe to land on its own, ahead of the flip that needs it. The consumers are wider than the inline handlers in index.html: - inline on*= handlers in static/v3/index.html - on*= handlers app.js BUILDS inside template literals (goFavPage, updatePlugin, hideScanBanner, ...) — they resolve against window at CLICK time, but live in a JS string, so scanning the HTML alone never finds them - static/v3/*.js (showScreen alone has 17 consumers), capabilities - feedback-desktop and the external plugin repos — easy to miss, they live in other repos and no core test covers them - capabilities/visualization.js reads window.setViz behind a `typeof` guard, so losing it DEGRADES IN SILENCE rather than throwing Constitution II names window.playSong / window.showScreen / window.feedBack as the public extension contract, so this is an obligation, not a convenience. FOUR names are invisible to every static tool. app.js:2156-2157 picks the handler NAME at runtime — const letterFn = favoritesOnly ? 'filterFavTreeLetter' : 'filterTreeLetter'; — and interpolates it into `onclick="${letterFn}('A')"`. The names exist only inside string literals, so ESLint, no-undef, and any grep for `onclick="fn` all miss them. They are the library A-Z rail and its pagination: drop one and those buttons throw at click time and nowhere else. New tests/js/window_contract.test.js scrapes the HTML's handlers AND app.js's template-literal handlers, and pins the 4 runtime-composed names by hand. Verified to BITE: dropping showScreen, goTreePage, or setViz each fails it with the right message. On-device: 28 A-Z rail buttons render with their real onclick sources (filterTreeLetter('A'), ...) and 8/8 execute with no ReferenceError; all 66 names resolve on window in the browser. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 17:09:18 +02:00
3 people	4b4c156fce	refactor(ui): defer every classic script, keep boot() on DOMContentLoaded (R3a) (#872) ... Puts every external `<script>` in the v3 shell into the deferred queue, and keeps each script's boot() firing at DOMContentLoaded exactly as it does today. Behaviourally a no-op; it is what makes the ES-module flips safe. WHY. `type="module"` defers execution to after HTML parse. Classic-`defer` and module scripts share ONE "execute after parsing" list and run in DOCUMENT ORDER, but a plain classic script runs DURING parse — ahead of all of them. So the moment capabilities.js becomes a module while app.js is still plain, app.js runs FIRST, and its 11 top-level `window.feedBack.on(...)` calls (app.js:6245-6722) hit a bare `{}` — `_ensureFeedBackEventBus()` (capabilities.js:33), which attaches .on/.emit/.off, would not have run yet. TypeError, app.js dies mid-parse. Deferring everything now keeps document order == execution order through the rest of the migration. THE CATCH (Codex preflight caught this — a real ordering change). 22 scripts guard their boot with `if (document.readyState === 'loading')`. A deferred script runs at readyState 'interactive', so that test is FALSE and the else-branch fires boot() immediately, at the script's position in document order — instead of at DOMContentLoaded, after every script has evaluated. That matters far more than one call site: a scan of the shell's scripts found **43 forward references** where a script's boot() reads a global that a LATER script defines (shell.js -> profile.js's window.v3Onboarding, songs.js -> settings.js's window._confirmDialog, badges.js -> songs.js's window.displayTuningName, ...). Every one of them resolves today only because all boots happen at DOMContentLoaded. So the guards now treat 'interactive' as not-ready (`!== 'complete'`), restoring that exactly. Codex's specific finding (first-run onboarding silently skipped) did NOT reproduce — shell.js's boot() awaits /api/profile, and that yield lets the remaining deferred scripts run first. But the race it described is real, the guard is silent when it fails (`&& window.v3Onboarding`), and the other 42 forward refs have no such await protecting them. Fixed at the root rather than at the one site. VERIFIED. A/B against origin/main on a fresh profile, 13 probes (onboarding overlay, v3Onboarding/v3Songs/v3Profile/fbNotify/v3Badges/uiPrompt/showScreen, bus, capabilities.version, createHighway, plugin scripts, mounted screens): IDENTICAL, zero console/page errors on both. pytest 2396, node 1028/1028, ESLint 0 errors, Codex 0. New guard: test_every_external_script_defers_so_document_order_is_execution_order fails if any external tag is plain classic — verified to fail on a single reverted tag, so it actually bites. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 16:57:04 +02:00
3 people	9d0bf95716	refactor(ui)!: remove the classic v2 shell — v3 is the only UI (R3a) (#871) ... * refactor(ui)!: remove the classic v2 shell — v3 is the only UI (R3a) Deletes `static/index.html`, the `/v2` route, and the `FEEDBACK_UI` v2/legacy opt-out. `/` and `/v3` both serve `static/v3/index.html`, which has been the default since 0.3.0. This is step 0 of the core-frontend ES-module migration (R3a). Both shells load the same `static/app.js`, so every later step of that migration — exposing the window contract, the `defer` ordering fix, the `type="module"` flips — would otherwise have to be made and verified twice. Removing the fallback now halves that surface before any of it is touched. Incidentally fixes a latent bug in `index()`: its guard read `if getenv_compat("FEEDBACK_UI") or getenv_compat("FEEDBACK_UI") in ("v2", "legacy")`, whose left operand is truthy for *any* non-empty value — so `FEEDBACK_UI=v3` actually served the **v2** shell. - `static/tailwind.min.css` regenerated: the content globs scanned the deleted file, so v2-only utility classes are now purged (CI's tailwind-fresh job rebuilds and diffs it). - Constitution amended to 1.3.0 — Principle II's frontend file list now names `static/v3/index.html`. - Tests: 4 suites read the v2 shell (3 via a constructed `path.join` that a literal grep misses). Their v2 halves are paired duplicates of v3 tests that stay, so they are dropped; `alpha_warning_banner` and the capability-registry script-order test retarget to `static/v3/index.html`. BREAKING CHANGE: `FEEDBACK_UI=v2` / `=legacy` and the `/v2` route are gone. Unset the variable and use `/`. No chart, settings, or plugin data changes, and no plugin API changes — v3 reuses the same engine. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: drop the stale '/ is v2' plugin-verification guidance (CodeRabbit) The v3-only rewrite updated the intro paragraphs but left three lines that still instructed plugin authors to verify in 'both / (v2) and /v3' — now the same shell. Historical 'in v2 it was X' contrasts are kept: they still orient authors whose plugins also ship to users on older cores. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 16:33:03 +02:00
3 people	5e30138c87	refactor(server): extract the artist routes into routers/artist.py (R3) (#870) ... The artist page + external-links payload (/api/artist/{name}/page, /links, /links/refresh) plus their exclusive helpers (_artist_links_payload, _artist_links_from_mb, the URL-slot table) move to lib/routers/artist.py. Bodies verbatim except @app->@router and the seam reads (meta_db->appstate.meta_db, CONFIG_DIR->appstate.config_dir, _default_settings->appstate.default_settings). MB link enrichment is reached as enrichment.X; the URL-safety validator is imported from lib/library_registry.py. No new seams. server.py: 2,507 -> 2,413 (-94). Verified: pyflakes clean; route set unchanged (143); full pytest 2395 passed. eslint 0. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 15:49:37 +02:00
3 people	0547f55844	refactor(server): extract the media/file-serving routes into routers/media.py (R3) (#869) ... Song audio (/audio/{f}), the local-audio-path resolver (/api/audio-local-path), and raw sloppak-member serving (/api/sloppak/{f}/file/{rel}) — plus the shared _resolve_sloppak_local_file helper — move to lib/routers/media.py. Bodies verbatim except @app->@router and the cache/static path seams (AUDIO_CACHE_DIR-> appstate.audio_cache_dir, STATIC_DIR->appstate.static_dir, SLOPPAK_CACHE_DIR-> appstate.sloppak_cache_dir — all already in the seam). No new slots. The two test fixtures that redirect STATIC_DIR to a temp dir now also patch appstate.static_dir (the moved routes read the seam, not server's global). server.py: 2,638 -> 2,507 (-131). Verified: pyflakes clean; route set identical (143), all unique-path (no catch-all, no shadowing); full pytest 2395 passed (the audio-local-path + sloppak-file-traversal cases). eslint 0. Boot smoke: /audio, /api/sloppak/{}/file serve 404 for unknown, 0 tracebacks. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 15:36:22 +02:00
3 people	b7624b7e65	refactor(server): extract the enrichment route handlers into routers/enrichment.py (R3) (#868) ... The 14 /api/enrichment/* routes — status, kick/cancel, per-song state, the Match-Review queue (accept/reject/pick/search/rematch/refresh/states), and the AcoustID fingerprint identify endpoints — plus the route-exclusive candidate sanitizer move to lib/routers/enrichment.py. Bodies verbatim except @app->@router and the seam reads (meta_db->appstate.meta_db, CONFIG_DIR->appstate.config_dir). The enrichment engine (transport, matcher, worker, upload caps) already lives in lib/enrichment.py from the earlier subsystem move and is reached as enrichment.X. No new seams. server.py: 2,925 -> 2,638 (-287). Verified: pyflakes clean; route set identical (143); full pytest 2396 passed (the enrichment route + Match-Review + identify cases, which fake the network on the enrichment module). eslint 0. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 15:19:34 +02:00
Byron GamatosandGitHub	f00ba2217d	Revert "feat(audio): loopback feeder mode — all app audio under exclusive/ASIO (#865)" (#867) ... This reverts commit 9a58a55fe8.	2026-07-11 14:56:35 +02:00
3 people	f09c4a217f	refactor(server): extract library + collections routes + the provider registry (R3) (#866) ... The library query surface (songs/albums/artists/stats/genres/tuning-names/ practice-suggestions), the provider list/art/sync endpoints, and collection CRUD move to lib/routers/library.py. The registry itself — LibraryProviderRegistry, LocalLibraryProvider, SmartCollectionProvider, the collection-provider lifecycle (_sync/_unregister_collection_provider), and the shared query/collection helpers (_library_filter_args, _split_csv, _sanitize_collection_rules, _safe_art_redirect_url, the filter-key sets) — moves to lib/library_registry.py. The PLUGIN CONTRACT is untouched: server.py still constructs the singleton (LocalLibraryProvider needs meta_db), still exposes register_library_provider / unregister_library_provider to plugins via plugin_context (with the per-plugin ownership scoping in plugins/__init__.py), and injects the registry + local provider into appstate. The router reads appstate.library_providers / appstate.local_library_provider at call time; the provider classes are duck-typed so no plugin imports a base class. Acyclic: library_registry imports routers.art (for LocalLibraryProvider.get_art) + appstate, never server. server.py: 3,692 -> 2,925 (-767). Verified: pyflakes clean; ORDERED route table identical set (library block mounts at one site — all exact/specific-path, no catch-all, no shadowing); full pytest 2397 passed (incl the plugin register/unregister + collection-as-provider tests). eslint 0. Boot smoke: /api/library + providers list "local"; a created collection surfaces as a `collection:N` provider through the seam; collection CRUD clean. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 14:56:12 +02:00
4 people	9a58a55fe8	feat(audio): loopback feeder mode — all app audio under exclusive/ASIO (#865) ... * feat(audio): loopback feeder mode — all app audio under exclusive/ASIO Tester-confirmed (2026-07-11 log): song previews and other plugin-private audio bypass the per-surface feeder taps and leak to the default WASAPI device under ASIO output. Also confirmed: the element capture path poisons itself when highway_3d already owns #audio's one-shot MediaElementSource (InvalidStateError with _elCtx assigned pre-throw → TypeError every later tick). - New preferred mode 'loopback': one getDisplayMedia frame-audio capture (desktop main answers with the app's own frame) covers song, previews, and UI sounds for the whole exclusive session — engages even with no song loaded. Local playback silenced via suppressLocalAudioPlayback, page-mute IPC fallback otherwise. - Sticky fallback to the existing stems/element surface modes when capture is unavailable (old desktop main, denied, Docker sphere). - Element capture: assign module state only after the whole chain succeeds; close the context on failure — collision now retries clean. - Failed engage now disables the bus and tears down loopback (no more bus-enabled-with-no-producer stranding). - Tests: 12 (5 new — loopback engage/preference/mute-fallback/sticky fallback, collision retry). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(audio): close loopback capture context on teardown (release tap worklet) The loopback context was reused across engages (_lbCtx || new), but teardown only stopped the stream + deactivated the tap — never closing the context or detaching the worklet node. Each exclusive<->shared switch orphaned a live tap worklet on the long-lived context. Use a fresh context per session and close it on disengage. Adds a test asserting the context is closed on teardown. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com> Co-authored-by: Byron Gamatos <xasiklas@gmail.com>	2026-07-11 14:54:40 +02:00
3 people	bbdff4e10f	refactor(server): extract the song routes into routers/song.py (R3) (#864) ... Upload/delete, the catalog-metadata write-back, user-meta, overrides, gap-fill, and the per-song info payload (11 routes) move to lib/routers/song.py with their exclusive helpers (the atomic upload commit + the song-IO lock, the upload caps, the gap-fill proposal builders). Bodies verbatim except @app->@router and the seam reads: meta_db->appstate.meta_db, art_override_paths->appstate.art_override_paths, and the scan/ingest helpers that stay in server.py (the scan lifecycle owns them) -> new appstate seam callables: kick_scan, invalidate_song_caches, stat_for_cache, and scan_status() (a getter — the underlying dict is reassigned). The gap-fill MBID/ISRC regexes are reached as enrichment.X; _MULTIPART_OVERHEAD_SLACK (shared with the staying AcoustID-identify route) moves to lib/enrichment.py beside _ACOUSTID_MAX_UPLOAD_BYTES. ROUTE ORDER: song_router mounts AFTER art_router — get_song_info's catch-all `/api/song/{filename:path}` would otherwise shadow `/api/song/{path}/art*` (Starlette matches first-registered; the :path converter is greedy). server.py: 4,478 -> 3,692 (-786). Verified: pyflakes clean; ORDERED route table preserves the specific-before-catch-all invariant; full pytest 2397 passed (incl the art/cover 304 + CAA-fetch tests that caught the shadowing before it was fixed). eslint 0. BEHAVIORAL — needs an on-device pass (upload a sloppak, edit metadata write-back, delete a song) before merge. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 13:14:52 +02:00
3 people	7258e1066a	refactor(server): extract the settings routes into routers/settings.py (R3) (#863) ... GET/POST /api/settings, /api/settings/reset, and the two-phase atomic export/import bundle (/api/settings/export|import) move to lib/routers/settings.py with their exclusive helpers (the relpath allowlist validator, the atomic writer, the library-DB snapshot + sqlite integrity gate, the config-type validator, the bundle schema). Bodies verbatim except @app->@router and the seam reads: meta_db->appstate.meta_db, CONFIG_DIR->appstate.config_dir, _running_version->appstate.running_version(), and _default_settings-> appstate.default_settings (the canonical defaults builder stays in server.py — the scan + artist-links code share it — and is injected as a new seam callable). server.py: 5,539 -> 4,478 (-1,061). Verified: pyflakes clean (bar the pre-existing File/safe_join/tuning_name/ET); route table IDENTICAL (143); full pytest 2397 passed (154 settings cases incl the export→import round-trip + library-DB snapshot/restore + relpath-allowlist SSRF/ traversal guards, retargeted onto the settings module). eslint 0. BEHAVIORAL — needs an on-device settings export→import round-trip sign-off before merge (do not merge on green CI alone). Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 12:35:05 +02:00
3 people	73127d5416	refactor(server): extract the album-art routes into routers/art.py (R3) (#862) ... The six song-art routes — GET /api/song/{f}/art, .../art/cover-search, .../art/candidates, POST .../art/upload, .../art/url, DELETE /api/art/{f}/override — plus their exclusive helpers (the ETag/304 response machinery, _save_art_override, _url_host_is_internal, _fetch_art_url + the art size/redirect caps) move to lib/routers/art.py. Bodies verbatim except @app->@router and the seam reads: meta_db->appstate.meta_db, ART_CACHE_DIR->appstate.art_cache_dir, and the three shared art helpers that stay in server.py (used by the song/delete routes too) -> appstate.<callable> (_song_pack_art_exists, _art_override_paths — already seam-injected for the enrichment worker — plus a new art_safe_name slot). The CAA / release-search transport lives in lib/enrichment.py and is reached as enrichment.X. LocalLibraryProvider.get_art now calls art_router.get_song_art. server.py: 5,988 -> 5,540 (-448). Verified: pyflakes clean (bar the pre-existing File/safe_join/tuning_name/ET); route table IDENTICAL (143); full pytest 2399 passed (33 art serve/candidates/ override/url cases incl the SSRF-guard _url_host_is_internal + _fetch_art_url size-cap tests, retargeted onto the art module); test_packaging 43; eslint 0. Boot smoke: /art 404, /art/candidates 404, DELETE /override 200 from the router. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 11:56:53 +02:00
3 people	165475d115	refactor(server): move the metadata-enrichment subsystem into lib/enrichment.py (R3) (#861) ... * refactor(server): move the metadata-enrichment subsystem into lib/enrichment.py (R3) MusicBrainz / Cover-Art-Archive / AcoustID transport, the match-scorer glue, and the background enrichment worker (~930 lines, 61 defs) leave server.py as one cohesive unit. Bodies are verbatim; the only changes are seam reads: meta_db / config_dir / sloppak_cache_dir / art_cache_dir -> appstate.<slot> _song_pack_art_exists / _art_override_paths (stay in server.py for the art + delete routes) -> appstate.<callable> (new seam slots, injected by reference) _env_flag -> env_compat.env_flag_compat (the existing identical helper) _artist_title_from_filename -> imported from metadata_db (its home) the User-Agent VERSION lookup: Path(__file__).parent -> Path(__file__).resolve().parents[1] (lib/enrichment.py -> app root) server.py drives the worker through the module (import enrichment; the routes + scan lifecycle call enrichment.X). Tests that faked the network on `server` (_mb_http_get, _enrich_network_enabled, _caa_http_get, ...) now patch the same names on `enrichment` — the module attribute is resolved at call time, so one setattr reaches both the routes and the worker's internal callers. Acyclic: enrichment imports appstate/appconfig/dlc_paths/metadata_db/mb_match/ acoustid_match/sloppak/loosefolder, never server. server.py: 6,917 -> 5,988 (-929). Verified: pyflakes clean (bar the pre-existing File/safe_join/tuning_name/ET); route table IDENTICAL (143); full pytest 2400 passed (140 enrichment/art cases incl the offline-safety + transport-error-pauses-pass contracts that fake the network); test_packaging 44 passed (enrichment.py resolves under lib/); eslint 0. Boot smoke: /api/enrichment/status + POST /kick serve from the new module. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * test: reset enrichment worker state between tests (CodeRabbit) lib/enrichment.py now owns the worker, and it stays imported for the whole session while the `server` fixtures pop-and-reimport `server` — so the cancel Event / status dict / caches would leak across tests, and a stale `_enrich_cancel` could short-circuit a later direct `_background_enrich()`. An autouse conftest fixture clears that process-global state before each test. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * test: tighten the enrichment-reset fixture (CodeRabbit) Narrow the import guard to ImportError (not blind Exception, BLE001), and stop clearing _caa_index_locks — it's guarded by _caa_index_locks_guard, so an unlocked clear() would race a still-alive worker, and its per-release mutexes carry no test state. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-11 11:32:21 +02:00