diff --git a/packages/core/src/editing/affordances.test.ts b/packages/core/src/editing/affordances.test.ts
index b975dd64bf..475e89d07a 100644
--- a/packages/core/src/editing/affordances.test.ts
+++ b/packages/core/src/editing/affordances.test.ts
@@ -156,6 +156,17 @@ describe("resolveEditingAffordances — sections", () => {
     }
   });
 
+  it("audio: vstFx applies", () => {
+    const s = resolveEditingAffordances(baseFacts({ tag: "audio" })).sections;
+    expect(s.vstFx).toBe(true);
+  });
+
+  it("vstFx does not apply to video, img, or plain elements", () => {
+    expect(resolveEditingAffordances(baseFacts({ tag: "video" })).sections.vstFx).toBe(false);
+    expect(resolveEditingAffordances(baseFacts({ tag: "img" })).sections.vstFx).toBe(false);
+    expect(resolveEditingAffordances(baseFacts({ tag: "div" })).sections.vstFx).toBe(false);
+  });
+
   it("img: media + colorGrading", () => {
     const s = resolveEditingAffordances(baseFacts({ tag: "img" })).sections;
     expect(s).toMatchObject({ media: true, colorGrading: true });
diff --git a/packages/core/src/editing/affordances.ts b/packages/core/src/editing/affordances.ts
index 272fb028fb..eaf12e5a10 100644
--- a/packages/core/src/editing/affordances.ts
+++ b/packages/core/src/editing/affordances.ts
@@ -38,6 +38,8 @@ export interface EditingSectionApplicability {
    *  as `layout`, kept separate since a future tag could need one without
    *  the other. */
   style: boolean;
+  /** VST FX chain editing — audio elements only (narrower than `media`, which also covers video/img). */
+  vstFx: boolean;
 }
 
 export interface EditingAffordances {
@@ -212,6 +214,7 @@ export function resolveEditingSections(facts: EditableElementFacts): EditingSect
     animation: facts.animationCount > 0,
     layout: hasVisualBox,
     style: hasVisualBox,
+    vstFx: facts.tag === "audio",
   };
 }
 
diff --git a/packages/core/src/runtime/init.ts b/packages/core/src/runtime/init.ts
index cd8bd8b2ea..dfbfae12e9 100644
--- a/packages/core/src/runtime/init.ts
+++ b/packages/core/src/runtime/init.ts
@@ -175,6 +175,8 @@ export function initSandboxRuntimeModular(): void {
   void webAudio.init().then((ok) => {
     webAudioReady = ok;
   });
+  // TEMP DEBUG — remove after diagnosis
+  (window as unknown as { __hfWebAudioDbg?: unknown }).__hfWebAudioDbg = webAudio;
   // `_auto` is a Studio-internal keyframe marker (an auto-tracked endpoint the
   // parser reads back), NOT an animatable property. Register it as a no-op GSAP
   // plugin so GSAP doesn't log "Invalid property _auto" on every tween build —
@@ -3028,7 +3030,15 @@ export function initSandboxRuntimeModular(): void {
   const scheduleWebAudioForActiveClips = () => {
     if (state.nativeMediaSyncDisabled || state.webAudioMediaDisabled) return;
     const gen = webAudio.startGeneration();
-    const audioEls = document.querySelectorAll("audio[data-start]");
+    // `data-vst-chain` elements are claimed by the VST preview hook
+    // (packages/studio/src/player/hooks/useVstPreview.ts) — it routes their
+    // audio through its own AudioContext/AudioWorklet fed by the sidecar and
+    // permanently mutes the element. Scheduling one here too would double-
+    // claim it: this transport's own mute/restore lifecycle (see
+    // webAudioTransport.ts's `schedulePlayback`/`stopAll`) would unmute it
+    // again once its native source ends, silently swapping the processed
+    // stream back for the untreated one.
+    const audioEls = document.querySelectorAll("audio[data-start]:not([data-vst-chain])");
     for (const rawEl of audioEls) {
       if (!(rawEl instanceof HTMLMediaElement) || !rawEl.isConnected) continue;
       const compStart = Number.parseFloat(rawEl.dataset.start ?? "");
@@ -3135,6 +3145,11 @@ export function initSandboxRuntimeModular(): void {
       const mediaEls = document.querySelectorAll("video, audio");
       for (const el of mediaEls) {
         if (!(el instanceof HTMLMediaElement)) continue;
+        // A VST-chain element is permanently muted by the VST preview hook —
+        // its actual audio plays through a separate AudioWorklet fed by the
+        // sidecar, not this element. Overwriting `.muted` here would
+        // silently swap the processed stream back for the untreated one.
+        if (el.hasAttribute("data-vst-chain")) continue;
         el.muted = effective || el.defaultMuted;
       }
     },
@@ -3144,6 +3159,7 @@ export function initSandboxRuntimeModular(): void {
       const mediaEls = document.querySelectorAll("video, audio");
       for (const el of mediaEls) {
         if (!(el instanceof HTMLMediaElement)) continue;
+        if (el.hasAttribute("data-vst-chain")) continue;
         const parsed = parseFloat(el.dataset.volume ?? "");
         const clipVolume = Number.isFinite(parsed) ? parsed : 1;
         el.volume = clipVolume * volume;
@@ -3156,6 +3172,7 @@ export function initSandboxRuntimeModular(): void {
       const mediaEls = document.querySelectorAll("video, audio");
       for (const el of mediaEls) {
         if (!(el instanceof HTMLMediaElement)) continue;
+        if (el.hasAttribute("data-vst-chain")) continue;
         el.muted = effective || el.defaultMuted;
       }
     },
diff --git a/packages/player/src/hyperframes-player.test.ts b/packages/player/src/hyperframes-player.test.ts
index f065f09786..f1a6b60626 100644
--- a/packages/player/src/hyperframes-player.test.ts
+++ b/packages/player/src/hyperframes-player.test.ts
@@ -26,6 +26,13 @@ function createForeignFrameMediaDocument(): {
     constructor(tagName: string) {
       this.tagName = tagName;
     }
+
+    // Real DOM elements always have this — matches the actual foreign-realm
+    // elements this class simulates. No attributes are ever set on these
+    // mocks, so it's always false.
+    hasAttribute(): boolean {
+      return false;
+    }
   }
 
   class FrameMedia extends FrameElement {
@@ -268,6 +275,36 @@ describe("HyperframesPlayer parent-frame media", () => {
     return video;
   }
 
+  it("does not mute a data-vst-chain iframe element when syncing the muted attribute", () => {
+    // A VST-chain element is permanently muted by the studio's VST preview
+    // hook (packages/studio/src/player/hooks/useVstPreview.ts) — its audio
+    // plays through a separate AudioWorklet fed by the sidecar, not this
+    // element. `_setIframeMediaMuted` (triggered here via the public `muted`
+    // attribute) must skip it, or every mute/unmute sync silently swaps the
+    // processed stream back for the untreated one.
+    player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
+    document.body.appendChild(player);
+
+    const iframe = player.shadowRoot?.querySelector("iframe");
+    if (!(iframe instanceof HTMLIFrameElement)) throw new Error("expected player iframe");
+    const iframeDoc = iframe.contentDocument;
+    if (!iframeDoc) throw new Error("expected player iframe document");
+
+    const vstAudio = iframeDoc.createElement("audio");
+    vstAudio.setAttribute("data-vst-chain", "fx/music.vstchain.json");
+    vstAudio.muted = false;
+    iframeDoc.body.appendChild(vstAudio);
+
+    const plainVideo = iframeDoc.createElement("video");
+    plainVideo.muted = false;
+    iframeDoc.body.appendChild(plainVideo);
+
+    player.setAttribute("muted", "");
+
+    expect(vstAudio.muted).toBe(false);
+    expect(plainVideo.muted).toBe(true);
+  });
+
   it("does not mute iframe media on autoplay fallback inside presenter slideshow", () => {
     const slideshow = document.createElement("hyperframes-slideshow");
     slideshow.appendChild(player);
@@ -716,13 +753,15 @@ describe("HyperframesPlayer media MutationObserver scoping", () => {
     // Subtree is still required — sub-composition media can be deeply nested
     // inside the host (e.g. wrapper div around the `<audio>`).
     // Attribute observation on "preload" is required so the player creates
-    // parent proxies just-in-time when the preloader promotes a clip.
+    // parent proxies just-in-time when the preloader promotes a clip;
+    // "data-vst-chain" so it drops/restores the dry proxy when a track's VST
+    // ownership flips (see parent-media's _adoptIframeMedia).
     for (const call of observeSpy.mock.calls) {
       expect(call[1]).toEqual({
         childList: true,
         subtree: true,
         attributes: true,
-        attributeFilter: ["preload"],
+        attributeFilter: ["preload", "data-vst-chain"],
       });
     }
   });
diff --git a/packages/player/src/hyperframes-player.ts b/packages/player/src/hyperframes-player.ts
index d1764a5e7e..d03c397957 100644
--- a/packages/player/src/hyperframes-player.ts
+++ b/packages/player/src/hyperframes-player.ts
@@ -535,7 +535,15 @@ class HyperframesPlayer extends HTMLElement {
     const iframeDoc = this._getSameOriginIframeDocument();
     if (!iframeDoc) return;
     for (const el of iframeDoc.querySelectorAll("video, audio")) {
-      if (isRealmHtmlMediaElement(el)) el.muted = muted || el.defaultMuted;
+      if (!isRealmHtmlMediaElement(el)) continue;
+      // A VST-chain element is permanently muted by the studio's VST preview
+      // hook — its audio plays through a separate AudioWorklet fed by the
+      // sidecar, not this element (see packages/core/src/runtime/init.ts's
+      // onSetMuted, which carries the same exclusion for the in-iframe
+      // runtime's own mute-sync path). Overwriting `.muted` here would
+      // silently swap the processed stream back for the untreated one.
+      if (el.hasAttribute("data-vst-chain")) continue;
+      el.muted = muted || el.defaultMuted;
     }
   }
 
diff --git a/packages/player/src/parent-media.test.ts b/packages/player/src/parent-media.test.ts
index d894c7ac70..7f1a8bf31a 100644
--- a/packages/player/src/parent-media.test.ts
+++ b/packages/player/src/parent-media.test.ts
@@ -162,3 +162,30 @@ describe("ParentMediaManager audio-src proxy lifecycle", () => {
     expect(mgr.entries[0]).toBe(adopted);
   });
 });
+
+describe("ParentMediaManager VST-chain tracks", () => {
+  it("does not create a dry parent proxy for a data-vst-chain element", () => {
+    const mgr = makeManager();
+    const plain = document.createElement("audio");
+    plain.setAttribute("data-start", "0");
+    plain.setAttribute("src", "https://example.test/plain.mp3");
+    const vst = document.createElement("audio");
+    vst.setAttribute("data-start", "0");
+    vst.setAttribute("data-vst-chain", "fx/x.vstchain.json");
+    vst.setAttribute("src", "https://example.test/vst-dry.mp3");
+    document.body.append(plain, vst);
+
+    // setupFromIframe adopts every audio[data-start] EXCEPT the VST-chained
+    // one — its audio is produced by the VST pipeline's AudioContext, so a dry
+    // proxy here would play the unprocessed file over the effect ("all dry").
+    mgr.setupFromIframe(document);
+
+    const srcs = mgr.entries.map((e) => e.el.src);
+    expect(srcs.some((s) => s.includes("plain.mp3"))).toBe(true);
+    expect(srcs.some((s) => s.includes("vst-dry.mp3"))).toBe(false);
+
+    mgr.teardownObserver();
+    plain.remove();
+    vst.remove();
+  });
+});
diff --git a/packages/player/src/parent-media.ts b/packages/player/src/parent-media.ts
index 7311461c93..7229e4bea4 100644
--- a/packages/player/src/parent-media.ts
+++ b/packages/player/src/parent-media.ts
@@ -376,6 +376,13 @@ export class ParentMediaManager {
 
   // fallow-ignore-next-line complexity
   private _adoptIframeMedia(iframeEl: HTMLMediaElement): void {
+    // A VST-chain track's audio is produced entirely by the studio's VST
+    // pipeline (useVstPreview) through its own AudioContext — the wet,
+    // processed stream. A dry parent proxy here would play the UNPROCESSED
+    // file on top of it, so the effect sounds absent ("all dry"). Leave this
+    // element's audio to the VST pipeline; the observer re-adopts it if the
+    // chain is later removed.
+    if (iframeEl.hasAttribute("data-vst-chain")) return;
     // Skip elements the preloader has demoted — the observer will re-trigger
     // when the preload attribute is promoted to "auto".
     if (iframeEl.preload === "metadata" || iframeEl.preload === "none") return;
@@ -428,6 +435,21 @@ export class ParentMediaManager {
           continue;
         }
 
+        // A track becoming (or ceasing to be) VST-chained flips who owns its
+        // audio: adding `data-vst-chain` hands playback to the VST pipeline, so
+        // drop the dry parent proxy; removing it hands playback back here.
+        if (m.type === "attributes" && m.attributeName === "data-vst-chain") {
+          const target = m.target;
+          if (
+            isRealmHtmlMediaElement(target) &&
+            target.matches("audio[data-start], video[data-start]")
+          ) {
+            if (target.hasAttribute("data-vst-chain")) this._detachIframeMedia(target);
+            else this._adoptIframeMedia(target);
+          }
+          continue;
+        }
+
         for (const added of m.addedNodes) {
           if (!isRealmElement(added)) continue;
           const candidates: HTMLMediaElement[] = [];
@@ -466,7 +488,7 @@ export class ParentMediaManager {
       childList: true,
       subtree: true,
       attributes: true,
-      attributeFilter: ["preload"],
+      attributeFilter: ["preload", "data-vst-chain"],
     };
 
     const targets = selectMediaObserverTargets(doc);
diff --git a/packages/studio/src/components/editor/manualEditingAvailability.ts b/packages/studio/src/components/editor/manualEditingAvailability.ts
index d156bf6941..82d26fafbd 100644
--- a/packages/studio/src/components/editor/manualEditingAvailability.ts
+++ b/packages/studio/src/components/editor/manualEditingAvailability.ts
@@ -74,4 +74,14 @@ export const STUDIO_FLAT_INSPECTOR_ENABLED = resolveStudioBooleanEnvFlag(
   true,
 );
 
+// VST FX chain editing (the property panel's "Make room for voiceover" carve
+// control + per-plugin chain UI) and its live-preview PCM streaming through
+// the VST host sidecar — new, unreleased surface, off by default pending
+// broader rollout. Default false; enable via VITE_STUDIO_ENABLE_VST=true.
+export const STUDIO_VST_ENABLED = resolveStudioBooleanEnvFlag(
+  env,
+  ["VITE_STUDIO_ENABLE_VST", "VITE_STUDIO_VST_ENABLED"],
+  false,
+);
+
 import { resolveEnabledSdkFamilies } from "../../utils/sdkCutoverPolicy";
diff --git a/packages/studio/src/components/editor/propertyPanelVstShared.ts b/packages/studio/src/components/editor/propertyPanelVstShared.ts
new file mode 100644
index 0000000000..26fc173ee7
--- /dev/null
+++ b/packages/studio/src/components/editor/propertyPanelVstShared.ts
@@ -0,0 +1,150 @@
+import type { DomEditSelection } from "./domEditing";
+import {
+  isRecord,
+  parseChainFile,
+  serializeChainFile,
+  type ChainFileJson,
+  type ChainPluginJson,
+} from "../../utils/vstChainFile";
+
+/** A plugin the sidecar found on disk during a filesystem scan (Task 12's `useVstHost`). */
+export interface VstRegistryEntry {
+  path: string;
+  name: string;
+  format: string;
+}
+
+export interface LoadChainResult {
+  /** The sidecar-assigned wire `trackIndex` for this track (see useVstHost's `assignNextTrackIndex`). */
+  trackIndex: number;
+  /** The dry file's real sample rate — the sidecar streams PCM at this
+   *  rate, not a fixed constant. The caller must create its AudioContext/
+   *  AudioWorkletNode at this rate, or playback comes out at the wrong
+   *  pitch and speed (and the drift-check misreads the resulting rate
+   *  mismatch as ever-growing drift). */
+  sampleRate: number;
+  /** False when pedalboard can't host this chain without emitting NaN/Inf/
+   *  runaway output (see the sidecar's `probe_chain_stability`). The caller
+   *  must NOT stream or mute the track — it stays on its dry audio, with a
+   *  warning — because a streamed unstable chain is silence at best. */
+  stable: boolean;
+}
+
+/**
+ * Consumed by this section; the real implementation is a Task 12 hook that
+ * talks to the sidecar over a WebSocket. `null` means the sidecar isn't
+ * running/installed.
+ */
+export interface VstHostApi {
+  registry: VstRegistryEntry[];
+  scan(): Promise<void>;
+  openEditor(trackId: string, pluginIndex: number): void;
+  /** Sets a single plugin parameter on the live (streaming) instance — takes
+   *  effect immediately, no reload. Fire-and-forget. */
+  setParam(trackId: string, pluginIndex: number, param: string, value: number): void;
+  loadChain(trackId: string, chain: ChainFileJson, wavUrl: string): Promise<LoadChainResult>;
+  getState(trackId: string): Promise<string[]>;
+}
+
+function readFileContent(value: unknown): string | null {
+  if (!isRecord(value)) return null;
+  return typeof value.content === "string" ? value.content : null;
+}
+
+/** Sensible [min, max, step] per built-in parameter name (pedalboard built-ins
+ *  don't expose ranges). Unknown names fall back to a 0..1 normalized slider. */
+const PARAM_RANGES: Record<string, [number, number, number]> = {
+  mix: [0, 1, 0.01],
+  wet_level: [0, 1, 0.01],
+  dry_level: [0, 1, 0.01],
+  depth: [0, 1, 0.01],
+  width: [0, 1, 0.01],
+  damping: [0, 1, 0.01],
+  room_size: [0, 1, 0.01],
+  resonance: [0, 1, 0.01],
+  feedback: [0, 1, 0.01],
+  freeze_mode: [0, 1, 1],
+  drive_db: [0, 60, 0.5],
+  gain_db: [-40, 40, 0.5],
+  threshold_db: [-100, 0, 0.5],
+  semitones: [-24, 24, 1],
+  bit_depth: [1, 16, 1],
+  ratio: [1, 20, 0.1],
+  delay_seconds: [0, 2, 0.01],
+  rate_hz: [0, 20, 0.1],
+  centre_delay_ms: [1, 50, 0.5],
+  attack_ms: [0, 100, 0.5],
+  release_ms: [0, 1000, 1],
+  centre_frequency_hz: [20, 20000, 1],
+  cutoff_frequency_hz: [20, 20000, 1],
+  cutoff_hz: [20, 20000, 1],
+  drive: [1, 30, 0.1],
+};
+
+export function paramRange(name: string): [number, number, number] {
+  return PARAM_RANGES[name] ?? [0, 1, 0.01];
+}
+
+export function humanizeParam(name: string): string {
+  return name.replace(/_/g, " ");
+}
+
+/** Built-in plugin state is base64(JSON of {param: number}); external plugins
+ *  carry opaque raw_state, so only built-ins are decodable into an editable
+ *  param map. Returns null for anything that isn't a plain number map. */
+export function decodeBuiltinParams(
+  stateB64: string | null | undefined,
+): Record<string, number> | null {
+  if (!stateB64) return null;
+  try {
+    const parsed: unknown = JSON.parse(atob(stateB64));
+    if (!isRecord(parsed)) return null;
+    const out: Record<string, number> = {};
+    for (const [k, v] of Object.entries(parsed)) {
+      if (typeof v === "number" && Number.isFinite(v)) out[k] = v;
+    }
+    return out;
+  } catch {
+    return null;
+  }
+}
+
+export function encodeBuiltinParams(params: Record<string, number>): string {
+  return btoa(JSON.stringify(params));
+}
+
+export function normalizePluginFormat(format: string): ChainPluginJson["format"] {
+  return format === "vst3" || format === "au" ? format : "builtin";
+}
+
+export function vstElementId(element: DomEditSelection): string {
+  return element.id ?? element.hfId ?? "element";
+}
+
+export function chainFilePath(element: DomEditSelection): string {
+  return `fx/${vstElementId(element)}.vstchain.json`;
+}
+
+export async function readChainFile(
+  projectId: string,
+  path: string,
+): Promise<ChainFileJson | null> {
+  const response = await fetch(`/api/projects/${projectId}/files/${encodeURIComponent(path)}`);
+  if (!response.ok) return null;
+  const content = readFileContent(await response.json());
+  if (content === null) return null;
+  return parseChainFile(content);
+}
+
+export async function writeChainFile(
+  projectId: string,
+  path: string,
+  chain: ChainFileJson,
+): Promise<boolean> {
+  const response = await fetch(`/api/projects/${projectId}/files/${encodeURIComponent(path)}`, {
+    method: "PUT",
+    headers: { "Content-Type": "text/plain" },
+    body: serializeChainFile(chain),
+  });
+  return response.ok;
+}
diff --git a/packages/studio/src/components/nle/NLEContext.test.ts b/packages/studio/src/components/nle/NLEContext.test.ts
index cb59fcdb1b..092b201584 100644
--- a/packages/studio/src/components/nle/NLEContext.test.ts
+++ b/packages/studio/src/components/nle/NLEContext.test.ts
@@ -2,7 +2,11 @@
 import React, { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { shouldDisableTimelineWhileCompositionLoading, NLEProvider } from "./NLEContext";
+import {
+  shouldDisableTimelineWhileCompositionLoading,
+  NLEProvider,
+  useNLEContext,
+} from "./NLEContext";
 import { useAssetPreviewStore } from "../../utils/assetPreviewStore";
 import { installReactActEnvironment } from "../../hooks/domSelectionTestHarness";
 
@@ -91,6 +95,69 @@ describe("NLEProvider — asset preview scoping", () => {
   });
 });
 
+describe("NLEProvider — vstHost wiring", () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it("threads a single useVstHost() instance through context, shared by every consumer", async () => {
+    // No project API in this unit test — stub fetch so nothing this pulls in
+    // (compIdToSrc's mount effect) hits the network.
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(() => Promise.reject(new Error("no network in tests"))),
+    );
+
+    const seen: Array<ReturnType<typeof useNLEContext>["vstHost"]> = [];
+    function Consumer() {
+      seen.push(useNLEContext().vstHost);
+      return null;
+    }
+
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    await act(async () => {
+      // Two independent consumers in the SAME render, mirroring how
+      // useVstPreview (inside useTimelinePlayer) and StudioRightPanel both
+      // read `vstHost` from this one context value rather than each calling
+      // useVstHost() itself (which would open a second, independent
+      // WebSocket connection to the sidecar).
+      root.render(
+        React.createElement(
+          NLEProvider,
+          { projectId: "project-a" },
+          React.createElement(Consumer),
+          React.createElement(Consumer),
+        ),
+      );
+      await Promise.resolve();
+    });
+
+    // NLEProvider's own effects (e.g. the compIdToSrc fetch above rejecting)
+    // can trigger more than one commit, so more than 2 pushes is expected —
+    // what matters is that within EVERY commit, both consumers saw the exact
+    // same `vstHost` reference (proving one hook instance, threaded via
+    // context, not two independent `useVstHost()` calls).
+    expect(seen.length).toBeGreaterThanOrEqual(2);
+    expect(seen.length % 2).toBe(0);
+    for (let i = 0; i < seen.length; i += 2) {
+      expect(seen[i]).toBe(seen[i + 1]);
+    }
+
+    const vstHost = seen.at(-1);
+    if (!vstHost) throw new Error("no vstHost observed");
+    expect(vstHost.status).toBe("idle");
+    expect(vstHost.api).toBeNull();
+    expect(typeof vstHost.ensureStarted).toBe("function");
+    expect(typeof vstHost.onPcmFrame).toBe("function");
+    expect(typeof vstHost.sendTransport).toBe("function");
+    expect(typeof vstHost.onDisconnect).toBe("function");
+    expect(typeof vstHost.onChainLoaded).toBe("function");
+
+    act(() => root.unmount());
+    host.remove();
+  });
+});
+
 describe("NLEProvider — composition source-map scoping", () => {
   afterEach(() => vi.unstubAllGlobals());
 
diff --git a/packages/studio/src/components/nle/NLEContext.tsx b/packages/studio/src/components/nle/NLEContext.tsx
index 5bdece6459..00ab3de189 100644
--- a/packages/studio/src/components/nle/NLEContext.tsx
+++ b/packages/studio/src/components/nle/NLEContext.tsx
@@ -9,6 +9,9 @@ import {
 } from "react";
 import { useTimelinePlayer, usePlayerStore } from "../../player";
 import type { TimelineElement } from "../../player";
+import { useVstHost, type UseVstHostResult } from "../../hooks/useVstHost";
+import { useVstPreview } from "../../player/hooks/useVstPreview";
+import { useStudioShellContextOptional } from "../../contexts/StudioContext";
 import type { CompositionLevel } from "./CompositionBreadcrumb";
 import { useCompositionStack } from "./useCompositionStack";
 import { MIN_TIMELINE_H, MIN_PREVIEW_H } from "./TimelineResizeDivider";
@@ -33,6 +36,12 @@ export interface NLEContextValue {
   seek: (time: number, options?: { keepPlaying?: boolean }) => boolean;
   refreshPlayer: () => void;
   onIframeLoad: () => void;
+  // Single VST sidecar connection for the whole shell (mounted once, right
+  // here in NLEProvider) — shared by live playback (useVstPreview, mounted
+  // alongside it) and the FX property panel (StudioRightPanel reads
+  // `vstHost.api` for PropertyPanel) so there is exactly one WebSocket, never
+  // two independent connections racing the sidecar's per-track state.
+  vstHost: UseVstHostResult;
   // composition stack (from useCompositionStack)
   compositionStack: CompositionLevel[];
   updateCompositionStack: React.Dispatch<React.SetStateAction<CompositionLevel[]>>;
@@ -83,6 +92,10 @@ export function NLEProvider({
   onCompositionLoadingChange,
   children,
 }: NLEProviderProps) {
+  // Optional — NLEProvider is also mounted directly in tests without the
+  // shell providers; useVstPreview's crash-fallback toast is skipped below
+  // without a showToast callback, same as before.
+  const shellCtx = useStudioShellContextOptional();
   const {
     iframeRef,
     togglePlay,
@@ -91,6 +104,14 @@ export function NLEProvider({
     refreshPlayer,
   } = useTimelinePlayer();
 
+  // Single sidecar connection for the whole shell, shared by live playback
+  // (useVstPreview, mounted right here) and the FX property panel
+  // (StudioRightPanel reads `vstHost.api` via this context) — see
+  // useVstPreview's doc-comment for why two independent connections to the
+  // sidecar aren't safe.
+  const vstHost = useVstHost();
+  useVstPreview(iframeRef, projectId, vstHost, shellCtx?.showToast); // no-op until a vst-chain track appears
+
   // Reset timeline state when the project changes. Done in an effect, not during
   // render: reset() updates the player store, and updating another store/component
   // mid-render triggers React's "Cannot update a component while rendering a
@@ -129,6 +150,14 @@ export function NLEProvider({
     // reload (the comp may not ship the plugin until it actually uses one).
     ensureMotionPathPluginLoaded(iframeRef.current);
     onIframeRef?.(iframeRef.current);
+    // A preview reload replaces the composition DOM — including every
+    // `<audio data-vst-chain>` element. Any VST track useVstPreview loaded
+    // against the PREVIOUS document is now orphaned: it muted a dead element
+    // (so the fresh, unmuted one plays dry) and its stream starves. Bumping
+    // this after the reload settles makes useVstPreview reconcile against the
+    // new DOM — tear the stale track down and reload it against the live
+    // element. (Idempotent when nothing changed: the chain-key check no-ops.)
+    usePlayerStore.getState().bumpVstChainRevision();
   }, [baseOnIframeLoad, iframeRef, onIframeRef]);
 
   const {
@@ -307,6 +336,7 @@ export function NLEProvider({
     seek,
     refreshPlayer,
     onIframeLoad,
+    vstHost,
     compositionStack,
     updateCompositionStack,
     handleNavigateComposition,
diff --git a/packages/studio/src/hooks/useVstHost.test.tsx b/packages/studio/src/hooks/useVstHost.test.tsx
new file mode 100644
index 0000000000..b46d03c38b
--- /dev/null
+++ b/packages/studio/src/hooks/useVstHost.test.tsx
@@ -0,0 +1,658 @@
+// @vitest-environment happy-dom
+
+import React, { StrictMode, act } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { Root } from "react-dom/client";
+import type { ChainFileJson } from "../utils/vstChainFile";
+import { mountReactHarness } from "./domSelectionTestHarness";
+import { __setSocketFactoryForTests, useVstHost } from "./useVstHost";
+import { FakeSocket, required } from "./vstSocketTestFixture";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+// ── Test helpers ──────────────────────────────────────────────────────────────
+
+async function flushAsyncWork(): Promise<void> {
+  for (let i = 0; i < 8; i += 1) {
+    await Promise.resolve();
+  }
+}
+
+type HookResult = ReturnType<typeof useVstHost>;
+
+function renderVstHost(onReady: (result: HookResult) => void): Root {
+  function Harness() {
+    const result = useVstHost();
+    onReady(result);
+    return null;
+  }
+  return mountReactHarness(<Harness />);
+}
+
+const TEST_TOKEN = "test-token-abc123";
+
+function okStartResponse(port: number, token: string = TEST_TOKEN): Response {
+  return new Response(JSON.stringify({ port, token }), {
+    status: 200,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+/** Mounts the hook without driving `ensureStarted()` — the caller controls the fetch/socket sequence. */
+function mountUnstartedHost(): { getLatest: () => HookResult | null; root: Root } {
+  let latest: HookResult | null = null;
+  const root = renderVstHost((r) => {
+    latest = r;
+  });
+  return { getLatest: () => latest, root };
+}
+
+/**
+ * Races `promise` against a short timer to prove it settles on its own
+ * (rather than hanging forever) and, if so, whether it rejected. Used by the
+ * "superseded" tests below to confirm a pre-empted pending command's promise
+ * resolves instead of hanging.
+ */
+async function raceSettleOutcome(
+  promise: Promise<unknown>,
+): Promise<{ settled: boolean; rejected: boolean; err: unknown }> {
+  const outcome: { settled: boolean; rejected: boolean; err: unknown } = {
+    settled: false,
+    rejected: false,
+    err: null,
+  };
+  await Promise.race([
+    promise.then(
+      () => {
+        outcome.settled = true;
+      },
+      (err: unknown) => {
+        outcome.settled = true;
+        outcome.rejected = true;
+        outcome.err = err;
+      },
+    ),
+    new Promise<void>((resolve) => setTimeout(resolve, 100)),
+  ]);
+  return outcome;
+}
+
+/** Asserts a `raceSettleOutcome` result rejected with a "superseded" error. */
+function expectSupersededRejection(outcome: {
+  settled: boolean;
+  rejected: boolean;
+  err: unknown;
+}): void {
+  // If this is false, the promise never settled within 100ms — i.e. it hung.
+  expect(outcome.settled).toBe(true);
+  expect(outcome.rejected).toBe(true);
+  expect(outcome.err).toBeInstanceOf(Error);
+  if (outcome.err instanceof Error) {
+    expect(outcome.err.message).toMatch(/superseded/);
+  }
+}
+
+/** Stubs `fetch` with `fetchMock` and calls `ensureStarted()` on a freshly
+ *  mounted (not-yet-started) host, swallowing its rejection — the shared
+ *  "attempt a start that's expected to fail" shape the tests below need. */
+async function ensureStartedFailing(
+  fetchMock: ReturnType<typeof vi.fn>,
+): Promise<{ getLatest: () => HookResult | null; root: Root }> {
+  vi.stubGlobal("fetch", fetchMock);
+  const { getLatest, root } = mountUnstartedHost();
+  await act(async () => {
+    await required<HookResult>(getLatest(), "hook result")
+      .ensureStarted()
+      .catch(() => {});
+  });
+  return { getLatest, root };
+}
+
+async function setupReadyHost(): Promise<{
+  getState: () => HookResult;
+  socket: FakeSocket;
+  root: Root;
+  fetchMock: ReturnType<typeof vi.fn>;
+}> {
+  const fetchMock = vi.fn(async () => okStartResponse(4321));
+  vi.stubGlobal("fetch", fetchMock);
+
+  const { getLatest, root } = mountUnstartedHost();
+
+  await act(async () => {
+    const startPromise = required<HookResult>(getLatest(), "hook result").ensureStarted();
+    await flushAsyncWork();
+    required<FakeSocket>(FakeSocket.instances[0], "socket instance").open();
+    await startPromise;
+  });
+
+  return {
+    getState: () => required<HookResult>(getLatest(), "hook result"),
+    socket: required<FakeSocket>(FakeSocket.instances[0], "socket instance"),
+    root,
+    fetchMock,
+  };
+}
+
+beforeEach(() => {
+  FakeSocket.instances = [];
+  __setSocketFactoryForTests((url) => new FakeSocket(url));
+});
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  __setSocketFactoryForTests(null);
+  vi.unstubAllGlobals();
+});
+
+// ── ensureStarted ─────────────────────────────────────────────────────────────
+
+describe("useVstHost — ensureStarted", () => {
+  it("posts to /api/vst/start once and opens a socket to the returned port", async () => {
+    const { getState, socket, root, fetchMock } = await setupReadyHost();
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock.mock.calls[0]?.[0]).toBe("/api/vst/start");
+    expect(socket.url).toContain(":4321");
+    expect(getState().status).toBe("ready");
+    expect(getState().api).not.toBeNull();
+
+    // A second call while already ready must not re-POST.
+    await act(async () => {
+      await getState().ensureStarted();
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    act(() => root.unmount());
+  });
+
+  // Finding 2 (final whole-branch review): the sidecar requires a
+  // shared-secret token (see server.py's `_authenticate`) on every
+  // connection — `/vst/start` relays it, and the client must thread it into
+  // the WS URL as a `?token=` query param or the sidecar's handshake hook
+  // rejects the upgrade before any command can be sent.
+  it("connects with the token from /api/vst/start as a ?token= query param", async () => {
+    const { socket, root } = await setupReadyHost();
+
+    expect(socket.url).toContain(`token=${TEST_TOKEN}`);
+
+    act(() => root.unmount());
+  });
+
+  it("fails to start when the response is missing a token", async () => {
+    // A response body missing `token` entirely (not just empty) — simulates
+    // a studio-server build that hasn't relayed it yet.
+    const missingTokenResponse = new Response(JSON.stringify({ port: 4321 }), {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    });
+    const { getLatest, root } = await ensureStartedFailing(vi.fn(async () => missingTokenResponse));
+
+    expect(required<HookResult>(getLatest(), "hook result").status).toBe("failed");
+    expect(required<HookResult>(getLatest(), "hook result").api).toBeNull();
+    // No socket should ever have been opened without a valid token.
+    expect(FakeSocket.instances).toHaveLength(0);
+
+    act(() => root.unmount());
+  });
+
+  it("sets status to failed and surfaces installHint when the start request fails", async () => {
+    const { getLatest, root } = await ensureStartedFailing(
+      vi.fn(
+        async () =>
+          new Response(JSON.stringify({ error: "no uv", installHint: "install uv" }), {
+            status: 503,
+            headers: { "content-type": "application/json" },
+          }),
+      ),
+    );
+
+    expect(required<HookResult>(getLatest(), "hook result").status).toBe("failed");
+    expect(required<HookResult>(getLatest(), "hook result").installHint).toBe("install uv");
+    expect(required<HookResult>(getLatest(), "hook result").api).toBeNull();
+
+    act(() => root.unmount());
+  });
+});
+
+// ── scan ──────────────────────────────────────────────────────────────────────
+
+describe("useVstHost — scan", () => {
+  it("resolves when a registry event arrives and updates api.registry", async () => {
+    const { getState, socket, root } = await setupReadyHost();
+
+    let scanPromise: Promise<void> | null = null;
+    await act(async () => {
+      const api = required(getState().api, "api");
+      scanPromise = api.scan();
+      await flushAsyncWork();
+      socket.emitJson({
+        event: "registry",
+        plugins: [{ path: "/plugins/Reverb.vst3", name: "Reverb", format: "vst3" }],
+      });
+      await required(scanPromise, "scan promise");
+    });
+
+    expect(required(getState().api, "api").registry).toEqual([
+      { path: "/plugins/Reverb.vst3", name: "Reverb", format: "vst3" },
+    ]);
+
+    act(() => root.unmount());
+  });
+});
+
+// ── loadChain ─────────────────────────────────────────────────────────────────
+
+describe("useVstHost — loadChain", () => {
+  it("rejects with the plugin name on a plugin_missing error for that trackId", async () => {
+    const { getState, socket, root } = await setupReadyHost();
+    const chain: ChainFileJson = { version: 1, plugins: [] };
+
+    let rejection: unknown;
+    await act(async () => {
+      const api = required(getState().api, "api");
+      const loadPromise = api.loadChain("track-1", chain, "/abs/dry.wav");
+      await flushAsyncWork();
+      socket.emitJson({
+        event: "error",
+        code: "plugin_missing",
+        plugin: "Missing FX",
+        trackId: "track-1",
+      });
+      await loadPromise.catch((err: unknown) => {
+        rejection = err;
+      });
+    });
+
+    expect(rejection).toBeInstanceOf(Error);
+    if (rejection instanceof Error) {
+      expect(rejection.message).toBe("Missing FX");
+    }
+
+    const sentLoadChain = socket.sent.find((raw) => raw.includes('"cmd":"load-chain"'));
+    expect(sentLoadChain).toBeDefined();
+    expect(sentLoadChain).toContain('"wavPath":"/abs/dry.wav"');
+
+    act(() => root.unmount());
+  });
+
+  it("rejects the first call's promise as superseded when a second loadChain for the same trackId is issued first", async () => {
+    const { getState, socket, root } = await setupReadyHost();
+    const chain: ChainFileJson = { version: 1, plugins: [] };
+
+    let secondResolved = false;
+    let firstOutcome: { settled: boolean; rejected: boolean; err: unknown } = {
+      settled: false,
+      rejected: false,
+      err: null,
+    };
+
+    await act(async () => {
+      const api = required(getState().api, "api");
+      const firstPromise = api.loadChain("track-1", chain, "/abs/dry1.wav");
+      await flushAsyncWork();
+      const secondPromise = api.loadChain("track-1", chain, "/abs/dry2.wav");
+      await flushAsyncWork();
+
+      // Only the second request gets a server reply.
+      socket.emitJson({ event: "chain-loaded", trackId: "track-1", sampleRate: 48000 });
+
+      await secondPromise.then(() => {
+        secondResolved = true;
+      });
+
+      // The first promise must settle (reject) on its own — it never gets a
+      // matching server reply. Race it against a short timer so an unfixed
+      // hang fails the test instead of hanging the whole run.
+      firstOutcome = await raceSettleOutcome(firstPromise);
+    });
+
+    expect(secondResolved).toBe(true);
+    expectSupersededRejection(firstOutcome);
+
+    act(() => root.unmount());
+  });
+
+  it("a getState for the same track does NOT supersede an in-flight loadChain (different kinds, different consumers)", async () => {
+    // Live-repro'd collision: useVstPreview's loadChain and the FX panel's
+    // 400ms getState polling run concurrently for the SAME track over this
+    // shared connection. With the pending map keyed by trackId alone, each
+    // poll clobbered + spuriously rejected the in-flight loadChain
+    // ("get-state superseded…"), so on a machine slow enough for the load to
+    // still be pending when a poll landed, the track never loaded — silent
+    // music, transport forever seeing zero loaded tracks.
+    const { getState, socket, root } = await setupReadyHost();
+    const chain: ChainFileJson = { version: 1, plugins: [] };
+
+    let loadResult: unknown = null;
+    let loadError: unknown = null;
+    let stateResult: string[] | null = null;
+
+    await act(async () => {
+      const api = required(getState().api, "api");
+      const loadPromise = api.loadChain("track-1", chain, "/abs/dry.wav");
+      await flushAsyncWork();
+      // Panel poll lands while the load is still in flight.
+      const statePromise = api.getState("track-1");
+      await flushAsyncWork();
+
+      // Sidecar answers both commands, in order.
+      socket.emitJson({ event: "chain-loaded", trackId: "track-1", sampleRate: 48000 });
+      socket.emitJson({ event: "state", trackId: "track-1", plugins: ["c3RhdGU="] });
+
+      await loadPromise.then(
+        (r) => {
+          loadResult = r;
+        },
+        (err: unknown) => {
+          loadError = err;
+        },
+      );
+      stateResult = await statePromise;
+    });
+
+    expect(loadError).toBeNull(); // the poll must not have rejected the load
+    expect(loadResult).toMatchObject({ sampleRate: 48000, stable: true });
+    expect(stateResult).toEqual(["c3RhdGU="]);
+
+    act(() => root.unmount());
+  });
+});
+
+// ── getState ──────────────────────────────────────────────────────────────────
+
+describe("useVstHost — getState", () => {
+  it("resolves with the plugin list from a matching state event", async () => {
+    const { getState, socket, root } = await setupReadyHost();
+
+    let result: string[] | null = null;
+    await act(async () => {
+      const api = required(getState().api, "api");
+      const statePromise = api.getState("track-1");
+      await flushAsyncWork();
+      socket.emitJson({ event: "state", trackId: "track-1", plugins: ["Reverb.vst3"] });
+      result = await statePromise;
+    });
+
+    expect(result).toEqual(["Reverb.vst3"]);
+
+    act(() => root.unmount());
+  });
+
+  it("rejects the first call's promise as superseded when a second getState for the same trackId is issued first", async () => {
+    const { getState, socket, root } = await setupReadyHost();
+
+    let secondResult: string[] | null = null;
+    let firstOutcome: { settled: boolean; rejected: boolean; err: unknown } = {
+      settled: false,
+      rejected: false,
+      err: null,
+    };
+
+    await act(async () => {
+      const api = required(getState().api, "api");
+      const firstPromise = api.getState("track-1");
+      await flushAsyncWork();
+      const secondPromise = api.getState("track-1");
+      await flushAsyncWork();
+
+      // Only the second request gets a server reply.
+      socket.emitJson({ event: "state", trackId: "track-1", plugins: ["Reverb.vst3"] });
+
+      secondResult = await secondPromise;
+
+      // The first promise must settle (reject) on its own — it never gets a
+      // matching server reply. Race it against a short timer so an unfixed
+      // hang fails the test instead of hanging the whole run.
+      firstOutcome = await raceSettleOutcome(firstPromise);
+    });
+
+    expect(secondResult).toEqual(["Reverb.vst3"]);
+    expectSupersededRejection(firstOutcome);
+
+    act(() => root.unmount());
+  });
+});
+
+// ── trackIndex mirroring + onChainLoaded ───────────────────────────────────────
+
+describe("useVstHost — trackIndex mirroring", () => {
+  it("resolves loadChain with the sidecar's assigned trackIndex per trackId", async () => {
+    const { getState, socket, root } = await setupReadyHost();
+    const chain: ChainFileJson = { version: 1, plugins: [] };
+
+    let indexTrack1 = -1;
+    let indexTrack2 = -1;
+    await act(async () => {
+      const api = required(getState().api, "api");
+      const p1 = api.loadChain("track-1", chain, "/abs/dry1.wav");
+      await flushAsyncWork();
+      socket.emitJson({ event: "chain-loaded", trackId: "track-1", sampleRate: 48000 });
+      indexTrack1 = (await p1).trackIndex;
+
+      const p2 = api.loadChain("track-2", chain, "/abs/dry2.wav");
+      await flushAsyncWork();
+      socket.emitJson({ event: "chain-loaded", trackId: "track-2", sampleRate: 48000 });
+      indexTrack2 = (await p2).trackIndex;
+    });
+
+    expect(indexTrack1).toBe(0);
+    expect(indexTrack2).toBe(1);
+
+    act(() => root.unmount());
+  });
+
+  it("mirrors the server's pop-then-reinsert rule: reloading an earlier track can reuse a later track's index", async () => {
+    // Mirrors stream.py's server-side rule exactly (see assignNextTrackIndex's
+    // doc-comment): `self._tracks.pop(track_id, None)` then
+    // `TrackStream(len(self._tracks), ...)`. Two tracks loaded in order get
+    // indices 0 and 1; reloading the FIRST one pops it (leaving one entry),
+    // so it's reassigned `len == 1` — the same index track-2 already holds.
+    // This is the real collision the sidecar's own design can produce, not a
+    // client-side bug — the assertion below documents that faithfully
+    // mirroring the server surfaces the same number, so a subscriber can at
+    // least detect it (see useVstPreview's onChainLoaded handler).
+    const { getState, socket, root } = await setupReadyHost();
+    const chain: ChainFileJson = { version: 1, plugins: [] };
+
+    const seenIndexes: Record<string, number> = {};
+    await act(async () => {
+      const api = required(getState().api, "api");
+      getState().onChainLoaded((trackId, trackIndex) => {
+        seenIndexes[trackId] = trackIndex;
+      });
+
+      const p1 = api.loadChain("track-1", chain, "/abs/dry1.wav");
+      await flushAsyncWork();
+      socket.emitJson({ event: "chain-loaded", trackId: "track-1", sampleRate: 48000 });
+      await p1;
+
+      const p2 = api.loadChain("track-2", chain, "/abs/dry2.wav");
+      await flushAsyncWork();
+      socket.emitJson({ event: "chain-loaded", trackId: "track-2", sampleRate: 48000 });
+      await p2;
+
+      // Reload track-1's chain (e.g. the FX panel adding/removing an effect).
+      const p3 = api.loadChain("track-1", chain, "/abs/dry1.wav");
+      await flushAsyncWork();
+      socket.emitJson({ event: "chain-loaded", trackId: "track-1", sampleRate: 48000 });
+      await p3;
+    });
+
+    expect(seenIndexes["track-2"]).toBe(1);
+    expect(seenIndexes["track-1"]).toBe(1); // reassigned — now collides with track-2
+
+    act(() => root.unmount());
+  });
+
+  it("broadcasts a chain-loaded event to every onChainLoaded subscriber, not just the calling promise", async () => {
+    const { getState, socket, root } = await setupReadyHost();
+
+    const observed: Array<{ trackId: string; trackIndex: number }> = [];
+    let unsubscribe: (() => void) | null = null;
+
+    await act(async () => {
+      unsubscribe = getState().onChainLoaded((trackId, trackIndex) => {
+        observed.push({ trackId, trackIndex });
+      });
+
+      // Nobody is awaiting a loadChain promise here — the event still fires.
+      socket.emitJson({ event: "chain-loaded", trackId: "track-9", sampleRate: 48000 });
+      await flushAsyncWork();
+    });
+
+    expect(observed).toEqual([{ trackId: "track-9", trackIndex: 0 }]);
+
+    required<() => void>(unsubscribe, "unsubscribe")();
+    await act(async () => {
+      socket.emitJson({ event: "chain-loaded", trackId: "track-9", sampleRate: 48000 });
+      await flushAsyncWork();
+    });
+    expect(observed).toHaveLength(1); // no further notifications after unsubscribing
+
+    act(() => root.unmount());
+  });
+});
+
+// ── PCM frames ────────────────────────────────────────────────────────────────
+
+describe("useVstHost — onPcmFrame", () => {
+  it("forwards a raw binary frame to subscribers without decoding it", async () => {
+    const { getState, socket, root } = await setupReadyHost();
+
+    const received: ArrayBuffer[] = [];
+    const unsubscribe = getState().onPcmFrame((frame) => received.push(frame));
+
+    const buf = new ArrayBuffer(16);
+    act(() => {
+      socket.emitBinary(buf);
+    });
+
+    expect(received).toHaveLength(1);
+    expect(received[0]).toBe(buf);
+
+    unsubscribe();
+    act(() => {
+      socket.emitBinary(new ArrayBuffer(4));
+    });
+    expect(received).toHaveLength(1);
+
+    act(() => root.unmount());
+  });
+});
+
+// ── disconnect ────────────────────────────────────────────────────────────────
+
+describe("useVstHost — disconnect", () => {
+  it("fires onDisconnect subscribers and flips status to failed when the socket closes", async () => {
+    const { getState, socket, root } = await setupReadyHost();
+
+    const disconnects: number[] = [];
+    getState().onDisconnect(() => disconnects.push(1));
+
+    await act(async () => {
+      socket.close();
+      await flushAsyncWork();
+    });
+
+    expect(disconnects).toHaveLength(1);
+    expect(getState().status).toBe("failed");
+    expect(getState().api).toBeNull();
+
+    act(() => root.unmount());
+  });
+});
+
+// ── unmount cleanup ───────────────────────────────────────────────────────────
+// A genuine unmount (component removed from the tree for good) must close
+// any open/in-flight socket — otherwise it keeps streaming from the sidecar
+// alongside whatever else is running, which is what a live repro traced back
+// to two competing live audio pipelines mixing into one output ("crackling,
+// can't tell which track", never recovering).
+
+describe("useVstHost — unmount cleanup", () => {
+  it("closes an already-open socket when the hook unmounts", async () => {
+    const { socket, root } = await setupReadyHost();
+
+    expect(socket.closed).toBe(false);
+    act(() => root.unmount());
+    expect(socket.closed).toBe(true);
+  });
+
+  it("closes a connection that finishes AFTER unmount instead of leaking it", async () => {
+    const fetchMock = vi.fn(async () => okStartResponse(4321));
+    vi.stubGlobal("fetch", fetchMock);
+
+    const { getLatest, root } = mountUnstartedHost();
+
+    let ensureStartedPromise: Promise<void> = Promise.resolve();
+    await act(async () => {
+      ensureStartedPromise = required<HookResult>(getLatest(), "hook result").ensureStarted();
+      await flushAsyncWork();
+    });
+
+    const socket = required<FakeSocket>(FakeSocket.instances[0], "socket instance");
+    // Unmount BEFORE the socket finishes connecting (`open()` never called
+    // yet) — simulates a StrictMode phantom mount whose async attempt is
+    // still in flight when React discards it.
+    act(() => root.unmount());
+    expect(socket.closed).toBe(false); // not open yet — nothing to close
+
+    // The connection now resolves, after unmount already ran.
+    await act(async () => {
+      socket.open();
+      await ensureStartedPromise;
+    });
+
+    expect(socket.closed).toBe(true);
+  });
+});
+
+// ── StrictMode double-invoke ──────────────────────────────────────────────────
+// React StrictMode (enabled in packages/studio/src/main.tsx, dev-mode only)
+// double-invokes effects on mount: mount, cleanup, mount again — on the SAME
+// component instance and the SAME refs, not a fresh remount with fresh state.
+// A regression here: the unmount-cleanup effect above sets `unmountedRef` to
+// `true` unconditionally and nothing ever reset it back to `false` for the
+// real, surviving mount — so StrictMode's own diagnostic cleanup pass
+// permanently poisoned every later `ensureStarted()` call for the rest of the
+// component's real lifetime, closing its own socket immediately after
+// connecting. That read as a permanent, unrecoverable "VST host disconnected"
+// even on a freshly loaded page — caught only by actually running the hook
+// under a real `<StrictMode>` wrapper, not by unmount/remount tests using two
+// separate root instances (those don't share refs, so they can't reproduce
+// same-instance state leaking across the double-invoke).
+
+describe("useVstHost — StrictMode double-invoke", () => {
+  it("still connects successfully after StrictMode's mount/cleanup/mount on the same instance", async () => {
+    const fetchMock = vi.fn(async () => okStartResponse(4321));
+    vi.stubGlobal("fetch", fetchMock);
+
+    const state: { latest: HookResult | null } = { latest: null };
+    function Harness() {
+      const result = useVstHost();
+      state.latest = result;
+      return null;
+    }
+    const root = mountReactHarness(
+      <StrictMode>
+        <Harness />
+      </StrictMode>,
+    );
+
+    await act(async () => {
+      const startPromise = required<HookResult>(state.latest, "hook result").ensureStarted();
+      await flushAsyncWork();
+      required<FakeSocket>(FakeSocket.instances[0], "socket instance").open();
+      await startPromise;
+    });
+
+    // The connection StrictMode's phantom cleanup pass may have closed is a
+    // separate, expected socket instance — what matters is the CURRENT state
+    // the component ends up in after settling.
+    expect(state.latest?.status).toBe("ready");
+    expect(state.latest?.api).not.toBeNull();
+
+    act(() => root.unmount());
+  });
+});
diff --git a/packages/studio/src/hooks/useVstHost.ts b/packages/studio/src/hooks/useVstHost.ts
new file mode 100644
index 0000000000..8af08da9de
--- /dev/null
+++ b/packages/studio/src/hooks/useVstHost.ts
@@ -0,0 +1,356 @@
+/**
+ * React hook that lazily starts the VST sidecar (`POST /api/vst/start`,
+ * built in Task 10) and manages a WebSocket connection to it, implementing
+ * the `VstHostApi` interface `propertyPanelVstSection.tsx` (Task 11)
+ * consumes but doesn't provide.
+ *
+ * The wire protocol (control-JSON parsing, binary-PCM passthrough, the
+ * pending-request bookkeeping, and the `/api/vst/start` + WebSocket connect
+ * sequence) lives in `vstHostWire.ts` — this file is just the React
+ * lifecycle: refs, effects, and the `VstHostApi` methods built on top.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type {
+  LoadChainResult,
+  VstHostApi,
+  VstRegistryEntry,
+} from "../components/editor/propertyPanelVstShared";
+import type { ChainFileJson } from "../utils/vstChainFile";
+import {
+  connectVstSocket,
+  DISCONNECTED_ERROR,
+  parseServerEvent,
+  applyServerEvent,
+  pendingKey,
+  requestVstStart,
+  type PendingScanEntry,
+  type PendingTrackEntry,
+  type VstSocketLike,
+} from "./vstHostWire";
+
+export { __setSocketFactoryForTests, type VstSocketLike } from "./vstHostWire";
+
+// ── Public types ──────────────────────────────────────────────────────────────
+
+export type VstHostStatus = "idle" | "starting" | "ready" | "failed";
+
+/** Mirrors the sidecar's `{"cmd":"transport",...}` command (see server.py's `_transport`). */
+export type TransportMsg =
+  | { action: "play"; timeSec?: number; rate?: number }
+  | { action: "pause" }
+  | { action: "seek"; timeSec: number };
+
+export interface UseVstHostResult {
+  api: VstHostApi | null;
+  status: VstHostStatus;
+  installHint: string | null;
+  /** Idempotent: posts `/api/vst/start` and opens the WS at most once per connection attempt. */
+  ensureStarted: () => Promise<void>;
+  onPcmFrame: (cb: (frame: ArrayBuffer) => void) => () => void;
+  sendTransport: (msg: TransportMsg) => void;
+  onDisconnect: (cb: () => void) => () => void;
+  /**
+   * Broadcasts every `chain-loaded` event this connection sees, regardless of
+   * which caller's `loadChain()` triggered it — the sidecar reassigns a
+   * track's numeric wire `trackIndex` on every reload (see
+   * `assignNextTrackIndex` in vstHostWire.ts), so a consumer holding an
+   * earlier index for `trackId` (e.g. `useVstPreview`, if the FX panel
+   * reloads a chain it already streamed) must resync from this, not just its
+   * own `loadChain` call's resolved value.
+   */
+  onChainLoaded: (cb: (trackId: string, trackIndex: number) => void) => () => void;
+}
+
+// ── Hook ──────────────────────────────────────────────────────────────────────
+
+export function useVstHost(): UseVstHostResult {
+  const [status, setStatus] = useState<VstHostStatus>("idle");
+  const [installHint, setInstallHint] = useState<string | null>(null);
+
+  const socketRef = useRef<VstSocketLike | null>(null);
+  const startPromiseRef = useRef<Promise<void> | null>(null);
+  const handledDisconnectRef = useRef(false);
+  // Set while this hook instance is unmounted — checked by `ensureStarted`'s
+  // async attempt after its socket finishes connecting, so a connect that
+  // resolves AFTER unmount closes the now-orphaned socket instead of leaving
+  // it open. Without this, an unmounted instance's in-flight connection isn't
+  // cancellable (a `useEffect` cleanup can't interrupt a promise already in
+  // flight), so the socket stays open and keeps streaming from the sidecar
+  // alongside whichever instance actually remounted — two live audio
+  // pipelines mixing into the same output is what reads as "crackling, can't
+  // tell which track" and a stream that never recovers.
+  //
+  // React StrictMode (dev mode) double-invokes this effect on the SAME
+  // component instance — mount, cleanup, mount again — not a fresh instance
+  // with a fresh ref. The reset at the top of the effect body is required:
+  // without it, StrictMode's own diagnostic cleanup pass permanently flips
+  // this to `true` and every later `ensureStarted()` call for the rest of
+  // the component's real lifetime sees a stale "unmounted" flag and closes
+  // its own socket immediately — READING AS A PERMANENT, UNRECOVERABLE
+  // "VST host disconnected" even on a freshly loaded page.
+  const unmountedRef = useRef(false);
+  useEffect(() => {
+    unmountedRef.current = false;
+    return () => {
+      unmountedRef.current = true;
+      socketRef.current?.close();
+    };
+  }, []);
+
+  // Mutated in place (never reassigned) so any `api` snapshot handed to a
+  // caller keeps seeing fresh contents after `scan()` resolves, matching how
+  // propertyPanelVstSection.tsx re-reads `vstHost.registry` after awaiting scan.
+  const registryRef = useRef<VstRegistryEntry[]>([]);
+
+  const pendingScanRef = useRef<PendingScanEntry | null>(null);
+  const pendingTrackRef = useRef<Map<string, PendingTrackEntry>>(new Map());
+
+  // Mirrors the sidecar's `self._tracks` insertion order (see
+  // `assignNextTrackIndex` in vstHostWire.ts) — mutated in place, never
+  // reassigned, same rationale as `registryRef` above.
+  const trackIndexRef = useRef<Map<string, number>>(new Map());
+  const chainLoadedListenersRef = useRef<Set<(trackId: string, trackIndex: number) => void>>(
+    new Set(),
+  );
+
+  const pcmListenersRef = useRef<Set<(frame: ArrayBuffer) => void>>(new Set());
+  const disconnectListenersRef = useRef<Set<() => void>>(new Set());
+
+  const sendJson = useCallback((payload: Record<string, unknown>) => {
+    socketRef.current?.send(JSON.stringify(payload));
+  }, []);
+
+  const handleDisconnect = useCallback(() => {
+    if (handledDisconnectRef.current) return;
+    handledDisconnectRef.current = true;
+    setStatus("failed");
+
+    const scanPending = pendingScanRef.current;
+    pendingScanRef.current = null;
+    scanPending?.reject(new Error(DISCONNECTED_ERROR));
+
+    for (const entry of pendingTrackRef.current.values()) {
+      entry.reject(new Error(DISCONNECTED_ERROR));
+    }
+    pendingTrackRef.current.clear();
+
+    // A WebSocket close/error does NOT imply the sidecar process (and its
+    // server-side `_tracks` dict) was torn down. `startVstSidecar`
+    // (packages/studio-server/src/vstSidecar.ts) is a singleton — "Only one
+    // sidecar runs per host process... a second call while one is already
+    // running returns the same instance" — and it's only ever killed by an
+    // explicit `stopVstSidecar()` tied to CLI shutdown, never by an
+    // individual socket closing. A plain WS disconnect (network blip,
+    // dev-server hiccup) leaves that process, and every track it already
+    // holds in `_tracks`, running and untouched in the common case.
+    //
+    // So `trackIndexRef` is deliberately left as-is here instead of reset to
+    // an assumed-empty map: clearing it would make this client recompute
+    // indices from a false "fresh sidecar" premise while the server (in that
+    // common same-process-reconnect case) is still working from its real,
+    // non-empty dict — exactly the mismatch that let two tracks silently
+    // collide on the wire after a reconnect. Leaving the mirror untouched
+    // keeps it accurate in that common case; on the rarer path where the
+    // process really was restarted (e.g. it crashed and exited), the mirror
+    // can still end up stale either way, so this alone is not a full
+    // guarantee.
+    //
+    // `useVstPreview` (a separate consumer of this hook, alongside the FX
+    // property panel) does not rely on this mirror staying correct at all
+    // post-disconnect: rather than trying to keep recomputing a trustworthy
+    // index for tracks it already streamed, it permanently stops issuing
+    // `load-chain` for ANYTHING — old or new — the first time it observes
+    // any disconnect (see its `suspendedRef`). This mirror is kept as-is
+    // here as forward-defensive infrastructure, not because some other
+    // active caller depends on it: grepping propertyPanelVstSection.tsx (the
+    // FX property panel) shows it never calls `loadChain` — only
+    // `useVstPreview` does — and that hook's doc-comment already notes the
+    // "FX panel calls loadChain post-reconnect" scenario this comment used to
+    // describe was aspirational, not real (see useVstPreview.ts's crash-
+    // fallback doc-comment). If a future caller of this shared `useVstHost()`
+    // connection ever does call `loadChain` directly (not through
+    // `useVstPreview`), this mirror staying accurate across a same-process
+    // reconnect is what makes that safe.
+
+    disconnectListenersRef.current.forEach((cb) => cb());
+  }, []);
+
+  const handleMessage = useCallback((ev: MessageEvent) => {
+    // `MessageEvent.data` is typed `any` in lib.dom — no cast needed to pass
+    // it through to a `(frame: ArrayBuffer) => void` subscriber once the
+    // `instanceof` check below confirms it's actually a binary frame.
+    if (ev.data instanceof ArrayBuffer) {
+      pcmListenersRef.current.forEach((cb) => cb(ev.data));
+      return;
+    }
+    if (typeof ev.data !== "string") return;
+
+    const parsed = parseServerEvent(ev.data);
+    if (!parsed) return;
+
+    applyServerEvent(parsed, {
+      registry: registryRef.current,
+      pendingScan: pendingScanRef,
+      pendingTrack: pendingTrackRef.current,
+      trackIndex: trackIndexRef.current,
+      chainLoadedListeners: chainLoadedListenersRef.current,
+    });
+  }, []);
+
+  // ── ensureStarted ───────────────────────────────────────────────────────────
+
+  const ensureStarted = useCallback((): Promise<void> => {
+    if (status === "ready" && socketRef.current) return Promise.resolve();
+    if (startPromiseRef.current) return startPromiseRef.current;
+
+    setStatus("starting");
+    setInstallHint(null);
+    handledDisconnectRef.current = false;
+
+    const attempt = (async () => {
+      const outcome = await requestVstStart();
+      if (!outcome.ok) {
+        setInstallHint(outcome.installHint);
+        setStatus("failed");
+        throw new Error(outcome.message);
+      }
+
+      const socket = await connectVstSocket(outcome.port, outcome.token, {
+        onMessage: handleMessage,
+        onReady: () => setStatus("ready"),
+        onDisconnect: handleDisconnect,
+      });
+      // This attempt was started before an unmount (StrictMode's dev-mode
+      // phantom mount/unmount included) but only finished connecting after
+      // it — the unmount's cleanup already ran and can't be re-run to close
+      // a socket that didn't exist yet. Close it here instead of handing it
+      // to a component that's gone; otherwise it keeps streaming from the
+      // sidecar alongside whatever instance actually remounted.
+      if (unmountedRef.current) {
+        socket.close();
+        return;
+      }
+      socketRef.current = socket;
+    })();
+
+    const settled = attempt.finally(() => {
+      startPromiseRef.current = null;
+    });
+    startPromiseRef.current = settled;
+    return settled;
+  }, [status, handleMessage, handleDisconnect]);
+
+  // ── VstHostApi methods ──────────────────────────────────────────────────────
+
+  const scan = useCallback((): Promise<void> => {
+    return new Promise<void>((resolve, reject) => {
+      const previous = pendingScanRef.current;
+      previous?.reject(new Error("scan superseded by a new scan"));
+      pendingScanRef.current = { resolve, reject };
+      sendJson({ cmd: "scan" });
+    });
+  }, [sendJson]);
+
+  const openEditor = useCallback(
+    (trackId: string, pluginIndex: number): void => {
+      sendJson({ cmd: "open-editor", trackId, pluginIndex });
+    },
+    [sendJson],
+  );
+
+  const setParam = useCallback(
+    (trackId: string, pluginIndex: number, param: string, value: number): void => {
+      sendJson({ cmd: "set-param", trackId, pluginIndex, param, value });
+    },
+    [sendJson],
+  );
+
+  // Supersede semantics are per-KIND (see `pendingKey`): a newer load-chain
+  // replaces an older load-chain for the same track, and likewise for
+  // get-state — but the two kinds never clobber each other. They're issued
+  // concurrently for the same track by different consumers of this shared
+  // connection (useVstPreview loads while the FX panel polls state).
+  const loadChain = useCallback(
+    (trackId: string, chain: ChainFileJson, wavUrl: string): Promise<LoadChainResult> => {
+      return new Promise<LoadChainResult>((resolve, reject) => {
+        const key = pendingKey("load-chain", trackId);
+        const previous = pendingTrackRef.current.get(key);
+        previous?.reject(
+          new Error(`load-chain superseded by a new request for track "${trackId}"`),
+        );
+        pendingTrackRef.current.set(key, { kind: "load-chain", resolve, reject });
+        sendJson({ cmd: "load-chain", trackId, chainJson: chain, wavPath: wavUrl });
+      });
+    },
+    [sendJson],
+  );
+
+  const getState = useCallback(
+    (trackId: string): Promise<string[]> => {
+      return new Promise<string[]>((resolve, reject) => {
+        const key = pendingKey("get-state", trackId);
+        const previous = pendingTrackRef.current.get(key);
+        previous?.reject(new Error(`get-state superseded by a new request for track "${trackId}"`));
+        pendingTrackRef.current.set(key, { kind: "get-state", resolve, reject });
+        sendJson({ cmd: "get-state", trackId });
+      });
+    },
+    [sendJson],
+  );
+
+  const api = useMemo<VstHostApi>(
+    () => ({
+      registry: registryRef.current,
+      scan,
+      openEditor,
+      setParam,
+      loadChain,
+      getState,
+    }),
+    [scan, openEditor, setParam, loadChain, getState],
+  );
+
+  // ── Transport + subscribers ──────────────────────────────────────────────────
+
+  const sendTransport = useCallback(
+    (msg: TransportMsg): void => {
+      sendJson({ cmd: "transport", ...msg });
+    },
+    [sendJson],
+  );
+
+  const onPcmFrame = useCallback((cb: (frame: ArrayBuffer) => void): (() => void) => {
+    pcmListenersRef.current.add(cb);
+    return () => {
+      pcmListenersRef.current.delete(cb);
+    };
+  }, []);
+
+  const onDisconnect = useCallback((cb: () => void): (() => void) => {
+    disconnectListenersRef.current.add(cb);
+    return () => {
+      disconnectListenersRef.current.delete(cb);
+    };
+  }, []);
+
+  const onChainLoaded = useCallback(
+    (cb: (trackId: string, trackIndex: number) => void): (() => void) => {
+      chainLoadedListenersRef.current.add(cb);
+      return () => {
+        chainLoadedListenersRef.current.delete(cb);
+      };
+    },
+    [],
+  );
+
+  return {
+    api: status === "ready" ? api : null,
+    status,
+    installHint,
+    ensureStarted,
+    onPcmFrame,
+    sendTransport,
+    onDisconnect,
+    onChainLoaded,
+  };
+}
diff --git a/packages/studio/src/hooks/vstHostWire.ts b/packages/studio/src/hooks/vstHostWire.ts
new file mode 100644
index 0000000000..0cbbaa2fa1
--- /dev/null
+++ b/packages/studio/src/hooks/vstHostWire.ts
@@ -0,0 +1,348 @@
+/**
+ * Pure wire-protocol helpers for `useVstHost.ts`: the injectable socket
+ * factory seam, control-JSON event parsing, pending-request bookkeeping (the
+ * `pendingKey` composite-key scheme), and the `/api/vst/start` + WebSocket
+ * connect sequence. Nothing here holds React state — it's all plain
+ * functions and module-level helpers the hook wires into refs/effects.
+ *
+ * Protocol (see `hyperframes_vst/server.py` in the
+ * `heygen-com/hyperframes-vst-host` repo): JSON text
+ * frames for control commands/events, raw binary `ArrayBuffer` frames for
+ * interleaved-stereo PCM (`u32 trackIndex` + `f64 samplePos` + `f32` samples)
+ * that the hook forwards unopened to `onPcmFrame` subscribers — decoding is
+ * Task 13's job.
+ */
+import type {
+  LoadChainResult,
+  VstRegistryEntry,
+} from "../components/editor/propertyPanelVstShared";
+import { isRecord } from "../utils/vstChainFile";
+
+// ── Socket injection seam ─────────────────────────────────────────────────────
+// Production code just calls `new WebSocket(url)`. Tests substitute a fake via
+// `__setSocketFactoryForTests` (module-level override) instead of requiring
+// every caller to thread a WebSocket implementation through the hook's API.
+// `VstSocketLike` is a `Pick` of the real DOM `WebSocket` type, so a real
+// `WebSocket` instance is always assignable to it and a hand-written fake only
+// needs to match these members (see useVstHost.test.tsx's `FakeSocket`).
+
+export type VstSocketLike = Pick<
+  WebSocket,
+  "binaryType" | "onopen" | "onclose" | "onerror" | "onmessage" | "send" | "close"
+>;
+
+type SocketFactory = (url: string) => VstSocketLike;
+
+let createSocket: SocketFactory = (url) => new WebSocket(url);
+
+/** Test-only: override (or, passed `null`, restore) the socket constructor. */
+export function __setSocketFactoryForTests(factory: SocketFactory | null): void {
+  createSocket = factory ?? ((url) => new WebSocket(url));
+}
+
+// ── Server → client event parsing ─────────────────────────────────────────────
+
+function isRegistryEntry(value: unknown): value is VstRegistryEntry {
+  if (!isRecord(value)) return false;
+  return (
+    typeof value.path === "string" &&
+    typeof value.name === "string" &&
+    typeof value.format === "string"
+  );
+}
+
+export type ParsedServerEvent =
+  | { kind: "registry"; plugins: VstRegistryEntry[] }
+  | { kind: "chain-loaded"; trackId: string; sampleRate: number; stable: boolean }
+  | { kind: "state"; trackId: string; plugins: string[] }
+  | { kind: "error"; code: string; plugin: string | null; trackId: string | null };
+
+// fallow-ignore-next-line complexity
+export function parseServerEvent(raw: string): ParsedServerEvent | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed)) return null;
+
+  if (parsed.event === "registry") {
+    const rawPlugins = Array.isArray(parsed.plugins) ? parsed.plugins : [];
+    return { kind: "registry", plugins: rawPlugins.filter(isRegistryEntry) };
+  }
+  if (
+    parsed.event === "chain-loaded" &&
+    typeof parsed.trackId === "string" &&
+    typeof parsed.sampleRate === "number"
+  ) {
+    // `stable` absent (older sidecar) is treated as stable — the guard only
+    // ever downgrades a track to dry, never the reverse.
+    const stable = typeof parsed.stable === "boolean" ? parsed.stable : true;
+    return { kind: "chain-loaded", trackId: parsed.trackId, sampleRate: parsed.sampleRate, stable };
+  }
+  if (parsed.event === "state" && typeof parsed.trackId === "string") {
+    const rawPlugins = Array.isArray(parsed.plugins) ? parsed.plugins : [];
+    return {
+      kind: "state",
+      trackId: parsed.trackId,
+      plugins: rawPlugins.filter((p): p is string => typeof p === "string"),
+    };
+  }
+  if (parsed.event === "error") {
+    return {
+      kind: "error",
+      code: typeof parsed.code === "string" ? parsed.code : "unknown",
+      plugin: typeof parsed.plugin === "string" ? parsed.plugin : null,
+      trackId: typeof parsed.trackId === "string" ? parsed.trackId : null,
+    };
+  }
+  return null;
+}
+
+// ── Pending request bookkeeping ───────────────────────────────────────────────
+
+export type PendingTrackEntry =
+  | { kind: "load-chain"; resolve: (result: LoadChainResult) => void; reject: (err: Error) => void }
+  | { kind: "get-state"; resolve: (states: string[]) => void; reject: (err: Error) => void };
+
+/**
+ * Pending-map key. Keyed by (kind, trackId) — NOT trackId alone — because the
+ * two request kinds are issued by two INDEPENDENT consumers of this shared
+ * connection for the same track at the same time: `useVstPreview` calls
+ * `loadChain` while the FX panel's param-seed effect polls `getState` every
+ * 400ms (propertyPanelVstSection.tsx). With trackId-only keys, each poll
+ * clobbered — and spuriously rejected as "superseded" — the in-flight
+ * `loadChain` sharing its slot, so on any machine slow enough for the load
+ * to still be pending when a poll landed, the track never finished loading
+ * (live-traced: `loadChain-rejected: get-state superseded...` twice, then
+ * `transport loaded: 0` forever — silent music). Supersede semantics only
+ * make sense WITHIN a kind: a newer get-state replaces an older get-state,
+ * never a load-chain.
+ */
+export function pendingKey(kind: PendingTrackEntry["kind"], trackId: string): string {
+  return `${kind}:${trackId}`;
+}
+
+export interface PendingScanEntry {
+  resolve: () => void;
+  reject: (err: Error) => void;
+}
+
+export const DISCONNECTED_ERROR = "VST sidecar disconnected";
+
+export interface EventDispatchRefs {
+  registry: VstRegistryEntry[];
+  pendingScan: { current: PendingScanEntry | null };
+  pendingTrack: Map<string, PendingTrackEntry>;
+  trackIndex: Map<string, number>;
+  chainLoadedListeners: Set<(trackId: string, trackIndex: number) => void>;
+}
+
+/**
+ * Mirrors the sidecar's exact index-assignment rule (server.py's `_dispatch`,
+ * `cmd == "load-chain"`):
+ *
+ *   old = self._tracks.pop(track_id, None)          # drop any existing entry
+ *   self._tracks[track_id] = TrackStream(len(self._tracks), ...)  # reinsert at the end
+ *
+ * A Python dict (like a JS `Map`) preserves insertion order and moves a
+ * re-inserted key to the end, so replaying "delete-if-present, then set" with
+ * `map.size` as the new index reproduces the server's numbering exactly —
+ * including its one real flaw: reloading a track can hand it the same index
+ * another still-loaded track already holds (the pop briefly shrinks the map
+ * below that other track's assigned position). This function does not paper
+ * over that; it exists so a client can detect a collision, since it now
+ * assigns indices with the identical rule the server uses.
+ */
+function assignNextTrackIndex(map: Map<string, number>, trackId: string): number {
+  map.delete(trackId);
+  const index = map.size;
+  map.set(trackId, index);
+  return index;
+}
+
+/** Resolves/rejects the pending request a server event answers, keyed as described in the module doc. */
+export function applyServerEvent(parsed: ParsedServerEvent, refs: EventDispatchRefs): void {
+  switch (parsed.kind) {
+    case "registry":
+      applyRegistryEvent(parsed.plugins, refs);
+      return;
+    case "chain-loaded":
+      applyChainLoadedEvent(parsed.trackId, parsed.sampleRate, parsed.stable, refs);
+      return;
+    case "state":
+      applyStateEvent(refs.pendingTrack, parsed.trackId, parsed.plugins);
+      return;
+    case "error":
+      applyErrorEvent(parsed, refs);
+      return;
+  }
+}
+
+function applyRegistryEvent(plugins: VstRegistryEntry[], refs: EventDispatchRefs): void {
+  refs.registry.length = 0;
+  refs.registry.push(...plugins);
+  const scanPending = refs.pendingScan.current;
+  refs.pendingScan.current = null;
+  scanPending?.resolve();
+}
+
+/** `error` has no trackId when replying to `scan` (the only non-track-scoped command). */
+function applyErrorEvent(
+  parsed: Extract<ParsedServerEvent, { kind: "error" }>,
+  refs: EventDispatchRefs,
+): void {
+  const message = parsed.plugin ?? parsed.code;
+  if (parsed.trackId === null) {
+    const scanPending = refs.pendingScan.current;
+    refs.pendingScan.current = null;
+    scanPending?.reject(new Error(message));
+    return;
+  }
+  // The error event carries a trackId but not which command failed — reject
+  // whichever request kinds are pending for that track (conservative: an
+  // error for either kills both, rather than leaving one hanging forever).
+  for (const kind of ["load-chain", "get-state"] as const) {
+    const key = pendingKey(kind, parsed.trackId);
+    const entry = refs.pendingTrack.get(key);
+    if (entry) {
+      refs.pendingTrack.delete(key);
+      entry.reject(new Error(message));
+    }
+  }
+}
+
+/**
+ * Always advances the mirrored index map and broadcasts to every
+ * `onChainLoaded` subscriber — regardless of whether THIS connection's
+ * pending map has a matching `load-chain` request — so a consumer who loaded
+ * a track earlier (and isn't the caller of the reload that produced this
+ * event) still hears about its new trackIndex.
+ */
+function applyChainLoadedEvent(
+  trackId: string,
+  sampleRate: number,
+  stable: boolean,
+  refs: EventDispatchRefs,
+): void {
+  const trackIndex = assignNextTrackIndex(refs.trackIndex, trackId);
+
+  const key = pendingKey("load-chain", trackId);
+  const entry = refs.pendingTrack.get(key);
+  if (entry?.kind === "load-chain") {
+    refs.pendingTrack.delete(key);
+    entry.resolve({ trackIndex, sampleRate, stable });
+  }
+
+  refs.chainLoadedListeners.forEach((cb) => cb(trackId, trackIndex));
+}
+
+function applyStateEvent(
+  pendingTrack: Map<string, PendingTrackEntry>,
+  trackId: string,
+  plugins: string[],
+): void {
+  const key = pendingKey("get-state", trackId);
+  const entry = pendingTrack.get(key);
+  if (entry?.kind !== "get-state") return;
+  pendingTrack.delete(key);
+  entry.resolve(plugins);
+}
+
+// ── Start + connect (module-level so each stays a small, single-purpose unit) ──
+
+export type StartOutcome =
+  | { ok: true; port: number; token: string }
+  | { ok: false; installHint: string | null; message: string };
+
+interface StartResponseBody {
+  port: number;
+  token: string;
+}
+
+/** Type guard for `/api/vst/start`'s success-path body shape (see routes/vst.ts). */
+function isStartResponseBody(body: unknown): body is StartResponseBody {
+  return isRecord(body) && typeof body.port === "number" && typeof body.token === "string";
+}
+
+/** Names which field `isStartResponseBody` rejected on, for a specific error message. */
+function missingStartField(body: unknown): "port" | "token" {
+  return isRecord(body) && typeof body.port === "number" ? "token" : "port";
+}
+
+/**
+ * Parses `/api/vst/start`'s response body (see routes/vst.ts) into a
+ * `StartOutcome`. The sidecar requires every WebSocket connection to present
+ * a shared-secret `token` (see server.py's `_authenticate`) before any
+ * command is processed — `/vst/start` relays it alongside the port, so a
+ * response missing it is treated the same as one missing the port: a
+ * connection couldn't be safely established from it.
+ */
+function parseStartResponse(response: Response, body: unknown): StartOutcome {
+  if (!response.ok) {
+    const hint = isRecord(body) && typeof body.installHint === "string" ? body.installHint : null;
+    const message =
+      isRecord(body) && typeof body.error === "string" ? body.error : "VST sidecar failed to start";
+    return { ok: false, installHint: hint, message };
+  }
+  if (!isStartResponseBody(body)) {
+    return {
+      ok: false,
+      installHint: null,
+      message: `VST sidecar start response missing ${missingStartField(body)}`,
+    };
+  }
+  return { ok: true, port: body.port, token: body.token };
+}
+
+export async function requestVstStart(): Promise<StartOutcome> {
+  let response: Response;
+  try {
+    response = await fetch("/api/vst/start", { method: "POST" });
+  } catch (err) {
+    return {
+      ok: false,
+      installHint: null,
+      message: err instanceof Error ? err.message : String(err),
+    };
+  }
+  const body: unknown = await response.json().catch(() => null);
+  return parseStartResponse(response, body);
+}
+
+export interface SocketHandlers {
+  onMessage: (ev: MessageEvent) => void;
+  onReady: () => void;
+  onDisconnect: () => void;
+}
+
+/**
+ * Opens the sidecar WS and resolves once it's open (or rejects if it closes
+ * first). `token` is sent as a `?token=` query param — the sidecar's
+ * `process_request` handshake hook (server.py's `_authenticate`) rejects the
+ * HTTP upgrade before any command can be sent if it's missing or wrong.
+ */
+export function connectVstSocket(
+  port: number,
+  token: string,
+  handlers: SocketHandlers,
+): Promise<VstSocketLike> {
+  return new Promise<VstSocketLike>((resolve, reject) => {
+    const host = typeof window !== "undefined" ? window.location.hostname : "localhost";
+    const socket = createSocket(`ws://${host}:${port}/?token=${encodeURIComponent(token)}`);
+    socket.binaryType = "arraybuffer";
+    socket.onopen = () => {
+      handlers.onReady();
+      resolve(socket);
+    };
+    socket.onmessage = handlers.onMessage;
+    socket.onclose = () => {
+      handlers.onDisconnect();
+      reject(new Error("VST sidecar socket closed before opening"));
+    };
+    socket.onerror = () => {
+      handlers.onDisconnect();
+    };
+  });
+}
diff --git a/packages/studio/src/hooks/vstSocketTestFixture.ts b/packages/studio/src/hooks/vstSocketTestFixture.ts
new file mode 100644
index 0000000000..2efff93ed0
--- /dev/null
+++ b/packages/studio/src/hooks/vstSocketTestFixture.ts
@@ -0,0 +1,62 @@
+// fallow-ignore-file unused-class-member
+// `FakeSocket`'s members are the `VstSocketLike` interface surface, called on
+// instances from the consuming test files (useVstHost.test.tsx /
+// useVstPreview.test.tsx) — genuinely used, but invisible to a same-file
+// dead-code scan now that the class lives in its own shared module.
+/**
+ * Shared WebSocket test double for `useVstHost` — used by both
+ * `useVstHost.test.tsx` (the hook's own unit tests) and
+ * `useVstPreview.test.tsx` (which drives the REAL `useVstHost` through this
+ * same seam per its integration-test doc-comment) so the two suites' fake
+ * socket behavior can't drift apart.
+ *
+ * Injected via `useVstHost`'s `__setSocketFactoryForTests` module-level
+ * override rather than a real `WebSocket` — production code just calls
+ * `new WebSocket(url)`.
+ */
+
+import type { VstSocketLike } from "./useVstHost";
+
+export class FakeSocket implements VstSocketLike {
+  static instances: FakeSocket[] = [];
+  binaryType: BinaryType = "blob";
+  onopen: ((ev: Event) => void) | null = null;
+  onclose: ((ev: CloseEvent) => void) | null = null;
+  onerror: ((ev: Event) => void) | null = null;
+  onmessage: ((ev: MessageEvent) => void) | null = null;
+  sent: string[] = [];
+  closed = false;
+
+  constructor(public url: string) {
+    FakeSocket.instances.push(this);
+  }
+
+  send(data: string): void {
+    this.sent.push(data);
+  }
+
+  close(): void {
+    this.closed = true;
+    this.onclose?.(new CloseEvent("close"));
+  }
+
+  open(): void {
+    this.onopen?.(new Event("open"));
+  }
+
+  emitJson(payload: unknown): void {
+    this.onmessage?.(new MessageEvent("message", { data: JSON.stringify(payload) }));
+  }
+
+  emitBinary(buf: ArrayBuffer): void {
+    this.onmessage?.(new MessageEvent("message", { data: buf }));
+  }
+}
+
+/** Narrows away `null`/`undefined` without a `!` assertion (repo convention). */
+export function required<T>(value: T | null | undefined, label = "value"): T {
+  if (value === null || value === undefined) {
+    throw new Error(`${label} was unexpectedly missing`);
+  }
+  return value;
+}
diff --git a/packages/studio/src/player/hooks/useTimelinePlayer.ts b/packages/studio/src/player/hooks/useTimelinePlayer.ts
index 39be707e68..3e2f11ee23 100644
--- a/packages/studio/src/player/hooks/useTimelinePlayer.ts
+++ b/packages/studio/src/player/hooks/useTimelinePlayer.ts
@@ -241,6 +241,7 @@ export function useTimelinePlayer() {
     const { audioMuted } = usePlayerStore.getState();
     setPreviewMediaMuted(iframeRef.current, audioMuted);
   }, []);
+
   const play = useCallback(() => {
     stopRAFLoop();
     stopReverseLoop();
diff --git a/packages/studio/src/player/hooks/useVstPreview.test.tsx b/packages/studio/src/player/hooks/useVstPreview.test.tsx
new file mode 100644
index 0000000000..2d4d371ad6
--- /dev/null
+++ b/packages/studio/src/player/hooks/useVstPreview.test.tsx
@@ -0,0 +1,993 @@
+// @vitest-environment happy-dom
+//
+// Integration tests use the REAL `useVstHost` (Task 12) driven through its
+// documented test seam (`__setSocketFactoryForTests` + a hand-rolled
+// `FakeSocket`, the same technique `useVstHost.test.tsx` uses) rather than
+// mocking the module — this exercises the actual wiring between the two
+// hooks instead of a hand-built stand-in.
+//
+// The browser has no Web Audio implementation in this test environment
+// (jsdom/happy-dom ship no AudioContext/AudioWorkletNode at all), so this
+// file stubs minimal fakes for those two globals, scoped to what
+// useVstPreview actually calls (constructor, `.audioWorklet.addModule`,
+// `.connect`, `.port.postMessage`, `.close`). It does NOT — and cannot —
+// exercise the real vst-stream AudioWorkletProcessor (vstStreamWorklet.js);
+// that requires a real browser audio-rendering thread. See the task report
+// for what manual/browser verification covers instead.
+
+import React, { act } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { Root } from "react-dom/client";
+import { mountReactHarness } from "../../hooks/domSelectionTestHarness";
+import { __setSocketFactoryForTests, useVstHost } from "../../hooks/useVstHost";
+import { FakeSocket, required } from "../../hooks/vstSocketTestFixture";
+import { liveTime, usePlayerStore } from "../store/playerStore";
+import { decodePcmFrame, useVstPreview } from "./useVstPreview";
+
+vi.mock("../../components/editor/manualEditingAvailability", () => ({
+  STUDIO_VST_ENABLED: true,
+}));
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+// ── Fake Web Audio (this environment has none at all) ───────────────────────
+
+class FakeAudioWorkletNode {
+  static instances: FakeAudioWorkletNode[] = [];
+  port = { postMessage: vi.fn(), onmessage: null };
+  connect = vi.fn();
+  constructor(
+    public context: unknown,
+    public name: string,
+    public options?: unknown,
+  ) {
+    FakeAudioWorkletNode.instances.push(this);
+  }
+}
+
+class FakeAudioContext {
+  static instances: FakeAudioContext[] = [];
+  audioWorklet = { addModule: vi.fn(async () => {}) };
+  destination = {};
+  close = vi.fn(async () => {});
+  // Real browsers start every new AudioContext "suspended" under the
+  // autoplay policy — resume() (called at the transport play transition,
+  // see useVstPreview.ts's resumeSuspendedContexts) is what makes PCM
+  // audible instead of silently dropped.
+  state: "suspended" | "running" = "suspended";
+  resume = vi.fn(async () => {
+    this.state = "running";
+  });
+  constructor(public options?: { sampleRate?: number }) {
+    FakeAudioContext.instances.push(this);
+  }
+}
+
+// ── Test helpers ──────────────────────────────────────────────────────────────
+
+async function flushAsyncWork(): Promise<void> {
+  // 30, not 10: loadVstTrack now awaits an extra fetch (resolveLocalWavPath)
+  // before api.loadChain, adding another real microtask hop per track.
+  for (let i = 0; i < 30; i += 1) {
+    await Promise.resolve();
+  }
+}
+
+/** Opens the first fake socket and flushes surrounding async work. Call inside `act()`. */
+async function openFirstSocket(): Promise<void> {
+  await flushAsyncWork();
+  required(FakeSocket.instances[0], "socket").open();
+  await flushAsyncWork();
+}
+
+/** Emits a chain-loaded event on the first fake socket and flushes surrounding async work. Call inside `act()`. */
+async function emitChainLoaded(payload: {
+  trackId: string;
+  sampleRate: number;
+  stable?: boolean;
+}): Promise<void> {
+  await flushAsyncWork();
+  required(FakeSocket.instances[0], "socket").emitJson({ event: "chain-loaded", ...payload });
+  await flushAsyncWork();
+}
+
+function okJsonResponse(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function buildFetchMock(chainJson: unknown): ReturnType<typeof vi.fn> {
+  return vi.fn(async (input: RequestInfo | URL) => {
+    const url = String(input);
+    if (url === "/api/vst/start") return okJsonResponse({ port: 4321, token: "test-token" });
+    if (url.includes("/vst/wav-path")) {
+      const subPath = new URL(url, "http://localhost").searchParams.get("path");
+      return okJsonResponse({ path: `/abs/project/${subPath}` });
+    }
+    if (url.includes("/files/")) return okJsonResponse({ content: JSON.stringify(chainJson) });
+    throw new Error(`unexpected fetch: ${url}`);
+  });
+}
+
+/** Finds the worklet node's most recent "reset" postMessage call — the
+ *  shared lookup the ring-realignment tests below need. */
+function findResetCall(
+  node: FakeAudioWorkletNode,
+): { type?: string; samplePos?: number } | undefined {
+  return node.port.postMessage.mock.calls
+    .map((c) => c[0] as { type?: string; samplePos?: number })
+    .find((m) => m && m.type === "reset");
+}
+
+interface Harnessed {
+  root: Root;
+  audioEl: HTMLAudioElement;
+  showToast: ReturnType<typeof vi.fn>;
+  fetchMock: ReturnType<typeof vi.fn>;
+}
+
+/** Mounts useVstPreview against a real <audio data-vst-chain> in `document`. */
+function mountHarness(
+  projectId: string | undefined,
+  chainJson: unknown,
+  includeAudio = true,
+): Harnessed {
+  const audioEl = document.createElement("audio");
+  audioEl.id = "track-1";
+  if (includeAudio) {
+    audioEl.setAttribute("data-vst-chain", "fx/track-1.vstchain.json");
+    audioEl.setAttribute("src", `/api/projects/${projectId ?? "proj-1"}/preview/dry.wav`);
+    document.body.append(audioEl);
+  }
+
+  const iframe = document.createElement("iframe");
+  Object.defineProperty(iframe, "contentDocument", { configurable: true, value: document });
+  const iframeRef = { current: iframe };
+
+  const fetchMock = buildFetchMock(chainJson);
+  vi.stubGlobal("fetch", fetchMock);
+
+  const showToast = vi.fn();
+
+  function Harness() {
+    const vstHost = useVstHost();
+    useVstPreview(iframeRef, projectId, vstHost, showToast);
+    return null;
+  }
+
+  const root = mountReactHarness(<Harness />);
+  return { root, audioEl, showToast, fetchMock };
+}
+
+/** Opens the first fake socket (inside `act()`) and returns it — the shared
+ *  "connect, then grab the socket instance" step every loaded-preview setup
+ *  below needs. */
+async function connectAndGetSocket(): Promise<FakeSocket> {
+  await act(async () => {
+    await openFirstSocket();
+  });
+  return required(FakeSocket.instances[0], "socket");
+}
+
+/** Drives a mounted harness to a fully loaded (ready + chain loaded) state. */
+async function setupLoadedPreview(): Promise<Harnessed & { socket: FakeSocket }> {
+  const harness = mountHarness("proj-1", { version: 1, plugins: [] });
+  const socket = await connectAndGetSocket();
+
+  await act(async () => {
+    await emitChainLoaded({ trackId: "track-1", sampleRate: 48000 });
+  });
+
+  return { ...harness, socket };
+}
+
+beforeEach(() => {
+  FakeSocket.instances = [];
+  FakeAudioContext.instances = [];
+  FakeAudioWorkletNode.instances = [];
+  __setSocketFactoryForTests((url) => new FakeSocket(url));
+  vi.stubGlobal("AudioContext", FakeAudioContext);
+  vi.stubGlobal("AudioWorkletNode", FakeAudioWorkletNode);
+});
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  __setSocketFactoryForTests(null);
+  vi.unstubAllGlobals();
+  usePlayerStore.getState().reset();
+  vi.useRealTimers();
+});
+
+// ── decodePcmFrame ────────────────────────────────────────────────────────────
+
+describe("decodePcmFrame", () => {
+  function encodeFrame(
+    trackIndex: number,
+    samplePos: number,
+    pairs: [number, number][],
+  ): ArrayBuffer {
+    const buf = new ArrayBuffer(12 + pairs.length * 2 * 4);
+    const view = new DataView(buf);
+    view.setUint32(0, trackIndex, true);
+    view.setFloat64(4, samplePos, true);
+    const interleaved = new Float32Array(buf, 12);
+    pairs.forEach(([l, r], i) => {
+      interleaved[2 * i] = l;
+      interleaved[2 * i + 1] = r;
+    });
+    return buf;
+  }
+
+  it("decodes trackIndex and samplePos from the header", () => {
+    const frame = decodePcmFrame(encodeFrame(3, 48000, [[0.5, -0.5]]));
+    expect(frame.trackIndex).toBe(3);
+    expect(frame.samplePos).toBe(48000);
+  });
+
+  it("de-interleaves stereo samples into separate left/right arrays", () => {
+    const frame = decodePcmFrame(
+      encodeFrame(0, 0, [
+        [1, -1],
+        [2, -2],
+        [3, -3],
+      ]),
+    );
+    expect(Array.from(frame.left)).toEqual([1, 2, 3]);
+    expect(Array.from(frame.right)).toEqual([-1, -2, -3]);
+  });
+
+  it("handles a zero-sample frame (header only)", () => {
+    const frame = decodePcmFrame(encodeFrame(1, 100, []));
+    expect(frame.left.length).toBe(0);
+    expect(frame.right.length).toBe(0);
+  });
+
+  it("round-trips a large trackIndex and fractional samplePos precisely", () => {
+    const frame = decodePcmFrame(encodeFrame(4294967295, 123456.789, [[0.1, 0.2]]));
+    expect(frame.trackIndex).toBe(4294967295);
+    expect(frame.samplePos).toBeCloseTo(123456.789, 6);
+  });
+});
+
+// ── Chain loading + muting ───────────────────────────────────────────────────
+
+describe("useVstPreview — chain loading", () => {
+  it("loads the chain and mutes the dry element once the sidecar is ready", async () => {
+    const { root, audioEl, socket } = await setupLoadedPreview();
+
+    expect(audioEl.muted).toBe(true);
+    expect(FakeAudioContext.instances).toHaveLength(1);
+    expect(FakeAudioContext.instances[0]?.audioWorklet.addModule).toHaveBeenCalledWith(
+      expect.stringContaining("vstStreamWorklet.js"),
+    );
+    expect(FakeAudioWorkletNode.instances).toHaveLength(1);
+    expect(FakeAudioWorkletNode.instances[0]?.connect).toHaveBeenCalledWith(
+      FakeAudioContext.instances[0]?.destination,
+    );
+    const loadChainMsg = socket.sent.find((raw) => raw.includes('"cmd":"load-chain"'));
+    expect(loadChainMsg).toBeDefined();
+    expect(loadChainMsg).toContain('"trackId":"track-1"');
+
+    act(() => root.unmount());
+  });
+
+  it("retries a load whose effect run was cancelled mid-flight instead of stranding the track", async () => {
+    // Live-repro'd race: effect run A starts the async load; before the
+    // sidecar replies `chain-loaded`, a dependency churn (elements /
+    // vstChainRevision — routine right after mount) re-runs the effect. Run B
+    // scans, sees A's load still pending (`pendingTrackIdsRef` guard), and
+    // skips the track. A then resolves, sees itself cancelled, and tears the
+    // freshly wired track down — with `trackOrderRef` still holding the
+    // "already attempted" reservation, NOTHING ever retried: chain loaded
+    // server-side, zero tracks client-side, transport forever seeing
+    // `loaded: 0` (music silent from the first play).
+    const { root, audioEl } = mountHarness("proj-1", { version: 1, plugins: [] });
+
+    // Let run A get as far as sending `load-chain` (its promise now pending
+    // on the chain-loaded reply we haven't emitted yet).
+    await act(async () => {
+      await openFirstSocket();
+    });
+    const socket = required(FakeSocket.instances[0], "socket");
+    expect(socket.sent.filter((m) => m.includes('"cmd":"load-chain"'))).toHaveLength(1);
+
+    // Mid-flight: re-run the load effect (run B) while A's load is pending.
+    await act(async () => {
+      usePlayerStore.getState().bumpVstChainRevision();
+      await flushAsyncWork();
+    });
+
+    // NOW the sidecar replies — resolving A's load inside a cancelled run.
+    await act(async () => {
+      socket.emitJson({ event: "chain-loaded", trackId: "track-1", sampleRate: 48000 });
+      await flushAsyncWork();
+    });
+
+    // The retry (run C, poked by the cancellation handler) re-issues
+    // load-chain; answer it and let it settle.
+    await act(async () => {
+      await flushAsyncWork();
+      socket.emitJson({ event: "chain-loaded", trackId: "track-1", sampleRate: 48000 });
+      await flushAsyncWork();
+    });
+
+    expect(socket.sent.filter((m) => m.includes('"cmd":"load-chain"'))).toHaveLength(2);
+    expect(audioEl.muted).toBe(true); // track actually loaded, not stranded dry
+
+    act(() => root.unmount());
+  });
+
+  it("does nothing when there is no data-vst-chain audio element in the DOM", async () => {
+    const { root, fetchMock } = mountHarness("proj-1", { version: 1, plugins: [] }, false);
+
+    await act(async () => {
+      await flushAsyncWork();
+    });
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(FakeSocket.instances).toHaveLength(0);
+
+    act(() => root.unmount());
+  });
+
+  it("does nothing when projectId is undefined", async () => {
+    const { root, fetchMock, audioEl } = mountHarness(undefined, { version: 1, plugins: [] });
+
+    await act(async () => {
+      await flushAsyncWork();
+    });
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(audioEl.muted).toBe(false);
+
+    act(() => root.unmount());
+  });
+});
+
+// ── Transport: play/pause/seek ───────────────────────────────────────────────
+
+describe("useVstPreview — transport", () => {
+  it("sends a play transport message with the live playhead time + playbackRate when isPlaying flips true", async () => {
+    const { root, socket } = await setupLoadedPreview();
+
+    act(() => {
+      // The real, continuously-updating playhead — see useVstPreview.ts's
+      // liveTimeRef doc-comment for why this reads `liveTime`, not the
+      // Zustand store's `currentTime` (the RAF loop only syncs that "once
+      // at end", so it stays stale/frozen for the entire duration of a
+      // fresh play from the start).
+      liveTime.notify(4.5);
+      usePlayerStore.getState().setPlaybackRate(1.5);
+      usePlayerStore.getState().setIsPlaying(true);
+    });
+
+    const playMsg = socket.sent
+      .map((raw) => JSON.parse(raw) as Record<string, unknown>)
+      .find((msg) => msg.cmd === "transport" && msg.action === "play");
+    expect(playMsg).toMatchObject({ action: "play", timeSec: 4.5, rate: 1.5 });
+
+    act(() => root.unmount());
+  });
+
+  it("resumes the track's suspended AudioContext when isPlaying flips true", async () => {
+    const { root } = await setupLoadedPreview();
+    const ctx = required(FakeAudioContext.instances[0], "audio context");
+    expect(ctx.state).toBe("suspended"); // real browsers start every context suspended
+
+    act(() => usePlayerStore.getState().setIsPlaying(true));
+
+    expect(ctx.resume).toHaveBeenCalled();
+    expect(ctx.state).toBe("running");
+
+    act(() => root.unmount());
+  });
+
+  it("sends a bare pause transport message when isPlaying flips false", async () => {
+    const { root, socket } = await setupLoadedPreview();
+
+    act(() => usePlayerStore.getState().setIsPlaying(true));
+    act(() => usePlayerStore.getState().setIsPlaying(false));
+
+    const pauseMsg = socket.sent
+      .map((raw) => JSON.parse(raw) as Record<string, unknown>)
+      .find((msg) => msg.cmd === "transport" && msg.action === "pause");
+    expect(pauseMsg).toEqual({ cmd: "transport", action: "pause" });
+
+    act(() => root.unmount());
+  });
+
+  it("flushes the worklet ring on pause so the buffered lead cushion doesn't keep playing", async () => {
+    // The sidecar streams ~0.5s AHEAD of the playhead (its _PUMP_LEAD_SEC
+    // jitter cushion), all buffered in the worklet ring. Pause only stops the
+    // pump — without an explicit ring reset the cushion audibly drains for
+    // up to a second after the pause click.
+    const { root } = await setupLoadedPreview();
+    const node = required(FakeAudioWorkletNode.instances[0], "worklet node");
+
+    act(() => {
+      liveTime.notify(3);
+      usePlayerStore.getState().setIsPlaying(true);
+    });
+    node.port.postMessage.mockClear();
+
+    act(() => {
+      liveTime.notify(3.4);
+      usePlayerStore.getState().setIsPlaying(false);
+    });
+
+    expect(node.port.postMessage).toHaveBeenCalledWith({
+      type: "reset",
+      samplePos: Math.floor(3.4 * 48000),
+    });
+
+    act(() => root.unmount());
+  });
+
+  it("sends a seek transport message and resets the worklet node on requestSeek", async () => {
+    const { root, socket } = await setupLoadedPreview();
+
+    act(() => usePlayerStore.getState().requestSeek(2));
+
+    const seekMsg = socket.sent
+      .map((raw) => JSON.parse(raw) as Record<string, unknown>)
+      .find((msg) => msg.cmd === "transport" && msg.action === "seek");
+    expect(seekMsg).toMatchObject({ action: "seek", timeSec: 2 });
+
+    const node = required(FakeAudioWorkletNode.instances[0], "worklet node");
+    expect(node.port.postMessage).toHaveBeenCalledWith({ type: "reset", samplePos: 2 * 48000 });
+
+    act(() => root.unmount());
+  });
+
+  it("floors a fractional seek time to an integer sample position when resetting the worklet", async () => {
+    const { root } = await setupLoadedPreview();
+    const node = required(FakeAudioWorkletNode.instances[0], "worklet node");
+
+    act(() => usePlayerStore.getState().requestSeek(1.234567));
+
+    // The sidecar streams integer sample positions (`int(timeSec * sr)`), and
+    // the ring accepts a block only if its samplePos matches exactly. A
+    // fractional reset target (`1.234567 * 48000 = 59259.216`) could never
+    // match, so every frame would be rejected and the ring would starve.
+    const resetCall = findResetCall(node);
+    expect(resetCall?.samplePos).toBe(Math.floor(1.234567 * 48000));
+    expect(Number.isInteger(resetCall?.samplePos)).toBe(true);
+
+    act(() => root.unmount());
+  });
+
+  it("resets the worklet to the floored live playhead when playback starts", async () => {
+    const { root } = await setupLoadedPreview();
+    const node = required(FakeAudioWorkletNode.instances[0], "worklet node");
+    node.port.postMessage.mockClear();
+
+    // A stale worklet ring from a previous run would reject every new frame;
+    // starting playback must realign it to the integer position the sidecar
+    // begins streaming from (see the play-path reseek in useVstPreview).
+    act(() => {
+      liveTime.notify(4.321);
+      usePlayerStore.getState().setIsPlaying(true);
+    });
+
+    const resetCall = findResetCall(node);
+    expect(resetCall?.samplePos).toBe(Math.floor(4.321 * 48000));
+
+    act(() => root.unmount());
+  });
+});
+
+// ── PCM frame routing ─────────────────────────────────────────────────────────
+
+describe("useVstPreview — incompatible plugin guard", () => {
+  it("keeps the track on dry audio and warns when the sidecar reports the chain unstable", async () => {
+    const harness = mountHarness("proj-1", {
+      version: 1,
+      plugins: [
+        {
+          format: "vst3",
+          path: "/x.vst3",
+          pluginName: "Weird FX",
+          name: "Weird FX",
+          stateB64: null,
+        },
+      ],
+    });
+
+    await act(async () => {
+      await openFirstSocket();
+    });
+    await act(async () => {
+      await emitChainLoaded({ trackId: "track-1", sampleRate: 48000, stable: false });
+    });
+
+    // Dry: the element is never muted and no playback node is created.
+    expect(harness.audioEl.muted).toBe(false);
+    expect(FakeAudioWorkletNode.instances.length).toBe(0);
+    // Warned, naming the offending plugin.
+    expect(harness.showToast).toHaveBeenCalledWith(expect.stringContaining("Weird FX"), "error");
+    expect(harness.showToast.mock.calls[0]?.[0]).toContain("isn't compatible");
+
+    act(() => harness.root.unmount());
+  });
+});
+
+describe("useVstPreview — chain removal reconciliation", () => {
+  it("tears down the track and unmutes the dry element when its chain is removed", async () => {
+    const { root, audioEl } = await setupLoadedPreview();
+    // Loaded → the hook muted the dry element to play the wet stream instead.
+    expect(audioEl.muted).toBe(true);
+
+    // Simulate the FX panel removing the chain: the attribute is gone from the
+    // preview DOM and the elements store refreshes (handleDomAttributeCommit's
+    // refreshAfter). The load effect must reconcile — without this it left the
+    // element muted forever (silent), and never reloaded a replacement chain.
+    await act(async () => {
+      audioEl.removeAttribute("data-vst-chain");
+      usePlayerStore.getState().setElements([]);
+      await flushAsyncWork();
+    });
+
+    expect(audioEl.muted).toBe(false); // dry audio restored
+    act(() => root.unmount());
+  });
+
+  it("re-binds to the fresh element and mutes it after a preview reload replaces the DOM node", async () => {
+    const { root, audioEl } = await setupLoadedPreview();
+    expect(audioEl.muted).toBe(true);
+
+    // A preview reload replaces the composition DOM: the old <audio> node is
+    // gone, a NEW node with the same id/chain takes its place. The old track
+    // is now orphaned — it muted the dead node, so the fresh (unmuted) one
+    // would play dry. NLEContext bumps vstChainRevision on iframe load to make
+    // this reconcile happen; simulate that here.
+    audioEl.remove();
+    const fresh = document.createElement("audio");
+    fresh.id = "track-1";
+    fresh.setAttribute("data-vst-chain", "fx/track-1.vstchain.json");
+    fresh.setAttribute("src", "/api/projects/proj-1/preview/dry.wav");
+    document.body.append(fresh);
+
+    await act(async () => {
+      usePlayerStore.getState().bumpVstChainRevision();
+      await emitChainLoaded({ trackId: "track-1", sampleRate: 48000, stable: true });
+    });
+
+    // The FRESH element is now muted (VST pipeline owns its audio); the old
+    // detached node no longer matters. Without the reload reconcile the fresh
+    // node stayed unmuted → dry bleed.
+    expect(fresh.muted).toBe(true);
+    act(() => root.unmount());
+  });
+});
+
+describe("useVstPreview — chain content swap", () => {
+  it("reloads the track when the chain FILE contents change, not the first-loaded effect", async () => {
+    // Same element + same data-vst-chain path, but the file's CONTENTS change
+    // (the FX panel rewrites it on swap). Element identity is unchanged, so
+    // this is caught only by comparing chain contents — the bug was the
+    // first-loaded effect streaming forever.
+    const chainObj = {
+      version: 1,
+      plugins: [
+        { format: "builtin", path: "Delay", pluginName: null, name: "Delay", stateB64: null },
+      ],
+    };
+    const harness = mountHarness("proj-1", chainObj);
+
+    await act(async () => {
+      await openFirstSocket();
+    });
+    await act(async () => {
+      await emitChainLoaded({ trackId: "track-1", sampleRate: 48000, stable: true });
+    });
+    expect(FakeAudioWorkletNode.instances.length).toBe(1);
+
+    // Swap the effect (rewrite the same file's contents), then re-run the load
+    // effect. The old track must be torn down and reloaded from the new chain.
+    chainObj.plugins = [
+      { format: "builtin", path: "Reverb", pluginName: null, name: "Reverb", stateB64: null },
+    ];
+    await act(async () => {
+      // The real trigger: the FX panel bumps this after rewriting the chain
+      // file (a same-path rewrite is invisible to the `elements` signal).
+      usePlayerStore.getState().bumpVstChainRevision();
+      await emitChainLoaded({ trackId: "track-1", sampleRate: 48000, stable: true });
+    });
+
+    // A SECOND worklet node proves the track reloaded (torn down + rebuilt),
+    // rather than the first-loaded Delay persisting.
+    expect(FakeAudioWorkletNode.instances.length).toBe(2);
+
+    act(() => harness.root.unmount());
+  });
+});
+
+describe("useVstPreview — PCM routing", () => {
+  it("routes a PCM frame matching the loaded track's index to its worklet node", async () => {
+    const { root, socket } = await setupLoadedPreview();
+    const node = required(FakeAudioWorkletNode.instances[0], "worklet node");
+
+    const buf = new ArrayBuffer(12 + 2 * 4);
+    const view = new DataView(buf);
+    view.setUint32(0, 0, true); // trackIndex 0 — the only loaded track
+    view.setFloat64(4, 1000, true);
+    new Float32Array(buf, 12)[0] = 0.25;
+    new Float32Array(buf, 12)[1] = -0.25;
+
+    act(() => socket.emitBinary(buf));
+
+    expect(node.port.postMessage).toHaveBeenCalledWith(
+      expect.objectContaining({ type: "pcm", samplePos: 1000 }),
+      expect.any(Array),
+    );
+
+    act(() => root.unmount());
+  });
+
+  it("drops a PCM frame whose trackIndex has no loaded track", async () => {
+    const { root, socket } = await setupLoadedPreview();
+    const node = required(FakeAudioWorkletNode.instances[0], "worklet node");
+    node.port.postMessage.mockClear();
+
+    const buf = new ArrayBuffer(12 + 2 * 4);
+    const view = new DataView(buf);
+    view.setUint32(0, 7, true); // no track loaded at index 7
+    view.setFloat64(4, 1000, true);
+
+    act(() => socket.emitBinary(buf));
+
+    expect(node.port.postMessage).not.toHaveBeenCalled();
+
+    act(() => root.unmount());
+  });
+});
+
+// ── trackIndex resync on an external chain reload ────────────────────────────
+//
+// Simulates the scenario Task 13b fixes: this hook and the FX property panel
+// now share ONE useVstHost() connection (see the module doc-comment), so a
+// `chain-loaded` event can arrive for a trackId this hook already streams
+// without this hook having initiated the reload itself — e.g. the panel
+// added/removed an effect. The fake socket is driven directly with a raw
+// `chain-loaded` event (bypassing `api.loadChain`) to model exactly that:
+// "some other caller on the shared connection reloaded this track".
+
+interface TwoTrackHarness {
+  root: Root;
+  audioEl1: HTMLAudioElement;
+  audioEl2: HTMLAudioElement;
+  showToast: ReturnType<typeof vi.fn>;
+  socket: FakeSocket;
+}
+
+/** Asserts both tracks reverted to unmuted dry playback and a toast fired
+ *  naming `messageSubstring` — the shared "both tracks reverted" outcome
+ *  several tests below check for (a routing collision, or a disconnect). */
+function expectBothTracksRevertedWithToast(
+  audioEl1: HTMLAudioElement,
+  audioEl2: HTMLAudioElement,
+  showToast: ReturnType<typeof vi.fn>,
+  messageSubstring: string,
+): void {
+  expect(audioEl1.muted).toBe(false);
+  expect(audioEl2.muted).toBe(false);
+  expect(showToast).toHaveBeenCalledWith(expect.stringContaining(messageSubstring), "error");
+}
+
+/** Loads two vst-chain tracks (track-1 → index 0, track-2 → index 1) through one shared connection. */
+async function setupTwoLoadedTracks(): Promise<TwoTrackHarness> {
+  const audioEl1 = document.createElement("audio");
+  audioEl1.id = "track-1";
+  audioEl1.setAttribute("data-vst-chain", "fx/track-1.vstchain.json");
+  audioEl1.setAttribute("src", "/api/projects/proj-1/preview/dry1.wav");
+  document.body.append(audioEl1);
+
+  const audioEl2 = document.createElement("audio");
+  audioEl2.id = "track-2";
+  audioEl2.setAttribute("data-vst-chain", "fx/track-2.vstchain.json");
+  audioEl2.setAttribute("src", "/api/projects/proj-1/preview/dry2.wav");
+  document.body.append(audioEl2);
+
+  const iframe = document.createElement("iframe");
+  Object.defineProperty(iframe, "contentDocument", { configurable: true, value: document });
+  const iframeRef = { current: iframe };
+
+  vi.stubGlobal("fetch", buildFetchMock({ version: 1, plugins: [] }));
+  const showToast = vi.fn();
+
+  function Harness() {
+    const vstHost = useVstHost();
+    useVstPreview(iframeRef, "proj-1", vstHost, showToast);
+    return null;
+  }
+  const root = mountReactHarness(<Harness />);
+  const socket = await connectAndGetSocket();
+
+  await act(async () => {
+    await emitChainLoaded({ trackId: "track-1", sampleRate: 48000 });
+    await emitChainLoaded({ trackId: "track-2", sampleRate: 48000 });
+  });
+
+  return { root, audioEl1, audioEl2, showToast, socket };
+}
+
+describe("useVstPreview — trackIndex resync on an external chain reload", () => {
+  it("keeps routing correctly when a solo track is reloaded and its index doesn't change", async () => {
+    const { root, audioEl, socket } = await setupLoadedPreview();
+    const node = required(FakeAudioWorkletNode.instances[0], "worklet node");
+    node.port.postMessage.mockClear();
+
+    // Only one track was ever loaded, so the sidecar's pop-then-reinsert rule
+    // reassigns it the SAME index (0) — no collision, nothing to revert.
+    await act(async () => {
+      socket.emitJson({ event: "chain-loaded", trackId: "track-1", sampleRate: 48000 });
+      await flushAsyncWork();
+    });
+
+    expect(audioEl.muted).toBe(true); // still streaming through the worklet, not reverted to dry
+
+    const buf = new ArrayBuffer(12 + 2 * 4);
+    const view = new DataView(buf);
+    view.setUint32(0, 0, true);
+    view.setFloat64(4, 2000, true);
+    act(() => socket.emitBinary(buf));
+
+    expect(node.port.postMessage).toHaveBeenCalledWith(
+      expect.objectContaining({ type: "pcm", samplePos: 2000 }),
+      expect.any(Array),
+    );
+
+    act(() => root.unmount());
+  });
+
+  it("updates the local trackIndex mapping when an external reload reassigns an already-loaded track", async () => {
+    const { root, socket } = await setupTwoLoadedTracks();
+    const node1 = required(FakeAudioWorkletNode.instances[0], "track-1 worklet node");
+    node1.port.postMessage.mockClear();
+
+    // track-1 (index 0) and track-2 (index 1) are both loaded. Reload
+    // track-2 — the MOST RECENTLY loaded track — which the server's rule
+    // reassigns to the SAME index it already held (pop leaves one entry, so
+    // `len(self._tracks)` is 1 again): no collision, but this hook must
+    // still pick up the fresh index from the event rather than silently
+    // keep routing on a value it never re-derived.
+    await act(async () => {
+      socket.emitJson({ event: "chain-loaded", trackId: "track-2", sampleRate: 48000 });
+      await flushAsyncWork();
+    });
+
+    const buf = new ArrayBuffer(12 + 2 * 4);
+    const view = new DataView(buf);
+    view.setUint32(0, 0, true); // track-1's index — must still route to track-1 only
+    view.setFloat64(4, 3000, true);
+    act(() => socket.emitBinary(buf));
+
+    expect(node1.port.postMessage).toHaveBeenCalledWith(
+      expect.objectContaining({ type: "pcm", samplePos: 3000 }),
+      expect.any(Array),
+    );
+
+    act(() => root.unmount());
+  });
+
+  it("reverts BOTH tracks to dry playback and warns instead of silently misrouting on an index collision", async () => {
+    // Reloading track-1 (NOT the most recently loaded track) pops it, leaving
+    // one entry (track-2), so the server's rule reassigns track-1 the same
+    // index track-2 already holds (1) — a genuine collision the wire
+    // protocol cannot disambiguate (see assignNextTrackIndex's doc-comment).
+    const { root, audioEl1, audioEl2, showToast, socket } = await setupTwoLoadedTracks();
+    const node1 = required(FakeAudioWorkletNode.instances[0], "track-1 worklet node");
+    const node2 = required(FakeAudioWorkletNode.instances[1], "track-2 worklet node");
+    node1.port.postMessage.mockClear();
+    node2.port.postMessage.mockClear();
+
+    expect(audioEl1.muted).toBe(true);
+    expect(audioEl2.muted).toBe(true);
+
+    await act(async () => {
+      socket.emitJson({ event: "chain-loaded", trackId: "track-1", sampleRate: 48000 });
+      await flushAsyncWork();
+    });
+
+    // Both tracks reverted to their original (unmuted) dry playback rather
+    // than one silently stealing the other's processed audio stream.
+    expectBothTracksRevertedWithToast(audioEl1, audioEl2, showToast, "routing conflict");
+
+    // A PCM frame at the now-ambiguous index must be dropped for both, not
+    // routed to whichever track happens to be first in iteration order.
+    const buf = new ArrayBuffer(12 + 2 * 4);
+    const view = new DataView(buf);
+    view.setUint32(0, 1, true);
+    view.setFloat64(4, 4000, true);
+    act(() => socket.emitBinary(buf));
+
+    expect(node1.port.postMessage).not.toHaveBeenCalled();
+    expect(node2.port.postMessage).not.toHaveBeenCalled();
+
+    act(() => root.unmount());
+  });
+});
+
+// ── Crash fallback ────────────────────────────────────────────────────────────
+
+describe("useVstPreview — crash fallback", () => {
+  it("unmutes the dry element, shows a toast, and attempts one restart on disconnect", async () => {
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+    const { root, audioEl, showToast, fetchMock, socket } = await setupLoadedPreview();
+
+    await act(async () => {
+      socket.close();
+      await flushAsyncWork();
+    });
+
+    expect(audioEl.muted).toBe(false);
+    expect(showToast).toHaveBeenCalledTimes(1);
+    expect(showToast).toHaveBeenCalledWith(expect.stringContaining("disconnected"), "error");
+
+    function countStartCalls(): number {
+      return fetchMock.mock.calls.filter((call: unknown[]) => call[0] === "/api/vst/start").length;
+    }
+
+    expect(countStartCalls()).toBe(1);
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(2000);
+    });
+
+    expect(countStartCalls()).toBe(2);
+
+    act(() => root.unmount());
+  });
+});
+
+// ── Global suspend: ANY disconnect permanently stops ALL future streaming ───
+//
+// Task 13b (round 3) bug history: a WS disconnect does NOT imply the sidecar
+// process (and its server-side `_tracks` dict) was torn down —
+// `startVstSidecar` reuses the SAME running process in the common case (see
+// useVstHost's handleDisconnect doc-comment). Round 1 mirrored the sidecar's
+// index assignment client-side and detected collisions after the fact; round
+// 2 snapshotted `loadedTracksRef`'s keys into an `unsafeAfterDisconnectRef`
+// set right before a disconnect cleared it, to stop those SPECIFIC tracks
+// from being silently reloaded. Round 2's review found a real gap: a track
+// that was in `trackOrderRef` (i.e. had already reserved a server-side
+// trackIndex via a successful `loadChain`) but not yet in `loadedTracksRef`
+// (its local AudioContext/AudioWorkletNode wiring hadn't finished, or had
+// thrown) was wiped from `trackOrderRef` on disconnect WITHOUT being marked
+// unsafe — so it got blindly reloaded post-reconnect with zero collision
+// detection. Enumerating every such in-flight state correctly has now failed
+// twice, so this hook replaces all per-track tracking with one permanent,
+// whole-hook `suspendedRef`: once ANY disconnect fires, NOTHING streams
+// through this hook instance again — not a previously-loaded track, not a
+// previously-attempted one, and not a track that only appears in the DOM
+// for the first time after the disconnect. The test below specifically
+// covers that last case (a track never seen by ANY tracker before the
+// disconnect), since that's exactly what round 2's narrower mechanism missed.
+
+describe("useVstPreview — global suspend after any disconnect", () => {
+  it("never streams again after a disconnect — not even a track that never appeared in the DOM until after reconnect", async () => {
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+    const { root, audioEl1, audioEl2, showToast, socket } = await setupTwoLoadedTracks();
+
+    expect(audioEl1.muted).toBe(true);
+    expect(audioEl2.muted).toBe(true);
+
+    // Disconnect — the crash-fallback effect immediately reverts both
+    // tracks to dry, latches `suspendedRef` permanently, and schedules one
+    // auto-reconnect.
+    await act(async () => {
+      socket.close();
+      await flushAsyncWork();
+    });
+
+    expectBothTracksRevertedWithToast(audioEl1, audioEl2, showToast, "disconnected");
+
+    // A brand-new track appears in the DOM AFTER the disconnect — one this
+    // hook never attempted to load and that was never held by
+    // loadedTracksRef, trackOrderRef, OR round 2's (now-removed)
+    // unsafeAfterDisconnectRef. Under round 2's narrower per-track tracking
+    // this track wouldn't be excluded by anything and would have been
+    // blindly loaded once the sidecar reconnected.
+    const audioEl3 = document.createElement("audio");
+    audioEl3.id = "track-3";
+    audioEl3.setAttribute("data-vst-chain", "fx/track-3.vstchain.json");
+    audioEl3.setAttribute("src", "/api/projects/proj-1/preview/dry3.wav");
+    document.body.append(audioEl3);
+
+    // Advance past the 2s auto-restart delay so the reconnect attempt opens
+    // a new socket — representing the SAME still-running, stateful sidecar
+    // (server-side `_tracks` for track-1/track-2 were never torn down by
+    // this disconnect).
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(2000);
+      await flushAsyncWork();
+    });
+
+    const newSocket = required(FakeSocket.instances[1], "reconnected socket");
+    await act(async () => {
+      newSocket.open();
+      await flushAsyncWork();
+    });
+
+    function loadChainCallsFor(trackId: string): string[] {
+      return newSocket.sent.filter(
+        (raw) => raw.includes('"cmd":"load-chain"') && raw.includes(`"trackId":"${trackId}"`),
+      );
+    }
+
+    // The fix: NOTHING gets (re)loaded on the new connection post-disconnect
+    // — previously-streamed tracks stay in dry fallback, and so does a track
+    // that only showed up in the DOM after the disconnect.
+    expect(loadChainCallsFor("track-1")).toHaveLength(0);
+    expect(loadChainCallsFor("track-2")).toHaveLength(0);
+    expect(loadChainCallsFor("track-3")).toHaveLength(0);
+    expect(audioEl1.muted).toBe(false);
+    expect(audioEl2.muted).toBe(false);
+    expect(audioEl3.muted).toBe(false);
+
+    act(() => root.unmount());
+  });
+
+  it("tears down a track whose local wiring was still in flight when the disconnect fired, instead of leaving it muted with no audio ever routed to it", async () => {
+    // Controls the timing of `audioContext.audioWorklet.addModule()` so the
+    // test can land the disconnect exactly between the sidecar's successful
+    // `chain-loaded` reply (which resolves `api.loadChain`) and the local
+    // AudioContext/AudioWorkletNode wiring finishing — the exact gap round
+    // 2's per-track "unsafe" snapshot missed, because at that moment this
+    // track is in neither `loadedTracksRef` nor `trackOrderRef` yet.
+    let releaseAddModule: (() => void) | null = null;
+    class GatedAudioContext extends FakeAudioContext {
+      constructor(options?: { sampleRate?: number }) {
+        super(options);
+        this.audioWorklet = {
+          addModule: vi.fn(
+            () =>
+              new Promise<void>((resolve) => {
+                releaseAddModule = resolve;
+              }),
+          ),
+        };
+      }
+    }
+    vi.stubGlobal("AudioContext", GatedAudioContext);
+
+    const { root, audioEl, showToast } = mountHarness("proj-1", { version: 1, plugins: [] });
+
+    await act(async () => {
+      await openFirstSocket();
+    });
+    const socket = required(FakeSocket.instances[0], "socket");
+
+    await act(async () => {
+      await emitChainLoaded({ trackId: "track-1", sampleRate: 48000 });
+    });
+
+    // Server-side load-chain succeeded, but local wiring is stuck awaiting
+    // our gated `addModule()` — the track isn't muted yet and isn't loaded.
+    expect(audioEl.muted).toBe(false);
+    expect(releaseAddModule).not.toBeNull();
+
+    await act(async () => {
+      socket.close();
+      await flushAsyncWork();
+    });
+
+    expect(showToast).toHaveBeenCalledWith(expect.stringContaining("disconnected"), "error");
+
+    // Now let the in-flight local wiring finish — AFTER the disconnect
+    // already fired and latched suspendedRef.
+    await act(async () => {
+      required(releaseAddModule, "releaseAddModule")();
+      await flushAsyncWork();
+    });
+
+    // Must be torn down to its original dry state, not left muted with a
+    // worklet that will never receive another PCM frame.
+    expect(audioEl.muted).toBe(false);
+    expect(required(FakeAudioContext.instances[0], "gated audio context").close).toHaveBeenCalled();
+
+    act(() => root.unmount());
+  });
+});
diff --git a/packages/studio/src/player/hooks/useVstPreview.ts b/packages/studio/src/player/hooks/useVstPreview.ts
new file mode 100644
index 0000000000..874c9d3b9d
--- /dev/null
+++ b/packages/studio/src/player/hooks/useVstPreview.ts
@@ -0,0 +1,399 @@
+import { useEffect, useRef, type RefObject } from "react";
+import { liveTime, usePlayerStore } from "../store/playerStore";
+import type { TransportMsg, UseVstHostResult } from "../../hooks/useVstHost";
+import { STUDIO_VST_ENABLED } from "../../components/editor/manualEditingAvailability";
+import {
+  collectVstChainAudioEls,
+  dbg,
+  decodePcmFrame,
+  isLoadAborted,
+  reconcileRemovedTracks,
+  removeFromTrackOrder,
+  reseekLoadedTracks,
+  resumeSuspendedContexts,
+  runVstLoadScan,
+  teardownTrack,
+  type LoadedVstTrack,
+} from "./useVstPreviewHelpers";
+
+export { decodePcmFrame } from "./useVstPreviewHelpers";
+
+const DRIFT_CHECK_INTERVAL_MS = 500;
+const RESTART_DELAY_MS = 2000;
+
+/**
+ * Streams live VST-processed audio into the preview.
+ *
+ * When at least one timeline `<audio data-vst-chain="...">` element is
+ * present and the sidecar (`useVstHost`) is ready: loads each track's chain,
+ * mutes the dry element, and plays the sidecar's processed PCM through a
+ * `vst-stream` AudioWorklet instead — kept in sync with the transport
+ * (play/pause/seek) and a periodic drift check. On a sidecar crash/
+ * disconnect, falls back to the original dry audio, surfaces a toast, and
+ * attempts one automatic sidecar reconnect for the shared connection's sake
+ * — but VST STREAMING ITSELF STAYS PERMANENTLY SUSPENDED for the rest of
+ * this hook instance's lifetime after the FIRST disconnect for ANY reason
+ * (see `suspendedRef` below): the sidecar's own track-index assignment can
+ * silently misroute or drop audio across a reconnect in ways this client
+ * cannot fully predict (see `useVstHost`'s doc-comments), so this hook
+ * intentionally never resumes streaming on its own — only a fresh mount
+ * (i.e. reloading the composition preview) does.
+ *
+ * Takes its `useVstHost()` instance as a parameter rather than calling the
+ * hook itself: the FX property panel (`propertyPanelVstSection.tsx`) also
+ * needs a `VstHostApi`, and the sidecar's wire protocol can't tell two
+ * independent WebSocket connections apart safely (see `onChainLoaded`'s
+ * doc-comment) — so the whole app shares exactly one connection, mounted
+ * once in `NLEProvider` (`NLEContext.tsx`) and exposed to every consumer,
+ * including this hook, via context.
+ */
+export function useVstPreview(
+  iframeRef: RefObject<HTMLIFrameElement | null>,
+  projectId: string | undefined,
+  vstHost: UseVstHostResult,
+  showToast?: (message: string, tone?: "error" | "info") => void,
+): void {
+  const { status, api, ensureStarted, onPcmFrame, sendTransport, onDisconnect, onChainLoaded } =
+    vstHost;
+
+  const loadedTracksRef = useRef<Map<string, LoadedVstTrack>>(new Map());
+  const trackOrderRef = useRef<string[]>([]);
+  /** trackIds with a `loadChain` call currently in flight — see `isTrackAlreadyHandled`'s doc-comment for why this exists. */
+  const pendingTrackIdsRef = useRef<Set<string>>(new Set());
+  const restartAttemptedRef = useRef(false);
+  // Set permanently the FIRST time this hook instance observes a disconnect
+  // (via `onDisconnect`, below) — never reset back to `false` for the rest of
+  // this hook instance's lifetime, even once the sidecar reconnects.
+  //
+  // Earlier attempts (see git history) tried to track, per track, whether
+  // reloading that SPECIFIC trackId post-reconnect was safe:
+  // round 1 mirrored the sidecar's index assignment and detected collisions
+  // after the fact; round 2 added a `Set` of trackIds snapshotted as "unsafe"
+  // from `loadedTracksRef` right before a disconnect clears it. Both rounds
+  // of review found a real gap: there is no complete way to enumerate "every
+  // track whose state might be compromised" from outside the sidecar, because
+  // the sidecar's own index-assignment rule (`self._tracks.pop(track_id,
+  // None)` then `TrackStream(len(self._tracks), ...)` in server.py) can
+  // reassign colliding indices on ANY reload, and a WS disconnect does not
+  // reliably tell the client whether the sidecar process (and its `_tracks`
+  // dict) is the same one from before or a fresh restart (see useVstHost's
+  // `handleDisconnect` doc-comment) — so a track that was never in
+  // `loadedTracksRef` (e.g. one whose local wiring was still in flight, or
+  // one that doesn't exist in the DOM yet) is just as unsafe to load as one
+  // that was.
+  //
+  // Rather than trying a third time to enumerate every in-flight state
+  // correctly, this flag makes the rule deliberately blunt and provably
+  // complete: once ANY disconnect has been observed, NOTHING streams through
+  // this hook instance again, ever — not a previously-loaded track, not a
+  // previously-attempted-but-failed one, and not a track that only appears in
+  // the DOM after the disconnect. See the "Load chains" effect below, which
+  // checks this flag before doing anything, and the crash-fallback effect,
+  // which sets it.
+  const suspendedRef = useRef(false);
+
+  // `usePlayerStore`'s `currentTime` is a Zustand field the RAF playback loop
+  // deliberately only syncs "once at end" (see useTimelinePlayerLoop.ts) —
+  // updating it every frame would trigger a React re-render 60x/second. The
+  // actual continuously-updating playhead is `liveTime`, a separate
+  // subscribe/notify pub-sub built for exactly this (see playerStore.ts).
+  // Reading `usePlayerStore.getState().currentTime` here for drift-checking
+  // or a transport "play" position would see a value frozen at whatever it
+  // was when playback last stopped — for a fresh play from the start, that's
+  // permanently 0, so every drift check sees the sidecar's real, advancing
+  // position as fully drifted and forces a reseek back to 0 every tick.
+  const liveTimeRef = useRef(0);
+  useEffect(() => {
+    const unsubscribe = liveTime.subscribe((t) => {
+      liveTimeRef.current = t;
+    });
+    return () => {
+      unsubscribe();
+    };
+  }, []);
+
+  // Re-run the DOM scans whenever the timeline's elements change — the
+  // reliable existing signal that the preview DOM was reloaded/edited.
+  const elements = usePlayerStore((s) => s.elements);
+  // Also re-run when the FX panel adds/removes/swaps a chain file: that rewrite
+  // is invisible to `elements`, so the panel bumps this counter to drive the
+  // load effect's content-diff reconcile (see playerStore's vstChainRevision).
+  const vstChainRevision = usePlayerStore((s) => s.vstChainRevision);
+
+  // ── Lazily start the sidecar once a vst-chain track appears ─────────────
+  useEffect(() => {
+    if (!STUDIO_VST_ENABLED) return;
+    if (!projectId || status !== "idle") return;
+    const doc = iframeRef.current?.contentDocument;
+    if (!doc) return;
+    if (collectVstChainAudioEls(doc).length === 0) return;
+    void ensureStarted();
+  }, [projectId, status, elements, iframeRef, ensureStarted]);
+
+  // Clears the "already attempted one auto-restart" flag once the sidecar is
+  // healthy again, so a LATER disconnect still gets its own one retry.
+  useEffect(() => {
+    if (status === "ready") restartAttemptedRef.current = false;
+  }, [status]);
+
+  // ── Load chains + mute dry elements + spin up worklets ───────────────────
+  useEffect(() => {
+    // `suspendedRef` is the blunt, permanent gate: once ANY disconnect has
+    // been observed by this hook instance, refuse to load ANY track — not
+    // just ones this effect has already seen — for the rest of this hook's
+    // lifetime (see suspendedRef's doc-comment above).
+    if (!projectId || status !== "ready" || !api || suspendedRef.current) return;
+    const doc = iframeRef.current?.contentDocument;
+    if (!doc) return;
+    const audioEls = collectVstChainAudioEls(doc);
+
+    // Reconcile before (re)loading — see `reconcileRemovedTracks`'s
+    // doc-comment. Runs even when no vst-chain elements remain (a full
+    // removal), so the dry element gets unmuted.
+    reconcileRemovedTracks(audioEls, loadedTracksRef.current, trackOrderRef.current);
+
+    if (audioEls.length === 0) return;
+
+    const workletModuleUrl = new URL("../lib/vstStreamWorklet.js", import.meta.url).href;
+    let cancelled = false;
+
+    void runVstLoadScan({
+      audioEls,
+      projectId,
+      api,
+      workletModuleUrl,
+      showToast,
+      sendTransport,
+      loadedTracks: loadedTracksRef.current,
+      trackOrder: trackOrderRef.current,
+      pendingTrackIds: pendingTrackIdsRef.current,
+      isAborted: () => isLoadAborted(cancelled, suspendedRef.current),
+      isSuspended: () => suspendedRef.current,
+      liveTimeSec: () => liveTimeRef.current,
+    });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [projectId, status, api, elements, vstChainRevision, iframeRef, sendTransport, showToast]);
+
+  // ── Resync trackIndex if anyone reloads an already-loaded track's chain ──
+  // This connection is now shared with the FX property panel (see the
+  // module doc-comment): if the panel — or any other future caller sharing
+  // this `useVstHost()` instance — reloads a chain for a trackId this hook
+  // already streams, the sidecar reassigns that track's wire trackIndex
+  // (`useVstHost`'s `assignNextTrackIndex`, mirroring stream.py's
+  // `TrackStream(len(self._tracks), ...)`). A trackIndex cached from the
+  // initial load would silently misroute PCM frames from then on, so update
+  // it from the broadcast event instead of trusting that stale value.
+  useEffect(() => {
+    return onChainLoaded((trackId, trackIndex) => {
+      const track = loadedTracksRef.current.get(trackId);
+      if (!track) return; // not a track this hook streams — nothing to resync
+
+      // The sidecar's own index-assignment rule can (by design — see
+      // assignNextTrackIndex's doc-comment) hand two DIFFERENT trackIds the
+      // same numeric index right after a reload (a brief dict-shrink from
+      // popping the reloaded key). The wire frame carries only that number,
+      // so once two loaded tracks collide on it, PCM can no longer be
+      // demultiplexed correctly for either. Rather than silently misroute
+      // audio to the wrong worklet, treat both sides of the collision as
+      // unsafe: revert them to dry playback and let a later DOM scan retry.
+      const collision = Array.from(loadedTracksRef.current.entries()).find(
+        ([otherId, other]) => otherId !== trackId && other.trackIndex === trackIndex,
+      );
+      if (collision) {
+        const [otherId, otherTrack] = collision;
+        loadedTracksRef.current.delete(trackId);
+        loadedTracksRef.current.delete(otherId);
+        removeFromTrackOrder(trackOrderRef.current, [trackId, otherId]);
+        void teardownTrack(track);
+        void teardownTrack(otherTrack);
+        showToast?.(
+          "VST track routing conflict detected — reverted affected tracks to unprocessed audio.",
+          "error",
+        );
+        return;
+      }
+
+      track.trackIndex = trackIndex;
+    });
+  }, [onChainLoaded, showToast]);
+
+  // ── Transport: play/pause ─────────────────────────────────────────────────
+  useEffect(() => {
+    return usePlayerStore.subscribe((state, prev) => {
+      if (state.isPlaying === prev.isPlaying) return;
+      dbg("transport", { isPlaying: state.isPlaying, loaded: loadedTracksRef.current.size });
+      if (loadedTracksRef.current.size === 0) return;
+      const timeSec = liveTimeRef.current;
+      if (state.isPlaying) {
+        resumeSuspendedContexts(loadedTracksRef.current.values());
+      }
+      const msg: TransportMsg = state.isPlaying
+        ? { action: "play", timeSec, rate: state.playbackRate }
+        : { action: "pause" };
+      sendTransport(msg);
+      // Realign the client rings on BOTH transitions. Play: to the integer
+      // sample position the sidecar starts streaming from (it just seeked to
+      // `timeSec`), and — via reset → setDriftBaseline — anchor drift
+      // measurement to this moment so the one-time play→first-frame latency
+      // isn't misread as drift. Sending transport FIRST, then resetting,
+      // keeps the worklet ring's expected position matching the frames now
+      // on their way; without this reset a stale ring from a previous run
+      // rejects every new frame. Pause: the sidecar streams `_PUMP_LEAD_SEC`
+      // (~0.5s) of audio AHEAD of the playhead as a jitter cushion, all of it
+      // sitting in the worklet ring — pausing only stops the pump, so
+      // without a flush the ring audibly drains that buffered lead for up to
+      // a second after the pause click. The reset zero-fills the ring, so
+      // pause is silent immediately; the next play reseeks anyway.
+      reseekLoadedTracks(loadedTracksRef.current.values(), timeSec);
+    });
+  }, [sendTransport]);
+
+  // ── Transport: seeks — same requestedSeekTime useTimelinePlayer consumes ─
+  useEffect(() => {
+    return usePlayerStore.subscribe((state, prev) => {
+      if (state.requestedSeekTime === null || state.requestedSeekTime === prev.requestedSeekTime) {
+        return;
+      }
+      if (loadedTracksRef.current.size === 0) return;
+      const timeSec = state.requestedSeekTime;
+      sendTransport({ action: "seek", timeSec });
+      reseekLoadedTracks(loadedTracksRef.current.values(), timeSec);
+    });
+  }, [sendTransport]);
+
+  // ── PCM frame routing ──────────────────────────────────────────────────────
+  useEffect(() => {
+    return onPcmFrame((buf) => {
+      // TEMP DEBUG — remove after diagnosis
+      const w = window as unknown as { __vstPcm?: { n: number; dropped: number } };
+      w.__vstPcm = w.__vstPcm ?? { n: 0, dropped: 0 };
+      w.__vstPcm.n += 1;
+      if (loadedTracksRef.current.size === 0) {
+        w.__vstPcm.dropped += 1;
+        return;
+      }
+      const frame = decodePcmFrame(buf);
+      for (const track of loadedTracksRef.current.values()) {
+        if (track.trackIndex !== frame.trackIndex) continue;
+        track.driftTracker.push(frame.samplePos, frame.left, frame.right);
+        track.workletNode.port.postMessage(
+          { type: "pcm", samplePos: frame.samplePos, left: frame.left, right: frame.right },
+          [frame.left.buffer, frame.right.buffer],
+        );
+        return;
+      }
+      // No loaded track claims this trackIndex — drop the frame.
+      w.__vstPcm.dropped += 1;
+    });
+  }, [onPcmFrame]);
+
+  // ── Periodic drift check ───────────────────────────────────────────────────
+  useEffect(() => {
+    const interval = setInterval(() => {
+      if (loadedTracksRef.current.size === 0) return;
+      const timeSec = liveTimeRef.current;
+      const drifted = Array.from(loadedTracksRef.current.values()).some((track) =>
+        track.driftTracker.needsResync(timeSec),
+      );
+      if (!drifted) return;
+      // The sidecar coalesces repeated seeks server-side — no client-side
+      // coalescing needed here.
+      sendTransport({ action: "seek", timeSec });
+      reseekLoadedTracks(loadedTracksRef.current.values(), timeSec);
+    }, DRIFT_CHECK_INTERVAL_MS);
+    return () => clearInterval(interval);
+  }, [sendTransport]);
+
+  // Read via ref (not the closed-over `ensureStarted`) inside the deferred
+  // restart below: `ensureStarted`'s identity — and its internal `status`
+  // read — changes on every status transition, including the very one
+  // disconnect just caused. A closure captured at disconnect time would
+  // still see the pre-disconnect "ready" status 2s later and short-circuit
+  // (useVstHost's `ensureStarted` treats stale-`status===ready` + a still-
+  // non-null `socketRef.current`, which disconnect never nils out, as
+  // already-connected). The ref always resolves to the latest closure.
+  const ensureStartedRef = useRef(ensureStarted);
+  ensureStartedRef.current = ensureStarted;
+
+  // ── Crash fallback ──────────────────────────────────────────────────────────
+  useEffect(() => {
+    return onDisconnect(() => {
+      dbg("disconnect", { wasAlreadySuspended: suspendedRef.current });
+      const wasAlreadySuspended = suspendedRef.current;
+      // Permanent, one-way: the very first disconnect this hook instance
+      // ever observes suspends VST streaming for the rest of its lifetime
+      // (see suspendedRef's doc-comment above) — set BEFORE tearing anything
+      // down so the "Load chains" effect's in-flight re-checks (above) see it
+      // as soon as possible, and regardless of whether any track happened to
+      // be loaded at this exact moment.
+      suspendedRef.current = true;
+
+      // Tear down anything actually loaded right now (if this is the first
+      // disconnect) down to dry playback. On a later disconnect this is a
+      // no-op in practice — nothing gets loaded once suspended, so
+      // `loadedTracksRef` stays empty — but running it unconditionally costs
+      // nothing and needs no extra branch.
+      const tracks = Array.from(loadedTracksRef.current.values());
+      loadedTracksRef.current.clear();
+      trackOrderRef.current.length = 0;
+      for (const track of tracks) {
+        void teardownTrack(track);
+      }
+
+      // Only the transition into suspension is newsworthy — a later
+      // disconnect (which can only happen after suspension already latched)
+      // doesn't need a second toast or another restart attempt.
+      if (wasAlreadySuspended) return;
+
+      // NOTE: there is currently no "reopen the FX panel" (or any other)
+      // trigger that calls `ensureStarted()` again for this hook — this
+      // suspension is NOT recoverable within the lifetime of this mounted
+      // hook instance. The only way to stream VST audio again is a fresh
+      // mount of `useVstPreview` (i.e. reloading/remounting the composition
+      // preview), which gets its own fresh `suspendedRef`. An earlier version
+      // of this comment claimed reopening the FX panel would re-trigger
+      // `ensureStarted()` "once wired" — grepping propertyPanelVstSection.tsx
+      // shows no such call exists, and NLEProvider (which mounts both
+      // `useVstHost` and this hook exactly once per studio session, not keyed
+      // by projectId or refreshKey — see NLEContext.tsx) never remounts on
+      // its own, so that recovery path was aspirational, not real.
+      showToast?.(
+        "VST plugin host disconnected — reverted to unprocessed audio. " +
+          "VST preview is now disabled for the rest of this session; reload the preview to re-enable it.",
+        "error",
+      );
+
+      if (restartAttemptedRef.current) return;
+      restartAttemptedRef.current = true;
+      setTimeout(() => {
+        void ensureStartedRef.current().catch(() => {
+          // Second attempt also failed. Regardless of outcome, THIS hook's
+          // streaming stays suspended (see suspendedRef) — but the
+          // underlying `useVstHost` connection is shared with the FX panel
+          // (see the module doc-comment), so still worth one retry for that
+          // other consumer's sake even though it can't unstick this hook.
+        });
+      }, RESTART_DELAY_MS);
+    });
+  }, [onDisconnect, showToast]);
+
+  // ── Unmount cleanup ─────────────────────────────────────────────────────────
+  useEffect(() => {
+    // Captured once: both refs hold long-lived data (not DOM nodes) mutated
+    // in place for the life of this hook, so reading them here — rather
+    // than re-reading `.current` inside the returned cleanup closure below —
+    // still reflects every track loaded up to the moment of unmount.
+    const tracks = loadedTracksRef.current;
+    const trackOrder = trackOrderRef.current;
+    return () => {
+      for (const track of tracks.values()) {
+        void teardownTrack(track);
+      }
+      tracks.clear();
+      trackOrder.length = 0;
+    };
+  }, []);
+}
diff --git a/packages/studio/src/player/hooks/useVstPreviewHelpers.ts b/packages/studio/src/player/hooks/useVstPreviewHelpers.ts
new file mode 100644
index 0000000000..7ad2d53074
--- /dev/null
+++ b/packages/studio/src/player/hooks/useVstPreviewHelpers.ts
@@ -0,0 +1,591 @@
+/**
+ * Pure/stateless helpers for `useVstPreview.ts`: wire-format decode, DOM
+ * scanning, the loaded-track bookkeeping record + its lifecycle functions,
+ * and the per-track chain-load pipeline (fetch chain → resolve local wav
+ * path → `loadChain` → wire up local playback). None of these read or write
+ * React state directly — the hook passes in whatever refs/values they need
+ * and applies their results.
+ */
+import { usePlayerStore } from "../store/playerStore";
+import type { TransportMsg } from "../../hooks/useVstHost";
+import type { VstHostApi } from "../../components/editor/propertyPanelVstShared";
+import { isRecord, parseChainFile, type ChainFileJson } from "../../utils/vstChainFile";
+import { VstRingBuffer } from "../lib/vstRingBuffer";
+
+// TEMP DEBUG — remove after diagnosis. Persists a lifecycle trace on window
+// so a failing run can be read back from the console after the fact.
+export function dbg(e: string, d?: unknown): void {
+  const w = window as unknown as { __vstTrace?: unknown[] };
+  w.__vstTrace = w.__vstTrace ?? [];
+  w.__vstTrace.push({ t: Math.round(performance.now()), e, d });
+}
+
+// ── Wire-format decode ────────────────────────────────────────────────────
+// Mirrors the sidecar's `encode_frame` (stream.py in heygen-com/hyperframes-vst-host):
+// little-endian u32 trackIndex, f64 samplePos, then interleaved f32 stereo.
+
+export interface DecodedPcmFrame {
+  trackIndex: number;
+  samplePos: number;
+  left: Float32Array;
+  right: Float32Array;
+}
+
+export function decodePcmFrame(buf: ArrayBuffer): DecodedPcmFrame {
+  const view = new DataView(buf);
+  const trackIndex = view.getUint32(0, true);
+  const samplePos = view.getFloat64(4, true);
+  const interleaved = new Float32Array(buf, 12);
+  const n = Math.floor(interleaved.length / 2);
+  const left = new Float32Array(n);
+  const right = new Float32Array(n);
+  for (let i = 0; i < n; i++) {
+    left[i] = interleaved[2 * i];
+    right[i] = interleaved[2 * i + 1];
+  }
+  return { trackIndex, samplePos, left, right };
+}
+
+// ── DOM scan — mirrors timelineIframeHelpers' contentDocument reach-in ──
+
+function resolveVstTrackId(el: HTMLAudioElement): string {
+  return el.id || el.getAttribute("data-hf-id") || el.getAttribute("data-vst-chain") || "track";
+}
+
+export function collectVstChainAudioEls(doc: Document): HTMLAudioElement[] {
+  return Array.from(doc.querySelectorAll<HTMLAudioElement>("audio[data-vst-chain]"));
+}
+
+function readFileContent(value: unknown): string | null {
+  if (!isRecord(value)) return null;
+  return typeof value.content === "string" ? value.content : null;
+}
+
+/** Same fetch idiom as propertyPanelVstSection.tsx's readChainFile. */
+async function fetchChainFile(projectId: string, path: string): Promise<ChainFileJson | null> {
+  let response: Response;
+  try {
+    // `no-store`: the FX panel may have just rewritten this file; a cached GET
+    // would make the content-diff below miss the change and skip the reload.
+    response = await fetch(`/api/projects/${projectId}/files/${encodeURIComponent(path)}`, {
+      cache: "no-store",
+    });
+  } catch {
+    return null;
+  }
+  if (!response.ok) return null;
+  const body: unknown = await response.json().catch(() => null);
+  const content = readFileContent(body);
+  if (content === null) return null;
+  return parseChainFile(content);
+}
+
+/** Project-relative asset path from a resolved `/preview/*` URL — the part
+ *  the static asset route (packages/studio-server/src/routes/preview.ts)
+ *  resolves against `project.dir`. */
+function projectRelativeAssetPath(previewUrl: string): string | null {
+  const marker = "/preview/";
+  const idx = previewUrl.indexOf(marker);
+  if (idx === -1) return null;
+  return decodeURIComponent(previewUrl.slice(idx + marker.length).split("?")[0] ?? "");
+}
+
+/**
+ * The sidecar is a native process on the same host — it opens audio via
+ * pedalboard's `AudioFile`, which needs a real filesystem path, not the
+ * `/preview/*` HTTP URL the dry `<audio>` element plays from (that URL isn't
+ * openable as a file at all, let alone the right one). Resolves it via the
+ * server's `/vst/wav-path` endpoint, which does the same `resolveWithinProject`
+ * join the static route itself uses.
+ */
+async function resolveLocalWavPath(projectId: string, previewUrl: string): Promise<string | null> {
+  const subPath = projectRelativeAssetPath(previewUrl);
+  if (!subPath) return null;
+  let response: Response;
+  try {
+    response = await fetch(
+      `/api/vst/wav-path?projectId=${encodeURIComponent(projectId)}&path=${encodeURIComponent(subPath)}`,
+    );
+  } catch {
+    return null;
+  }
+  if (!response.ok) return null;
+  const body: unknown = await response.json().catch(() => null);
+  return isRecord(body) && typeof body.path === "string" ? body.path : null;
+}
+
+// ── Loaded-track bookkeeping ──────────────────────────────────────────────
+
+export interface LoadedVstTrack {
+  audioEl: HTMLAudioElement;
+  audioContext: AudioContext;
+  workletNode: AudioWorkletNode;
+  /** Wire-format trackIndex — the sidecar's call-order of load-chain (see stream.py's `TrackStream(len(self._tracks), ...)`). */
+  trackIndex: number;
+  /** The dry file's real sample rate (see `LoadChainResult`'s doc-comment) —
+   *  this track's `audioContext` and `driftTracker` are both anchored to it,
+   *  so samplePos↔seconds conversions for THIS track must use it, not any
+   *  other track's rate or a shared constant. */
+  sampleRate: number;
+  originalMuted: boolean;
+  /** `JSON.stringify` of the chain this track was loaded from. The FX panel
+   *  rewrites a chain file IN PLACE (same `data-vst-chain` path) on add /
+   *  remove / swap, so the element identity is unchanged — this is how the
+   *  load effect detects the contents changed and reloads instead of leaving
+   *  the first-loaded effect streaming forever. */
+  chainKey: string;
+  /** Tracks expected write position / drift only — never read for playback. */
+  driftTracker: VstRingBuffer;
+  /** Latest underrun telemetry posted by the worklet (see vstStreamWorklet.js).
+   *  `totalSamples` is the cumulative count of zero-filled (ring-starved)
+   *  samples; during steady playback it MUST stay flat — a rising value means
+   *  the sidecar isn't keeping the ring fed (degraded/choppy audio). */
+  underrun: { totalSamples: number; atTime: number };
+}
+
+export async function teardownTrack(track: LoadedVstTrack): Promise<void> {
+  track.audioEl.muted = track.originalMuted;
+  try {
+    await track.audioContext.close();
+  } catch {
+    /* already closed */
+  }
+}
+
+export function reseekLoadedTracks(tracks: Iterable<LoadedVstTrack>, timeSec: number): void {
+  for (const track of tracks) {
+    // MUST floor to an integer sample: the sidecar streams frames whose
+    // `samplePos` is `int(timeSec * sample_rate)` (see stream.py `seek`), and
+    // the ring buffer's `push` accepts a block only if its `samplePos`
+    // exactly equals the expected position. A fractional reset target
+    // (`3.02s * 44100 = 133182.9…`) can never equal the sidecar's integer
+    // positions, so every pushed block is rejected — the ring starves, the
+    // worklet zero-fills (degraded audio), and `resyncNeeded` latches on,
+    // forcing this same broken reseek again on the next drift check.
+    const samplePos = Math.floor(timeSec * track.sampleRate);
+    track.workletNode.port.postMessage({ type: "reset", samplePos });
+    track.driftTracker.reset(samplePos, timeSec);
+  }
+}
+
+/**
+ * Each track's `AudioContext` (created in `createTrackPlaybackNode`, well
+ * before any play click — right when its chain finishes loading) starts
+ * `"suspended"` under the browser's autoplay policy and never resumes on its
+ * own. PCM frames still arrive and route to the worklet correctly even while
+ * suspended — the context just silently drops them instead of producing
+ * sound, so playback looks completely healthy from the wire protocol's side
+ * while staying inaudible. Resuming here, at the actual transport "play"
+ * transition (a real user gesture), is the one point guaranteed to satisfy
+ * the policy.
+ */
+export function resumeSuspendedContexts(tracks: Iterable<LoadedVstTrack>): void {
+  for (const track of tracks) {
+    dbg("resume", { trackIndex: track.trackIndex, state: track.audioContext.state });
+    if (track.audioContext.state === "suspended") void track.audioContext.resume();
+  }
+}
+
+/** Removes `ids` from `order` in place — the unmount-cleanup effect below captures the array once and relies on it never being reassigned. */
+export function removeFromTrackOrder(order: string[], ids: readonly string[]): void {
+  for (let i = order.length - 1; i >= 0; i -= 1) {
+    if (ids.includes(order[i])) order.splice(i, 1);
+  }
+}
+
+/** True once EITHER this specific effect run was cancelled (re-render/unmount) OR the whole hook has been permanently suspended by a disconnect (see `suspendedRef`). */
+export function isLoadAborted(cancelled: boolean, suspended: boolean): boolean {
+  return cancelled || suspended;
+}
+
+/** A track is already spoken for this session if it's fully loaded, has already reserved a server-side trackIndex via a prior `loadChain` success (see `loadVstTrack` — a local-wiring failure AFTER that point is never safe to retry, or the two indices would desync), or has a `loadChain` call currently in flight. That last case matters because the "Load chains" effect below can re-run (its dependency array includes `elements`, which can change several times in quick succession right after mount, before any prior run's async work has settled) — without this check, an overlapping re-run would issue a SECOND `loadChain` for the same trackId while the first is still pending, and `useVstHost`'s own supersede-guard would then reject that first (still-legitimate) attempt, so the track never finishes loading at all. */
+function isTrackAlreadyHandled(
+  trackId: string,
+  loadedTracks: ReadonlyMap<string, LoadedVstTrack>,
+  trackOrder: readonly string[],
+  pendingTrackIds: ReadonlySet<string>,
+): boolean {
+  return loadedTracks.has(trackId) || trackOrder.includes(trackId) || pendingTrackIds.has(trackId);
+}
+
+/** Creates the AudioContext + vst-stream worklet node for one loaded track. */
+async function createTrackPlaybackNode(
+  el: HTMLAudioElement,
+  trackIndex: number,
+  sampleRate: number,
+  workletModuleUrl: string,
+  chainKey: string,
+): Promise<LoadedVstTrack | null> {
+  let audioContext: AudioContext | null = null;
+  try {
+    // Must match the dry file's real rate — the sidecar streams PCM at that
+    // rate, not a fixed constant (see `LoadChainResult`'s doc-comment).
+    audioContext = new AudioContext({ sampleRate });
+    await audioContext.audioWorklet.addModule(workletModuleUrl);
+    const workletNode = new AudioWorkletNode(audioContext, "vst-stream", {
+      outputChannelCount: [2],
+    });
+    workletNode.connect(audioContext.destination);
+    const originalMuted = el.muted;
+    el.muted = true;
+    const track: LoadedVstTrack = {
+      audioEl: el,
+      audioContext,
+      workletNode,
+      trackIndex,
+      sampleRate,
+      originalMuted,
+      chainKey,
+      // 1s of headroom for drift bookkeeping (tracking-only — never read for
+      // playback), sized to this track's own real rate.
+      driftTracker: new VstRingBuffer(sampleRate, sampleRate),
+      underrun: { totalSamples: 0, atTime: 0 },
+    };
+    workletNode.port.onmessage = (event) => {
+      const data = event.data;
+      if (data && data.type === "underrun") {
+        track.underrun = { totalSamples: data.totalSamples, atTime: data.atTime };
+        // TEMP DEBUG — remove after diagnosis
+        dbg("underrun", { totalSamples: data.totalSamples, atTime: data.atTime });
+      }
+    };
+    dbg("wire:track-ready", { trackIndex, sampleRate, ctxState: audioContext.state });
+    return track;
+  } catch (err) {
+    dbg("wire:failed", String(err));
+    void audioContext?.close();
+    return null; // chain loaded server-side, but local playback wiring failed — stays dry
+  }
+}
+
+// ── loadVstTrack pipeline ─────────────────────────────────────────────────
+
+interface ResolvedChainSource {
+  chain: ChainFileJson;
+  wavPath: string;
+}
+
+/** Fetches the chain file + resolves the dry element's local wav path — the
+ *  two prerequisites `loadVstTrack` needs before it can call `api.loadChain`.
+ *  Returns `null` (safe to retry next scan — no server-side index consumed
+ *  yet) on any resolution failure. */
+async function resolveChainSource(
+  el: HTMLAudioElement,
+  trackId: string,
+  projectId: string,
+): Promise<ResolvedChainSource | null> {
+  const chainPath = el.getAttribute("data-vst-chain");
+  if (!chainPath) {
+    dbg("load:no-chain-attr", trackId);
+    return null;
+  }
+  const chain = await fetchChainFile(projectId, chainPath);
+  if (!chain) {
+    dbg("load:chain-fetch-failed", { trackId, chainPath });
+    return null; // no index consumed — safe to retry next scan
+  }
+  const dryWavUrl = el.currentSrc || el.src;
+  const wavPath = await resolveLocalWavPath(projectId, dryWavUrl);
+  if (!wavPath) {
+    dbg("load:wav-path-failed", { trackId, dryWavUrl });
+    return null; // can't resolve to a local file — safe to retry next scan
+  }
+  return { chain, wavPath };
+}
+
+interface LoadChainOutcome {
+  trackIndex: number;
+  sampleRate: number;
+  stable: boolean;
+}
+
+/** Calls the sidecar's `loadChain`, translating a rejection into `null`
+ *  (retryable — no index was ever consumed). */
+async function callLoadChain(
+  api: VstHostApi,
+  trackId: string,
+  chain: ChainFileJson,
+  wavPath: string,
+): Promise<LoadChainOutcome | null> {
+  try {
+    // Resolves with the sidecar-assigned wire trackIndex for this load (see
+    // useVstHost's `assignNextTrackIndex`) — authoritative for THIS call, but
+    // can go stale if anyone (including this same hook, on a later scan)
+    // reloads this trackId again; the `onChainLoaded` subscription (in
+    // useVstPreview) keeps it current for the lifetime of the loaded track.
+    // `sampleRate` is the dry file's real rate (see `LoadChainResult`'s
+    // doc-comment).
+    const { trackIndex, sampleRate, stable } = await api.loadChain(trackId, chain, wavPath);
+    dbg("load:chain-loaded", { trackId, trackIndex, sampleRate, stable });
+    return { trackIndex, sampleRate, stable };
+  } catch (err) {
+    dbg("load:loadChain-rejected", { trackId, err: String(err) });
+    return null; // sidecar rejected the chain (e.g. missing plugin) — retryable
+  }
+}
+
+/**
+ * Fetches + loads one track's chain and, on success, spins up its playback
+ * node. Returns `null` if the track should stay dry (fetch/parse failure,
+ * loadChain rejection, or local wiring failure) — the caller leaves the
+ * element unmuted in every `null` case.
+ */
+async function loadVstTrack(
+  el: HTMLAudioElement,
+  trackId: string,
+  projectId: string,
+  api: VstHostApi,
+  attemptedTrackIds: string[],
+  workletModuleUrl: string,
+  showToast?: (message: string, tone?: "error" | "info") => void,
+): Promise<LoadedVstTrack | null> {
+  const source = await resolveChainSource(el, trackId, projectId);
+  if (!source) return null;
+
+  const outcome = await callLoadChain(api, trackId, source.chain, source.wavPath);
+  if (!outcome) return null;
+
+  // Marks this trackId as having reserved a server-side slot, regardless of
+  // whether local wiring below succeeds (a local failure must never be
+  // retried, or a fresh loadChain would desync from what the sidecar already
+  // holds for this trackId).
+  attemptedTrackIds.push(trackId);
+
+  // The sidecar couldn't host this chain without producing NaN/Inf/runaway
+  // output (see its `probe_chain_stability`). Leave the element on its dry
+  // audio — streaming an unstable chain is silence at best — and tell the
+  // user which plugin is at fault rather than failing silently.
+  if (!outcome.stable) {
+    const label = source.chain.plugins[0]?.name ?? "This VST effect";
+    showToast?.(
+      `${label} isn't compatible with the offline VST host — playing the original audio instead.`,
+      "error",
+    );
+    return null;
+  }
+
+  return createTrackPlaybackNode(
+    el,
+    outcome.trackIndex,
+    outcome.sampleRate,
+    workletModuleUrl,
+    JSON.stringify(source.chain),
+  );
+}
+
+// ── Load-effect scan (per-DOM-scan reconcile + load loop) ────────────────
+
+/** Tears down any loaded track whose element is no longer a live vst-chain
+ *  element — its chain was removed in the FX panel, or a preview reload
+ *  replaced the DOM node. Clearing it from `trackOrder` (which doubles as
+ *  the "already attempted" set, see `isTrackAlreadyHandled`) is what lets
+ *  the SAME trackId reload when it reappears with a different chain — i.e.
+ *  how add / remove / swap in the panel actually takes audible effect. Runs
+ *  even when no vst-chain elements remain (a full removal), so the dry
+ *  element gets unmuted. */
+export function reconcileRemovedTracks(
+  liveAudioEls: readonly HTMLAudioElement[],
+  loadedTracks: Map<string, LoadedVstTrack>,
+  trackOrder: string[],
+): void {
+  const liveEls = new Set<HTMLAudioElement>(liveAudioEls);
+  for (const [trackId, track] of Array.from(loadedTracks.entries())) {
+    if (!liveEls.has(track.audioEl)) {
+      loadedTracks.delete(trackId);
+      removeFromTrackOrder(trackOrder, [trackId]);
+      void teardownTrack(track);
+    }
+  }
+}
+
+type TrackLoadDecision = "aborted" | "skip" | "proceed";
+
+/**
+ * Decides what the load loop should do next for one DOM element, BEFORE
+ * calling `loadVstTrack`:
+ *  - "aborted": the effect run was cancelled/suspended while this check was
+ *    async (re-fetching the chain file below) — the caller must stop the
+ *    whole scan, not just this element.
+ *  - "skip": either this trackId is already loaded with unchanged chain
+ *    contents, or it's already handled by `isTrackAlreadyHandled` (loaded /
+ *    reserved / in flight) — nothing to do this scan.
+ *  - "proceed": either this trackId is new, or its loaded chain's contents
+ *    changed (the FX panel rewrote the same `data-vst-chain` path — this
+ *    tears the stale track down as a side effect) — the caller should now
+ *    call `loadVstTrack`.
+ *
+ * Comparing chain CONTENTS — not just element identity — is what makes
+ * switching effects actually switch, instead of the first-loaded effect
+ * streaming forever.
+ */
+async function decideTrackLoadAction(
+  el: HTMLAudioElement,
+  trackId: string,
+  projectId: string,
+  loadedTracks: Map<string, LoadedVstTrack>,
+  trackOrder: string[],
+  pendingTrackIds: ReadonlySet<string>,
+  isAborted: () => boolean,
+): Promise<TrackLoadDecision> {
+  const existing = loadedTracks.get(trackId);
+  if (existing) {
+    const chainPath = el.getAttribute("data-vst-chain");
+    const current = chainPath ? await fetchChainFile(projectId, chainPath) : null;
+    if (isAborted()) return "aborted";
+    if (current && JSON.stringify(current) === existing.chainKey) return "skip"; // unchanged
+    // Changed (or unreadable): tear the old track down and fall through to
+    // reload from the current chain.
+    loadedTracks.delete(trackId);
+    removeFromTrackOrder(trackOrder, [trackId]);
+    void teardownTrack(existing);
+    return "proceed";
+  }
+  if (isTrackAlreadyHandled(trackId, loadedTracks, trackOrder, pendingTrackIds)) {
+    return "skip";
+  }
+  return "proceed";
+}
+
+/**
+ * Cancellation branch of the per-track load loop. A disconnect can land
+ * while `loadVstTrack` was in flight — including AFTER its server-side
+ * `load-chain` succeeded and its local AudioContext/AudioWorkletNode wiring
+ * finished (which mutes the element as a side effect, see
+ * `createTrackPlaybackNode`). Tear down fully via `teardownTrack` (not just
+ * close the AudioContext) so a track resolved mid-disconnect doesn't get
+ * left muted with no processed audio ever routed to it — a "half-loaded",
+ * permanently silent state.
+ *
+ * Cancellation (an effect re-run superseding this one — timeline `elements`
+ * churn right after mount does this routinely) must not strand the track:
+ * the superseding run already scanned and SKIPPED this trackId (the
+ * `pendingTrackIds` guard, while our load was in flight), and `loadVstTrack`
+ * reserved it in `trackOrder` (the "already attempted" set) — so with no
+ * further action, no later run would ever retry it. The track would sit
+ * permanently silent: chain loaded server-side, nothing streaming
+ * client-side (live-traced: `wire:track-ready` fires, then transport sees
+ * `loaded: 0` forever). Drop the reservation and poke the load effect to
+ * rescan against the CURRENT DOM (the element this run captured may be a
+ * dead node if the reload was an iframe swap — that's why the loaded track
+ * is torn down rather than adopted). Suspension is the exception:
+ * permanently suspended means never retry, by design.
+ */
+function handleCancelledTrackLoad(
+  loaded: LoadedVstTrack | null,
+  trackId: string,
+  trackOrder: string[],
+  suspended: boolean,
+): void {
+  if (loaded) void teardownTrack(loaded);
+  if (!suspended) {
+    removeFromTrackOrder(trackOrder, [trackId]);
+    usePlayerStore.getState().bumpVstChainRevision();
+  }
+}
+
+/**
+ * Registers a freshly loaded track and, if playback is already running,
+ * catches it up immediately. The transport play/pause effect only reacts to
+ * `isPlaying` CHANGING — if playback was already running by the time this
+ * track finished its async load (chain fetch + loadChain + local
+ * AudioContext/worklet wiring can easily outlast a quick click), that
+ * transition already fired and found the loaded-tracks map empty, so it
+ * silently skipped sending "play". Catch this track up to the current
+ * transport state now, or it never streams for the rest of this playback
+ * run.
+ */
+function applyNewlyLoadedTrack(
+  loaded: LoadedVstTrack,
+  trackId: string,
+  loadedTracks: Map<string, LoadedVstTrack>,
+  sendTransport: (msg: TransportMsg) => void,
+  liveTimeSec: number,
+): void {
+  loadedTracks.set(trackId, loaded);
+  const { isPlaying, playbackRate } = usePlayerStore.getState();
+  if (isPlaying) {
+    resumeSuspendedContexts([loaded]);
+    sendTransport({ action: "play", timeSec: liveTimeSec, rate: playbackRate });
+    reseekLoadedTracks([loaded], liveTimeSec);
+  }
+}
+
+export interface LoadScanParams {
+  audioEls: readonly HTMLAudioElement[];
+  projectId: string;
+  api: VstHostApi;
+  workletModuleUrl: string;
+  showToast?: (message: string, tone?: "error" | "info") => void;
+  sendTransport: (msg: TransportMsg) => void;
+  loadedTracks: Map<string, LoadedVstTrack>;
+  trackOrder: string[];
+  pendingTrackIds: Set<string>;
+  /** Re-checked live on every iteration (not just once) — a disconnect can
+   *  land while this loop is mid-flight awaiting a previous track's
+   *  `loadVstTrack` call. */
+  isAborted: () => boolean;
+  isSuspended: () => boolean;
+  liveTimeSec: () => number;
+}
+
+/** Runs one DOM-scan's worth of track loads sequentially, one element at a
+ *  time — see `decideTrackLoadAction`, `handleCancelledTrackLoad`, and
+ *  `applyNewlyLoadedTrack` for what happens at each stage. */
+export async function runVstLoadScan(params: LoadScanParams): Promise<void> {
+  const {
+    audioEls,
+    projectId,
+    api,
+    workletModuleUrl,
+    showToast,
+    sendTransport,
+    loadedTracks,
+    trackOrder,
+    pendingTrackIds,
+    isAborted,
+    isSuspended,
+    liveTimeSec,
+  } = params;
+
+  for (const el of audioEls) {
+    if (isAborted()) return;
+    const trackId = resolveVstTrackId(el);
+
+    const decision = await decideTrackLoadAction(
+      el,
+      trackId,
+      projectId,
+      loadedTracks,
+      trackOrder,
+      pendingTrackIds,
+      isAborted,
+    );
+    if (decision === "aborted") return;
+    if (decision === "skip") continue;
+
+    pendingTrackIds.add(trackId);
+    let loaded: LoadedVstTrack | null;
+    try {
+      loaded = await loadVstTrack(
+        el,
+        trackId,
+        projectId,
+        api,
+        trackOrder,
+        workletModuleUrl,
+        showToast,
+      );
+    } finally {
+      pendingTrackIds.delete(trackId);
+    }
+
+    if (isAborted()) {
+      handleCancelledTrackLoad(loaded, trackId, trackOrder, isSuspended());
+      return;
+    }
+
+    if (loaded) {
+      applyNewlyLoadedTrack(loaded, trackId, loadedTracks, sendTransport, liveTimeSec());
+    }
+  }
+}
diff --git a/packages/studio/src/player/lib/timelineIframeHelpers.ts b/packages/studio/src/player/lib/timelineIframeHelpers.ts
index 9be165f1de..50baadb09a 100644
--- a/packages/studio/src/player/lib/timelineIframeHelpers.ts
+++ b/packages/studio/src/player/lib/timelineIframeHelpers.ts
@@ -39,10 +39,10 @@ export function normalizePreviewViewport(doc: Document, win: Window): void {
   win.scrollTo({ top: 0, left: 0, behavior: "auto" });
 }
 
-// Legacy recovery retained until versioned composition manifests complete
-// their compatibility soak across published CDN runtimes.
-// fallow-ignore-next-line complexity
-export function autoHealMissingCompositionIds(doc: Document): void {
+// Scan <style>/<script> text for data-composition-id="..." references. These
+// are compositions the CDN runtime's own code refers to by id but that may not
+// carry the attribute on their host element yet.
+function extractReferencedCompositionIds(doc: Document): Set<string> {
   const compositionIdRe = /data-composition-id=["']([^"']+)["']/gi;
   const referencedIds = new Set<string>();
   const scopedNodes = Array.from(doc.querySelectorAll("style, script"));
@@ -55,7 +55,23 @@ export function autoHealMissingCompositionIds(doc: Document): void {
       if (id) referencedIds.add(id);
     }
   }
+  return referencedIds;
+}
+
+// Resolve a referenced composition id to its candidate host element, trying
+// the loader's own naming conventions before the bare id.
+function resolveCompositionIdHost(doc: Document, compId: string): HTMLElement | null {
+  return (
+    doc.getElementById(`${compId}-layer`) ||
+    doc.getElementById(`${compId}-comp`) ||
+    doc.getElementById(compId)
+  );
+}
 
+// Legacy recovery retained until versioned composition manifests complete
+// their compatibility soak across published CDN runtimes.
+export function autoHealMissingCompositionIds(doc: Document): void {
+  const referencedIds = extractReferencedCompositionIds(doc);
   if (referencedIds.size === 0) return;
 
   const existingIds = new Set<string>();
@@ -67,10 +83,7 @@ export function autoHealMissingCompositionIds(doc: Document): void {
 
   for (const compId of referencedIds) {
     if (compId === "root" || existingIds.has(compId)) continue;
-    const host =
-      doc.getElementById(`${compId}-layer`) ||
-      doc.getElementById(`${compId}-comp`) ||
-      doc.getElementById(compId);
+    const host = resolveCompositionIdHost(doc, compId);
     if (!host) continue;
     if (!host.getAttribute("data-composition-id")) {
       host.setAttribute("data-composition-id", compId);
@@ -232,7 +245,11 @@ export function scrubPreviewAudio(
   }
   if (!doc) return;
   const el = resolveScrubAudioEl(doc, musicId);
-  if (el) applyScrub(el, audioFileTime);
+  // A VST-chain track is permanently muted and fed by the VST preview hook's
+  // own AudioContext/AudioWorklet (packages/studio/src/player/hooks/useVstPreview.ts),
+  // not this raw dry element — scrubbing it here would force-unmute the
+  // untreated source file underneath the processed stream.
+  if (el && !el.hasAttribute("data-vst-chain")) applyScrub(el, audioFileTime);
 }
 
 export function stopScrubPreviewAudio(): void {
diff --git a/packages/studio/src/player/lib/vstRingBuffer.test.ts b/packages/studio/src/player/lib/vstRingBuffer.test.ts
new file mode 100644
index 0000000000..bd3613e5b4
--- /dev/null
+++ b/packages/studio/src/player/lib/vstRingBuffer.test.ts
@@ -0,0 +1,261 @@
+import { describe, expect, it } from "vitest";
+import { VstRingBuffer } from "./vstRingBuffer";
+
+const SAMPLE_RATE = 48000;
+
+function makeStereo(n: number, seed = 1): { left: Float32Array; right: Float32Array } {
+  const left = new Float32Array(n);
+  const right = new Float32Array(n);
+  for (let i = 0; i < n; i++) {
+    left[i] = seed + i;
+    right[i] = -(seed + i);
+  }
+  return { left, right };
+}
+
+/** Reads `n` samples from `ring` into fresh output buffers — the shared
+ *  read-and-assert shape every test below needs. */
+function readN(
+  ring: VstRingBuffer,
+  n: number,
+): { left: Float32Array; right: Float32Array; readCount: number } {
+  const left = new Float32Array(n);
+  const right = new Float32Array(n);
+  const readCount = ring.read([left, right], n);
+  return { left, right, readCount };
+}
+
+describe("VstRingBuffer", () => {
+  it("round-trips a sequential push/read at the expected position", () => {
+    const ring = new VstRingBuffer(SAMPLE_RATE, SAMPLE_RATE);
+    const { left, right } = makeStereo(4, 10);
+    ring.push(0, left, right);
+
+    const { left: outLeft, right: outRight, readCount } = readN(ring, 4);
+
+    expect(readCount).toBe(4);
+    expect(Array.from(outLeft)).toEqual([10, 11, 12, 13]);
+    expect(Array.from(outRight)).toEqual([-10, -11, -12, -13]);
+    expect(ring.expectedPos).toBe(4);
+  });
+
+  it("advances expectedPos across multiple contiguous pushes", () => {
+    const ring = new VstRingBuffer(SAMPLE_RATE, SAMPLE_RATE);
+    const first = makeStereo(1024, 0);
+    ring.push(0, first.left, first.right);
+    expect(ring.expectedPos).toBe(1024);
+
+    const second = makeStereo(1024, 1024);
+    ring.push(1024, second.left, second.right);
+    expect(ring.expectedPos).toBe(2048);
+  });
+
+  it("fills silence and reports the real count on a full underrun (nothing buffered)", () => {
+    const ring = new VstRingBuffer(SAMPLE_RATE, SAMPLE_RATE);
+    const { left: outLeft, right: outRight, readCount } = readN(ring, 8);
+
+    expect(readCount).toBe(0);
+    expect(Array.from(outLeft)).toEqual(new Array(8).fill(0));
+    expect(Array.from(outRight)).toEqual(new Array(8).fill(0));
+  });
+
+  it("fills silence for the remainder and reports the real count on a partial underrun", () => {
+    const ring = new VstRingBuffer(SAMPLE_RATE, SAMPLE_RATE);
+    const { left, right } = makeStereo(3, 5);
+    ring.push(0, left, right);
+
+    const { left: outLeft, right: outRight, readCount } = readN(ring, 6);
+
+    expect(readCount).toBe(3);
+    expect(Array.from(outLeft)).toEqual([5, 6, 7, 0, 0, 0]);
+    expect(Array.from(outRight)).toEqual([-5, -6, -7, 0, 0, 0]);
+  });
+
+  it("drops a block and flags a resync when samplePos gaps from expected", () => {
+    const ring = new VstRingBuffer(SAMPLE_RATE, SAMPLE_RATE);
+    const first = makeStereo(1024, 0);
+    ring.push(0, first.left, first.right);
+
+    // Gap: server skipped ahead to 5000 instead of the expected 1024.
+    const second = makeStereo(4, 900);
+    ring.push(5000, second.left, second.right);
+
+    // expectedPos is unchanged — the gapped block was dropped, not written.
+    expect(ring.expectedPos).toBe(1024);
+    expect(ring.needsResync(0)).toBe(true);
+  });
+
+  it("clears the resync flag when the stream re-aligns after stale in-flight frames", () => {
+    // Live-repro'd loop: every reseek inevitably rejects the frames already
+    // on the wire from the OLD stream position; with the flag latched until
+    // the next reset, each drift check reseeked again, whose own trailing
+    // stale frames latched it again — a permanent reseek loop at the check
+    // cadence (stutter burst, then effective silence). An aligned push is
+    // proof the stream re-synced, so it must clear the flag.
+    const ring = new VstRingBuffer(SAMPLE_RATE, SAMPLE_RATE);
+    ring.reset(48000, 1.0); // reseek to 1.0s
+
+    // Stale in-flight frame from before the reseek → dropped + flagged.
+    const stale = makeStereo(1024, 7);
+    ring.push(20000, stale.left, stale.right);
+    expect(ring.needsResync(1.0)).toBe(true);
+
+    // The post-reseek stream arrives at the expected position — re-synced.
+    const aligned = makeStereo(1024, 1);
+    ring.push(48000, aligned.left, aligned.right);
+    expect(ring.needsResync(1.0)).toBe(false);
+  });
+
+  it("keeps the resync flag standing across a genuine gap until realigned", () => {
+    const ring = new VstRingBuffer(SAMPLE_RATE, SAMPLE_RATE);
+    const first = makeStereo(1024, 0);
+    ring.push(0, first.left, first.right);
+
+    // A real dropped frame: the stream jumps past the expected position and
+    // KEEPS going from the wrong place — never realigns.
+    const afterGap = makeStereo(1024, 5);
+    ring.push(5000, afterGap.left, afterGap.right);
+    expect(ring.needsResync(0)).toBe(true);
+    ring.push(6024, afterGap.left, afterGap.right);
+    expect(ring.needsResync(0)).toBe(true); // still gapped — flag must persist
+  });
+
+  it("does not corrupt buffered data when a gapped push is dropped", () => {
+    const ring = new VstRingBuffer(SAMPLE_RATE, SAMPLE_RATE);
+    const first = makeStereo(4, 1);
+    ring.push(0, first.left, first.right);
+
+    const gapped = makeStereo(4, 999);
+    ring.push(5000, gapped.left, gapped.right);
+
+    const { left: outLeft, readCount } = readN(ring, 4);
+
+    expect(readCount).toBe(4);
+    expect(Array.from(outLeft)).toEqual([1, 2, 3, 4]);
+  });
+
+  it("driftSamples returns 0 before any baseline has been set", () => {
+    // Real streams always have SOME one-time startup latency (AudioContext
+    // resume + a WebSocket round trip + async sidecar dispatch) between the
+    // transport clock starting and the first PCM frame arriving. Without an
+    // explicit baseline, comparing absolute transportTimeSec against
+    // expectedPos would misread that latency as ongoing drift and force a
+    // destructive reseek loop — see setDriftBaseline's doc-comment. Instead,
+    // drift reads as 0 until a baseline is explicitly anchored.
+    const ring = new VstRingBuffer(SAMPLE_RATE, SAMPLE_RATE);
+    const { left, right } = makeStereo(2400, 0);
+    ring.push(0, left, right);
+
+    // A full second of "elapsed" transport time with no baseline set would
+    // read as 48000 samples of drift under naive absolute comparison — here
+    // it must read as zero.
+    expect(ring.driftSamples(1.0)).toBe(0);
+    expect(ring.needsResync(1.0)).toBe(false);
+  });
+
+  it("computes driftSamples relative to the setDriftBaseline anchor", () => {
+    const ring = new VstRingBuffer(SAMPLE_RATE, SAMPLE_RATE);
+    // Anchor at transport time 0.5s (simulating real startup latency before
+    // the first frame arrives) — expectedPos is still 0 at this point.
+    ring.setDriftBaseline(0.5);
+
+    const { left, right } = makeStereo(2400, 0);
+    ring.push(0, left, right);
+    expect(ring.expectedPos).toBe(2400);
+
+    // 0.1s ELAPSED SINCE THE BASELINE (i.e. transport time 0.6s) = 4800
+    // samples elapsed; the stream has only advanced 2400 → drift 2400.
+    expect(ring.driftSamples(0.6)).toBeCloseTo(2400, 5);
+    // Transport time exactly 2400 samples past the baseline: zero drift.
+    expect(ring.driftSamples(0.5 + 2400 / SAMPLE_RATE)).toBeCloseTo(0, 5);
+  });
+
+  it("needsResync compares drift against the threshold (default 50ms), relative to the baseline", () => {
+    const ring = new VstRingBuffer(SAMPLE_RATE, SAMPLE_RATE);
+    ring.setDriftBaseline(0);
+    // expectedPos stays 0 (nothing pushed yet).
+    expect(ring.needsResync(0.03)).toBe(false); // 30ms drift < 50ms default
+    expect(ring.needsResync(0.06)).toBe(true); // 60ms drift > 50ms default
+    // Custom threshold.
+    expect(ring.needsResync(0.06, 0.1)).toBe(false); // 60ms < 100ms threshold
+    expect(ring.needsResync(0.11, 0.1)).toBe(true); // 110ms > 100ms threshold
+  });
+
+  it("does NOT resync when the stream runs ahead of the playhead (healthy lead buffer)", () => {
+    // The sidecar streams a lead cushion, so the stream position is normally
+    // AHEAD of the transport playhead (negative drift). That is healthy — the
+    // ring self-caps any excess — and must not trip a resync. A two-sided
+    // abs() check treated this steady lead as drift and fired a destructive
+    // reseek every interval; the check is one-sided (only a stream that has
+    // fallen BEHIND resyncs).
+    const ring = new VstRingBuffer(SAMPLE_RATE, SAMPLE_RATE);
+    ring.setDriftBaseline(0);
+    // 0.5s of audio already streamed, but the playhead has barely moved (5ms):
+    // stream is ~0.5s AHEAD → large negative drift.
+    const { left, right } = makeStereo(SAMPLE_RATE / 2, 0);
+    ring.push(0, left, right);
+    expect(ring.driftSamples(0.005)).toBeLessThan(0);
+    expect(ring.needsResync(0.005)).toBe(false);
+  });
+
+  it("reset clears buffered audio, realigns expectedPos, and clears a pending resync flag", () => {
+    const ring = new VstRingBuffer(SAMPLE_RATE, SAMPLE_RATE);
+    const first = makeStereo(4, 1);
+    ring.push(0, first.left, first.right);
+    // Force a resync flag.
+    ring.push(5000, first.left, first.right);
+    expect(ring.needsResync(0)).toBe(true);
+
+    ring.reset(9600, 9600 / SAMPLE_RATE);
+
+    expect(ring.expectedPos).toBe(9600);
+    expect(ring.needsResync(9600 / SAMPLE_RATE)).toBe(false);
+
+    // Buffered audio was cleared — a read returns silence, not the old data.
+    const { left: outLeft, readCount } = readN(ring, 4);
+    expect(readCount).toBe(0);
+    expect(Array.from(outLeft)).toEqual([0, 0, 0, 0]);
+  });
+
+  it("reset re-anchors the drift baseline to the given transportTimeSec", () => {
+    const ring = new VstRingBuffer(SAMPLE_RATE, SAMPLE_RATE);
+    ring.reset(9600, 0.2);
+
+    // No time has elapsed since the reset's baseline, and expectedPos
+    // already matches the seek target — zero drift.
+    expect(ring.driftSamples(0.2)).toBeCloseTo(0, 5);
+
+    const { left, right } = makeStereo(4800, 9600);
+    ring.push(9600, left, right);
+    // 0.1s elapsed since the reset baseline (transport time 0.3s) = 4800
+    // samples elapsed, and the stream advanced by exactly 4800 — zero drift.
+    expect(ring.driftSamples(0.3)).toBeCloseTo(0, 5);
+  });
+
+  it("reset without a transportTimeSec leaves the drift baseline untouched", () => {
+    const ring = new VstRingBuffer(SAMPLE_RATE, SAMPLE_RATE);
+    // No baseline has ever been set — reset(pos) alone must not implicitly
+    // anchor one, or a caller that only wants to realign the buffer (not
+    // measure drift yet) would silently start a drift comparison anyway.
+    ring.reset(9600);
+    expect(ring.driftSamples(1.0)).toBe(0);
+  });
+
+  it("wraps around the circular buffer correctly across many small pushes", () => {
+    const capacity = 16;
+    const ring = new VstRingBuffer(capacity, SAMPLE_RATE);
+    let pos = 0;
+    // Push/read in blocks of 5 several times over — exercises wraparound
+    // since 5 does not evenly divide the 16-sample capacity.
+    for (let round = 0; round < 6; round++) {
+      const { left, right } = makeStereo(5, pos);
+      ring.push(pos, left, right);
+      pos += 5;
+
+      const { left: outLeft, readCount } = readN(ring, 5);
+      expect(readCount).toBe(5);
+      expect(Array.from(outLeft)).toEqual([pos - 5, pos - 4, pos - 3, pos - 2, pos - 1]);
+    }
+    expect(ring.expectedPos).toBe(pos);
+  });
+});
diff --git a/packages/studio/src/player/lib/vstRingBuffer.ts b/packages/studio/src/player/lib/vstRingBuffer.ts
new file mode 100644
index 0000000000..1780739abe
--- /dev/null
+++ b/packages/studio/src/player/lib/vstRingBuffer.ts
@@ -0,0 +1,193 @@
+/**
+ * Fixed-capacity circular buffer for streamed stereo PCM samples arriving
+ * from the VST sidecar's WebSocket (see `useVstHost`'s module doc for the
+ * wire format). Pure logic — no WebAudio/browser API dependency — so it can
+ * run on the main thread (for drift bookkeeping in `useVstPreview`) and,
+ * duplicated inline, inside the `vst-stream` AudioWorkletProcessor (see the
+ * header comment in `vstStreamWorklet.js`, which must be kept in sync with
+ * this file by hand — worklet files can't import across the module graph).
+ *
+ * `push()` writes are expected to arrive in strictly increasing, contiguous
+ * `samplePos` order (each block picking up exactly where the previous one
+ * left off). A mismatch — a dropped network frame, stream reordering, or a
+ * stale in-flight frame trailing a `reset()` — is never silently absorbed
+ * into the buffer at the wrong offset: the block is dropped and a resync
+ * flag is raised instead, cleared by `reset()` or by the stream re-aligning
+ * on its own (an aligned push — see `push`'s doc-comment).
+ */
+export class VstRingBuffer {
+  private readonly capacity: number;
+  private readonly sampleRateValue: number;
+  private left: Float32Array;
+  private right: Float32Array;
+  /** Circular write cursor — index of the next slot `push` will write to. */
+  private writeIndex = 0;
+  /** Circular read cursor — index of the next slot `read` will consume. */
+  private readIndex = 0;
+  /** Count of valid, unread samples currently buffered. */
+  private available = 0;
+  /** The sample position `push` expects to start its next write at. */
+  private nextExpectedPos: number;
+  /** Set by `push` on a `samplePos` gap; cleared by `reset` or an aligned push. */
+  private resyncNeeded = false;
+  /** Wall-clock/sample-position pair captured at the last `setDriftBaseline`
+   *  or `reset` call — see `driftSamples`' doc-comment for why this exists. */
+  private baselineTimeSec: number | null = null;
+  private baselineSamplePos = 0;
+
+  constructor(capacitySamples: number, sampleRate: number) {
+    this.capacity = Math.max(1, Math.floor(capacitySamples));
+    this.sampleRateValue = sampleRate;
+    this.left = new Float32Array(this.capacity);
+    this.right = new Float32Array(this.capacity);
+    this.nextExpectedPos = 0;
+  }
+
+  /** The sample position `push` expects its next call to start at. */
+  get expectedPos(): number {
+    return this.nextExpectedPos;
+  }
+
+  /**
+   * Writes `left`/`right` (equal-length, same sample count) at `samplePos`.
+   * If `samplePos` doesn't match `expectedPos` — a gap from a dropped
+   * network frame, or a stale in-flight frame from before a `reset()` —
+   * the block is dropped (never written at the wrong offset) and a resync
+   * is flagged.
+   *
+   * An ALIGNED push clears the flag again: reaching the expected position
+   * proves the stream re-synced on its own. Without this, the flag latched
+   * permanently on the stale frames that inevitably trail every reseek
+   * (frames already on the wire when `reset()` ran), so the next drift
+   * check reseeked again, whose own trailing stale frames latched it
+   * again — a self-sustaining reseek loop at the drift-check cadence that
+   * zero-filled the ring every cycle (heard as a stutter burst, then
+   * effectively silence). Only a mismatch with NO aligned frame following
+   * it — a genuine, persistent gap — now leaves the flag standing for the
+   * drift check to act on.
+   */
+  push(samplePos: number, left: Float32Array, right: Float32Array): void {
+    if (samplePos !== this.nextExpectedPos) {
+      this.resyncNeeded = true;
+      return;
+    }
+    this.resyncNeeded = false;
+    const n = Math.min(left.length, right.length);
+    this.writeSamples(left, right, n);
+    this.nextExpectedPos += n;
+  }
+
+  private writeSamples(left: Float32Array, right: Float32Array, n: number): void {
+    let writeN = n;
+    let srcOffset = 0;
+    // A single block larger than the whole buffer: keep only its tail.
+    if (writeN > this.capacity) {
+      srcOffset = writeN - this.capacity;
+      writeN = this.capacity;
+    }
+    // Make room by dropping the oldest unread samples if this write would
+    // overflow the buffer (a persistent reader stall).
+    const overflow = this.available + writeN - this.capacity;
+    if (overflow > 0) {
+      this.readIndex = (this.readIndex + overflow) % this.capacity;
+      this.available -= overflow;
+    }
+    for (let i = 0; i < writeN; i++) {
+      const idx = (this.writeIndex + i) % this.capacity;
+      this.left[idx] = left[srcOffset + i];
+      this.right[idx] = right[srcOffset + i];
+    }
+    this.writeIndex = (this.writeIndex + writeN) % this.capacity;
+    this.available += writeN;
+  }
+
+  /**
+   * Fills `out[0]`/`out[1]` with up to `n` samples. On underrun (fewer than
+   * `n` samples buffered) the remainder is filled with silence (zeros).
+   * Returns the count of real samples actually available and copied.
+   */
+  read(out: [Float32Array, Float32Array], n: number): number {
+    const avail = Math.min(this.available, n);
+    for (let i = 0; i < n; i++) {
+      if (i < avail) {
+        const idx = (this.readIndex + i) % this.capacity;
+        out[0][i] = this.left[idx];
+        out[1][i] = this.right[idx];
+      } else {
+        out[0][i] = 0;
+        out[1][i] = 0;
+      }
+    }
+    this.readIndex = (this.readIndex + avail) % this.capacity;
+    this.available -= avail;
+    return avail;
+  }
+
+  /**
+   * Anchors drift measurement to "how far has the stream progressed SINCE
+   * THIS MOMENT" rather than absolute position. Without this, `driftSamples`
+   * would compare the sidecar's sample-accurate stream position against
+   * wall-clock time measured from whenever the transport's own clock started
+   * — but there's always some real, one-time startup latency between "play
+   * clicked" and "the sidecar's first PCM frame arrives" (AudioContext
+   * autoplay-policy resume, a WebSocket round trip, async dispatch on the
+   * sidecar). That latency is normal and harmless — every streaming pipeline
+   * has SOME buffering delay — but a naive absolute comparison misreads it as
+   * ongoing drift, forces a resync, and since the resync's own reset()
+   * re-arms the same absolute comparison, the "drift" reappears identically
+   * at the next check, forever: a self-inflicted loop where the correction
+   * is the actual cause of the corruption it appears to be fixing. Anchoring
+   * to a baseline captured once real streaming begins cancels the fixed
+   * startup offset out of the comparison, leaving only drift that genuinely
+   * accumulates during playback (real clock-rate mismatches) — the only kind
+   * this mechanism is meant to catch.
+   */
+  setDriftBaseline(transportTimeSec: number): void {
+    this.baselineTimeSec = transportTimeSec;
+    this.baselineSamplePos = this.nextExpectedPos;
+  }
+
+  /**
+   * How far (in samples) this buffer's write position has drifted from
+   * where the transport thinks playback should be, measured relative to the
+   * last `setDriftBaseline`/`reset` anchor (see `setDriftBaseline`'s
+   * doc-comment). Returns 0 before any baseline has been set.
+   */
+  driftSamples(transportTimeSec: number): number {
+    if (this.baselineTimeSec === null) return 0;
+    const elapsedWallClock = transportTimeSec - this.baselineTimeSec;
+    const elapsedStreamSamples = this.nextExpectedPos - this.baselineSamplePos;
+    return elapsedWallClock * this.sampleRateValue - elapsedStreamSamples;
+  }
+
+  /**
+   * True when a `push` gap was flagged (unresolved), or the stream has fallen
+   * BEHIND the playhead by more than `thresholdSec` (default 50ms).
+   *
+   * The check is one-sided on purpose. `driftSamples` is positive when the
+   * stream lags the playhead (the ring is draining toward starvation — a real
+   * fault a resync fixes) and negative when the stream runs AHEAD of it. Ahead
+   * is the normal, healthy state: the sidecar deliberately streams a lead
+   * cushion (see server.py `_PUMP_LEAD_SEC`) so the ring stays fed through
+   * jitter, and the ring self-caps any excess by dropping its oldest samples.
+   * A two-sided `abs()` check treated that steady lead as drift and fired a
+   * destructive reseek every interval — the correction causing the corruption.
+   */
+  needsResync(transportTimeSec: number, thresholdSec = 0.05): boolean {
+    if (this.resyncNeeded) return true;
+    return this.driftSamples(transportTimeSec) > thresholdSec * this.sampleRateValue;
+  }
+
+  /** Clears all buffered audio and realigns `expectedPos` to `samplePos`
+   *  (post-seek), re-anchoring the drift baseline to that same moment. */
+  reset(samplePos: number, transportTimeSec?: number): void {
+    this.left.fill(0);
+    this.right.fill(0);
+    this.writeIndex = 0;
+    this.readIndex = 0;
+    this.available = 0;
+    this.nextExpectedPos = samplePos;
+    this.resyncNeeded = false;
+    if (transportTimeSec !== undefined) this.setDriftBaseline(transportTimeSec);
+  }
+}
diff --git a/packages/studio/src/player/lib/vstStreamWorklet.js b/packages/studio/src/player/lib/vstStreamWorklet.js
new file mode 100644
index 0000000000..fa6e9c5e92
--- /dev/null
+++ b/packages/studio/src/player/lib/vstStreamWorklet.js
@@ -0,0 +1,169 @@
+// fallow-ignore-file code-duplication
+/**
+ * `vst-stream` AudioWorkletProcessor — plays back the PCM stream forwarded
+ * by `useVstPreview` from the VST sidecar's WebSocket.
+ *
+ * Runs in the browser's separate audio-rendering thread (AudioWorkletGlobalScope):
+ * no `window`, no DOM, and no module imports across the worklet boundary — so
+ * this file cannot `import` `VstRingBuffer` from `vstRingBuffer.ts`. The class
+ * below is a plain-JS copy of that file's logic.
+ *
+ * Kept in sync with vstRingBuffer.ts — edit both.
+ *
+ * Messages handled via `port.onmessage`:
+ *   { type: "pcm", samplePos, left: Float32Array, right: Float32Array }
+ *   { type: "reset", samplePos }
+ */
+
+class VstRingBuffer {
+  constructor(capacitySamples, sampleRate) {
+    this.capacity = Math.max(1, Math.floor(capacitySamples));
+    this.sampleRateValue = sampleRate;
+    this.left = new Float32Array(this.capacity);
+    this.right = new Float32Array(this.capacity);
+    this.writeIndex = 0;
+    this.readIndex = 0;
+    this.available = 0;
+    this.nextExpectedPos = 0;
+    this.resyncNeeded = false;
+    this.baselineTimeSec = null;
+    this.baselineSamplePos = 0;
+  }
+
+  get expectedPos() {
+    return this.nextExpectedPos;
+  }
+
+  push(samplePos, left, right) {
+    if (samplePos !== this.nextExpectedPos) {
+      this.resyncNeeded = true;
+      return;
+    }
+    // An aligned push proves the stream re-synced — clear the flag so the
+    // stale in-flight frames trailing every reset don't latch a permanent
+    // reseek loop (see vstRingBuffer.ts's push doc-comment, kept in sync).
+    this.resyncNeeded = false;
+    const n = Math.min(left.length, right.length);
+    this._writeSamples(left, right, n);
+    this.nextExpectedPos += n;
+  }
+
+  _writeSamples(left, right, n) {
+    let writeN = n;
+    let srcOffset = 0;
+    if (writeN > this.capacity) {
+      srcOffset = writeN - this.capacity;
+      writeN = this.capacity;
+    }
+    const overflow = this.available + writeN - this.capacity;
+    if (overflow > 0) {
+      this.readIndex = (this.readIndex + overflow) % this.capacity;
+      this.available -= overflow;
+    }
+    for (let i = 0; i < writeN; i++) {
+      const idx = (this.writeIndex + i) % this.capacity;
+      this.left[idx] = left[srcOffset + i];
+      this.right[idx] = right[srcOffset + i];
+    }
+    this.writeIndex = (this.writeIndex + writeN) % this.capacity;
+    this.available += writeN;
+  }
+
+  read(out, n) {
+    const avail = Math.min(this.available, n);
+    for (let i = 0; i < n; i++) {
+      if (i < avail) {
+        const idx = (this.readIndex + i) % this.capacity;
+        out[0][i] = this.left[idx];
+        out[1][i] = this.right[idx];
+      } else {
+        out[0][i] = 0;
+        out[1][i] = 0;
+      }
+    }
+    this.readIndex = (this.readIndex + avail) % this.capacity;
+    this.available -= avail;
+    return avail;
+  }
+
+  setDriftBaseline(transportTimeSec) {
+    this.baselineTimeSec = transportTimeSec;
+    this.baselineSamplePos = this.nextExpectedPos;
+  }
+
+  driftSamples(transportTimeSec) {
+    if (this.baselineTimeSec === null) return 0;
+    const elapsedWallClock = transportTimeSec - this.baselineTimeSec;
+    const elapsedStreamSamples = this.nextExpectedPos - this.baselineSamplePos;
+    return elapsedWallClock * this.sampleRateValue - elapsedStreamSamples;
+  }
+
+  needsResync(transportTimeSec, thresholdSec = 0.05) {
+    if (this.resyncNeeded) return true;
+    // One-sided: only a stream that has fallen BEHIND the playhead is a fault.
+    // Running ahead (the sidecar's lead cushion) is healthy — see the fuller
+    // explanation in vstRingBuffer.ts, kept in sync with this file.
+    return this.driftSamples(transportTimeSec) > thresholdSec * this.sampleRateValue;
+  }
+
+  reset(samplePos, transportTimeSec) {
+    this.left.fill(0);
+    this.right.fill(0);
+    this.writeIndex = 0;
+    this.readIndex = 0;
+    this.available = 0;
+    this.nextExpectedPos = samplePos;
+    this.resyncNeeded = false;
+    if (transportTimeSec !== undefined) this.setDriftBaseline(transportTimeSec);
+  }
+}
+
+class VstStreamProcessor extends AudioWorkletProcessor {
+  constructor(options) {
+    super();
+    const processorOptions = (options && options.processorOptions) || {};
+    // Default: 2s of headroom at the worklet's actual sampleRate (global,
+    // set by the browser to match the AudioContext this node belongs to).
+    const capacitySamples = processorOptions.capacitySamples || sampleRate * 2;
+    this._ring = new VstRingBuffer(capacitySamples, sampleRate);
+    // Underrun telemetry: `read()` zero-fills whenever the ring is starved, so
+    // count those silent samples. Posted (cumulative + audio-clock time) to the
+    // main thread ~2x/sec so playback health is a NUMBER, not a listening call:
+    // during steady playback underruns/sec MUST be 0 — any nonzero rate is the
+    // sidecar failing to keep the ring fed (see server.py `_pump`).
+    this._underrunSamples = 0;
+    this._renderedSinceReport = 0;
+    this.port.onmessage = (event) => {
+      const data = event.data;
+      if (!data) return;
+      if (data.type === "pcm") {
+        this._ring.push(data.samplePos, data.left, data.right);
+      } else if (data.type === "reset") {
+        this._ring.reset(data.samplePos);
+      }
+    };
+  }
+
+  process(_inputs, outputs) {
+    const output = outputs[0];
+    const left = output[0];
+    const right = output[1] || output[0];
+    if (left) {
+      const filled = this._ring.read([left, right], left.length);
+      this._underrunSamples += left.length - filled;
+      this._renderedSinceReport += left.length;
+      if (this._renderedSinceReport >= sampleRate * 0.5) {
+        this.port.postMessage({
+          type: "underrun",
+          totalSamples: this._underrunSamples,
+          atTime: currentTime,
+        });
+        this._renderedSinceReport = 0;
+      }
+    }
+    // Keep the node alive for the lifetime of the AudioContext.
+    return true;
+  }
+}
+
+registerProcessor("vst-stream", VstStreamProcessor);
diff --git a/packages/studio/src/player/store/playerStore.ts b/packages/studio/src/player/store/playerStore.ts
index e8c101c8fd..179c4d77c2 100644
--- a/packages/studio/src/player/store/playerStore.ts
+++ b/packages/studio/src/player/store/playerStore.ts
@@ -104,6 +104,11 @@ interface PlayerState extends KeyframeSlice {
   /** True while a beat dot is being dragged — hides the playhead guideline. */
   beatDragging: boolean;
   elements: TimelineElement[];
+  /** Bumped by the FX panel whenever a track's VST chain file is added /
+   *  removed / swapped. `useVstPreview` watches this to reconcile+reload the
+   *  affected track — the panel and the preview hook are otherwise decoupled
+   *  (a chain-file rewrite is invisible to the timeline `elements` signal). */
+  vstChainRevision: number;
   selectedElementId: string | null;
   playbackRate: number;
   audioMuted: boolean;
@@ -184,6 +189,7 @@ interface PlayerState extends KeyframeSlice {
   setTimelineReady: (ready: boolean) => void;
   setBeatDragging: (dragging: boolean) => void;
   setElements: (elements: TimelineElement[]) => void;
+  bumpVstChainRevision: () => void;
   setSelectedElementId: (id: string | null, options?: SelectElementOptions) => void;
   /** Move the selection anchor within an active multi-selection without collapsing it. */
   setSelectionAnchor: (id: string | null) => void;
@@ -290,6 +296,7 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   timelineReady: false,
   beatDragging: false,
   elements: [],
+  vstChainRevision: 0,
   selectedElementId: null,
   playbackRate: readStudioUiPreferences().playbackRate ?? 1,
   audioMuted: readStudioUiPreferences().audioMuted ?? false,
@@ -472,6 +479,7 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   setTimelineReady: (ready) => set({ timelineReady: ready }),
   setBeatDragging: (dragging) => set({ beatDragging: dragging }),
   setElements: (elements) => set({ elements }),
+  bumpVstChainRevision: () => set((s) => ({ vstChainRevision: s.vstChainRevision + 1 })),
   // A genuine single selection: always collapse the set to just this element. User
   // intent (timeline click, preview click via applyDomSelection) flows here; DOM sync
   // echoes that must preserve a group go through setSelectionAnchor instead.
diff --git a/packages/studio/src/utils/vstChainFile.test.ts b/packages/studio/src/utils/vstChainFile.test.ts
new file mode 100644
index 0000000000..61850683bb
--- /dev/null
+++ b/packages/studio/src/utils/vstChainFile.test.ts
@@ -0,0 +1,132 @@
+import { describe, expect, it } from "vitest";
+import {
+  appendCarveBands,
+  parseChainFile,
+  projectRelativeAssetPath,
+  serializeChainFile,
+  type ChainFileJson,
+} from "./vstChainFile";
+
+function sampleChain(): ChainFileJson {
+  return {
+    version: 1,
+    plugins: [
+      {
+        format: "vst3",
+        path: "/Library/Audio/Plug-Ins/VST3/Reverb.vst3",
+        pluginName: "Reverb",
+        name: "Reverb",
+        stateB64: "AAECAw==",
+      },
+      {
+        format: "builtin",
+        path: "builtin://eq",
+        pluginName: null,
+        name: "EQ",
+        stateB64: null,
+      },
+    ],
+  };
+}
+
+describe("vstChainFile", () => {
+  it("round-trips a chain through serializeChainFile + parseChainFile", () => {
+    const chain = sampleChain();
+    const parsed = parseChainFile(serializeChainFile(chain));
+    expect(parsed).toEqual(chain);
+  });
+
+  it("returns null for malformed JSON", () => {
+    expect(parseChainFile("not json")).toBeNull();
+  });
+
+  it("returns null for a missing/wrong version", () => {
+    expect(parseChainFile(JSON.stringify({ version: 2, plugins: [] }))).toBeNull();
+    expect(parseChainFile(JSON.stringify({ plugins: [] }))).toBeNull();
+  });
+
+  it("returns null when plugins is missing or contains malformed entries", () => {
+    expect(parseChainFile(JSON.stringify({ version: 1 }))).toBeNull();
+    expect(
+      parseChainFile(
+        JSON.stringify({
+          version: 1,
+          plugins: [
+            { format: "not-a-format", path: "x", pluginName: null, name: "x", stateB64: null },
+          ],
+        }),
+      ),
+    ).toBeNull();
+  });
+
+  it("parses an empty plugin chain", () => {
+    expect(parseChainFile(JSON.stringify({ version: 1, plugins: [] }))).toEqual({
+      version: 1,
+      plugins: [],
+    });
+  });
+});
+
+describe("appendCarveBands", () => {
+  it("appends one PeakFilter per band, preserving existing plugins", () => {
+    const existing: ChainFileJson = {
+      version: 1,
+      plugins: [
+        { format: "builtin", path: "Reverb", pluginName: null, name: "Reverb", stateB64: null },
+      ],
+    };
+    const next = appendCarveBands(existing, [
+      { freq: 1000, gainDb: -4, q: 1.5 },
+      { freq: 2500, gainDb: -2, q: 1.5 },
+    ]);
+    expect(next.plugins).toHaveLength(3);
+    expect(next.plugins[0].path).toBe("Reverb"); // untouched
+    expect(next.plugins[1].path).toBe("PeakFilter");
+    const params = JSON.parse(atob(next.plugins[1].stateB64 ?? ""));
+    expect(params).toEqual({ cutoff_frequency_hz: 1000, gain_db: -4, q: 1.5 });
+    expect(existing.plugins).toHaveLength(1); // input not mutated
+  });
+
+  it("starts a fresh chain from null", () => {
+    const next = appendCarveBands(null, [{ freq: 400, gainDb: -3, q: 1.5 }]);
+    expect(next.version).toBe(1);
+    expect(next.plugins).toHaveLength(1);
+    expect(next.plugins[0].format).toBe("builtin");
+    expect(next.plugins[0].pluginName).toBeNull();
+  });
+
+  it("replaces a prior carve run's bands instead of stacking on top of them", () => {
+    const afterFirstCarve = appendCarveBands(
+      {
+        version: 1,
+        plugins: [
+          { format: "builtin", path: "Reverb", pluginName: null, name: "Reverb", stateB64: null },
+        ],
+      },
+      [{ freq: 160, gainDb: -1.5, q: 1.5 }],
+    );
+    const afterSecondCarve = appendCarveBands(afterFirstCarve, [
+      { freq: 160, gainDb: -4.6, q: 1.5 },
+    ]);
+    // Only ONE carve band (the new depth), plus the untouched user effect —
+    // not two stacked cuts at the same frequency.
+    expect(afterSecondCarve.plugins).toHaveLength(2);
+    expect(afterSecondCarve.plugins[0].path).toBe("Reverb");
+    const carveEntries = afterSecondCarve.plugins.filter((p) => p.name.startsWith("Carve "));
+    expect(carveEntries).toHaveLength(1);
+    const params = JSON.parse(atob(carveEntries[0].stateB64 ?? ""));
+    expect(params.gain_db).toBe(-4.6);
+  });
+});
+
+describe("projectRelativeAssetPath", () => {
+  it("extracts the part after /preview/", () => {
+    expect(projectRelativeAssetPath("http://x/preview/media/vo.wav?t=1")).toBe("media/vo.wav");
+  });
+  it("strips a leading ./ from an already-relative src", () => {
+    expect(projectRelativeAssetPath("./media/vo.wav")).toBe("media/vo.wav");
+  });
+  it("returns null for empty input", () => {
+    expect(projectRelativeAssetPath("")).toBeNull();
+  });
+});
diff --git a/packages/studio/src/utils/vstChainFile.ts b/packages/studio/src/utils/vstChainFile.ts
new file mode 100644
index 0000000000..6a107c1548
--- /dev/null
+++ b/packages/studio/src/utils/vstChainFile.ts
@@ -0,0 +1,101 @@
+/**
+ * On-disk `.vstchain.json` contract. Shared with the Python VST sidecar and
+ * the CLI render pipeline — do not change field names/types here without
+ * updating those consumers too.
+ */
+export interface ChainPluginJson {
+  format: "vst3" | "au" | "builtin";
+  path: string;
+  pluginName: string | null;
+  name: string;
+  stateB64: string | null;
+  /** Bypass toggle — absent means enabled (backward compatible with v1 files
+   *  written before the field existed, and ignored by older sidecars). A
+   *  disabled plugin stays in the chain (its slot, params, and state are
+   *  preserved) but is skipped by the processing board in both live preview
+   *  and render bounce. */
+  enabled?: boolean;
+}
+
+/** Bypass check honoring the absent-means-enabled default. */
+export function isPluginEnabled(plugin: ChainPluginJson): boolean {
+  return plugin.enabled !== false;
+}
+
+export interface ChainFileJson {
+  version: 1;
+  plugins: ChainPluginJson[];
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+// fallow-ignore-next-line complexity
+function isChainPluginJson(value: unknown): value is ChainPluginJson {
+  if (!isRecord(value)) return false;
+  const { format, path, pluginName, name, stateB64, enabled } = value;
+  if (format !== "vst3" && format !== "au" && format !== "builtin") return false;
+  if (typeof path !== "string" || typeof name !== "string") return false;
+  if (pluginName !== null && typeof pluginName !== "string") return false;
+  if (stateB64 !== null && typeof stateB64 !== "string") return false;
+  if (enabled !== undefined && typeof enabled !== "boolean") return false;
+  return true;
+}
+
+/** Parses a `.vstchain.json` file's text. Returns null on parse error, wrong version, or a malformed plugin entry. */
+export function parseChainFile(text: string): ChainFileJson | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed)) return null;
+  if (parsed.version !== 1) return null;
+  if (!Array.isArray(parsed.plugins) || !parsed.plugins.every(isChainPluginJson)) return null;
+  return { version: 1, plugins: parsed.plugins };
+}
+
+export function serializeChainFile(chain: ChainFileJson): string {
+  return JSON.stringify(chain, null, 2);
+}
+
+export interface CarveBand {
+  freq: number;
+  gainDb: number;
+  q: number;
+}
+
+const CARVE_NAME_PREFIX = "Carve ";
+
+/** Appends one PeakFilter built-in per carve band to a chain, replacing any
+ *  bands a PRIOR carve run added (identified by the `"Carve "` name prefix)
+ *  so re-running "Make room for voiceover" at a different amount swaps the
+ *  cut depth instead of stacking a second cut on top of the first. Other
+ *  plugins (user-picked effects) are preserved untouched. A null/absent
+ *  chain starts fresh. Pure — returns a new object. */
+export function appendCarveBands(chain: ChainFileJson | null, bands: CarveBand[]): ChainFileJson {
+  const base = (chain?.plugins ?? []).filter((p) => !p.name.startsWith(CARVE_NAME_PREFIX));
+  const carved: ChainPluginJson[] = bands.map((b) => ({
+    format: "builtin",
+    path: "PeakFilter",
+    pluginName: null,
+    name: `${CARVE_NAME_PREFIX}${Math.round(b.freq)}Hz`,
+    stateB64: btoa(JSON.stringify({ cutoff_frequency_hz: b.freq, gain_db: b.gainDb, q: b.q })),
+  }));
+  return { version: 1, plugins: [...base, ...carved] };
+}
+
+/** Project-relative asset path from a track `src`/preview URL: the part after
+ *  `/preview/` (decoded, query stripped), or the src minus a leading `./` when
+ *  it's already relative. Null only for empty input. */
+export function projectRelativeAssetPath(url: string): string | null {
+  if (!url) return null;
+  const marker = "/preview/";
+  const idx = url.indexOf(marker);
+  if (idx !== -1) {
+    return decodeURIComponent(url.slice(idx + marker.length).split("?")[0] ?? "");
+  }
+  return url.replace(/^\.\//, "").split("?")[0] ?? null;
+}