reasampler/src/shell/view/CLAUDE.md

src/shell/view — Design View mode application shell

Scope

The REAPER-facing half of Design View: applying a mode's visibility/processing state to live tracks (park/restore), snapshotting flag values before parking, and restoring from snapshot on toggle-back. The mode registry, membership derivation, and the pure park/restore planner are owned by core/view (view_mode_model) — this directory is the shell that reads/writes REAPER track flags, it does not decide membership or mode rules.

Invariants

• Never touches master or B_MUTE; never LOSES solo. The tool owns visibility, B_MAINSEND, I_FXEN, per-FX offline, and — on a real mode switch only — I_SOLO, on every managed leaf, tagged or untagged. B_MUTE is untouched absolutely. The master track is untouched absolutely: it is outside GetTrack's index space, so it never enters the enumeration any of these writes iterate, and its visibility flags are never driven (the SDK forbids B_SHOWINTCP/B_SHOWINMIXER on master).
• Solo surfaces are disjoint per mode, cached not destroyed. A real switch (target != active) reads every live track's raw I_SOLO, banks the non-zero values against the OUTGOING mode, clears them, and replays the incoming mode's banked values verbatim — solo-in-place and safe-solo variants included, never collapsed to a boolean. This is the same snapshot sense of non-destructive that park/restore already gives visibility and FX state: the user's solo is never lost, only parked with the mode it belongs to. A REAPPLY (target == active — tag/untag/show-both, project load) touches solo not at all.
• Parking a track (inactive-mode leaf) drives B_SHOWINTCP=0, B_SHOWINMIXER=0 (hide both panels), B_MAINSEND=0 (out of mix), I_FXEN=0 (FX bypassed), and TrackFX_SetOffline(track, fx, true) for each FX (reclaim CPU) — full CPU-park, not mix-removal-only.
• Non-destructive restore. For every flag the tool drives, snapshot the prior value BEFORE parking; on toggle-back restore FROM the snapshot, never to a hardcoded "on." Round-trip (snapshot → park → restore) returns every driven flag to its captured value — the phase's trust anchor, the analog of the capture null test. Per-FX offline is snapshotted WITH each FX's identity (TrackFX_GetFXGUID) and restored through core/view/fx_offline, so a chain reordered while the track was parked cannot land one plugin's state on another; an FX gone at restore time is dropped and reported to the console, never restored onto its old slot.
• GUID-keyed, reorder-safe. Membership/snapshot keys on track GUID (GetTrackGUID), never track index; tolerates unknown/stale GUIDs (pruned on reconcile).
• Relative/portable state only in the persisted view section (GUID strings, mode ids — no absolute paths, no index positions).
• Documented caveat: offlined FX re-instantiate when a track returns to the active mode — stateful plugins (convolution, loaded samplers, tail-holding effects) re-initialize on return (load hitch, un-persisted internal state lost). Accepted cost of the CPU reclaim; surfaced at the toggle affordance (tooltip). The hitch no longer sits on the switch's synchronous path: per-FX offline/online is enqueued and applied on a later idle tick (view_fx_park), so the new mode paints first. The deferral changes only WHEN the plugins move — they still unload and re-instantiate, and un-persisted internal state is still lost. What it does change is the undo record: the offline writes land outside the switch's undo block, so the tool no longer re-drives them on an undo or a redo — what a Ctrl-Z then leaves the chain at is REAPER's own FX-state record, [verify — DAW].
• Stated DEVIATION — the undo mask does not keep FX out of a real switch. The apply mask (kApplyUndoMask) drops UNDO_STATE_FX and ORs it back in when a driven flag in that domain moved; the only such flag is I_FXEN, which every park writes. So any switch that parks at least one track still makes REAPER marshal the project-wide FX chunk into its undo record. The saving is real only on a reapply and on a no-op switch. Narrowing it further would mean not carrying I_FXEN in the undo record at all, which would break "one switch is one Ctrl-Z."
• Show-both semantics: a per-track "pin visible across modes" flag re-enables processing whenever shown. A show-both leaf appears in every mode's visible set and is never parked — its driven flags stay at snapshot/restored values, FX online, in the mix. ("Show but keep parked" is not offered.) Stored on the membership record; persists; togglable per selection.
• No literal second canvas. A literal second arrange surface, a second window, or a duplicated project stays rejected — reject any such path in review.

Two-canvas sub-phase (Phase D2/E) — settled and landed parts, DAW-application half:

• Fixed-lane item-level separation mechanics. Map mode → lane; toggle drives per-lane play/show so only the active mode's lane is present. Items keep their real position and real track — nothing is moved in time or deleted. SDK surface (verified present in vendor/reaper-sdk): track-side I_FREEMODE = 2, I_NUMFIXEDLANES, C_LANEPLAYS:N; item-side I_FIXEDLANE, C_LANEPLAYS, B_FIXEDLANE_HIDDEN. I_FREEMODE changes require UpdateTimeline() to take visible effect.
• Inactive-mode content is hidden AND silenced. The off-mode lane is set C_LANEPLAYS = 0 — neither shown nor played — consistent with exclusive membership and with D1's "flipping modes is a real change, not cosmetic." Show-both is the deliberate opt-out for a lane that must stay audible across modes.
• Capture placement is mode-aware. An explicit placement while in Design mode — including capture-and-place — lands the item in the Design lane; the same rule governs manual insertion. The capture load-bearing principle is untouched: capture still writes a file + index entry and never auto-inserts; this governs only where an explicit placement lands.
• REAPER floor: v7 for this sub-phase (fixed lanes shipped in v7); no version-gate branch — below v7 the sub-phase is simply unavailable.

Item→lane membership rules (the adoption rule, exclusive-per-item membership, the managed/manual lane distinction, and the lane-ownership index) are model concepts owned by core/view — see that directory's Invariants; this directory only applies the resulting lane state to live tracks.

Modules

• view — Design View shell: snapshots flag values before parking, drives hide + CPU-park on inactive-mode leaves (B_SHOWINTCP/B_SHOWINMIXER/B_MAINSEND/I_FXEN, with per-FX offline deferred to view_fx_park), restores from snapshot. Owns the one discriminator (target != active) that separates a real switch from a reapply, and with it both the playback gate (transportBlocksModeSwitch) and the solo cache/clear/restore seams. Never touches master or B_MUTE.
• view_fx_park — the per-FX offline surface: the TrackFX_GetFXGUID identity read snapshot/park/restore share, the deferred intent queue that keeps TrackFX_SetOffline off the switch's synchronous path (at most one intent per track GUID, latest wins, an intent landing on its own pending inverse cancels it), and the idle-tick drain main.cpp's OnTimer calls. The drain owns no model state. A snapshot is dropped where the restore is PLANNED — the flags are back at their captured values from that moment, and a model that still described the track as parked would let a persist or a reapply inside the drain window replan a restore over whatever the user changed since. What the deferral costs instead is that the live FX chain stops being a trustworthy snapshot source while an intent is pending: a park that CANCELS a pending restore takes the pre-park FX states from that restore's ops (preParkFxFromCancelledRestore), because the chain still reads the parked values and the cancel means no drain will ever fix them.
• view_solo — the I_SOLO read/write pair behind the per-mode solo surface, plus clearTrackSolos/restoreTrackSolos, the outgoing-clear and incoming-replay entry points view drives them through. Holds no policy: what to cache, clear, or replay is core/view/solo_cache.

Gotchas

• The pure mode model (ViewModeModel, membership, reconcile(liveGuids), the snapshot-based park/restore planner) lives in core/view — reference it, do not duplicate its spec here.
• The Two-canvas sub-phase (Phase D2/E)'s settled DAW-application rules (fixed-lane mechanics, mode-aware capture placement, hidden-AND-silenced) are reflected in Invariants above; the membership/lane-ownership model concepts it also covers live in core/view's Invariants.
• REAPER's own undo restores live I_SOLO but not the model's solo cache or activeModeId — neither rolls back with a Ctrl-Z. An undo after a mode switch leaves the two out of step, and the next switch banks the undo-restored solos under whatever mode id is active at that point, not the one the user undid back to. Pre-existing: snapshots_ already carries this same model-vs-undo split; the solo cache inherits it rather than introducing it. Not fixed here.
• fx_offline's identity keying (TrackFX_GetFXGUID) assumes the GUID stays attached to its plugin across a chain mutation while parked. That is [verify — DAW] (see fxGuidString in view_fx_park.cpp) and SWS issue #802 is a known reason it might not hold: SNM_MoveOrRemoveTrackFX reportedly leaves the FXID lines behind on reorder rather than moving them with the plugin. If confirmed, an SWS-driven reorder of a parked track's chain — not a native drag-reorder — can produce wrong-plugin restores or mass drops through resolveFxRestore. Do not design around this pre-emptively; if native reorder is clean (the likely case), only the SWS path degrades.