Multiplayer B: shared session — synchronized launches & song arrangement

[spacedevin]

Summary

Multiplayer model A (independent b2b decks) just shipped: each player drives their own session/song locally, and the co-DJ stream now reflects the armed/launched pattern (emitLivePlayback) rather than the edit rack, so a collaborator hears your launches on your deck lane and the crossfader blends them.

Model B is the next step: a shared session where launches and song position are synchronized across players — when the host (or a master lane) launches a pattern/scene, everyone follows one playhead. This is necessary for the session system to work "properly" in a true collaborative jam (not just two independent decks).

Why A is not enough

The live-performance layer is local runtime state (rt.*), never streamed as control state:

State	Where	Synced today
Song position (rt.songScene, songSceneEndTick)	runtime	❌
Launched pattern (rt.sessionArmedClipIds)	runtime	❌ (only the resulting audio/pattern streams via A)
Per-track overrides (rt.trackOverrides)	runtime	❌
Patterns / clips / session grid / scenes	project → TPL	✅ (master-gated, Merge.tish)

In A we stream the realized pattern (the notes), so the other side hears the result but doesn't share the intent — they can't follow your song, and there's no single shared arrangement/playhead. The song arrangement is also still implicit (saved scenes in grid order); there's no explicit, editable, portable arrangement.

Proposed architecture for B

1. Explicit song arrangement block in TPL — make the arrangement data, not derived:

   song
     P1 x2
     P2
     P3 x4
   

   Emit + parse + round-trip + tests. The song-chain in playbackTick reads this instead of deriving grid order. (Foundation: already discussed as a standalone improvement.)

2. Launch / transport control messages on the hub — a new message type alongside tpl.block:

   • launch.scene { sceneIdx, effectivePerfStep }
   • launch.clip { trackId, clipId, effectivePerfStep } (per-track override)
   • transport { play: "song"|"sequence"|"stop", songScene, effectivePerfStep }
     Gated by master rights (laneCanMaster in Merge.tish); per-track overrides scoped to the track owner.

3. Shared transport clock / playhead — a master broadcasts song position (scene + bar) on a quantized boundary so followers align; or an Ableton-Link-style beat clock. Receivers apply launches to the shared arming (sessionArmedClipIds / songScene) at the target perfStep, rather than only merging track bodies.

4. Authority & conflict model — who may launch (master vs per-lane ownership), how a follower's local launches reconcile with the master's, and how per-track overrides interact with ownership (actorMayEditTrack).

5. UI — indicate "following host" vs "free" per player; show the shared playhead; a follow/independent toggle so a player can break off into their own deck (back to model A behaviour) and rejoin.

Tasks

• song arrangement block: TPL emit/parse, playback reads it, round-trip tests
• Hub message types for launch.scene / launch.clip / transport (schema + gateway routing)
• Master-gated apply of launch/transport messages → shared sessionArmedClipIds / songScene at effectivePerfStep
• Shared playhead broadcast + follower alignment (quantized boundary or beat clock)
• Authority model (master launches; ownership-scoped per-track overrides)
• UI: following/independent state, shared playhead indicator, follow toggle
• Tests: two-actor sim — host launch propagates to follower at the right perfStep; follower override scoped to owned track; break-off/rejoin

Acceptance criteria

• Host launches P3 → all following players switch to P3 on the same bar.
• A player can take a per-track clip (their owned track) without desyncing the rest.
• A player can toggle "independent" (model A) and rejoin "follow" cleanly.
• Song arrangement is explicit in TPL and round-trips.

References

• A (done): emitLivePlayback (src/tpl/Emit.tish), broadcast wiring in src/ui/App.tish (coDjPushLive), tests in test/smoke.tish (mp A: checks).
• Multiplayer merge/ownership/master-gating: src/codj/Merge.tish.
• Session/song model: src/model/Session.tish (firstSongScene, nextSongScene, armSceneWithOverrides, trackOverrides).

[spacedevin]

Foundational milestone (prerequisite for everything below): host-authoritative state + snapshot-on-join

Surfaced while testing model A: there is currently no source-of-truth and no initial state replication.

• Each client boots its own loadDefaultDeckardProject() and only receives incremental tpl.block / tpl.line afterwards.
• The gateway's joined message ships replay: [] (always empty); it caches no state.
• The client's join handler (src/ui/CoDjPanel.tish) never applies a host snapshot — it keeps its local default.
• There is no host concept in the gateway; all conns are equal peers.

Consequence: a joining client always shows the default song; the host's arrangement is never pushed; the two decks never truly sync. This must be fixed before synchronized launches are meaningful — otherwise "host launches P3 → all follow" launches against divergent local projects.

Required

1. Host = source of truth. One actor per room is the host (first joiner carrying master_mixer, or an explicit host flag in join). Gateway tracks room.hostActorId.
2. State snapshot on join. Host emits a full-project snapshot (state.snapshot carrying full TPL) on connect + on significant change. Gateway caches the latest per room.
3. Deliver to new joiners. On a new join, the gateway sends the cached host snapshot to the joiner (via joined.replay or a follow-up state.snapshot).
4. Client clobber-and-apply. On snapshot, the client replaces its local project with the host's (discarding its default), then renders. Clients then contribute only to their own lane on top of the host's authoritative state.
5. Role model in UI. Client knows it is a follower; host owns master/session state.

Tasks

• gateway: room.hostActorId + cache latest host snapshot
• host: emit state.snapshot (full project TPL) on connect + on significant change
• gateway: deliver snapshot to new joiners (joined.replay or state.snapshot)
• client: apply snapshot, clobbering local default; mark follower role
• test: a late joiner ends up with the host's exact project, not the default song

This is Milestone 0 — the synchronized-launch / shared-playhead work in the issue body depends on it.

[spacedevin]

✅ Milestone 0 implemented

Host-authoritative state replication is in:

• Gateway (services/gateway/main.tish): room.hostActorId (first master_mixer joiner) + room.hostSnapshot cache. On a follower join it delivers the cached snapshot and sends request.snapshot to the host; on receiving state.snapshot it caches + fans out to existing followers. joined/presence now carry hostActorId.
• Host UI (src/ui/CoDjPanel.tish): sendStateSnapshot() (full emitProject TPL) on connect-as-host and on request.snapshot.
• Follower UI: applyHostSnapshot() clobbers the local default via loadProjectFromTpl + setProject (+ resyncAudio).

Verified (live gateway + worker + host browser + follower probes): host designated; snapshot cached (72 lines); a cold follower received the host's project at the host's distinctive bpm 140, not its own default; host responds to request.snapshot; no errors; smoke 84/84.

Ongoing edits after the initial clobber still flow via the model-A incremental stream (tpl.block/tpl.line); snapshots are for initial/late-join sync. Remaining (future): host reassignment on disconnect, and on-edit snapshot refresh for extra robustness.

• gateway: room.hostActorId + cache latest host snapshot
• host: emit state.snapshot on connect + on request
• gateway: deliver snapshot to new joiners + request fresh from host
• client: apply snapshot, clobbering local default
• (future) host reassignment on disconnect; on-edit snapshot refresh