reasampler/src/core/view/CLAUDE.md

src/core/view — pure Design View mode model

Scope

Pure, REAPER-free Design View model: mode/track membership, folder-derived visibility, snapshot-based park/restore planning, new-content (GUID) detection, and the managed/manual lane-identity convention that underlies per-item mode separation (fixed lanes). Does not include: the actual DAW-side flag application (hide, CPU-park, per-FX offline, restore via B_SHOWINTCP / B_SHOWINMIXER / B_MAINSEND / I_FXEN) or the never-touch-master/mute/solo enforcement — those live in shell/view.

Invariants

Design View — additive phase spec (settled decisions; Two-canvas sub-phase, settled 2026-07-23):

• Membership. Default = Arrange; every untagged leaf belongs to it. Leaves opt in to Design (or any mode). No track appears in two modes at once except via an explicit show-both toggle or parent/folder derivation.
• Parents are derived, never tagged. A parent/folder track is visible in mode M if either any descendant leaf is visible in M, or the parent belongs to M by its own membership; an untagged parent is an Arrange member by default. A parent is never parked in any mode it is visible in. Master track is always visible and never touched.
• N-mode model, two-mode UI. The data model carries arbitrarily many modes; the UI ships Arrange + Design. A mode is (stable id, display name, ordinal).
• Persistence. Membership index + last-active mode + per-track flag snapshots ride in the existing "reasampler" project ext-state namespace and travel with the .rpp.
• Non-destructive restore (enforced in the pure layer). For every flag the tool drives, snapshot the prior value before parking; on toggle-back, restore from the snapshot, never to a hardcoded default. Round-trip (snapshot → park → restore) returns every driven flag to its captured value — this is the phase's trust anchor, the analog of the capture null test.
• GUID-keyed, reorder-safe. Membership keys on track GUID (GetTrackGUID), never track index; tolerates unknown/stale GUIDs (pruned on reconcile via ViewModeModel::reconcile(liveGuids)).
• Relative/portable state only in the persisted view section (GUID strings, mode ids — no absolute paths, no index positions).
• Show-both semantics. A per-track "pin visible across modes" flag that 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. Stored on the membership record; persists; togglable per selection.
• Non-goals / guardrails: No literal second canvas — a second window or duplicated project stays rejected; subproject/second-project-file approaches and overloading item D_POSITION with mode semantics (timebase-offset regions) are rejected paths (the latter collides with the capture null test). Every leaf is managed: an untagged leaf is an Arrange member and, when the active mode is not Arrange, is fully parked and snapshot-restored exactly like a tagged leaf; show-both is the only way to opt a leaf out of parking. Restore from snapshot, never to a default: no hardcoded "on" restores.

Two-canvas sub-phase (Phase D2/E) — settled and landed parts only:

• Mechanism: fixed item lanes. 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.
• Membership: adoption rule for new items; active mode for new tracks. New tracks are tagged to the active mode at creation. New items follow an adoption rule: if the item's track has pre-existing managed-eligible content spanning exactly one mode, the item adopts that mode; the active-mode fallback applies only when the track is empty or already spans multiple modes. Items in manual lanes are excluded from the prior-mode computation and are not auto-tagged at all. Membership is exclusive per item except via show-both.
• Managed vs. manual lanes — indexed and distinct. The tool maintains a lane-ownership index — per (track GUID, lane): managed (which mode owns it) vs. manual (user-minted, outside the mode system). Mode operations touch only managed lanes; manual lanes are never shown, hidden, silenced, or re-laned by a toggle, and their C_LANEPLAYS stays exactly as the user set it. The ownership index rides in "reasampler" view_state alongside the membership index, GUID-keyed and portable. New invariant — mode operations touch only managed lanes: "the 'which lanes may this toggle touch' decision is a pure query over the ownership index; only reading REAPER's live lane state is shell."
• REAPER floor: v7 for this sub-phase (fixed lanes shipped in v7); no version-gate branch — below v7 the sub-phase is simply unavailable.
• Precision invariants (null test, bit-identical repeats, non-destructive, exact bounds, relative-paths-only) are entirely unaffected by this sub-phase — no capture path changes; lane assignment and C_LANEPLAYS are reversible flags, never a destructive operation.

Modules

• view_mode_model — Design View mode system: mode registry, GUID-keyed membership, folder-tree-aware visibility derivation, snapshot-based park/restore planner, JSON round-trip.
• view_tree — pure I_FOLDERDEPTH→FolderTree helper for the Design View shell.
• mode_switch — REAPER-free segment layout + hit-test for the bank_panel's Design View mode switch.
• guid_diff — the pure, REAPER-free core of the D2 Wave-2 new-content detection: newGuids(previous, current) computes the GUIDs present in current but absent from previous (empty GUIDs ignored); GuidBaseline tracks the live GUID set across polls for one project, implementing the first-poll-after-open guard (the first observe() after construction/reset() records a baseline and reports nothing new, so pre-existing content is never mass-tagged) and re-arms via reset() on a detected project switch so detection never diffs across two unrelated projects.
• lane_keys — the pure, REAPER-free convention mapping a fixed lane's durable REAPER name (P_LANENAME:n) to the opaque lane-key view_mode_model keys by, plus the managed/manual heuristic both the toggle-apply path and the new-content/auto-tag exemption path share: kManagedLanePrefix ("reasampler:") stamps every lane the tool mints; isManagedLaneName/managedLaneKey/laneNameForMode/modeIdFromLaneName round-trip a lane name ↔ its owning mode id; isOnManualLane is the single predicate governing which lanes a toggle may drive and which items are exempt from auto-tag.

Gotchas

• REAPER exposes no durable per-lane GUID — the only lane identity is the ordinal I_FIXEDLANE, which REAPER renumbers on reorder/delete. Lane identity must ride on the durable P_LANENAME (lane_keys), never the raw ordinal, or a reorder will silently corrupt managed/manual ownership.
• kManagedLanePrefix ("reasampler:") is stable-forever like an action-id string — changing it strands the ownership of every already-minted lane in every already-saved project.
• guid_diff::GuidBaseline must have reset() called on every detected project switch, or the next observe() will diff across two unrelated projects and mass-tag (or miss) content.