refactor(studio): extract the visualisation layer to src/viz.js (step 6)

[byrongamatos]

What

Step 6. Moves the visualisation layer out of main.js into src/viz.js:

• rAF playhead loop: _startAnimLoop / _stopAnimLoop
• waveform canvas + zoom/scroll: _drawWaveform / _redrawWaveform / _drawAllCursors / _clampScroll / _initWaveformWheelZoom
• master level meter: _startMasterMeter / _debounceSaveMaster

Upper layer over the audio engine: imports _getAudioCtx (audio-graph) + _formatTime (util), reaches the stop action via the window.studioStop global (no import-back). Its 3 animation/meter exports are what main.js injects into audio-graph via configureAudioGraph — no cycle (audio-graph never imports viz).

Also moved _getTrackColor + TRACK_COLORS/INSTRUMENT_COLORS → util.js: viz's _redrawWaveform needs it and so does main's render, so the pure colour helper belongs in the shared leaf. (This fixes the ReferenceError Codex flagged in preflight — viz referencing a main-private helper.) Added a _getTrackColor unit test.

main.js 2489 → 2236.

Tests

node --test 15/15, pytest 25/25. Codex preflight: 0 (clean after the _getTrackColor fix).

Behavioral (rendering/animation) — on-device pass: waveforms draw (incl. recorded tracks), playhead animates, zoom/scroll, level meter.

Summary by CodeRabbit

• New Features

  • Enhanced waveform playback visuals, including improved playhead syncing, cursor updates, session markers, and smoother zoom/scroll interaction.
  • Added/updated automatic master level meter updates during playback.

• Bug Fixes

  • Track colors are now more consistently selected, honoring explicit colors first, then matching by track name/instrument, with a stable palette fallback.
  • Playback now stops cleanly when the session reaches its end.

• Tests

  • Added unit coverage for track color selection logic and the playback stop hook behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 692fa25b-31dc-42d8-b645-703d7f0ea60d

📥 Commits

Reviewing files that changed from the base of the PR and between 46fd4ac and 12c682a.

📒 Files selected for processing (1)

• src/viz.js

🚧 Files skipped from review as they are similar to previous changes (1)

• src/viz.js

---

📝 Walkthrough

Walkthrough

This PR extracts visualization logic from src/main.js into src/viz.js, moves track-color selection into src/util.js, updates wiring to use the new helpers, and adds tests plus a changelog note.

Changes

Visualization extraction

Layer / File(s)	Summary
Track color utility extraction src/util.js, src/main.js, tests/util.test.mjs	TRACK_COLORS, INSTRUMENT_COLORS, and _getTrackColor move into src/util.js; main.js imports the helper; the utility test covers explicit, name-based, instrument-based, and fallback color selection.
Animation loop and waveform rendering module src/viz.js, src/main.js	_startAnimLoop, _stopAnimLoop, _drawWaveform, _redrawWaveform, and _drawAllCursors move into src/viz.js, with matching removals from main.js.
Master meter and zoom/scroll controls src/viz.js, src/main.js	_startMasterMeter, _debounceSaveMaster, _clampScroll, and _initWaveformWheelZoom are implemented in src/viz.js and replace the removed in-file helpers.
Audio graph wiring tests tests/audio-graph.test.mjs	New tests verify exported function presence, configureAudioGraph input tolerance, and invocation of an injected stopAnimLoop hook during _pause().
Changelog entry CHANGELOG.md	Documents the visualization-layer extraction as a move-only change.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant RAF as requestAnimationFrame
  participant Viz as viz.js
  participant DOM as Studio UI
  participant Window as window.studioStop

  RAF->>Viz: _startAnimLoop tick
  Viz->>DOM: update studio-time-current, studio-seek-bar
  Viz->>Viz: _drawAllCursors(timeSeconds)
  Viz->>DOM: redraw waveform canvases
  Viz->>Window: studioStop() when duration reached

Loading

Possibly related PRs

• got-feedBack/feedBack-plugin-studio#17: Builds on the same ES-module refactor by moving helper logic into src/util.js, which this PR now uses for track color selection.
• got-feedBack/feedBack-plugin-studio#20: Introduces the injected audio-graph seams that this PR’s stopAnimLoop wiring and tests rely on.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: extracting the studio visualization layer into src/viz.js.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/es-module-split-viz

---

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

This PR continues the Studio ES-module refactor by extracting the visualisation responsibilities (playhead rAF loop, waveform rendering/zoom/scroll, and master level meter) out of main.js into a dedicated src/viz.js, while also relocating the shared track-colour helper into src/util.js and adding focused unit tests to pin the new seams.

Changes:

• Extract visualisation logic from src/main.js into src/viz.js and wire it back via configureAudioGraph (avoiding an import cycle).
• Move _getTrackColor (and its palettes) into src/util.js for shared use, and add a unit test for it.
• Add tests/audio-graph.test.mjs to validate the configureAudioGraph injection contract and module importability.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/util.test.mjs	Adds coverage for the newly shared _getTrackColor helper.
tests/audio-graph.test.mjs	Pins the configureAudioGraph seam and verifies exported surface.
src/viz.js	New module containing the visualisation layer (animation loop, waveform rendering, master meter).
src/util.js	Adds _getTrackColor and related palette constants.
src/main.js	Removes inlined visualisation/color helpers and imports them from viz.js/util.js.
CHANGELOG.md	Documents step 6 of the ES-module migration.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.