Drain deferred FX parks before the view model is serialized; re-validate track handles per intent; pin the restore-plan round trip

src/shell/view/view_fx_park.h

@@ -41,6 +41,11 @@ public:
     // The caller needs them: that restore never ran, so the live chain still
     // reads the PARKED offline states and is no longer a source for a fresh
     // pre-park snapshot (see preParkFxFromCancelledRestore).
+    //
+    // The empty return is a LOAD-BEARING sentinel that deliberately conflates
+    // "nothing was cancelled" with "cancelled a restore carrying no ops": a
+    // zero-op restore held no FX state to hand back, so falling through to a
+    // live chain read is the same answer, not a worse one.
     std::vector<FxOfflineOp> park(const std::string& guid) {
         FxParkIntent* held = find(guid);
         if (!held) {
@@ -73,10 +78,12 @@ public:
     void clear() { pending_.clear(); }
 
     // Detaches everything pending, leaving the queue able to accept intents
-    // enqueued WHILE the caller applies what it took. Applying loads/unloads
-    // plugins, which pumps the message loop, so a re-entrant switch can enqueue
-    // mid-apply: iterating the live queue would dangle on the push_back, and
-    // clearing it afterwards would discard whatever arrived during the apply.
+    // enqueued WHILE the caller applies what it took. [verify — DAW] applying
+    // loads/unloads plugins, which is ASSUMED to pump the message loop, so a
+    // re-entrant switch can enqueue mid-apply: iterating the live queue would
+    // dangle on the push_back, and clearing it afterwards would discard
+    // whatever arrived during the apply. The detach is correct either way; only
+    // the need for it is unconfirmed.
     std::vector<FxParkIntent> take() {
         std::vector<FxParkIntent> taken;
         taken.swap(pending_);
@@ -109,6 +116,17 @@ struct PreParkFx {
 // cancelled) means the caller reads the live chain instead. The restore's own
 // keying travels with it so a slot-keyed snapshot lifted from a legacy
 // view_state does not silently become an identity-keyed one with no identities.
+//
+// FAITHFUL TO THE SNAPSHOT, NOT THE CHAIN. The ops describe the chain as it was
+// at the ORIGINAL park; applyPark enumerates it again at drain time. So an FX
+// added while the track was parked (a floating FX-chain window, ReaScript) is
+// absent from this reconstruction yet IS offlined by the cancelling park's
+// drain — and so never comes back online. Rare, and recoverable by hand in the
+// FX chain, but specific to the deferral.
+//
+// `offline` is already boolean by the time it arrives: makeRestorePlan narrowed
+// FxOfflineState's defensive int to FxOfflineOp's bool, so this widening back to
+// int restores the type, not lost information.
 inline PreParkFx preParkFxFromCancelledRestore(const std::vector<FxOfflineOp>& cancelled) {
     PreParkFx out;
     if (cancelled.empty()) return out;
@@ -133,12 +151,29 @@ void deferFxRestore(ReaProject* proj, const std::string& guid, std::vector<FxOff
 // dropped where the restore is planned (applyMode). Discards the queue unapplied
 // if the project it was enqueued against is no longer current (close / switch);
 // an intent whose track is gone is pruned. Idle cost is one empty-queue test.
+// Re-entrant calls early-out: one drain at a time, the outer one owns the queue.
+//
+// Called on the idle tick AND synchronously before the view model is serialized
+// (persistViewState, render_in_place). The second call is not an optimization:
+// between a restore's synchronous flag writes and its drain the FX are still
+// offline while the model has already dropped the snapshot that would replan
+// them, so a save inside that window — deterministic under a custom action chain
+// like "toggle mode; save project" — records offline FX beside a snapshot-free
+// model, and nothing on reopen brings them back online. The cost is that an
+// action-driven switch pays the FX hitch before it returns; its repaint and undo
+// block have both closed by then, which is what the deferral was for.
 void drainDeferredFxParks();
 
 // Drops every pending intent without applying it. Called when the model the
 // intents were planned against has been replaced (project load/switch, undo/redo
 // state restore) — applying them then would write the pre-reload plan over the
 // project that replaced it.
+//
+// Not pure loss: the caller reapplies the active mode over the reloaded model
+// immediately after, which re-plans a park for every inactive leaf, so parked FX
+// converge on the following drain. The case that does NOT self-heal is a track
+// whose reloaded model carries no snapshot — nothing plans a restore for it, so
+// FX left offline stay offline.
 void discardDeferredFxParks();
 
 } // namespace reasampler