# ReaSampler — implementation briefing

A native C++ REAPER extension that captures any arbitrary audio source into a
per-project **sample bank** (cached files + a docked grid), decoupled from the
arrange view, with keyboard/MIDI-bindable capture and placement. Built as a
precision tool: deterministic, non-destructive, no clutter.

This document is the spec. Read the existing scaffold first (`src/main.cpp` is
the REAPER<->extension contract; the pure/testable-core split in `src/bank_model.*`
is the pattern to preserve — the *discipline* of a pure testable core split from
REAPER-facing shells runs throughout the codebase). Verify every REAPER API name
and signature against `vendor/reaper-sdk/sdk/reaper_plugin_functions.h` before use
— the API names in this brief are correct-by-intent but treat them as hints, not
gospel, and check argument order/types.

## The load-bearing principle

**Capture and placement are separate acts.** Capturing audio writes a file to
the bank and adds an index entry — it NEVER puts an item in the arrange. Placement
is a distinct, on-demand action (insert / drag). Any code path that auto-inserts a
capture into the timeline violates the entire point of the tool and must be
rejected in review. This single rule is why the tool exists.

## Settled decisions

- **Capture modes:** offline render (deterministic, the default) AND realtime
  record (for hardware / performed FX). Both sit behind one capture interface and
  produce identical bank entries.
- **Bank scope:** per-project, travels with the `.rpp`. Files live in a
  project-relative subfolder; the index persists in project ext state. No absolute
  paths anywhere in the index.
- **Material:** must handle full-mix/stem bounces, chops/one-shots, and
  single-cycle/wavetable grabs equally. That means exact sample-accurate bounds,
  explicit tail control, channel-count preservation, and loop/zero-crossing
  handling all matter from day one.

> Build detail for this phase (module architecture, data model sketch, API surface, build order) moved to CONTEXT-ARCHIVE.md.

## Precision invariants (enforce, test)

- **Null test:** a dry offline capture of a range, re-inserted at its source
  position, nulls to silence against the source. Ship this as a verification
  action; it is the tool's trust anchor. (Verification action cut per
  `docs/product/provenance.md` — manual verification only.)
- **Bit-identical repeats:** identical offline requests produce identical files.
- **Non-destructive:** capture never mutates source items or tracks (realtime's
  temp track is created and removed cleanly; source routing is restored).
- **Exact bounds:** no rounding of the requested range; no added silence unless a
  tail is explicitly requested; channel count preserved (no silent stereo fold).
- **Relative paths only** in the persisted index.

## Non-goals / guardrails

- No auto-insertion of captures into the arrange (see the load-bearing principle).
- Native OS drag-out is deferred to the final milestone — `InsertMedia`-driven
  placement is the primary path and must work first.
- Do not depend on REAPER's peak API for thumbnails; compute from the captured
  file.
- Do not silently time-stretch on insert; conform is opt-in.
- Do not trust this brief's API names blindly — verify against the SDK header.

## Open questions to resolve during build

- Exact no-dialog render command/flag on the current REAPER build.
- ~~Realtime record routing that captures wet master output without altering the
  user's monitoring.~~ **Resolved:** realtime taps the *selected track* (track scope),
  not the master — a post-fader track→temp send is chain-independent by construction,
  so there is no wet-master-routing problem and monitoring is untouched (see the
  Realtime record API surface above).
- Audio format for the bank (wav bit depth default; allow float for wavetable
  fidelity).
- Thumbnail cache: recompute vs store peak bins alongside the index.

---

# Design View — additive phase spec

> **Additive section.** This is a standalone phase parallel to — not part of — the
> M0–M11 capture roadmap above. Nothing above changes. Product framing (workflow
> narrative, screenset differentiation, N-mode reasoning, design-direction calls)
> lives in `docs/product/design-view.md`; this section is the authoritative
> technical spec, matching the house style of the capture spec. Same standing
> discipline applies: **verify every REAPER API name/signature against
> `vendor/reaper-sdk/sdk/reaper_plugin_functions.h` before use.**

## What it is

A **track-visibility-plus-processing "mode" system**, toggled from the ReaSampler
window. Tracks used purely for sound design (scratch oscillators, FX mangling,
resampling sources) are tagged into **Design** mode; the arrangement's real tracks
are **Arrange** mode (the default). Toggling to a mode **hides and disables** the
tracks that don't belong to it. Workflow value: mental separation + clutter
elimination — be in Design view, resample into the bank, flip to Arrange, place it.

Design View is a **mode projection over REAPER's single arrange timeline** —
reaching both **tracks** (parked per mode) and **items** (lane-split per mode on
shared tracks). It approximates two canvases without a second surface: same project,
same timeline, but each stance sees its own tracks and its own items. It **never**
duplicates the project or opens a second window.

> **Two-canvas reach — settled (2026-07-23).** The original single-canvas framing
> here was derived from a REAPER constraint, not chosen as a product stance. Daniel
> reopened it — "as close as possible to two separate design and arrange canvases,
> same project, different items and leaves" — and has now signed off on the
> mechanism and resolved all forks. The "different leaves" half is delivered by
> track-parking (D1). The "different items" half is delivered by **per-item mode
> membership via REAPER fixed lanes** (track-side `I_FREEMODE=2`, `I_NUMFIXEDLANES`,
> `C_LANEPLAYS:N`; item-side `I_FIXEDLANE`, `C_LANEPLAYS`, `B_FIXEDLANE_HIDDEN`):
> each mode owns a lane on a shared track, and toggling shows/plays only the active
> mode's lane. This is an item-visibility projection over the one timeline — the
> exact analog of today's track-visibility projection — with still **no** literal
> second surface, window, or duplicate project. It is an **additive sub-phase (Phase
> D2 / Phase E)** on top of D1, spec'd in *§Two-canvas sub-phase* below. Full framing
> and the rejected alternatives (timebase-offset, subproject) live in
> `docs/product/design-view.md` §Two-canvas direction.

It is the visibility/processing analog of the capture pillar's load-bearing rule:
**designing and arranging are separate stances on one timeline**, and the tool
enforces the separation **without ever destroying the user's real state.**

## Settled decisions

- **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
  (a) via an explicit **show-both** toggle, or (b) parent/folder derivation.
- **Parents are derived, never tagged.** A parent/folder track is visible in mode M
  if **either** (a) any descendant leaf is visible in M (descendant-derived), **or**
  (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
  UI ships **Arrange** + **Design**. A mode is (stable id, display name, ordinal).
  Arrange is special only as the default home for untagged leaves.
- **Parking a track** (inactive-mode leaf): `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
  is the deliberate choice over mix-removal-only.
- **Never touches `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.
- **Persistence.** Membership index + last-active mode + per-track flag snapshots
  ride in the existing `"reasampler"` project ext-state namespace and travel with
  the `.rpp`. On project open, reapply the active mode's visibility + processing.

## Precision invariants (enforce, test)

- **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. This is the phase's trust anchor — the analog of the
  capture null test — and is enforced in the pure layer.
- **Mute/solo untouched.** No toggle ever reads or writes `B_MUTE` / `I_SOLO`.
- **Master untouched.** The tool never drives the master track's visibility flags
  (the SDK forbids `B_SHOWINTCP`/`B_SHOWINMIXER` on master; the invariant agrees).
- **GUID-keyed, reorder-safe.** Membership keys on track GUID (`GetTrackGUID`),
  never track index; tolerates unknown/stale GUIDs (prune 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; surface it at the toggle affordance (tooltip).

## 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, FX online, in the
mix. ("Show but keep parked" is not offered — a visible-but-silent-and-offline
track is clutter with a thumbnail.) Stored on the membership record; persists;
togglable per selection.

> Build detail for this phase (module architecture, API surface) moved to CONTEXT-ARCHIVE.md.

## Non-goals / guardrails

- **No *literal* second canvas.** A literal second arrange surface, a second window,
  or a duplicated project stays **rejected** — reject any such path in review. This
  guardrail was **narrowed (2026-07-23), not lifted**: per-item mode separation via
  REAPER fixed lanes on shared tracks (an item-visibility projection over the one
  timeline) is now **allowed** and specified in *§Two-canvas sub-phase* below. Paths
  that remain **rejected**: subproject / second-project-file approaches, and
  overloading item `D_POSITION` with mode semantics (timebase-offset regions) — the
  latter collides with the capture null test. See `docs/product/design-view.md`
  §Two-canvas direction for why those were rejected.
- **Never touch mute/solo.** Any code path reading/writing `B_MUTE` / `I_SOLO` is a
  bug.
- **Never drive a manual lane** (Phase D2). A mode toggle touches only **managed**
  lanes (minted by the mode system, keyed in the lane-ownership index). Any code path
  that shows, hides, silences, or re-lanes a **manual** lane — a user-created comp/take
  lane outside the mode system — is a bug. The tool drives only lanes it created.
- **Every leaf is managed.** The mode system owns all leaf tracks: an untagged leaf
  is an Arrange member, and when the active mode is not Arrange it is fully parked
  and snapshot-restored exactly like a tagged leaf out of its mode. **show-both** is
  the only way to opt a leaf out of parking. (Parents stay visibility-only, master
  is never touched — see below.)
- **Restore from snapshot, never to a default.** No hardcoded "on" restores.
- **Verify API names** against the SDK header before use.

## Open questions to resolve during build

- Reconcile residuals (bulk behavior shipped — `ViewModeModel::reconcile(liveGuids)`
  prunes orphaned snapshots on every toggle/load; folder restructure is self-healing
  because the tree is rebuilt each toggle; membership is intentionally kept so
  undo-delete preserves the tag). Two sub-items remain deferred:
  - **FX-GUID keying for `restoreFxOffline`:** currently restores by slot index; a
    reshuffled FX chain while parked will restore to the wrong slot. Fix requires
    FX-GUID keying + snapshot-schema migration — deferred.
  - **Dormant membership entries:** truly-deleted tracks accumulate stale entries in
    persisted `view_state` (harmless and bounded); natural home is a future
    user-initiated "compact" action, not automatic pruning (which would reintroduce
    undo-delete tag-loss).
- Interaction with the user having a screenset active (Design View drives the same
  flags a screenset recall would; last writer wins — confirm no surprising fight).

## Two-canvas sub-phase (Phase D2 / Phase E) — additive to D1

> **Additive sub-phase, settled 2026-07-23.** Extends D1's track-level mode
> projection to **item level** so each stance owns its own items as well as its own
> tracks. Nothing in D1 changes; this wraps it. Runtime floor rises to **REAPER 7**
> for this sub-phase (fixed lanes shipped in v7). Product framing in
> `docs/product/design-view.md` §Two-canvas direction.

### What it adds

On a track present in **both** stances (a show-both track, or a folder carrying its
own media), each mode owns a **fixed lane**: the active mode's lane shows and plays;
the inactive mode's lane is hidden and silent. A Design take and an Arrange take can
then live on the *same track, same time position*, without colliding on the view.
Track-only-in-one-mode content is still handled by D1 track-parking, unchanged.

### Settled decisions

- **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. 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.
- **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 track stays
  single-mode, no lane split, nothing stranded. The active-mode fallback applies
  only when the track is empty (no prior content) or already spans multiple modes.
  Items in **manual lanes** are excluded from the prior-mode computation and are
  not auto-tagged at all (manual/managed boundary unchanged). Deliberate multi-mode
  splits occur only via the explicit tag/move-item actions, never via auto-tag.
  Pre-existing content defaults to **Arrange**. Membership is **exclusive per
  item**: an item lives in exactly one mode, except via the existing **show-both**
  escape hatch. (New-track tagging follows the same active-mode rule as D1 track
  membership; the adoption rule is a refinement for items on shared tracks.)
- **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.
- **Managed vs. manual lanes — indexed and distinct.** Fixed lanes are also REAPER's
  native comping surface: a user may keep **their own** manual lanes (comp takes,
  alternate reads) on a track alongside the mode system's lanes. 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. Items a user adds
  to a **manual** lane are **not** auto-tagged (auto-tag governs normal timeline
  content, not hand-managed lanes). The ownership index rides in `"reasampler"`
  `view_state` alongside the membership index, GUID-keyed and portable.
- **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.** No version-gate branch — below v7 this sub-phase is simply
  unavailable.

### Precision invariants (unaffected — called out explicitly)

The capture 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; lanes are a placement/view concern
downstream of the written file. Lane assignment and `C_LANEPLAYS` are **reversible
flags**: the item is never relocated in time or deleted, so the sub-phase extends the
D1 non-destructive snapshot/restore contract to a new (item-lane) flag family rather
than introducing any destructive operation.

**New invariant — mode operations touch only managed lanes.** A mode toggle drives
only lanes the mode system minted (managed lanes, keyed in the lane-ownership index).
Manual lanes — user-created comp/take lanes outside the mode system — are **never**
shown, hidden, silenced, or re-laned by a toggle; their `C_LANEPLAYS` is left exactly
as the user set it. This is the fixed-lane analog of *never touch `B_MUTE`/`I_SOLO`*
and *never touch master*: **the tool drives only what it created.** Enforceable and
testable in the pure layer — 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.

> Build detail for this sub-phase (module architecture, new-content detection, API surface) moved to CONTEXT-ARCHIVE.md.

---

# Multi-bank — additive phase spec

> **Additive section.** This is a standalone phase parallel to — not part of — the
> M0–M11 capture roadmap and Phase D above. Nothing above changes. Product framing
> (workflow narrative, pool-privilege reasoning, movement semantics, UI-direction
> calls) lives in `docs/product/multi-bank.md`; this section is the authoritative
> technical spec, matching the house style of the capture and Design View specs.
> Same standing discipline applies: **verify every REAPER API name/signature
> against `vendor/reaper-sdk/sdk/reaper_plugin_functions.h` before use.**

## What it is

The single per-project **bank** (`bank_model` / `BankIndex`) is generalized into a
**multi-bank system**. The existing bank becomes **the pool** — a default,
always-present bank that every capture lands in unless another bank is the active
target. On top of the pool the user creates **named banks** ("Drums", "1-Shots",
"Synth Hits") that group samples for a purpose. Samples move freely between any
banks, including to and from the pool. Exactly one bank is the **active bank** — the
capture target — the pool by default.

**This is the container generalization of the capture pillar's bank.** The pool is
to banks what Arrange is to modes: structurally one member of an N-collection, but
privileged as the default home. The capture pillar's load-bearing rule is
untouched — capture still writes a file + an index entry and never inserts into the
arrange; the only change is *which* index the entry lands in.

## Settled decisions

- **The pool is privileged, not special-cased.** Structurally the pool is one
  `BankIndex` among many in the container (mirror of "Arrange is just another
  mode"). Semantically it is privileged: it **always exists**, is **un-deletable**,
  and is **un-renamable** (fixed id + fixed display name "Pool"). New projects and
  migrated single-bank projects start with the pool and **zero** named banks. This
  keeps the data model uniform (no pool-shaped special type) while the rules layer
  enforces the three privileges.
- **Container in the pure core; a `BankIndex` per bank.** A new pure module
  `bank_book` owns an ordered registry of banks, each bank = `{ stable bank id,
  display name, ordinal, BankIndex }`. **`BankIndex` is untouched** — the multi-bank
  layer wraps it, it does not modify it (additive; no `bank-id` field on `Sample`).
  Bank id is the stable key (GUID-style, minted on bank create); display name and
  ordinal are mutable (rename / reorder). **Display names are unique**, enforced in the
  pure model on create and rename: `createBank` / `renameBank` reject a name that
  duplicates an existing bank's (renaming a bank to its own current name is a no-op
  success). The comparison is **trimmed + case-insensitive (ASCII)**, so "Drums",
  "drums", and " Drums " cannot coexist; the pool's reserved name "Pool" is protected
  by the same check. Uniqueness makes by-name resolution in the action shell
  unambiguous by construction. The pool is the first, seeded, fixed-id
  member. `bank_book` is the mirror of `bank_model` and `view_mode_model`: pure, no
  REAPER types, unit-tested outside the DAW, JSON round-trip.
- **Active bank lives in the model, routes through the capture path.** `bank_book`
  carries the active bank id (defaults to the pool). The capture action family
  resolves "which bank does this capture land in?" by asking the session for the
  active bank's `BankIndex`, then adds exactly as today. No capture backend changes;
  only the add-target is selected upstream. Activating a bank is a model mutation +
  a persist write; it never touches the timeline.
- **Movement moves the index entry, not the file.** Moving a sample from
  bank A to bank B is an **index-only** operation: remove the `Sample` from A's
  `BankIndex`, add it to B's. The underlying file stays in the project bank folder —
  banks are logical groupings over one shared file pool, not separate folders on
  disk. This keeps movement cheap, non-destructive, and immune to path-rewrite bugs.
  (Per-bank subfolders on disk are an explicit non-goal — see guardrails.)
- **Dedup-by-hash is per-bank.** Each `BankIndex` dedups within itself, unchanged.
  Moving a sample whose hash already exists in the destination bank **collapses**
  onto the existing entry there (the move is a no-op add on the destination side,
  and the source entry is still removed) — the same collapse semantics
  `BankIndex::add` already has, now observed across a move. Cross-bank dedup is
  **not** enforced: the same hash may exist in the pool and in a named bank
  simultaneously (that is the point — copy lets a sample be grouped into "Drums"
  while still living in the pool).
- **Move vs. copy are distinct acts; move is the default.** *Move* removes from
  source, adds to destination (one logical sample, regrouped) — it is the **primary,
  low-friction gesture**, so a sample lives in exactly one bank at a time. *Copy* adds
  to destination and leaves the source entry intact (same file, two index entries, two
  banks) — the **deliberate secondary act** for the "in two places at once" case. Both
  are index-only; both share the destination-collapse rule. Under move-as-default the
  pool is the default home and staging ground, not a permanent superset: moving a
  sample into a named bank takes it out of the pool. (See product notes for the
  mental-model reconciliation.)
- **Delete drops members; evacuate returns them.** Deleting a **named** bank drops
  its member index entries (files are **not** deleted — file lifecycle stays owned by
  the capture/prune path). A separate **evacuate** operation moves all of a bank's
  members back to the pool (index-only, same destination-collapse-by-hash as move),
  leaving the bank empty. Intended workflow: *evacuate then delete* to keep the
  samples, *plain delete* to drop the grouping and its members. A plain delete of a
  non-empty bank orphans those members out of every index — their files persist on
  disk until prune, referenced by no bank — so the UI **confirms on non-empty delete**
  and offers evacuate as the alternative. Evacuate cannot be applied to the pool.
- **Persistence: a new ext-state key; the pool folds in and the legacy key is
  retired.** The multi-bank state serializes to a new key `banks` in the existing
  `"reasampler"` namespace, alongside `view_state` and `project_guid`. The pool's
  index rides *inside* the `banks` blob as bank-zero — persisted identically to any
  named bank (one blob, one section, one JSON shape). **Migration:** on load, if a
  `banks` key is absent but a legacy `bank_index` key is present, the legacy index is
  promoted into the pool inside a freshly-minted `banks` blob and the book is
  `{ pool }` with zero named banks — a one-way, lossless promotion. After migration
  the `banks` blob is **authoritative**; the legacy `bank_index` key is **retired** (not
  written or read back going forward). The one-way retirement trades pre-multi-bank
  backward-read compatibility for the clean single-blob shape — an accepted,
  forward-only migration consistent with how M4 project state already moves forward.
- **Vertical-split UI, pool on top.** The bank window splits vertically: **pool on
  top**, the **named-banks region below** (a tab-page strip, one tab per named bank,
  empty when none exist). Two full-height toggles collapse the split: **pool
  full-height** (hide the named-banks region) and **banks full-height** (hide the
  pool). The Design View segmented mode switch already in the window header is
  **orthogonal** and stays — it governs timeline visibility, not bank grouping; the
  two coexist in the header/body without interaction.

## Precision / invariant implications

- **Relative-paths-only survives unchanged.** Every `BankIndex` in the book keeps
  the relative-path invariant at its `add` boundary — the book adds no new path
  handling, because movement is index-only and files never relocate. The invariant
  is enforced N times (once per bank) by the exact code that enforces it today.
- **Non-destructive.** Bank create / rename / delete / activate / evacuate and sample
  move / copy mutate only index + ext-state; no file is written, moved, or deleted,
  and no timeline item is touched. Deleting a **named** bank drops its member index
  entries but does **not** delete their files; file lifecycle stays owned by the
  capture/prune path, not the bank container. A file referenced *only* by the deleted
  bank becomes an orphan on disk — present but indexed by no bank — until the
  capture/prune path reclaims it. That orphaned-until-prune window is designed, not
  accidental; the *evacuate* verb and the confirm-on-non-empty-delete guardrail exist
  to keep the user out of it unintentionally.
- **Travels-with-the-.rpp preserved.** The `banks` blob rides the same ext-state
  namespace and the same GUID-primary project-identity / Save-As-relocation
  machinery as the bank index does today (M4). One shared physical bank folder, one
  ext-state namespace, now three logical sections (banks + view + identity).
- **Determinism / null-test / bit-identical are untouched** — they are properties
  of the capture path and the file, and the multi-bank layer sits above the file
  entirely.

> Build detail for this phase (module architecture, API surface) moved to CONTEXT-ARCHIVE.md.

## Non-goals / guardrails

- **No per-bank folders on disk.** Banks are logical groupings over one shared
  project bank folder. Do not create a subfolder per bank or move files on
  bank-move — reject any such path in review (it reintroduces the path-rewrite
  bug class M4 closed).
- **No cross-bank dedup enforcement.** The same hash may exist in multiple banks
  (that is what copy is for). Do not add a global dedup that collapses across banks.
- **Pool privileges are inviolable.** No action path may delete or rename the pool,
  leave a project with zero banks, or **evacuate** the pool (the pool is evacuation's
  destination, not a source). Enforce in the pure rules layer, not just the UI.
- **Delete drops members; files are never deleted by a bank op.** Deleting a named
  bank removes its member index entries only. No bank operation writes, moves, or
  deletes a file — file lifecycle stays with capture/prune. The UI **confirms on
  non-empty delete** and offers evacuate; do not silently orphan members.
- **Capture still never inserts into the arrange.** The load-bearing principle is
  unchanged; multi-bank only redirects which index the capture lands in.
- **Additive only.** Do not alter `BankIndex`, the M0–M11 capture roadmap, or Phase
  D semantics. `bank_book` wraps; it does not modify.
- **Verify API names** against the SDK header before use.

---

# Sample removal — additive spec (Phase B, point B5)

> **Additive section, part of the Multi-bank pillar.** The sample-level companion
> to move/copy/evacuate/delete-bank: a verb that **drops a `Sample`'s index entry**
> from a bank (or the pool). Index-only, non-destructive to the file — it sits on
> the same side of the index/file line as every other Phase B op. Product framing:
> `docs/product/removal-and-prune.md` §Sample-remove. Same verify discipline:
> **verify every REAPER API name/signature against the SDK header before use.**

## What it is

Move, copy, and evacuate all keep a sample *somewhere*; there was no verb to drop
a sample outright. **Sample-remove** is that verb: it removes one `Sample` entry
from one `BankIndex`. It exposes the `remove` primitive `bank_model`'s `BankIndex`
**already has** — B5 wires it to an action + a panel affordance, it does not add a
model capability.

## Settled decisions (spec-level)

- **Remove is index-only.** It removes the `Sample` from a `BankIndex` and mutates
  only index + ext-state. No file is written, moved, or deleted; no timeline item
  is touched. Identical non-destructive posture to move/copy/evacuate/delete-bank.
- **Remove can orphan a file — the same designed orphaned-until-prune state a
  non-empty delete-bank produces.** When remove drops the *last* index reference to
  a file (no other bank holds its hash), that file becomes an orphan on disk,
  referenced by no bank, reclaimed later by **prune** (Phase R) — never by remove.
  This is not a new hazard class; it is the existing "files persist until prune"
  window, reached by a sample-level verb instead of a bank-level one.
- **Collapse-by-hash is unaffected.** Remove targets a specific entry in a specific
  bank. Because cross-bank dedup is deliberately not enforced, removing a sample
  from one bank leaves any same-hash entry in another bank intact — the same
  coexistence copy relies on.
- **The pool's *contents* are removable; the pool *container* is not.** Pool
  privileges (un-deletable, un-renamable, un-evacuable) govern the pool as a
  container. Individual samples **can** be removed from the pool — otherwise the
  pool would be a one-way trap. Remove-from-pool is the pool's own "drop this
  sample" verb and is allowed.
- **Remove scope (fork R-A, SETTLED 2026-07-24 — this-bank).** Remove drops the
  entry from *this* bank only, leaving copies in other banks untouched — the core
  and only shipped verb. The action carries a `scope: this-bank | all-banks` seam,
  but **this-bank is the settled default and the only surfaced affordance**;
  all-banks stays a latent parameter (promotable later behind the seam without a
  rewrite), never a surfaced verb now. See product notes §Fork R-A.

## Precision / invariant implications

- **Non-destructive** extends to remove verbatim: index + ext-state only, no file
  touched, no timeline item touched.
- **Relative-paths-only** is unaffected — remove deletes an entry, it adds no path
  handling.
- **Determinism / bit-identical / null-test (capture)** untouched — remove sits
  above the file, same as all of multi-bank.

## Guardrails

- **Removes are silent — no confirm dialog.** Recoverability is provided by the
  batched REAPER undo (R-B): one Ctrl-Z restores the index entry, whether or not
  the sample was a last reference. Files are never deleted by remove
  (orphaned-until-prune is unchanged). `hashReferencedElsewhere` is a tested
  model API retained for Phase R prune; it has no shell caller in the remove path.
- **Undo (fork R-B, SETTLED 2026-07-24 — batched REAPER undo points, Phase-B-wide).**
  Bank/index mutations integrate into REAPER's undo system as **batched undo points**
  (`Undo_BeginBlock` / `Undo_EndBlock`): the related index mutations of one bank
  operation are batched into a single undo point, so one bank operation is one
  Ctrl-Z. This is a **Phase-B-wide** decision — it applies to
  create/rename/reorder/delete-bank, move, copy, evacuate, *and* remove, retro-
  touching B1–B4, not just B5. **Must-verify before build:** confirm against
  `vendor/reaper-sdk` that `"reasampler"` ext-state mutations participate correctly
  in `Undo_BeginBlock`/`Undo_EndBlock` undo blocks — the whole approach depends on
  it. Surfaced with remove because remove is the first verb whose *only* effect is
  index-entry destruction with no relocation, so it is where the gap first bit; the
  fix is shared. See product notes §Fork R-B.

> Build detail for this phase (module architecture, API surface) moved to CONTEXT-ARCHIVE.md.

## Settled forks (Daniel, 2026-07-24)

- **Fork R-A — remove scope.** Settled: **this-bank** (this-bank-primary, all-banks
  a latent seam-only parameter). Folded into Settled decisions above.
- **Fork R-B — undo model for index mutations.** Settled: **batched REAPER undo
  points** (`Undo_BeginBlock`/`Undo_EndBlock`), Phase-B-wide (retro-touches B1–B4),
  with the ext-state-participation SDK check as a must-verify-before-build. Folded
  into Guardrails above and the Phase B / B1 plan points.

---

# Prune — file-lifecycle spec (Phase R — Reclaim)

> **New pillar, its own lettered phase.** Prune is the file-lifecycle path the
> capture and multi-bank specs forward-reference throughout ("files persist on disk
> until prune", "the capture/prune path reclaims it") but that had no phase, module,
> or point until now. It is the **only** operation in ReaSampler that deletes bytes
> off disk. Namespaced **`R` (Reclaim)** alongside `M` (capture), `D` (Design View),
> `B` (Banks) — it is a distinct pillar, not a Multi-bank sub-step, because it
> serves *every* orphan-producing path (delete-bank, sample-remove, re-capture) and
> carries a new risk class (file deletion) with its own invariants. Product framing
> and the phase-placement justification: `docs/product/removal-and-prune.md` §Prune.
> Same discipline: **verify every REAPER/SWELL/filesystem API name/signature against
> the SDK/SWELL headers before use.**

## What it is

Over a project's life, delete-bank and sample-remove (and, potentially, M10
re-capture superseding an old file) leave `.wav` files on disk that no bank index
references — the "orphaned-until-prune" state the specs design in on purpose.
**Prune is the reclaim pass**: reconcile the physical bank folder against the union
of every bank's index, and reclaim the files nothing references. It makes good on
the promise the rest of the spec keeps making.

## The load-bearing rule

> **Remove creates orphans; prune reclaims them.** Sample-remove and delete-bank
> drop index entries and may leave a file referenced by nothing. Prune is the
> single path that turns such an orphan back into free disk space. **No other
> operation deletes a file; prune deletes *only* files that no index references.**
> A bank op that deletes a file is still a bug — prune is not a bank op, it is the
> file-lifecycle op.

This asymmetry is deliberate and must be stated loudly: every *other* invariant
says "no operation deletes a file." Prune is the sole, explicit exception, and its
entire job is deletion — so it must be the *only* file-deleting authority in the
system, with the strongest guardrails.

## Mirror of `reconcile` — the pure pattern one level down

Prune reuses the shape Design View already shipped. `view_mode_model`'s
`ViewModeModel::reconcile(liveGuids)` reconciles *membership entries* against *live
tracks* and returns the residuals to drop. **Prune reconciles *files on disk*
against *referenced files*** (the union of every bank's index) and returns the
orphan set to delete. Same pure pattern, one level down (files instead of GUIDs).

The **decision is pure and unit-tested**: given the set of files present in the
bank folder and the set of files referenced by the book, compute the orphan set.
Only the two ends touch the shell — *enumerating* the bank folder and *deleting*
the orphans are filesystem I/O. Keep the "which files are orphans" core REAPER-free
and hard-tested (this is the safety-critical part); keep the I/O thin. Same
pure/shell split as `bank_model` / `view_mode_model` / `bank_book`.

## Settled decisions (spec-level)

- **Referenced-set is the union across ALL banks, pool included.** A file is an
  orphan iff **no** bank in the book references it. Because copy lets one file be
  referenced by several banks, prune must union references across the whole book
  before deciding. This is the safety-critical computation — the **prune null
  test** is *prune never deletes a file that any index references.*
- **Project-relative resolution, current folder.** Prune enumerates and deletes
  within the project bank folder using the **same M4 project-relative path
  resolution** the index uses, against the *resolved current* folder — never a
  stale absolute path — so a Save-As relocation cannot cause it to mis-identify or
  mis-target orphans.
- **Dry-run first, always.** Prune reports before it deletes: the orphan count,
  reclaimed size, and (for a small set) the files. The dry-run — compute-and-report,
  the pure core with no deletion — is the primary surface; actual deletion is the
  confirmed second step. A prune that silently sweeps is unacceptable for an
  irreversible file-delete.
- **Scope is the bank system's own leavings, not the folder at large.** Prune
  reclaims files that *were* bank files and are now unreferenced — never a file a
  user hand-dropped into the folder. Prune is a reclaimer of ReaSampler's own
  orphans, not a general folder cleaner.
- **Orphan attribution is an owned-file manifest (fork R-D, SETTLED 2026-07-24).**
  The book tracks the set of files it has created (an **owned-file manifest**);
  prune reclaims `(owned ∩ on-disk) − referenced`. This is the honest encoding of
  "reclaim only our own leavings" and rejects folder-sweep (which would delete
  hand-dropped files). **The seam lands early:** because the manifest is cheap to
  maintain from capture onward but a backfill cliff to reconstruct later, **capture
  writes each file it creates into the owned-file manifest starting in Phase B**,
  even though prune consumes it only in Phase R. R1/R2 consume the manifest; they do
  not build it. The manifest is persisted in the `"reasampler"` ext-state; the exact
  persistence shape (a sibling key vs. folded into the `banks` blob) is a small
  build-time residual, but the manifest-now decision is firm.

## Precision / invariant implications

- **The single intentional exception to "no operation deletes files."** Stated
  above; called out again here so the invariant table is honest: prune is
  destructive-to-files *by design and by exclusive authority*.
- **Relative-paths-only / Save-As machinery reused** — prune resolves paths the
  same way the index does (M4), so it inherits relative-path correctness and
  Save-As survival; it introduces no new path handling.
- **Determinism / bit-identical / null-test (capture)** untouched — prune sits
  below the capture path entirely.
- **Prune null test (new invariant):** a prune of a folder whose every file is
  referenced by some bank deletes nothing; a prune deletes exactly the
  `present − referenced` orphan set and nothing else. Ship as a tested property of
  the pure core.

## Guardrails — the genuinely destructive act

- **Dry-run + confirm-with-manifest** (above): the user approves a *specific*
  deletion (count + size + files), never an abstract "clean up."
- **Never a referenced file; never a non-bank file.** The union-across-all-banks
  rule protects referenced files; the ownership-attribution rule (fork R-D)
  protects hand-dropped files.
- **Safest platform deletion available (fork R-C, SETTLED 2026-07-24 — trash-
  preferred, unlink fallback).** Route deletions to the platform recycle bin / trash
  wherever a portable move-to-trash is available (recoverable outside the app); fall
  back to unlink — behind the dry-run + confirm guardrail — only where the platform
  affords no portable trash. "Delete where possible" means recoverable-trash-
  preferred, never plain unlink-by-default. The move-to-trash surface is an explicit
  per-platform **to-verify** (see REAPER/platform API surface). (R3 verified: Windows
  `SHFileOperationW` + `FOF_ALLOWUNDO` confirmed against SDK 10.0.26100; macOS/Linux
  unlink fallback — no portable SWELL trash surface.)
- **Manual, explicit trigger (fork R-E, SETTLED 2026-07-24 — manual action + panel
  button).** Prune runs via a bindable manual action (dry-run-first, confirm-to-
  delete) **and** a `bank_panel` button that fires that same action — never a silent
  background sweep. The earlier optional "…and prune now at the delete-bank
  confirmation" convenience was **not** selected and is out of scope; a periodic
  background sweep remains rejected (silent irreversible file-deletion violates the
  guardrails).

> Build detail for this phase (module architecture, API surface) moved to CONTEXT-ARCHIVE.md.

## Non-goals / guardrails

- **Prune is the ONLY file-deletion authority.** No bank op, no capture op, no
  Design View op deletes a file. If any path other than prune deletes a bank file,
  reject it in review.
- **No general folder cleaning.** Prune reclaims the bank system's own unreferenced
  leavings, not arbitrary files a user placed in the folder (fork R-D governs the
  attribution).
- **No silent deletion.** Dry-run + explicit confirm always; no background sweep.
- **No file deleted while any index references it.** The referenced-set union
  across all banks is the safety-critical invariant — enforce and test it in the
  pure core, not just the UI.
- **Additive only.** Prune reads the book and the folder; it does not modify
  `BankIndex`, `bank_book`, the capture roadmap, or Design View semantics.

## Settled forks (Daniel, 2026-07-24)

- **Fork R-C — deletion mechanism.** Settled: **trash-preferred, unlink fallback.**
  Route to the OS trash where a portable move-to-trash is available (recoverable),
  else unlink behind the dry-run/confirm guardrail. Per-platform trash surface is a
  must-verify. Folded into Settled decisions + Guardrails + API surface above.
  Product notes §Fork R-C.
- **Fork R-D — orphan attribution.** Settled: **owned-file manifest**, `(owned ∩
  present) − referenced`; folder-sweep rejected as unsafe. The **seam lands early** —
  capture writes each created file to the manifest starting in Phase B, prune
  consumes it in Phase R. Persistence shape (sibling key vs. `banks` blob) is a
  build-time residual. Folded into Settled decisions + Module architecture + API
  surface above, and added as an up-front Phase B / capture plan point. Product
  notes §Fork R-D.
- **Fork R-E — trigger.** Settled: **manual action + `bank_panel` button**, dry-run-
  first, confirm-to-delete; no background sweep. The delete-time "…and prune now"
  convenience was not selected (out of scope). Folded into Guardrails + Module
  architecture above and the R3 plan points. Product notes §Fork R-E.

**Build-time residual (not a fork):** the owned-file manifest's exact persistence
shape (sibling `"reasampler"` ext-state key vs. folded into the `banks` blob).

---

# MIDI-playback instrument — additive phase spec (Phase S — Sampler)

> **New pillar, its own lettered phase, and — uniquely — its own build artifact.**
> Every prior phase (M / D / B / R / V) ships inside the one `reaper_reasampler`
> extension binary. Phase S does **not**: a REAPER extension *cannot* be a
> MIDI-triggered instrument (it is not a node in any track's signal chain), so the
> instrument is a **second, separate binary** — a native **VST3** plugin the user
> instantiates on an instrument track — that reads ReaSampler's banks and plays them
> MIDI-triggered. Namespaced **`S` (Sampler)** rather than "D" (which would collide
> with Design View). The `M`/`D`/`B`/`R`/`V` extension pillars are untouched. Product
> framing, the plugin-format reasoning, the bare-VST3-vs-JUCE assessment, and the
> settled decision record: `docs/product/midi-playback.md`. Same standing discipline:
> **verify every Steinberg VST3 SDK and REAPER/SWELL API name/signature against the
> vendored headers before use.**

## What it is

A native **VST3 sampler instrument** — a separate product/artifact from the
extension — that maps ReaSampler's captured bank samples across a MIDI keyboard and
plays them back with a real voice engine (polyphony, velocity, envelopes). The
extension stays the sole owner of **capture + organization**; the instrument is the
**playback surface**. The two are *tightly integrated but distinct acts*: the
extension captures and organizes; the instrument plays. Neither crosses into the
other's role — the instrument never captures, the extension never becomes an
instrument.

**Why a VST3 and not the extension (load-bearing, settled — see D1/D5/D6 below).** An
instrument track's "read live MIDI, emit audio per-voice, in REAPER's
routing/record/render path" contract belongs to VST/VST3/CLAP/JSFX plugins, hosted
through an entirely different mechanism than the extension API. The extension SDK's
audio-adjacent surfaces (`Audio_RegHardwareHook`, `kbd_OnMidiEvent`, `PlayPreview`,
`pcmsrc` subclassing) are each the wrong tool for a live-MIDI instrument — the full
reasoning is in `docs/product/midi-playback.md` §1. The instrument is therefore a
standard VST3 plugin; this is not an engineering-around-able limitation, it is what
the plugin *format* is.

## The three locked decisions this spec assumes

Settled by Daniel (2026-07-26); everything below assumes them. Reasoning preserved in
`docs/product/midi-playback.md` §4.

- **D1 — native VST3.** Not JSFX. Full sampler sophistication, clean integration, and
  access to the REAPER VST-host bridge. JSFX retired (cross-platform-for-free is
  worthless under D5, and JSFX gets no bridge).
- **D5 — Windows-only, VST3-only, REAPER-only.** No cross-platform DSP/build/signing
  matrix, no multi-format wrapper, no standalone-in-other-hosts concern. REAPER-coupling
  via the bridge is intended. This is the single biggest simplifier — it deletes most of
  what makes VST3 painful.
- **D6 — two products, tightly integrated.** A separate artifact, but **not** a
  divorced file-only companion: via the VST-host bridge it reads the live
  `"reasampler"` project ext-state and is project-aware.

## The VST-host bridge (the integration mechanism, stated once)

A VST3 *hosted inside REAPER* can call back into REAPER's own API by resolving
function pointers by name over the host callback
(`hostcb(&effect, 0xdeadbeef, 0xdeadf00d, 0, "FunctionName", 0.0)` — the same
string-keyed API table the extension uses; verified in `video_processor.h` and the
`reaper_plugin_functions.h` `GetProjExtState`/`SetProjExtState`/`EnumProjExtState`
entries). The plugin can also fetch its **host context** — the track/take/project it
was instantiated in (opcode `0xdeadf00e`). **Consequence:** the instrument reads the
*same* live `"reasampler"` ext-state that `persist` writes, follows the active
project, and needs no "point me at the bank folder" wiring — it asks REAPER which
project it is in. This capability exists *because* the plugin is hosted in REAPER; it
is the technical affordance D6 leaned on. **Must-verify before build:** confirm the
bridge opcodes and the by-name resolution against the vendored
`vendor/reaper-sdk/sdk/` headers (`reaper_plugin.h`, `video_processor.h`,
`reaper_plugin_functions.h`) — the framing doc's opcode citations are verified from
those headers but the exact call marshalling should be confirmed at the spike.

## The two seams (audio via files, mapping via live state)

- **File seam (audio, permanent).** The sample **audio** is the on-disk 32-bit-float
  WAVs — project-relative, travelling with the `.rpp` via the M4 machinery. The
  instrument resolves those paths **the same way `persist` does** (a shared convention,
  not a re-implementation). There is no live PCM stream across the bridge, by design.
- **Live-state seam (the mapping, via the bridge).** For everything that is *not* raw
  audio — the bank index, the mapping, which project is active — the instrument reads
  the live `"reasampler"` ext-state via the bridge. It sees what `persist` last wrote
  and follows the active project.

## The seam fields — what becomes a bank intrinsic (D-B, settled 2026-07-26)

**The split model (option iii) is the settled answer.** It mirrors the
capture/placement separation:

- **Bank intrinsics (facts about the captured file) live on `Sample`.** **Root note**
  (the MIDI note the sample was recorded at, so it can be repitched across the
  keyboard — distinct from the existing optional *musical key* field) and **loop
  points** (sustain-loop start/end for held notes; sample-accurate, zero-crossing-aware)
  are *facts about the file*, analogous to sample rate, length, and peaks. They are added
  to `Sample` as an **additive field extension** — the same shape as how `provenance`
  was added in M1: new optional fields with JSON round-trip, populated at/after capture,
  defaulting cleanly for pre-existing samples. This keeps the bank a clean,
  tool-agnostic library (WAVs + facts, readable by anything).
- **The performance map (a creative arrangement) lives in the instrument.** **Key
  zones** (low/high note per sample), **velocity layers**, **round-robin groups**,
  **amplitude envelopes** (ADSR), and per-sample tuning/gain trim are a *performance
  choice*, not a fact about a file — they belong to the instrument, not the bank. Under
  the live-state seam the instrument may still *read* performance-map data out of shared
  `"reasampler"` state, so "who owns which field" is a data-ownership decision, not a
  transport one.

**Why the intrinsic fields are added early (D-B, the backfill-cliff reasoning).** The
`Sample` field addition is scheduled as an **early Phase S point** even though the
instrument that consumes them lands later. Rationale (the *design-the-seam-even-if-you-
defer-the-feature* instinct, same as Fork R-D's owned-file manifest): if the fields are
added only when the instrument needs them, every sample captured before then lacks a
root note / loop points and must be backfilled by hand. Adding the fields now — so
capture starts populating them (or at least defaulting them cleanly) — costs almost
nothing and closes the cliff. The field addition touches the **extension** codebase
(`bank_model` + capture + persist), is independently shippable, and lands before the
instrument build leans on it.

## Scope tiers (D-C, settled 2026-07-26 — Tier 0–1 committed, Tier 2 held, Tier 3 optional-forever)

Tiers are minimal → sophisticated; **Tier 0 delivers the core promise** and each tier
above is optional depth, not a prerequisite for the one below.

- **Tier 0 — "the bank plays" (committed).** One sample mapped chromatically across
  the keyboard from its root note; basic polyphony; a simple amp envelope; velocity →
  volume. The honest MVP: point a bank sample at a MIDI track and play it repitched.
  On the native path this is the `SingleComponentEffect` skeleton plus a single-voice
  core, editor deferrable behind a parameters-only default view.
- **Tier 1 — "a keymap" (committed).** Multiple samples zoned across the keyboard (key
  ranges), each with its own root note — a captured *kit* or a *multisampled instrument*
  plays correctly. This is where the root-note + key-range seam fields earn their place.
  One sample per key-region.
- **Tier 2 — "expressive" (HELD — noted, not specified).** Velocity layers, round-robin
  (the anti-machine-gun feature), full ADSR, per-sample tuning/gain trim, sustain loops.
  Where it becomes a tool people reach for. **Explicitly a follow-on** — its points are
  not drawn up in this spec; it is recorded as the next depth increment once Tier 0–1
  proves the instrument belongs in ReaSampler's world.
- **Tier 3 — "instrument polish" (optional-forever).** Filters, filter/pitch envelopes,
  LFOs, per-voice pan, choke groups, a modest FX slot. A direction to leave room for,
  never a commitment. Do **not** let a Tier-3 feature list inflate the build-shape
  decisions.

## The build shape (D-A, settled 2026-07-26 — bare Steinberg VST3 SDK + LICE editor)

**Settled: bare Steinberg VST3 SDK, no JUCE, with the editor drawn in the same
LICE/SWELL stack `bank_panel` already uses.** Reasoning (full assessment in
`docs/product/midi-playback.md` §1a and §4 D-A):

- **The audio-processing scaffolding is bounded.** Using `SingleComponentEffect` (the
  SDK's combined processor+controller base — sanctioned for a non-distributable,
  REAPER-only plugin under D5/D6) plus the SDK's factory macros, a silent-but-loading
  VST3 instrument skeleton is order-of-magnitude a few-hundred lines of
  adapt-from-example ceremony, written once. The AGain / Note Expression Synth SDK
  examples are the copy-source. Not a tar pit.
- **D5 deletes JUCE's biggest justification.** JUCE exists largely for multi-format /
  cross-platform, both of which D5 removed. Its one genuine remaining pull is the editor
  UI — and ReaSampler is the atypical case where even that is weak, because it already
  has a working, docked, custom-drawn LICE UI (`bank_panel`) and a house style. Drawing
  the editor in a VST3 `IPlugView` that hosts a LICE surface reuses that muscle, keeps
  the look house-consistent, and avoids JUCE's AGPL-or-pay license posture (the Steinberg
  SDK is permissive, no revenue gate).
- **The one real edge — the `IPlugView`↔LICE bridge** (window lifecycle, sizing, event
  routing from the host into the draw/hit-test loop) — is *the same class of work*
  ReaSampler already did to dock `bank_panel`, not a new competence, but it is less
  trodden than dropping in a JUCE editor. It is therefore the phase's **opening spike**
  (below), which also converts §1a's experienced-estimates (Windows module-export
  symbol names, factory-macro spellings, exact bridge marshalling) into verified fact
  before the engine build leans on them. VSTGUI (the SDK's bundled toolkit) is the noted
  fallback rung *only if* the LICE bridge proves gnarlier than the panel work suggests;
  JUCE is the last resort behind that.

## The pure core (D3 — the load-bearing split, transplanted)

**The sampler's voice engine, envelope math, key/velocity mapping, repitch/interpolation,
and keymap resolution are a pure, REAPER-free, DAW-free, unit-tested module** — the
mirror of `bank_model` / `peaks` / `view_mode_model` / `bank_book`, tested in the CTest
harness outside any host. This is the heart of the phase; **test it hard.** The VST3
wrapper — the `SingleComponentEffect` subclass, bus setup, the `process` call
marshalling MIDI→core and core→audio-buffer, the `IPlugView` LICE editor, and the bridge
calls that read `"reasampler"` ext-state — is the **thin shell**, the only part that
touches VST3 or REAPER at all. Critically, this split is **invariant under the build-shape
choice**: whether the shell is bare-SDK or (hypothetically) JUCE, the pure core is
identical, REAPER-free, and tested the same way. The format choice is a shell choice; the
core is invariant.

> Build detail for this phase (module architecture, WDL API surface, build sequencing, the superseded S10 workflow hierarchy, Steinberg API surface, the S17 drop-and-load spec) moved to CONTEXT-ARCHIVE.md.

## Precision / invariant implications

- **The bank is one source; the instrument is another view of it (never a fork).** The
  instrument is a pure *consumer* of the bank — it does not copy samples, does not own a
  private sample store, and does not mutate the bank. The bank stays the single
  authoritative artifact (the one-source-multiple-views instinct). Any instrument path
  that writes back into the bank or keeps its own sample copies is a bug.
- **Capture/placement/playback stay distinct acts.** The instrument reads and plays; it
  never captures and never inserts into the arrange. The capture load-bearing principle
  is untouched — Phase S adds a *third* distinct act (playback) without weakening the
  capture↔placement separation.
- **`Sample` field addition is additive and lossless.** Root note + loop points are new
  optional fields with JSON round-trip, defaulting cleanly for samples captured before
  the addition — the same additive, backward-compatible shape as `provenance` (M1). No
  existing `Sample` field changes; no `BankIndex` behavior changes.
- **Relative-paths-only survives.** The instrument resolves audio via the M4
  project-relative machinery; it introduces no absolute paths.

## Embedded TCP/MCP UI (D-D, settled 2026-07-26 — SCHEDULED as a later Phase S point)

A REAPER-hosted VST3 can draw its own UI **inline in the track/mixer control panel**
via `reaper_plugin_fx_embed.h` (the plugin implements `IReaperUIEmbedInterface`; the
same Cockos surface REAPER's own embedded FX use). A ReaSampler instrument can render a
compact keymap/level strip inline in the TCP/MCP, not only in its own window. Because
this uses the **same LICE-class drawing as the D-A editor path**, it composes naturally
with the bare-SDK-plus-LICE build — the groundwork is the groundwork.

**Settled: scheduled, not deferred.** This is a real, in-phase later point — it lands
**after** the main `IPlugView` editor exists (it composes with that LICE path), not a
someday-note. It is polish, not a Tier-0 need, so it sequences last in the phase; but it
is on the roadmap. **Must-verify before build:** the `IReaperUIEmbedInterface` contract
and embed message/lifecycle against `vendor/reaper-sdk/sdk/reaper_plugin_fx_embed.h`.

## Channel mode — mono | stereo (D-E, decided 2026-07-26; PLAN.md S7)

**Decided direction: the instrument gets a per-instance channel-mode toggle — 1 (mono) or
2 (stereo) — that negotiates the REAPER audio bus automatically.** Captures are often
stereo; the current mono downmix is a Tier-0 simplification, not a permanent shape.

- **Mono mode keeps today's path.** The decode-side downmix stands: a stereo source in
  mono mode downmixes (the existing policy), a mono source plays as-is. No engine change
  for mono.
- **Stereo mode is an S3-core extension, not a shell hack (honest).** The S3 core is
  **mono-per-sample by design today** — `SampleData::frames` is one mono stream,
  `Voice::renderFrame` returns a single value, `VoiceEngine::render` writes one channel.
  Stereo mode grows the core a **channel dimension**: 2-channel decoded PCM, per-voice
  **stereo** render (per-channel fractional read + linear interpolation + loop), and a
  per-channel mix in the engine. Mono stays the degenerate (single-channel) case, so
  existing mono behavior is unchanged. This is why S7 sequences first after the editor/embed
  work: it touches the engine Daniel smoke-tests.
- **Where the toggle lives.** Per-instance component state (setState/getState), alongside
  the selected sample — a **performance choice the instrument owns**, never written to the
  bank (D-B: not a file fact). Default preserves current behavior (mono).
- **Cross-mode policy (settled).** Mono source + stereo mode → **dual-mono** (same signal
  both channels, centered). Stereo source + mono mode → **downmix** (the existing
  decode-side policy). The bank's per-sample channel-count intrinsic (already on `Sample`)
  tells the shell how many channels to decode into `SampleData`.
- **Bus negotiation (the "works with the REAPER bus automatically" requirement).** The VST3
  implements `setBusArrangements` so the output bus reports mono or stereo per the
  instance's channel mode, and REAPER's routing follows without manual channel wiring.
  **Must-verify before build:** the `setBusArrangements` / `getBusArrangement` contract and
  REAPER's mono/stereo instrument-bus expectations against the vendored Steinberg SDK +
  `reaper_vst3_interfaces.h`.

## Sampling modes — Trigger vs Gate + pitch envelope (S15/S16; core + editor)

**Daniel's directive (2026-07-26, verbatim):** *"Sampling mode: Trigger vs Gate. Gate has
an AHDSR envelope. Trigger has fade in, % length, and fade out. Both modes have modifiable
start point, Gate has modifiable loop points too. In addition to amp env, there will be a
pitch envelope/curve (AD?) which is off by default."* The feature set is **settled**; two
forks (S15-F1 choke, S15-F2 param granularity) are flagged with leans below.

**Daniel's S16 correction (2026-07-26, verbatim):** *"isn't that ratio stuff going to change
the playback rate? I want duration-preserving repitching."* Correct — the `readPos_ += ratio_`
path is **varispeed** (pitch and duration coupled). S16 is revised from "pitch envelope only"
into a **pitch-engine mode (Varispeed vs Preserve) + pitch envelope** (see §Pitch engine
modes below). Two new S16 forks are flagged: **S16-F1** (the engine default — lean Preserve)
and **S16-F2** (the Preserve implementation — lean `WDL_SimplePitchShifter` first, hand-rolled
held). The prior WDL finding that dismissed `WDL_SimplePitchShifter` is **corrected in place**
below (duration-preserving is now the requirement, so that shifter is the Preserve candidate).

### Play mode — Gate vs Trigger (S15)

Each played sample carries a **play mode** — a per-sample/per-zone **performance choice**
(D-B, instrument-owned, never a bank fact). Two modes, precisely:

- **Gate — classic held note (grows the current path).** Note-on enters the amp envelope;
  note-off enters release; a **sustain loop** applies for held notes (S11's draggable loop
  markers are Gate-mode UI). The current core envelope is **ADSR**; Gate adds a **Hold**
  stage → **AHDSR**: `0→1` over attack, **hold at 1** over `holdFrames`, `1→sustain` over
  decay, hold sustain until note-off, `level→0` over release. **`holdFrames == 0` is
  exactly today's ADSR** — a back-compat degenerate, no behavior change for existing Gate
  play. Segment math is the existing linear-ramp idiom (`AdsrEnvelope::tick`) with one new
  stage inserted between Attack and Decay.
- **Trigger — one-shot drum-pad.** Note-on fires playback of a defined **% of sample
  length** with a **fade-in** and **fade-out** ramp; **note-off is ignored** (the voice
  plays through); **no sustain loop**. Envelope math (distinct from AHDSR): play the frame
  span `[startFrame, playEnd)` where `playEnd = startFrame + round(lengthFraction·(frames −
  startFrame))`, `lengthFraction ∈ (0,1]`; amplitude ramps `0→1` over `fadeInFrames`
  (fade-in) at the head and `1→0` over `fadeOutFrames` anchored to `playEnd` (fade-out),
  unity between; fades clamp so `fadeInFrames + fadeOutFrames ≤ play length`. The voice
  frees when `readPos_ ≥ playEnd` (mirror of the current run-off-end idle). **Fade curve
  default: equal-power** (constant-power `sin`/`cos` — click-free on one-shots); linear is a
  build-time residual. **Note-off in Trigger is a no-op** (choke is held — fork S15-F1).

**Both modes: modifiable start point.** Playback begins at `startFrame` (a frame offset into
the sample, clamped `0 ≤ startFrame < frames`), not always frame 0. This is the voice's
initial `readPos_`; the existing per-frame `readPos_ += ratio_` read and linear-interp/loop
machinery are otherwise unchanged. Gate additionally has **modifiable loop points** (already
the S2 loop intrinsic + S11 override); Trigger has none (it is a one-shot).

**Voice-stealing interaction (unchanged).** The S3 stealing policy (oldest-in-release, else
oldest-overall) is mode-agnostic — a Trigger one-shot is a normal active voice until it runs
off `playEnd`; it can be stolen like any voice. No new stealing rule.

**Confirmed from the core (`sampler_core.cpp`):** the read loop advances `readPos_` by an
arbitrary `ratio_` per frame with 2-point linear interpolation, and the amp is a per-frame
`env_.tick()` multiply — so both the AHDSR hold stage and the Trigger fade/%-length envelope
are **per-frame amplitude functions** over the existing read machinery, and the start point
is just a non-zero initial `readPos_`. No resampler or voice-lifecycle rewrite is needed.

**Parameter ownership (D-B).** The play mode + its params (Gate: AHDSR; Trigger: %-length +
fade-in + fade-out; both: start point) attach to the **capture selection / zone** and live
in the instrument's **performance map** (component state, version-bumped, back-compat: a
truncated/older blob defaults to **Gate, hold=0, start=0, no fades = exactly today**). Start
point joins `rootOverride` / loop-override as another per-`PerformanceZone` optional
override; a per-zone `PlayMode` + param struct is added additively. **Fork S15-F2 (flagged):**
per-capture-selection *and* per-zone, or per-zone only with the single-capture case as a
one-zone map? **Lean: per-zone only** — the single capture is already a one-zone map
(S10-Z's back-compat lift), so one storage site serves both; flagged because it touches
S10's single-capture setup surface shape.

**Editor (mode-aware, on the S11 waveform surface).** Gate shows draggable **start + loop
markers**; Trigger shows **start + %-length end + fade-in/out** handles — same waveform, same
pure `frame↔pixel` + marker-grab geometry module (S11), mode switches which markers draw. A
**mode toggle** per capture/zone sits in the S10 guided setup / S10-Z Zones panel. Every edit
commits **off-thread** via `commitAndReload`; the instrument stays a **read-only bank
consumer** (mode/params are performance map, never written to `Sample` or the bank).

### Pitch engine modes — Varispeed vs Preserve (S16)

**Daniel's correction (2026-07-26, verbatim):** *"isn't that ratio stuff going to change the
playback rate? I want duration-preserving repitching."* Correct: the `readPos_ += ratio_`
resampling path is **Varispeed** — pitch and duration are coupled (an octave up halves the
note's duration). Daniel wants **duration-preserving** repitch. So S16 grows a per-voice/
per-zone **pitch-engine mode**, not just a pitch envelope:

- **Varispeed engine (current path).** `ratio_ = pitchRatio(note,root)`, `readPos_ += ratio_`
  with 2-point linear interp — resampling that couples pitch and duration. This is the
  **classic sampler / RS5K** behavior and today's shipped S3/S5 output. Cheap, zero-latency.
  Musically right for **drums / one-shots** (pitch-down-lengthens-the-hit is a feature there).
- **Preserve engine (duration-preserving).** The read advances at the **source** rate
  (duration held) while a **pitch shifter** transposes the output by `2^((note−root)/12)`.
  Musically right for **tempo-locked loops and phrases** — a transposed loop still lines up to
  the bar. Since captured banks are project slices (loop/phrase-heavy), this is the default
  lean (fork S16-F1).

Mode is **per-`PerformanceZone` performance state (D-B)** — instrument-owned, never a bank
fact — additive/version-bumped (absent/older blob → the S16-F1 default). A per-zone
**Varispeed/Preserve toggle** surfaces in the S10 guided setup / S10-Z Zones panel.

**Preserve engine implementation (fork S16-F2).** Two RT-disciplined routes behind the
`PitchEngine::Preserve` seam (identical contract either way):
- **(a) `WDL_SimplePitchShifter`** (`vendor/WDL/WDL/simple_pitchshift.h`) — a per-voice
  time-domain OLA shifter. Under the duration-preserving directive this is **the right
  category** (see the corrected WDL finding below). `set_shift(2^(semi/12))` for pitch,
  `set_tempo(1.0)` to hold duration — pitch and duration are separately controllable. **Lean:
  route (a) first** (low-cost proof), with two costs owned in the build: an inherent
  **onset latency** (~half-window, ~25 ms @ the 50 ms quality-0 window; pre-warm at voice-
  allocation, and it lands on sustained/loop material where least harmful) and a **queue-growth
  allocation** hazard in `BufferDone` (`WDL_Queue::Add`) that is settled by a silence pre-warm
  at voice-allocation so no `process`-thread allocation occurs in steady state.
- **(b) hand-rolled pure `pitch_shift` OLA/granular module** (house pattern — CTest-testable,
  no REAPER/VST3/WDL type at the boundary) — **held** as the quality/latency upgrade if the
  SimpleWindowed warble or onset lag proves musically unacceptable.

**`WDL_Resampler` is not a Preserve engine** — it is a *resampler* (couples duration); it
remains a held **Varispeed-quality** upgrade only. **elastique is NOT available** (licensed
zplane, not vendored — restated). JUCE / rubberband / signalsmith are **new-dependency forks
carrying D-A weight** (bare-VST3-no-framework is the locked D-A) — **not proposed**.

**S15 × S16 interaction (Preserve consumes S15's source-frame read).** S15's amplitude
semantics are defined over the voice's **source-frame** timeline; the Preserve engine wraps
that read and transposes the output, so:
- **Trigger %-length** stays a source-frame fact (`playEnd = start + round(lengthFraction·
  (frames − start))`); under Preserve its **wall-clock is stable under transpose** — *cleaner*
  than Varispeed, where transposing a Trigger also scales its audible length.
- **Gate sustain loop** — under Preserve, **loop the source read** (the `[loopStart, loopEnd)`
  source-frame region) and feed the looped stream into the shifter, which transposes the
  **output**. Contract: *loop the source, shift the output*; loop points stay source-frame
  facts (S11 markers unchanged). Under Varispeed the loop read itself carries the pitch.
- **Start point** is a source-frame offset in both engines (engine-independent).

### Pitch envelope — AD, off by default, engine-aware (S16)

A per-voice **pitch modulation curve** riding on top of whichever engine — a short **AD**
(attack-decay) envelope that biases pitch over time. **Off by default** (so existing playback
is bit-identical under the same engine). The classic use is a percussive **pitch drop**.

- **Shape (lean, build-time residual): two-segment AD** — at note-on the pitch offset rises
  to `peakSemitones` over `attackFrames`, then falls to 0 (base pitch) over `decayFrames`.
  A **zero attack** gives the pure "start high, drop to base" percussive drop.
- **Range: semitones (±).** `peakSemitones` is signed; default depth range noted at build.
- **Applied per engine.** Under **Varispeed** the offset is a **per-frame multiply of
  `ratio_`** by `2^(pitchEnvSemitones(frame)/12)` (the effective read increment varies frame-
  by-frame at no structural cost — the same per-frame `tick()` idiom as the amp envelope,
  RT-safe, no `process` allocation). Under **Preserve** the offset is **added to the shifter's
  shift amount** — `set_shift(2^((note−root + pitchEnvSemitones(frame))/12))` — bending pitch
  without touching duration. Per-voice (polyphonic notes each run their own).
- **Ownership + editor.** Per-zone instrument performance-map state (D-B), additive/version-
  bumped (absent → disabled). Editor exposure folds into the S12 ADSR-editor tier: attack +
  decay + a ±semitone depth control, default-off (discoverable but inert until enabled).

## Ingest through the bank — the extension owns ingest (decided "option 1", 2026-07-26; PLAN.md S8)

**Decided: loading a sample into the sampler is ONE gesture — capture/import-into-bank AND
auto-assign to the active sampler instance — and the *extension* owns it.** The instrument
stays a **read-only bank consumer**; it never captures and never imports. The extension is
the right owner: it has arrange access, Media-Explorer access, and the drop-target surface
on its own docked panels. Ingest lives in the *extension* codebase (actions + `bank_panel` +
capture/import add-path), routing through the existing capture add-path and the live
`"reasampler"` seam the instrument already reads.

**The three ingest surfaces, with the honest SDK reality (verified against the vendored
headers):**

- **Arrange capture → bank → assign.** A one-click action captures the selected item /
  time-selection into the bank (reusing the existing capture request path —
  `CountSelectedMediaItems` / `GetSelectedMediaItem` + `GetSet_LoopTimeRange` are already the
  capture inputs) and assigns the resulting `Sample` id to the target instance. **It never
  inserts a timeline item** — the capture/placement separation is load-bearing; assignment
  is a bank-index + instance-selection act, not a placement.
- **Media Explorer import → bank → instrument on selected track.** The Media-Explorer surface is **thin**:
  `OpenMediaExplorer` (open/select a file) and `MediaExplorerGetLastPlayedFileInfo` (read the
  *one* last-played/selected file path + its selection range/pitch/vol/rate) are the whole
  contract. There is **no** enumerate-selected-files and **no** register-a-drop-handler-on-
  the-Media-Explorer API. So ME import is **single-file, pull-on-action** — an action fired
  while a file is selected in the ME — not a push/drop from inside the ME. **Shipped behavior:**
  after importing the file into the active bank, the action adds a ReaSampler 9000 instrument to
  the user's **currently selected track** via `loadInstrumentOntoTrack` in `instrument_drop_win`
  — no new track is created and no routing is changed ("new sound, existing track"). If no track
  is selected the sound still lands in the bank but no instrument is placed and a console message
  explains why. No `assignment_request` is written; it never touches a live instance's selection.
  Undo-wrapped: persist + FX-add + inject = one Ctrl-Z.
- **Drag-and-drop onto ReaSampler surfaces.** REAPER exposes **no** drag-drop registration
  API. Drop handling is on ReaSampler's *own* HWNDs via SWELL/Win32 (`WM_DROPFILES` /
  `IDropTarget` on the docked `bank_panel` HWND — the surface the panel already owns) → ingest
  (bank-fill only). Dropped files are imported into the active bank; no `assignment_request` is
  written and no live instance's selection is affected. The bank-generation bump is retained so
  open instances' browsers refresh to show newly available sounds. **Assess-and-flag (spike,
  not promised):** a drop *onto the VST3 editor window* — whether the `IPlugView` HWND can
  accept an OS file drop and **relay it to the extension as a bank-ingest request** (the
  instrument does not ingest; it forwards a request over an agreed seam). This crosses the
  two-artifact boundary and the relay is unproven; if gnarly, drop-onto-panel is the shipped
  path and drop-onto-editor is deferred.

**The assign seam.** The ingest action names the target instance (lean: the active/
last-focused instance, discovered via the host context the bridge already resolves) and hands
it the new sample id — the same instance-owned selection state S4 already persists, so a
reload picks it up. With the change-detection seam (below) the assignment refreshes
hands-free; without it the ingest action pokes the target instance's reload directly.

**Guardrail (load-bearing, restated):** ingest is an *extension* act. Any instrument code
path that captures, imports, inserts a timeline item, or writes back into the bank is a bug —
the instrument reads and plays only.

## Bank-generation change-detection — hands-free refresh (decided 2026-07-26; PLAN.md S9)

Instances reference sample **ids**. So a **recapture** (M10) landing under the same id — or
an **ingest** (S8) touching the active bank — should refresh playing instances **hands-free**,
without re-opening each editor. The missing trigger: a **bank-generation counter** in
`"reasampler"` ext-state.

- **Writer (extension).** A monotonic **bank-generation counter**, stamped into
  `"reasampler"` ext-state under a new forever-stable `ext_keys.h` constant, bumped on every
  bank-content mutation that changes what an instance would play (capture add, recapture-in-
  place, sample-remove, move/copy affecting the active bank). Additive to the persist blob;
  defaults to 0 for projects saved before the stamp exists.
- **Reader (instrument).** Poll the generation over the bridge on a safe **off-audio-thread
  cadence** (a UI/timer tick, **never** `process`), compare to the last-seen value, and call
  the existing off-thread `reloadInstrument()` on change — reusing S4's atomic pointer-swap
  handoff (graveyard-reclaim) so a mid-play refresh does not glitch. No new audio-thread work;
  no allocation in `process`.
- **Cadence + safety.** A low-frequency UI timer, coalescing multiple bumps between polls into
  one reload (build-time residual). The read already tolerates a stale value by design (it
  reloads on the *next* poll). **Must-verify before build:** no torn-read hazard on the single
  integer generation key for a bridge read on the instrument's UI/timer thread concurrent with
  an extension write.

This seam serves **both** S8 ingest and M10 recapture; the writer side is extension-only and
independent of S8, so it can land alongside either.

## Design-system foundation — moved to Phase L (2026-07-26)

> **The visual design language moved out of Phase S into its own Phase L.** The
> design-system content that stood here (the toolkit assessment, the shared LICE drawing
> kit **S0-DS**, and the dock-panel refresh **S14**) has been lifted into **Phase L**
> (Look-and-feel) on `dev`, taken up by a parallel team so Phase S feature work proceeds
> ungated. S0-DS is now **Phase L point L1** (the shared kit); S14 is now **L2** — and,
> per Daniel's DS-3 call, expanded from a light re-skin into a **thorough dock-panel layout
> redesign** that lays out the full M11-aware button inventory before applying the kit; the
> VST editor + embed-strip restyle is now the explicit **L3** point (gated on Phase S
> landing on dev). The design-system forks DS-1 (LICE + WDL free game, no external
> frameworks), DS-2 (Direction B "Neon Console" + Direction C's spectral keyboard strip),
> and DS-3 (thorough panel layout redesign) are all **SETTLED (Daniel, 2026-07-26)**.
>
> **Authoritative from here:** **PLAN.md §Phase L + CONTEXT.md §Phase L on `dev`**, and
> `docs/product/visual-design-language.md` (on `dev`). Phase S's **S10–S13 build their
> interaction UX with the current drawing and adopt the Phase L kit when it lands — they
> are not gated on Phase L.** LICE/SWELL-only, the pure-geometry-module discipline, RT
> discipline, and the read-only-over-bank / VST3-class-UID-unchanged guardrails all hold
> exactly as before — a visual refresh is not a data-ownership or compat event.

## Product name — ReaSampler 9000 (Daniel, 2026-07-26)

The MIDI-playback instrument's product name is **ReaSampler 9000**. The extension stays
**ReaSampler** (capture + organization); the instrument is **ReaSampler 9000** (playback).
Set by Daniel on DAW-testing the S1–S6 instrument, alongside the UX-overhaul directive.

- **Propagate the display name** across user-visible surfaces: the VST3 class **display
  name** string in the factory registration, the **factory vendor/name strings**, the
  `IPlugView` editor **title band** (currently "ReaSampler Instrument"), the **S6 embed-strip
  label**, and the Phase S docs.
- **Do NOT change the VST3 class UID.** Instances in already-saved projects key off the
  class UID; changing it orphans every existing instance in every saved project. The UID is
  a forever-stable contract (mirror of the command-id / ext-state-namespace forever-stable
  strings).
- **S-NAME-1 SETTLED (Daniel, 2026-07-26): rename the binary filename too.** The on-disk
  module name is renamed to match the product (e.g. `reasampler_9000.vst3`), not just the
  display strings. Full rename surface: **CMake `OUTPUT_NAME`** on the second VST3 target,
  the **factory vendor/name strings**, the **editor title**, and the **embed label**. The
  **class UID stays locked** as the compat anchor.
- **Compat verification (must-DAW-verify before shipping the rename).** The working
  assumption is that REAPER **rebinds a saved instance by its VST3 class UID, not by the
  module filename** — so a filename rename with an unchanged UID keeps saved projects working.
  **This is a to-verify assumption, not a confirmed fact:** a web check surfaced a
  JUCE/VST3-replace-VST2 case suggesting REAPER's binding can be more nuanced than "UID only"
  (an FXID match is involved), so it is not safe to assert UID-only rebinding from source.
  **DAW-verify:** save a project with an instance under the old filename, rename the module,
  reopen, and confirm the instance rebinds and restores its state. If REAPER keys partly on
  filename, fall back to keeping the current filename (display-strings-only) and record that
  as the shipped choice.

## VST3 channel identity — the UID pair + the pairing surface (S18; extends Phase V V4)

**Decided (Daniel, 2026-07-26):** the beta/stable channel split Phase V V4 gave the
*extension* extends to the **ReaSampler 9000 VST3 instrument** — a beta-built VST pairs with
the beta extension only, a stable VST with stable only, both installable side-by-side in one
REAPER. This is the instrument-side companion to V4 and mirrors its philosophy exactly:
**one channel per binary; all channel identity derives from the ONE
`REASAMPLER_CHANNEL_IS_BETA` bit via the pure `app_version` module — no scattered `#ifdef`s
in the VST shell.**

**What is already isolated (structural, not added by S18).** The wire/data pairing is
already done and needs no per-key work: `ext_keys.h`'s `kProjExtNamespace()` delegates to
`app_version::extStateNamespace()`, so a beta-compiled VST's bridge reads `"reasampler_beta"`.
Every wire key — `banks`, `assign_request`, S9's bank-generation key (in-flight), S17's
component-state contract, and **any future key** — is a plain constant *under* that
namespace, so channel data-isolation is **structural: no per-key opt-in, and a future key
that forgets to isolate is impossible by construction** (it keys off the namespace accessor,
not a raw literal). What S18 adds is only the missing *plugin identity* layer.

- **The UID-pair invariant (the permanent commitment).** The VST3 class UID is the plugin's
  identity — a saved REAPER project records it and rebinds a saved instance by it. Today
  `reasampler_vst.h` holds **one** forever-locked UID (`kReaSamplerProcessorUID`,
  `REASAMPLER_PROC_UID_1..4`, S-NAME-1). A beta VST with the **same** UID cannot coexist with
  stable in one install (same UID = identity collision / arbitrary rebind). So beta needs its
  **own** forever-stable UID: a second constant, minted once, locked exactly as the first.
  **Invariant: BOTH UIDs are frozen forever once shipped; the channel bit selects which is
  compiled into this binary** (one `DEF_CLASS2`, one class per binary — not both classes in
  one binary; that mirrors V4's fully-isolated-binary philosophy and keeps a beta build from
  ever presenting the stable identity). Saved-project isolation follows directly: a project
  saved with beta instances rebinds only to the beta VST; a stable-saved instance opened
  where only the beta extension has banks resolves the stable UID and shows a clean empty
  "pick a capture" state (S10 policy), not an error.
- **Binary + display identity, channel-derived.** Mirror the extension's `OUTPUT_NAME` fork
  (`reaper_reasampler` / `reaper_reasampler_beta`): the VST3 module's on-disk name forks
  `reasampler_9000` / `reasampler_9000_beta`, its factory display name "ReaSampler 9000" /
  "ReaSampler 9000 beta", and its editor title band + S6 embed-strip label are channel-aware
  — **all sourced from `app_version` channel accessors (a VST-name accessor beside
  `binaryName()`/`dockTitle()`), never a literal in `reasampler_vst.h`/`vst_entry.cpp`.** The
  factory version string carries the `-beta` render where V4's `appVersion()` already does;
  vendor/url/email stay shared unless V4 qualified the equivalent (V4 kept the lane-name
  prefix shared — shared-where-V4-shares is the default).
- **The complete pairing surface (the guarantee to state, not new code).** A channel's VST
  talks to that channel's extension **only**, because (1) plugin identity — UID + filename +
  display — is channel-forked (above), and (2) **all** wire keys live under the
  channel-derived `kProjExtNamespace()`. The two together make pairing complete and
  structural: identity keeps the *plugins* distinct; the namespace keeps the *data* distinct.
  No per-key or per-seam isolation work is ever needed — S8's assignment key, S9's generation
  key, and S17's blob-injection key all inherit it. **Verify all identity/factory wiring
  against the vendored Steinberg SDK** (`DEF_CLASS2` / `INLINE_UID` / `FUID` from
  `pluginfactory.h` + `funknown.h`); the pure `app_version` name accessors are CTest-tested.
- **Fork S18-F1 (flagged — Daniel's call): mint the beta UID now vs. at first beta release.**
  Lean **mint now** — mirrors the stable UID (minted at the S1 spike, locked long before
  ship), removes a "remember to mint before shipping beta" landmine, zero cost for an
  unused-until-beta constant. The alternative (a locked-once placeholder replaced before the
  first beta VST ships) defers the commitment but adds a release-gate step. Flagged only
  because the UID is a forever commitment.

## Non-goals / guardrails

- **The instrument never captures and never inserts into the arrange.** Playback is a
  read-only act over the bank. Any instrument path that captures, places a timeline item,
  or writes back into the bank is a bug — reject in review.
- **The instrument keeps no private copy of the samples.** It consumes the one
  authoritative bank; per-instance sample stores are a non-goal (they refork the source
  the one-source-multiple-views instinct keeps single).
- **The instrument never ingests (S8).** Capture, import, and drop-ingest are *extension*
  acts; the instrument only reads and plays. A drop onto the editor window (if the spike
  proves it viable) is *relayed to the extension* as an ingest request — the instrument
  never writes the bank itself.
- **Channel mode is a performance choice, not a bank fact (S7).** The mono/stereo toggle is
  per-instance component state, never written to `Sample` or the bank (D-B). The bank's
  per-sample channel-count intrinsic is a *file fact*; the play mode is the instrument's.
- **No cross-platform / multi-format.** Windows-only, VST3-only, REAPER-only (D5). Do
  not add an AU/AAX/VST2/CLAP wrapper, a mac/Linux build, or a standalone host target.
- **The pure core stays REAPER-free *and* VST3-free.** The voice engine / envelope /
  keymap / repitch module takes no VST3 or REAPER type at its boundary — the shell
  marshals. Any VST3 or REAPER type leaking into the core is a bug (the D3 split).
- **Additive to the extension.** The `Sample` intrinsic-field addition is additive
  (new optional fields; no existing field or `BankIndex` behavior changes); everything
  else in Phase S lives in the *second* artifact and does not alter the extension's
  M/D/B/R/V pillars.
- **Do not spec Tier 2/3.** Tier 2 is held (noted, not specified); Tier 3 is
  optional-forever. Do not let their feature lists drive Tier 0–1's build shape. **Note:**
  S7 stereo is *not* a Tier-2 feature — it is a channel-count dimension on the existing
  Tier 0–1 engine, orthogonal to Tier 2's velocity-layers / round-robin / per-sample trim.
  (S7's stereo loop read is the same loop the core already has, extended per-channel — not
  the Tier-2 "sustain loops" feature.) **Likewise S15/S16** (Trigger/Gate modes + pitch
  envelope) are Daniel-directed engine features on the Tier 0–1 core, *not* Tier 2/3 — the
  AHDSR hold, Trigger one-shot, start point, and AD pitch envelope are orthogonal amplitude-
  shape / read-rate dimensions, not the held velocity-layers / round-robin / filter work.
- **S15/S16 params are performance choices, not bank facts.** Play mode, start point,
  %-length, fades, AHDSR, and the pitch envelope are per-instance performance-map state
  (component state), never written to `Sample` or the bank (D-B). The bank carries file
  facts (root note, loop intrinsic, channel count); the instrument owns how they are played.
- **S15/S16 stay channel-count-agnostic (S7 interplay).** The mode/envelope logic is
  per-frame amplitude and read-rate, independent of the S7 channel dimension. Any S15/S16
  code that assumes a fixed channel count (mono) — rather than operating per-frame pre-mix —
  is a bug that would collide with S7. Spec and build them channel-agnostic.
- **Trigger ignores note-off; choke is out of scope (S15).** In Trigger mode note-off is a
  no-op and the one-shot plays to `playEnd`. Choke-on-note-off / choke-groups are held
  (fork S15-F1, Tier-3-adjacent) — do not add a choke path in S15.
- **Pitch envelope is off by default (S16).** Default-disabled → offset always 0 → the
  engine's un-modulated output → playback bit-identical to the same engine pre-envelope. A
  regression that applies pitch modulation when the envelope is off is a bug.
- **Pitch engine is a per-zone performance choice, not a bank fact (S16).** Varispeed vs
  Preserve is per-`PerformanceZone` component state (D-B), never written to `Sample` or the
  bank. The engine default is fork S16-F1 (**lean Preserve** — Daniel's call), with a
  prominent per-zone toggle so drum/one-shot zones opt into Varispeed cheaply.
- **Preserve engine is RT-disciplined (S16).** The `WDL_SimplePitchShifter` (or hand-rolled)
  Preserve path **pre-warms at voice-allocation** and does **no allocation in `process`** — a
  `WDL_Queue::Add` or `Resize` on the audio thread in steady state is a bug. Preserve's onset
  latency (shifter window) is an accepted property, **not** a defect; a note-onset **click or
  smear** from a cold-started (un-pre-warmed) shifter **is** a bug.
- **`WDL_Resampler` is not a Preserve engine (S16).** It is a resampler (couples duration) —
  a held Varispeed-quality option only. Do not wire it as the duration-preserving path.
- **Drop-and-load must not regress the two existing drags.** S17 inserts a new middle case
  (`InstrumentDrop`) between the M11 OS drag-out and the internal bank-to-bank drag; both
  existing gestures stay byte-for-byte unchanged in their own regions. Drop-and-load never
  inserts a media item into the arrange and never copies sample bytes into the instance —
  it hands the new instance a *reference* to an already-captured bank sample.
- **Verify Steinberg SDK, bridge, embed, and LICE-view surfaces** against the vendored
  headers before use — several §1a claims are experienced estimates until the spike
  confirms them.

## Editor view-model redesign — three views: Sample / Browse / Zone (S-VIEW; Daniel, 2026-07-27, r9)

> **Additive sub-phase of Phase S — an *editor* redesign, not an engine change.** Re-partitions
> the ReaSampler 9000 editor from today's two-view toggle (Browser + Zones) into a **three-view
> model where the loaded sample is the home**, adds three new performance parameters (key-tracking,
> preview velocity, and the r10 velocity→amp transfer curve) and three visual components (envelope
> overlay, real piano-key pattern, and the r10 velocity-curve editor), and
> frames two engineering prerequisites (drop-to-FX bug, default window size). The S3 voice
> engine, keymap resolution, and read-only-over-bank contract are **unchanged**; the
> component-state format extends additively (key-tracking + the r10 velocity curve on the
> zones-payload axis, preview velocity on the envelope axis). Product framing: `docs/product/
> midi-playback.md` §Addendum r9 + r10. Same standing discipline: **LICE/SWELL drawing only,
> all layout/hit-test in pure geometry modules, RT-safe, VST3 class UID unchanged, verify every
> API name/signature against the vendored headers before use.**

### The view model — Sample is home; Browse is modal; Zone is a dedicated surface

The three views are **not a flat three-way toggle** (today's Browser|Zones segmented switch is
retired). The model is **document-with-modal-picker** (mirror: Ableton Simpler — the device face
*is* the loaded sample; loading a new one is a distinct act):

- **Sample (the home / default face).** What the editor shows on open with a capture loaded. The
  hero waveform, the envelope overlay, all per-sample tuning controls, the preview-trigger. This
  is where the user lives.
- **Browse (a modal page layered over Sample).** Summoned by a **Browse button** (and, when
  nothing is loaded, the empty-state's primary affordance — Browse must be *very* easy to open
  when there is no capture selected). It renders as a **full-window overlay** over the Sample
  face — filters + captures grid + **select-then-confirm** to change the loaded sample, then
  dismisses back to Sample. It is a picker sheet, not a peer tab.
- **Zone (a dedicated editing surface).** Opened by its own **Zone button** when the user wants
  to map the capture(s) across the keyboard. Not shown by default ("most of the time zones won't
  be used" — the S10 reframe). Returns to Sample on close.

**Navigation contract.** From Sample: a Browse button opens the Browse overlay; a Zone button
opens the Zone surface. From Browse: select a card + confirm (or cancel) returns to Sample with
(or without) a new loaded capture. From Zone: a close/back affordance returns to Sample. The
empty state (no capture loaded) surfaces Browse as its dominant call-to-action. **The fresh
instance stays silent with a "pick a capture" empty state (S10 reversal, unchanged).**

### View 1 — Sample (the new main view)

The home face. Composition follows the reference devices (Simpler / Phase Plant): a **hero
waveform up top with the envelope drawn over it at accurate time**, a **dense labelled
value-strip beneath**, **root fenced as its own affordance**, and a **preview cluster**. Bands,
top to bottom:

- **Title band.** Plugin name (channel-derived `vstPluginName()`) + live readout (loaded capture
  name / `[pick a capture]` / `[bank empty]` / `[host: no bridge]`) + the **Browse** and **Zone**
  view buttons. (Inherits today's title-band text logic.)
- **Hero waveform band (enlarged) with the ENVELOPE OVERLAY (new).** The picked capture's
  full-resolution envelope (from `peaks` over the cached mono PCM — no new decode), given real
  vertical space (the Simpler/Phase-Plant hero, materially taller than today's 72px strip). Drawn
  over it, at **accurate wall-clock time**: (a) the **S11 markers** — start (teal/secondary),
  loop start/end (purple/tertiary), the faint loop-region fill — moved here from Browse
  unchanged; and (b) the **NEW amplitude-envelope overlay** — the AHDSR shape (Gate) or the
  fade-in/%-length/fade-out shape (Trigger) traced as a curve across the sample at the same time
  base the voice engine uses, in an accent hue. This is the "reads like a real sampler, not a
  spreadsheet" move: the envelope becomes a *shape over the sound*, not four abstract sliders.
- **Root + preview cluster (fenced, new preview-trigger).** Root note shown as a first-class,
  always-visible control (fenced like Phase Plant's "Root" box), draggable/typeable — this is the
  keyboard-strip root-drag from today's Browse setup, promoted to a fenced control. Adjacent: the
  **NEW preview-trigger button** (fires the sampler at the loaded capture's root note through the
  live voice engine, off the audio-thread commit path — no MIDI controller needed) with an
  **adjacent velocity knob** setting the preview velocity level. The **Mono/Stereo toggle** moves
  here from Browse (it is a per-capture output-mode tuning concern, not a choosing concern).
- **The "Modes-and-down" control strip (moved from Zone).** Every per-sample control that lives
  on today's Zones param panel for the single-capture case — **Mode** (Gate/Trigger), **Pitch
  engine** (Varispeed/Preserve), the **AHDSR** sliders (Gate) or **Length%/Fade-in/Fade-out**
  (Trigger), and the **AD pitch envelope** (Off/On + P.Attack/P.Decay/P.Depth) — renders here as
  the Sample view's control strip, laid out as a dense labelled value-row (bold micro-caps over a
  value/slider, the reference grammar). For a single loaded capture this is the same one-zone
  storage site the S15-F2 lean already established (the empty-map single-capture face reads/writes
  the same `PerformanceZone` defaults) — no new storage.

**Browse elements that MOVE to Sample (inventory — nothing silently dropped):** the large
waveform preview, the S11 start/loop markers + loop fill, the keyboard-strip root affordance (now
the fenced root control), and the Mono/Stereo toggle.

### View 2 — Browse (reduced to *choosing*, laid over Sample as a modal)

Browse's only job is **pick a capture**. Today's Browser view is close but overloaded; it is cut
to the choosing essentials and rendered as a modal overlay:

- **Kept (the excellent core, unchanged):** the **type-to-filter search box**, the **bank filter
  tabs** (All + one per named bank), the **captures grid** (cards: peak thumbnail + name +
  root/key badge), **scroll** (wheel + thumb), and card **selection**.
- **Added:** a **confirm/cancel** affordance (select a card, confirm to load it into Sample and
  dismiss; cancel to dismiss unchanged) — the modal-picker close semantics. Double-click-to-load
  is the natural accelerator.
- **Removed from Browse (moved to Sample or cut):** the **large waveform preview** (redundant —
  the grid thumbnails already show every capture's waveform; moved to Sample as the hero); the
  **Mono/Stereo toggle** (moved to Sample); the **root-note keyboard-strip** in the setup band
  (moved to Sample as the fenced root control); the **loop-point labels** and the **track-root
  message** (cut — they waste space and add nothing to *choosing*).

**Rationale (why cut, not keep-and-hide):** Browse is a picker. Every tuning affordance on it is
a mode error — you tune what you *have*, you browse for what you *want*. Concentrating tuning on
Sample and choosing on Browse makes each view do one job, and makes the modal overlay light
enough to summon and dismiss without ceremony.

### View 3 — Zone (dedicated keyboard-mapping surface + key-tracking + real piano pattern)

Zone is the multi-zone keymap editor — RS5K structurally lacks a multi-zone-in-one-instance view,
so this is a genuine capability, kept as the deliberate secondary surface. Retains today's Zones
view wholesale, with two changes:

- **Kept (inventory — nothing silently dropped):** **+ Add Zone** / **Delete** buttons, the
  **keyboard strip with one bar per zone** (selected zone lit accent-primary + static glow, others
  categorical), the **selected-zone legend** with the three **Low/High/Root numeric-entry fields**
  (click-to-type, `parseNoteEntry`), and the **per-zone param control panel** (Mode, Pitch engine,
  AHDSR/Trigger, AD pitch envelope) — the same panel Sample now also hosts for the single-capture
  case (one storage site, two surfaces).
- **NEW — key-tracking parameter (0%–200%, default 100%).** A per-`PerformanceZone` scalar on how
  sample pitch tracks the keyboard around the root note. **100% = standard 12-tone-ET tracking**
  (today's behavior, bit-identical); **0% = no tracking** (the sample plays at root pitch on every
  key — a fixed one-shot); **200% = double-rate tracking**. Additive on `PerformanceZone`,
  version-bumped, defaulting to 100% so pre-existing zones are unchanged. Applies inside the
  repitch math in **both** engines: under **Varispeed** it scales the semitone offset feeding
  `pitchRatio(note, root)` (`effectiveSemis = (note − root) · keyTrack`); under **Preserve** it
  scales the semitone offset feeding `set_shift(2^(effectiveSemis/12))`. Surfaces as a control in
  the Zone param panel (and, for the single capture, on the Sample control strip). **The pure
  sampler core owns the key-track math** (unit-tested: a known note/root/keyTrack triple asserts
  the expected ratio); the shell only maps the 0–200% control to the scalar.
- **NEW — real piano-key pattern on the keyboard strip.** Today's spectral strip is pretty but
  does not read as a keyboard (Daniel's note). Keep the pastel spectral hue as the backdrop, but
  **overlay the actual alternating white/black key pattern** — bright cells for naturals, dark
  cells for accidentals (C#/D#/F#/G#/A#), per the palette (bright ≈ a light neutral, dark ≈
  `bg/base`/hairline) — so the strip is instantly identifiable as a keyboard. It need not be
  *shaped* like a keyboard (no protruding black keys); it carries the **pattern** as an overlay,
  so a glance reads pitch position without counting. The pure `keyboard_strip` geometry gains a
  `isBlackKey(note)`/per-key-natural query (12-tone pattern, pure + unit-tested); the shell draws
  the two-tone overlay over the spectral fill. This same strip serves the Sample view's fenced
  root affordance (one keyboard grammar everywhere).

### New parameters — ownership and persistence (D-B; instrument-owned, never bank facts)

- **Key-tracking** — per-`PerformanceZone`, additive/version-bumped component state, default 100%.
  A **performance choice**, never written to `Sample` or the bank. Back-compat: an absent field on
  an older blob → 100% (bit-identical playback).
- **Preview velocity** — a **utility** setting for the Sample view's preview-trigger button, not a
  musical parameter of the capture. **SETTLED (S-VIEW-F1, Daniel 2026-07-27): it PERSISTS across
  reloads.** The seam is **VST3 component state**, not the extension's `persist` ext-state module.
  This distinction is load-bearing and was verified against the existing VST source, not recalled:
  - **Wrong seam — the extension's `persist` module.** `persist` writes REAPER *project* ext-state
    (`SetProjExtState`, namespace `"reasampler"`) and is owned by the **extension**, not the
    instrument. Preview velocity is a **per-instance** instrument-editor setting; putting it in
    project ext-state would (a) make it project-global rather than per-instance (two ReaSampler 9000
    instances would share one preview level), (b) route an instrument-owned setting through a seam
    the instrument only *reads* from (bank state), violating the read-only-over-bank contract, and
    (c) leak an instrument concern into the extension's key space. Rejected.
  - **Right seam — the instrument's own VST3 component state**, the same blob the processor already
    round-trips via `ReaSamplerProcessor::getState`/`setState` over `IBStream`, whose format is the
    **envelope-versioned `ComponentState`** in `src/vst/sample_map.h` (currently **v5**: version tag
    + channel-mode byte + last-consumed-assignment marker + selection-id + zones payload). Preview
    velocity is a **top-level instance concern** — a sibling of `channelMode` and
    `lastConsumedAssignGeneration`, **not** a per-`PerformanceZone` field (it is one setting per
    instance, not per zone). It therefore lands as a **new field on `ComponentState`** added by
    bumping the **envelope version to v6** (a new `float previewVelocity` after the assignment
    marker, before the selection-id), leaving the **zones payload untouched** — exactly the
    independent-version-axes composition the header already documents (envelope grows a field; the
    zone-record payload version does not move). Round-trip: `serializeComponentState` appends it,
    `deserializeComponentState` reads it; a v6 blob restores it directly, and **every older blob
    (v5 and down) lifts to a sensible default** (e.g. 100/127 ≈ 0.79 or a chosen mid level), so
    already-saved instances are unchanged and no compat surface is broken. This is the same additive
    envelope-bump discipline S7 (v4→v5) already used — a well-trodden move in this codebase, not new
    machinery.

### The envelope overlay — visual component (new)

The amp envelope drawn as a curve over the Sample view's hero waveform at accurate wall-clock
time (the Simpler/Phase-Plant grammar). Gate → the AHDSR shape (attack ramp, hold, decay to
sustain, release tail); Trigger → the fade-in/unity/%-length/fade-out shape anchored to `playEnd`.
The time base is the same the voice engine resolves (seconds → frames at the live rate), so the
drawn shape lines up with the waveform under it. **Pure geometry:** an `envelope_overlay` module
(mirror of `waveform_view` / `param_slider`) maps the AHDSR/Trigger params + the sample's
frame-length to a polyline in the waveform rect (`param↔pixel` at the shared time base),
unit-tested against known param sets; the shell traces it via kit line draws in an accent hue.

**The overlay is directly editable — DRAGGABLE NODES (SETTLED, S-VIEW-F2, Daniel 2026-07-27).**
The envelope is not a read-only informative curve — its breakpoints are **draggable handles** that
set the envelope parameters directly. Dragging a node and the existing sliders are **two surfaces
onto one model**: the sliders stay as the precise numeric-entry surface, node-drag is the direct-
manipulation surface, and **both read and write the same `PerformanceZone` envelope fields** — a
drag updates the params, the sliders reflect them live, and a slider edit re-lays the nodes. There
is exactly one source of truth (the zone's envelope params); the two surfaces never diverge. This
is the same one-source-multiple-views instinct the whole system runs on.

- **Which nodes, and what each axis means.** The AHDSR shape (Gate) exposes handles at the segment
  breakpoints — **attack-end** (top of the attack ramp), **hold-end**, **decay-end / sustain-level**
  (the corner where decay settles to the sustain plateau), and **release-end**. The Trigger shape
  exposes **fade-in-end**, **%-length** (the `playEnd` anchor), and **fade-out-end**. For each node,
  **the horizontal axis maps to time** (the segment duration — attack/hold/decay/release seconds, or
  fade/length fractions) and **the vertical axis maps to level** where the node is a level breakpoint
  (the sustain node's vertical drag sets sustain 0..1; the peak nodes sit at unity). Time-only nodes
  (attack-end, hold-end, release-end) drag horizontally; the sustain node drags on **both** axes
  (its X sets decay time, its Y sets sustain level) — the standard ADSR-editor grammar (Ableton
  Simpler, Phase Plant, Serum all use exactly this).
- **Constraints.** Nodes are **monotonic in time** — a node cannot be dragged left of its
  predecessor or right of its successor (attack-end can't pass hold-end, etc.); each segment stays
  ≥ 0. Level drags clamp to **0..1** (sustain) / unity (peaks). Times clamp to the same per-param
  min/max the sliders already enforce (so node-drag can never produce a param the slider couldn't).
  The `playEnd`/%-length node additionally clamps to the sample's frame-length. **No snapping** by
  default (continuous drag, matching the sliders' resolution); a fine-drag modifier (drag with a
  held modifier for reduced sensitivity) is an optional polish, not required.
- **Pure module owns the geometry/hit-test math (house pattern).** A pure REAPER/LICE-free module —
  name it **`envelope_edit`** (sibling to `envelope_overlay`; mirror of `card_drag` / `mode_switch`
  / `param_slider`) — owns **node hit-testing** (point → which node, with a pick radius) and the
  **drag→param mapping** (a pixel delta on a given node → the resulting clamped envelope param set,
  respecting the monotonic + range constraints above). It is **unit-tested**: a known node + a known
  pixel delta asserts the expected param delta and the clamp/monotonic behavior at the boundaries.
  `envelope_overlay` keeps the params→polyline forward map (draw); `envelope_edit` owns the
  pixel→params inverse map (edit) + hit-test. The shell (`reasampler_editor.cpp`) does the LICE
  handle draw (small node markers at each breakpoint, hover/drag-lit via kit states) and routes
  mouse events through `envelope_edit`, then commits the resulting params to the zone through the
  same off-audio-thread path the sliders use (no new RT surface — a node-drag is a param edit, same
  as a slider drag). Zones and the single-capture Sample face share this one edit surface (one
  storage site, S15-F2).
- **Sync with sliders (load-bearing).** Because both surfaces write the same `PerformanceZone`
  envelope fields, keeping them in sync is **structural, not a listener chain**: the editor re-reads
  the zone's params every paint, so a slider edit re-lays the nodes and a node-drag re-positions the
  sliders with no explicit cross-wiring. The single source of truth makes divergence impossible by
  construction.

### The real piano-key pattern — visual component (new)

Covered under View 3 above. Pure: `keyboard_strip` gains the natural/accidental predicate; shell
draws the bright/dark overlay over the existing pastel spectral fill. Shared by the Zone strip and
the Sample root affordance.

### The velocity → amp transfer-curve editor — visual component (new; Daniel, 2026-07-27, r10)

A **visual transfer-curve editor** mapping MIDI velocity to an amp scalar: **X = velocity (0–127),
Y = amp scalar (0–1)**, an editable bezier from a flat default to an arbitrary multi-point curve.
It gives fully shapeable velocity dynamics per sound. Today the engine maps velocity to gain
*linearly* — `velocityGain_ = velocity / 127.0`, computed once at note-on in `Voice::start()`
(`src/vst/sampler_core.cpp:261`); this replaces that fixed line with an editable curve evaluated at
the same point.

**State home — per-`PerformanceZone` (instrument-owned, D-B).** Velocity response is a per-sound
performance characteristic — a sibling of the AHDSR amp envelope, the pitch engine, and the r9
`keyTrack` scalar, all of which already live on `PerformanceZone`. A drum and a pad want different
velocity curves, so the curve varies **per zone**, not per instance. This is deliberately **not**
`ComponentState` (per-instance): that is where **preview velocity** correctly lives, because
preview velocity is a *utility* setting (one per instrument, like a metronome level), whereas the
transfer curve is a *musical* setting (one per sound). The curve is an **additive field on
`PerformanceZone`** riding the **zones-payload version axis** (contrast preview velocity's
envelope-v6 bump — a top-level per-instance field on the *envelope* axis; the two version axes are
independent, as the header documents). The single-capture Sample face reads/writes the same
one-zone storage site (S15-F2), so Sample and Zone views share one curve store per zone.

**Default — flat y=1, a deliberate behavior change (fork R10-F1, Daniel's call).** Daniel's
verbatim default is *"any velocity plays at full level"* — a flat curve at y=1. This is **not**
bit-identical to today's shipped linear `velocity/127` map: today soft hits are quieter; under a
flat-y=1 default every hit plays at unity, so every existing zone's felt dynamics change. This is
the one genuine fork the feature carries:
- **Option A (Daniel's stated default): flat y=1.** Honors the directive; velocity is inert until a
  curve is drawn. *Con:* NOT back-compat — already-saved instances and new captures get flatter
  dynamics than today until a curve is drawn.
- **Option B: default = today's linear ramp (y = x/127).** Bit-identical to the shipped engine; the
  editor's flat y=1 is one drawn state, not the default. *Con:* contradicts the verbatim *"by
  default … full level"* (the default line is a diagonal, not flat).
- **Lean: Option A (flat y=1)** — it is what Daniel asked for and the feature's point is opt-in
  velocity dynamics — but flagged loudly as a **shipped-behavior change**, not a silent regression.
  Option B is the safe fallback and costs only the default curve's seeded control points. Whichever
  wins, the *stored* default is a curve the editor draws and the core evaluates; the options differ
  only in which curve is seeded.

**Pure module — `velocity_curve` (REAPER/LICE-free, unit-tested).** Mirror of `envelope_edit` /
`card_drag`. Two responsibilities:
- **Evaluation:** `eval(velocity 0–127) → amp scalar 0–1` — a bezier through the control points,
  clamped to the 0–127 × 0–1 box, **monotonic in x** by construction (each velocity has exactly one
  output). Called at note-on, never per frame.
- **Editing:** add / move / delete control points, each clamped into the box and **x-ordered** (a
  point cannot cross its neighbours in x — the same monotonic grammar as the envelope nodes); a
  point hit-test (point → which control point, pick radius) and a pixel-delta → clamped-point
  inverse map (mirror of `envelope_edit`'s inverse map). The flat identity curve (per R10-F1) is a
  named constructor.

Both halves are **unit-tested** at the boundaries: a known curve + known velocity asserts the eval
output; a known drag asserts the clamped point set + the box/order constraints; add/delete assert
the point count and ordering invariants.

**Voice-engine application point — `Voice::start()`, off the per-frame path.** Confirmed from
source: `Voice::start(int note, int velocity, …)` (`sampler_core.cpp:252`) computes
`velocityGain_ = velocity / 127.0` **once at note-on** (line 261); the per-frame render then just
multiplies the cached scalar (`advanceFrame`, line 408: `gain = amp * velocityGain_`). The transfer
curve slots in at exactly that line — `velocityGain_ = curve.eval(velocity)` at note-on — **off the
audio-thread-hostile per-frame path** (evaluated once per voice, no new `process`-thread work, no
allocation). The curve reaches the voice the same way the AHDSR/keyTrack params do: on the zone's
`SampleData::play` bundle (resolved from the stored `PerformanceZone` at keymap build), read by the
voice at `start()`. The pure `velocity_curve` core owns the eval; the voice reads it.

**The curve-editor UI — Sample view, adjacent to the envelope overlay.** Lives on the **Sample
view** (the r9 home face), a compact band next to the hero-waveform envelope overlay — the two are
the same grammar (a drawn 2-D curve with draggable handles), and amp-over-time beside
amp-over-velocity reads naturally. Draws through the **L1 kit** like every S-VIEW surface: a
bordered box (X = velocity 0–127, Y = amp 0–1), the bezier traced in an accent hue, small draggable
node markers per control point (hover/drag-lit via kit states), add-point on empty-space click,
delete on modifier-click / drag-off. The shell (`reasampler_editor.cpp`) does the LICE draw + mouse
routing; **all geometry/hit-test/clamp math lives in the pure `velocity_curve` module**. On the
Zone view the same editor appears in the per-zone param panel (one curve per zone). Additive and
bit-identical for existing projects only under R10-F1 Option B; under Option A (the lean) it is
additive-but-behavior-changing.

**Wave-plan slot (concurrency-aware).** The curve lands on `PerformanceZone`, so it is **blocked by
Wave 1 track T-KEYTRK** (which owns the `PerformanceZone` schema + zones-payload version bump). The
`velocityCurve` field must sequence as a **LATER additive payload bump AFTER T-KEYTRK merges** — the
two are sequential additive extensions of the same zones-payload record, not simultaneous ones, so
they never collide on one payload version. It is **not** blocked by T-STATE (that owns the
per-instance `ComponentState` v5→v6 envelope bump for preview velocity — a different struct on the
independent envelope version axis). Concretely: a **follow-on foundation track** (pure
`velocity_curve` + the `Voice::start` application point + the additive `PerformanceZone` field +
payload bump), gated on T-KEYTRK; plus a **Wave 2 shell-integration item** (the Sample-view +
Zone-panel curve-editor UI through the L1 kit), gated on the foundation track and composing with the
S-VIEW-2 Sample face + S-VIEW-3 envelope overlay.

### The Sample-face recomposition — full-width hero, knob deck, curve popup (r11; Daniel, 2026-07-27)

> **Additive S-VIEW revision (r11) — the layout spec for the Wave B editor rebuild.** Recomposes
> the landed S-VIEW-1..10 Sample face after Daniel's DAW pass: **every linear slider becomes a
> small radial knob** grouped into a fenced **knob deck**, the two **mode toggles shrink** from
> full-width control rows to compact group-header segments, and the **inline velocity-curve box
> is replaced by a miniature curve preview button** that summons a **full-size popup editor** —
> freeing the **hero waveform to run full width**. The view recomposition is otherwise **parameter-
> preserving** — existing params, their persisted seams, and the VST3 class UID are all unchanged.
> **Exception (landed in FB1):** r11 added a post-mixer **master gain** control (MASTER group,
> −∞…+24 dB dB-taper, per-sample ramped in the processor) backed by a new `masterGainLinear`
> field in `ComponentState`, bumping the **envelope version v7→v8**; pre-v8 blobs lift to unity
> gain. The **knob primitive** itself
> (minimal arc ~6→4 o'clock, needle indicator, vertical drag) is a **separate in-flight track**;
> this section specs the layout that consumes it. Directives (Daniel, 2026-07-27): radial knobs
> replacing all sliders, grouped "in a reasonable way" with **the envelope controls grouped
> together intuitively**; pitch-engine and Gate/Trigger toggles **not full-width**; the velocity
> curve as a **small square preview button right of the preview-velocity control** opening a
> popup with the full-size editor, **right-click removing a control point** in the popup; the
> waveform preview **full-width**. Product framing: `docs/product/midi-playback.md` §Addendum r11.

**Inventory contract — every landed Sample-face element has a named home (nothing silently
dropped):**

| Landed element (S-VIEW-1..10) | r11 home |
|---|---|
| Title band: name + live readout, Browse + Zone nav buttons | Unchanged |
| Hero waveform + S11 markers (start/loop/loop-fill) + "(decoding…)" placeholder | Unchanged, now **full width** (the velCurve carve-out is gone) |
| Envelope overlay polyline + draggable nodes (S-VIEW-3/F2) | Unchanged, over the full-width hero |
| Inline velocity-curve box (trace, node drag, click-add, Alt-click delete, drag-off delete) | **Popup editor** — all interactions preserved, + new right-click delete; summoned from the mini preview button |
| Fenced root spectral strip + root marker drag | Unchanged (cluster left, now remainder-width) |
| Preview-trigger button | Unchanged (cluster) |
| Preview-velocity horizontal slider | **Radial knob** in the cluster ("Vel"), same persisted `previewVelocity` seam (envelope-v6, untouched) |
| Mono \| Stereo toggle | Unchanged (cluster, right-anchored) |
| Mode row (Gate\|Trigger, full-width toggle) | **Compact toggle in the AMP ENVELOPE group caption row** |
| Pitch eng row (Varisp\|Preserve, full-width toggle) | **Compact toggle in the PITCH group caption row** |
| Attack / Hold / Decay / Sustain / Release sliders (Gate) | **Knobs in the AMP ENVELOPE group** |
| Length % / Fade in / Fade out sliders (Trigger) | **Knobs in the AMP ENVELOPE group** (time-ordered: Fade In · Length % · Fade Out) |
| Pitch env row (Off\|On, full-width toggle) | **Compact toggle in the PITCH ENV group caption row** |
| P.Attack / P.Decay / P.Depth sliders | **Knobs in the PITCH ENV group** |
| Key track slider | **Knob in the PITCH group** |
| Empty state ("pick a capture") + S13 drop-hint banner | Unchanged |

**Band order (top → bottom) — hero becomes the elastic band.** Title (26, unchanged) → **hero
(full width between kPad margins, ELASTIC: absorbs all height left after the fixed bands, floor
150px)** → cluster (52, unchanged height) → **knob deck (fixed-height, bottom-anchored; ~92px
per deck row)**. The old fixed-150 hero + rest-of-window slider stack inverts: the control
surface is now the fixed band and the waveform grows with the window. At the unchanged 840×620
default this yields a ~430px hero (see fork R11-F1 for the height call).

**The knob deck — three fenced groups, left → right.** Each group is a hairline-bordered
`bg/panel` box with a **caption row** (~20px: micro-caps caption left; the group's **compact
mode toggle right-anchored in the caption row** — this is where the not-full-width toggles
live) over a **knob row** of fixed cells. Knob cell: **48w × 58h** — 28px knob centered, 12px
`Font::Micro` label beneath in `text/dim`; **the label swaps to the live value during
hover/drag** (no third line, no permanent value clutter). Toggle segments reuse the Mono/Stereo
grammar (~44–52px per segment, 18px tall, Active segment accent-primary). Groups:

- **AMP ENVELOPE** — caption toggle: **Gate | Trigger** (`kPlayMode`). Knobs, Gate: **Attack ·
  Hold · Decay · Sustain · Release**; Trigger: **Fade In · Length % · Fade Out** (a deliberate
  time-order reorder of today's row order — left-to-right matches the drawn envelope). The group
  **reserves the 5-cell Gate width** so a mode flip repopulates in place and never reflows the
  neighboring groups (Trigger simply leaves two cells blank). This is the "envelope controls
  grouped together as a unit" directive: the group IS the envelope, its toggle picks the shape,
  and the hero's envelope overlay is the same params drawn large (two surfaces, one model —
  unchanged from S-VIEW-F2).
- **PITCH** — caption toggle: **Varisp | Preserve** (`kPitchEngine`). Knob: **Key Track**
  (0–200%, the S-VIEW-6 scalar). Key tracking is repitch math, so it lives with the engine that
  applies it.
- **PITCH ENV** — caption toggle: **Off | On** (`kPitchEnvEnable`). Knobs: **P.Attack · P.Decay
  · P.Depth**. Its own fenced envelope unit, mirroring AMP ENVELOPE's grammar at smaller scale.
  When Off, the three knobs draw `Disabled` (kit state) rather than vanish — stable geometry.

Group gaps 12px; deck side margins kPad. Sum at these metrics ≈ 610px wide; **below that width
the pure module wraps whole trailing groups to a second deck row deterministically** (the deck
grows, the elastic hero shrinks toward its floor — the 560px `checkSizeConstraint` minimum
forces PITCH ENV onto row two, which is acceptable at the floor).

**The cluster band (root + preview + curve button).** Root strip keeps the left side but becomes
**remainder-width** (min ~200px) instead of a fixed 55%; the right side is a fixed-width
right-anchored run: **Preview button (64w) · Vel knob cell (48w, the radial preview-velocity
knob) · curve preview button (28×28, immediately right of the Vel knob — per the directive) ·
Mono | Stereo (right-anchored, unchanged)**. The **curve preview button** is a hairline-bordered
`bg/cell` square with the zone's live velocity curve traced in miniature (1px secondary-accent
trace, no node markers at this scale); Hover lifts it, and it draws **Active (accent-primary
border)** while its popup is open. It re-renders live as the popup edits the curve.

**The popup curve editor.** Summoned by left-click on the curve preview button. A **centered
sheet over the Sample face**: a 0.50-alpha `bg/base` wash over the whole window (lighter than
Browse's 0.82 — this is a focused sub-editor, the Sample face stays legible behind it), then a
`bg/panel` + hairline sheet, **width clamp(60% of window, 360..520), height clamp(55%, 260..380)**.
Inside: a ~22px title row ("VELOCITY → AMP" micro-caps left, a **Close (×) button** 18×18 right),
and the **full-size curve box** filling the remainder using the existing `curveBoxFromRect`
inset/mapping-box grammar (one coordinate formula, as landed). Interactions are **identical to
the landed inline editor** — node drag with mouse-up commit, empty-space click adds + grabs a
point, Alt-click delete, drag-off delete (the box+24px drag-off margin stays inside the sheet,
so it cannot collide with dismissal) — **plus the NEW right-click delete (issue 3c): right-click
on a node removes it**, committing immediately through the same path as Alt-click, with the
existing `deletePoint` endpoint guard making endpoint right-clicks a safe no-op. Right-click
becomes the *primary* delete affordance; Alt-click and drag-off remain as landed alternates
(nothing dropped). **Dismiss:** Close click, click on the wash outside the sheet (only when no
drag is in flight), or Esc. Popup state (open flag + target zone) is editor-local, never
persisted. The `dragStartMap_` rollback contract is unchanged.

**Module architecture (r11 delta — house pattern preserved).**

- **Pure NEW `knob_deck`** — group boxes, caption rows, compact-toggle rects, knob-cell rects,
  deterministic group wrap, and hit-test (point → control id + element kind). Mirror of
  `action_bar` / `param_slider`; consumes the same shell-owned control-id descriptors;
  engine-free, LICE-free, unit-tested (layout at reference widths, wrap at the 560 floor,
  hit-test at cell/toggle boundaries).
- **Pure NEW `curve_popup`** — sheet/close/box geometry from the window size + the
  outside-sheet dismissal test. Mirror of `overflow_menu`; unit-tested at the size clamps.
- **The knob primitive** (value↔needle-angle map, arc geometry, vertical-drag delta→value) is
  the **separate in-flight track**; `knob_deck` treats a knob cell as a rect and defers
  value↔angle to the primitive. Layout-level contract on it: vertical drag with resolution at
  least matching the retired sliders; a Shift fine-drag is optional polish (mirroring the
  envelope-node note), not required.
- **`param_slider` retires from the Sample face** (and from the Zone panel under fork R11-F2);
  its toggle-segment helpers may be reused for the compact toggles or subsumed into `knob_deck`
  — implementer's call at build. The preview-velocity control becomes a knob cell bound to the
  same persisted `previewVelocity` (seam untouched).
- **Shell (`reasampler_editor.cpp`):** re-lays `computeSampleBands` (elastic hero, fixed deck),
  draws groups/knobs/mini-button/popup through the **L1 kit** by palette role, routes
  right-click (verify `WM_RBUTTONDOWN` reaches the child wndproc — see must-verify) and Esc.
  Knob drags commit on mouse-up exactly as slider drags did (live invalidate, `commitAndReload`
  on release); the knobs and the hero's envelope nodes stay two surfaces on one param model.

**Spec'd aesthetic defaults (decided here; Daniel can veto at smoke test):** label↔value
swap-in on knob cells; Trigger knob time-order (Fade In · Length % · Fade Out); popup wash
0.50; group captions AMP ENVELOPE / PITCH / PITCH ENV; disabled-not-hidden PITCH ENV knobs.
The two genuinely open aesthetic calls are forks **R11-F1** and **R11-F2** in the fork ledger
below.

### Engineering prerequisite 1 — drop-to-FX bug (routed to implementation, NOT a design call)

**Symptom (Daniel):** dropping a capture onto a track's FX chain does not instantiate + init
ReaSampler 9000 — the audio-to-arrange drop works, but the "instrument init never fires."

**RESOLVED (GA post-launch DAW-fix pass, 2026-07-28).** The root cause was the injection
mechanism, not the gesture wiring: `TrackFX_SetNamedConfigParm(..., "vst_chunk", <base64>)`
is silently unappliable for VST3 — REAPER's VST3 wrapper cannot apply unframed raw component-state
bytes there (the write parm returns true but the instance stays at defaults). The fix:
`instrument_drop` builds a Steinberg-format `.vstpreset` file image (header + 'Comp' chunk =
serialized component state, class ID from `reasampler_uid.h`); `instrument_drop_win` writes a
transient temp file and applies it via `TrackFX_SetPreset(track, fx, path)`, which the SDK
documents as accepting full `.vstpreset` paths for VST3 plug-ins. FX hotspot prefix-set extended
to `tcp.fx*`/`mcp.fx*`/`fx_*` (embed strip tokens excluded). `reasampler_uid.h` split out of
`reasampler_vst.h` as an SDK-free header so `instrument_drop` (pure module) can derive the
class-ID hex string without the VST3 SDK.
**Verify in DAW:** drag a capture onto a track's FX button → a ReaSampler 9000 instance appears on
that track already playing that capture (one Ctrl-Z removes it). **VERIFIED.**

### Engineering prerequisite 2 — default window size for 1080p (routed to implementation)

**Symptom (Daniel):** the editor window is too small by default; assume a 1080p minimum screen.

**SDK sweep (done this pass — mechanism verified):** the VST3 editor size is set by the
`IPlugView`/`CPluginView` contract. `getSize()` returns the view's `rect` (set via `setRect` — the
default the host opens at); `checkSizeConstraint()` is where a minimum is enforced; `onSize()`
handles host resizes; `canResize()` already returns `kResultTrue`. **Verified in
`vendor/vst3sdk/public.sdk/source/common/pluginview.h`.** Today `ReaSamplerEditor`'s constructor
sets `ViewRect(0, 0, 560, 400)` — the undersized default. **The fix is a one-line default change**
(a larger initial `ViewRect` sized for the new three-band Sample face on a 1080p display) **plus
an optional `checkSizeConstraint` minimum** so the host cannot shrink the window below a usable
floor. **This is not a platform limitation — the mechanism exists and is trivial.** The exact
default dimensions are a build-time value to set against the Sample face's band heights (hero
waveform + control strip want materially more than 400px tall; a ~840×560 or larger default is the
starting point, tuned at build). **Routing:** flagged for **staff-engineer**; no product fork.
**Verify in DAW:** the editor opens at the new default on a 1080p screen showing the full Sample
face without scrolling, and cannot be resized below the constraint floor.

> Build detail for this sub-phase (module architecture) moved to CONTEXT-ARCHIVE.md.

### Precision / invariant implications

- **Read-only bank consumer (unchanged).** Key-tracking, preview velocity, envelope-node edits, and
  every marker/mode control are the instrument's **performance map / editor state** (D-B) — held in
  the instrument's own VST3 component state, **never written to `Sample` or the bank.**
- **Additive, back-compat component state.** Three additive fields land: `keyTrack` (per-
  `PerformanceZone`, default 100%) and — sequenced after it on the same zones-payload axis —
  `velocityCurve` (per-`PerformanceZone`, r10, default the R10-F1 curve) inside the zones payload,
  and `previewVelocity` (per-instance) as a new top-level `ComponentState` field via an **envelope
  bump to v6** on the independent envelope axis. Every older blob lifts on read (absent `keyTrack` →
  100%, absent `velocityCurve` → the R10-F1 default curve, absent `previewVelocity` → the chosen mid
  default), so already-saved instances restore cleanly. **Playback back-compat carries a caveat for
  the velocity curve:** under R10-F1 Option A (flat y=1 default) an already-saved zone with no
  stored curve now plays every velocity at unity — **not** bit-identical to the linear `velocity/127`
  it played before; under Option B (linear default) it is bit-identical. This is the one non-back-
  compat surface in S-VIEW and is the substance of fork R10-F1. `keyTrack` and `previewVelocity`
  remain fully bit-identical on lift. No existing field changes.
- **RT discipline (unchanged).** The preview-trigger fires a note through the existing voice engine
  via the off-audio-thread commit path (`commitAndReload` idiom); no new `process`-thread work,
  no allocation on the audio thread.
- **VST3 class UID unchanged.** A view reorganization + additive param is **not** a compat event;
  saved instances rebind and restore. The UID stays the S-NAME-1/S18 forever-locked identity.
- **Capture ≠ placement ≠ playback (unchanged).** The preview-trigger plays; it never captures,
  never inserts a timeline item. The three acts stay distinct.

### Open questions / forks (Daniel / Phase S team)

*(S-VIEW-F1 and S-VIEW-F2 are SETTLED — Daniel 2026-07-27 — and folded into the spec above:
preview velocity **persists** via envelope-v6 `ComponentState`; the envelope overlay's nodes are
**draggable** via the pure `envelope_edit` module. They are no longer open questions.)*

- **S-VIEW-F3 — Browse modal presentation. SETTLED (2026-07-27): full-window overlay** — landed
  in S-VIEW-1/S-VIEW-5 (Browse renders as a full-window modal over Sample). Recorded here so the
  ledger matches PLAN.md; no longer open.
- **R10-F1 — velocity-curve default (Daniel, 2026-07-27).** **Option A: flat y=1** (Daniel's
  verbatim default — every velocity plays at full level; NOT back-compat with today's linear
  `velocity/127`, so existing zones' dynamics change) vs. **Option B: linear y = x/127** (bit-
  identical to the shipped engine; contradicts the verbatim "full level" default). **Lean A**,
  flagged as a deliberate shipped-behavior change, not a silent regression. This is the only
  non-back-compat surface the velocity-curve feature introduces. **Daniel's call.**
- **R11-F1 — hero height vs. default window (r11; Daniel, 2026-07-27).** With the knob deck
  collapsing ~312px of slider rows into ~92px, the elastic hero at the unchanged 840×620
  default runs ~430px tall — waveform-dominant (Simpler-like; envelope-node drags gain vertical
  precision). Alternative: shrink the default to ~840×520 (hero ~330px, a tighter face).
  **Lean: keep 840×620 + elastic hero** — the freed space going to the waveform is the point of
  the recomposition, and no default-size churn. Purely aesthetic. **Daniel's call.**
- **R11-F2 — Zone-panel parity (r11; Daniel, 2026-07-27).** Convert the Zone param panel to the
  same knob deck + curve-preview-button/popup (one control grammar everywhere; retires
  `param_slider`'s slider rows outright) vs. leave Zone on the landed slider rows (smaller Wave
  B, but the same params render as knobs on Sample and sliders on Zone — a grammar fork).
  **Lean: parity** — one grammar, and the two surfaces already share one storage site (S15-F2).
  Cost: Wave B scope grows by the Zone panel re-lay. **Daniel's call.**

### Must-verify before build (S-VIEW)

- **Editor size mechanism** — `getSize`/`setRect`/`checkSizeConstraint`/`onSize`/`canResize`
  **verified present** in `vendor/vst3sdk/public.sdk/source/common/pluginview.h`; confirm the exact
  min-size enforcement point (`checkSizeConstraint`) behaves under REAPER's host at build.
- **Drop-to-FX** — `TrackFX_AddByName` / `TrackFX_SetPreset` / `GetThingFromPoint` all
  **verified present** in `reaper_plugin_functions.h`; injection via `TrackFX_SetPreset` +
  `.vstpreset` image (not `vst_chunk`) — **RESOLVED, GA DAW-fix pass 2026-07-28.**
- **Preview note through the voice engine off-thread** — confirm the existing `commitAndReload`
  / off-thread reload idiom is the right seam to fire a one-shot preview note without touching
  `process` on the UI thread; no torn state on the atomic voice-engine pointer.
- **Preview-velocity persistence seam (S-VIEW-F1)** — the envelope-v6 `ComponentState` field is the
  prescribed seam (verified against `src/vst/sample_map.h` + `reasampler_processor.cpp`
  getState/setState this pass); confirm at build that appending a `float previewVelocity` after the
  assignment marker keeps the v5→v6 lift clean and the zones-payload byte offsets unchanged.
- **Envelope node-edit inverse map (S-VIEW-F2)** — confirm the pure `envelope_edit` pixel→param
  inverse map produces params the sliders' own min/max already permit (so the two surfaces can
  never diverge), and that the monotonic time-node constraint holds at the segment boundaries.
- **Envelope-overlay time base** — confirm the seconds→frames resolution the overlay draws against
  matches the voice engine's live-rate resolution so the drawn shape lines up with the waveform.
- **Velocity-curve application point (r10)** — confirm `Voice::start()` (`sampler_core.cpp:252`) is
  the sole velocity→gain site and that replacing `velocityGain_ = velocity / 127.0` (line 261) with
  `velocityGain_ = curve.eval(velocity)` keeps the eval at note-on only, off the per-frame render
  path (line 408 `gain = amp * velocityGain_` unchanged). No new `process`-thread work or allocation.
- **Velocity-curve payload sequencing (r10)** — confirm the additive `velocityCurve` field on
  `PerformanceZone` lands as a zones-payload bump AFTER T-KEYTRK's `keyTrack` bump (not simultaneous),
  so the two sequential extensions of the same record never collide on one payload version number.
- **Velocity-curve eval monotonicity (r10)** — confirm the pure `velocity_curve` bezier is monotonic
  in x over the 0–127×0–1 box (one output per velocity) and that control-point edits stay clamped +
  x-ordered at the boundaries.
- **Right-click routing (r11)** — confirm `WM_RBUTTONDOWN`/`WM_RBUTTONUP` reach the editor's child
  wndproc (today only left-button + move are handled) before committing to right-click node delete;
  same sweep for Esc/`VK_ESCAPE` key routing while the curve popup is open (the Browse search box
  already takes keyboard input, so the focus path exists — confirm the popup sees it).
- **Deck wrap + hero floor (r11)** — confirm the pure `knob_deck` wrap is deterministic at the
  560×460 `checkSizeConstraint` floor (PITCH ENV onto row two) and the elastic hero's 150px floor
  holds with a two-row deck at minimum height.
- **Knob primitive contract (r11)** — confirm the separately-built knob primitive and `knob_deck`
  agree on the knob-cell rect and the value↔angle map (one formula each side of the seam), so the
  drawn needle and the drag hit-test can never drift — the same one-formula discipline as
  `curveBoxFromRect`.

## Instance-usage detection — the un-prunable guarantee (pS-usage, 2026-07-28)

> **Additive sub-phase of Phase S.** Adds a new safety seam between the VST3 instrument
> and the extension's prune path: a live ReaSampler 9000 instance holding a capture
> makes that capture un-prunable. Build detail and module architecture: CLAUDE.md
> §Architecture. The pure core (`sample_usage`) and its tests (`sample_usage_tests`) are
> REAPER-free; the REAPER-facing shell (`usage_scan`) is read-only at prune-scan time.

### The guarantee

A capture held by any live ReaSampler 9000 FX instance in the project **can never be
deleted by `BANK_PRUNE_FOLDER`**. If the prune cannot determine with certainty which
captures are held — because any usage record is unreadable or ambiguous — the prune
**aborts entirely (deletes nothing)**. Over-protection (prune skips a reclaimable file
or refuses to run) is the accepted residual; under-protection (deleting a file an
instance may still be playing) is a data-loss bug.

### The wire: `rsusage_<instanceGuid>`

Each VST3 instance holds a **per-instance GUID** persisted in `ComponentState` v11
(`instanceGuid` field; pre-v11 blobs mint the guid on first publish). At the tail of
every `reloadInstrument` call (off audio thread) the processor publishes its held
`SampleRefs` paths to the ext-state key `rsusage_<instanceGuid>` in the `"reasampler"`
namespace via `reaper_bridge::writeUsageExtState`. That entry point is **prefix-guarded**
— it accepts only `rsusage_`-prefixed keys and refuses all others, so the read-only-bank
invariant is structurally enforced.

**Direction:** the instrument writes usage keys; the extension reads them. This is the
one sanctioned instrument→ext-state write (a deliberate exception analogous to
`assignment_request` on the other wire), and it never touches the bank, view, tail, or
any other extension-owned key.

### Liveness — no teardown clearing, no challenge/response

Usage records are **never cleared by the instrument** at teardown: REAPER destroys the
plugin instance when an FX chain is set offline (including Design View's CPU-park), so
a terminate-time clear would strip the record of an instance that still exists in the
project. Liveness is decided extension-side at prune-scan time by cross-referencing the
usage records against the live FX enumeration (`usage_scan`).

### The prune-scan fold

At prune-scan time `usage_scan` (the REAPER-facing shell):

1. Enumerates every `rsusage_*` ext-state key and decodes each record. A present-but-
   unreadable record sets `abortPrune` — halting the prune, deleting nothing.
2. Enumerates every ReaSampler 9000 FX instance in the project: all tracks (master
   included), normal + record/input chains, FX containers recursively, and take FX.
   Truncated/partial enumeration → `abortPrune`.
3. Folds via `sample_usage::foldUsageRecords` / `usageHeldPaths` (pure, provable
   without a DAW): a record counts iff its publishing track still hosts at least one
   instance (offline FX included); a record with no track context counts while any
   instance exists; and when records exist but zero instances were identified,
   **every** record's paths are protected (identity-failure net — a matcher failure
   must never degrade toward delete).

The resulting held-paths set feeds `prune_reconcile::mergeReferenced`, which unions it
into the bank-referenced set. The orphan computation is therefore
`(owned ∩ present) − (bankRefs ∪ liveInstanceHolds)`.

### Collision safety (FX copy / track duplication)

A persisted GUID is copyable. Two design mechanisms close the copy gap in the
fail-safe direction:

- **`ownerNonce`** — a per-lifetime nonce minted fresh in memory at instance creation,
  never persisted. Proves "exactly this incarnation wrote the key last."
- **`unioned` flag** — a sticky multi-writer poison. Once a same-track sibling is
  detected, the key enters union-forever mode: holds only accumulate, never drop.

The publish plan (`planUsagePublish`) resolves every collision toward over-protect:
same-nonce + not-unioned → clean replace; same-track foreign nonce or unioned → union;
cross-track foreign nonce → remint under a fresh key. All three directions over-protect
at worst; none can under-protect.

### Fail-safe summary

| Situation | Outcome |
|---|---|
| Normal: record readable, instance live | Held paths added to `referenced` |
| Record readable, instance gone (stale key) | Paths excluded — not protected |
| Records exist, zero instances identified | ALL records' paths protected |
| Any record unreadable | Prune aborts — deletes nothing |
| Same-track copy detected | Union of holds; `unioned` flag set forever |
| Cross-track copy detected | Remint under fresh key |

### `actions` integration

`BANK_PRUNE_FOLDER` checks `PruneReport.abortedUnreadableUsage`; when set it halts
before any deletion and prints the offending `rsusage_*` key names with instructions
(the keys name which FX instances need attention). This is the only user-visible surface
of an abort — the dry-run path shows the same abort signal before any confirm step.

### Deferred follow-up

**Persist instance identity (TODO.md):** the per-instance `ownerNonce` is minted fresh
each incarnation and is NOT persisted. After save→reopen an instance cannot recognize its
own prior-session usage record — it looks foreign, so the instance unions and marks the
record `unioned` (append-only) forever. Net effect: after any reopen, prune stops
reclaiming captures an instance once held but no longer uses. Safe (never deletes a live
capture), but the bank folder grows without bound. The fix — persist the nonce in
`ComponentState` so an instance recognizes its own last-session record and does a
clean-replace — is deferred because a persisted nonce is inherited by a Ctrl+D in-place
FX duplicate, and a divergent clone must still be detected and protected fail-safe without
reintroducing the sibling-drop bug.

---

# Look-and-feel — visual design language (Phase L)

> **New pillar, own lettered phase, taken up by a parallel team.** Phase L is the
> whole-system look-and-feel effort — a shared LICE drawing kit and the surfaces that
> adopt it — that replaces the flat "temple os" drawing (opaque `LICE_FillRect` blocks +
> raw GDI `DrawTextA`) with a modern, sleek 2026 dark synth look across ReaSampler
> (the extension's docked bank panel) and ReaSampler 9000 (the Phase S VST editor + embed
> strip). Namespaced **`L` (Look-and-feel)**, orthogonal to and ungated by the
> M/D/B/R/V/S pillars. Product framing, the settled decision record (DS-1/DS-2/DS-3 all
> SETTLED 2026-07-26), palette, the three visual directions, and the toolkit assessment:
> `docs/product/visual-design-language.md`. Same standing discipline: **verify every LICE/
> WDL/SWELL API name/signature against `vendor/WDL` before use.** When a point lands,
> doc-keeper moves it to `COMPLETED.md`.

## What it is

A **shared LICE-based drawing kit** (palette + type scale + component-draw layer) and the
surfaces that consume it. The kit is the **one source of drawing** for the whole system —
a button, row, slider, or waveform looks identical in the bank panel, the embed strip, and
the VST editor because it is the same kit function (the one-source-multiple-views instinct,
applied to drawing). The current "temple os" look is the system drawing at the **floor** of
LICE (flat fills, GDI text, no gradients/AA/rounded/hover); the kit lifts every surface to
LICE's actual ceiling — which REAPER's own themed UI and SWS prove is a modern dark UI.

## Settled decisions (Daniel, 2026-07-26 — reasoning in `docs/product/visual-design-language.md` §6)

- **DS-1 — toolkit: LICE + WDL free game, no external frameworks.** Draw with **LICE**
  directly (gradients via `LICE_GradRect`, AA rounded via `LICE_RoundRect`/`LICE_Line`,
  cached AA text via `LICE_CachedFont`). **Reuse any useful WDL/vwnd piece** — skin/image
  helpers, draw idioms, a specific control (e.g. `virtwnd-listbox` for a long scroll list)
  — where it beats re-deriving; "don't reinvent the wheel." **Reject external frameworks**
  (iPlug2 / JUCE / VSTGUI — they re-open the settled bare-SDK+LICE build shape to solve a
  look problem that is not a toolkit-ceiling problem). **Caution, not a ban:** keep
  hit-test **geometry** in pure CTest-covered modules — do not import vwnd's retained-mode
  object model wholesale (its controls own their hit-test internally, which would move
  geometry into untestable shell code and undercut the pure/shell split).
- **DS-2 — visual direction: Direction B ("Neon Console") + Direction C's spectral
  keyboard strip. SETTLED 2026-07-26, REVISED 2026-07-26 (Daniel) — three-accent pastel
  accents AND REAPER-grey neutrals (palette-only).** *Neutral surfaces (revised):* the
  neutral ladder moved **from near-black up into REAPER's mid-grey theme family** so the
  dock reads as *part of REAPER, not a black slab* — `bg/base` ≈ `#2b2b2b` (REAPER chrome),
  `bg/panel` ≈ `#333333`, `bg/cell` ≈ `#3a3a3a` (REAPER track bg), `line/hairline` ≈
  `#4a4a4a`, `text/primary` ≈ `#dcdcdc`, `text/dim` ≈ `~#a0a0a0`+. Elevation-ladder
  discipline unchanged (base < panel < cell by a few %, micro-gradient + inner
  highlight/shadow carry elevation, not hard borders). *Accent layer (revised):* changed
  from **one electric cyan** to **three pastel accents**: `accent/primary` = **pastel lime
  green** (`~176,224,152`, the
  live/active/selected signal), `accent/secondary` = **pastel teal** (`~132,214,208`,
  categorical role A), `accent/tertiary` = **pastel purple** (`~194,170,232`, categorical
  role B); `accent/hot` is a lighter pastel-lime tint (`~200,236,178`). These are *starting*
  values — the implementer locks final hex against the theme module's WCAG tests, staying
  **within the pastel intent** ("soft-side" floor: the most pastel value that still clears,
  not re-saturated toward neon). The **spectral (hue-mapped) keyboard strip** — signature
  surface, glow-on-active as a static drawn state — is now a **pastel** sweep anchored on the
  three accents (pastel-lime low → pastel-teal mid → pastel-purple high). **A stylish/bundled
  font upgrade was considered and DECLINED (Daniel, 2026-07-26)** — no font bundling or
  redistribution; the kit keeps its **current** cached-font face and no new typeface is
  specified (§3.1). The kit palette stays **abstract** (role→color, one constants block —
  now three accent roles), so the direction is a single-file change. *Tight pairs flagged for
  the implementer (re-verify against the GREY ladder, not near-black):* **`text/dim` on
  grey** (mid-grey-on-mid-grey — lands ~4:1 at start, must be lifted toward `~#a8a8a8`+ to
  clear AA 4.5:1 body on `#333`/`#3a3a3a`, the classic floor failure); **the three pastels
  as state indicators / active fills on `bg/cell`** (the pastel cushion shrank from ~15:1 on
  near-black to ~6:1–7:1 on grey — still clears 3:1 but must be re-checked; if any drops
  below floor, nudge that hue slightly deeper within the pastel intent); body text **on a
  pastel fill** (light-grey on a light pastel can drop below AA 4.5:1 — use dark labels on
  pastel fills or darken the fill); and **secondary vs. tertiary** distinguishability (both
  cool/desaturated — verify they read as distinct categories). Full reasoning:
  `docs/product/visual-design-language.md` §2.1 + §4 + §6.
- **DS-3 — dock-panel scope: a thorough layout redesign, not a light re-skin.** L2 lays out
  the *full* button/affordance inventory — including M11's action-trigger buttons +
  keybinding-help labels — intuitively, uncluttered, and useful, then applies the kit.
  Sequenced after M11 merges so it designs against the actual landed button set.

## Palette + the "punch" rule (Daniel's standing taste)

Dark, modern, **visual punch over conservative contrast — now pastel, on REAPER-grey.** The
palette is defined by **role**, not hardcoded hue: `bg/base`, `bg/panel`, `bg/cell`,
`line/hairline`, `text/primary`, `text/dim`, `accent/primary`, `accent/secondary`,
`accent/tertiary`, `accent/hot`, `warn`. **Neutral surfaces (DS-2 revised, 2026-07-26):**
the neutral ladder sits in **REAPER's mid-grey theme family**, not near-black, so the dock
reads as *part of REAPER* — `bg/base` ≈ `#2b2b2b`, `bg/panel` ≈ `#333333`, `bg/cell` ≈
`#3a3a3a`, `line/hairline` ≈ `#4a4a4a`, `text/primary` ≈ `#dcdcdc`, `text/dim` ≈ `~#a0a0a0`+.
A modern dark UI is built from **elevation layers**, not borders — surfaces gain a
**micro-gradient** (`LICE_GradRect`, a few percent lighter at the top) + a 1px inner
top-highlight / bottom-shadow (the vwnd trick) instead of flat fills; the grey ladder keeps
this discipline (base < panel < cell by a few %, subtle steps like REAPER, not hard
outlines). The three accents carry categorical meaning: **primary (pastel lime) =
live/active/selected**, **secondary (pastel teal) + tertiary (pastel purple) = supporting
categorical distinctions** (kinds, not intensity — primary is always "what's live now").
**WCAG-floor discipline (pastel + grey re-read):** moving neutrals *up* into grey makes two
pairs *harder* — (1) **`text/dim` on `bg/panel`/`bg/cell`** is the classic
mid-grey-on-mid-grey floor failure (must be lifted light enough to clear AA 4.5:1 body on
the greyest surface it draws on), and (2) **the three pastels as state indicators on grey**
have a shrunken contrast cushion (~6:1–7:1 vs. ~15:1 on near-black — still clear 3:1 but
re-verify; nudge a hue slightly deeper within the pastel intent if it drops below floor).
Text-on-a-pastel-fill (AA 4.5:1) remains a tight pair. Take the *most pastel* value that
still clears the floor **on grey** — approached from the **soft side**, never re-saturated
toward neon "to be safe," except where the grey floor forces a small deepening. The `warn`
role (red/amber) is reserved *only* for byte-deleting or clip states (prune, delete).
Because the palette is role-based in one constants block, the settled-and-revised
B+pastel+grey+spectral direction (DS-2) is one file.

## "Speed is the selling point" — a design constraint, not a tagline

The UI must **feel instant, and no decoration may cost that.** Sub-frame hover/press/drag
feedback repainted immediately on the input message (instant acknowledgment *is* the
perception of speed); zero-jank via the preserved double-buffer discipline (draw to
`LICE_SysBitmap`, single `BitBlt`); region-scoped `InvalidateRect` during a drag
(build-time residual). **No decorative animation** — no tweens/fades/pulses; the only
permitted motion is a level/meter readout following the audio directly (as the embed strip
already does). Direction C's glow/bloom is a **static drawn state, never a pulse.** The
"fast" feeling is typography + hover + no-jank, not motion.

> Build detail for this phase (kit architecture, L2/L4/L5 dock-panel layout contracts, L7 implementation detail, the L3 gate, LICE/WDL API surface) moved to CONTEXT-ARCHIVE.md.

## L7 capture ordering · card metadata · selection styling (ordering model · overlay · tertiary-border selection)

L7 is the **next ungated dock-panel pass over the same `bank_panel` grid** L4–L6 built. Unlike
L4/L5 (pure layout over existing actions), **L7 (1) is a persisted-model change** — it adds an
explicit per-sample display order with gap-preserving sparse placement to the persisted bank
state and its JSON round-trip. (2) and (3) are draw-only. **No new capture/placement behavior;**
the "capture ≠ placement" principle is untouched. Drawn through the L1 kit in the DS-2
grey-neutral + three-accent-pastel palette; **no palette/font decision is re-opened.** Ungated
by Phase S; independent of the L3 gate. Sequences AFTER L6.

**Research baseline (dev, confirmed at spec time).** The grid draws in **`BankIndex` insertion
order**: `BankIndex` holds `std::vector<Sample> samples_` in insertion order (`all()`), and
`bank_grid::computeCellRects` tiles exactly one contiguous rect per sample left-to-right,
top-to-bottom — **no explicit ordinal, no sparse slots today.** `Sample` already carries
`lengthSeconds`, `lengthBeats`, and `captureTempo` (BPM at capture) but **no time-signature
field.** The selected cell is drawn (`bank_panel::drawThumbnail`) as
`InteractionState::Active` (accent-fill surface) + an `accent/primary` border + an *inverted*
waveform (`bg/base`), with focus as a `text/primary` double-line ring. Drag today: press on a
selected cell arms a drag; crossing a threshold begins it; leaving the client rect hands off to
OS drag-out (`drag_out::decideGesture`); a drop on a tab / the other region moves (or copies on
Ctrl) the samples to that bank. **There is no same-bank in-grid reorder today.**

### Drag disambiguation (F3 — SETTLED 2026-07-27)

In-grid reorder must coexist with the existing internal bank-move/copy drag and OS drag-out.
**Precedence (one clean rule, evaluated live during the drag):**
1. **Pointer leaves the client rect → OS drag-out** (unchanged; `drag_out::decideGesture` wins
   first — the existing invariant #4 boundary).
2. **Else drop lands on a tab / the OTHER region's bank → move/copy** (unchanged; Ctrl = copy).
3. **Else drop lands within the SAME bank's own grid → reorder-to-slot** (new).
   - Onto an **empty** slot → place there.
   - Onto an **occupied** slot, **no modifier** → insert-before-and-shift-tail (the default,
     above).
   - Onto an **occupied** slot, **Alt held** → **REPLACE** the occupant (below).

So: leave-client wins → else other-bank wins → else same-bank-grid = reorder. The precedence is
encoded in a **pure decision helper** (mirror `drag_out::decideGesture`); the shell reads the
live pointer + focused region + client rect + **modifier state (Alt)** and calls it. This keeps
the reorder gesture from ever stealing an intended bank-move or OS-drag, and keeps a same-bank
in-grid drag from being mis-read as a no-op (today a same-bank drop is a no-op; L7 gives it
reorder meaning).

**Alt+drop-onto-occupied = REPLACE (SETTLED 2026-07-27).** Holding **Alt** at drop over an
occupied slot **replaces the occupant** instead of inserting-and-shifting. Replace semantics,
precisely:
- The replaced sample is **removed from THAT bank's index only** — same semantics as the existing
  remove-from-bank verb (`BankBook::removeSample` index-only). **The file stays on disk;** the
  owned-manifest and Phase R prune govern its bytes. If the replaced sample's last reference
  disappears, that is exactly the existing cross-bank-reference story (`hashReferencedElsewhere`
  reports whether the hash is still referenced elsewhere; prune later reclaims a now-orphaned
  owned file). Replace introduces **no new deletion authority** — it never touches the disk.
- The dragged sample then takes the vacated slot (the slot's position is preserved; only its
  occupant changes).
- **Pool case (un-evacuable pool — SETTLED rule).** The pool's privileges (un-deletable,
  un-renamable, **un-evacuable**, never zero banks) are enforced in `bank_book`. **Alt+Replace is
  allowed in the pool only when it does not violate a pool privilege.** Concretely: replacing a
  pool entry is an index-only removal of that pool sample; it is **permitted** as long as it does
  not empty the pool below the pool's floor and does not remove the *last* reference in a way the
  pool's rules forbid. The consistent rule the model enforces: **the replace's index-removal step
  is the same operation as remove-from-bank, and it must pass the same pool-privilege guard that
  remove already applies — if remove-from-pool would be rejected for that sample, Alt+Replace over
  it is rejected too** (the drop falls back to a no-op; the pool-privilege guard is reused
  as-is — confirmed at build). No special pool-only replace path; one rule, guarded by the
  existing pool invariants.

**Drop-result cursor cues (SETTLED 2026-07-27 — REAPER-idiomatic special cursors).** During a
drag the cursor must indicate **what the drop will do**, following REAPER's idiomatic use of
distinct action cursors. The cue set:
- **Reorder-to-slot** (within the same bank's grid) — a move/reorder cursor.
- **Move/copy to another bank or tab** — the move (or copy, when Ctrl is held) cursor, matching
  the existing internal-drag semantics.
- **OS drag-out** (pointer left the client rect) — the OS copy/drag cursor (owned by the OS drag
  loop once handed off).
- **Replace** — a distinct replace cursor, shown **only when Alt is actually held over an
  occupied slot** (i.e. only when precedence resolves to the Alt+replace case). It must not appear
  over an empty slot or when Alt is not held.

**Shell mechanism:** the shell sets the cursor via Win32/SWELL `SetCursor`. SWELL stock cursors
were chosen at build (Reorder→`IDC_SIZEALL`, Move→`IDC_HAND`, Copy→`IDC_UPARROW`,
Replace→`IDC_SIZEWE`; no custom cursor load/synthesis required). **The *decision* of which cue
applies stays in the pure gesture/disambiguation helper** — the same helper that resolves
precedence returns the resolved gesture (reorder / move / copy / os-drag-out / replace), and the
shell maps that pure result to a cursor. No cue logic in the shell; the shell only owns the
`SetCursor` call and the cursor resources.

## Precision / invariant implications (what Phase L does NOT change)

- **The pure/shell split holds.** All layout/hit-test stays in pure CTest-covered geometry
  modules; the kit's *draw* half is shell, its *geometry* half is pure — even where a WDL
  piece is reused (DS-1). No hit-test math moves into untestable code.
- **RT discipline untouched.** The kit is draw-thread only; nothing here touches `process`
  or any off-thread reload handoff (a Phase S concern surfaced at L3).
- **Read-only-over-bank untouched.** This is look-and-feel; no data-ownership change.
- **The capture/placement load-bearing principle is untouched.** Phase L draws; it does not
  capture, place, or mutate the bank.
- **VST3 class UID / component-state contract unchanged** (Phase S concern; noted for L3).
- **Windows-only (D5).** Font/GDI/HFONT choices assume Windows; no cross-platform font
  fallback concern.

## Non-goals / guardrails

- **No external UI framework.** iPlug2 / JUCE / VSTGUI are rejected (DS-1). LICE + reused
  WDL pieces are the toolkit; reject any path that pulls in a new framework.
- **No hit-test geometry in untestable shell code.** Even when reusing a WDL piece, layout/
  hit-test math stays in pure CTest-covered modules (DS-1 caution). Reject a control whose
  adoption would move geometry into the shell without a pure test seam.
- **L2 does not restructure the panel bones.** The vertical-split / grid / tab structure is
  sound and stays; L2 designs the *layout of the button inventory around it* (DS-3). A
  ground-up structural rework of landed Phase-B panel structure is out of scope.
- **L3 does not build on dev until Phase S lands there.** The gate is explicit; do not chase
  Phase S files on dev.
- **A visual refresh is not a compat event.** VST3 class UID, command-id strings, ext-state
  namespaces, and component-state contracts are unchanged by Phase L.
- **Verify LICE/WDL/SWELL surfaces** against `vendor/WDL` before use.

---

# Structural reorganization — reorg spec (Phase Q — Quality)

> **New pillar, own lettered phase, and the LAST structural pillar.** Phase Q is a **pure
> structural refactor** of `src/` — more encapsulation, granular namespaces, `core/`/`shell/`/
> `app/` subdirectories — against a stated quality bar (*"mtytel Vital is my code reference for
> quality"*), to bring the codebase "into the realm of something I can stand to look at." It
> **ships no feature and changes no behavior**: the test suite passing unchanged is the proof of
> correctness. Namespaced **`Q` (Quality)** — M/D/B/R/V/S/L taken; `Q` names the end (the quality
> bar), the reorg being the means. Product framing, the Vital-grounded target shape, the
> grep-verified SOLID audit (the evidence base), and the fork record (Q-1..Q-6):
> `docs/product/code-organization.md`. When a point lands, doc-keeper moves it to `COMPLETED.md`.
>
> **Phase Q opens with a pre-restructure audit (Q-W0 — added 2026-07-27).** Before any structural
> point (Q-W1+), Phase Q runs a **functional + DSP quality audit** that produces a written, triaged
> findings report — a functional-correctness/algorithm-quality complement to the SOLID/naming audit
> below. **Q-W1 is gated on Q-W0's triage being complete and Daniel signing off on each finding's
> disposition** (fix-now vs. document-and-defer). Spec: §"The pre-restructure audit wave (Q-W0)"
> below. **STATUS (2026-07-28): Q-W0 COMPLETE and SIGNED OFF — all 59 dispositions approved; the
> Q-W1 sub-gate is satisfied once the six approved fix-now remediations land (in flight on
> `pq-w0-fixes`). The audit's plan reshape is folded into this spec: Q-W2 6→8 seams, NEW wave
> Q-W2v (parallel with Q-W2), Q-W3 3→4 hoists + riders, Q-W5 + the ext-state-loop dedupe.**

## What it is

A directory + namespace + file-split reorganization that makes ReaSampler's **already-real,
CMake-enforced** architecture **legible in the code's shape**. The pure/shell split exists (30
pure static libs, each with its own test executable, none linking a REAPER SDK) but is invisible:
all 45 files sit in **one flat `src/`**, all 37 headers in **one flat `reasampler` namespace**,
four modules have grown into god-modules, and the JSON parser is copy-pasted across four models.
Phase Q gives the existing subsystem grouping — model / view / capture / audio / ui / reclaim /
version — a **structural home** (directories + namespaces), splits the four god-modules along
validated seams, and extracts the duplicated JSON into one pure module. Nothing about the
architecture *changes*; it becomes *visible*. This is why the phase can be zero-runtime-cost and
CTest-green throughout: the seams already exist in the link graph; Phase Q draws them where a
reader sees them.

## The pre-restructure audit wave (Q-W0)

Phase Q **opens** with `Q-W0` — a thorough **static/functional audit** that runs before any
structural point (Q-W1+) moves a single file. It is the *functional-correctness and
algorithm-quality* complement to the grep-verified SOLID audit (§"The evidence base" in
`docs/product/code-organization.md` §2) and naming audit (§2b): those ground *where responsibilities
live* and *what things are called*; Q-W0 grounds *does the code do the right thing, and does it do it
well.* It exists because the structural reorg is the wrong moment to discover a bad algorithm — a
reinvented wheel or a numerically-fragile DSP path should be eliminated or consciously documented
**before** it is relocated, re-namespaced, and split, not carried forward untouched into a tidier
tree. Bringing the code "into the realm of something I can stand to look at" is not only a matter of
shape; it is also a matter of the code being *functionally sound*.

**STATUS (2026-07-28): Q-W0 is COMPLETE — audit run, triage done, sign-off given.** Four parallel
tracks (T1 DSP, T2 architecture, T3 env-coupled constants, T4 sizing + placement), **59
findings**; report: `docs/product/code-quality-audit.md`, appendices:
`docs/product/audit-notes/q-w0-t{1..4}-*.md`. Daniel approved **every disposition as proposed** on
2026-07-28. Six findings are fix-now *in Q-W0* — **T1-01** (linked-lag stereo splice alignment),
**T1-03** (Preserve prime bound + immediate `freezeTail()`), **T1-09** (`declickR_` dead-state
removal, riding the `sampler_core` edits), **T2-01(a)** (provenance wire-cursor hardening
backport), **T3-01** (gain-ramp seconds), **T3-03** (fade-ceiling seconds) — in flight on branch
`pq-w0-fixes`; **the Q-W1 sub-gate is satisfied once they land** (each with its module's CTest
target green; the audible DSP fixes with a stated before/after listening check). All other
fix-nows are assigned to the wave that already opens their file and are recorded in the wave specs
below. **The Q-11 question is answered:** the correlation-aligned SOLA pitch engine is **sound —
no technique replacement (phase-vocoder / WSOLA) warranted**; every pitch finding is a bounded
in-technique fix or a documented operating limit.

**Audit scope — the named surfaces:**

1. **DSP / audio, close eye on pitch.** Assess *algorithm quality* — correctness, artifacts,
   numerical robustness, interpolation quality, and reinvented-wheel-vs.-established-technique — on:
   - `src/vst/pitch_shift` — the hand-rolled OLA pitch-preserve engine: window/overlap choice, phase
     coherence, transient and formant behavior, buffer-edge handling. **The highest-priority DSP
     surface** (Daniel: "a close eye on the Pitch stuff").
   - `sampler_core` — repitch ratio math, interpolation order/quality, loop-point-aware sustain
     crossfade, and voice-stealing correctness (clicks/discontinuities on steal).
   - `peaks` — envelope min/max binning correctness.
   - `wav_trim` — the realtime-tail decay-scan threshold + truncate plan.
   - the capture / tail paths — any DSP-adjacent arithmetic in capture range/tail handling.
2. **Architecture smells.** Duplicate code, reinvented wheels, poor abstractions, and leaky
   pure/shell boundaries (a `core/` file reaching a REAPER/host type; geometry or algorithm math
   sitting untestable in a shell instead of a pure module). This overlaps the SOLID audit's territory
   but targets the *functional* smell, not the responsibility-placement smell — Q-W0 reports what
   §2/§2b did not.
3. **Env-coupled-constant domain-modeling smells (explicit category).** ANY value stored in a
   frame / rate / DPI / tick-coupled domain that should instead be stored **rate-free and resolved at
   the point of use** is a domain-modeling smell — *store rate-free, resolve at use*, **not** "rescale
   by the rate." This is grounded in the load-bearing invariant that wall-clock times are stored as
   rate-free **SECONDS** resolved against the live project rate (`sample_map`), with **NO hardcoded
   sample rates in `src/`** (Daniel's standing ruling). There was a prior incident on exactly this —
   envelope times stored in the frame domain — which is why it is a first-class audit category, not a
   footnote. Sweep at least: envelope times, loop points, fade lengths, tail lengths, and any UI
   geometry constant that silently bakes in a DPI or rate.

**Deliverable + acceptance:** a **written findings report** exists covering the named surfaces;
**every finding is triaged** into *eliminate-before-restructure* (fix-now) or *document-and-defer*
(with a one-line rationale so the deferral is a decision, not an omission). Fix-now findings are
remediated **in Q-W0**, or folded into the downstream wave that already opens the file (recorded per
finding) — they are **not** silently deferred into the structural waves. Any behavior-changing
remediation lands with the module's CTest executable green, and where a DSP path changes audibly, a
stated before/after listening or null check. **The gate to begin Q-W1 is: triage complete and Daniel
signed off on every disposition.**

**Relationship to the structural waves:** Q-W0's findings may **add or reshape** downstream
Q-W1..Q-W6 points (e.g. an algorithm rewrite that changes a module's shape, or a domain-modeling fix
that changes a payload). Those reshapes are folded in before Q-W1 begins. Q-W0 is thus both the entry
point and a scoping input to the rest of the phase.

**Report home (Q-10 — SETTLED, Daniel 2026-07-27): a committed doc.** The findings report lives as a
committed doc under `docs/product/` — `code-quality-audit.md`, alongside the SOLID/naming audit that
already lives in `docs/product/code-organization.md`. It sits beside the existing audit, travels with
the tree, and each finding's disposition is reviewable in one place. A tracked issue list was set
aside — the audit is a one-shot pre-reorg sweep, not an ongoing backlog. The Q-W0 "Triage + report"
step writes this file. See `docs/product/code-organization.md` §2c.3.

**Pitch-remediation depth (Q-11 — SETTLED, Daniel 2026-07-27): defer to findings.** How deep the OLA
pitch-preserve remediation goes is decided by what Q-W0 finds, not pre-committed. Default is
**document-and-defer**; only if the audit surfaces artifacts that matter is a **bounded fix** (tune
window/overlap/edge handling) weighed **before** a **technique replacement** (phase-vocoder / WSOLA).
A technique replacement reshapes `pitch_shift`, would spill a downstream Q-wave point, and is
therefore **a Daniel decision at triage time, not an automatic Q-W0 action**. See §2c.4.

## The quality bar — Vital (read from its actual `src/` tree)

Vital (`github.com/mtytel/vital`) groups its synth by **subsystem** — `common/` `synthesis/`
`interface/` `plugin/` — with `synthesis/` further subdivided by function (`synth_engine/
modulators/ filters/ effects/ producers/ framework/ lookups/ utilities/`). The grouping principle
is **layered functional architecture**: the directory tree *is* the architecture diagram; you read
the subsystem map off the folders. ReaSampler adopts the *pattern* (directory = architecture),
adapted to its own most load-bearing invariant — the pure/shell split — as the top level (see
below). Vital is GPLv3; the borrowed artifact is the **structural pattern**, not code.

## Settled decisions (Q-1/Q-10/Q-11 settled 2026-07-27; Q-5/Q-6/Q-8/Q-9 + the audit's §4 forks settled 2026-07-28 — REC history kept; see `docs/product/code-organization.md` §6 and `docs/product/code-quality-audit.md` §4)

- **Q-1 — namespace letter. SETTLED: `Q` (Quality).** Point-id family `Q1..Qn`, wave prefixes
  `Q-W0` (the pre-restructure audit) then `Q-W1..Q-W6` (the structural reorg; + **`Q-W2v`**, the
  VST god-module wave added at the Q-W0 sign-off, 2026-07-28). `O` (Organization)
  was set aside: the glyph reads ambiguously against zero in
  point ids, and "Organization" undersells a phase measured against a *quality* bar.
- **Q-2 — JSON extraction in scope + first. REC: yes.** The 4× duplicated `Parser` is the largest
  DRY+SRP violation and is entirely off the hot paths — the ideal safe, high-leverage opener
  (Q-W1).
- **Q-3 — directory shape. REC: `core/`/`shell/`/`app/` top-split, subsystem dirs beneath.** Top
  level by the pure/shell discipline (so the invariant is *structural*, not merely conventional),
  subsystem grouping one level down. Preferred over pure-Vital subsystem-first because ReaSampler
  has a pure/host split Vital lacks and that split is the invariant most worth protecting
  structurally.
- **Q-4 — sub-namespace to match sub-directory. REC: both.** `reasampler::model`/`view`/`capture`/
  `audio`/`ui`/`reclaim`/`version`/`json`. Directory and namespace agree; a symbol's home is
  unambiguous from either.
- **Q-5 — god-module split granularity. REC: to the audit's named seams, no finer.** Well-factored,
  not atomized. **SETTLED (Daniel, 2026-07-28): seams-by-responsibility with the Q-W0 T4 seam
  lists adopted** — `bank_panel` 6→8 seams (+ `panel_layout`, `panel_drag`; T4-01),
  `capture_orchestrator` further split with `capture_batch` (T4-02) — **and the ~600-line file
  ceiling is an acceptance criterion on every split wave**: seams are the method, the ceiling is
  the bar; arbitrary bisection to hit the number is rejected. One documented exception:
  `sampler_core.cpp` stays whole (T4-14/T4-27).
- **Q-6 — OCP registration-table. REC: in scope, last (most droppable if narrowing).** **SETTLED
  (Daniel, 2026-07-28): in scope, last wave, as planned.**
- **Q-7 — naming rides the relocation waves, no dedicated naming wave. REC: yes** (forced once
  Q-3/Q-4 settle — a rename is near-free during relocation, near-pure-churn standalone).
- **Q-8 — class/module renames beyond the free namespace fix. REC: fix the two that actively
  mislead** — `BankIndex`→`BankModel` (the `bank_model.h`/`BankIndex` file↔class word-mismatch)
  and the unified JSON parser → `json::Reader`/`json::Writer` (or `json::Parser`) — **leave the
  merely-quirky** (`Book`/`Bank`/`Index`, `Sample`/`AudioSample`, `MinMax`, `KitBox`). Daniel's
  to call. **SETTLED (Daniel, 2026-07-28): both renames** — `BankIndex`→`BankModel` (W1) and the
  JSON parser minted as `json::Reader`/`json::Writer` (W1). From the audit, additionally:
  **`ICaptureBackend` is deleted in Q-W3** (T4-26 — one deriver, zero polymorphic call sites; the
  CLAUDE.md/CONTEXT "two backends behind one interface" correction **rides Q-W3's own commit**,
  not earlier).
- **Q-9 — align the `capture_realtime` (shell) / `realtime_record` (pure) word-order inversion.
  REC: yes, during Q-W3** (a free rider — W3 already hoists the realtime lifecycle). **SETTLED
  (Daniel, 2026-07-28): yes** — the pure module takes the stem `capture_realtime`, the shell
  takes the suffix (the `drag_out`↔`drag_out_win` model), during W3.
- **Audit §4a — VST placement. SETTLED (Daniel, 2026-07-28): T4-18** — `src/vst/` integrates into
  the single `core/`/`shell/` top split as `core/instrument/{engine,map,ui}` +
  `shell/instrument/`. One rule, no special case: a file's directory says whether it may touch a
  *host* type (REAPER **or** VST3 SDK); the artifact boundary is a link-graph fact the sources
  already straddle. The T4-19 artifact-first subtree was set aside. Directory map below updated.
- **Audit §4e — WAV/RIFF consolidation moment. SETTLED (Daniel, 2026-07-28): a named rider on
  Q-W3** — one pure **`wav_codec`** owner (chunk walker + layout + build + patch), absorbing the
  T4-10 ingest extraction (T2-08 / T4-23 / T4-10). The dedup-by-hash / null-test maintenance
  surface gets exactly one implementation.
- **Audit §4f — Q-W2v scheduling. SETTLED (Daniel, 2026-07-28): parallel with Q-W2** (different
  artifact, zero file overlap); the serial "Q-W7" alternative was set aside.
- **Audit §4b/§4c/§4d — the Q-W0 fix-now set. SETTLED (Daniel, 2026-07-28): all approved
  fix-now** — T1-01 + T1-03 (with T1-09 riding), T2-01(a), T3-01 + T3-03; in flight on
  `pq-w0-fixes`; landing them closes Q-W0 and opens Q-W1.

## The directory + namespace map (Q-3 / Q-4)

Top-level by the pure/shell discipline; subsystem dirs beneath `core/`; namespaces mirror
directories.

**`core/` (pure, no REAPER types, unit-tested — `reasampler::<subsystem>`):**
- `core/model/` (`::model`) — `bank_model`, `bank_book`, `owned_manifest`, `provenance`
- `core/view/` (`::view`) — `view_mode_model`, `view_tree`, `lane_keys`, `mode_switch`
- `core/capture/` (`::capture`) — `render_settings`, `batch_capture`, `tail_control`,
  `capture_paths`, `wav_trim`, `insert_plan`; **post-Q-W3** `wav_codec` (the one pure WAV/RIFF
  owner — audit §4e rider)
- `core/audio/` (`::audio`) — `peaks`
- `core/ui/` (`::ui`) — `theme`, `component_geometry`, `bank_grid`, `tab_strip`, `action_buttons`,
  `prune_button`
- `core/reclaim/` (`::reclaim`) — `prune_reconcile`
- `core/version/` (`::version`) — `app_version`
- `core/json/` (`::json`) — **NEW** — extracted parser/serializer, minted as
  `json::Reader`/`json::Writer` (replaces the 5 duplicate hand-rolled decoders — the four
  `Parser`s + `tail_control`'s, T2-02)
- `core/instrument/` — **T4-18 SETTLED (Daniel, 2026-07-28)** — the VST artifact's pure side
  joins the one top split (directory = "may it touch a host type", REAPER *or* VST3 SDK):
  - `core/instrument/engine/` — `sampler_core`, `pitch_shift`, `velocity_curve`, `master_gain`
  - `core/instrument/map/` — `sample_map` (+ `component_state_io` post-Q-W2v), `bank_sync`,
    `bridge_marshal`, `note_entry`, `trigger_seam`
  - `core/instrument/ui/` — `editor_geometry`, `keyboard_strip`, `waveform_view`,
    `capture_browser`, `browser_scroll`, `param_slider`, `knob_deck`, `curve_popup`,
    `envelope_overlay`, `envelope_edit`, `embed_strip`

**`shell/` (REAPER-facing — subdir by subsystem, namespace as house style prefers):**
- `shell/capture/` — `capture`, `capture_realtime`, `provenance_shell`, `track_guid`, `item_read`;
  **post-Q-W3** `capture_orchestrator`, `capture_batch`, `scope_resolve`, `realtime_lifecycle`,
  `capture_realtime_finalize` (with the Q-9 stem/suffix rename)
- `shell/panel/` — `draw_kit`; **post-Q-W2** `panel_render`, `panel_thumbnails`,
  `panel_audition`, `panel_input`, `panel_layout`, `panel_drag`, `panel_bank_ops`,
  `panel_window` (from `bank_panel` — eight seams, T4-01)
- `shell/view/` — `view`
- `shell/persist/` — **post-Q-W5** `session`, `ext_state_io`, `prune_fs` (from `persist`)
- `shell/actions/` — `drag_out_win`; **post-Q-W4** `design_view_actions`, `bank_actions`,
  `prune_action` (from `actions`)
- `shell/instrument/` — `reaper_bridge`, `reasampler_embed`, `vst_entry`, `reasampler_vst.h` /
  `reasampler_uid.h`; **post-Q-W2v** the editor TUs (`editor_session` / `editor_controls` /
  `editor_paint_sample` / `editor_paint_browse_zone` / `editor_input_sample` /
  `editor_input_browse_zone` / `editor_platform` — `editor_layout` hoists *pure* →
  `core/instrument/ui/`, discharging T2-06) and the processor TUs (`processor_state` /
  `processor_reload` / lifecycle+`process()`)

**`app/`:** `main.cpp` (post-Q-W3: API-pointer ownership + `ReaperPluginEntry` + dispatch only).

**Collision sweep (before W1):** `Sample` (`::model`) vs `AudioSample` (`::audio` alias) vs the
unified `Parser` (`::json`) must not collide once flattened into granular namespaces; resolve by
subsystem home.

## The god-module split seams (Q-5 — SETTLED 2026-07-28: T4 seam lists adopted; ~600 ceiling is the bar)

Split each to the audit-validated seams, no finer — **and every shipped TU lands under the
~600-line ceiling** (the Q-5 settlement: seams are the method, the ceiling is the bar; arbitrary
bisection to hit the number is rejected; the one documented exception is `sampler_core.cpp`).
LOC figures updated to the Q-W0 T4 census (2026-07-28):

- **`bank_panel.cpp` (3459 LOC → `shell/panel/`, Q-W2 — eight seams, T4-01):** `panel_render`
  (draw/paint) / `panel_thumbnails` (compute+cache) / `panel_audition` (preview engine — **hot
  path, direct call-through**) / `panel_input` (mouse/key/wheel + new-content detection) /
  **`panel_layout`** (toolbar/footer/menu rects + row/cluster builders + region geometry — new
  seam) / **`panel_drag`** (the card-drag/hover state machine, pure mirror `card_drag` — new
  seam) / `panel_bank_ops` (bank CRUD — the single owner W4 dedupes against) / `panel_window`
  (lifecycle + OS drag-out/drop-target). Without the two new seams, `panel_render` (~700) and
  `panel_input` (~800) would ship over the ceiling. Split the fat `bank_panel.h` per seam (I).
- **`main.cpp` (1897 LOC → hoist to `shell/capture/`, Q-W3 — four hoists, T4-02):**
  `capture_orchestrator` (`RunCapture`/`captureAndIndexOne`/`renderOffline`/single-capture +
  realtime/insert action bodies — lands ~450) / **`capture_batch`** (batch family +
  `RunRecaptureFromSource` + the two RAII selection guards — new hoist; recapture is
  planner-driven like batch and shares the guard machinery) / `scope_resolve` (range/razor/track
  resolution + provenance assembly inputs) / `realtime_lifecycle` (state machine + globals).
  `FxBypassGuard` moves out but **stays stack RAII** (precision-critical). `main.cpp` → `app/`,
  reduced to pointers + entry + dispatch. **Wave riders (SETTLED 2026-07-28):** delete
  `ICaptureBackend` + correct the CLAUDE.md/CONTEXT description in the same commit (T4-26);
  shared `stampCaptureSample` epilogue dedupe (T2-09); `capture_realtime_finalize` split with
  the Q-9 rename (T4-08); `makeUniqueTag` per-session monotonic counter (T1-11); the pure
  `wav_codec` consolidation (audit §4e).
- **`actions.cpp` (1016 LOC → `shell/actions/`, Q-W4 — T4-03: seams unchanged, still
  sub-600):** `design_view_actions` /
  `bank_actions` / `prune_action` (`doBankPruneFolder` — the single file-deletion action). Dedupe
  `promptText`/`mintBankId` + bank verbs against `panel_bank_ops`.
- **`persist.cpp` (852 LOC → `shell/persist/`, Q-W5 — T4-04: seams unchanged; the pS-usage
  growth landed exactly where this wave isolates it):** `session` (lifecycle/poll +
  `BeginLoadProjectState` reload hook) / `ext_state_io` (serialization bridge + GUID minting +
  folder relocation) / **`prune_fs`** (prune scan + `deleteOrphanFile` via `SHFileOperationW` —
  the isolated single file-deletion authority). **Wave rider (T2-04):** the `GetProjExtState`
  grow-loop ×3 dedupes onto `bridge_marshal`'s generalized retry policy — `usage_scan`'s
  prune-safety-adjacent copy included.
- **`reasampler_editor.cpp` (3065 LOC — the largest file in the repo → `shell/instrument/`,
  Q-W2v — eight TUs, T4-11; split axis = the Sample/Browse/Zone face structure):**
  `editor_session` / `editor_controls` / `editor_layout` (**pure-candidate hoist** →
  `core/instrument/ui/`, `editor_geometry` the named owner — discharges T2-06's
  stranded-layout-math finding) / `editor_paint_sample` / `editor_paint_browse_zone` /
  `editor_input_sample` / `editor_input_browse_zone` / `editor_platform`. Rider: adopt the pure
  `ThumbnailKey` on the VST side while the editor is open (T2-10).
- **`reasampler_processor.cpp` (1164 LOC → `shell/instrument/`, Q-W2v — three TUs, T4-12):**
  `processor_state` / `processor_reload` / lifecycle+`process()` kept whole. **No virtual seam
  on the atomic-pointer-swap reload pattern (T4-29).**
- **`sample_map` (970 LOC + 708-line header → Q-W2v, T4-13 ≡ T2-07):** resolution core vs the
  **`component_state_io`** binary ComponentState codec (+ matching header split) — the codec
  grows every envelope bump (v6→v11 in one quarter); the extension stops linking the whole voice
  engine to serialize one preset blob. The `core/wire` LE byte-codec template
  (`putLE`/`readLE`, T4-20) lands with it.
- **`sampler_core.cpp` (968 LOC + 762-line header — Q-W2v, T4-14/T4-27): the TU stays WHOLE —
  the documented hot-path exception to the ~600 ceiling.** Envelope `tick()`s run
  per-voice-per-sample; same-TU definition is what lets the compiler inline the stack (no LTO in
  the build); a by-class split is the exact heuristic-(3) dispatch blowout. The header splits
  into `zone_params.h` + `sampler_core.h`. Recorded here so nobody "fixes" it later.

## The JSON extraction (Q-2 / Q-W1)

Extract one pure **`core/json`** (`::json` — minted as **`json::Reader`/`json::Writer`**, Q-8
SETTLED 2026-07-28): parser (`parseString`/`parseInt`/`parseKey`/
`skipValue` + escape) + serialize/emit helpers. Rewire `bank_model`, `bank_book`,
`view_mode_model`, `owned_manifest`, **and `tail_control` (T2-02 — the fifth hand-rolled decoder
the §2 audit undercounted)** onto it and **delete all five hand-rolled decoders**.
Round-trip output must be **byte-identical** to before — this is a structural dedupe, not a format
change. Off all hot paths (serialization runs at save/load, never per frame) — safe to abstract
freely. **W1 siblings (from the Q-W0 sign-off):** the shared `readFileBytes` pure helper
(T2-03); the length-prefixed wire-`Cursor` collapse into one shared wire codec beside
`core/json`, consumed by `provenance` / `assignment_request` / `sample_usage` /
`parseBankGeneration` (T2-01(b) — the structural half; the hardening backport lands in Q-W0);
the **concrete** `ui::Rect` unification + `contains()` + per-role aliases, retiring the
XYWH-vs-LTRB fork — NOT a template (T2-05 ≡ T4-21), with the `clamp01` rider (T4-24) and the
`hitIndex` template only as an opportunistic follow-on (T4-22); the `slot_map` extraction
(T4-05) and optional `view_mode_model` planner split (T4-06) riding files W1 already opens; the
relocation scope grows to the ~20 clean VST pure libs under `core/instrument/` (T4-18).

## The OCP registration-table (Q-6 / Q-W6)

Replace the ~350-line hand-written **non-table** action registration blocks (isolated in
`app/main.cpp` after Q-W3) with a **data-driven registration table**, so adding an action edits one
place, not four parallel `Register("command_id"/"gaccel"/"hookcommand")` sites. Unload
mirror-unregisters from the same table. Command-id + display strings stay **byte-identical**
(FOREVER-STABLE, per-channel — the Phase V V4 contract). Also split residual fat headers
(`capture.h`/`persist.h`) alongside their TU splits (I).

## The naming dimension (Q-7 / Q-8 / Q-9 — grep-verified audit in `docs/product/code-organization.md` §2b)

Alongside giving symbols a directory + namespace *home* (Q-3/Q-4), Phase Q gives
inconsistently/poorly-named symbols a consistent *name* — same Vital bar, orthogonal to the SOLID
focus. The audit (2026-07-27) is grep-verified; the load-bearing findings:

- **Already consistent — preserve verbatim:** the geometry-mirror verb vocabulary
  (`compute<Thing>Rects`/`compute<Thing>` + `hitTest<Thing>`, verified across `bank_grid` /
  `mode_switch` / `action_buttons` / `action_bar` / `tab_strip` / `prune_button` / `overflow_menu` /
  `footer_bar` / `card_drag` / `component_geometry`) and the uniform `<module>_tests` CTest suffix.
- **Collisions — resolved by the Q-4 sub-namespaces for free:** four `class Parser`
  (`bank_model.cpp` / `bank_book.cpp` / `owned_manifest.cpp` / `view_mode_model.cpp`) collapse to
  one `json::Parser` in Q-W1; the shared pure-UI rect types `FooterRect` / `ButtonRect` (defined in
  `prune_button.h`, reused by `footer_bar.h` under an explicit hand-collision "NAME NOTE") get one
  `ui::` owner; `Sample` (`model::`) vs `AudioSample` (`audio::`) de-collide by home.
- **Genuine renames (Q-8/Q-9 — SETTLED, Daniel 2026-07-28: all land):** `BankIndex`→`BankModel` (the `bank_model.h`
  file↔class word-mismatch — the worst legibility wart, rec: rename the class so the model family
  reads `BankModel`/`BankBook`/`ViewModeModel`); the unified JSON parser named `json::Reader`/
  `json::Writer` at W1 mint; align `capture_realtime`(shell)/`realtime_record`(pure) to the house
  shell↔core convention (`drag_out`↔`drag_out_win` is the model) during Q-W3.
- **Sequencing (Q-7):** renames ride the wave that already relocates/splits the file — **no
  dedicated naming wave.** Rule: *no rename lands on a file the wave isn't otherwise touching.* W1
  carries the collision + model-class renames; W2 the `panel_*` names; W3 the realtime word-order
  fix. Zero-behavior-change like the rest of Phase Q; verified by the module's own test executable.
- **Out of scope (never renamed):** the FOREVER-STABLE contract strings are not C++ symbols —
  `command_id` strings, action display names, ext-state namespace (`"reasampler"`/`"reasampler_beta"`)
  and keys, the `reasampler:` lane prefix, the VST3 class UID. Renaming a C++ class is orthogonal
  to these literals (audit §2b.5).

## Performance guardrails (HARD CONSTRAINT — Daniel's non-negotiable)

The reorg must cost **zero runtime.** The two hot paths must keep their exact call/inline shape;
the following are acceptance criteria on every point:

- **`peaks` envelope compute** (`computeEnvelope` / `lastFrameAboveThreshold` over full PCM): **NO
  virtual dispatch, NO `peaks` interface, NO added header→TU indirection.** `computeEnvelope`
  stays a **free function on `const std::vector<float>&`** so it inlines as today. Relocate +
  namespace only; never wrap in an abstraction.
- **Audition / preview**: `panel_audition` may be its own TU (Q-W2), but the call stays a **direct
  call-through, not virtual.**
- **Realtime-capture tick**: keep the idle fast-path a **single pointer test**;
  `realtime_lifecycle` (Q-W3) must not change the tick's branch shape.
- **JSON extraction** is **off all hot paths** — safe to abstract freely (why Q-W1 is the safe
  opener).
- **`FxBypassGuard`** runs per-capture, not per-frame — keep it **stack RAII** when it moves out
  of `main.cpp` (Q-W3); never heap-allocate or virtualize it.

**Net:** every recommended split falls on a cold path or preserves call/inline shape on the two
hot ones. *A split that would add a hot-path indirection is out of scope — rework it or drop it.*

## Structural heuristics (Daniel, 2026-07-28 — acceptance criteria phase-wide)

Three heuristics postdate the original framing and bind every wave. They **generalize** the
three-hot-path performance guardrail above — they do not replace it:

1. **More directories is a must; more files is good; ~600-line file ceiling.** SRP applies to
   namespaces, encapsulation, and file organization alike. The ceiling is the *bar*, the audit's
   named seams are the *method*: a file landing over ~600 needs a responsibility seam, not an
   arbitrary bisection (bisection-to-hit-the-number is rejected). A documented hot-path
   exception (`sampler_core.cpp`, T4-14/T4-27) is legitimate; silent overshoot is not.
2. **Templates are the right tool for compile-time dedup — use them where earned.** The LE
   byte-codec `putLE`/`readLE` (T4-20) is earned: compile-time dispatch, zero runtime cost, off
   the hot paths. The rect family is NOT (T4-21): the types differ in name only, so one
   **concrete** `ui::Rect` — a template there would model nothing.
3. **SOLID is great, but saved CPU is better.** No dispatch-stack blowouts *anywhere* — not just
   the three named hot paths; prefer static polymorphism where the types are compile-time-known.
   The T4-27 warning is the canonical case: a by-class `sampler_core` split would put virtual
   envelope `tick()`s on the per-voice-per-sample path — exactly the blowout this forbids.

## The GATE (load-bearing — Phase Q is last)

Phase Q is **gated on the tree being otherwise quiescent.** Daniel's plain readiness target:
**"when Phase S and L3 are finished."** As of 2026-07-27 the outstanding work is precisely
**(1) Phase S** merged to dev (the large second-artifact branch, currently on the phase-s worktree)
and **(2) Phase L L3** merged to dev (the VST restyle, itself gated on Phase S). **L1/L2/L4/L5/L6/L7
have already landed** (see `COMPLETED.md`) — the earlier "L2 + L3" wording was stale and is
corrected to **L3 only**. **D2** is functionally complete (D2-W1..W3-B landed; its lone open item,
a per-track lane-split panel indicator, is *explicitly deferred*, not a blocking residual). **M9**
(slots) is **abandoned** (Daniel, 2026-07-27) — will not be built. D2 is named here only so that
*reactivating* its deferred panel indicator re-arms the quiescence condition; neither D2 nor M9
blocks the gate today.
*Why:* Phase Q touches **nearly every file in `src/`** (relocate, re-namespace, split the four
largest TUs, plus the §2b renames); every large in-flight branch (Phase S on its worktree, L3 once
it lands) is diffed against the *current flat layout*, so landing a rename-and-relocate-everything
reorg mid-flight forces every open branch through the worst conflict class — a combinatorial
re-resolution, not a linear one. Phase Q is *last* precisely because it reshapes the ground every
other pillar stands on: landing it early taxes every subsequent phase; landing it last taxes
nothing. Re-confirm quiescence against dev before Q-W1.

> **M9 disposition — resolved (Daniel, 2026-07-27): abandoned.** M9 is out; it will not be
> reactivated. The gate remains satisfied; no re-arm condition applies.

## Wave sequencing (each independently landable, CTest-green at every step)

Big-bang is rejected — the CMake per-module static-lib + per-module test-executable seams make a
file move + namespace change **mechanically verifiable** (`ctest --test-dir build` green or not, at
every commit), a property only an *incremental* reorg uses. Risk-ordered:

- **Q-W0** — **pre-restructure functional + DSP quality audit** (entry point; see §"The
  pre-restructure audit wave (Q-W0)"). Produces a written, triaged findings report; runs **first**
  and **gates Q-W1** — no structural point begins until the triage closes and Daniel signs off on
  every disposition. Fix-now findings are remediated here or folded into the wave that opens the
  file; the report may add/reshape downstream Q-W1..Q-W6 points before they start. **COMPLETE
  and signed off 2026-07-28; the sub-gate closes when the six fix-now remediations land
  (`pq-w0-fixes`).**
- **Q-W1** — safe opener: `core/json` extract (delete the 5 hand-rolled decoders — T2-02 adds
  `tail_control`) + impose the directory/
  namespace layout on the 30 clean pure libs + clean shells (pure relocation, no logic change).
  All later waves assume this layout. **Carries the naming collision fixes + the model-class
  renames (Q-8), which are free during this relocation.** **Scope grown by Q-W0 (2026-07-28):**
  + `readFileBytes` (T2-03), the wire-`Cursor` codec (T2-01(b)), the concrete `ui::Rect`
  unification (T2-05 ≡ T4-21) + `clamp01` (T4-24), the `slot_map`/planner riders (T4-05/T4-06),
  and the ~20 clean VST pure libs under `core/instrument/` (T4-18).
- **Q-W2..Q-W5 (+ Q-W2v)** — the god-module splits, risk-ordered (`bank_panel` →
  `main.cpp` → `actions.cpp` → `persist.cpp`), plus **Q-W2v** (NEW, added at the Q-W0 sign-off:
  the VST god-modules — editor eight TUs / processor three TUs / `component_state_io`;
  `sampler_core` TU whole, the documented exception), which **runs parallel with Q-W2**
  (different artifact, zero file overlap — audit §4f SETTLED). Q-W4 depends on Q-W2
  (`panel_bank_ops` dedupe target); Q-W5 best after Q-W4 (`prune_action` → `prune_fs` routing);
  otherwise parallel-safe.
  **Q-W2 carries the `panel_*` names; Q-W3 carries the `capture_realtime`/`realtime_record`
  word-order fix (Q-9) + the settled riders (`ICaptureBackend` deletion + doc correction,
  `wav_codec`, `stampCaptureSample` dedupe, T1-11, `capture_realtime_finalize`).**
- **Q-W6** — OCP registration-table + residual fat-header (I) splits. Depends on Q-W3 (registration
  code isolated first). Sequenced last; most droppable if narrowing.
- **Naming (Q-7): no dedicated wave** — every rename rides the wave already relocating/splitting
  its file; a rename that would touch an otherwise-untouched file is deferred.

## Precision / invariant implications (what Phase Q does NOT change)

- **The pure/shell split is strengthened, never dissolved.** Top-level `core/` vs `shell/` makes
  it *structural*; no file crosses the boundary; no `core/` file gains a REAPER type; the CMake
  per-module test executables stay green.
- **Every precision invariant holds.** Null test, bit-identical repeats, non-destructive capture,
  exact bounds — none is code Phase Q rewrites. `FxBypassGuard` moves but stays stack RAII with
  identical behavior.
- **Capture ≠ placement.** No hoisted `Run*` / `capture_orchestrator` path may gain an
  `InsertMedia` call during the split.
- **Single file-deletion authority is concentrated, never spread.** `prune_fs` (Q-W5) is the one
  module that deletes bytes; the reorg improves this invariant.
- **Relative-paths-only** in the persisted index — untouched.
- **On-the-wire/on-disk contract strings unchanged.** Command-id strings, action display names,
  ext-state namespaces, VST3 class UID are byte-identical (per-channel, per Phase V V4).
  Re-namespacing C++ symbols is orthogonal to these.
- **No behavior change.** Phase Q is a pure structural refactor; the test suite passing unchanged
  is the proof of correctness. A point that changes observable behavior has exceeded its charter.

## Non-goals / guardrails

- **No feature, no behavior change.** If a point ships anything user-visible, it is out of scope.
- **No hot-path indirection.** No virtual dispatch or header→TU indirection on `peaks`/audition/
  realtime-tick — ever (a hard acceptance bar, not advice).
- **No design-level (D-letter SOLID) rework.** `main`/`bank_panel` depending on concrete capture
  backends is a low-priority Dependency-Inversion concern — **out of scope** (a design change, not
  a reorg). Phase Q reorganizes; it does not re-architect interfaces. (Deleting the *dead*
  `ICaptureBackend` abstraction in Q-W3 is the opposite move — removing a false interface with
  one deriver and zero polymorphic call sites, T4-26 — and is in scope.)
- **No `peaks` data-ownership change.** `peaks` forcing a whole-file `std::vector<float>` copy on
  the thumbnail path is noted but **not touched** — reworking it risks the hot path.
- **No big-bang commit.** Every wave is independently landable and CTest-green; reject a change set
  that cannot be verified at each step.
- **Do not begin before the GATE.** Re-confirm the tree is quiescent (Phase S + L + D2 merged/closed;
  M9 abandoned) before any Q point. **And do not begin any structural point (Q-W1+) before the Q-W0
  sub-gate:** the audit's triage is complete and Daniel has signed off on every finding's disposition.
  (Sign-off given 2026-07-28; the sub-gate now closes when the six fix-now remediations land on
  `pq-w0-fixes`.)
- **Verify** the CMake `src/` path updates and the SWELL/LICE surfaces still resolve after
  relocation, as the existing build already requires.
