docs(design-view): parent visibility = descendant-derived OR own membership

Untagged folder carrying its own FX/media shows in Arrange (its default) as
well as any mode derived from its children. Parents still never parked.
This commit is contained in:
2026-07-23 06:33:24 -04:00
parent fbb9cf5f36
commit 56f2e3e308
2 changed files with 25 additions and 11 deletions
+9 -3
View File
@@ -197,9 +197,15 @@ enforces the separation **without ever destroying the user's real state.**
- **Membership.** Default = Arrange; every untagged leaf belongs to it. Leaves - **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 **opt in** to Design (or any mode). No track appears in two modes at once except
(a) via an explicit **show-both** toggle, or (b) parent/folder derivation. (a) via an explicit **show-both** toggle, or (b) parent/folder derivation.
- **Parents are derived, never tagged.** A parent appears in — and is never parked - **Parents are derived, never tagged.** A parent/folder track is visible in mode M
in — every mode any of its descendant leaves belongs to. Rule of thumb: **tag if **either** (a) any descendant leaf is visible in M (descendant-derived), **or**
leaves; parents follow.** Master track is always visible and never touched. (b) the parent belongs to M by its **own membership** — and an untagged parent is
an Arrange member by default. So an untagged folder carrying its own FX/media
above all-Design leaves shows in **both** Arrange (its own default) and Design
(derived from its children). A parent is **never parked** in any mode it is visible
in. Rule of thumb: **tag leaves; parents follow** — the common case, since a
content-bearing folder still surfaces wherever its own membership places it.
Master track is always visible and never touched.
- **N-mode model, two-mode UI.** The data model carries arbitrarily many modes; the - **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). UI ships **Arrange** + **Design**. A mode is (stable id, display name, ordinal).
Arrange is special only as the default home for untagged leaves. Arrange is special only as the default home for untagged leaves.
+16 -8
View File
@@ -90,10 +90,17 @@ home for untagged leaves — structurally it is just another mode.
elsewhere. Untagged = Arrange. elsewhere. Untagged = Arrange.
- **Leaves opt in.** You tag a *leaf* track into Design (or any mode). You never - **Leaves opt in.** You tag a *leaf* track into Design (or any mode). You never
tag a parent. tag a parent.
- **Parents are derived, never tagged.** A folder/parent track appears in — and is - **Parents are derived, never tagged.** A folder/parent track's visibility is the
never parked in — every mode that *any* of its descendant leaves belongs to. If **OR of two sources**: (a) *descendant-derived* it appears in every mode that
a folder holds two Design leaves and one Arrange leaf, the folder shows in both *any* of its descendant leaves belongs to; **or** (b) *its own membership* — an
modes. Rule of thumb: **tag leaves; parents follow.** untagged parent is an Arrange member by default, exactly like a leaf. If a folder
holds two Design leaves and one Arrange leaf, the folder shows in both modes by
descendant derivation. The case own-membership fixes: an **untagged folder that
carries its own FX/media** above leaves that are *all* tagged Design still shows in
**Arrange** (its own default) as well as Design (derived from its children) —
without the own-membership clause it would vanish from Arrange even though the
folder itself is an Arrange member. A parent is **never parked** in any mode it is
visible in. Rule of thumb: **tag leaves; parents follow** — still the common case.
- **Master is always visible**, in every mode, and the tool never touches its - **Master is always visible**, in every mode, and the tool never touches its
flags. (REAPER's own SDK forbids driving `B_SHOWINTCP`/`B_SHOWINMIXER` on the flags. (REAPER's own SDK forbids driving `B_SHOWINTCP`/`B_SHOWINMIXER` on the
master track — the invariant and the API agree.) master track — the invariant and the API agree.)
@@ -101,10 +108,11 @@ home for untagged leaves — structurally it is just another mode.
mode only via (a) the explicit *show-both* toggle, or (b) the parent-derivation mode only via (a) the explicit *show-both* toggle, or (b) the parent-derivation
rule above. Otherwise a leaf lives in exactly one mode. rule above. Otherwise a leaf lives in exactly one mode.
The parent-derivation rule is why the pure model must be **folder-tree aware**. It The descendant-derived half of the parent rule is why the pure model must be
cannot answer "should this parent be visible in mode M?" from the membership index **folder-tree aware**. Own-membership (part b) is answerable from the membership
alone — it needs the current parent↔child structure, which the shell reads from index alone, but descendant derivation (part a) is not — to know whether *any* child
REAPER's `I_FOLDERDEPTH` and feeds in. The tree is an *input* to the pure model's leaf is visible in mode M, the model needs the current parent↔child structure, which
the shell reads from REAPER's `I_FOLDERDEPTH` and feeds in. The tree is an *input* to the pure model's
visibility query, not something the model stores (folder structure is REAPER's visibility query, not something the model stores (folder structure is REAPER's
truth and changes underneath us). truth and changes underneath us).