Two-phase offline WAM chain build: clone plugins before the setContext swap

[naomiaro]

Follow-up from #536's final review (Important #2).

renderToneOffline swaps Tone's global context (setContext(offlineContext)) for the whole offline graph build. Since #536 the build awaits real async work per WAM entry (ensureWamHost worklet load + cloneInstanceInto), so the window where app code creating Tone nodes (track add, effect-chain mutation, recording arm) lands on the offline context grew from ~1 microtask (upstream Tone.Offline) to 100ms–1s. Exports themselves are serialized (module-level queue in renderToneOffline), and the docs carry a don't-mutate-mid-export caveat, but the structural fix is:

Two-phase buildOfflineChain: clone all WAM entries against the raw OfflineAudioContext before the setContext swap — ensureWamHost/cloneInstanceInto take the context explicitly and don't need the global swap; only the synchronous Tone-node creation does. That shrinks the swapped window back to roughly upstream's exposure.

Refs: packages/browser/src/utils/renderToneOffline.ts, packages/browser/src/effects/offlineChain.ts, packages/browser/src/hooks/useExportWav.ts (renderOffline).

[naomiaro]

Release triage (2026-07-02): not a blocker for the @waveform-playlist/browser minor that ships WAM export.

Reasoning:

• The window only exists for exports with WAM entries — native-only chains resolve the offline build in a microtask or two, the same exposure Tone.Offline has always had. The worst outcome (a spent OfflineAudioContext permanently installed as the global context) is already fixed by the serialization queue in renderToneOffline.
• What remains: nodes created by app code during the 100ms–1s WAM-clone phase of an in-flight export land on the offline context and are dead afterwards. Scoped to the mid-export action, recoverable (remove/re-add), global context restores correctly, and the caveat is documented in wam-plugins.md.
• Contract stability is not at risk from deferring: the two-phase build can land as a non-breaking optional hook — the offline factories attach an optional prepare(rawContext) step that pre-clones WAM instances before the setContext swap, and renderOffline calls it when present. Plain async OfflineEffectsFunction consumers keep working unchanged. No need to reshape the just-shipped types pre-publish.

Revisit sooner if: (a) WAM export gets promoted to consumers building custom export UIs with live-editable racks, or (b) a design pass finds the optional-hook path doesn't work and a breaking contract change is the only route.