feat(editor): buffer-less compose-mode transport (Phase A3)

[ChrisBeWithYou]

Phase A3 — buffer-less compose-mode transport

Third step of the workspace-shell time-model foundation (§1.7). Independent of A1/A2 — builds directly on main.

The problem

startPlayback() early-returned without S.audioBuffer:

if (!S.audioBuffer || !S.audioCtx) return;

So a from-scratch song (compose mode — no recording) had no clock, no metronome, no guide claps. You could place notes but not hear time move.

What A3 adds

A buffer-less transport. When there's no recording:

• The clock runs off the AudioContext, not a BufferSource. _anchorTransportAtCursor() pins playStartWall/playStartTime; playbackTick() advances cursorTime from the ctx clock exactly as before — just with no audio node.
• The grid bounds the song. S.duration = the time of the last grid beat via the A1 converter (timeOf(lastBeat)), extended if authored content runs past the last bar, or an explicit S.composeLength. No audio buffer needed to know how long the song is.
• The metronome/guide scheduler is the only sound. _guideTick was already ctx-time-based and gates on S.audioCtx (never S.audioBuffer), so it fires off the beat map with no changes.
• _ensureAudioCtx() creates the shared context on the play gesture, since compose mode never hits the decode path that used to be the only creation site.

_restartPlaybackAt() (loop wrap / seek) takes the same buffer-less branch. Audio-present playback is unchanged — buffered and buffer-less share one clock; a recording rides the clock, it isn't the source of time.

Incidental cleanup

The clock-advance formula playStartTime + (ctxNow − playStartWall) was copy-pasted at four sites (playbackTick, guide tick, guide-timer sync, chartTimeNow). A3 extracts it to one pure _transportChartTimePure and rewires all four — no behaviour change, less drift for the Logic-style ruler/LCD (B2/B3) to trip over later.

Tests

tests/compose_transport.test.js — 15 cases, all would-fail-on-main (every A3 symbol is absent on main):

• _transportChartTimePure — advance / stationary-at-anchor / monotonic
• _composeSongDurationPure — user length wins · max(grid, content) · junk → 0
• _composeSongDuration (live, real timeOf, no buffer) — grid-derived length · extends for late content · honours composeLength · degenerate grid → 0
• _anchorTransportAtCursor pins the anchor and creates no BufferSource
• playback advances cursorTime with audioBuffer = null (the core A3 claim)
• guide scheduler is buffer-independent — reset seeds the watermark from cursorTime; _guideTick gates on audioCtx, never audioBuffer

Verification

• node --check screen.js clean
• Full JS suite: 72 pass / 0 fail
• No routes.py change (no pytest); no wire/spec change

Ordering

Independent of A2 (#135) — both branch off main and can merge in any order. A4 (loop-as-beats) and A5 (beat-lock) require A2 merged; Phase B waits on the feature-PR backlog draining.

Design source: SONG-EDITOR-WORKSPACE-SHELL-CHARRETTE.md §1.7.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added buffer-less compose-mode transport playback (no recording loaded), including AudioContext-clock-based playhead movement.
  • Compose-mode playback now bounds song length to the grid while still including authored content/tail, with consistent guide/metronome output.

• Bug Fixes

  • Fixed compose-mode end-of-guide clap being cut short.
  • A/B compare now remains inactive when no reference audio is available.
  • Transport and guide timing are more resilient when seeking/restarting.

• Tests

  • Expanded automated coverage for compose-mode transport timing, duration selection, scheduling independence, and safe initialization when Web Audio is unavailable.
  • Updated A/B loop test setup to default to buffered behavior.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 93de2747-ac34-49b3-872a-3b7d717361f1

📥 Commits

Reviewing files that changed from the base of the PR and between 0951584 and ee29476.

📒 Files selected for processing (4)

• CHANGELOG.md
• screen.js
• tests/compose_transport.test.js
• tests/loop_ab.test.js

---

📝 Walkthrough

Walkthrough

This PR adds buffer-less compose-mode playback in screen.js, shared transport-time calculation, updated A/B gating for no-buffer playback, and matching tests plus changelog notes.

Changes

Compose-mode transport clock

Layer / File(s)	Summary
Playback start and anchoring screen.js	Adds lazy _ensureAudioCtx() for loadAudio, and implements compose-mode playback start/restart anchoring with duration derived from grid/content or explicit compose length.
Shared transport clock call sites screen.js, CHANGELOG.md, tests/loop_ab.test.js	Updates playbackTick, guide scheduling, the scheduled-until horizon, and chartTimeNow to use _transportChartTimePure, tightens _abActive for compose mode, and updates release notes plus loop A/B test setup.
Compose transport tests tests/compose_transport.test.js	Adds tests for transport-time math, compose duration rules, compose anchoring, scheduler independence from audioBuffer, A/B compose-mode behavior, and AudioContext creation fallback.

Estimated code review effort: 4 (Complex) | ~40 minutes

Possibly related PRs

• got-feedBack/feedBack-plugin-editor#90: Both PRs modify screen.js playback scheduling around the transport clock and guide scheduler resets.
• got-feedBack/feedBack-plugin-editor#91: Both PRs modify the shared guide/metronome scheduling logic in screen.js.
• got-feedBack/feedBack-plugin-editor#122: Both PRs affect _abActive() and A/B compare behavior based on whether an audio buffer exists.

🚥 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: buffer-less compose-mode transport for Phase A3.
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/editor-compose-transport

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@screen.js`:
- Around line 6864-6867: _ensureAudioCtx() currently instantiates the audio
context unconditionally, so it throws a TypeError when neither AudioContext nor
webkitAudioContext exists and breaks the no-op fallback in startPlayback. Update
_ensureAudioCtx() to detect unsupported Web Audio before constructing the
context, leave S.audioCtx unset when unavailable, and return null so callers
like startPlayback and loadAudio can safely bail out via their existing guard.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: d8a45bdc-0873-4670-8fae-53a690057259

📥 Commits

Reviewing files that changed from the base of the PR and between b367c23 and 96a0b84.

📒 Files selected for processing (3)

• CHANGELOG.md
• screen.js
• tests/compose_transport.test.js

[byrongamatos]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.