@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/audio/preview.ts

@@ -12,17 +12,48 @@
 // the fade maths is exactly how preview stops matching export, and the F3-A
 // review caught that divergence in the wild once already.
 //
-// There are no gain TRACKS here. Doc3D has blocks, not tracks, and no block
-// writes a clip's gain — so `sampledGain` is never supplied and the envelope
-// falls back to the clip's static gain, which is what the shot exporter mixes.
+// That includes the DE-CLICK: the engine ramps every clip edge the author did
+// not fade, so nothing here opens or closes a voice by hand. A voice scheduled
+// from the middle of a clip gets the same ramp for the same reason — it is a
+// transport artefact, and the engine is where that is decided.
 //
 // ── TIME MODEL ──────────────────────────────────────────────────────────
 //
 // The chrome's rAF transport is the authority; this anchors frame→audio-time as
-// t(f) = anchorTime + framesToSeconds(f - anchor, fps) per (re)schedule. Both
-// clocks are wall-clock and drift between them is NOT corrected: a reschedule
-// (scrub, doc edit, unmute) re-anchors. Only edges, discontinuities and doc
-// identity changes do work; the per-frame path just records the snapshot.
+// t(f) = anchorTime + framesToSeconds(f - anchor, fps), ONCE per session. The
+// anchor pair is STORED, so everything that joins the session later — a late
+// decode, a clip the author just added — lands on the same timeline as the
+// voices already playing rather than on a fresh reading of two clocks taken a
+// moment apart.
+//
+// The play edge's session anchors on the TRANSPORT'S ORIGIN (`playOrigin`,
+// bridge v51): the frame the run started on, at the audio time of the wall
+// instant it started. The picture clock (Header.tsx) counts from that same
+// instant, so picture and sound start together rather than a React commit
+// apart. A later session of the same run (an unmute, a re-anchor) takes its
+// own reading, as the picture does after a rate or window change.
+//
+// Drift between the rAF clock and the AudioContext clock is CHECKED rather than
+// assumed away: when the picture's frame and the audio clock disagree by more
+// than a frame, the session re-anchors. A scrub and a loop wrap are that
+// disagreement in the large. A main-thread stall is NOT: the transport derives
+// its frame from absolute wall time (Header.tsx), so after a stall the picture
+// catches up to where the audio already is and the two still agree. It is
+// checked only when the FRAME moved: a notification that moved anything else
+// says nothing about the picture's clock, and the audio has run on since the
+// last frame by up to a frame of its own. The audio may also be one refresh
+// further AHEAD (`DRIFT_REFRESH_S`): the transport picks a frame for the start
+// of the refresh it draws on (rAF's timestamp), and this reads its clock later
+// in that same tick.
+//
+// ── DECODED AHEAD ───────────────────────────────────────────────────────
+//
+// Once the stage has presented the open document whole (its ready edge), the
+// heard clips decode one at a time, nearest the playhead first, at low fetch
+// priority, into the cache the session schedules from. A decode needs no
+// realtime context (`AudioPreviewDeps.decode`), so none exists before the
+// first press: a queued Play's ARM creates or resumes it inside the press,
+// and the transport starts later by itself.
 //
 // ── AND IT MOUNTS FROM THE CHROME ───────────────────────────────────────
 //
@@ -33,10 +64,35 @@
 //
 // No DOM lib types: every Web Audio surface is a minimal structural *Like type
 // and every effect is injected, so the jsdom tests drive a hand-rolled fake.
-import { audioClipWindow, audioEnvelopePoints, audioSourceTimeAt, framesToSeconds } from "@dailies-studio/engine";
-import type { AudioClip, Rational } from "@dailies-studio/engine";
-import { docDurationFrames } from "@dailies-studio/shot/doc";
-import type { AudioClipRef, Doc3D } from "@dailies-studio/shot/doc";
+import {
+  AUDIO_EDGE_RAMP_SAMPLES,
+  MIX_SAMPLE_RATE,
+  audioClipWindow,
+  audioEnvelopePoints,
+  audioSourceTimeAt,
+  framesToSeconds,
+  panGains,
+  wirePan,
+} from "@dailies-studio/engine";
+import type {
+  PanContextLike as EnginePanContextLike,
+  PanStage as EnginePanStage,
+  Rational,
+} from "@dailies-studio/engine";
+import {
+  asEngineClip,
+  audioAnalysisFileName,
+  audioGainSampler,
+  audioPlayPath,
+  audioTracksOf,
+  derivedGainTracks,
+  docDurationFrames,
+  duckSourceAssets,
+  isAudioFxFileName,
+  masterAudioClips,
+  sceneWindows,
+} from "@dailies-studio/shot/doc";
+import type { AudioAnalysis, AudioClipRef, Doc3D, MasterAudioClip, ShotTrack } from "@dailies-studio/shot/doc";
 
 // --- minimal structural Web Audio surface (fakes stay trivial) ---------------
 
@@ -44,12 +100,30 @@ export interface AudioParamLike {
   value: number;
   setValueAtTime(value: number, time: number): unknown;
   linearRampToValueAtTime(value: number, time: number): unknown;
+  /** Needed to re-automate a voice that is already sounding: an edit has to
+   *  drop the future the old envelope scheduled before it writes its own. */
+  cancelScheduledValues(time: number): unknown;
 }
 
 export interface GainNodeLike {
   readonly gain: AudioParamLike;
-  connect(destination: unknown): unknown;
-  disconnect(): void;
+  /** `output`/`input` pick a channel on a splitter or merger (the pan stage). */
+  connect(destination: unknown, output?: number, input?: number): unknown;
+  /** Written only by the pan stage, which needs a mono source UPMIXED before
+   *  its splitter. Optional so the fakes that never pan stay as they are. */
+  channelCount?: number;
+  channelCountMode?: string;
+  channelInterpretation?: string;
+  /**
+   * The SELECTIVE form is optional here and required by the meter.
+   *
+   * A tap hangs off the master node and must unwire only itself
+   * (`meter.ts`'s `release`): calling the no-argument form on the monitored
+   * node would drop its real output as well, which is the whole mix. Declared
+   * as an optional parameter rather than a second method so every existing
+   * fake — each of which spells `disconnect(): void` — still satisfies it.
+   */
+  disconnect(destination?: unknown): void;
 }
 
 export interface AudioBufferLike {
@@ -62,11 +136,37 @@ export interface AudioBufferSourceNodeLike {
   start(when?: number, offset?: number, duration?: number): void;
   stop(when?: number): void;
   disconnect(): void;
+  /** Set so a voice released with a ramp disconnects ITSELF once the stop it
+   *  scheduled has actually happened. Disconnecting earlier would cut the ramp
+   *  off, which is the click the ramp exists to remove. */
+  onended: (() => void) | null;
+}
+
+/** A ChannelSplitter or ChannelMerger, as far as the pan stage wires one. */
+export interface ChannelNodeLike {
+  connect(destination: unknown, output?: number, input?: number): unknown;
+  disconnect(): void;
 }
 
-export interface AudioContextLike {
+/**
+ * The part of a context the pan stage (engine's `wirePan`) needs. The splitter
+ * pair is OPTIONAL so a jsdom fake that never pans stays trivial; the offline
+ * mix refuses a panned clip without it rather than mixing it centred.
+ */
+export type PanContextLike = EnginePanContextLike<GainNodeLike, ChannelNodeLike>;
+
+/** One voice's pan stage, as this lane's node types. */
+export type PanStage = EnginePanStage<GainNodeLike, ChannelNodeLike>;
+
+export interface AudioContextLike extends PanContextLike {
   readonly currentTime: number;
   readonly destination: unknown;
+  /** The device's rate. Nothing in the scheduler reads it — the envelope is
+   *  the engine's and works in seconds — but the meter's worklet derives its
+   *  own `dt` from it, and `MeterContextLike` (meter.ts) is satisfied by
+   *  exactly this field. Declaring it here is what lets the monitor hand a
+   *  real context straight to `attachMeter` with no cast. */
+  readonly sampleRate: number;
   createGain(): GainNodeLike;
   createBufferSource(): AudioBufferSourceNodeLike;
   resume?(): unknown;
@@ -74,13 +174,25 @@ export interface AudioContextLike {
 }
 
 export interface AudioPreviewDeps {
-  /** Called lazily on the first audible play edge — a user gesture, so the
-   *  real context is born unblocked by autoplay policy. */
+  /** Called lazily inside the first press that could sound: a queued Play's
+   *  arm, or a play edge that starts at once. Both run in the press's own call
+   *  stack, so the real context is born unblocked by autoplay policy. */
   createContext(): AudioContextLike;
-  fetchBytes(url: string): Promise<ArrayBuffer>;
-  decode(ctx: AudioContextLike, bytes: ArrayBuffer): Promise<AudioBufferLike>;
+  /** `"low"` for a decode ahead, which must not compete with the stage's own
+   *  loads; absent for a play edge's, which the author is waiting on. */
+  fetchBytes(url: string, priority?: "low"): Promise<ArrayBuffer>;
+  /**
+   * Decode with NO realtime context, so a clip can decode before the first
+   * press. The browser's is one `OfflineAudioContext(2, 1, MIX_SAMPLE_RATE)`,
+   * the export mix's rate (audio/index.tsx); a buffer plays on any context,
+   * resampled to its rate.
+   */
+  decode(bytes: ArrayBuffer): Promise<AudioBufferLike>;
   /** Audio-clock override for tests; defaults to ctx.currentTime. */
   now?(): number;
+  /** Wall-clock override for tests; defaults to `performance.now()`, the clock
+   *  `TransportSnapshot.origin.at` is read on. */
+  wallNow?(): number;
 }
 
 /** The transport truth the host reads off the store on every change. */
@@ -88,6 +200,66 @@ export interface TransportSnapshot {
   playing: boolean;
   frame: number;
   doc: Doc3D | null;
+  /**
+   * Whether the MASTER timeline is what is playing, AT ITS OWN SPEED.
+   *
+   * Two things make it false, and they are one thing twice: a second clock the
+   * picture's cannot agree with. `transportAudible` in state/types.ts is the
+   * one place both are decided, and `audio/index.tsx` is its only caller — this
+   * scheduler is handed the answer rather than forming a second opinion.
+   *
+   * A COMPONENT CONTEXT drives a definition's own clock and `frame` does not
+   * move at all. Without this the preview heard a play edge, started the whole
+   * document's soundtrack from a static master frame, and played it over a
+   * definition looping on its own — with nothing to re-anchor it, because the
+   * frame it was watching never changed.
+   *
+   * ANY SHUTTLE RATE BUT 1 IS SILENT, and that is a refusal rather than a
+   * missing feature. Reverse needs reversed buffers and a pitch-preserved 2x
+   * needs a time stretcher; each is a second scheduler running its own
+   * arithmetic beside the picture's, and the first time the two round
+   * differently the author hears one frame while watching another. Playing the
+   * buffers at `playbackRate` instead would be worse still: it is a pitch shift
+   * the export will never make, so the preview would be wrong about what the
+   * film sounds like — the one thing this lane refuses above all.
+   */
+  audible: boolean;
+  /** The shot the author has ENTERED, whose window the transport loops inside;
+   *  null on the master timeline. A voice must not outlive that window. */
+  scene: string | null;
+  /**
+   * The tracks this tab SOLOS, or absent/empty for the whole mix.
+   *
+   * Monitoring, not document state: it lives in the editor beside
+   * `previewMuted`, only `reconcile` reads it, and neither export mix ever
+   * sees it. A soloed tab hears a partial mix, which the mixer shows by dimming
+   * every track that is not soloed.
+   */
+  solo?: readonly string[];
+  /**
+   * A QUEUED PLAY waits (`playIntent`, bridge v51): the press has happened and
+   * the transport starts later, by itself, outside it. So the ARM is where the
+   * realtime context is created, or resumed after the page suspended it.
+   */
+  armed?: boolean;
+  /**
+   * WHERE AND WHEN THE TRANSPORT STARTED (`playOrigin`): its frame, and the
+   * `performance.now()` of the start. The play edge that brings a new one
+   * anchors its session on it, as the picture clock does.
+   */
+  origin?: TransportOrigin | null;
+  /**
+   * The stage has PRESENTED the open subject whole: one is attached and owes
+   * no presentation (`stageBusy` false). Its rising edge is the ready edge the
+   * decode ahead waits for.
+   */
+  presented?: boolean;
+}
+
+/** `ShotEditorState.playOrigin`, as the scheduler reads it. */
+export interface TransportOrigin {
+  readonly frame: number;
+  readonly at: number;
 }
 
 export interface AudioPreview {
@@ -107,47 +279,245 @@ export interface AudioPreview {
   dispose(): void;
 }
 
-/** A frame jump beyond this (or any decrease) while playing is a scrub. */
-export const SCRUB_JUMP_FRAMES = 10;
+// ── THE MONITOR TAP: WHERE A METER FACE FINDS THE GRAPH ────────────────────
+//
+// `audio/meter.ts` can measure any gain node, and there was no way for a
+// component to GET one. The preview owns the only audio graph this chrome
+// builds, it builds it lazily inside `ensureContext` on the first press (an
+// arm or a play edge), and the preview object itself lives inside
+// `AudioPreviewBridge`'s effect, which renders null and is reachable from
+// nothing. So the one node worth metering — the master gain every voice is
+// summed into, which is exactly what the author is hearing — is published
+// here and subscribed to by the face.
+//
+// A MODULE-LEVEL SLOT AND NOT THE SHOT STORE, for `meterStore.ts`'s reason one
+// level up: this is a live Web Audio node, it is not document state, it must
+// never enter the undo history, and a face holding it through the store would
+// pin the graph across every notification. It is also not the meter store,
+// which carries READINGS (three floats at ~60 Hz) and knows nothing about
+// nodes.
+//
+// IDENTITY IS THE CONTRACT, the same one `meterStore.readMeter` keeps:
+// `readMonitor` is a `useSyncExternalStore` getter called during render, so it
+// returns the SAME object until the graph actually changes and allocates
+// nothing. Null until the first press, which is why `useMeterTap` takes a
+// null source and starts measuring when one arrives.
+//
+// ponytail: ONE slot for the page, not one per preview. Exactly one
+// `AudioPreviewBridge` mounts in this chrome and it owns the page's only
+// AudioContext; a second preview would overwrite the first's publication.
+// `dispose` therefore clears only its OWN graph, so the surviving one keeps
+// its meter rather than both going dark. Key the slot by preview instance if a
+// second bridge is ever mounted.
+
+/** The channel a master meter reads, spelled once so the tap and the face
+ *  cannot disagree about which name the readings arrive under. */
+export const MASTER_METER_KEY = "master";
+
+/** What a face needs to hang a tap: the context to compile the worklet into,
+ *  and the node to measure. */
+export interface MonitorGraph {
+  ctx: AudioContextLike;
+  node: GainNodeLike;
+  /**
+   * One unity BUS per audio track, keyed by track id, every voice on that
+   * track summed into it before the master. A tap on it reads that track
+   * alone (Sound mode's channel strips). Unity gain and a plain connect, so
+   * the master sum is the same with or without the buses. A NEW map whenever
+   * a bus is added, so a face's `useSyncExternalStore` sees the change.
+   */
+  tracks: ReadonlyMap<string, GainNodeLike>;
+}
+
+let monitor: MonitorGraph | null = null;
+const monitorListeners = new Set<() => void>();
+
+/** The live monitor graph, or null before the first press. */
+export function readMonitor(): MonitorGraph | null {
+  return monitor;
+}
+
+/** Subscribe to the graph appearing or going away. */
+export function subscribeMonitor(listener: () => void): () => void {
+  monitorListeners.add(listener);
+  return () => {
+    monitorListeners.delete(listener);
+  };
+}
+
+/** A listener that THROWS must not stop the others hearing about it — the
+ *  posture `publishMeter` already takes, and for the same reason: a meter face
+ *  is decoration and may not take the preview down with it. */
+function publishMonitor(next: MonitorGraph | null): void {
+  if (next === monitor) return;
+  monitor = next;
+  for (const listener of [...monitorListeners]) {
+    try {
+      listener();
+    } catch {
+      // See above.
+    }
+  }
+}
+
+/** Test hook, and the one way to empty the slot without a real dispose. */
+export function resetMonitor(): void {
+  publishMonitor(null);
+}
+
+/**
+ * How far the picture and the audio clock may disagree before the session
+ * re-anchors, in frames.
+ *
+ * ponytail: one frame, the smallest disagreement that is not rounding. Raise it
+ * if a loaded machine is measured re-anchoring on its own.
+ */
+export const DRIFT_FRAMES = 1;
+
+/**
+ * How much further the audio clock may run AHEAD of the picture than behind
+ * it before the session re-anchors, in seconds: one refresh.
+ *
+ * The transport picks each frame for the start of the refresh it draws on
+ * (rAF's timestamp, Header.tsx), its boundaries placed up to half a refresh
+ * off the origin, and this reads the audio clock later in that same tick. So
+ * a picture that agrees with the audio begins up to a refresh before the
+ * reading, besides the frame it has run into. With a frame alone allowed, a
+ * 60 fps run whose base sat late would re-anchor at nearly every frame.
+ *
+ * ponytail: a 60 Hz refresh assumed, as renderScaleController.ts does; a
+ * slower display's late tick reads as drift. Hand the measured refresh over
+ * if one ever must not.
+ */
+export const DRIFT_REFRESH_S = 1 / 60;
+
+/** The engine's de-click, in seconds — the release a voice fades over when the
+ *  TRANSPORT stops it, which is not something the envelope can express. */
+const RAMP_SECONDS = AUDIO_EDGE_RAMP_SAMPLES / MIX_SAMPLE_RATE;
 
 type CacheEntry =
   | { status: "pending" }
   | { status: "ready"; buffer: AudioBufferLike }
   | { status: "failed" };
 
+/** The same three states for an analysis sidecar. */
+type AnalysisEntry =
+  | { status: "pending" }
+  | { status: "ready"; analysis: AudioAnalysis }
+  | { status: "failed" };
+
 interface Voice {
   source: AudioBufferSourceNodeLike;
   gain: GainNodeLike;
+  /** The pan stage, or null on a context with no splitter pair. */
+  pan: PanStage | null;
+  /** What would make this voice the WRONG SOURCE WINDOW — a move, a trim, a
+   *  slip, a different asset. Changing it means a new node. */
+  timing: string;
+  /** The file it plays (`audioPlayPath`): the asset, or its processed file. */
+  path: string;
+  /** What is only a LEVEL — gain, fades, the automation track. Changing it is
+   *  re-automated on the node that is already sounding. */
+  shape: string;
 }
 
-/** `AudioClipRef` as engine's `AudioClip`: the same fields under the one name
- *  that differs, with this lane's absent-means-default filled in. */
-function asEngineClip(clip: AudioClipRef): AudioClip {
-  return {
-    id: clip.id,
-    name: clip.id,
-    asset: clip.asset,
-    at: clip.frame,
-    offsetFrames: clip.offsetFrames ?? 0,
-    durationFrames: clip.durationFrames,
-    gain: clip.gain ?? 1,
-    fadeInFrames: clip.fadeInFrames ?? 0,
-    fadeOutFrames: clip.fadeOutFrames ?? 0,
-    ...(clip.muted === undefined ? {} : { muted: clip.muted }),
-  };
+/** One audible session: the anchor pair every voice in it shares, the window
+ *  its voices end at, and the voices themselves. */
+interface Session {
+  anchorFrame: number;
+  anchorTime: number;
+  endFrame: number;
+  voices: Map<string, Voice>;
+}
+
+/** Re-exported from the data plane, where `dailies check` also needs it. One
+ *  widening, not two, and now not three. */
+export { asEngineClip };
+
+/** The frame a voice may sound until: the entered shot's window end, or the
+ *  whole document's. A voice scheduled to the document end while the transport
+ *  loops inside one shot would keep playing past the loop point. */
+function endFrameOf(doc: Doc3D, scene: string | null): number {
+  if (scene === null) return docDurationFrames(doc);
+  return sceneWindows(doc).find((w) => w.id === scene)?.end ?? docDurationFrames(doc);
+}
+
+/** What makes a voice the wrong SOURCE WINDOW. Asset PATH, not id: an id is
+ *  only unique within its own document. */
+/** The file a `timingOf` key names. */
+const playPathOf = (timing: string): string => (JSON.parse(timing) as unknown[])[2] as string;
+
+function timingOf(clip: AudioClipRef, assetPath: string | undefined, trackId: string): string {
+  return JSON.stringify([
+    // The TRACK too: a voice is wired to its track's bus, and a clip moved to
+    // another track has to sum into the other bus or that strip's meter lies.
+    trackId,
+    clip.frame,
+    assetPath,
+    clip.offsetFrames ?? 0,
+    clip.durationFrames,
+    clip.muted === true,
+  ]);
+}
+
+/**
+ * What is only a level, and can be re-automated in place.
+ *
+ * Takes the RESOLVED track rather than reading `clip.gainTrack`, because a
+ * ducked bed's level changes when nothing on the bed does: the voice above it
+ * moved, or its analysis just landed. Hashing the authored field would leave
+ * the old envelope sounding with no edit to notice.
+ */
+function shapeOf(clip: AudioClipRef, track: ShotTrack | undefined, pan: number): string {
+  return JSON.stringify([
+    clip.gain ?? 1,
+    clip.fadeInFrames ?? 0,
+    clip.fadeOutFrames ?? 0,
+    track ?? null,
+    // PAN IS A LEVEL, so a pan-knob drag re-automates the two side gains of
+    // the voice already sounding instead of restarting it.
+    pan,
+  ]);
+}
+
+/** Whether a flattened clip is heard in this tab: not muted (the track's mute
+ *  is already folded in), and on a soloed track when any track is soloed. */
+function heard(m: MasterAudioClip, solo: readonly string[] | undefined): boolean {
+  if (m.clip.muted === true) return false;
+  return solo === undefined || solo.length === 0 || solo.includes(m.trackId);
+}
+
+function sameSolo(a: readonly string[] | undefined, b: readonly string[] | undefined): boolean {
+  const x = a ?? [];
+  const y = b ?? [];
+  return x.length === y.length && x.every((id, i) => id === y[i]);
 }
 
 export function createAudioPreview(deps: AudioPreviewDeps): AudioPreview {
   let ctx: AudioContextLike | null = null;
   let ctxFailed = false;
   let master: GainNodeLike | null = null;
+  /** Per-track unity buses, created as tracks first get a voice; see
+   *  `MonitorGraph.tracks`. They live as long as the context does. */
+  let buses: Map<string, GainNodeLike> = new Map();
   let masterMuted = false;
   let masterVolume = 1;
   let disposed = false;
-  let last: TransportSnapshot = { playing: false, frame: 0, doc: null };
+  let last: TransportSnapshot = {
+    playing: false,
+    frame: 0,
+    doc: null,
+    audible: true,
+    scene: null,
+  };
 
   /**
-   * AudioBuffer cache by asset PATH. "failed" is terminal: one error, no retries.
+   * AudioBuffer cache by asset PATH, filled by the decode ahead and by a play
+   * edge alike. A "failed" entry is retried on the next PLAY EDGE, never inside
+   * a session and never by the decode ahead, so one dead URL cannot turn the
+   * transport into a fetch loop and one transient 5xx cannot silence a clip for
+   * the rest of the page's life — which used to make the preview and the export
+   * disagree about what the document sounds like.
    *
    * NOT by asset id. `ShotAsset.id` is a slug of the filename uniquified only
    * against the ids already in ITS OWN document (`freshId(usedIdsOf(doc), …)`),
@@ -156,19 +526,90 @@ export function createAudioPreview(deps: AudioPreviewDeps): AudioPreview {
    * that owns this preview never remounts — so an id key serves one shot's
    * audio to another shot with the same filename. `asset.path` is the
    * content-addressed `<hash8>-<name>` the asset store writes, which is unique
-   * across every document and identical for identical bytes: keying on it also
-   * keeps the cache hit for a genuine re-import of the same file.
+   * across every document and identical for identical bytes.
+   *
+   * A clip's PROCESSED file (schema v49) leaves once no clip of the document
+   * plays it (`reconcile`): each setting is a whole decoded sound, and a knob
+   * turned during playback would otherwise keep every one of them.
    */
   const buffers = new Map<string, CacheEntry>();
 
-  /** clipId -> live voice. Non-null exactly while an audible session runs —
-   *  late decodes join it; mute/pause null it. */
-  let session: Map<string, Voice> | null = null;
+  /**
+   * Analysis sidecars by asset PATH, on the same terms as the buffers above:
+   * content-addressed key, one fetch per asset, a failure retried on the next
+   * play edge rather than latched for the life of the page.
+   *
+   * A missing analysis is not an error here. `duckedGainTrack` returns
+   * undefined without one, so the bed simply plays at its authored level until
+   * the sidecar arrives and `reconcile` re-automates it. The EXPORT is the
+   * strict one: it refuses rather than shipping the level the author has
+   * stopped hearing.
+   */
+  const analyses = new Map<string, AnalysisEntry>();
+  /** Bumped whenever an analysis lands, so the derived-track memo below knows
+   *  the answer may have changed even though the document did not. */
+  let analysisGeneration = 0;
+  let derivedFor: { doc: Doc3D; generation: number; tracks: Map<string, ShotTrack> } | null = null;
+
+  /** Every ducked clip's derived level, recomputed only when the document
+   *  object or the set of landed analyses actually changes. A gain drag mints
+   *  a new document per pointermove, so this runs at gesture rate. */
+  function derivedTracks(doc: Doc3D): Map<string, ShotTrack> {
+    if (derivedFor !== null && derivedFor.doc === doc && derivedFor.generation === analysisGeneration) {
+      return derivedFor.tracks;
+    }
+    const tracks = derivedGainTracks(doc, (asset) => {
+      const entry = analyses.get(asset.path);
+      return entry?.status === "ready" ? entry.analysis : undefined;
+    });
+    derivedFor = { doc, generation: analysisGeneration, tracks };
+    return tracks;
+  }
+
+  /** The live session, or null while paused, muted or inaudible. */
+  let session: Session | null = null;
+  /** The document id the stage last presented whole (its ready edge): the
+   *  one the decode ahead may fetch for. */
+  let readyDoc: string | null = null;
+  /** A decode ahead in flight: one at a time, so the nearest lands first. */
+  let ahead = false;
 
   function now(): number {
     return deps.now ? deps.now() : ctx!.currentTime;
   }
 
+  function wallNow(): number {
+    return deps.wallNow ? deps.wallNow() : performance.now();
+  }
+
+  function fpsOf(): Rational {
+    return last.doc!.fps;
+  }
+
+  /** Audio time of a picture frame, on the CURRENT session's anchor. */
+  function t(frame: number): number {
+    const s = session!;
+    return s.anchorTime + framesToSeconds(frame - s.anchorFrame, fpsOf());
+  }
+
+  /**
+   * The frame the audio clock has reached, rounded UP so anything scheduled
+   * from it is scheduled in the future.
+   *
+   * EPSILON before the ceil, because the common case is an exact boundary: the
+   * transport ticks frame by frame and the elapsed time is n/fps, which in
+   * doubles lands a few ULPs either side of the integer. Ceiling that lands on
+   * n + 1 half the time, and a reconcile or a late decode scheduled from one
+   * frame later than the audio actually is drops a frame of it.
+   */
+  function frameNow(): number {
+    const s = session!;
+    const fps = fpsOf();
+    const elapsed = now() - s.anchorTime;
+    const frames = (elapsed * fps.num) / fps.den;
+    return s.anchorFrame + Math.max(0, Math.ceil(frames - 1e-9));
+  }
+
   function ensureContext(): boolean {
     if (ctxFailed) return false;
     if (!ctx) {
@@ -184,126 +625,445 @@ export function createAudioPreview(deps: AudioPreviewDeps): AudioPreview {
       master = ctx.createGain();
       master.gain.value = masterVolume;
       master.connect(ctx.destination);
+      // THE GRAPH NOW EXISTS, so anything waiting to meter it can start. After
+      // the connect, so a tap can never be attached to a node that is not yet
+      // in the graph.
+      // The document's buses go up WITH the master, so the first press
+      // publishes once and a face re-renders once.
+      buses = new Map();
+      if (last.doc !== null) addBuses(last.doc);
+      publishMonitor({ ctx, node: master, tracks: buses });
     }
     try {
-      void ctx.resume?.(); // autoplay policy: nudge on every play gesture
+      void ctx.resume?.(); // autoplay policy: nudge on every press
     } catch {
       // resume is best-effort; a suspended context just stays silent
     }
     return true;
   }
 
-  /** Schedule one clip's voice, anchored at (anchorFrame ↔ anchorTime). */
+  /** Create or resume the realtime context, for a transport that can sound. */
+  function wake(): boolean {
+    return last.doc !== null && !masterMuted && last.audible && ensureContext();
+  }
+
+  /**
+   * Stop a voice the way the TRANSPORT stops it: a short release, then the
+   * stop, then teardown once that stop has happened.
+   *
+   * The envelope's own ramps cannot cover this. They describe the CLIP, and
+   * pausing at frame 200 is not something the clip has an opinion about — the
+   * gain is whatever it is when the author lets go, and cutting a source off
+   * there is a step discontinuity in the output buffer. Which is a click, on
+   * every pause, every scrub and every loop wrap.
+   */
+  /**
+   * Give every track of `doc` its bus, into a NEW map when any is missing.
+   * True when it added one, so the caller publishes.
+   *
+   * ponytail: a deleted track's bus stays wired, idle, until the context
+   * closes. Drop it here if a session ever churns through many tracks.
+   */
+  function addBuses(doc: Doc3D): boolean {
+    const missing = audioTracksOf(doc).filter((t) => !buses.has(t.id));
+    if (missing.length === 0) return false;
+    const next = new Map(buses);
+    for (const track of missing) {
+      const bus = ctx!.createGain();
+      bus.gain.value = 1;
+      bus.connect(master!);
+      next.set(track.id, bus);
+    }
+    buses = next;
+    return true;
+  }
+
+  /** The bus a track's voices sum into. `reconcile` has already made one for
+   *  every track of the document, so this only builds on a stale snapshot. */
+  function busFor(trackId: string): GainNodeLike {
+    const existing = buses.get(trackId);
+    if (existing !== undefined) return existing;
+    const bus = ctx!.createGain();
+    bus.gain.value = 1;
+    bus.connect(master!);
+    buses = new Map(buses).set(trackId, bus);
+    publishMonitor({ ctx: ctx!, node: master!, tracks: buses });
+    return bus;
+  }
+
+  function release(voice: Voice): void {
+    const t0 = now();
+    const param = voice.gain.gain;
+    const drop = (): void => {
+      voice.source.disconnect();
+      voice.gain.disconnect();
+      if (voice.pan !== null) {
+        voice.pan.split.disconnect();
+        voice.pan.l.disconnect();
+        voice.pan.r.disconnect();
+        voice.pan.merge.disconnect();
+      }
+    };
+    try {
+      param.cancelScheduledValues(t0);
+      param.setValueAtTime(param.value, t0);
+      param.linearRampToValueAtTime(0, t0 + RAMP_SECONDS);
+    } catch {
+      // A param that refuses a schedule (a context already closed) still has to
+      // reach the stop below.
+    }
+    voice.source.onended = drop;
+    try {
+      voice.source.stop(t0 + RAMP_SECONDS);
+    } catch {
+      drop(); // already ended — its nodes are inert, and onended will not fire
+    }
+  }
+
+  /** Schedule one clip's voice into the CURRENT session. */
   function scheduleClip(
-    ref: AudioClipRef,
+    m: MasterAudioClip,
     buffer: AudioBufferLike,
-    endFrameExclusive: number,
-    fps: Rational,
-    anchorFrame: number,
-    anchorTime: number,
+    fromFrame: number,
+    timing: string,
+    shape: string,
+    track: ShotTrack | undefined,
   ): void {
+    const ref = m.clip;
+    const s = session!;
+    const fps = fpsOf();
     const clip = asEngineClip(ref);
     const { start, end } = audioClipWindow(clip);
-    const schedEnd = Math.min(end, endFrameExclusive);
-    const first = Math.max(start, anchorFrame); // mid-window start advances the offset
+    const schedEnd = Math.min(end, s.endFrame);
+    const first = Math.max(start, fromFrame); // mid-window start advances the offset
     if (first >= schedEnd) return;
     const offset = audioSourceTimeAt(clip, first, fps);
     if (offset >= buffer.duration) return; // trimmed past the source: silence is legal
-    const t = (f: number): number => anchorTime + framesToSeconds(f - anchorFrame, fps);
     const c = ctx!;
     const source = c.createBufferSource();
     source.buffer = buffer;
     const gain = c.createGain();
     source.connect(gain);
-    gain.connect(master!);
+    // ALWAYS through the pan stage when the context has one, even at centre,
+    // so a later pan drag is a parameter write and never a reschedule.
+    const bus = busFor(m.trackId);
+    const pan = wirePan(c, gain, bus, m.pan ?? 0);
+    if (pan === null) gain.connect(bus);
     // The preview===export envelope: the engine's ONE point list, rendered as
-    // set-then-ramps; the source stops at the last point's frame.
-    const points = audioEnvelopePoints(clip, first, endFrameExclusive);
+    // set-then-ramps; the source stops at the last point's frame. `ref.frame`
+    // is the MASTER start the flatten put this clip at, and `gainTrack`'s
+    // frames are local to exactly that. The de-click at either edge is already
+    // in that list, including the one a mid-window `first` needs.
+    const points = audioEnvelopePoints(
+      clip,
+      first,
+      s.endFrame,
+      fps,
+      audioGainSampler(track, ref.frame, fps),
+    );
     if (points.length === 0) return;
-    gain.gain.setValueAtTime(points[0]!.gain, t(points[0]!.frame));
+    // A START ALREADY BEHIND THE AUDIO CLOCK. The session anchors on the
+    // transport's origin, and a context resumed at the play edge reads only a
+    // few ms by then, so the anchor, and a voice that starts on it, can lie
+    // before zero (Web Audio refuses a negative time: the throw ended the
+    // hand-over, and the transport never started) or merely in the past. The
+    // voice is already sounding there: it starts now, that much further into
+    // its source (source time runs with the timeline's), and no automation
+    // point is set before now.
+    const current = now();
+    const when = t(first);
+    const late = Math.max(0, current - when);
+    const length = framesToSeconds(points.at(-1)!.frame - first, fps) - late;
+    if (length <= 0) {
+      gain.disconnect();
+      return;
+    }
+    const at = (frame: number): number => Math.max(current, t(frame));
+    gain.gain.setValueAtTime(points[0]!.gain, at(points[0]!.frame));
     for (const p of points.slice(1)) {
-      gain.gain.linearRampToValueAtTime(p.gain, t(p.frame));
+      gain.gain.linearRampToValueAtTime(p.gain, at(p.frame));
     }
-    source.start(t(first), offset, framesToSeconds(points.at(-1)!.frame - first, fps));
-    session!.set(clip.id, { source, gain });
+    source.start(when + late, offset + late, length);
+    s.voices.set(clip.id, { source, gain, pan, timing, shape, path: playPathOf(timing) });
   }
 
-  /** Begin an audible session from `fromFrame`: schedule every decoded clip
-   *  whose window intersects [fromFrame, docDuration); kick decodes for the
-   *  rest (their resolve handler joins the then-current session). */
-  function startSession(fromFrame: number): void {
+  /**
+   * Follow an edited LEVEL on the node that is already sounding.
+   *
+   * The whole point of separating `shape` from `timing`. A gain-band drag mints
+   * a new document object per pointermove (the history scrub re-derives from
+   * the base), so treating any document change as a reschedule stopped and
+   * restarted every voice sixty times a second — and that is precisely the
+   * gesture an author performs WHILE LISTENING.
+   *
+   * The glide is the envelope's OWN next point rather than a ramp of our
+   * choosing: hold what is sounding, then ramp to where the new envelope says
+   * to be at the next point. At most one frame, and click-free by construction.
+   */
+  function reautomate(
+    voice: Voice,
+    ref: AudioClipRef,
+    shape: string,
+    track: ShotTrack | undefined,
+    pan: number,
+  ): void {
+    const s = session!;
+    const fps = fpsOf();
+    const clip = asEngineClip(ref);
+    const points = audioEnvelopePoints(
+      clip,
+      audioClipWindow(clip).start,
+      s.endFrame,
+      fps,
+      audioGainSampler(track, ref.frame, fps),
+    );
+    const t0 = now();
+    const param = voice.gain.gain;
+    param.cancelScheduledValues(t0);
+    param.setValueAtTime(param.value, t0);
+    for (const p of points) {
+      if (t(p.frame) > t0) param.linearRampToValueAtTime(p.gain, t(p.frame));
+    }
+    if (voice.pan !== null) {
+      // The side gains glide over the engine's de-click, so a knob drag never
+      // steps the waveform.
+      const g = panGains(pan);
+      for (const [side, value] of [
+        [voice.pan.l, g.l],
+        [voice.pan.r, g.r],
+      ] as const) {
+        side.gain.cancelScheduledValues(t0);
+        side.gain.setValueAtTime(side.gain.value, t0);
+        side.gain.linearRampToValueAtTime(value, t0 + RAMP_SECONDS);
+      }
+    }
+    voice.shape = shape;
+  }
+
+  /**
+   * Begin an audible session from `fromFrame`: on the transport's `origin`
+   * when the play edge brought a new one (its frame, at the audio time of its
+   * wall instant), otherwise on a reading of the clock now.
+   */
+  function startSession(fromFrame: number, origin: TransportOrigin | null = null): void {
     const doc = last.doc;
-    if (doc === null || masterMuted) return;
-    if (!ensureContext()) return;
-    session = new Map();
-    const anchorTime = now();
-    const endFrame = docDurationFrames(doc);
-    for (const clip of Object.values(doc.audio)) {
-      if (clip.muted === true) continue; // gain would be 0 — skip the node entirely
-      const window = audioClipWindow(asEngineClip(clip));
-      if (Math.min(window.end, endFrame) <= Math.max(window.start, fromFrame)) continue;
+    if (doc === null || !wake()) return;
+    session = {
+      anchorFrame: origin?.frame ?? fromFrame,
+      anchorTime: origin === null ? now() : now() - (wallNow() - origin.at) / 1000,
+      endFrame: endFrameOf(doc, last.scene),
+      voices: new Map(),
+    };
+    reconcile(fromFrame);
+  }
+
+  /**
+   * Bring the session's voices in line with the document, from `fromFrame`.
+   *
+   * Starting a session and absorbing an edit are the same question asked at
+   * different moments: which clips should be sounding, and are the nodes we
+   * hold the right ones for them.
+   *
+   * THROUGH THE FLATTEN, never `doc.audio`: since schema v13 that record is
+   * the bed only, and a shot's own clips are scene-local — so scheduling from
+   * it would play them at the wrong master time, or (for a shot that is not
+   * first) not at all. `masterAudioClips` is also what the export mixes from,
+   * and preview === export is the rule this lane is built on.
+   */
+  function reconcile(fromFrame: number): void {
+    const s = session;
+    const doc = last.doc;
+    if (s === null || doc === null) return;
+    const wanted = new Set<string>();
+    // Ask for anything a duck needs and does not have yet. Cheap: the list is
+    // empty for a document with no duck, and each path is fetched once.
+    for (const asset of duckSourceAssets(doc)) {
+      const entry = analyses.get(asset.path);
+      if (entry === undefined || entry.status === "failed") requestAnalysis(asset.path);
+    }
+    const derived = derivedTracks(doc);
+    /** Every file a clip of this document plays, heard now or not. */
+    const plays = new Set<string>();
+    // A track added mid-session gets its bus (and a strip its tap) here.
+    if (addBuses(doc)) publishMonitor({ ctx: ctx!, node: master!, tracks: buses });
+    for (const m of masterAudioClips(doc)) {
+      const clip = m.clip;
       const asset = doc.assets[clip.asset];
-      if (asset === undefined) continue; // validation requires it; a hole stays silent
-      const entry = buffers.get(asset.path);
+      if (asset !== undefined) plays.add(audioPlayPath(clip, asset));
+      // Muted (gain would be 0) or not soloed: skip the node entirely.
+      if (!heard(m, last.solo)) continue;
+      if (asset === undefined) {
+        // Both mixes THROW on this document and validateShotDoc refuses it, so
+        // silence with no explanation would be the preview quietly disagreeing
+        // with a file that cannot be produced at all.
+        console.error(
+          `[audio] clip ${clip.id} references unknown asset ${clip.asset}; ` +
+            `an export of this document will refuse it`,
+        );
+        continue;
+      }
+      wanted.add(clip.id);
+      const path = audioPlayPath(clip, asset);
+      const timing = timingOf(clip, path, m.trackId);
+      const track = derived.get(clip.id) ?? clip.gainTrack;
+      const shape = shapeOf(clip, track, m.pan ?? 0);
+      const voice = s.voices.get(clip.id);
+      const entry = buffers.get(path);
+      if (voice !== undefined) {
+        if (voice.timing === timing) {
+          if (voice.shape !== shape) reautomate(voice, clip, shape, track, m.pan ?? 0);
+          continue;
+        }
+        // NEW EFFECTS, SAME WINDOW: the processed file is being made. The old
+        // voice keeps sounding until it decodes (`onBufferReady` swaps it), so
+        // a knob turned during playback never drops the clip out.
+        if (entry?.status !== "ready" && voice.timing === timingOf(clip, voice.path, m.trackId)) {
+          if (entry === undefined || entry.status === "failed") requestDecode(path);
+          continue;
+        }
+        release(voice); // the source window moved: this node is the wrong one
+        s.voices.delete(clip.id);
+      }
       if (entry?.status === "ready") {
-        scheduleClip(clip, entry.buffer, endFrame, doc.fps, fromFrame, anchorTime);
-      } else if (entry === undefined) {
-        requestDecode(asset.path);
+        scheduleClip(m, entry.buffer, fromFrame, timing, shape, track);
+      } else if (entry === undefined || entry.status === "failed") {
+        void requestDecode(path);
       }
-      // pending: scheduled on resolve if still playing; failed: already errored
+      // pending: scheduled by onBufferReady when it lands
+    }
+    for (const [id, voice] of [...s.voices]) {
+      if (wanted.has(id)) continue;
+      release(voice); // deleted, muted, or moved out of this shot
+      s.voices.delete(id);
+    }
+    // Processed files the document no longer plays. A voice still sounding
+    // one holds its own buffer; one still decoding lands and goes next time.
+    for (const [path, entry] of buffers) {
+      if (entry.status !== "pending" && !plays.has(path) && isAudioFxFileName(path)) buffers.delete(path);
     }
   }
 
-  function requestDecode(path: string): void {
-    const c = ctx!; // non-null: only called under an ensured context; captured
-    // so a dispose() while the fetch is in flight can't null it away.
+  /** Fetch and decode one asset into the cache. Settles when it has landed or
+   *  failed, and never rejects. */
+  function requestDecode(path: string, priority?: "low"): Promise<void> {
     buffers.set(path, { status: "pending" });
-    void deps
-      .fetchBytes(`/studio/assets/${encodeURIComponent(path)}`)
-      .then((bytes) => deps.decode(c, bytes))
+    return deps
+      .fetchBytes(`/studio/assets/${encodeURIComponent(path)}`, priority)
+      .then((bytes) => deps.decode(bytes))
       .then(
         (buffer) => {
           buffers.set(path, { status: "ready", buffer });
           onBufferReady(path, buffer);
         },
         (e: unknown) => {
-          buffers.set(path, { status: "failed" }); // terminal — never retried
-          console.error(`[audio] asset ${path} failed to load; its clips stay silent`, e);
+          // Not terminal: the next PLAY EDGE tries again. A terminal failure
+          // made one transient error silence a clip for the page's life while
+          // the export — which fetches independently — still had it.
+          buffers.set(path, { status: "failed" });
+          console.error(`[audio] asset ${path} failed to load; retrying on the next play`, e);
         },
       );
   }
 
-  /** A late decode joins the CURRENT session from the then-current store frame
-   *  — never the (stale) frame play started at. No session = arrived after
-   *  pause/mute: schedule nothing.
+  /**
+   * DECODE AHEAD: the heard clip nearest the playhead whose asset nothing has
+   * asked for yet, then the next once that one lands.
    *
-   *  Matched through the then-current document's own asset record, so a decode
-   *  started in one shot cannot claim the same-named asset of the shot that
-   *  replaced it while the fetch was in flight. */
+   * Only while the stage has presented THIS document whole, and at low fetch
+   * priority, because these are canonical WAVs, tens of megabytes, and the
+   * stage's own loads come first. A failure waits for the next play edge, as
+   * any other does.
+   */
+  function decodeAhead(): void {
+    const doc = last.doc;
+    if (disposed || ahead || doc === null || last.presented !== true || doc.id !== readyDoc) return;
+    const frame = last.frame;
+    let nearest: { path: string; distance: number } | null = null;
+    for (const m of masterAudioClips(doc)) {
+      // The file playback asks for (`audioPlayPath`): a clip with effects
+      // plays its processed file, so warming the raw asset would be a large
+      // fetch nobody uses while the processed one still decodes cold on Play.
+      const asset = doc.assets[m.clip.asset];
+      const path = asset === undefined ? undefined : audioPlayPath(m.clip, asset);
+      if (path === undefined || buffers.has(path) || !heard(m, last.solo)) continue;
+      const start = m.clip.frame;
+      const end = start + m.clip.durationFrames;
+      const distance = frame < start ? start - frame : frame < end ? 0 : frame - end + 1;
+      if (nearest === null || distance < nearest.distance) nearest = { path, distance };
+    }
+    if (nearest === null) return;
+    ahead = true;
+    void requestDecode(nearest.path, "low").then(() => {
+      ahead = false;
+      decodeAhead();
+    });
+  }
+
+  /**
+   * Fetch one analysis sidecar. The document's own duck is what asks for it,
+   * so a project with no ducking never touches this path.
+   *
+   * On landing it RECONCILES rather than scheduling directly: the clip whose
+   * level changed is the bed, not the voice the sidecar describes, and
+   * reconcile is the one place that knows which is which.
+   */
+  function requestAnalysis(path: string): void {
+    analyses.set(path, { status: "pending" });
+    void deps
+      .fetchBytes(`/studio/assets/${encodeURIComponent(audioAnalysisFileName(path))}`)
+      .then((bytes) => JSON.parse(new TextDecoder().decode(bytes)) as AudioAnalysis)
+      .then(
+        (analysis) => {
+          analyses.set(path, { status: "ready", analysis });
+          analysisGeneration++;
+          if (!disposed && session !== null && last.playing) reconcile(frameNow());
+        },
+        (e: unknown) => {
+          analyses.set(path, { status: "failed" });
+          console.error(`[audio] analysis for ${path} failed to load; a duck on it stays flat`, e);
+        },
+      );
+  }
+
+  /**
+   * A late decode joins the CURRENT session on ITS OWN ANCHOR.
+   *
+   * Not on a fresh reading of the clock: the pair (anchorTime, anchorFrame) has
+   * to be sampled at one instant, or the voice lands offset from the ones
+   * already playing. This used to read `now()` here and pair it with the frame
+   * recorded at the last store notification — two different moments, up to a
+   * whole main-thread stall apart — which is a flam on a hit and phasing on two
+   * beds. A first Play takes this path for every clip the decode ahead has not
+   * reached yet.
+   */
   function onBufferReady(path: string, buffer: AudioBufferLike): void {
     if (disposed || session === null || !last.playing) return;
     const doc = last.doc;
     if (doc === null) return;
-    const anchorTime = now();
-    const endFrame = docDurationFrames(doc);
-    for (const clip of Object.values(doc.audio)) {
-      if (doc.assets[clip.asset]?.path !== path) continue;
-      if (clip.muted === true || session.has(clip.id)) continue;
-      scheduleClip(clip, buffer, endFrame, doc.fps, last.frame, anchorTime);
+    const from = frameNow();
+    const derived = derivedTracks(doc);
+    for (const m of masterAudioClips(doc)) {
+      const clip = m.clip;
+      const asset = doc.assets[clip.asset];
+      if (asset === undefined || audioPlayPath(clip, asset) !== path) continue;
+      if (!heard(m, last.solo)) continue;
+      const timing = timingOf(clip, path, m.trackId);
+      // A voice still playing this clip's previous file (its effects changed
+      // while the new one was made) is swapped here; one already on it stays.
+      const held = session.voices.get(clip.id);
+      if (held !== undefined) {
+        if (held.timing === timing) continue;
+        release(held);
+        session.voices.delete(clip.id);
+      }
+      const track = derived.get(clip.id) ?? clip.gainTrack;
+      scheduleClip(m, buffer, from, timing, shapeOf(clip, track, m.pan ?? 0), track);
     }
   }
 
   function teardown(): void {
     if (session === null) return;
-    for (const { source, gain } of session.values()) {
-      try {
-        source.stop();
-      } catch {
-        // already ended — stopping is best-effort
-      }
-      source.disconnect();
-      gain.disconnect();
-    }
+    for (const voice of session.voices.values()) release(voice);
     session = null;
   }
 
@@ -312,30 +1072,72 @@ export function createAudioPreview(deps: AudioPreviewDeps): AudioPreview {
       if (disposed) return;
       const prev = last;
       last = snap;
-      if (!snap.playing) {
-        if (prev.playing) teardown();
+      // THE ARM. A queued Play is the press, and the start it waits for is not
+      // one, so the realtime context is created or resumed here: the store
+      // notifies inside the `set` that arms, which runs in the press itself.
+      if (snap.armed === true && prev.armed !== true) wake();
+      // THE READY EDGE, keyed to its document. A Project switch reaches this
+      // before the stage has said it owes the new one a picture, and the
+      // decode ahead must not start under a scene that is still loading.
+      const presented = snap.presented === true;
+      if (presented && prev.presented !== true) readyDoc = snap.doc?.id ?? null;
+      // Only on what can change its answer, never on a tick. After this push,
+      // so a play edge's own requests go first, at full priority.
+      if (presented && (prev.presented !== true || snap.doc !== prev.doc || !sameSolo(prev.solo, snap.solo))) {
+        queueMicrotask(decodeAhead);
+      }
+      const running = snap.playing && snap.audible;
+      if (!running) {
+        if (session !== null) teardown();
         return;
       }
-      if (!prev.playing) {
-        // Play edge — the user-gesture moment; the context is created here.
-        startSession(snap.frame);
+      if (session === null) {
+        // Play edge. A new origin is this edge's alone: its session anchors on
+        // it, and any later one in the same run takes its own reading.
+        const origin = snap.origin ?? null;
+        startSession(snap.frame, origin === (prev.origin ?? null) ? null : origin);
         return;
       }
-      // While playing: reschedule on document identity change (a gain or fade
-      // edit audibly applies) or a scrub-jump; the monotone +small frame path
-      // (the rAF clock ticking) does nothing but the snapshot record above.
-      const scrubbed = snap.frame < prev.frame || snap.frame - prev.frame > SCRUB_JUMP_FRAMES;
-      if (snap.doc !== prev.doc || scrubbed) {
+      const doc = snap.doc;
+      if (doc === null) {
+        teardown();
+        return;
+      }
+      // The WINDOW moved under the transport (the entered shot was trimmed, or
+      // the author entered one): every voice's stop time is wrong, so this is a
+      // restart and not a reconcile.
+      if (endFrameOf(doc, snap.scene) !== session.endFrame) {
         teardown();
         startSession(snap.frame);
+        return;
+      }
+      // THE DRIFT CHECK, which replaced a jump threshold. A scrub or a loop
+      // wrap moves the picture without moving the audio clock, so the two
+      // disagree by the whole distance; a monotone tick does not, and neither
+      // does a stall — the transport's clock is absolute, so the picture
+      // catches up to where the audio already is. On a FRAME CHANGE only: any
+      // other notification carries the last tick's frame, which the audio has
+      // run past by up to a frame of its own. The audio runs ahead of the
+      // picture's frame by up to a refresh more (`DRIFT_REFRESH_S`).
+      if (snap.frame !== prev.frame) {
+        const ahead = now() - t(snap.frame);
+        const allowed = framesToSeconds(DRIFT_FRAMES, doc.fps);
+        if (ahead < -allowed || ahead > allowed + DRIFT_REFRESH_S) {
+          teardown();
+          startSession(snap.frame);
+          return;
+        }
       }
+      // A DOCUMENT EDIT, absorbed per clip rather than as a restart.
+      // A solo change is the same question: which voices should be sounding.
+      if (doc !== prev.doc || !sameSolo(prev.solo, snap.solo)) reconcile(frameNow());
     },
 
     setMasterMute(muted) {
       if (disposed || muted === masterMuted) return;
       masterMuted = muted;
       if (muted) teardown();
-      else if (last.playing) startSession(last.frame);
+      else if (last.playing && last.audible) startSession(last.frame);
     },
 
     setMasterVolume(volume) {
@@ -351,6 +1153,14 @@ export function createAudioPreview(deps: AudioPreviewDeps): AudioPreview {
       if (disposed) return;
       disposed = true;
       teardown();
+      // ITS OWN PUBLICATION AND NOT WHATEVER IS THERE. See the ceiling on the
+      // slot: one bridge owns it in practice, and a second preview disposing
+      // must not blank the surviving one's meter. A face's detach lands on the
+      // next commit, after this node is already unwired, which `release`
+      // already tolerates — its `disconnect` is wrapped for exactly that.
+      if (monitor !== null && monitor.node === master) publishMonitor(null);
+      for (const bus of buses.values()) bus.disconnect();
+      buses = new Map();
       master?.disconnect();
       master = null;
       try {