docs: 1.0 documentation restructure
Split root CLAUDE.md into 19 per-directory files scoped to their source area. Roll v0 history into docs/ARCHIVE.md; retire CONTEXT.md, CONTEXT-ARCHIVE.md, PLAN.md, COMPLETED.md. Move plan docs under docs/. Rescue 9 live deferrals into docs/TODO.md.
This commit is contained in:
@@ -0,0 +1,85 @@
|
||||
# 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`/`I_SOLO`.** The tool owns only visibility,
|
||||
`B_MAINSEND`, `I_FXEN`, and per-FX offline, on every managed leaf, tagged or
|
||||
untagged. User mute/solo survives every toggle untouched; the master track's
|
||||
visibility flags are never driven (the SDK forbids `B_SHOWINTCP`/`B_SHOWINMIXER`
|
||||
on master).
|
||||
- **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.
|
||||
- **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 (possible load hitch, un-persisted internal
|
||||
state lost). Accepted cost of the CPU reclaim; surfaced at the toggle affordance
|
||||
(tooltip).
|
||||
- **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` + per-FX offline), restores from snapshot. **Never touches master or `B_MUTE`/`I_SOLO`.**
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user