App.tish

import { useState, useRef, useEffect, h, Fragment, memo } from '@tishlang/lattish'
import { projectToJson, projectFromJson } from '../model/Project.tish'
import { channelDeck, crossfadeValue, crossfadeValueY } from '../model/DeckRouting.tish'
import { freshSetEnergy, freshActiveDecks, foldSetEnergyStep } from '../model/SetEnergy.tish'
import { loadDefaultDeckardProject, loadProjectFromTpl } from '../model/ProjectLoad.tish'
import { loadUserInstrumentPresets } from '../model/InstrumentPresets.tish'
import { createStationPresets } from '../core/StationPresets.tish'
import { cancelTtsVocal } from '@spacedevin/deck-synths'
import { emitLevel, retargetTpl } from '../core/Levels.tish'
import { createSetLibrary, emitSet, loadSet, freeDecks, emitSetStream, parseSetStream, isStreamSet } from '../core/SetLibrary.tish'
import { loadDeckSet, deckSetCatalog } from '../model/DeckSets.tish'
import { levelPresetList, addLevelPreset, findLevelPreset, removeLevelPreset } from '../model/LevelPresets.tish'
import { PresetBar } from './PresetBar.tish'
import { promptName, alertModal } from './PromptModal.tish'
import { IkSelect } from './InstrumentKit.tish'
import { emitProject, emitLivePlayback } from '../deckfile/Emit.tish'
import { CodeDebugView } from './CodeDebugView.tish'
import { migrateProjectGenerators } from '../model/Migrate.tish'
import { ensureAudio, updateMixerFromProject, resyncAllChannelBuses, applyCueRouting, applyOutputDevices, setCueLevel, setCueSyncOffset, setMainAutoSync, ensureCueOutput, suspendDrawsAround, drawsSuspended, setDrawDisabled, triggerMasterFxEcho, triggerMasterFxFilter, playHitAt, applyChannelFilterAutomation } from '../audio/Engine.tish'
import { createAudioDeviceSettings } from '../core/AudioDeviceSettings.tish'
import { AudioRackPanel } from './AudioRackPanel.tish'
import { MidiPanel } from './MidiPanel.tish'
import { SongBrowser } from './SongBrowser.tish'
import { loadScratchBuffer, setScratchRate, setScratchVolume, setScratchDucking, scratchHasBuffer, setScratchPos, setScratchCut, scratchSpin } from '../audio/Engine.tish'
import { renderDeckLoopToBuffer } from '../audio/Playback.tish'
import { createMidiController } from '../midi/Midi.tish'
import { transportTick } from '../audio/Playback.tish'
import { generatorChannelAtBeat } from '../audio/ParamAtBeat.tish'
import { secondsPerStep } from '../audio/Scheduler.tish'
import { createIngest, bumpAllRev, ensureProjectRev } from '../core/Ingest.tish'
import { createEditor } from '../core/Edit.tish'
import { createSignals } from '../core/Signals.tish'
import { createTransport } from '../audio/Transport.tish'
import { tplLoopResetAll } from '../deckfile/LoopState.tish'
import { TransportBar } from './Transport.tish'
import { collectActorLanes, channelActorLane, ensureActorMixerEntries } from '../model/MixerRouting.tish'
import { InstrumentStack } from './InstrumentStack.tish'
import { CoDjPanel } from './CoDjPanel.tish'
import { launchSceneDirective, transportDirective, fxDirective, cueDirective, deckMoveDirective } from '../codj/Launch.tish'
import { coDjClockPayload, coDjShouldFollow, coDjClockAlign, coDjIsFollower, coDjOwnDeckLetter } from '../codj/Transport.tish'
import {
  PianoRollCanvas,
  PianoRollZoomBar,
  attachPianoRoll,
  drawRackPianoPreview,
  pianoRollVisualSig,
  rackPianoPreviewSig,
  updatePianoRollCtx
} from './PianoRoll.tish'
import { drawScopeCanvas, drawSpectrumCanvas, drawMiniWave, busPeakLevel, drawSetWaveLane, drawSetWaveOverlay } from './Scope.tish'
import { StepGridPanel, gridBarsForProject } from './grid/StepGrid.tish'
import { DeckMixer, applyDeckEq, ensureDeckEq, DeckJog, VinylRow, deckEntries, DeckChannelStrip } from './deck/DeckMixer.tish'
import { PatternBank } from './PatternBank.tish'
import { coDjInitWebMidi } from '../codj/MidiProfiles.tish'
import {
  coDjFlushScheduledForStep,
  coDjStepsPerBar,
  coDjStepsUntilBarBoundary,
  coDjEnsureSchedule
} from '../codj/Schedule.tish'
import { pruneStaleTracks, coDjTrackExpirySequences } from '../codj/Prune.tish'
import { createDeckardRuntime } from './DeckardRuntime.tish'
import { setChannelGain, setChannelPan, setChannelEq } from '../model/Edits.tish'
import {
  ensureProjectSession,
  sessionArmScene,
  sessionCommitQueued,
  sessionQueueScene,
  sceneSlotClipId,
  sessionPlayingSceneIndex,
  sessionWriteRackToSceneClip,
  sessionWriteRackBarToSceneClip,
  loadSceneIntoRack,
  loadSceneBarIntoRack,
  firstSongScene,
  nextSongScene,
  songStart,
  songAdvance,
  sceneBarLength,
  armSceneWithOverrides,
  mirrorStepToggleToMainClip,
  mirrorClearStepToMainClip,
  syncActiveClipsInstrumentsFromChannels
} from '../model/Session.tish'
import { SessionView } from './SessionView.tish'
import { PlaylistView } from './PlaylistView.tish'

// Memo'd channel rack (the heaviest panel). It re-renders only when the grid actually changes — gridGen
// (bar page / expand / step bumps), the selected channel, the project's channels-rev, or the promote UI.
// A crossfader move bumps NONE of those, so the rack memo-skips instead of re-rendering all the cells.
// memo() is created ONCE at module scope (in-render memo() would reset its cache every render).
fn stepGridEq(a, b) {
  return a.gridGen === b.gridGen && a.selectedCh === b.selectedCh && a.channelsRev === b.channelsRev && a.seqPromoteUi === b.seqPromoteUi && a.activeDeck === b.activeDeck
}
let StepGridMemo = memo((p) => StepGridPanel(p.project, p.selectedCh, p.setProjectFromUI, p.setSelectedCh, p.rt, p.headerRight, p.activeDeck), stepGridEq)

// Same scoping for the other PURE panels (no internal useState — CodeDebugView/CoDjPanel DO have internal
// hooks, so they are NOT memo'd: Lattish memo skips on equal props regardless of internal state, which
// would freeze their self-driven updates). areEqual compares only the scalar dep list; volatile props
// (freshly-built header vnodes, callbacks, the project ref) are intentionally ignored.
fn sessionEq(a, b) {
  return a.sessionUiGen === b.sessionUiGen && a.seqPromoteUi === b.seqPromoteUi && a.sessionRev === b.sessionRev && a.channelsRev === b.channelsRev && a.playing === b.playing && a.activeDeck === b.activeDeck
}
let SessionViewMemo = memo((p) => SessionView(p.project, p.rt, p.setProjectFromUI, p.playing, p.bumpSessionUi, p.patternBank, p.headerRight, p.activeDeck), sessionEq)

fn playlistEq(a, b) {
  return a.timelineGen === b.timelineGen && a.setLibGen === b.setLibGen && a.channelsRev === b.channelsRev
}

// A press in the left deck strip selects that deck — but NOT when it lands on a control (jog, faders, EQ knobs,
// vinyl/CUE buttons, crossfader, XY pad). Only presses on the deck's empty area / title row select it. Bound to
// mousedown (NOT click): at press time e.target is the exact element under the cursor, so a control is caught
// reliably. A knob/fader DRAG ends with mouseup off the control, which would synthesize a `click` on the deck
// container (target = deck div, not the knob) and slip past this gate — pressing is unambiguous, so we gate that.
fn deckBgClick(e, deck, setActiveDeck) {
  let t = e !== null ? e.target : null
  if ((t !== null) && (t.closest !== null) && t.closest("button, input, select, textarea, canvas, .dk-jog, .dk-xfade, .dk-xypad, [class*='knob'], [class*='lever'], [class*='fader']") !== null) {
    return
  }
  setActiveDeck(deck)
}
let PlaylistMemo = memo((p) => PlaylistView(p.project, p.rt, p.props), playlistEq)

fn instrumentEq(a, b) {
  return a.selectedCh === b.selectedCh && a.channelsRev === b.channelsRev && a.activeDeck === b.activeDeck
}
let InstrumentStackMemo = memo((p) => InstrumentStack(p.project, p.selectedCh, p.setProjectFromUI, p.tplMirrorFlush, p.rt, p.activeDeck), instrumentEq)

fn deckMixerEq(a, b) {
  let ap = a.project
  let bp = b.project
  let abpm = ap ? ap.bpm : 120
  let bbpm = bp ? bp.bpm : 120
  return a.xfadeX === b.xfadeX && a.xfadeY === b.xfadeY && a.channelsRev === b.channelsRev && a.deckMixRev === b.deckMixRev && a.playing === b.playing && abpm === bbpm
}
let DeckMixerMemo = memo((p) => DeckMixer(p.project, p.setProjectFromUI, p.touchMixer, p.rt), deckMixerEq)

let initialDeckardBoot = loadDefaultDeckardProject()
// Restore the user's saved instrument presets from localStorage (the factory ones come from the boot project).
loadUserInstrumentPresets(initialDeckardBoot.project)
if (initialDeckardBoot.errors.length > 0 && typeof console !== "undefined" && console.warn) {
  let ei = 0
  while (ei < initialDeckardBoot.errors.length) {
    console.warn("default deck L" + String(initialDeckardBoot.errors[ei].line) + ": " + initialDeckardBoot.errors[ei].msg)
    ei = ei + 1
  }
}

let audioStore = {}
// The lookahead scheduler + clock + draw loop now live in the Transport projection (src/audio/Transport.tish).
// Preview runs on its OWN clock, fully independent of the live (Sequence/Session) transport.
let previewTimer = null
let previewTick = 0
// rAF coalescing flag for the per-deck mixer (EQ knobs / deck volume) — those mutate project.deckEq in
// place and must NOT reconcile+re-render synchronously per mousemove (that saturates the main thread and
// starves the audio clock). One reconcile + one DeckMixer-only re-render per frame instead.
let deckMixPending = false

// --- OffscreenCanvas scope worker (Tier 1): the heaviest per-frame canvas drawing (master spectrum +
// per-stem waveforms) runs on a WORKER thread, so it never competes with the main thread (audio reconfig,
// DOM patching, Lattish render). The main thread only reads the analyser bytes + postMessages them. The
// meters/playhead stay on the main thread (DOM, can't go to a worker). Capability-gated; falls back to
// drawing on the main thread when OffscreenCanvas/Worker aren't available.
let scopeWorker = null
let scopeWorkerTried = false
let scopeTransferred = null

fn ensureScopeWorker() {
  if (scopeWorkerTried) {
    return scopeWorker
  }
  scopeWorkerTried = true
  if (typeof Worker === "undefined" || typeof OffscreenCanvas === "undefined" || typeof WeakSet === "undefined") {
    return null
  }
  if (typeof HTMLCanvasElement === "undefined" || !HTMLCanvasElement.prototype || typeof HTMLCanvasElement.prototype.transferControlToOffscreen !== "function") {
    return null
  }
  try {
    scopeWorker = new Worker("/scope-worker.js")
    scopeTransferred = new WeakSet()
  } catch (e) {
    scopeWorker = null
  }
  return scopeWorker
}

// Transfer a canvas's rendering to the worker ONCE (idempotent via the WeakSet). Lattish never re-applies the
// canvas's constant width/height/class props (it skips unchanged props), so the transferred canvas is never
// re-touched → no InvalidStateError. Returns true once the canvas is worker-owned.
fn scopeRegister(cv, id) {
  if (!scopeWorker || !cv) {
    return false
  }
  if (scopeTransferred.has(cv)) {
    return true
  }
  let dpr = (typeof window !== "undefined" && window.devicePixelRatio) ? window.devicePixelRatio : 1
  if (dpr > 2.5) {
    dpr = 2.5
  }
  let cssW = cv.offsetWidth
  let cssH = cv.offsetHeight
  if (cssW < 4) {
    cssW = cv.width > 0 ? cv.width : 64
  }
  if (cssH < 4) {
    cssH = cv.height > 0 ? cv.height : 34
  }
  let off = null
  try {
    off = cv.transferControlToOffscreen()
  } catch (e) {
    return false
  }
  scopeTransferred.add(cv)
  scopeWorker.postMessage({ type: "register", id: id, cssW: cssW, cssH: cssH, dpr: dpr, canvas: off }, [off])
  return true
}
// Per-stem scope colour = the channel's DECK colour (matches --deck-a/b/c/d), so a deck's waveforms read in
// its own hue instead of all cyan.
fn deckWaveColorHex(deck) {
  if (deck === "B") {
    return "#e879f9"
  }
  if (deck === "C") {
    return "#f59e0b"
  }
  if (deck === "D") {
    return "#4ade80"
  }
  return "#22d3ee"
}

fn renderDeckPips(project, deckLetter) {
  let active = []
  let i = 0
  while (i < 16) {
    active.push(false)
    i = i + 1
  }
  if (project && project.channels) {
    let j = 0
    let chs = project.channels
    let len = chs.length
    while (j < len) {
      let ch = chs[j]
      if (ch && channelDeck(project, ch) === deckLetter && ch.steps) {
        let si = 0
        let slen = ch.steps.length
        while (si < 16) {
          if (si < slen) {
            let s = ch.steps[si]
            if (s && s.on) {
              active[si] = true
            }
          }
          si = si + 1
        }
      }
      j = j + 1
    }
  }

  let pips = []
  let stepIdx = 0
  while (stepIdx < 16) {
    let on = active[stepIdx]
    pips.push(<span class={"deck-nav-indicator-sq" + (on ? " deck-nav-indicator-on" : "")}></span>)
    stepIdx = stepIdx + 1
  }
  return <div class="deck-nav-indicators">{pips}</div>
}

export fn App() {
  let [project, setProject] = useState(initialDeckardBoot.project)
  migrateProjectGenerators(project)
  let tplInit = emitProject(project)
  let [tplText, setTplText] = useState(tplInit)
  let [activeDeck, setActiveDeck] = useState("A")
  let [selectedCh, setSelectedCh] = useState(3)
  let [playing, setPlaying] = useState(false)
  let [previewing, setPreviewing] = useState(false)
  // The live transport's source — "sequence" (FL rack as the live song) or "song" (the session clips).
  // Sequence and Session share ONE clock; toggling between them while playing never restarts it.
  let [playMode, setPlayMode] = useState("song")
  let [sessionUiGen, setSessionUiGen] = useState(0)
  let [seqPromoteUi, setSeqPromoteUi] = useState(0)
  let [midiGen, setMidiGen] = useState(0)
  let midiRenderRaf = useRef(false)
  let [songBrowserOpen, setSongBrowserOpen] = useState(false)
  let [songQuery, setSongQuery] = useState("")
  let [scratchGen, setScratchGen] = useState(0)
  let [gridGen, setGridGen] = useState(0)
  let [deckMixRev, setDeckMixRev] = useState(0)

  // MUST use the functional updater (like bumpSeqPromoteUi/bumpGrid below): this is called from the
  // long-lived scheduleStep closure (created once per Play press), so `sessionUiGen` captured by value
  // is frozen at that render. The value form re-set the SAME number each launch commit → SessionViewMemo's
  // sessionUiGen dep never changed → the memo skipped the queued→playing repaint and the cell stayed
  // stuck orange/blinking instead of turning green. The functional form always increments the latest slot.
  fn bumpSessionUi() {
    setSessionUiGen((x) => x + 1)
  }

  fn touchMixer() {
    updateMixerFromProject(project, audioStore)
  }

  let rtRef = useRef(null)
  if (!rtRef.current) {
    rtRef.current = createDeckardRuntime()
  }
  let rt = rtRef.current
  rt.bumpSeqPromoteUi = () => {
    setSeqPromoteUi((x) => x + 1)
  }
  // Per-deck EQ/volume reconcile, rAF-coalesced + DeckMixer-scoped (deckMixRev only — NOT bumpAllRev, so the
  // step grid / session / instrument panels don't re-render on a deck fader move). Audio + the lever/knob
  // visual both land once per frame, however fast the user drags.
  rt.scheduleDeckMix = () => {
    if (deckMixPending) {
      return
    }
    deckMixPending = true
    requestAnimationFrame(() => {
      deckMixPending = false
      // Isolate the audio reconcile so a transitional-graph throw can't skip the booth-strip repaint.
      try {
        if (audioStore.ctx) {
          updateMixerFromProject(rtRef.current.project, audioStore)
        }
      } catch (eDm) {}
      setDeckMixRev((x) => x + 1)
    })
  }
  // The BROADCASTING deck-mix commit door: a local booth EQ/volume edit recomputes the per-channel eq, repaints
  // the strip (rAF-coalesced via scheduleDeckMix), AND rides the websocket through the same debounced gate as
  // every other edit (host → state.snapshot with deck_mix lines; follower → deck.put with its owned deck_mix).
  // The per-pixel drag stays smooth (scheduleDeckMix is rAF, coDjScheduleEditBroadcast is 200ms-debounced).
  rt.commitDeckMix = (deck) => {
    let p = rtRef.current && rtRef.current.project ? rtRef.current.project : project
    applyDeckEq(p, deck)
    rt.scheduleDeckMix()
    coDjScheduleEditBroadcast()
  }
  // Receiver hook: after adopting a snapshot / deck.put that carried deck_mix, recompute the per-channel eq for
  // ALL decks and repaint the booth strip (DeckMixerMemo keys on deckMixRev, NOT the bumpAllRev slice counters).
  rt.reconcileDeckMix = () => {
    let p = rtRef.current && rtRef.current.project ? rtRef.current.project : project
    let dd = ["A", "B", "C", "D"]
    let i = 0
    while (i < dd.length) {
      applyDeckEq(p, dd[i])
      i = i + 1
    }
    if (audioStore.ctx) {
      updateMixerFromProject(p, audioStore)
    }
    setDeckMixRev((x) => x + 1)
  }
  rt.bumpGrid = () => {
    setGridGen((x) => x + 1)
  }
  rt.touchMixer = touchMixer
  // Exposed so the Co-DJ panel can force a full re-render (bumpAllRev) when the connection state changes —
  // e.g. so the deck-routing lock visibly engages/releases on connect/disconnect.
  rt.setProjectFromUI = setProjectFromUI
  rt.mirrorStepToSessionClip = (ch, si) => {
    mirrorStepToggleToMainClip(ch, si)
  }
  rt.mirrorClearStepToSessionClip = (ch, si) => {
    mirrorClearStepToMainClip(ch, si)
  }
  rt.project = project
  // Per-slice rev counters (bumped in place at the ingest boundary / by setProjectFromUI) feed the memo'd
  // panels' areEqual so they re-render only when their slice changed.
  let pRev = ensureProjectRev(project)
  let channelsRev = pRev ? pRev.channels : 0
  let sessionRev = pRev ? pRev.session : 0
  let xfadeX = typeof project.transportCrossfade === "number" ? project.transportCrossfade : -1
  let xfadeY = typeof project.transportCrossfadeY === "number" ? project.transportCrossfadeY : -1
  rt.setProject = setProject
  rt.setTplText = setTplText
  rt.selectedCh = selectedCh
  rt.setSelectedCh = setSelectedCh
  rt.playing = playing
  rt.playMode = playMode
  // Launch quantize lives on the project (source of truth) so it round-trips in deck and syncs to every
  // player via the host snapshot / stream — same value, same UI everywhere. 16 steps = 1 bar default.
  let launchQuant = (project.launchQuant !== null) && Math.floor(Number(project.launchQuant)) >= 1
    ? Math.floor(Number(project.launchQuant))
    : 16
  rt.launchQuantSteps = launchQuant

  // ---- The ONE write door (rearch): ingest + editor. Every UI edit emits a deck fragment through here
  // instead of mutating `project` directly. Local, co-DJ, and agent all share this gated path. ----
  let storeRef = useRef(null)
  if (!storeRef.current) {
    storeRef.current = { project: project, runtime: rt }
  }
  storeRef.current.project = project
  // Local actor ctx: single-player = "human" (the default-project owner) with master rights; co-DJ
  // overrides coDjActorId / coDjLocalSkillIds when a session assigns a narrower role.
  fn localCtx() {
    let r = rtRef.current
    return {
      actorId: r.coDjActorId ? r.coDjActorId : "human",
      skillIds: r.coDjLocalSkillIds ? r.coDjLocalSkillIds : ["master_mixer"],
      perfStep: r.perfStep !== null ? r.perfStep : 0
    }
  }
  let ingestRef = useRef(null)
  if (!ingestRef.current) {
    ingestRef.current = createIngest(storeRef.current)
    // On stream-advance: reconcile audio (LIVE), re-render, mirror to the deck editor. A continuous control
    // (crossfader / faders) fires an emit on every mousemove pixel, so the re-render and the heavy
    // emitProject deck-serialize MUST be coalesced — otherwise each pixel re-renders the whole tree + rebuilds
    // the full project deck, which scales with channel count and lags hard once decks have content. The audio
    // reconcile stays per-emit (you must hear the move now); the render coalesces to one per frame, and the
    // deck mirror trails on a debounce (it's a reflection, not needed at interaction rate).
    let advancePending = false
    let tplMirrorTimer = null
    ingestRef.current.onAdvance((v) => {
      let r = rtRef.current
      if (!r.project) {
        return
      }
      // Coalesce the audio reconcile + re-render to one per animation frame: a 60fps crossfade is smooth and
      // a full-tree re-render per mousemove pixel is what lags. Per-emit work is now just scheduling.
      if (!advancePending) {
        advancePending = true
        requestAnimationFrame(() => {
          advancePending = false
          let rr = rtRef.current
          if (rr.project) {
            // The audio reconcile can throw on a transitional graph (analyser detached mid deck-load, a bus
            // mid-resync). It must NOT skip setProject — otherwise that edit never repaints and the UI looks
            // stuck. Isolate the reconcile so the re-render always lands.
            try {
              if (audioStore.ctx) {
                updateMixerFromProject(rr.project, audioStore)
              }
            } catch (eMix) {}
            setProject(rr.project)
          }
        })
      }
      // The deck-editor mirror (heavy emitProject serialize) trails on a debounce — a reflection, not needed
      // at interaction rate.
      if (tplMirrorTimer) {
        clearTimeout(tplMirrorTimer)
      }
      tplMirrorTimer = setTimeout(() => {
        let rr = rtRef.current
        if (rr.project) {
          syncProjectToTplEditor(rr.project)
        }
      }, 140)
      // Stream this LOCAL emit-path edit (knobs, steps, pattern, etc.) to peers, debounced + independent of
      // the transport. onAdvance fires ONLY for local edits (received peer edits apply through CoDjPanel, not
      // this ingest), so this never echoes. Without it a follower's knob/step edits never reach the host.
      coDjScheduleEditBroadcast()
    })
  }
  let editorRef = useRef(null)
  if (!editorRef.current) {
    editorRef.current = createEditor(storeRef.current, ingestRef.current.ingest, localCtx)
  }
  rt.emit = (addr, val) => editorRef.current.emit(addr, val)
  rt.directive = (line) => editorRef.current.directive(line)
  rt.directiveUndoable = (fwd, inv, addr) => editorRef.current.directiveUndoable(fwd, inv, addr)
  // Apply an arbitrary deck fragment (e.g. a preset's deck) through the one gated write door.
  rt.applyTpl = (tpl) => editorRef.current.directive(tpl)
  // Undo / redo: re-ingest the inverse / forward deck through the same gated door (ownership-checked,
  // broadcast, round-trip-safe). ingest re-renders via onAdvance, so the toolbar buttons refresh.
  rt.undo = () => editorRef.current.undo()
  rt.redo = () => editorRef.current.redo()
  rt.canUndo = () => editorRef.current.canUndo()
  rt.canRedo = () => editorRef.current.canRedo()

  // Let the co-DJ connect flow land a joining follower on its OWN deck (so it sees its own loop, not the
  // host's Deck A). Exposed here because setActiveDeck (useState) is only in scope in the App component.
  rt.setActiveDeck = (d) => {
    if (d === "A" || d === "B" || d === "C" || d === "D") {
      setActiveDeck(d)
    }
  }

  // Add a new channel: emit a bare `track` header on the ACTIVE deck (the ingest creates it via makeChannel
  // with an empty 16-step pattern), undoable (inverse = remove it), and select it.
  rt.onAddTrack = () => {
    let p = rtRef.current.project
    // Mint a doc-unique id (don't collide with existing channels — agents prefix theirs, the host uses c<N>).
    let n = p.channels.length
    let id = "c" + String(n)
    let conflict = true
    while (conflict) {
      conflict = false
      let i = 0
      while (i < p.channels.length) {
        if (p.channels[i].id === id) {
          conflict = true
        }
        i = i + 1
      }
      if (conflict) {
        n = n + 1
        id = "c" + String(n)
      }
    }
    // In a live session each player owns ONE deck; a new track must land on MY deck by OWNERSHIP — NOT on
    // whatever deck I happen to be viewing. activeDeck defaults to "A" and is never synced to a follower's
    // own deck, so authoring `deck A slot 0` here pinned every guest's first instrument onto the host's
    // Deck A (channelPlayerIndex reads deckSlot before ownership). Omitting the deck line lets ownership
    // (the local actor stamped on ingest) route it to my own deck. Solo keeps the activeDeck placement.
    let pl = p.coDjPlayers
    let inSession = Array.isArray(pl) && pl.length > 1
    // In a live session a FOLLOWER's new track needs a globally-unique, owned id — a bare c<N> would collide
    // with the host's c<N> (and any other client's) and be owner-denied on the host, so the added instrument
    // would never sync. Prefix it with my actorId. The host keeps c<N> (it owns Deck A, the canonical ids).
    let amHostNow = rtRef.current && rtRef.current.coDjIsHost === true
    let aidNow = rtRef.current && rtRef.current.coDjActorId ? String(rtRef.current.coDjActorId) : ""
    if (inSession && !amHostNow && aidNow.length > 0) {
      id = aidNow + "_" + id
    }
    let slot = activeDeck === "B" ? 1 : (activeDeck === "C" ? 2 : (activeDeck === "D" ? 3 : 0))
    let fwd = inSession
      ? ("track Track id " + id + " gen basic_osc")
      : ("track Track id " + id + " gen basic_osc\n  deck " + activeDeck + " slot " + String(slot))
    rt.directiveUndoable(fwd, "remove_track " + id, "track/" + id + "/add")
    setSelectedCh(rtRef.current.project.channels.length - 1)
  }
  // Delete a channel: capture its full deck as the undo inverse BEFORE removing (so undo recreates exactly it,
  // not a project snapshot), emit `remove_track`, then rebuild the index-keyed audio buses (a splice misaligns
  // them) and clamp the selection if it ran off the end.
  rt.onDeleteTrack = (chId) => {
    let p = rtRef.current.project
    let inv = emitLevel(p, "channel", chId)
    rt.directiveUndoable("remove_track " + chId, inv, "track/" + chId + "/del")
    let p2 = rtRef.current.project
    if (audioStore.ctx) {
      resyncAllChannelBuses(p2, audioStore)
      updateMixerFromProject(p2, audioStore)
    }
    if (typeof rt.selectedCh === "number" && rt.selectedCh >= p2.channels.length) {
      setSelectedCh(p2.channels.length > 0 ? p2.channels.length - 1 : 0)
    }
  }

  // ---- MIDI: keyboard notes audition the SELECTED instrument; a learned CC drives a control via emit (the
  // same gated/broadcast/round-tripping deck a UI drag emits → multiplayer-native).
  // A MIDI note-on plays the selected channel's voice live (a monitor).
  fn midiNote(note, vel) {
    ensureAudio(project, audioStore)
    let ctx = audioStore.ctx
    if (!ctx || !audioStore.buses) {
      return
    }
    let sc = typeof rt.selectedCh === "number" ? Math.floor(rt.selectedCh) : 0
    let bus = audioStore.buses[sc]
    let ch = project.channels[sc]
    if (!bus || !ch) {
      return
    }
    let gch = generatorChannelAtBeat(project, ch, 0)
    playHitAt(ctx, bus, ctx.currentTime + 0.005, note, vel, 0.5, gch, 0, null)
  }
  // A mapped CC (value 0..1) → resolve its target. Keep these ids in sync with midiTargetList. EVERY target
  // drives a control that is VISIBLE on screen and moves with the hardware (the rule: nothing audible-but-invisible).
  fn midiControl(targetId, v01) {
    let ed = editorRef.current
    if (!ed) {
      return
    }
    let p = rtRef.current.project
    // `scoped` targets repaint themselves (deck booth knobs via scheduleDeckMix → deckMixRev) or need no React
    // paint at all (scratch = audio + a canvas jog), so they skip the broad bumpAllRev re-render below.
    let scoped = false
    if (targetId === "bpm") {
      ed.emit("bpm", Math.round(40 + v01 * 200))
    } else if (targetId === "scratch") {
      // A centered pitch fader / spring knob scrubs DECK A's scratch: 0.5 = stop, ends = ±max reverse/forward.
      // (A controller scrubs one platter — deck A by convention; the on-screen jogs cover the rest.)
      if (rt.scratchRate) {
        rt.scratchRate("A", (v01 - 0.5) * 16)
      }
      scoped = true
    } else if (targetId === "master_lo") {
      ed.emit("master/eq_lo", Math.round((-12 + v01 * 24) * 10) / 10)
    } else if (targetId === "master_mid") {
      ed.emit("master/eq_mid", Math.round((-12 + v01 * 24) * 10) / 10)
    } else if (targetId === "master_hi") {
      ed.emit("master/eq_hi", Math.round((-12 + v01 * 24) * 10) / 10)
    } else if (targetId === "xfade_x") {
      ed.emit("xfade", [v01, p.transportCrossfadeY !== null ? p.transportCrossfadeY : 0])
    } else if (targetId === "xfade_y") {
      ed.emit("xfade", [p.transportCrossfade !== null ? p.transportCrossfade : 0.5, v01])
    } else if (String(targetId).indexOf("deck:") === 0) {
      // deck:<X>:<band> — the per-deck booth HI/MID/LO/FILTER knobs + volume fader. Drive them through the EXACT
      // path the on-screen knobs use (mutate deckEq → applyDeckEq → scheduleDeckMix), so the visible knob tracks
      // the hardware (deckMixRev re-renders just that strip) and the audio reconciles once per frame.
      let parts = String(targetId).split(":")
      let dk = parts[1]
      let band = parts[2]
      ensureDeckEq(p)
      let de = p.deckEq[dk]
      if (de !== null) {
        if (band === "vol") {
          de.vol = Math.round(v01 * 1000) / 1000
        } else if (band === "flt") {
          de.flt = Math.round((-1 + v01 * 2) / 0.02) * 0.02
        } else {
          // hi / mid / lo — ±12 dB, integer detents (matches the knob's step)
          de[band] = Math.round(-12 + v01 * 24)
        }
        applyDeckEq(p, dk)
        if (rt.scheduleDeckMix) {
          rt.scheduleDeckMix()
        }
      }
      scoped = true
    } else if (String(targetId).indexOf("track:") === 0) {
      ed.emit("track/" + String(targetId).substring(6) + "/mix/gain", Math.round(v01 * 1000) / 1000)
    }
    // The remaining emits go through the gated door (which bumps slice revs) but never call a React setter, so the
    // UI knob/fader never followed the hardware. Coalesce a re-render to once per frame so it tracks the move.
    if (!scoped && !midiRenderRaf.current) {
      midiRenderRaf.current = true
      requestAnimationFrame(() => {
        midiRenderRaf.current = false
        let pr = rtRef.current.project
        if (pr) { bumpAllRev(pr) }
        setMidiGen((x) => x + 1)
      })
    }
  }
  let midiRef = useRef(null)
  if (!midiRef.current) {
    midiRef.current = createMidiController({
      onNote: (note, vel) => midiNote(note, vel),
      onControl: (targetId, v01) => midiControl(targetId, v01),
      onChange: () => setMidiGen((x) => x + 1)
    })
  }
  rt.midi = midiRef.current
  // Set presets: named, saveable copies of the WHOLE workspace (the one level a global load fits — it
  // replaces everything, no target). Built-in "Default" is always present (loading it resets the set).
  let setPresetsRef = useRef(null)
  if (!setPresetsRef.current) {
    setPresetsRef.current = createStationPresets()
  }
  let setPresets = setPresetsRef.current
  let [setListGen, setSetListGen] = useState(0)

  // Set library: TIME-aware, per-player bundles (the new "Set"). Loading one fills the free deck slots
  // with its players (ghosts you can jam alongside) and restores its `song` arrangement; you can also drop
  // one onto a single deck from the deck picker. Seeded from the deck-set catalog so it's never empty.
  let setLibraryRef = useRef(null)
  if (!setLibraryRef.current) {
    setLibraryRef.current = createSetLibrary()
  }
  let setLibrary = setLibraryRef.current
  let [setLibGen, setSetLibGen] = useState(0)

  // I/O Rack: persisted speaker/headphone output device choice. Cue state (which decks → headphones) is on
  // rt.cuedDecks; share the same object with the audio store so updateMixerFromProject can reconcile it.
  let audioDevicesRef = useRef(null)
  if (!audioDevicesRef.current) {
    audioDevicesRef.current = createAudioDeviceSettings()
  }
  let audioDevices = audioDevicesRef.current
  audioStore.cuedDecks = rt.cuedDecks
  let [cueGen, setCueGen] = useState(0)

  // ---- Transport/Clock projection + signal bus (rearch step 4). The scheduler publishes step position
  // and health on `signals`; the playhead / grid / BPM readout SUBSCRIBE here (decoupled from timing). ----
  let signalsRef = useRef(null)
  if (!signalsRef.current) {
    signalsRef.current = createSignals()
  }
  let signals = signalsRef.current
  let transportRef = useRef(null)
  if (!transportRef.current) {
    transportRef.current = createTransport(audioStore, signals)
    signals.subscribe("transport.position", (step) => {
      let r = rtRef.current
      if (step < 0) {
        if (r.setPlaybackHighlight) {
          r.setPlaybackHighlight(0, false)
        }
        if (r.updateGridPlayhead) {
          r.updateGridPlayhead(0, false)
        }
        if (r.updateTimelinePlayhead) {
          r.updateTimelinePlayhead(0, false)
        }
        return
      }
      // Honour the draw gate (user-disabled, or an audio-source-switch quiet window): the playhead is a
      // draw call too. The rAF/position stream keeps running, so it resumes the moment the gate clears.
      if (drawsSuspended(audioStore)) {
        return
      }
      if (r.setPlaybackHighlight) {
        r.setPlaybackHighlight(step % 16, true)
      }
      if (r.updateGridPlayhead) {
        r.updateGridPlayhead(step, true)
      }
      if (r.updateTimelinePlayhead) {
        // The Set Recorder is a TAKE-relative timeline (waveform x = step since the take's origin), so the
        // playhead + auto-scroll use the same relative coordinate. tplViewOrigin = the global step at the
        // recorder's 0 marker (the take start, or 0 during replay; re-zeroed by New).
        let origin = r.tplViewOrigin !== null ? Math.floor(r.tplViewOrigin) : 0
        let prel = step - origin
        if (prel < 0) {
          prel = 0
        }
        r.updateTimelinePlayhead(prel, true)
      }
    })
    signals.subscribe("transport.health", (hh) => {
      let r = rtRef.current
      if (r.setBpmReadout) {
        r.setBpmReadout(hh.target, hh.trueBpm, hh.marginMs, hh.underruns)
      }
    })
  }
  let transport = transportRef.current

  fn setLaunchQuant(q) {
    let v = Math.floor(Number(q))
    if (v < 1 || v !== v) {
      v = 16
    }
    rt.emit("launch_quant", v)
  }

  // Transport hotkeys: Space = Play/Stop Sequence (monitor the rack), Enter = Play/Stop Song (live
  // arrangement). Ignored while typing in an input / textarea / contenteditable.
  useEffect(() => {
    if (typeof window === "undefined") {
      return () => {}
    }
    fn onKey(e) {
      let r = rtRef.current
      if (!r) {
        return
      }
      // Escape closes any open overlay/modal — the patch/gen editor first, then a sequencer grid overlay
      // (piano / locks / EUCLID), then the song browser. Handled BEFORE the typing-field guard so it works
      // from a focused field inside a modal. An open IkSelect dropdown stops Escape from reaching here (it
      // closes itself first), so this only fires for actual modals.
      if (e.key === "Escape") {
        if (r.genModal !== null) {
          r.genModal = null
          if (r.setProjectFromUI) { r.setProjectFromUI(r.project) }
          if (e.preventDefault) { e.preventDefault() }
          return
        }
        let anyOverlay = false
        let ovMaps = [r.gridExpanded, r.gridLocks, r.gridPianoLocks, r.gridAuto, r.gridEuclid, r.gridLyrics]
        let omi = 0
        while (omi < ovMaps.length) {
          let m = ovMaps[omi]
          if (m !== null && Object.keys(m).length > 0) {
            anyOverlay = true
          }
          omi = omi + 1
        }
        if (anyOverlay) {
          r.gridExpanded = {}
          r.gridLocks = {}
          r.gridPianoLocks = {}
          r.gridAuto = {}
          r.gridEuclid = {}
          r.gridLyrics = {}
          if (r.bumpGrid) { r.bumpGrid() }
          if (e.preventDefault) { e.preventDefault() }
          return
        }
        setSongBrowserOpen(false)
        return
      }
      let tgt = e.target
      let tag = tgt && tgt.tagName ? String(tgt.tagName).toLowerCase() : ""
      if (tag === "input" || tag === "textarea" || tag === "select" || (tgt && tgt.isContentEditable)) {
        return
      }
      // Undo / redo first (they own the Cmd/Ctrl+Z chord). Cmd/Ctrl+Z = undo, +Shift (or Cmd/Ctrl+Y) = redo.
      if ((e.metaKey || e.ctrlKey) && (e.key === "z" || e.key === "Z" || e.key === "y" || e.key === "Y")) {
        e.preventDefault()
        let isRedo = (e.key === "y" || e.key === "Y") || ((e.key === "z" || e.key === "Z") && e.shiftKey)
        if (isRedo) {
          if (r.redo) { r.redo() }
        } else {
          if (r.undo) { r.undo() }
        }
        return
      }
      // A plain modifier+key chord that we don't handle (e.g. Cmd+C copy) — let the browser have it.
      if (e.metaKey || e.ctrlKey || e.altKey) {
        return
      }
      if (e.code === "Space" || e.key === " ") {
        // Space = Preview: audition the rack on its own clock (separate from the live transport).
        e.preventDefault()
        if (r.onPreview) {
          r.onPreview()
        }
      } else if (e.key === "Enter") {
        // Enter = live Play / Stop (in the current Sequence/Session mode).
        e.preventDefault()
        if (r.onPlayStop) {
          r.onPlayStop()
        }
      } else if (e.key === "e" || e.key === "E") {
        // Hold E = ECHO FX throw: engage on the first keydown (ignore auto-repeat), release on keyup.
        if (!e.repeat && r.onFxThrow) {
          r.onFxThrow("echo", true)
        }
      } else if (e.key === "f" || e.key === "F") {
        // Hold F = FILTER FX throw (master lowpass sweep).
        if (!e.repeat && r.onFxThrow) {
          r.onFxThrow("filter", true)
        }
      } else if (e.key === "c" || e.key === "C") {
        // C = cue / un-cue the active scene on the private preview (launch a scene to take it live).
        if (!e.repeat && r.onCueActive) {
          r.onCueActive()
        }
      } else if (e.key === "v" || e.key === "V") {
        // Hold V = CUT the actively-jogged deck — the two-handed transformer/chirp: jog with the mouse, cut
        // with V. Targets r.activeScratchDeck (set when you grab a jog / vinyl move). Routes through the
        // `@ deck` directive so the cut broadcasts to peers, same as the buttons.
        if (!e.repeat && r.onDeckMove && r.activeScratchDeck) {
          r.onDeckMove(r.activeScratchDeck, "cut", true)
        }
      }
    }
    fn onKeyUp(e) {
      let r = rtRef.current
      if (!r) {
        return
      }
      let tgt = e.target
      let tag = tgt && tgt.tagName ? String(tgt.tagName).toLowerCase() : ""
      if (tag === "input" || tag === "textarea" || tag === "select" || (tgt && tgt.isContentEditable)) {
        return
      }
      if ((e.key === "e" || e.key === "E") && r.onFxThrow) {
        r.onFxThrow("echo", false)
      } else if ((e.key === "f" || e.key === "F") && r.onFxThrow) {
        r.onFxThrow("filter", false)
      } else if ((e.key === "v" || e.key === "V") && r.scratchCut && r.activeScratchDeck) {
        r.scratchCut(r.activeScratchDeck, false)
      }
    }
    // Suppress the browser's native right-click menu everywhere EXCEPT text fields (right-click is a real
    // editing gesture here — clear a step, delete a note — so the OS menu just gets in the way). Text
    // inputs/textarea/contenteditable keep their native menu so the deck editor still has copy/paste.
    fn onCtx(e) {
      let tgt = e.target
      let tag = tgt && tgt.tagName ? String(tgt.tagName).toLowerCase() : ""
      if (tag === "input" || tag === "textarea" || tag === "select" || (tgt && tgt.isContentEditable)) {
        return
      }
      if (e.preventDefault) {
        e.preventDefault()
      }
    }
    window.addEventListener("keydown", onKey)
    window.addEventListener("keyup", onKeyUp)
    window.addEventListener("contextmenu", onCtx)

    let lastTime = 0
    let spinRafId = 0
    fn jogSpinFrame(timestamp) {
      if (typeof document === "undefined") {
        return
      }
      if (lastTime === 0) {
        lastTime = timestamp
      }
      let dt = (timestamp - lastTime) / 1000
      lastTime = timestamp
      if (dt > 0.1) {
        dt = 0.1
      }

      let markers = document.querySelectorAll(".dk-jog-marker")
      let i = 0
      while (i < markers.length) {
        let mk = markers[i]
        let deck = null
        if (mk) {
          if (mk.classList.contains("dk-marker-A")) { deck = "A" }
          else if (mk.classList.contains("dk-marker-B")) { deck = "B" }
          else if (mk.classList.contains("dk-marker-C")) { deck = "C" }
          else if (mk.classList.contains("dk-marker-D")) { deck = "D" }
        }
        let r = rtRef.current
        if (mk && deck && r) {
          if (!r.deckRot) {
            r.deckRot = { A: 0, B: 0, C: 0, D: 0 }
          }
          if (!r.deckBrakeTime) {
            r.deckBrakeTime = { A: 0, B: 0, C: 0, D: 0 }
          }
          if (!r.deckSpinTime) {
            r.deckSpinTime = { A: 0, B: 0, C: 0, D: 0 }
          }

          let grabbed = false
          let activeMove = ""
          if (r.scratchHold && r.scratchHold[deck]) {
            let keys = Object.keys(r.scratchHold[deck])
            if (keys.length > 0) {
              grabbed = true
              if (keys.indexOf("jog") >= 0) {
                activeMove = "jog"
              } else if (keys.indexOf("spin") >= 0) {
                activeMove = "spin"
              } else if (keys.indexOf("brake") >= 0) {
                activeMove = "brake"
              } else if (keys.indexOf("rev") >= 0) {
                activeMove = "rev"
              }
            }
          }

          if (activeMove !== "jog") {
            let rate = 0
            if (activeMove === "rev") {
              rate = -1
            } else if (activeMove === "brake") {
              r.deckBrakeTime[deck] = r.deckBrakeTime[deck] + dt
              let progress = r.deckBrakeTime[deck] / 0.5
              if (progress > 1) {
                progress = 1
              }
              rate = 1 - progress
            } else if (activeMove === "spin") {
              r.deckSpinTime[deck] = r.deckSpinTime[deck] + dt
              let progress = r.deckSpinTime[deck] / 0.35
              if (progress > 1) {
                progress = 1
              }
              rate = -10 * (1 - progress)
            } else {
              r.deckBrakeTime[deck] = 0
              r.deckSpinTime[deck] = 0
              if (r.playing) {
                rate = 1
              }
            }

            let bpm = r.project && typeof r.project.bpm === "number" ? r.project.bpm : 120
            let revsPerSecond = bpm / 60 / 4
            let dAngle = rate * revsPerSecond * 2 * Math.PI * dt
            r.deckRot[deck] = r.deckRot[deck] + dAngle

            mk.style.transform = "translateX(-50%) rotate(" + String(r.deckRot[deck]) + "rad)"
          }
        }
        i = i + 1
      }
      spinRafId = requestAnimationFrame(jogSpinFrame)
    }
    spinRafId = requestAnimationFrame(jogSpinFrame)

    return () => {
      window.removeEventListener("keydown", onKey)
      window.removeEventListener("keyup", onKeyUp)
      window.removeEventListener("contextmenu", onCtx)
      if (spinRafId) {
        cancelAnimationFrame(spinRafId)
      }
    }
  }, [])

  rt.ensureStreamSeeded = () => {
    if (!rt.coDjWs || rt.coDjWs.readyState !== 1 || !Array.isArray(rt.tplSessionStream) || rt.tplSessionStream.length > 0) {
      return
    }
    let cur = ""
    if (rt.getSongText) {
      cur = rt.getSongText()
    }
    if (!cur || cur.trim().length === 0) {
      return
    }
    let lineArr = cur.split("\n")
    let step = typeof rt.perfStep === "number" ? rt.perfStep : 0
    rt.tplSessionStream.push({ lines: lineArr, effectivePerfStep: step })
  }
  rt.appendStreamedBlock = (lineArray, effectivePerfStep) => {
    if (!lineArray || lineArray.length === 0) {
      return
    }
    rt.tplLastAppliedLineCount = lineArray.length
    rt.tplLastAppliedAt = typeof Date !== "undefined" && Date.now ? Date.now() : 0
    let step = effectivePerfStep
    if (step === null) {
      step = typeof rt.perfStep === "number" ? rt.perfStep : 0
    }
    let streamMode = rt.coDjWs && rt.coDjWs.readyState === 1 && Array.isArray(rt.tplSessionStream)
    if (streamMode) {
      if (!rt.tplSessionStream) {
        rt.tplSessionStream = []
      }
      if (rt.ensureStreamSeeded) {
        rt.ensureStreamSeeded()
      }
      rt.tplSessionStream.push({ lines: lineArray, effectivePerfStep: step })
      let parts = []
      let pi = 0
      while (pi < rt.tplSessionStream.length) {
        parts.push(rt.tplSessionStream[pi].lines.join("\n"))
        pi = pi + 1
      }
      let next = parts.join("\n\n") + "\n"
      setTplText(next)
      if (rt.setSongText) {
        rt.setSongText(next)
      }
    } else {
      setTplText((prev) => {
        let s = prev.trimEnd()
        let sep = s.length > 0 && !s.endsWith("\n") ? "\n\n" : "\n"
        let next = s + sep + lineArray.join("\n") + "\n"
        if (rt.setSongText) {
          rt.setSongText(next)
        }
        return next
      })
    }
  }
  rt.consumePlayedBlocks = (perfStep) => {
    if (!rt.coDjWs || rt.coDjWs.readyState !== 1 || !Array.isArray(rt.tplSessionStream)) {
      return
    }
    let seq = 64
    let arr = rt.tplSessionStream
    let keep = []
    let j = 0
    while (j < arr.length) {
      if (arr[j].effectivePerfStep + seq > perfStep) {
        keep.push(arr[j])
      }
      j = j + 1
    }
    rt.tplSessionStream = keep
    if (keep.length === 0) {
      return
    }
    let parts = []
    let pi = 0
    while (pi < keep.length) {
      parts.push(keep[pi].lines.join("\n"))
      pi = pi + 1
    }
    let next = parts.join("\n\n") + "\n"
    setTplText(next)
    if (rt.setSongText) {
      rt.setSongText(next)
    }
  }

  fn tplMirrorFlush() {
    try {
      let r = rtRef.current
      let p = r.project
      if (!p) {
        return
      }
      let e = emitProject(p)
      setTplText(e)
      setTimeout(() => {
        try {
          let r2 = rtRef.current
          let p2 = r2.project
          if (!p2) {
            return
          }
          let e2 = emitProject(p2)
          if (r2.setSongText) {
            r2.setSongText(e2)
          }
          setTplText(e2)
        } catch (err2) {
          if (typeof console !== "undefined" && console.warn) {
            console.warn("tplMirrorFlush (deferred)", err2)
          }
        }
      }, 0)
    } catch (err) {
      if (typeof console !== "undefined" && console.warn) {
        console.warn("tplMirrorFlush", err)
      }
    }
  }

  fn syncProjectToTplEditor(p) {
    try {
      let e = emitProject(p)
      setTplText(e)
      let r = rtRef.current
      if (r.setSongText) {
        r.setSongText(e)
      }
      r.tplLastHighlightSource = null
    } catch (err) {
      if (typeof console !== "undefined" && console.warn) {
        console.warn("syncProjectToTplEditor", err)
      }
    }
  }

  // Stream a LOCAL edit to peers over the live deck stream, debounced, INDEPENDENT of the transport. The old
  // path only streamed during playback (coDjPushLive) — so once followers became host-only-transport they
  // could never reach the host while stopped, and their content silently never synced. This is the fix:
  // every local commit pushes to the hub (host → snapshot; follower → its own lines, host applies the tracks
  // it owns). Received peer edits commit via setProject (NOT setProjectFromUI), so this never echoes them.
  fn coDjScheduleEditBroadcast() {
    let r = rtRef.current
    if (!(r && r.coDjWs && r.coDjWs.readyState === 1 && r.coDjBroadcastNow)) {
      return
    }
    if (r.coDjEditBroadcastTimer) {
      clearTimeout(r.coDjEditBroadcastTimer)
    }
    r.coDjEditBroadcastTimer = setTimeout(() => {
      let rr = rtRef.current
      if (rr) {
        rr.coDjEditBroadcastTimer = null
      }
      if (rr && rr.coDjWs && rr.coDjWs.readyState === 1 && rr.coDjBroadcastNow) {
        rr.coDjBroadcastNow()
      }
    }, 200)
  }

  fn setProjectFromUI(p) {
    syncActiveClipsInstrumentsFromChannels(p, rtRef.current)
    // Legacy direct-mutation commit: it mutated `p` in place without declaring what changed, so bump ALL
    // slice revs to invalidate every memo'd panel (full re-render, as before). Migrated emit-path edits get
    // precise per-slice bumps at the ingest boundary instead.
    bumpAllRev(p)
    setProject(p)
    if (audioStore.ctx) {
      updateMixerFromProject(p, audioStore)
    }
    setTimeout(() => {
      let r = rtRef.current
      let proj = r.project
      if (proj) {
        syncProjectToTplEditor(proj)
      }
    }, 0)
    coDjScheduleEditBroadcast()
  }

  // Per-deck CUE toggle: send a deck to the headphones bus (or stop). Pure monitor state on rt.cuedDecks
  // (shared with audioStore); reconciles the live cue sends immediately.
  rt.onCueToggle = (deck) => {
    if (!rt.cuedDecks) {
      rt.cuedDecks = { A: false, B: false, C: false, D: false }
    }
    rt.cuedDecks[deck] = !rt.cuedDecks[deck]
    audioStore.cuedDecks = rt.cuedDecks
    // Light the CUE button NOW: the centre strip is memoized on deckMixRev (its `cued` prop), NOT cueGen, so
    // the toggle must bump deckMixRev or the button looks unchanged until some other edit re-renders the deck.
    setDeckMixRev((x) => x + 1)
    if (audioStore.ctx) {
      // Optionally do the cue routing inside a draw-quiet window (the "CUE PAUSE" toggle). Off by default now
      // that the scopes render off-thread (GPU/worker), so cueing no longer freezes the visuals.
      if (audioDevices.get().cuePauseDraws === true) {
        suspendDrawsAround(audioStore, () => {
          applyCueRouting(rtRef.current.project, audioStore)
        })
      } else {
        applyCueRouting(rtRef.current.project, audioStore)
      }
    }
  }
  // Pin the live audio sinks to the saved speaker/headphone devices + cue level. Called right after audio
  // starts (the dual-output <audio> els exist only after ensureAudio).
  fn applyIoRack() {
    let io = audioDevices.get()
    setDrawDisabled(audioStore, io.drawOff)
    setMainAutoSync(audioStore, io.autoSync)
    applyOutputDevices(audioStore, io.speakers, io.headphones)
    // Pre-warm the cue (headphone) output at audio init so the speakers + headphones sinks are both
    // established up front — live cue toggles are then just a gain flip, never a setSinkId/path-build
    // mid-playback (which is what glitched the sync).
    if (audioStore.canDualOut) {
      ensureCueOutput(audioStore)
    }
    setCueLevel(audioStore, io.cueLevel)
    setCueSyncOffset(audioStore, io.cueOffsetMs)
    // Re-sync cue sends here (on play), not in the per-emit mixer hot path — covers decks cued while stopped.
    audioStore.cuedDecks = rt.cuedDecks
    applyCueRouting(project, audioStore)
  }
  setTimeout(() => {
    coDjInitWebMidi(project, setProject, rtRef.current)
  }, 100)
  setTimeout(() => {
    let r = rtRef.current
    let pr = document.querySelector(".piano-roll")
    if (pr) {
      let sig = pianoRollVisualSig(project, selectedCh)
      if (r.prSkipRedrawSig !== sig || r.prSkipRedrawEl !== pr) {
        r.prSkipRedrawSig = sig
        r.prSkipRedrawEl = pr
        attachPianoRoll(pr, project, selectedCh, setProjectFromUI)
      } else {
        updatePianoRollCtx(pr, project, selectedCh, setProjectFromUI)
      }
    }
    if (!r.rackPrSigCache) {
      r.rackPrSigCache = []
    }
    if (!r.rackPrNode) {
      r.rackPrNode = []
    }
    let rpi = 0
    while (rpi < project.channels.length) {
      let rackCv = document.getElementById("rack-pr-" + String(rpi))
      if (rackCv) {
        let rsig = rackPianoPreviewSig(project.channels[rpi])
        if (r.rackPrSigCache[rpi] !== rsig || r.rackPrNode[rpi] !== rackCv) {
          r.rackPrSigCache[rpi] = rsig
          r.rackPrNode[rpi] = rackCv
          drawRackPianoPreview(rackCv, project.channels[rpi])
        }
      }
      rpi = rpi + 1
    }
  }, 0)

  if (!rt.dawScopeStarted) {
    rt.dawScopeStarted = true
    let scopeTick = 0
    fn scopeFrame() {
      // The scope/spectrum/meter drawing is purely visual and the heaviest per-frame main-thread work
      // (5+ canvases, O(fftSize) each). Throttle it to ~30fps so it doesn't compete with audio scheduling
      // + interaction — 30fps meters/waves are indistinguishable from 60. The playhead is on a separate
      // (un-throttled) Transport draw loop, so timing visuals stay crisp.
      scopeTick = scopeTick + 1
      // Skip drawing when the user disabled draws OR we're inside an audio-source-switch quiet window, and
      // throttle the rest to ~30fps. The UNCONDITIONAL re-arm at the very bottom keeps the loop spinning, so
      // it resumes the instant the gate clears.
      if (!(drawsSuspended(audioStore) || scopeTick % 2 !== 0)) {
      // Guard the ENTIRE draw in try/catch: a transient audio-graph / canvas race (an analyser detached mid
      // deck-load, a worker postMessage on a detached buffer, the bus array drifting during a resync) must
      // NEVER throw out of this loop. The re-arm is the only thing keeping meters/waves alive and it used to
      // sit AFTER the throwable body — so one bad frame froze every meter for the whole session. Now a throw
      // is swallowed and the loop self-heals on the next frame.
      try {
      // Worker path collects per-canvas analyser bytes into `frames` (buffers transferred in one postMessage);
      // when unavailable, `sw` is null and we draw on the main thread as before.
      let sw = ensureScopeWorker()
      let frames = sw !== null ? [] : null
      let bufs = sw !== null ? [] : null
      if (audioStore.analyser) {
        let spec = document.querySelector(".dk-spectrum")
        if (spec) {
          if ((sw !== null) && scopeRegister(spec, "spectrum")) {
            let n = audioStore.analyser.frequencyBinCount
            let sb = new Uint8Array(n)
            audioStore.analyser.getByteFrequencyData(sb)
            frames.push({ id: "spectrum", kind: "spectrum", color: "#f97316", data: sb })
            bufs.push(sb.buffer)
          } else {
            drawSpectrumCanvas(spec, audioStore.analyser, "#f97316")
          }
        }
      }
      // Bottom-bar COMPRESSOR readout: live gain reduction (dB). ratio<=1 means the toggle bypassed it.
      if (audioStore.masterComp) {
        let cg = document.querySelector(".master-comp-gr")
        if (cg) {
          let bypassed = audioStore.masterComp.ratio && audioStore.masterComp.ratio.value <= 1.01
          if (bypassed) {
            cg.textContent = "BYPASS"
          } else {
            let red = audioStore.masterComp.reduction
            if ((red !== null) && red.value !== undefined) {
              red = red.value
            }
            cg.textContent = Number(Math.round(Number(red) * 10) / 10).toFixed(1) + "dB"
          }
        }
      }
      if (audioStore.buses) {
        let dpj = rt.project
        let deckLvl = { A: 0, B: 0, C: 0, D: 0 }
        // Look the bus up by STABLE channel id, not positional index. The per-frame reconcile (syncChannelBuses)
        // only GROWS the bus array and never reorders it, while a full resyncAllChannelBuses runs on only a few
        // paths — so after a deck load / reorder / remote adopt, buses[wi] can point at a DIFFERENT channel's
        // analyser than channels[wi], feeding the wrong stem's meter/waveform (or none). A chId→bus map keeps
        // each meter on its own signal. Falls back to positional for any legacy bus without a chId.
        let busById = {}
        let bj = 0
        while (bj < audioStore.buses.length) {
          let bb = audioStore.buses[bj]
          if (bb && (bb.chId !== null)) {
            busById[String(bb.chId)] = bb
          }
          bj = bj + 1
        }
        let chans = (dpj && dpj.channels) ? dpj.channels : []
        let wi = 0
        while (wi < chans.length) {
          let ch = chans[wi]
          let bus = ch ? busById[String(ch.id)] : null
          if (!bus) {
            bus = audioStore.buses[wi]
          }
          let lvl = bus && bus.analyser ? busPeakLevel(bus.analyser) : 0
          let chDeck = ch ? channelDeck(dpj, ch) : "A"
          // Key the canvas/meter/worker-id by the CHANNEL ID (stable), not the bus index (which shifts on a deck
          // load → a stale scope-worker registration painting the wrong deck's colour, the "loaded deck = blue
          // waveforms" bug). The canvas carries class dk-wave-<ch.id>, matching DeckMixer's StemFader.
          let wkey = ch ? ch.id : String(wi)
          let cv = document.querySelector(".dk-wave-" + wkey)
          if (cv && bus && bus.analyser) {
            let col = deckWaveColorHex(chDeck)
            if ((sw !== null) && scopeRegister(cv, "wave-" + wkey)) {
              let N = bus.analyser.fftSize
              let tb = new Uint8Array(N)
              bus.analyser.getByteTimeDomainData(tb)
              frames.push({ id: "wave-" + wkey, kind: "wave", color: col, data: tb })
              bufs.push(tb.buffer)
            } else {
              drawMiniWave(cv, bus.analyser, col)
            }
          }
          // Drive the per-stem fader's segmented level meter from the same analyser (CSS var → fill height).
          let meterEl = document.querySelector(".dk-lvl-" + wkey)
          if (meterEl) {
            meterEl.style.setProperty("--lvl", String(lvl))
          }
          // Accumulate the deck's level (max across its channels) for the centre per-deck volume meters.
          if (ch) {
            if ((deckLvl[chDeck] !== null) && lvl > deckLvl[chDeck]) {
              deckLvl[chDeck] = lvl
            }
          }
          wi = wi + 1
        }
        let dks = ["A", "B", "C", "D"]
        let di = 0
        while (di < dks.length) {
          let dm = document.querySelector(".dk-deck-lvl-" + dks[di])
          if (dm) {
            dm.style.setProperty("--lvl", String(deckLvl[dks[di]]))
          }
          di = di + 1
        }
      }
      // One message per frame for ALL worker canvases; transfer the byte buffers (zero-copy).
      if ((sw !== null) && (frames !== null) && frames.length > 0) {
        scopeWorker.postMessage({ type: "frame", frames: frames }, bufs)
      }
      // Set Recorder waveform: repaint the four deck lane canvases ONLY when the tape changed (the dirty flag is
      // set by recordPlayedStep as it folds each step, and re-asserted at the end of every PlaylistView render
      // so a memo-recreated canvas repaints). This coalesces many taped steps into <=1 repaint/frame, here on
      // the throttled visual loop — never on the audio scheduler path. The flag is cleared only AFTER drawing,
      // and this whole block is past the drawsSuspended/30fps gate, so a step taped during a suspend survives.
      if (rt.tplWaveDirty && rt.tplEnergy) {
        let plCv = document.querySelector(".pl-wave-cv-overlay")
        if (plCv) {
          drawSetWaveOverlay(plCv, rt.tplEnergy, rt.tplActiveDecks, 26, 16)
        }
        // Keep the note/step/bar counter live without a per-bar vdom render (bumpTimeline now fires only when a
        // new lane mounts). Imperative textContent — same format as PlaylistView's status line.
        let plStatus = document.querySelector(".pl-status")
        if (plStatus) {
          let tn = rt.tplEnergy.totalNotes !== null ? rt.tplEnergy.totalNotes : 0
          let stp = Array.isArray(rt.tplTape) ? rt.tplTape.length : 0
          let brs = Math.ceil((rt.tplEnergy.maxStep + 1) / 16)
          let txt = stp === 0
            ? "nothing recorded yet"
            : String(tn) + " note" + (tn === 1 ? "" : "s") + " · " + String(stp) + " step" + (stp === 1 ? "" : "s") + " · " + String(brs) + " bar" + (brs === 1 ? "" : "s")
          if (plStatus.textContent !== txt) {
            plStatus.textContent = txt
          }
        }
        rt.tplWaveDirty = false
      }
      } catch (eFrame) {}
      }
      requestAnimationFrame(scopeFrame)
    }
    requestAnimationFrame(scopeFrame)
  }

  // mode: "sequence" = play the rack / pattern you are editing (monitor); "song" = play the live
  // arrangement of launched patterns (session arming). Space -> sequence, Enter -> song.
  fn onPlay(mode, startTick, songScene) {
    if (typeof window !== "undefined" && window.speechSynthesis) {
      if (!window.__ttsUnlocked) {
        let u = new SpeechSynthesisUtterance("")
        u.volume = 0
        window.speechSynthesis.speak(u)
        window.__ttsUnlocked = true
      }
    }
    let pm = mode === "song" ? "song" : "sequence"
    rt.playMode = pm
    setPlayMode(pm)
    ensureAudio(project, audioStore)
    applyIoRack()
    updateMixerFromProject(project, audioStore)
    let ctx = audioStore.ctx
    // A follower joining a song mid-flight starts at the host's playhead so it lands on the same bar.
    let st = (startTick !== null) && Math.floor(Number(startTick)) >= 0 ? Math.floor(Number(startTick)) : 0
    tplLoopResetAll()
    // Hitting Play starts a fresh take — snapshot the sounds + zero the tape so the timeline records THIS
    // performance. (No-op during a replay, which sets tplReplaying before calling onPlay.)
    if (rt.beginTake) {
      rt.beginTake(st)
    }
    if (pm === "song") {
      // A song starts at the head of the explicit arrangement (or the first saved pattern when none is
      // set) and auto-advances through it. Per-track clip overrides are honoured on top of each scene.
      rt.songStopRequested = false
      let scn = songStart(project, rt)
      if ((songScene !== null) && Math.floor(Number(songScene)) >= 0) {
        scn = Math.floor(Number(songScene))
        rt.followCount = 0
        rt.songPos = null
        rt.sessionActiveScene = scn
      }
      armSceneWithOverrides(project, rt, scn)
      rt.songScene = scn
      rt.songSceneEndTick = st + sceneBarLength(project, scn) * coDjStepsPerBar()
      coDjPushLive(project, rt, st)
      if (!coDjIsFollower(rt)) {
        coDjPushControl([transportDirective("song", scn)], 0)
      }
    } else {
      rt.songScene = null
      rt.songSceneEndTick = null
    }
    rt.playing = true
    rt.transportNextTick = st

    // All the non-audio per-step bookkeeping (session/song advance, co-DJ flush, prune), for ONE step.
    // Pure of timing: `when` is the exact audio-clock time the step sounds; visuals are published by the
    // Transport's draw loop so they land with the audio, not ~lookahead early.
    fn scheduleStep(p, r, step, when) {
      let barSteps = coDjStepsPerBar()
      let qSteps = typeof r.launchQuantSteps === "number" && r.launchQuantSteps >= 1
        ? Math.floor(r.launchQuantSteps)
        : barSteps
      let onQuant = qSteps > 0 && step % qSteps === 0
      let onBar = barSteps > 0 && step % barSteps === 0
      if ((onQuant || onBar) && p) {
        if (r.playMode === "song") {
          let armedChanged = false
          if (r.sessionQueuePending) {
            if (onQuant && sessionCommitQueued(p, r)) {
              r.trackOverrides = []
              r.trackPending = []
              r.songScene = r.sessionActiveScene
              r.songSceneEndTick = step + sceneBarLength(p, r.songScene) * barSteps
              armedChanged = true
            }
          } else {
            if (onQuant && r.trackPending && r.trackPending.length > 0) {
              if (!r.sessionArmedClipIds) {
                r.sessionArmedClipIds = []
              }
              let pi = 0
              while (pi < r.trackPending.length) {
                let it = r.trackPending[pi]
                r.sessionArmedClipIds[it.t] = it.clip
                pi = pi + 1
              }
              r.trackPending = []
              armedChanged = true
            }
            if (onBar && (r.songSceneEndTick !== null) && step >= r.songSceneEndTick) {
              let cur = r.songScene !== null ? r.songScene : 0
              let nxt = songAdvance(p, r, cur)
              if (nxt < 0) {
                r.songStopRequested = true
              } else {
                if (nxt !== cur) {
                  armSceneWithOverrides(p, r, nxt)
                  r.songScene = nxt
                  armedChanged = true
                }
                r.songSceneEndTick = step + sceneBarLength(p, nxt) * barSteps
              }
            }
          }
          if (armedChanged) {
            bumpSessionUi()
            coDjPushLive(p, r, step + barSteps)
          }
        } else if (onQuant) {
          if (sessionCommitQueued(p, r)) {
            bumpSessionUi()
          }
        }
        if (onBar && r.coDjPushClock) {
          r.coDjPushClock(step, r.songScene !== null ? r.songScene : null)
        }
      }
      if (step % 64 === 0) {
        if (p && audioStore.buses) {
          let res = pruneStaleTracks(p, audioStore, step, coDjTrackExpirySequences())
          if (res.removedCount > 0 && r.setProject) {
            r.setProject(p)
          }
          if (res.removedCount > 0 && r.setSelectedCh && typeof r.selectedCh === "number" && r.selectedCh >= p.channels.length) {
            r.setSelectedCh(p.channels.length > 0 ? p.channels.length - 1 : 0)
          }
        }
        if (r.consumePlayedBlocks) {
          r.consumePlayedBlocks(step)
        }
      }
      r.perfStep = step
      // A replay plays exactly as long as the recording; stop once its last step has sounded (+1 bar tail).
      if (r.tplReplaying && (r.tplReplayMaxStep !== null) && step > Math.floor(r.tplReplayMaxStep) + 16) {
        onStop()
        return
      }
      coDjFlushScheduledForStep(step, r)
      // THE audio: schedule this step's notes at the EXACT audio time `when` (jitter-immune).
      transportTick(r.project, audioStore, step, r, when)
      // Grid-synced channel filter sweeps (the universal CUTOFF automation — works on any voice incl. decks).
      applyChannelFilterAutomation(r.project, audioStore, step * 0.25, when)
      if (r.sessionQueuePending && r.bumpSeqPromoteUi) {
        r.bumpSeqPromoteUi()
      }
    }

    // Hand the timing to the Transport projection: it runs the lookahead scheduler + clock pump + draw
    // loop, calling scheduleStep for each step and publishing position/health on the signal bus.
    transport.start({
      startTick: st,
      secPerStep: () => {
        let p2 = rtRef.current.project
        return secondsPerStep(p2 && typeof p2.bpm === "number" ? p2.bpm : 120)
      },
      targetBpm: () => {
        let p2 = rtRef.current.project
        return p2 && typeof p2.bpm === "number" ? p2.bpm : 120
      },
      swing: () => {
        let p2 = rtRef.current.project
        return p2 && typeof p2.swing === "number" ? p2.swing : 0
      },
      onStep: (step, when) => {
        let r = rtRef.current
        scheduleStep(r.project, r, step, when)
        r.transportNextTick = step + 1
        if (r.songStopRequested) {
          r.songStopRequested = false
          return true
        }
        return false
      },
      onStopReached: () => {
        onStop()
      }
    })
    setPlaying(true)
    // Only the host broadcasts the shared transport. A follower reaches onPlay via coDjFollowStart (it's
    // mirroring the host) — it must NOT re-broadcast playing_start, or the room echoes its own follow.
    if (rt.coDjNotifyPlaying && !coDjIsFollower(rt)) {
      rt.coDjNotifyPlaying(true)
    }
    ctx.resume()
  }

  fn onDeckMain(mode) {
    rt.emit("main_deck", mode === "local" ? "local" : "live")
  }

  // Broadcast what is ACTUALLY PLAYING (armed pattern + per-track overrides) to the co-DJ hub, so
  // collaborators hear your launches on your deck lane — not your edit buffer. effStep = the perf step
  // the receiver should apply it from. (Multiplayer model A; see the "shared session" issue for B.)
  fn coDjPushLive(proj, rtObj, effStep) {
    if (!(rtObj && rtObj.coDjWs && rtObj.coDjWs.readyState === 1)) {
      return
    }
    let aid = rtObj.coDjActorId ? rtObj.coDjActorId : (rtObj.coDjClientId ? rtObj.coDjClientId : "actor")
    let text = emitLivePlayback(proj, rtObj)
    let lines = text.split("\n")
    let payload = JSON.stringify({
      type: "deck.block",
      lines: lines,
      effectivePerfStep: effStep,
      actorId: aid,
      authorId: aid
    })
    rtObj.coDjWs.send(payload)
  }

  // The perf step a launch should land on: the next launch-quantize boundary while playing (so a
  // follower commits the host's launch on the same boundary), else 0 (apply on receipt).
  fn nextLaunchStep() {
    if (!rt.playing) {
      return 0
    }
    let ps = typeof rt.perfStep === "number" ? Math.floor(rt.perfStep) : 0
    let q = (rt.launchQuantSteps !== null) && Math.floor(rt.launchQuantSteps) >= 1 ? Math.floor(rt.launchQuantSteps) : 16
    return (Math.floor(ps / q) + 1) * q
  }

  // Broadcast session-control directives (@ launch / @ transport) to the hub at a quantized step, so
  // every player applies the same launch to their shared arming — same UI, same sound (issue #1, B).
  fn coDjPushControl(directiveLines, effStep) {
    if (!(rt && rt.coDjWs && rt.coDjWs.readyState === 1)) {
      return
    }
    if (!directiveLines || directiveLines.length === 0) {
      return
    }
    let aid = rt.coDjActorId ? rt.coDjActorId : (rt.coDjClientId ? rt.coDjClientId : "actor")
    rt.coDjWs.send(JSON.stringify({
      type: "deck.block",
      lines: directiveLines,
      effectivePerfStep: effStep,
      actorId: aid,
      authorId: aid
    }))
  }
  rt.coDjPushControl = coDjPushControl
  rt.nextLaunchStep = nextLaunchStep

  // Live FX throw audio hook (the Audio side of the `@ fx` directive): applyLaunchDirective calls this on
  // every client (local + peers) so the punch lands identically. echo = tempo-synced delay; filter = sweep.
  rt.triggerMasterFx = (type, on, params) => {
    if (type === "filter") {
      triggerMasterFxFilter(audioStore, on, params)
    } else {
      triggerMasterFxEcho(audioStore, on, params)
    }
  }
  // The echo division (in BEATS: 1/4 note = 1, 1/8 = 0.5, 3/16 = 0.75, 1/2 = 2). Chosen in the FX row.
  if (rt.fxBeatDiv === null) {
    rt.fxBeatDiv = 0.75
  }
  // UI/hotkey entry for an FX throw: apply LOCALLY through ingest (gated → fires the audio) AND broadcast to
  // peers. Hold-to-throw (on=engage, off=release). The echo TIME is beat-synced to the current BPM so the
  // repeats land on the grid (not a fixed 0.3s).
  rt.onFxThrow = (type, on) => {
    let params = {}
    if (type !== "filter") {
      let bpm = rtRef.current.project && typeof rtRef.current.project.bpm === "number" ? rtRef.current.project.bpm : 120
      let beats = typeof rt.fxBeatDiv === "number" && rt.fxBeatDiv > 0 ? rt.fxBeatDiv : 0.75
      params.time = Math.round((60 / bpm) * beats * 1000) / 1000
      params.fb = 0.5
    }
    let line = fxDirective(type === "filter" ? "filter" : "echo", on === true, params)
    if (rt.directive) {
      rt.directive(line)
    }
    coDjPushControl([line], 0)
  }

  // ---- DECK vinyl moves as `@ deck` directives (multiplayer-safe, recordable) ----
  // The RECEIVER: applyLaunchDirective calls this on every client (local + peers) so a cut/brake/reverse lands
  // identically. Dispatches to the local per-deck scratch engine (the same hooks the jog uses).
  rt.applyDeckMove = (deck, move, on) => {
    if (move === "cut" && rt.scratchCut) {
      rt.scratchCut(deck, on)
    } else if (move === "rev" && rt.scratchReverse) {
      rt.scratchReverse(deck, on)
    } else if (move === "brake" && rt.scratchBrake) {
      rt.scratchBrake(deck, on)
    } else if (move === "spin" && rt.scratchSpinback) {
      rt.scratchSpinback(deck)
    }
  }
  // UI/hotkey entry for a deck move: apply LOCALLY through ingest (gated → fires the scratch) AND broadcast to
  // peers — exactly the `@ fx` throw pattern, so cuts/brakes are multiplayer-safe and ride a recorded Set.
  rt.onDeckMove = (deck, move, on) => {
    let line = deckMoveDirective(deck, move, on)
    if (rt.directive) {
      rt.directive(line)
    }
    coDjPushControl([line], 0)
    // If a take is recording, buffer this move so recordPlayedStep folds it into the step's tape entry — the
    // Set ghost re-fires your cuts/brakes/reverses, not just the notes.
    if (rt.tplRecording && !rt.tplReplaying) {
      if (!rt.tplPendingMoves) {
        rt.tplPendingMoves = []
      }
      rt.tplPendingMoves.push({ deck: deck, move: move, on: on === true })
    }
  }

  // Host clock heartbeat: while the host plays, broadcast the playhead (step + scene) once per bar so
  // followers can lock to it. Only the host emits — followers slave.
  fn coDjPushClock(perfStep, scene) {
    if (!(rt && rt.coDjWs && rt.coDjWs.readyState === 1 && rt.coDjIsHost === true)) {
      return
    }
    let aid = rt.coDjActorId ? rt.coDjActorId : (rt.coDjClientId ? rt.coDjClientId : "actor")
    let bpm = project && typeof project.bpm === "number" ? project.bpm : null
    rt.coDjWs.send(JSON.stringify(coDjClockPayload(aid, perfStep, scene, bpm, rt.playMode)))
  }
  rt.coDjPushClock = coDjPushClock

  // Followers call these (from the co-DJ receive path) to slave their transport to the host.
  rt.setTransportTick = (n) => {
    let v = Math.floor(Number(n))
    if (v >= 0 && v === v) {
      transport.setTick(v)
      rt.transportNextTick = v
    }
  }
  rt.getTransportTick = () => {
    return transport.getTick()
  }
  // Start following the host's song at `hostStep`: if stopped, begin playback there; if already playing,
  // just realign the tick. Audio may stay silent until the user interacts (browser gesture policy), but
  // the transport position stays locked so it's in phase the moment audio resumes.
  rt.coDjFollowStart = (hostStep, hostMode) => {
    if (!coDjShouldFollow(rt)) {
      return
    }
    // The host's clock takes over — drop any local Preview the follower started so we don't double up.
    onStopPreview()
    let step = Math.floor(Number(hostStep))
    if (step < 0 || step !== step) {
      step = 0
    }
    if (!rt.playing) {
      // Follow the HOST's mode: sequence = play the (synced) rack, song = play the session clips. Forcing
      // "song" made a guest silent whenever the host was jamming the rack in Sequence mode.
      onPlay(hostMode === "sequence" ? "sequence" : "song", step)
    } else {
      transport.setTick(step)
      rt.transportNextTick = step
    }
  }
  rt.coDjFollowStop = () => {
    if (coDjShouldFollow(rt) && rt.playing) {
      onStop()
    }
  }
  // Apply a host clock tick: realign the local tick toward the host (snap on large drift).
  rt.coDjApplyClock = (hostStep) => {
    if (!coDjShouldFollow(rt) || !rt.playing) {
      return
    }
    let aligned = coDjClockAlign(transport.getTick(), hostStep, 1)
    transport.setTick(aligned)
    rt.transportNextTick = aligned
  }

  fn curViewBar() {
    return rt.gridViewBar !== null ? Math.floor(Number(rt.gridViewBar)) : 0
  }

  // SAVE — copy the current rack (steps / piano / per-bar) into pattern `si`. Edit-only; never plays.
  fn onPatternSave(si) {
    ensureProjectSession(project)
    sessionWriteRackToSceneClip(project, si)
    bumpSessionUi()
    if (rt.playing && rt.bumpSeqPromoteUi) {
      rt.bumpSeqPromoteUi()
    }
    setProjectFromUI(project)
  }

  // SAVE 1 — copy only the bar you're viewing into pattern `si`'s matching bar (others untouched).
  fn onPatternSaveBar(si) {
    ensureProjectSession(project)
    sessionWriteRackBarToSceneClip(project, si, curViewBar())
    bumpSessionUi()
    if (rt.playing && rt.bumpSeqPromoteUi) {
      rt.bumpSeqPromoteUi()
    }
    setProjectFromUI(project)
  }

  // LOAD — pull pattern `si` into the rack so you can see / edit it. Does not arm anything live;
  // in Play Sequence mode this is also what you hear (the rack is the monitored buffer).
  fn onPatternLoad(si) {
    ensureProjectSession(project)
    loadSceneIntoRack(project, si)
    rt.editingScene = si
    if (rt.bumpGrid) {
      rt.bumpGrid()
    }
    bumpSessionUi()
    setProjectFromUI(project)
  }

  // LOAD 1 — pull only pattern `si`'s viewed bar into the rack's current bar (other bars untouched).
  fn onPatternLoadBar(si) {
    ensureProjectSession(project)
    loadSceneBarIntoRack(project, si, curViewBar())
    if (rt.bumpGrid) {
      rt.bumpGrid()
    }
    bumpSessionUi()
    setProjectFromUI(project)
  }

  // LAUNCH — go LIVE on pattern `si`. If a song is already live, queue the swap for the next quantize
  // boundary (no restart). If nothing live is running (stopped, or just previewing the rack), launching
  // STARTS the session live on this scene immediately — launching is a live act, so you hear it.
  fn onPatternLaunch(si) {
    ensureProjectSession(project)
    // Launching a scene takes it live — so end any private cue audition (you've committed). This is the
    // "cue → launch" path that replaced the separate THROW button.
    onStopPreview()
    // A full pattern LAUNCH resets the per-track mix — every track follows this pattern again.
    rt.trackOverrides = []
    rt.trackPending = []
    if (rt.playing && rt.playMode === "song") {
      // Already live — queue the swap (and the co-DJ broadcast) for the next bar.
      sessionQueueScene(project, rt, si)
      coDjPushControl([launchSceneDirective(si)], nextLaunchStep())
    } else {
      // Not live (stopped or previewing) — start the session live on this scene now.
      onPlay("song", 0, si)
    }
    bumpSessionUi()
    if (rt.playing && rt.bumpSeqPromoteUi) {
      rt.bumpSeqPromoteUi()
    }
    setProjectFromUI(project)
  }

  fn onStop() {
    // A replay ends when the transport stops; clear replay state so the next Play records a fresh take.
    rt.tplReplaying = false
    rt.tplReplayTriggers = null
    rt.tplReplayControls = null
    rt.tplReplayMoves = null
    bumpTimeline()
    // Only the host broadcasts the shared transport (a follower reaches onStop via coDjFollowStop).
    if (rt.coDjNotifyPlaying && !coDjIsFollower(rt)) {
      rt.coDjNotifyPlaying(false)
    }
    // A master stopping the transport stops the shared session for followers too (apply on receipt).
    if (!coDjIsFollower(rt)) {
      coDjPushControl([transportDirective("stop", 0)], 0)
    }
    // Tear down the Transport projection (scheduler + pump + draw loop); it publishes position -1 so the
    // playhead/grid subscribers clear themselves.
    transport.stop()
    rt.playing = false
    rt.transportNextTick = null
    cancelTtsVocal()
    setPlaying(false)
  }
  rt.stopPlayback = onStop
  rt.onPlaySequence = () => onPlay("sequence")
  rt.onPlaySong = () => onPlay("song")

  // ---- deck-stream playback (the Playlist tape): record the live deck stream, save it as a Set, replay it.
  let [timelineGen, setTimelineGen] = useState(0)
  fn bumpTimeline() {
    setTimelineGen((g) => g + 1)
  }
  // Tape one deck fragment with its step (relative to record-start). The single recorder entry point: the
  // ingest out-stream tap routes here, and so do the not-yet-migrated handlers (step toggles, notes,
  // launches) that still bypass ingest — so REC captures a real performance, not just the mixer moves.
  // Record WHAT PLAYED: transportTick hands us the note triggers it fired this step (the performance), and
  // we tape them with the step (relative to the take's start). This — not the edit stream — is the Set.
  // The performance CONTROLS that aren't notes: the 4-way crossfader (X/Y) and the per-deck FLT filter. We
  // tape a snapshot per step so a saved Set replays the whole DJ move — the filter sweep + the fader blend —
  // not just the note stream. Crossfade is read normalized (the value the audio actually used).
  fn controlSnapshot(p) {
    let de = p.deckEq ? p.deckEq : {}
    let fa = de.A && typeof de.A.flt === "number" ? de.A.flt : 0
    let fb = de.B && typeof de.B.flt === "number" ? de.B.flt : 0
    let fc = de.C && typeof de.C.flt === "number" ? de.C.flt : 0
    let fd = de.D && typeof de.D.flt === "number" ? de.D.flt : 0
    return { xf: crossfadeValue(p), xfy: crossfadeValueY(p), fA: fa, fB: fb, fC: fc, fD: fd }
  }
  fn controlsDiffer(a, b) {
    if (!b) {
      return true
    }
    return a.xf !== b.xf || a.xfy !== b.xfy || a.fA !== b.fA || a.fB !== b.fB || a.fC !== b.fC || a.fD !== b.fD
  }
  // ---- Set Recorder waveform accumulator. The timeline is drawn imperatively to canvas (drawSetWaveLane, from
  // scopeFrame) off an incremental per-deck energy map on rt — so per played step is O(triggers), never an
  // O(total) re-bucket + SVG-path rebuild in render. The fold math is pure (SetEnergy.tish); these wire it to rt.
  fn resetTplEnergy() {
    rt.tplEnergy = freshSetEnergy()
    rt.tplActiveDecks = freshActiveDecks()
    rt.tplWaveDirty = true
  }
  // Cache busIndex -> deck letter; rebuilt only when the channel roster changes (channelDeck does a co-DJ roster
  // walk, too costly per-trigger in the hot path). channelsRev is the roster's rev counter.
  fn ensureDeckOfBus() {
    let p = rt.project
    if (!p || !p.channels) {
      rt.tplDeckOfBus = []
      return
    }
    let rev = ensureProjectRev(p).channels
    // Key the cache on project IDENTITY as well as the channels rev. rev.channels is a per-instance counter
    // that every freshly loaded project starts at 0 (loads never bump it), so a project SWAP (load/replay)
    // could collide on rev (old 0 === new 0) and silently reuse the previous project's bus→deck map — which
    // collapses a multi-deck Set's energy onto the wrong/missing lanes. Identity guards that.
    if ((rt.tplDeckOfBus !== null) && rt.tplDeckOfBusProj === p && rt.tplDeckOfBusRev === rev) {
      return
    }
    let arr = []
    let i = 0
    while (i < p.channels.length) {
      arr.push(channelDeck(p, p.channels[i]))
      i = i + 1
    }
    rt.tplDeckOfBus = arr
    rt.tplDeckOfBusProj = p
    rt.tplDeckOfBusRev = rev
  }
  // Fold one played step's triggers into the per-deck energy map. Returns true if a deck produced its FIRST
  // sound (so the caller can mount that lane's canvas via a one-off bumpTimeline).
  fn foldStepIntoEnergy(step, trs) {
    ensureDeckOfBus()
    return foldSetEnergyStep(rt.tplEnergy, rt.tplActiveDecks, rt.tplDeckOfBus, step, trs)
  }
  // One-time O(total) rebuild from the tape (load/replay/deck-remap only, never per bar).
  fn rebuildTplEnergy() {
    resetTplEnergy()
    let tape = Array.isArray(rt.tplTape) ? rt.tplTape : []
    let i = 0
    while (i < tape.length) {
      let ev = tape[i]
      let s = Math.floor(Number(ev.step))
      // A loaded Set is untrusted input: drop NaN/negative steps and cap the max so a corrupt/hostile file
      // can't push an absurd maxStep into the per-frame canvas loop (a 162M-px canvas → UI hang). Live
      // recording is already bounded by transport progress; only the load path needs the clamp.
      if (s >= 0 && s <= 131072) {
        foldStepIntoEnergy(s, ev.triggers !== null ? ev.triggers : [])
      }
      i = i + 1
    }
    rt.tplWaveDirty = true
  }
  rt.recordPlayedStep = (globalStep, triggers) => {
    if (!rt.tplRecording || rt.tplReplaying) {
      return
    }
    let trs = triggers ? triggers : []
    let ctl = controlSnapshot(rt.project)
    let ctlChanged = controlsDiffer(ctl, rt.tplLastCtl)
    let moves = (rt.tplPendingMoves && rt.tplPendingMoves.length > 0) ? rt.tplPendingMoves : null
    // Record a step when notes fired OR a performance control moved OR a deck move fired — so the FLT/4-way-fader
    // trajectory AND the scratch/cut/brake gestures are captured across silent steps too, not only under notes.
    if (trs.length === 0 && !ctlChanged && (moves === null)) {
      return
    }
    if (moves !== null) {
      rt.tplPendingMoves = []
    }
    let step = Math.floor(globalStep) - Math.floor(rt.tplTapeStartStep !== null ? rt.tplTapeStartStep : 0)
    if (step < 0) {
      step = 0
    }
    rt.tplLastCtl = ctl
    rt.tplTape.push({ step: step, triggers: trs, ctl: ctl, moves: moves })
    // Fold this step into the per-deck energy map + flag the canvas dirty (scopeFrame repaints the lanes, off
    // the audio path). Re-render the React CHROME when a deck FIRST produces sound (its lane canvas must mount)
    // OR at a bar boundary (so the ruler ticks + the track's gridline width keep growing with the take instead
    // of freezing at the last lane-mount). This stays cheap — the heavy waveform is canvas/off-vdom now, so
    // PlaylistView only rebuilds the small ruler/chrome, NEVER an SVG path or a tape re-bucket; no old jank.
    let newLane = foldStepIntoEnergy(step, trs)
    rt.tplWaveDirty = true
    if (newLane || step % 16 === 0) {
      bumpTimeline()
    }
  }
  // A take begins when the transport starts a normal play: snapshot the sounds (the Set header) + zero the
  // tape clock. Called from onPlay. Skipped during replay (we're re-firing, not recording).
  rt.beginTake = (startStep) => {
    if (!rt.tplRecording || rt.tplReplaying) {
      return
    }
    rt.tplTape = []
    rt.tplLastCtl = null
    resetTplEnergy()
    rt.tplStartState = emitProject(rt.project)
    rt.tplRecMode = rt.playMode === "sequence" ? "sequence" : "song"
    rt.tplTapeStartStep = Math.floor(startStep !== null ? startStep : (typeof rt.perfStep === "number" ? rt.perfStep : 0))
    rt.tplViewOrigin = rt.tplTapeStartStep
  }
  // "New" clears the timeline; the next Play records a fresh take.
  // REC arm/disarm. Recording is off by default; arming while already playing starts a fresh take from the
  // current step (otherwise no take was begun at Play time, so the tape origin would be stale).
  fn onToggleRec() {
    let on = rt.tplRecording === true ? false : true
    rt.tplRecording = on
    if (on && playing && rt.beginTake) {
      rt.beginTake(typeof rt.perfStep === "number" ? rt.perfStep : 0)
    }
    setProjectFromUI(project)
  }
  fn onNewTake() {
    rt.tplTape = []
    rt.tplStartState = null
    rt.tplLastCtl = null
    resetTplEnergy()
    // Restart the take at the 0 marker: re-zero the take clock (so whatever plays next records as step 0 and
    // draws from the left edge) and snap the timeline scroll back to the start — even mid-playback.
    let ps = typeof rt.perfStep === "number" ? Math.floor(rt.perfStep) : 0
    rt.tplTapeStartStep = ps
    rt.tplViewOrigin = ps
    if (typeof document !== "undefined") {
      let sc = document.querySelector(".pl-scroll")
      if (sc) {
        sc.scrollLeft = 0
      }
    }
    bumpTimeline()
  }
  // Persist the current take as a Set: the sounds header + the played-trigger timeline.
  fn onSaveRecording() {
    if (!rt.tplTape || rt.tplTape.length === 0) {
      return
    }
    promptName("Save this take as a Set (" + String(rt.tplTape.length) + " played steps)", "My Take", (nm) => {
      let header = rt.tplStartState !== null ? rt.tplStartState : emitProject(project)
      setLibrary.save(nm, emitSetStream(header, rt.tplTape, rt.tplRecMode), 0)
      setSetLibGen((g) => g + 1)
    })
  }
  // Replay a take: install its trigger map and run the transport from 0 — transportTick fires the recorded
  // triggers at each step (the ghost re-plays the exact performance), instead of recomputing from patterns.
  fn replayTriggers(tape, mode) {
    let map = {}
    let ctlMap = {}
    let moveMap = {}
    let maxStep = 0
    let i = 0
    while (i < tape.length) {
      let e = tape[i]
      let s = Math.floor(Number(e.step))
      map[s] = e.triggers
      if (e.ctl !== null) {
        ctlMap[s] = e.ctl
      }
      if (e.moves !== null) {
        moveMap[s] = e.moves
      }
      if (e.step > maxStep) {
        maxStep = s
      }
      i = i + 1
    }
    rt.tplReplayTriggers = map
    rt.tplReplayControls = ctlMap
    rt.tplReplayMoves = moveMap
    rt.tplReplayStartStep = 0
    rt.tplReplayMaxStep = maxStep
    rt.tplReplaying = true
    rt.tplViewOrigin = 0
    onPlay(mode === "sequence" ? "sequence" : "song", 0)
  }
  // Re-apply the recorded performance controls for a replay step: the 4-way crossfader + per-deck FLT, set
  // exactly as taped, through the same path the live DeckMixer uses (deckEq mutate → applyDeckEq → one
  // coalesced mix). Snapshots are sparse (only at change points), so the value persists until the next one.
  rt.applyReplayControls = (rel) => {
    let cm = rt.tplReplayControls
    if (!cm) {
      return
    }
    let ctl = cm[rel]
    if (ctl === null) {
      return
    }
    let p = rt.project
    if (typeof ctl.xf === "number") {
      p.transportCrossfade = ctl.xf
    }
    if (typeof ctl.xfy === "number") {
      p.transportCrossfadeY = ctl.xfy
    }
    ensureDeckEq(p)
    if (typeof ctl.fA === "number") { p.deckEq.A.flt = ctl.fA }
    if (typeof ctl.fB === "number") { p.deckEq.B.flt = ctl.fB }
    if (typeof ctl.fC === "number") { p.deckEq.C.flt = ctl.fC }
    if (typeof ctl.fD === "number") { p.deckEq.D.flt = ctl.fD }
    applyDeckEq(p, "A")
    applyDeckEq(p, "B")
    applyDeckEq(p, "C")
    applyDeckEq(p, "D")
    if (rt.scheduleDeckMix) {
      rt.scheduleDeckMix()
    }
  }
  // Re-fire the taped DECK vinyl moves for a replay step (cut/rev/brake/spin), through the LOCAL scratch engine
  // (not re-broadcast) so the ghost reproduces the scratch performance over its own decks.
  rt.applyReplayMoves = (rel) => {
    let mm = rt.tplReplayMoves
    if (!mm) {
      return
    }
    let mv = mm[rel]
    if (mv === null) {
      return
    }
    let i = 0
    while (i < mv.length) {
      let m = mv[i]
      if (rt.applyDeckMove) {
        rt.applyDeckMove(m.deck, m.move, m.on)
      }
      i = i + 1
    }
  }
  // Load a recorded Set: load its sounds, show the played timeline, then replay it (the ghost).
  fn onLoadReplay(nm) {
    let st = setLibrary.get(nm)
    if (!st || !isStreamSet(st.tpl)) {
      return
    }
    let parsed = parseSetStream(st.tpl)
    let res = loadProjectFromTpl(parsed.header)
    loadFullProject(res.project)
    rt.tplTape = parsed.events
    // loadFullProject's setProject is microtask-deferred, so rt.project still points at the OLD roster right
    // now — but rebuildTplEnergy folds synchronously and maps each trigger's busIndex→deck through rt.project.
    // Point it at the loaded project first (the deferred render reassigns the same instance) so a multi-deck
    // Set's energy lands on the right lanes instead of collapsing onto deck A via the off-roster fallback.
    rt.project = res.project
    rebuildTplEnergy()
    bumpTimeline()
    setTimeout(() => {
      replayTriggers(parsed.events, parsed.mode)
    }, 30)
  }

  // Perf debug readout (direct-DOM, no React churn): target vs measured BPM, the scheduler's lookahead
  // buffer margin (headroom before audio underruns), and an underrun count. Colour = health.
  rt.setBpmReadout = (target, trueBpm, marginMs, underruns) => {
    if (typeof document === "undefined") {
      return
    }
    let el = document.querySelector(".bpm-debug")
    if (!el) {
      return
    }
    let tb = trueBpm !== null ? Math.round(Number(trueBpm) * 10) / 10 : null
    let mm = marginMs !== null ? Math.round(Number(marginMs)) : null
    let ur = underruns !== null ? Math.floor(Number(underruns)) : 0
    // Self-expanding health readout: a bare ♥ when all is well (the target BPM already shows in the stepper
    // right beside it, so repeating it is redundant), expanding to live numbers ONLY when something needs
    // attention. Branch priority mirrors the colour cut below: underrun (alarm) → low headroom → tempo drift.
    let txt = "♥"
    if (ur > 0) {
      txt = "♥ ✕" + String(ur)
    } else if (mm !== null && mm < 25) {
      txt = "♥ " + String(mm) + "ms"
    } else if (tb !== null && Number(target) - tb > 2) {
      txt = "♥ " + String(Math.round(Number(target))) + "→" + String(tb)
    }
    el.textContent = txt
    let cls = "bpm-debug ok"
    if (ur > 0) {
      cls = "bpm-debug bad"
    } else if ((mm !== null) && mm < 25) {
      cls = "bpm-debug warn"
    } else if ((tb !== null) && Number(target) - tb > 2) {
      cls = "bpm-debug warn"
    }
    el.className = cls

    // Sync active jog wheel rotation speed directly with the BPM
    let markers = document.querySelectorAll(".dk-jog-marker")
    let mi = 0
    let dur = String((60 / Number(target)) * 4) + "s"
    while (mi < markers.length) {
      let mk = markers[mi]
      if (mk && (mk.classList.contains("dk-jog-spinning") || mk.classList.contains("dk-jog-spinning-rev"))) {
        mk.style.animationDuration = dur
      }
      mi = mi + 1
    }
  }

  // ---- Live transport: Sequence ⟷ Session on ONE shared clock ----------------------------------
  // Toggle the live source. Stopped → just selects what Play uses. Playing → flips the source LIVE on
  // the same running clock (no restart) — the whole point of "Sequence and Session share a clock".
  fn selectPlayMode(pm) {
    let m = pm === "song" ? "song" : "sequence"
    if (m === rt.playMode) {
      return
    }
    rt.playMode = m
    setPlayMode(m)
    // Repaint the Session panel on EVERY mode switch, even when stopped. SessionViewMemo (sessionEq) keys on
    // sessionUiGen, not playMode, and the panel renders playMode-derived state (which deck is the live source,
    // scene/clip highlights). Bumping here BEFORE the stopped early-return is what makes "switch Sequence↔
    // Session" actually update the panel when not playing (previously it only repainted while playing, so the
    // same click worked or didn't depending on transport state — the "switching doesn't always work" bug).
    bumpSessionUi()
    if (!rt.playing) {
      return
    }
    if (m === "song") {
      rt.songStopRequested = false
      let scn = songStart(project, rt)
      armSceneWithOverrides(project, rt, scn)
      rt.songScene = scn
      rt.songSceneEndTick = transport.getTick() + sceneBarLength(project, scn) * coDjStepsPerBar()
      coDjPushLive(project, rt, transport.getTick() + coDjStepsPerBar())
      coDjPushControl([transportDirective("song", scn)], 0)
    } else {
      rt.songScene = null
      rt.songSceneEndTick = null
    }
    bumpSessionUi()
  }
  rt.selectPlayMode = selectPlayMode
  // The live Play / Stop button: start in the current mode when stopped, stop when playing.
  fn onPlayStop() {
    // Host-only SHARED transport: a connected FOLLOWER can't drive the room's Play/Stop (the host is the clock
    // master; the follower auto-follows via coDjFollowStart). But its Play button is NOT dead — it auditions
    // (Previews) its own deck locally, which is the follower's whole "you can only preview" affordance.
    // Without this a follower's Play button does nothing in EITHER mode, which reads as "play not working".
    if (coDjIsFollower(rt)) {
      onPreview()
      return
    }
    if (rt.playing) {
      onStop()
    } else {
      onPlay(rt.playMode)
    }
  }
  rt.onPlayStop = onPlayStop

  // ---- Preview transport: its OWN independent clock, NOT bundled with the live transport ----------
  // Auditions the rack pattern (always sequence rendering) on a separate timer + tick. Starting/stopping
  // it never touches the live Sequence/Session clock, and vice versa.
  fn previewStepMs() {
    let b = project && typeof project.bpm === "number" ? project.bpm : 120
    if (b < 40) { b = 40 }
    if (b > 300) { b = 300 }
    return (60 / b / 4) * 1000
  }
  fn onStopPreview() {
    if (previewTimer) {
      clearTimeout(previewTimer)
      previewTimer = null
    }
    setPreviewing(false)
    // Stopping the preview clears any cue (so the THROW disarms + the scene un-highlights).
    if (rt.cueScene !== null) {
      rt.cueScene = null
      bumpSessionUi()
    }
  }
  fn onPreview() {
    if (previewing) {
      onStopPreview()
      return
    }
    ensureAudio(project, audioStore)
    applyIoRack()
    updateMixerFromProject(project, audioStore)
    if (previewTimer) {
      clearTimeout(previewTimer)
    }
    previewTick = 0
    // A throwaway runtime forced to sequence mode so transportTick renders the rack (ch.steps/pianoNotes).
    let pRt = { playMode: "sequence", playing: true }
    fn previewStep() {
      let r = rtRef.current
      if (!r || !audioStore.ctx) {
        return
      }
      pRt.project = r.project
      transportTick(r.project, audioStore, previewTick, pRt)
      previewTick = previewTick + 1
      previewTimer = setTimeout(previewStep, previewStepMs())
    }
    previewStep()
    setPreviewing(true)
  }
  rt.onPreview = onPreview
  rt.onStopPreview = onStopPreview
  // Un-cue: stop the audition + clear the cue (so THROW disarms). Driven by `@ cue off`.
  rt.onUncue = () => onStopPreview()

  // ---- Cue → Throw (Pioneer deck model): CUE auditions a scene PRIVATELY on the preview transport (never
  // broadcast — peers hear nothing); THROW commits the cued scene to the SHARED main. Driven by the
  // @ cue / @ throw directives so the whole flow is multiplayer-native deck.
  rt.onCueScene = (scene) => {
    onStopPreview()
    ensureAudio(project, audioStore)
    applyIoRack()
    updateMixerFromProject(project, audioStore)
    if (previewTimer) {
      clearTimeout(previewTimer)
    }
    // Beat-LOCK the cue to the main when it's playing: start the audition at the main's current step so the
    // cued scene's bar phase lines up with the master grid (you hear how it will actually drop). When the
    // main is stopped, the cue is a free audition from 0.
    previewTick = rt.playing && typeof rt.perfStep === "number" ? Math.floor(rt.perfStep) : 0
    rt.cueScene = scene
    ensureProjectSession(project)
    // The preview plays the CUED scene (song mode + that scene's clips armed) — your private audition.
    let armed = []
    let ti = 0
    while (ti < project.channels.length) {
      armed.push(sceneSlotClipId(project, scene, ti))
      ti = ti + 1
    }
    let pRt = { playMode: "song", playing: true, sessionArmedClipIds: armed, songScene: scene }
    fn cueStep() {
      let r = rtRef.current
      if (!r || !audioStore.ctx) {
        return
      }
      pRt.project = r.project
      transportTick(r.project, audioStore, previewTick, pRt)
      previewTick = previewTick + 1
      previewTimer = setTimeout(cueStep, previewStepMs())
    }
    cueStep()
    setPreviewing(true)
    bumpSessionUi()
  }
  // Commit the cued scene to the shared main LOCALLY (the @ throw directive already broadcast — no re-push).
  rt.onThrowScene = (scene) => {
    onStopPreview()
    rt.cueScene = null
    ensureProjectSession(project)
    rt.trackOverrides = []
    rt.trackPending = []
    if (rt.playing && rt.playMode === "song") {
      sessionQueueScene(project, rt, scene)
    } else {
      onPlay("song", 0, scene)
    }
    bumpSessionUi()
    setProjectFromUI(project)
  }
  // Hotkey C toggles the cue: un-cue if something's cued, else cue the active/last scene.
  rt.onCueActive = () => {
    if (!rt.directive) {
      return
    }
    if (rt.cueScene !== null) {
      rt.directive(cueDirective("off"))
      return
    }
    let s = rt.sessionActiveScene !== null ? rt.sessionActiveScene : (rt.songScene !== null ? rt.songScene : 0)
    rt.directive(cueDirective(Math.floor(Number(s))))
  }
  // Deck-set hot-swap: rebuild channel buses on the LIVE audio context so playback continues
  // seamlessly through a set load (no stop / no manual re-Play). No-op until audio has started.
  rt.resyncAudio = () => {
    let p = rtRef.current.project
    resyncAllChannelBuses(p, audioStore)
    updateMixerFromProject(p, audioStore)
  }
  // Load a SONG (a catalog deck-set or a user Set) onto a deck — the shared loader behind the Song panel +
  // the deck-header picker. Catalog songs carry a BPM; adopt it ONLY when nothing's playing (don't disrupt a
  // live set). Clears stale arming + reconciles audio so playback continues seamlessly through the swap.
  rt.loadSongOntoDeck = (kind, key, deck) => {
    // MULTIPLAYER GUARD: in a live session a player may only load a song onto their OWN deck. Reject any other
    // target (defense-in-depth behind the SongBrowser's disabled buttons). Solo (not connected) is unrestricted.
    let mine = coDjOwnDeckLetter(rt)
    if (mine !== null && deck !== mine) {
      if (typeof console !== "undefined" && console.log) {
        console.log("[loadSong] blocked: deck " + String(deck) + " is not my own (" + String(mine) + ") in a session")
      }
      return
    }
    let bpm = null
    if (kind === "set") {
      let lib = createSetLibrary()
      let st = lib.get(key)
      if (st) {
        loadSet(project, st, deck)
      }
    } else {
      loadDeckSet(project, deck, key)
      let cat = deckSetCatalog()
      let ci = 0
      while (ci < cat.length) {
        if (cat[ci].id === key) {
          bpm = cat[ci].bpm
        }
        ci = ci + 1
      }
    }
    rt.sessionArmedClipIds = []
    rt.sessionQueuedClipIds = []
    rt.sessionQueuePending = false
    rt.sessionQueuedScene = null
    if (rt.resyncAudio) {
      rt.resyncAudio()
    }
    // Adopt the song's tempo only when stopped — through the one write door so it round-trips + broadcasts.
    if ((bpm !== null) && bpm > 0 && !rt.playing && editorRef.current) {
      editorRef.current.emit("bpm", Math.round(Number(bpm)))
    }
    setProjectFromUI(project)
    // In a co-DJ session, push this deck change to peers so it syncs (host: snapshot; follower: stream own
    // lines, host applies the tracks it owns). Without this a follower's deck load never reaches the host.
    if (rt.coDjWs && rt.coDjWs.readyState === 1 && rt.coDjBroadcastNow) {
      rt.coDjBroadcastNow()
    }
  }
  // ---- Per-deck scratch (CDJ-style: each deck A/B/C/D has its own jog platter). Each renders ITS OWN pattern
  // loop into ITS OWN worklet, and grabbing a deck's wheel drives that deck's signed read-rate + ducks that
  // deck's live channels (so the scratch REPLACES the deck). Local performance gestures (not streamed) — like
  // the meters/preview. Each platter's output rides its deck's crossfader gain. `deck` is the letter "A".."D".
  rt.scratchLoadDeckLoop = (deck) => {
    ensureAudio(project, audioStore)
    let pr = renderDeckLoopToBuffer(project, deck, 1)
    if (pr && pr.then) {
      pr.then((res) => {
        if (res && res.data) {
          loadScratchBuffer(audioStore, deck, res.data)
          // Phase-align the freshly-loaded loop to where the deck is on the grid (the buffer load resets the
          // read head to 0, so seed it AFTER) — so a grab on the first touch is already locked to the beat.
          rt.scratchSeekLive(deck)
          setScratchGen((x) => x + 1)
        }
      }, (e) => {})
    }
  }
  // Seek a deck's platter to the LIVE beat phase (bar-relative 0..1) so the scratch loop starts where the music
  // actually is and stays locked to the master clock. Only meaningful while playing (a stopped deck has no grid
  // position — leave the read head at 0). perfStep is the live cumulative grid step; % 16 = position in the bar.
  rt.scratchSeekLive = (deck) => {
    if (!rt.playing) {
      return
    }
    let ps = typeof rt.perfStep === "number" ? rt.perfStep : 0
    let phase = (ps % 16) / 16
    if (phase < 0) {
      phase = phase + 1
    }
    setScratchPos(audioStore, deck, phase)
  }
  rt.scratchRate = (deck, rate) => setScratchRate(audioStore, deck, rate)
  rt.scratchSetVolume = (deck, v) => {
    setScratchVolume(audioStore, deck, v)
    if (rt.scheduleDeckMix) {
      rt.scheduleDeckMix()
    }
  }
  // True once a deck's loop is loaded — the jog uses this to load lazily on first grab (then it's cached).
  rt.scratchHasBuffer = (deck) => scratchHasBuffer(audioStore, deck)
  // Grab/release a deck's platter: duck that deck's live output while scratching so the scratch replaces it.
  rt.scratchDuck = (deck, on) => {
    setScratchDucking(audioStore, deck, on)
    if (rt.scheduleDeckMix) {
      rt.scheduleDeckMix()
    }
  }

  // ---- VINYL PERFORMANCE: cut / reverse / brake / spinback, all on the per-deck scratch platter ----
  // A per-deck SET of active "grabs" (jog/cut/rev/brake/spin). The platter stays engaged (deck ducked) while
  // ANY grab is held and disengages only when the last lets go — so you can jog with one hand and CUT with the
  // other (the transformer/chirp two-hand move) without the cut's release un-ducking the still-held jog.
  if (!rt.scratchHold) {
    rt.scratchHold = { A: {}, B: {}, C: {}, D: {} }
  }
  fn scratchHoldCount(deck) {
    let h = rt.scratchHold[deck]
    return h ? Object.keys(h).length : 0
  }
  rt.scratchEngage = (deck, gid) => {
    let h = rt.scratchHold[deck]
    if (!h) {
      return
    }
    let first = scratchHoldCount(deck) === 0
    h[gid] = true
    rt.activeScratchDeck = deck
    if (first) {
      if (rt.scratchHasBuffer && !rt.scratchHasBuffer(deck)) {
        rt.scratchLoadDeckLoop(deck)
      }
      rt.scratchDuck(deck, true)
      rt.scratchSeekLive(deck)
    }
  }
  rt.scratchRelease = (deck, gid) => {
    let h = rt.scratchHold[deck]
    if (!h) {
      return
    }
    delete h[gid]
    if (scratchHoldCount(deck) === 0) {
      setScratchRate(audioStore, deck, 0)
      setScratchCut(audioStore, deck, false)
      rt.scratchDuck(deck, false)
    }
  }
  // CUT — a sharp hold-to-mute gate on the scratch (one hand jogs, the other cuts → transformer / chirp / stab).
  // Standalone (no jog held) it spins the platter at full-speed playback so cutting it cuts the deck's own sound.
  rt.scratchCut = (deck, on) => {
    if (on === true) {
      rt.scratchEngage(deck, "cut")
      if (rt.scratchHold[deck] && !rt.scratchHold[deck].jog) {
        setScratchRate(audioStore, deck, 1)
      }
      setScratchCut(audioStore, deck, true)
    } else {
      setScratchCut(audioStore, deck, false)
      rt.scratchRelease(deck, "cut")
    }
  }
  // REVERSE / censor — hold to play the deck's loop backward; release resumes the deck forward.
  rt.scratchReverse = (deck, on) => {
    if (on === true) {
      rt.scratchEngage(deck, "rev")
      setScratchRate(audioStore, deck, -1)
    } else {
      rt.scratchRelease(deck, "rev")
    }
  }
  // BRAKE — the vinyl power-down: the platter slows from full speed to a dead stop over ~0.5 s, then stays
  // stopped while held; release brings the deck back. A hold.
  rt.scratchBrake = (deck, on) => {
    if (on === true) {
      rt.scratchEngage(deck, "brake")
      scratchSpin(audioStore, deck, 1, 0.5)
    } else {
      rt.scratchRelease(deck, "brake")
    }
  }
  // SPINBACK — the rewind zip: a fast reverse decaying to a stop over ~0.35 s, then auto-resumes the deck. Tap.
  rt.scratchSpinback = (deck) => {
    rt.scratchEngage(deck, "spin")
    scratchSpin(audioStore, deck, -10, 0.35)
    if (typeof window !== "undefined" && window.setTimeout) {
      window.setTimeout(() => {
        rt.scratchRelease(deck, "spin")
      }, 430)
    }
  }

  fn onBpmInput(e) {
    let v = Number(e.target.value)
    if (v >= 40 && v <= 240) {
      // UI-as-deck-client: emit `bpm <v>` through the one write door (no direct project mutation).
      editorRef.current.emit("bpm", v)
    }
  }
  // The −/+ deck-style nudge buttons step by `delta`. Read the LIVE bpm from the fold (updated synchronously
  // on emit) — NOT a render-time prop — so a fast burst of taps accumulates instead of all reading one stale
  // value before the rAF-coalesced re-render. Clamp + emit through the one write door.
  fn onBpmStep(delta) {
    let p = rtRef.current.project
    let cur = p && typeof p.bpm === "number" ? p.bpm : 120
    let n = Math.round(cur + Number(delta))
    if (n < 40) {
      n = 40
    }
    if (n > 240) {
      n = 240
    }
    editorRef.current.emit("bpm", n)
  }

  fn onExport() {
    let blob = projectToJson(project)
    let a = document.createElement("a")
    a.setAttribute("href", "data:application/json;charset=utf-8," + encodeURIComponent(blob))
    a.setAttribute("download", "decbard-project.json")
    a.click()
  }

  // ---- Set presets: load REPLACES the whole workspace (a set has no merge target). ----
  fn loadFullProject(p) {
    migrateProjectGenerators(p)
    // A loaded set/station replaces the workspace; re-merge the user's saved instrument presets (de-duped) so
    // they stay available regardless of which station carried them.
    loadUserInstrumentPresets(p)
    setProject(p)
    let r = rtRef.current
    r.rackPrSigCache = []
    r.rackPrNode = []
    if (audioStore.ctx) {
      resyncAllChannelBuses(p, audioStore)
      updateMixerFromProject(p, audioStore)
    }
    let em = emitProject(p)
    setTplText(em)
    setTimeout(() => {
      let r2 = rtRef.current
      if (r2.setSongText) {
        r2.setSongText(emitProject(r2.project))
      }
    }, 0)
  }
  // ---- Contextual level presets (sequence / rack / session): save the current level, load in-context.
  fn savePreset(level) {
    promptName("Save " + level + " preset as", level, (nm) => {
      let scope = level === "sequence" && project.channels[selectedCh] ? project.channels[selectedCh].id : null
      addLevelPreset(project, level, nm, emitLevel(project, level, scope))
      setProjectFromUI(project)
      // The preset list now lives in localStorage (read fresh each render), but the memoized SEQ/Session headers
      // won't re-render on this save unless we bump their gen — without this the just-saved preset never shows
      // in the load dropdown ("doesn't load").
      if (rt && rt.bumpGrid) {
        rt.bumpGrid()
      }
      bumpSessionUi()
    })
  }
  fn loadPreset(level, nm) {
    let pr = findLevelPreset(project, level, nm)
    if (!pr) {
      return
    }
    let tpl = pr.tpl
    // A sequence preset is one channel's pattern — retarget it onto the channel you're editing.
    if (level === "sequence" && project.channels[selectedCh]) {
      tpl = retargetTpl(pr.tpl, project.channels[selectedCh])
    }
    rt.applyTpl(tpl)
  }
  // Delete a saved level preset (rack / session / channel). Mirrors savePreset's re-render so the load dropdown
  // refreshes immediately.
  fn deletePreset(level, nm) {
    if (!nm || nm.length === 0) {
      return
    }
    removeLevelPreset(project, level, nm)
    setProjectFromUI(project)
    if (rt && rt.bumpGrid) {
      rt.bumpGrid()
    }
    bumpSessionUi()
  }
  rt.onDeleteTrack = (chId, nm) => {
    deletePreset("channel", nm)
  }
  // Per-TRACK presets — the whole channel (instrument + pattern), saved/loaded from each sequencer ROW's own
  // icons (level "channel"). Distinct from the top "Sequence" (pattern only, selected channel) / "Rack" bars.
  rt.onSaveTrack = (chId) => {
    if (!chId) {
      return
    }
    promptName("Save track as", String(chId), (nm) => {
      addLevelPreset(project, "channel", nm, emitLevel(project, "channel", chId))
      setProjectFromUI(project)
      if (rt && rt.bumpGrid) {
        rt.bumpGrid()
      }
    })
  }
  rt.onLoadTrack = (chId, nm) => {
    let pr = findLevelPreset(project, "channel", nm)
    if (!pr) {
      return
    }
    let ch = null
    let i = 0
    while (i < project.channels.length) {
      if (project.channels[i].id === chId) {
        ch = project.channels[i]
      }
      i = i + 1
    }
    if (!ch) {
      return
    }
    rt.applyTpl(retargetTpl(pr.tpl, ch))
  }

  fn onLoadSet(nm) {
    let sp = setPresets.get(nm)
    if (!sp) {
      return
    }
    let res = loadProjectFromTpl(sp.tpl)
    loadFullProject(res.project)
  }
  fn onSaveSet() {
    promptName("Save current workspace as station", "My Station", (nm) => {
      setPresets.save(nm, emitProject(project))
      setSetListGen((g) => g + 1)
    })
  }
  fn onDeleteSet(nm) {
    if (setPresets.remove(nm)) {
      setSetListGen((g) => g + 1)
    }
  }
  fn onExportSet(nm) {
    let text = setPresets.exportText(nm)
    if ((text === null) || typeof document === "undefined") {
      return
    }
    let blob = new Blob([text], { type: "text/plain" })
    let url = URL.createObjectURL(blob)
    let a = document.createElement("a")
    a.href = url
    a.download = "deckard-station-" + nm + ".deck"
    a.click()
    URL.revokeObjectURL(url)
  }
  fn onImportSetFile(e) {
    let f = e.target.files && e.target.files.length > 0 ? e.target.files[0] : null
    if (!f) {
      return
    }
    let reader = new FileReader()
    reader.onload = () => {
      let imp = setPresets.importText(reader.result, f.name)
      setSetListGen((g) => g + 1)
      if (imp) {
        onLoadSet(imp.name)
      }
    }
    reader.readAsText(f)
  }

  // ---- Sets (TIME-aware, per-player). Load into the free deck slots + restore arrangement; capture the
  // currently-loaded decks back into a named Set.
  fn onLoadSetLib(nm) {
    let st = setLibrary.get(nm)
    if (!st) {
      return
    }
    let res = loadSet(project, st, null)
    if (res.loaded === 0) {
      return
    }
    loadFullProject(project)
  }
  fn onDeleteSetLib(nm) {
    if (setLibrary.remove(nm)) {
      setSetLibGen((g) => g + 1)
    }
  }
  fn onSaveSetLib() {
    // Players = the decks that currently hold channels (A→D order).
    let occupied = []
    let free = freeDecks(project)
    let letters = ["A", "B", "C", "D"]
    let li = 0
    while (li < letters.length) {
      if (free.indexOf(letters[li]) < 0) {
        occupied.push(letters[li])
      }
      li = li + 1
    }
    if (occupied.length === 0) {
      // A Set captures DECK PLAYERS (the ghost-racing bundle), not the rack. With no decks loaded there's
      // nothing to capture — say so instead of silently doing nothing (this read as "Save Set is broken").
      alertModal("Save Set captures the loaded DECKS (their racks, clips + arrangement). No decks are loaded right now — load an instrument onto a deck first, or use \"Save Station\" to save the whole workspace (instruments, sequences and all).", "Nothing to save")
      return
    }
    promptName("Save loaded decks as a Set (" + String(occupied.length) + " player" + (occupied.length === 1 ? "" : "s") + ")", "My Set", (nm) => {
      setLibrary.save(nm, emitSet(project, occupied), occupied.length)
      setSetLibGen((g) => g + 1)
    })
  }
  fn onImportSetLibFile(e) {
    let f = e.target.files && e.target.files.length > 0 ? e.target.files[0] : null
    if (!f) {
      return
    }
    let reader = new FileReader()
    reader.onload = () => {
      let imp = setLibrary.importText(reader.result, f.name)
      setSetLibGen((g) => g + 1)
      if (imp) {
        onLoadSetLib(imp.name)
      }
    }
    reader.readAsText(f)
  }

  fn onImport() {
    promptName("Paste full project JSON", "", (s) => {
      if (!s || s.length <= 2) {
        return
      }
      try {
        let p = projectFromJson(s)
        migrateProjectGenerators(p)
        loadUserInstrumentPresets(p)
        setProject(p)
        let r = rtRef.current
        r.prSkipRedrawSig = null
        r.rackPrSigCache = []
        r.rackPrNode = []
        let em = emitProject(p)
        setTplText(em)
        setTimeout(() => {
          let r2 = rtRef.current
          let e2 = emitProject(r2.project)
          if (r2.setSongText) {
            r2.setSongText(e2)
          }
          setTplText(e2)
        }, 0)
      } catch (e) {
        alertModal("That doesn't look like valid project JSON.", "Invalid JSON")
      }
    }, { multiline: true, okLabel: "Import" })
  }

  // Channel mixer edits — emit one `mix` statement through the write door (audio + render follow on
  // stream-advance). No direct project mutation, no manual updateMixerFromProject.
  fn onTrim(idx, e) {
    rt.emit("track/" + project.channels[idx].id + "/mix/gain", Number(e.target.value) / 100)
  }

  fn onTrimCommit() {}

  fn onEq(idx, key, e) {
    rt.emit("track/" + project.channels[idx].id + "/mix/eq_" + key, Number(e.target.value))
  }

  fn onEqCommit() {}

  fn onPan(idx, e) {
    rt.emit("track/" + project.channels[idx].id + "/mix/pan", Number(e.target.value) / 100)
  }

  fn onPanCommit() {}

  ensureActorMixerEntries(project)
  ensureProjectSession(project)

  let seqBarCount = Math.floor(Number(project.session.sceneCount))
  if (seqBarCount < 1 || seqBarCount !== seqBarCount) {
    seqBarCount = 4
  }
  // editingScene = pattern loaded in the rack (LOAD highlight). liveScene = pattern currently armed
  // as the live output / P0 (LAUNCH highlight). queuedScene = a launch waiting for the next bar.
  let editingScene = rt.editingScene !== null ? Math.floor(Number(rt.editingScene)) : null
  // While a song plays, the live pattern is the song's current scene (per-track overrides can make the
  // armed clips a hybrid that wouldn't match any single scene); otherwise infer it from the armed clips.
  let liveScene = playing && playMode === "song" && (rt.songScene !== null)
    ? Math.floor(Number(rt.songScene))
    : sessionPlayingSceneIndex(project, rt)
  let queuedScene = rt.sessionQueuedScene
  let queuePending = rt.sessionQueuePending === true && (queuedScene !== null)
  let seqBarPx = launchQuant >= 1 ? Math.floor(launchQuant) : coDjStepsPerBar()
  let seqDropSteps = null
  if (playing && playMode === "song") {
    let nt = rt.transportNextTick
    if (nt !== null) {
      seqDropSteps = coDjStepsUntilBarBoundary(nt, seqBarPx)
    }
  }
  let patternBank = {
    count: seqBarCount,
    editingScene: editingScene,
    liveScene: liveScene,
    queuedScene: queuedScene,
    queuePending: queuePending,
    dropSteps: seqDropSteps,
    rev: seqPromoteUi,
    playing: playing,
    playMode: playMode,
    onLoad: onPatternLoad,
    onLoadBar: onPatternLoadBar,
    onSave: onPatternSave,
    onSaveBar: onPatternSaveBar,
    onLaunch: onPatternLaunch,
    viewBar: rt.gridViewBar !== null ? Math.floor(Number(rt.gridViewBar)) : 0,
    bars: gridBarsForProject(project)
  }

  // One view — no tab. Sequencer + session on top, then the selected channel's instrument rack boxes.
  // Load/save now lives in each panel's header (the common PanelHeader), right-aligned — no extra strip.
  // Per-track (per-channel) load/save now lives on each sequencer ROW (onSaveTrack/onLoadTrack); the old top
  // "Sequence" bar was the duplicate — removed. "Rack" (the whole rack of channels) stays, it's not per-track.
  let seqHeaderRight = [
    PresetBar("Rack", levelPresetList(project, "rack"), (n) => loadPreset("rack", n), () => savePreset("rack"), "", (n) => deletePreset("rack", n))
  ]
  let sessionHeaderRight = PresetBar("Session", levelPresetList(project, "session"), (n) => loadPreset("session", n), () => savePreset("session"), "", (n) => deletePreset("session", n))
  // Recordings = the stream Sets (a recorded deck tape) — listed in the Playlist panel for replay.
  let recordingItems = []
  let allLibSets = setLibrary.list()
  let rli = 0
  while (rli < allLibSets.length) {
    if (isStreamSet(allLibSets[rli].tpl)) {
      recordingItems.push(allLibSets[rli])
    }
    rli = rli + 1
  }
  let playlistProps = {
    recording: rt.tplRecording === true,
    playing: playing,
    recordings: recordingItems,
    onToggleRec: onToggleRec,
    onNewTake: onNewTake,
    onSaveRecording: onSaveRecording,
    onLoadReplay: onLoadReplay,
    onDeleteReplay: onDeleteSetLib,
    onStop: onStop,
    channelsRev: channelsRev,
    rebuildTplEnergy: rebuildTplEnergy
  }
  let seqSession = (
    <div class="seq-session-wrap">
      <div class="seq-session-split">
        <div class="seq-split-main">
          {h(StepGridMemo, { project: project, selectedCh: selectedCh, setProjectFromUI: setProjectFromUI, setSelectedCh: setSelectedCh, rt: rt, headerRight: seqHeaderRight, gridGen: gridGen, channelsRev: channelsRev, seqPromoteUi: seqPromoteUi, activeDeck: activeDeck })}
        </div>
        <div class="seq-split-session">
          {h(SessionViewMemo, { project: project, rt: rt, setProjectFromUI: setProjectFromUI, playing: playing, bumpSessionUi: bumpSessionUi, patternBank: patternBank, headerRight: sessionHeaderRight, sessionUiGen: sessionUiGen, seqPromoteUi: seqPromoteUi, sessionRev: sessionRev, channelsRev: channelsRev, activeDeck: activeDeck })}
        </div>
      </div>
    </div>
  )

  // Set-preset picker options (built-in Default first, then saved user sets). setListGen forces refresh.
  // IkSelect wants { value, label } objects (NOT <option> vnodes); `deletable: false` hides the ✕ on factory items.
  let setItems = setPresets.list()
  let setOpts = []
  let spi = 0
  while (spi < setItems.length) {
    let it = setItems[spi]
    setOpts.push({ value: it.name, label: it.name + (it.factory ? " (default)" : ""), deletable: !it.factory })
    spi = spi + 1
  }
  let setListGenKey = setListGen

  // Set library picker (TIME-aware, per-player bundles). Loading fills the FREE deck slots with the Set's
  // players + restores its arrangement. Disabled when no slot is free (all 4 decks occupied = listen-only).
  let setLibItems = setLibrary.list()
  let setLibOpts = []
  let sli = 0
  while (sli < setLibItems.length) {
    let li = setLibItems[sli]
    // Recorded stream Sets live in the Playlist panel (replay), not the deck-load dropdown.
    if (!isStreamSet(li.tpl)) {
      let tag = li.factory ? " (rack)" : " · " + String(li.players) + "p"
      setLibOpts.push({ value: li.name, label: li.name + tag, deletable: !li.factory })
    }
    sli = sli + 1
  }
  let freeSlotCount = freeDecks(project).length
  let setLibGenKey = setLibGen

  // Master bus state for the bottom bar's COMPRESSOR / REVERB_BUS chips (toggles + live readout).
  let mmx = project.masterMixer ? project.masterMixer : { compEnabled: true, reverbEnabled: true }
  let compOn = mmx.compEnabled !== false
  let reverbOn = mmx.reverbEnabled !== false
  let revSends = 0
  let rci = 0
  while (rci < project.channels.length) {
    if ((project.channels[rci].reverbSend !== null) && project.channels[rci].reverbSend > 0) {
      revSends = revSends + 1
    }
    rci = rci + 1
  }

  // One deck nav block: the title row spans the full width on top; the jog (+ vinyl), EQ knobs and volume
  // fader sit in a single centered, tightly-gapped row below it. (Replaces the old platter-card | strip split
  // where the jog was centered in a wide flex column far from the EQ.)
  fn renderDeckNav(letter) {
    let lc = String(letter).toLowerCase()
    let hasContent = deckEntries(project, letter).length > 0
    return (
      <div class={"deck-nav-btn deck-" + lc + (activeDeck === letter ? " deck-active" : "")} onmousedown={(e) => deckBgClick(e, letter, setActiveDeck)} key={"decknav-" + letter}>
        <div class="deck-nav-title-row">
          <span class="deck-nav-dot"></span>
          <span class="deck-nav-text">{"DECK " + letter}</span>
          {renderDeckPips(project, letter)}
        </div>
        <div class="deck-nav-controls-row">
          {hasContent ? (
            <div class="deck-nav-controls">
              {DeckJog(letter, rt)}
              {VinylRow(letter, rt)}
            </div>
          ) : (
            <div class="deck-nav-empty">{"(empty)"}</div>
          )}
          {DeckChannelStrip(project, letter, setProjectFromUI, touchMixer, rt)}
        </div>
      </div>
    )
  }

  return <div class="daw-root">
    <header class="daw-header">
      <div class="logo-col">
        <h1 class="logo">{"Deckard"}</h1>
        <div class="made-by-credit">
          {"by "}
          <a href="https://space.la" target="_blank" rel="noopener noreferrer">space.la</a>
          <span class="made-by-sep">{" · "}</span>
          <a href="/docs/" class="docs-link">{"Docs"}</a>
        </div>
      </div>
      {TransportBar(
        project.bpm,
        playing,
        playMode,
        previewing,
        onPreview,
        onPlayStop,
        (m) => selectPlayMode(m),
        onBpmInput,
        onBpmStep,
        onExport,
        onImport,
        project.transportMainDeck !== "local" ? "live" : "local",
        onDeckMain,
        launchQuant,
        (q) => setLaunchQuant(q),
        () => rt.undo(),
        () => rt.redo(),
        rt.canUndo ? rt.canUndo() : false,
        rt.canRedo ? rt.canRedo() : false,
        coDjIsFollower(rt)
      )}
      <div class="set-presets" key={"sp-" + String(setListGenKey)}>
        <button type="button" class="songs-open-btn" title="Browse the song library — load a full song (kit + patterns) onto any deck" onclick={() => setSongBrowserOpen(true)}>{"♫"}</button>
        <span class="transport-div" />
        {IkSelect({
          class: "set-select",
          value: "",
          placeholder: "— load station —",
          title: "Station presets — full workspace snapshots (instruments, sequences and all)",
          options: setOpts,
          onChange: (v) => {
            if (v && v.length > 0) {
              onLoadSet(v)
            }
          },
          onDelete: (v) => {
            if (v && v.length > 0) {
              onDeleteSet(v)
            }
          }
        })}
        <button type="button" class="set-btn set-save" onclick={onSaveSet} title="Save the whole workspace as a named station">{"⤓"}</button>
        <label class="set-btn set-import" title="Import a .deck station file">{"⤒"}
          <input type="file" accept=".deck,.tpl,.txt" style={{ display: "none" }} onchange={onImportSetFile} />
        </label>
      </div>
      <div class="set-presets set-lib" key={"sl-" + String(setLibGenKey)}>
        {IkSelect({
          class: "set-select",
          value: "",
          placeholder: "— load set —",
          title: freeSlotCount === 0 ? "All 4 decks occupied — free a deck to load a Set (or drop one onto a deck from its picker)." : "Load a Set into the " + String(freeSlotCount) + " free deck slot" + (freeSlotCount === 1 ? "" : "s"),
          options: setLibOpts,
          onChange: (v) => {
            if (v && v.length > 0) {
              onLoadSetLib(v)
            }
          },
          onDelete: (v) => {
            if (v && v.length > 0) {
              onDeleteSetLib(v)
            }
          }
        })}
        <button type="button" class="set-btn set-save" onclick={onSaveSetLib} title="Capture the loaded decks (their racks, clips + arrangement) as a named Set">{"⤓"}</button>
        <label class="set-btn set-import" title="Import a .deck Set file">{"⤒"}
          <input type="file" accept=".deck,.tpl,.txt" style={{ display: "none" }} onchange={onImportSetLibFile} />
        </label>
      </div>
      <button
        type="button"
        class="daw-fullscreen-btn"
        title="Toggle fullscreen"
        onclick={() => {
          let d = globalThis.document
          if (d !== null) {
            if (d.fullscreenElement) {
              if (d.exitFullscreen) { d.exitFullscreen() }
            } else if (d.documentElement && d.documentElement.requestFullscreen) {
              d.documentElement.requestFullscreen()
            }
          }
        }}
      >
        <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
          <path d="M8 3H5a2 2 0 0 0-2 2v3m18 0V5a2 2 0 0 0-2-2h-3m0 18h3a2 2 0 0 0 2-2v-3M3 16v3a2 2 0 0 0 2 2h3" />
        </svg>
      </button>
    </header>
    <div class="daw-app-layout">
      <aside class="daw-sidebar-left">
        {renderDeckNav("A")}
        {renderDeckNav("B")}
        {renderDeckNav("C")}
        {renderDeckNav("D")}
      </aside>
      <div class="daw-main-area">
        <div class="daw-body daw-body-stack">
          <div class="daw-main-stack">
            {h(InstrumentStackMemo, { project: project, selectedCh: selectedCh, setProjectFromUI: setProjectFromUI, tplMirrorFlush: tplMirrorFlush, rt: rt, channelsRev: channelsRev, activeDeck: activeDeck })}
            {seqSession}
          </div>
        </div>

      </div>
      <aside class="daw-sidebar-right">
        <div class="daw-bottom-col daw-bottom-codj">{CoDjPanel(project, setProject, tplMirrorFlush, rt)}</div>
        <div class="daw-bottom-col daw-tpl-dock">{CodeDebugView(project, setProject, tplText, setTplText, rt, true)}</div>
        <div class="daw-bottom-col">
          {h(DeckMixerMemo, { project: project, setProjectFromUI: setProjectFromUI, touchMixer: touchMixer, rt: rt, xfadeX: xfadeX, xfadeY: xfadeY, channelsRev: channelsRev, deckMixRev: deckMixRev, playing: playing })}
        </div>
      </aside>
    </div>
    <footer class="daw-foot daw-foot-pinned">
      <div class="seq-arrange">
        {h(PlaylistMemo, { project: project, rt: rt, props: playlistProps, timelineGen: timelineGen, setLibGen: setLibGen, channelsRev: channelsRev })}
      </div>
      <div class="daw-foot-master">
        <button
          type="button"
          class={compOn ? "master-chip master-chip-on" : "master-chip master-chip-off"}
          title={"COMPRESSOR — master glue compressor; click to bypass. Readout = live gain reduction (dB)."}
          onmousedown={(e) => e.stopPropagation()}
          onclick={() => { if (rt && rt.emit) { rt.emit("master/comp", !compOn) } }}
        >
          <span class="master-comp-gr">{compOn ? "0.0dB" : "BYPASS"}</span>
        </button>
        <button
          type="button"
          class={reverbOn ? "master-chip master-chip-on" : "master-chip master-chip-off"}
          title={"REVERB_BUS — shared reverb send bus; click to mute. Readout = channels currently sending."}
          onmousedown={(e) => e.stopPropagation()}
          onclick={() => { if (rt && rt.emit) { rt.emit("master/reverb", !reverbOn) } }}
        >
          <span class="master-rev-state">{reverbOn ? ("ON · " + String(revSends) + " send" + (revSends === 1 ? "" : "s")) : "OFF"}</span>
        </button>
        {AudioRackPanel(audioStore)}
        {MidiPanel(midiRef.current, project, midiGen)}
      </div>
    </footer>
    {songBrowserOpen ? SongBrowser(project, rt, () => setSongBrowserOpen(false), songQuery, setSongQuery) : null}
  </div>
}