From 0ffa7a4e772090dbfd3b4cac36b338eeec327f8f Mon Sep 17 00:00:00 2001 From: daniel-c-harvey Date: Mon, 27 Jul 2026 11:57:27 -0400 Subject: [PATCH] docs(plan): archive Phase S (S3-S18) to COMPLETED; PLAN keeps only the deferred S13 relay stub --- COMPLETED.md | 703 ++++++++++++++++++++++++++++++ PLAN.md | 1163 ++------------------------------------------------ 2 files changed, 736 insertions(+), 1130 deletions(-) diff --git a/COMPLETED.md b/COMPLETED.md index 72e9329..fdf0ba2 100644 --- a/COMPLETED.md +++ b/COMPLETED.md @@ -1481,3 +1481,706 @@ placement behavior; the "capture ≠ placement" principle is untouched. meter stamp; SWELL stock cursors chosen (no custom cursor load/synthesis required); gap navigation = skip gaps (arrow keys skip empty slots); same-slot reorder = no-op. - New CTest targets `card_drag_tests`, `card_meta_tests`. + +--- + +# Phase S — MIDI-playback instrument (native VST3 sampler; a second build artifact) + +> **Landed on dev (merged 2026-07-27); DAW verification pending Daniel's smoke test.** +> S1–S18 are all on dev. The cross-artifact ingest relay (one S13 bullet) was explicitly +> DEGRADED and remains deferred in `PLAN.md`. Authoritative spec: **CONTEXT.md +> §MIDI-playback instrument — additive phase spec (Phase S)**. Product framing: +> `docs/product/midi-playback.md`. + +--- + +## S3 — pure sampler core (voice engine / envelope / keymap / repitch) +**Goal:** The REAPER-free **and** VST3-free sampler core — voice allocation/polyphony, +amplitude envelope (ADSR), key→sample and velocity→sample mapping (the keymap), +repitch/interpolation from root note, keymap resolution — unit-tested in CTest against +known signals. **The heart of the phase (D3); the mirror of +`bank_model`/`peaks`/`view_mode_model`/`bank_book`; test it hard.** The core is +invariant under the build-shape choice — no VST3 or REAPER type at its boundary. +CONTEXT.md §Phase S (pure core, module architecture). +**Verify:** CTest green. Voice allocation is correct under polyphony (note-on/off, +voice stealing where bounded); ADSR shape asserted against a known signal (mirror of +`peaks`); repitch from root note produces the expected pitch ratio; keymap resolution +maps a (note, velocity) to the correct sample/zone; the core takes and returns only +plain data (no VST3/REAPER types) — enforced by the test target linking neither SDK. +**Depends on:** S2 (consumes `rootNote` / loop points as core inputs). + +- [x] Voice engine: polyphonic voice allocation (note-on/off, bounded voice stealing), + per-voice state, mono-and-basic-polyphony sufficient for Tier 0. +- [x] Amplitude envelope (ADSR) math — asserted against a known signal. +- [x] Repitch/interpolation from root note (chromatic pitch ratio across the + keyboard); loop-point-aware sustain for held notes. +- [x] Keymap model + resolution: key ranges/zones (Tier-1 shape) and the + (note, velocity) → sample/zone query; Tier-0 chromatic-from-single-root as the + degenerate case. +- [x] Tests: voice allocation under polyphony + stealing; ADSR envelope shape; + repitch pitch-ratio correctness; keymap resolution (single-root chromatic + zoned); + core boundary is plain-data-only (no VST3/REAPER types). + +--- + +## S4 — Tier 0: "the bank plays" (single sample, chromatic) +**Goal:** The honest MVP — one bank sample mapped chromatically across the keyboard +from its root note, basic polyphony, a simple amp envelope, velocity→volume. Wire the +S3 core into the S1 VST3 shell over the live-state seam (bridge-read bank + audio via +the M4 project-relative path machinery). Editor deferrable behind a parameters-only +default view. CONTEXT.md §Phase S (Tier 0, seams). **Delivers the core promise.** +**Verify (in DAW):** on an instrument track, the VST3 plays a chosen bank sample +MIDI-triggered, repitched chromatically from its root note, with basic polyphony, +an amp envelope, and velocity→volume; it reads the live `"reasampler"` bank via the +bridge and resolves the WAV audio the same project-relative way `persist` does; +following the active project works; it never captures and never inserts into the +arrange (read-only over the bank). +**Depends on:** S1, S2, S3. + +- [x] VST3 `process` marshalling: read MIDI note-on/off/velocity off the event bus, + drive the S3 core, write per-voice audio to the output bus. (Block-granular event + timing at Tier 0; sample-accurate offset scheduling is a later tier.) +- [x] Live-state seam: read the bank index + selected sample's root note from + `"reasampler"` ext-state via the bridge; resolve the WAV audio path the M4 + project-relative way (shared convention with `persist`, not re-implemented — the + parent-of-.rpp derivation is extracted to `capture_paths::projectDirOfRpp`, which both + `persist` and the bridge call). Bank JSON parsed via the shared `bank_book` path (the + spike string-scan reader retired); ext-state key names shared via pure `ext_keys.h`. +- [x] Sample selection UI (minimal, in the `IPlugView` LICE editor): a clickable list + of the bank's samples; the pick is the instance's own VST3 component state + (setState/getState), never written back to the bank. +- [x] Tier-0 playback: chromatic-from-root, basic polyphony (16 voices), amp envelope, + velocity→volume — plays in REAPER's routing/record/render path like any VSTi. Sample + load / decode / keymap build happen off the audio thread and hand to `process` via a + lock-free atomic pointer swap (graveyard-reclaim); `process` never allocates. + +--- + +## S5 — Tier 1: "a keymap" (zoned multisamples, per-sample root notes) +**Goal:** Multiple bank samples zoned across the keyboard (key ranges), each with its +own root note — a captured *kit* (one-shots) or a *multisampled instrument* (same +instrument sampled at several pitches) plays correctly. One sample per key-region. +CONTEXT.md §Phase S (Tier 1). **Where the root-note + key-range seam fields earn +their place.** +**Verify (in DAW):** a keymap of several bank samples plays correctly zoned across +the keyboard, each repitched from its own root note within its range; a captured kit +and a multisampled instrument both play as expected; the keymap is authored in the +instrument (performance map) while root notes come from the bank intrinsics (S2); +editing the keymap does not touch the bank. +**Depends on:** S4. + +- [x] Keymap editor in the `IPlugView` LICE editor: assign bank samples to key ranges + (low/high note per sample), each with its own root note (from S2 intrinsics, + overridable in the performance map). +- [x] Tier-1 playback: zoned resolution — a note picks its zone's sample and repitches + from that sample's root note; one sample per key-region. +- [x] Performance-map persistence: the keymap (zones, per-sample assignment) is the + instrument's own state — held in the instrument as VST3 component state (setState/getState) + per D-B's data-ownership split; the live `"reasampler"` seam is read-only (bank + + intrinsics in, nothing written back), never written back as a bank intrinsic. + +--- + +## S6 — embedded TCP/MCP UI (D-D — scheduled in-phase, after the editor) +**Goal:** Render a compact keymap/level strip **inline in the track/mixer control +panel** via `reaper_plugin_fx_embed.h` (`IReaperUIEmbedInterface`) — the same +Cockos surface REAPER's own embedded FX use — so the instrument draws inline, not only +in its own window. Composes with the S1/S5 LICE editor path (same LICE-class drawing). +**Scheduled, not deferred (D-D settled 2026-07-26):** a real later point, sequenced +last because it is polish over a Tier-0 need — but on the roadmap. CONTEXT.md §Phase S +(embedded UI, D-D). +**Verify (in DAW):** the instrument draws a compact inline strip in the TCP/MCP (not +only its own editor window); the inline surface reflects and (where offered) edits the +keymap/levels; the embed lifecycle is clean (open/close/resize); the same LICE drawing +as the main editor is reused. +**Depends on:** S5 (composes over the existing LICE editor). **Must-verify before +build:** the `IReaperUIEmbedInterface` contract + embed message/lifecycle against +`vendor/reaper-sdk/sdk/reaper_plugin_fx_embed.h`. + +- [x] Implement `IReaperUIEmbedInterface` on the VST3; draw a compact keymap/level + strip inline in the TCP/MCP using the same LICE surface as the editor. +- [x] Embed lifecycle (open/close/resize/hit-test inline) handled cleanly; reflects + the live keymap/levels. + +--- + +## S7 — stereo channel mode (mono | stereo; core channel dimension + bus negotiation) +**Goal:** Give the instrument a per-instance **channel-mode toggle — 1 (mono) or 2 +(stereo)** — that "works with the REAPER audio bus automatically." Mono keeps today's +downmix path; stereo grows the S3 core a **channel dimension** (2-channel sample data, +per-voice stereo render, stereo interp/loop) and negotiates the VST3 output bus so +mono/stereo just works in REAPER's routing. **This is an S3-core extension, not a shell +hack** — it touches the engine Daniel smoke-tests, so it sequences first after the +editor/embed work. CONTEXT.md §Phase S (channel mode, D-E). **Decided direction +(2026-07-26); leans below are build-time residuals, not open forks.** +**Verify (in DAW):** an instance set to stereo plays a stereo capture in true stereo, +its VST3 output bus negotiated to 2 channels via `setBusArrangements` so REAPER routes it +without manual channel wiring; an instance set to mono plays the existing downmix path; a +mono source in stereo mode plays dual-mono (centered); a stereo source in mono mode +downmixes (existing policy); the mode is per-instance state that survives project +save/reopen (component state, like the selected sample); the pure core's stereo render is +asserted against a known two-channel signal (mirror of `peaks`), and mono behavior is +unchanged (regression). +**Depends on:** S3 (extends the core), S4 (extends the process/bus shell). Independent of +S8/S9. + +- [x] Core channel dimension (pure, S3 extension): `SampleData` carries 1- or 2-channel + decoded PCM (`frames` + optional length-matched `framesR`; `channelCount()`); + `Voice::renderFrameStereo` + a `VoiceEngine::render(left,right,n)` overload produce a + per-channel frame sharing one read head + one envelope tick; stereo linear interpolation + + loop read per channel. Mono stays the degenerate case (`renderFrame` reads channel 0 only, + byte-identical). Tests: stereo render asserted against a known 2-channel signal; dual-mono; + per-channel repitch + additive mix; mono render unchanged (regression) — sampler_core_tests. +- [x] Channel-mode toggle as per-instance state: `ChannelMode {Mono,Stereo}` in the + instrument's own component state (v4 = v3 + a channel-mode byte; setState/getState); + default mono. Cross-mode policy in `decodeChannels`: **mono source + stereo mode → + dual-mono**; **stereo source + mono mode → downmix** (existing decode-side policy). The + toggle lives in the instrument, never written to the bank (D-B). v1/v2/v3 blobs lift to v4 + with mono default; round-trip + lift tests — sample_map_tests. +- [x] Shell: `decodeRelative` fills 1- or 2-channel `DecodedZonePcm` per the active mode + (source channel count from the WAV layout); the process path renders the host's negotiated + output channel count (stereo into ch0/ch1, mono into ch0) — RT discipline unchanged. +- [x] VST3 bus negotiation: `setBusArrangements` accepts only the mode's arrangement + (kMono/kStereo), else rejects (kResultFalse) but keeps a valid mode arrangement so + `getBusArrangement` (base default) reports it; a runtime mode change repoints the output bus + + calls `restartComponent(kIoChanged)` so REAPER re-negotiates. **Verified** against the + vendored Steinberg SDK (`ivstaudioprocessor.h` contract, `vstsinglecomponenteffect.cpp` + base impl, `ivsteditcontroller.h` kIoChanged); see handoff notes. + +--- + +## S8 — ingest through the bank (one gesture: capture/import into bank + assign to instance) +**Goal:** Loading a sample into the sampler is **one gesture** — capture/import-into-bank +**and** auto-assign to the active sampler instance. **The extension owns ingest** (it has +arrange access, media-explorer access, and drop-target surface on its own panels); the +instrument stays a **read-only bank consumer**. This lives in the *extension* codebase +(actions + bank_panel + capture/insert), routing through the existing capture add-path and +the live `"reasampler"` seam the instrument already reads. CONTEXT.md §Phase S +(ingest-through-bank contract). **Decided direction "option 1" (2026-07-26).** +**Verify (in DAW):** a one-click "capture selected item / time-selection into the bank and +assign to the active instance" action captures via the existing capture path (never +auto-inserting into the arrange — load-bearing principle intact) and the target instance +plays the new sample on its next reload; a Media Explorer file imports into the bank and +assigns the same way; a file dropped onto a ReaSampler panel surface ingests into the bank +and assigns; the instrument never captures or imports (read-only over the bank throughout). +**Depends on:** S4 (an instance to assign to), M7 capture add-path, B2 (active-bank add +target). Best paired with S9 so assignment refreshes hands-free; functional without it +(assign triggers a reload on the target instance directly). + +- [ ] "Capture selected item / time-selection into bank + assign to active instance" + action (`command_id`/`gaccel`/`hookcommand`, MIDI-bindable): reuse the existing capture + request path (`CountSelectedMediaItems`/`GetSelectedMediaItem` + `GetSet_LoopTimeRange` + as the capture inputs), add the resulting `Sample` to the active bank, then assign its + id to the target instance. **Never inserts a timeline item** (capture/placement stay + separate — the assignment is a bank-index + instance-selection act, not a placement). +- [ ] Media Explorer import → bank → assign: read the Media Explorer's current selection + via `MediaExplorerGetLastPlayedFileInfo` (path + selection range), import the file into + the bank (existing import/capture add-path), assign to the target instance. **Honest SDK + limit (verified against the vendored headers):** the Media-Explorer surface is thin — + `OpenMediaExplorer` (open/select) + `MediaExplorerGetLastPlayedFileInfo` (read the *one* + last-played/selected file + its range) 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 the user fires while a file is + selected in the ME), not a push/drop from inside the Media Explorer. **Spike:** confirm + `MediaExplorerGetLastPlayedFileInfo` returns a usable path+range for a merely-*selected* + (not-yet-played) file, or whether a play is required first. +- [ ] Drag-and-drop onto ReaSampler surfaces: accept an OS file drop onto the docked + `bank_panel` (and its bank/tab regions) → ingest into the bank → assign. **Honest SDK + limit (verified):** REAPER exposes **no** drag-drop registration API; drop handling is on + ReaSampler's *own* HWNDs via SWELL/Win32 (`WM_DROPFILES` / an `IDropTarget` on the panel + HWND), the same surface the panel already owns. **Assess-and-flag (spike, do not promise + here):** 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 to the extension over an agreed seam). Reported + honestly as a spike because it crosses the two-artifact boundary and the relay mechanism + is unproven; if it proves gnarly, drop-onto-panel is the shipped path and drop-onto-editor + is deferred. +- [ ] "Assign to instance" seam: how the ingest action names the target instance and hands + it the new sample id. Lean (build-time residual, not a fork): the active/last-focused + instance is the target, discovered via the host context the bridge already resolves; the + assignment is the same instance-owned selection state S4 already persists, so a reload + picks it up. If the change-detection seam (S9) exists, assignment refreshes hands-free; + without it, the ingest action pokes the target instance's reload directly. + +--- + +## S9 — bank-generation change-detection (recapture / ingest refreshes instances hands-free) +**Goal:** Because instances reference sample **ids**, a **recapture** (M10) landing under +the same id — or an **ingest** (S8) touching the active bank — should refresh playing +instances **hands-free**, without the user re-opening each editor. Add a **bank-generation +counter** to `"reasampler"` ext-state that the extension bumps on any bank-content +mutation, and that the instrument polls off the audio thread on a safe cadence, calling its +existing `reloadFromBank()` when the generation changes. CONTEXT.md §Phase S +(bank-generation seam). **Closes the missing change-detection trigger the recapture +auto-update story needs.** +**Verify (in DAW):** a recapture that regenerates a sample already assigned to a live +instance refreshes that instance's playback within a bounded cadence, no editor re-open; an +ingest (S8) that updates the active bank likewise refreshes assigned instances; the poll +runs off the audio thread (never in `process`) and triggers the existing off-thread reload +path; instances not referencing a changed sample do not audibly glitch (reload is atomic — +the S4 graveyard-reclaim handoff); a project with no generation stamp (pre-S9) defaults +cleanly (treated as generation 0; first bump refreshes). +**Depends on:** S4 (the off-thread `reloadFromBank` + atomic handoff this drives). Writer +side is extension-only and independent of S8; consumed by S8 and M10 recapture. Best landed +alongside S8. + +- [x] Writer (extension): a monotonic **bank-generation counter** stamped into + `"reasampler"` ext-state (new `ext_keys.h` constant — forever-stable spelling), 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. +- [x] Reader (instrument): poll the generation over the bridge on a safe **off-audio-thread + cadence** (a UI/timer tick, not `process`), compare to the last-seen value, and call the + existing `reloadFromBank()` on change — reusing S4's atomic pointer-swap handoff so a + refresh mid-play does not glitch. No new audio-thread work; no allocation in `process`. +- [x] Cadence + coalescing: pick a poll interval that is responsive but cheap (build-time + residual — a low-frequency UI timer, coalescing multiple bumps between polls into one + reload). **Must-verify before build:** that a bridge ext-state read on the instrument's + UI/timer thread is safe against a concurrent extension write (the read already tolerates a + stale value by design — it reloads on the *next* poll; confirm no torn-read hazard for the + single integer generation key). + +--- + +## S10 — capture-first editor: browser + guided single-capture setup ("ReaSampler 9000" UX overhaul, part 1) +**Goal (REVISED 2026-07-26 — workflow-first reframe, Daniel):** Rebuild the editor's +default face around the **primary flow = one capture, fast**, not a keymap. A giant list of +"item" blocks is visually useless; most instances play a *single capture*, and zones are a +nice-to-have. So the default view is a **capture browser** (scannable cards with peak +thumbnails, name, root/key badge; **bank filter**) feeding a **guided single-capture setup** +(root note, play-mode basics, level) — and the keyboard strip serves the *single-capture* +case first (shows where the capture sits / its root). **Time-to-first-note is the metric.** +Multi-zone keymap editing is **demoted to an opt-in "Zones" panel** (S10-Z below), not the +default. The keyboard-strip drag machinery is still built here, but in service of the +capture-first layout. All layout/hit-test math is **pure geometry** (new `keyboard_strip` + +a `capture_browser` layout module — mirrors of `mode_switch`/`editor_geometry`); the LICE +draw + drag-state machine is the editor shell. RT discipline untouched (edits commit +off-thread via `commitMapAndReload`); the instrument stays a **read-only bank consumer**. +CONTEXT.md §Phase S (ReaSampler 9000 UX — capture-first editor). + +**Policy reversal — fresh instance is SILENT, nothing auto-selected (was S4).** The S4 +"first sample plays" fallback is **removed**: on open with no stored selection, the +instrument plays **nothing** and the editor shows a clear **empty state** ("pick a capture") +— it does not auto-play sample #1. Retires the `selectSample` first-sample fallback +(`sample_map.cpp` "No stored id → fall back to the FIRST sample") and the processor's +Tier-0 fallback that resolved it; an empty stored id now resolves to silence. A capture is +loaded when the user picks one (or via S13 drop-to-load / S8 ingest). This is a deliberate +reversal of the S4 convenience default, not a regression. + +**Verify (in DAW):** a fresh instance plays **nothing** and shows the "pick a capture" +empty state (no auto-play of sample #1); the capture browser draws **peak thumbnails** +(the `Sample` peaks bank_model already carries — same data the dock panel thumbnails use), +name, and a root/key badge where present, and is **filterable by bank** (bank_book named +banks); picking a capture loads it, shows it (waveform/peaks + its root on the keyboard +strip), and it plays repitched from its root; time-to-first-note is a pick-then-play, not a +list-scroll; the keyboard strip shows the single capture's root and is draggable to set it; +the pure geometry modules are CTest-green (browser card/grid layout + hit-test; strip +edge-grab/body-move/key→note) with no host types at their boundary; the ±1 nudge-button row +is gone. +**Depends on:** S4 (the selection state + reload path this reverses the fallback on), S1 +(the LICE `IPlugView` drag/event routing — extends the click-only `wndProc` to +`WM_MOUSEMOVE`/`WM_LBUTTONUP`), S5 (the `PerformanceMap`/zone model the opt-in Zones panel +edits — but the default face does not require a keymap). **Adopts the Phase L kit when +available — not gated on Phase L.** S10 builds its browser cards + keyboard strip with the +current LICE drawing; when Phase L's L1 kit lands on `dev`, this surface adopts it (the one +source of drawing). The drag machine's `WM_MOUSEMOVE` tracking also lights the kit's +**hover** states at near-zero marginal cost once the kit is present. + +- [ ] No-auto-select + empty state (the policy reversal): remove the `selectSample` + first-sample fallback (`sample_map.cpp`) and the processor's Tier-0 fallback that + consumed it — an empty stored selection resolves to **silence**, not sample #1. The + editor draws a clear **empty state** ("pick a capture" affordance) when nothing is + selected. Pure change is testable (empty id → `nullopt`); the empty-state draw is shell. +- [ ] Capture browser (pure layout + shell draw): grow `SampleChoice` to carry the + **peak thumbnail data** (from the `Sample` peaks bank_model already stores — the same + peaks the dock panel draws), the **root/key badge** (S2 `rootNote` intrinsic / the + optional musical key), and its bank. A new pure `capture_browser` module lays out + scannable **cards/rows** (card rect grid, thumbnail rect, hit-test a point → card) — no + host types at the boundary, unit-tested. The shell draws each card's peak thumbnail + + name + badge in LICE (house palette) and routes a click to select. +- [ ] Bank filter (pure + shell): a filter/tab strip over the browser that narrows the + drawn cards to a chosen bank_book bank (or "all"). Filter-tab layout + hit-test pure + (mirror of `mode_switch`); the active-filter state is transient UI state; the shell draws + the tabs and applies the filter to the card list. (Type-to-filter search folds in from + S12 — see S12's boundary note; a name-substring filter over the same card list.) +- [ ] Guided single-capture setup (the fast path): once a capture is picked, a prominent, + self-explanatory setup surface — **root note** (settable on the keyboard strip / typed), + **play-mode basics**, **level** — sized for the single-capture case, not a zone table. + Graphic and descriptive; the point is to get from pick → set → play with no hunting. +- [ ] Pure `keyboard_strip` geometry module (serves the single-capture case first): map a + MIDI key span across a strip width (128 keys → pixels, reusing the S6 `embed_strip` + key-span idiom); a **root marker** for the loaded capture; `pixel→note` and a `keyAtPoint` + for click-to-set-root; a drag-delta resolver `(grabbedField, startNote, dxPixels) → + newNote`; **per-zone bar rect** + **edge-grab hit regions** (resize handles vs. body + move-handle) for the opt-in Zones panel. No VST3/REAPER/LICE types at the boundary; + unit-tested (root marker, edge grabs, body-move delta, key mapping, clamps low≤high, + boundary rounding). Mirror of `mode_switch`/`editor_geometry`. +- [ ] Editor shell drag-state machine: `WM_LBUTTONDOWN` grabs a card / a key / a zone + edge-or-body, `WM_MOUSEMOVE` updates the in-flight edit against the pure resolver, + `WM_LBUTTONUP` commits via the existing `commitMapAndReload` (off-thread reload; RT path + untouched). Live visual feedback while dragging; a single undo-coherent edit on release. + +### S10-Z — Zones panel (opt-in multi-zone keymap editing; demoted from the default face) +The multi-zone keymap editor is now an **opt-in view/panel** ("Zones" toggle), not the +default. It reuses the same `keyboard_strip` geometry and drag-state machine: each zone a +bar over the keys it covers; **drag an edge** → low/high note; **drag the bar body** → move +the zone (span preserved); **click a key** → set/relocate the zone's root. This is the +capability RS5K structurally lacks (multi-zone in one instrument), kept as a *nice-to-have* +per Daniel's hierarchy — "most of the time the zones won't be used." Add/select/delete a +zone; overlapping zones render legibly and resolve first-match. The seven ±1 nudge/delete +mini-buttons are retired everywhere; delete is one affordance (a small × on the bar or a +keystroke). The `zoneHitTest`/±1 nudge path in `editor_geometry` is retired (a numeric +fallback for accessibility is a build-time residual, not a fork). +**Verify (in DAW):** the Zones panel is reachable via an explicit toggle (default view is +the capture browser + single-capture setup, not this); a zone's range is set by **dragging +edges** (not nudge clicks); body-drag moves the span; click-a-key sets the root (audible on +the next held note); zone add/select/delete work; the ±1 nudge row is gone. + +- [ ] "Zones" panel toggle (opt-in): the default editor face is the capture browser + + single-capture setup; a toggle reveals the multi-zone keymap editor. Toggle state is + transient UI state (or per-instance component state if it should persist — build-time + residual). +- [ ] Zone edit via the shared strip: draw the keyboard strip + zone bars in LICE, drive + the shared drag-state machine (edge = resize, body = move, key = root), commit via + `commitMapAndReload`. Zone add/select/delete as single affordances; ±1 nudge row gone. + +--- + +## S11 — waveform view with draggable loop points (UX overhaul, part 2) +**Goal:** Give each sample/zone a **waveform display** with **draggable start/end/loop +markers** — the S2 loop-point intrinsics and the S5 performance map already carry the data; +today there is no way to *see* a sample or *set* its loop by eye. Selecting a zone (or a +bank sample) shows its waveform (peaks via the existing `peaks` module, fed the decoded +PCM the shell already loads); drag the **loop-start / loop-end** markers to set the sustain +loop, snapping to zero-crossings (the S2 spec's zero-crossing-aware requirement). Loop +points are a **performance-map override on the zone** where set, seeded from the bank +intrinsic (D-B split: the bank carries the file-fact default; the instrument's drag is the +performance choice). All marker/waveform layout + hit-test is pure geometry; peaks compute +reuses `peaks`; the draw + drag is the shell. CONTEXT.md §Phase S (ReaSampler 9000 UX — +waveform view). +**Verify (in DAW):** selecting a zone shows its sample's waveform; dragging the loop-start +and loop-end markers sets the sustain loop and a held note audibly loops that region; +markers snap to the nearest zero-crossing; a sample with no loop shows the "no loop" state +and a held note past the end goes silent (existing core behavior); the waveform peaks match +the audio (mirror of the `peaks` envelope assertion); the marker geometry module is +CTest-green (px↔frame mapping, marker grab regions, clamp start≤end). +**Depends on:** S2 (loop-point intrinsics), S3 (loop-aware sustain the markers drive), S5 +(the zone the loop attaches to), S10 (shares the editor's drag-state machine + shell). The +zero-crossing snap is a small pure helper over the decoded PCM. + +> **Boundary note (S10 reframe, 2026-07-26):** the waveform view is now **central to the +> single-capture fast path**, not just per-zone. Selecting a capture in S10's browser shows +> its waveform (this is "see it" in pick → see it → play it); the loop-marker drag here +> extends that same waveform surface. S11's waveform draw is the same one S10's picked- +> capture view uses — build it once, S10 shows it read-only for the single capture, S11 adds +> the draggable loop markers. No renumber; S11 stays the loop-editing point. + +- [ ] Pure waveform/marker geometry: `frame↔pixel` mapping across the waveform rect, marker + x-position from a frame index, marker grab regions (start/end/loop-start/loop-end), + drag-delta `(grabbedMarker, dxPixels) → newFrame` with clamps (start≤end, in-bounds). A + **zero-crossing snap** helper: nearest sign-change frame to a target (pure, over the + decoded mono PCM). No host types; unit-tested. +- [ ] Waveform draw: compute peaks with the existing `peaks` module from the shell's already- + decoded PCM (no new decode path, no new WAV reader); draw the envelope in LICE in the + house style; draw the loop markers over it. Reuses the S10 drag-state machine. +- [ ] Loop-point edit → performance-map override: a dragged loop writes a per-zone loop + override (seeded from the S2 bank intrinsic, D-B), committed off-thread via + `commitMapAndReload`; the bank intrinsic is never written back (instrument is a read-only + bank consumer). Extends `PerformanceZone` with an optional loop override (additive, same + shape as `rootOverride`) + its component-state (de)serialize (version bump, back-compat + with S5's v2 map blob — a truncated/older blob defaults the override absent). + +--- + +## S12 — editor scale + ergonomics (UX overhaul, part 3; scrollable/searchable list, direct entry) +**Goal:** Make the editor usable **at bank scale** and close the remaining RS5K-parity +gaps: the sample list **scrolls** (today a long bank's rows run off the panel with no way +to reach them) and has a **type-to-filter search**; add **direct numeric entry** for a +zone's low/high/root (a click-to-type field over the strip, for precision the drag can't +hit) and an **ADSR control** for the amp envelope (S3 already has the ADSR math; today it +is fixed — expose attack/decay/sustain/release as draggable sliders, per-instance state). +This is the "sensible list handling + direct manipulation of the parameters that exist" +tier. All slider/scroll/search-box layout + hit-test is pure geometry; the shell draws + +routes; ADSR/scroll/filter state is instrument-owned (component state / transient UI +state). CONTEXT.md §Phase S (ReaSampler 9000 UX — scale + ergonomics). +**Verify (in DAW):** a bank with more samples than fit **scrolls** (wheel + drag) and every +sample is reachable; typing filters the list to matching names; a zone's low/high/root can +be **typed** (not only dragged) via a click-to-edit field; the amp envelope's ADSR is +**adjustable** (four draggable controls) and the change is audible + persists across project +save/reopen (component state); the scroll/search/slider geometry is CTest-green. +**Depends on:** S10 (the editor shell + drag-state machine + the **capture browser** the +scroll/search now apply to), S3 (the `AdsrParams` the ADSR sliders drive — already wired +into the voice engine; today they are fixed defaults), S5 (the map the numeric fields edit). + +> **Boundary note (S10 reframe, 2026-07-26):** the "sample list" S12 originally scrolled and +> searched **is now S10's capture browser** (cards with peak thumbnails, bank filter). What +> pulled INTO S10: the browser layout itself, the peak thumbnails, and the **bank filter** +> (a bank_book tab, distinct from name search). What stays in S12 and applies **to S10's +> browser**: (a) **scroll** for a bank longer than the panel, and (b) **type-to-filter +> search** (a name-substring narrow over the same cards, composing with S10's bank filter — +> bank filter picks the bank, search narrows within it). The scroll/search geometry is pure, +> layered over the `capture_browser` module S10 builds. Net: S12 = scroll + search over the +> S10 browser + numeric entry + ADSR; the browser *card* work is S10's. **S12 now also +> carries the S15/S16 control surfaces** (per-zone Gate/Trigger mode toggle, AHDSR hold +> control, Trigger %-length/fade controls, Varispeed/Preserve engine toggle, and the AD pitch +> envelope depth/shape controls) — deferred here from S15 and S16 per spec. + +- [x] Scrollable, searchable capture browser: a scroll offset (wheel + scrollbar drag) so a + bank longer than the panel is fully reachable; a **type-to-filter search** that narrows + the drawn cards to matching display names, **composing with S10's bank filter** (bank + filter selects the bank; search narrows within it). Scroll/search layout + hit-test is + pure geometry (visible-card window, scrollbar thumb rect, search-box rect), layered over + S10's `capture_browser` module; filter/scroll state is transient UI state. **Landed:** + pure `browser_scroll` module (`browser_scroll_tests`) — scrollContentHeight / max / clamp, + visibleCardRange window, scrolledCardCellRect, scrollThumbRect + thumbDragToOffset inverse, + searchBoxRect, nameMatchesQuery + filterNameIndices. Editor shell wires wheel (`WM_MOUSEWHEEL`), + thumb-drag (`DragKind::kScrollThumb`), and the search box (`WM_CHAR` -> `onSearchChar`, + composed into `rebuildVisible`). Scroll/search are transient (never persisted). +- [x] Direct numeric entry for zone low/high/root: a click-to-edit field over the strip + (LICE text-entry idiom) so a precise note can be typed, not only dragged. Commits via + `commitAndReload` like every other edit. **Landed:** pure `note_entry` module + (`note_entry_tests`) — `parseNoteEntry` accepts a decimal integer OR a note name (C4==60), + clamps to [0,127], rejects garbage. Editor shell hosts three focusable fields (low/high/root) + on the Zones legend, committing on Enter through `commitAndReload`. +- [x] ADSR/AHDSR editor + S15/S16 control surfaces: draggable sliders over the S3 `AdsrParams` + (attack/**hold**/decay/sustain/release — hold is the S15 addition) plus the deferred S15/S16 + controls — per-zone Gate|Trigger mode toggle, Trigger %-length/fade-in/fade-out, Varispeed| + Preserve engine toggle, and the AD pitch-envelope enable/attack/decay/±semitone depth. All + edit the SELECTED zone's `ZonePlayParams` (instrument-owned, D-B; never the bank), round-trip + through the existing v3 component-state blob (no new persistence — the S15/S16 payload already + landed in the core pass), and commit off-thread via `commitAndReload`. **Landed:** pure + `param_slider` module (`param_slider_tests`) — control-panel stack layout, toggle-segment + split + hit-test, slider value<->pixel round-trip + clamping, point->control routing. The + shell owns the control-id -> engine-param binding + the value DOMAIN mapping (frames/fraction/ + semitones); the module stays engine-free. + +**Notes/decisions:** +- **Wall-clock envelope times stored as rate-free SECONDS (zones payload v5)**, resolved to + frames at keymap build against the live project rate — no hardcoded sample rates anywhere in + `src/`. Daniel's standing ruling; enforced throughout the voice engine and verified at S12. + +--- + +## S13 — drop-to-load (partial landing; relay deferred) +**Goal:** Make "load a sample into the sampler" **one gesture from the editor** via an +OS file drop onto the editor window. The cross-artifact relay was a spike — the +instrument's REAPER bridge (`reaper_bridge`) is deliberately READ-ONLY; the relay is +DEGRADED and deferred. The two landed items are the drop-accept surface and the UX degrade +path. The deferred relay item remains in `PLAN.md`. CONTEXT.md §Phase S (drop-to-load). + +**Spike verdict (ps-w12, 2026-07-27): DEGRADED.** The relay would require (a) a new +instrument WRITE seam into ext-state and (b) an extension-side timer poller + claim/clear +nonce — the same cross-process handshake race the S17 spec rejected. The shipped ingest +gesture stays drop-onto-docked-panel (S8). The relay is a future wave when the design is +ready. + +- [x] Editor-window drop target: accept `WM_DROPFILES`/`IDropTarget` on the editor child + HWND (the same SWELL/Win32 surface `bank_panel` owns), extracting the dropped file + path(s). Windows-only (D5). This is the *acceptance* half; the ingest is the extension's. + **Landed:** the editor child window calls `DragAcceptFiles(TRUE)` on attach and handles + `WM_DROPFILES` (`reasampler_editor.cpp`). Windows-only (D5). +- [ ] Cross-artifact ingest relay (the S8-flagged spike): **DEFERRED** — relay mechanism + proved load-bearing to redesign. Remains in `PLAN.md` §S13. +- [x] UX degrade path: when the relay is unavailable/unproven, the editor shows a clear + "drop files on the ReaSampler panel to add" affordance rather than silently swallowing the + drop — the shipped ingest gesture stays discoverable either way. **Landed:** the editor + ACCEPTS the drop and flashes a transient banner ("drop files onto the ReaSampler bank panel + to add them") that decays over a few sync ticks, plus a persistent affordance line in the + empty state ("drop a file onto the ReaSampler bank panel"). No file is ingested; NO timeline + item is ever inserted (the hard invariant — the editor only displays guidance). + +--- + +## S15 — sampling modes: Trigger vs Gate (per-sample play-mode; core + editor) +**Goal:** Give each played sample a **play mode** — **Gate** (classic held note) or +**Trigger** (one-shot) — a per-sample/per-zone performance choice (D-B, instrument-owned). +**Gate** is today's behavior grown from ADSR to **AHDSR** (adds a Hold stage): note-on → +attack/hold/decay/sustain, note-off → release, sustain **loop points apply** (S11's +draggable loop UI is Gate-mode UI). **Trigger** is a one-shot drum-pad: note-on fires +playback of a defined **% of sample length** with a **fade-in** and **fade-out** ramp, +**ignores note-off**, and uses **no sustain loop**. **Both** modes carry a **modifiable +start point** (playback begins at an offset into the sample, not always frame 0). This is +an **S3-core extension** (the engine Daniel smoke-tests) plus editor surfacing — the mode + +its parameters are instrument performance-map state, never a bank fact. CONTEXT.md §Phase S +(Sampling modes — Trigger vs Gate). **Daniel's feature set is settled.** +**Verify (in DAW):** a sample in **Gate** mode plays held with the AHDSR envelope (hold +stage audible between attack and decay), releases on note-off, and loops its sustain region +if loop points are set; a sample in **Trigger** mode fires a fixed % of its length on +note-on with audible fade-in/out, **plays through to completion regardless of note-off**, +and never sustain-loops; the **start point** offsets playback in both modes (a note starts +partway into the sample); the mode + parameters are per-instance component state that +survive save/reopen; the pure core's Trigger envelope (fade-in → hold → fade-out over +%-length frames) and the AHDSR hold stage are asserted against known signals; existing +Gate/ADSR behavior is unchanged when hold=0 (regression). +**Depends on:** S3 (extends the envelope + voice read-position machinery), S5 (the +`PerformanceZone` the mode + params attach to), S11 (Gate loop-point UI; Trigger's waveform +shows start + %-length + fades on the same waveform surface). Independent of S7. + +- [x] Core: `PlayMode { Gate, Trigger }` on the voice + the envelope split. **Gate** grows + `AdsrParams` → `AhdsrParams` (add `holdFrames` between attack and decay; hold=0 is the + exact current ADSR — back-compat). **Trigger** is a distinct envelope: play `[start, + start + lengthFraction·(frames−start))` with a **fade-in** ramp (0→1 over `fadeInFrames`) + and a **fade-out** ramp (1→0 over `fadeOutFrames` ending at the play-length end), + **ignoring note-off** (release is a no-op in Trigger). Fade curve default **equal-power** + (constant-power `sin`/`cos`, click-free on one-shots); pure, unit-tested against a known + signal. +- [x] Core: **modifiable start point** — the voice's initial `readPos_` is `startFrame` + (frame offset), applied in both modes; the existing per-frame `readPos_ += ratio_` read + and loop/interp machinery is otherwise unchanged. Clamp `0 ≤ startFrame < frames`. +- [x] Core: **% length → frames + fade mapping** for Trigger. `lengthFraction ∈ (0,1]` + resolves to `playEnd = start + round(lengthFraction·(frames − start))`; `fadeInFrames` / + `fadeOutFrames` clamp so their sum ≤ play length (fade-out anchored to `playEnd`). Note-off + in Trigger does nothing; the voice frees when `readPos_ ≥ playEnd`. **Choke on note-off is + NOT in scope** (fork S15-F1, held). +- [x] Parameter ownership (per-sample/per-zone, instrument-owned): the play mode + its + params (Gate: AHDSR; Trigger: %-length, fade-in, fade-out; both: start point) attach to + the **capture selection / zone**, stored in the **performance map** (D-B). Additive/ + version-bumped component state; back-compat — a truncated/older blob defaults to **Gate**, + hold=0, start=0, no fades = exactly today's behavior. +- [x] Editor (S11 waveform surface, mode-aware): **Gate** shows draggable **start + loop + markers** (S11's loop UI); **Trigger** shows **start + %-length end + fade-in/out** + handles on the same waveform. A **mode toggle** per capture/zone in the guided setup + (S10) / Zones panel (S10-Z). Marker/handle geometry is pure; commits off-thread via + `commitMapAndReload`. The instrument stays a **read-only bank consumer**. **Editor control + surface deferred to S12 tier (spec-sanctioned).** + +--- + +## S16 — pitch engine modes (Varispeed vs Preserve) + pitch envelope (per-voice) +**Goal:** Give the sampler **two pitch behaviors** and a pitch envelope that rides whichever +is chosen. **Varispeed** — resampling that couples pitch and duration (classic sampler / +RS5K default). **Preserve** — duration-preserving repitch, where a transposed note keeps +its original length. A **per-zone/per-capture pitch-engine mode**. On top of either engine +rides a per-voice **AD pitch envelope**, **off by default** — a short attack-decay pitch +modulation. Per-instance performance-map state (D-B). CONTEXT.md §Phase S (Pitch engine +modes + pitch envelope). +**Verify (in DAW):** Varispeed — a note an octave up plays half as long as the root note; +Preserve — a note an octave up plays at the same duration as the root note; pitch envelope +off (default) under either engine: no pitch modulation applied (regression); pitch envelope +on: an AD envelope makes a note start offset in pitch and glide to the zone's base pitch +over attack+decay; CPU stays within budget at polyphony cap. +**Depends on:** S3, S5, S15. Independent of S7. + +- [x] Core: **pitch-engine mode on the voice/zone** — `PitchEngine { Varispeed, Preserve }`. + **Varispeed** = `readPos_ += ratio_` (today's path, pitch and duration coupled). **Preserve** + = duration-preserving: the read advances at the **source** rate while a pitch shifter + transposes the output. Mode is per-`PerformanceZone` performance state (D-B), additive/ + version-bumped; absent/older blob → engine default. Pure where possible: Varispeed math and + duration-invariance contract unit-tested. +- [x] Core: **Preserve engine implementation** — hand-rolled pure OLA `pitch_shift` module + (house pattern — CTest-testable, no WDL/REAPER/VST3 type at the boundary). Pre-allocated, + no locks, no `process` allocation; pre-warmed at voice allocation. `pitch_shift_tests` + CTest target. WDL_SimplePitchShifter excluded by include-chain (windows.h); held as a + quality/latency swap alternative (`PitchEngine::Preserve` contract identical behind the seam). +- [x] Core: a per-voice **AD pitch envelope**, engine-aware — `PitchEnvParams { enabled=false, + int64 attackFrames, int64 decayFrames, double peakSemitones }`. Off by default (`enabled=false` + → offset always 0). Under **Varispeed** the offset multiplies `ratio_`; under **Preserve** + the offset is **added to the shifter's shift amount**. Pure, unit-tested. +- [x] Parameter ownership + editor: pitch-engine mode + pitch envelope are per-zone + instrument performance-map state (D-B), additive/version-bumped. Editor exposure deferred + to S12 tier (spec-sanctioned). The instrument stays a **read-only bank consumer**. + +**Notes/decisions:** +- **S16-F1 (default engine):** default is **Preserve** (Daniel's directive: "I want + duration-preserving repitching"). Per-zone toggle prominent and cheap to flip for + drum/one-shot zones that want Varispeed character. +- **S16-F2 (Preserve engine):** hand-rolled pure OLA `pitch_shift` module chosen over + `WDL_SimplePitchShifter` (excluded by include-chain). Both share the same + `PitchEngine::Preserve` contract; `WDL_SimplePitchShifter` is held as the quality/latency + swap (the HELD item in `PLAN.md`). + +--- + +## S17 — drop-and-load: drag a capture onto a track's FX button → instantiate ReaSampler 9000 with the capture loaded +**Goal:** Turn a bank capture into a playable instrument in one gesture. While a capture +is dragged from the `bank_panel`, a track's TCP **FX button** lights as a drop zone, +and dropping there instantiates a **ReaSampler 9000** on that track with the dragged +capture **already loaded and selected** for playback. A third `DragGesture` — +`InstrumentDrop` — added to the `drag_out` pure module. Mechanism: `TrackFX_AddByName` + +VST3 component-state injection via `TrackFX_SetNamedConfigParm(..., "vst_chunk", blob)`. +The shared `instrument_drop` pure module constructs the blob via the instrument's own +`sample_map::serializeComponentState`/`deserializeComponentState` — one serializer called +from both artifacts, so the blob format cannot drift. CONTEXT.md §Phase S (drop-and-load). +**Verify (in DAW):** dragging a single capture from the dock over a track's FX button +highlights it; dropping instantiates ReaSampler 9000 on that track with the dragged +capture loaded, selected, and MIDI-playable immediately; OS drag-out to Explorer still works +unchanged; internal bank-to-bank drag still works unchanged; no media item ever inserted +into the arrange. DAW-verify: whether REAPER's `vst_chunk` write-parm expects the plugin's +raw IComponent-state bytes or wraps them in a REAPER container header. +**Depends on:** M11 (`drag_out` gesture machinery), Phase S S4, the load-capture seam +(VST3 component-state injection — the shared blob contract). + +- [x] Extend the `drag_out` pure module with the third gesture: `DragGesture::InstrumentDrop` + when a drag armed with a **single** capture is over REAPER's UI outside the panel client + rect; `OsDrag` only when it has left REAPER entirely; `Internal`/`OsDrag`/`None` otherwise + unchanged. `DragState` gains two defaulted fields (`singleCapture`, `overReaperUi`); M11 + callers filling only `{dragging, hasArmedSamples}` get byte-identical M11 behavior — the + existing tests are the non-regression proof. **OPEN QUESTION RESOLVED (multi-capture over + FX button): REJECT** — only `singleCapture` arms InstrumentDrop; multi-payload over + REAPER UI falls through to `OsDrag`. +- [x] Shell (extension): hover-track the pointer over REAPER's UI during the drag; resolve + the hovered track + its FX button via `GetThingFromPoint` (verified present; its info string + reports `"fx_chain"`/`"fx_N"` for the FX region); highlight it as a drop target; on release + drive the drop. FX HOTSPOT resolved — drop target is the FX region (info prefix `"fx_"`), + not home-grown geometry. `instrument_drop_win::resolveFxDropTarget` implements this. + **Landed in `src/instrument_drop_win.cpp`.** +- [x] Shell (extension): on drop, `TrackFX_AddByName(track, "VST3:" + app_version::vstPluginName(), + false, negative)` to always add a fresh instance; capture the returned FX index; invoke the + load-capture seam. Batched into one REAPER undo point (`Undo_BeginBlock2`/`EndBlock2`). + NEVER inserts a timeline item. **Landed: `instrument_drop_win::performInstrumentDrop`.** +- [x] **ReaSampler 9000 load-capture seam:** the instrument's existing `setState`/`getState` + already round-trip the full `ComponentState` via + `sample_map::serializeComponentState`/`deserializeComponentState` (S10). The extension + REUSES that exact serializer through the new pure `instrument_drop` module + (`buildInstrumentDropChunk` → `serializeComponentState` → base64). The shared-writer + requirement is met STRUCTURALLY — the blob format cannot drift. Pure round-trip test decodes + back through the instrument's own reader and asserts the capture is selected. + **`instrument_drop` lives at `src/instrument_drop.{h,cpp}`** (extension-side pure module); + CTest target `instrument_drop_tests`. +- [x] Tests: gesture disambiguation (inside-panel / over-REAPER-UI / left-REAPER) across + single- and multi-capture payloads; M11 OS drag-out and internal bank-to-bank drag both + unchanged. `test_drag_out.cpp` adds the InstrumentDrop cases with M11 cases retained as + the non-regression guard; `test_instrument_drop.cpp` is the blob round-trip + base64 codec + coverage. FX hit resolution is REAPER-API-bound (`GetThingFromPoint`) — DAW-verified in the + shell, not pure-tested (noted honestly). + +**Notes/decisions:** +- `resetDragState()` consolidation in `bank_panel` (prior drift cleaned up this wave). +- Copy-only / no-auto-insert / no-source-deletion invariants all hold: NEVER inserts a + timeline item; the bank file is not deleted; prune remains the sole file-deleter. + +--- + +## S18 — VST3 channel isolation: a beta ReaSampler 9000 that pairs with the beta extension only +**Goal:** Extend Phase V's beta/stable channel split (V4) to the **ReaSampler 9000 VST3 +instrument**, so a beta-built VST is a distinct plugin that pairs only with the beta +extension, and a stable VST pairs only with stable — installable side-by-side in one REAPER +with no collision. **One channel per binary; all identity derives from the ONE +`REASAMPLER_CHANNEL_IS_BETA` bit via `app_version`, no scattered `#ifdef`s.** Mirrors V4's +philosophy exactly. Two forever-stable VST3 class UIDs committed (the existing stable UID + +a new beta UID). CONTEXT.md §Phase S (VST3 channel identity — the UID-pair invariant). +**Verify (in DAW):** stable VST3 (`reasampler_9000.vst3`) and beta VST3 +(`reasampler_9000_beta.vst3`) install side-by-side in one REAPER as distinct plugins; +a beta instance reads only the beta extension's banks; a stable instance reads only stable's; +save/reopen rebinds by the correct UID; nothing plays differently (identity/pairing wave only). +**Depends on:** V4 (`app_version` channel-identity single-source), S1 (VST3 factory identity). + +- [x] **Beta VST3 class UID (the permanent commitment).** Second FOREVER-STABLE class UID + (`REASAMPLER_PROC_UID_BETA_1..4` + `kReaSamplerProcessorUIDBeta`) alongside the existing + stable UID in `reasampler_vst.h`. The channel bit selects which UID the factory registers + (`DEF_CLASS2`) — compile-time, one class per binary. Both UIDs frozen forever. +- [x] **Channel-derived binary + display identity (no scattered `#ifdef`s).** Binary name: + CMake VST3 target `OUTPUT_NAME` forks by channel — `reasampler_9000` (stable) / + `reasampler_9000_beta` (beta) — via `REASAMPLER_VST_OUTPUT_NAME`. Display name: factory + `DEF_CLASS2` plug-in display string sourced from `app_version::vstPluginName()` — "ReaSampler + 9000" / "ReaSampler 9000 beta". Editor title band + S6 embed-strip label channel-aware from + the same accessor. +- [x] **Factory vendor/version strings channel-aware** where V4 does the equivalent. Version + display carries the `-beta` render (`appVersion()` yields `"0.9.01-beta"` on beta). +- [x] **Pairing-surface invariant recorded** (no new code — a documented guarantee): channel + isolation is structural — all wire keys live under the channel-derived `kProjExtNamespace()`, + so a future wire key that forgets to isolate is impossible by construction. The invariant + is recorded in CONTEXT.md. +- [x] **DAW-verify contract (the acceptance gate, no unit test — identity is a shell fact).** + Both channels installed side-by-side: each browser sees only its channel's banks; a + project saved with a beta instance reopens rebinding to the beta VST and restores its state. diff --git a/PLAN.md b/PLAN.md index c273357..52c2629 100644 --- a/PLAN.md +++ b/PLAN.md @@ -66,856 +66,58 @@ landed milestone. # Phase S — MIDI-playback instrument (native VST3 sampler; a second build artifact) -> **New pillar, own lettered namespace, and — uniquely — a second build artifact.** -> Every prior phase 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 **separate native VST3 -> plugin** the user instantiates on an instrument track, reading ReaSampler's banks -> and playing them MIDI-triggered. Namespaced **`S` (Sampler)** rather than "D" -> (Daniel's call — "D" collides with Design View). Authoritative spec: **CONTEXT.md -> §MIDI-playback instrument — additive phase spec (Phase S)**. Product framing + -> the settled decision record (D1/D5/D6 locked, D-A..D-D settled 2026-07-26): -> `docs/product/midi-playback.md`. When a point lands, doc-keeper moves it to -> `COMPLETED.md`. +> **Landed on dev (merged 2026-07-27); DAW verification pending Daniel's smoke test.** +> S1–S18 and the product-name/binary-rename work are all on dev. The cross-artifact +> ingest relay (S13 bullet) was explicitly DEGRADED and remains deferred — see below. +> Completed material archived in `COMPLETED.md`. Authoritative spec: **CONTEXT.md +> §MIDI-playback instrument — additive phase spec (Phase S)**. Product framing: +> `docs/product/midi-playback.md`. > -> **Locked (see `docs/product/midi-playback.md` §4):** D1 native VST3 (not JSFX); -> D5 Windows-only / VST3-only / REAPER-only; D6 two products, tightly integrated via -> the VST-host bridge (live `"reasampler"` ext-state, project-aware). **Settled forks -> (2026-07-26):** D-A bare Steinberg VST3 SDK + LICE editor (no JUCE); D-B split seam -> with root-note + loop-points added to `Sample` *now*; D-C Tier 0–1 committed (Tier 2 -> held, Tier 3 optional-forever); D-D embedded TCP/MCP UI **scheduled** as a later -> in-phase point (after the main editor exists). -> -> **Visual design moved to Phase L (2026-07-26).** The look-and-feel work originally -> drafted here as **S0-DS** (shared LICE drawing kit) and **S14** (dock-panel refresh) has -> been lifted out of Phase S into its own **Phase L** (Look-and-feel), taken up by a -> parallel team on `dev` so Phase S feature work proceeds ungated. See **PLAN.md §Phase L -> + CONTEXT.md §Phase L on `dev`** and `docs/product/visual-design-language.md` (on `dev`). -> 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.** -> -> **Numbering note:** S0-DS and S14 are removed (moved to Phase L); S7–S13 keep their -> numbers. -> -> **Second build artifact (load-bearing, flagged up front):** Phase S produces a -> *separate* VST3 binary alongside `reaper_reasampler`. The Steinberg VST3 SDK is a -> **new vendored dependency** (vendor at the spike — an implementation-time -> prerequisite, not done here), and CMake grows a second target with Windows VST3 -> module-export/bundle wiring. Both are established by S1 so nothing downstream leans -> on an unbuilt target. +## S13 — cross-artifact ingest relay (deferred) -## S1 — opening spike: VST3 skeleton + `IPlugView`↔LICE bridge (proof + second target) -**Goal:** Stand up the second build artifact and prove the two least-trodden -unknowns before the engine build leans on them: (1) a silent-but-loading VST3 -`SingleComponentEffect` skeleton that REAPER hosts, and (2) an `IPlugView` that hosts -a LICE-drawn surface. Converts §1a's experienced-estimates (Windows module-export -names, factory-macro spellings, exact bridge marshalling) into verified fact. -CONTEXT.md §Phase S (build shape, module architecture, API surface). -**Prerequisite (implementation-time):** vendor the Steinberg VST3 SDK (a new -submodule/dependency alongside `reaper-sdk` / `WDL`); confirm whether VSTGUI is -bundled (moot for D-A but resolves the noted fallback rung). -**Verify (in DAW):** the VST3 skeleton loads in REAPER on an instrument track, -enumerates via `GetPluginFactory`, sets up an event-in + audio-out bus, and runs an -empty `process` without error; an `IPlugView` opens and draws a LICE surface with a -working hit-test; the VST-host bridge resolves `GetProjExtState` by name and reads a -known `"reasampler"` value. Nothing plays yet — this is the loading/drawing/bridge -proof. +> **SPIKE VERDICT (ps-w12, 2026-07-27): DEGRADED — relay deferred.** The instrument's +> REAPER bridge (`reaper_bridge`) is deliberately READ-ONLY; a relay would need a new +> instrument WRITE seam into ext-state and an extension-side timer poller servicing a +> drop-ingest inbox key with a claim/clear nonce — the same cross-process handshake race +> the S17 spec rejected for alternative (A). Both the read-only-instrument boundary and +> the new poller are load-bearing design calls, so the relay is deferred to a future wave. +> The shipped ingest gesture stays drop-onto-docked-panel (S8). The degrade path (editor +> shows a "drop files onto the ReaSampler bank panel to add them" affordance) landed as +> part of Phase S. See `COMPLETED.md` §S13 for full context. -- [x] CMake second target: a separate VST3 module artifact built alongside - `reaper_reasampler` (Windows VST3 export/bundle wiring; `GetPluginFactory` + - `InitDll`/`ExitDll` — **verify exact export names against the vendored SDK**). -- [x] `SingleComponentEffect` skeleton: factory + class registration, `initialize` - declaring an event-input bus + an audio-output bus (no audio input), - `setupProcessing`, `setActive`, empty `process`. Loads silently in REAPER. -- [x] `IPlugView`↔LICE bridge spike: open a plugin editor window hosting a LICE-drawn - surface (window creation/sizing, host→draw/hit-test event routing), reusing the - `bank_panel` LICE/SWELL competence. **The decision's one real unknown — prove it - here.** (VSTGUI is the noted fallback only if this proves gnarlier than the panel - work suggests.) -- [x] Bridge read spike: resolve `GetProjExtState`/`EnumProjExtState` by name via - `IReaperHostApplication::getReaperApi` (host project context via `getReaperParent(3)`) - from `reaper_vst3_interfaces.h`, and read a known `"reasampler"` ext-state value. - (The `0xdeadf00d`/`0xdeadf00e` opcodes are the VST2 path — verified not applicable here.) +- [ ] Cross-artifact ingest relay: the editor hands the dropped path + this instance's + identity to the extension as a bank-ingest request over an agreed seam. DEFERRED — + relay mechanism proved load-bearing to redesign; drop-onto-panel (S8) is the shipped + ingest path. Requires (a) a new instrument WRITE seam into ext-state and (b) an + extension-side timer poller + claim/clear nonce. A future wave when the design is ready. -## S2 — `Sample` intrinsic fields (root note + loop points; in the *extension*) -**Goal:** Add the two bank-intrinsic seam fields to `Sample` — **root note** (MIDI -note the sample was recorded at; distinct from the existing optional *musical key*) -and **loop points** (sustain-loop start/end, sample-accurate, zero-crossing-aware) — -as an additive field extension with JSON round-trip, populated at/after capture. This -touches the **extension** codebase, is independently shippable, and lands early to -close the backfill cliff before the instrument consumes the fields. CONTEXT.md -§Phase S (seam fields, D-B). **Same additive shape as `provenance` (M1).** -**Verify:** CTest green. Round-trip lossless across the new fields; pre-existing -samples (no root note / loop points) deserialize with clean defaults (no loss, no -migration break); capture populates root note where derivable and loop points where -set; relative-paths-only unaffected; `BankIndex` behavior unchanged (purely -additive). -**Depends on:** nothing in Phase S (extension-only; can land before or in parallel -with S1). +## Phase S — held and optional-forever (noted, not specified) -- [x] Add `rootNote` (optional MIDI note) + `loopStart`/`loopEnd` (optional - sample-accurate loop points) to `Sample`; JSON serialize/deserialize with clean - defaults for samples lacking them (additive, backward-compatible — mirror of how - `provenance` was added). -- [x] Populate the fields on capture where derivable (root note) / settable (loop - points); leave them cleanly empty otherwise. No existing `Sample` field changes. -- [x] Tests: full round-trip lossless including the new fields; a legacy `Sample` - JSON (no new fields) parses with defaults and re-serializes without loss; additive - invariant (no change to existing fields, dedup, tier, or `BankIndex` behavior). +> S3–S11 have landed; archived in `COMPLETED.md`. S12 and S13 (partial) have also +> landed; archived in `COMPLETED.md`. The cross-artifact relay (S13) remains deferred — see §S13 above. -## S3 — pure sampler core (voice engine / envelope / keymap / repitch) -**Goal:** The REAPER-free **and** VST3-free sampler core — voice allocation/polyphony, -amplitude envelope (ADSR), key→sample and velocity→sample mapping (the keymap), -repitch/interpolation from root note, keymap resolution — unit-tested in CTest against -known signals. **The heart of the phase (D3); the mirror of -`bank_model`/`peaks`/`view_mode_model`/`bank_book`; test it hard.** The core is -invariant under the build-shape choice — no VST3 or REAPER type at its boundary. -CONTEXT.md §Phase S (pure core, module architecture). -**Verify:** CTest green. Voice allocation is correct under polyphony (note-on/off, -voice stealing where bounded); ADSR shape asserted against a known signal (mirror of -`peaks`); repitch from root note produces the expected pitch ratio; keymap resolution -maps a (note, velocity) to the correct sample/zone; the core takes and returns only -plain data (no VST3/REAPER types) — enforced by the test target linking neither SDK. -**Depends on:** S2 (consumes `rootNote` / loop points as core inputs). +> S8 has landed; archived in `COMPLETED.md`. -- [x] Voice engine: polyphonic voice allocation (note-on/off, bounded voice stealing), - per-voice state, mono-and-basic-polyphony sufficient for Tier 0. -- [x] Amplitude envelope (ADSR) math — asserted against a known signal. -- [x] Repitch/interpolation from root note (chromatic pitch ratio across the - keyboard); loop-point-aware sustain for held notes. -- [x] Keymap model + resolution: key ranges/zones (Tier-1 shape) and the - (note, velocity) → sample/zone query; Tier-0 chromatic-from-single-root as the - degenerate case. -- [x] Tests: voice allocation under polyphony + stealing; ADSR envelope shape; - repitch pitch-ratio correctness; keymap resolution (single-root chromatic + zoned); - core boundary is plain-data-only (no VST3/REAPER types). - -## S4 — Tier 0: "the bank plays" (single sample, chromatic) -**Goal:** The honest MVP — one bank sample mapped chromatically across the keyboard -from its root note, basic polyphony, a simple amp envelope, velocity→volume. Wire the -S3 core into the S1 VST3 shell over the live-state seam (bridge-read bank + audio via -the M4 project-relative path machinery). Editor deferrable behind a parameters-only -default view. CONTEXT.md §Phase S (Tier 0, seams). **Delivers the core promise.** -**Verify (in DAW):** on an instrument track, the VST3 plays a chosen bank sample -MIDI-triggered, repitched chromatically from its root note, with basic polyphony, -an amp envelope, and velocity→volume; it reads the live `"reasampler"` bank via the -bridge and resolves the WAV audio the same project-relative way `persist` does; -following the active project works; it never captures and never inserts into the -arrange (read-only over the bank). -**Depends on:** S1, S2, S3. - -- [x] VST3 `process` marshalling: read MIDI note-on/off/velocity off the event bus, - drive the S3 core, write per-voice audio to the output bus. (Block-granular event - timing at Tier 0; sample-accurate offset scheduling is a later tier.) -- [x] Live-state seam: read the bank index + selected sample's root note from - `"reasampler"` ext-state via the bridge; resolve the WAV audio path the M4 - project-relative way (shared convention with `persist`, not re-implemented — the - parent-of-.rpp derivation is extracted to `capture_paths::projectDirOfRpp`, which both - `persist` and the bridge call). Bank JSON parsed via the shared `bank_book` path (the - spike string-scan reader retired); ext-state key names shared via pure `ext_keys.h`. -- [x] Sample selection UI (minimal, in the `IPlugView` LICE editor): a clickable list - of the bank's samples; the pick is the instance's own VST3 component state - (setState/getState), never written back to the bank. -- [x] Tier-0 playback: chromatic-from-root, basic polyphony (16 voices), amp envelope, - velocity→volume — plays in REAPER's routing/record/render path like any VSTi. Sample - load / decode / keymap build happen off the audio thread and hand to `process` via a - lock-free atomic pointer swap (graveyard-reclaim); `process` never allocates. - -## S5 — Tier 1: "a keymap" (zoned multisamples, per-sample root notes) -**Goal:** Multiple bank samples zoned across the keyboard (key ranges), each with its -own root note — a captured *kit* (one-shots) or a *multisampled instrument* (same -instrument sampled at several pitches) plays correctly. One sample per key-region. -CONTEXT.md §Phase S (Tier 1). **Where the root-note + key-range seam fields earn -their place.** -**Verify (in DAW):** a keymap of several bank samples plays correctly zoned across -the keyboard, each repitched from its own root note within its range; a captured kit -and a multisampled instrument both play as expected; the keymap is authored in the -instrument (performance map) while root notes come from the bank intrinsics (S2); -editing the keymap does not touch the bank. -**Depends on:** S4. - -- [x] Keymap editor in the `IPlugView` LICE editor: assign bank samples to key ranges - (low/high note per sample), each with its own root note (from S2 intrinsics, - overridable in the performance map). -- [x] Tier-1 playback: zoned resolution — a note picks its zone's sample and repitches - from that sample's root note; one sample per key-region. -- [x] Performance-map persistence: the keymap (zones, per-sample assignment) is the - instrument's own state — held in the instrument as VST3 component state (setState/getState) - per D-B's data-ownership split; the live `"reasampler"` seam is read-only (bank + - intrinsics in, nothing written back), never written back as a bank intrinsic. - -## S6 — embedded TCP/MCP UI (D-D — scheduled in-phase, after the editor) -**Goal:** Render a compact keymap/level strip **inline in the track/mixer control -panel** via `reaper_plugin_fx_embed.h` (`IReaperUIEmbedInterface`) — the same -Cockos surface REAPER's own embedded FX use — so the instrument draws inline, not only -in its own window. Composes with the S1/S5 LICE editor path (same LICE-class drawing). -**Scheduled, not deferred (D-D settled 2026-07-26):** a real later point, sequenced -last because it is polish over a Tier-0 need — but on the roadmap. CONTEXT.md §Phase S -(embedded UI, D-D). -**Verify (in DAW):** the instrument draws a compact inline strip in the TCP/MCP (not -only its own editor window); the inline surface reflects and (where offered) edits the -keymap/levels; the embed lifecycle is clean (open/close/resize); the same LICE drawing -as the main editor is reused. -**Depends on:** S5 (composes over the existing LICE editor). **Must-verify before -build:** the `IReaperUIEmbedInterface` contract + embed message/lifecycle against -`vendor/reaper-sdk/sdk/reaper_plugin_fx_embed.h`. - -- [x] Implement `IReaperUIEmbedInterface` on the VST3; draw a compact keymap/level - strip inline in the TCP/MCP using the same LICE surface as the editor. -- [x] Embed lifecycle (open/close/resize/hit-test inline) handled cleanly; reflects - the live keymap/levels. - -## S7 — stereo channel mode (mono | stereo; core channel dimension + bus negotiation) -**Goal:** Give the instrument a per-instance **channel-mode toggle — 1 (mono) or 2 -(stereo)** — that "works with the REAPER audio bus automatically." Mono keeps today's -downmix path; stereo grows the S3 core a **channel dimension** (2-channel sample data, -per-voice stereo render, stereo interp/loop) and negotiates the VST3 output bus so -mono/stereo just works in REAPER's routing. **This is an S3-core extension, not a shell -hack** — it touches the engine Daniel smoke-tests, so it sequences first after the -editor/embed work. CONTEXT.md §Phase S (channel mode, D-E). **Decided direction -(2026-07-26); leans below are build-time residuals, not open forks.** -**Verify (in DAW):** an instance set to stereo plays a stereo capture in true stereo, -its VST3 output bus negotiated to 2 channels via `setBusArrangements` so REAPER routes it -without manual channel wiring; an instance set to mono plays the existing downmix path; a -mono source in stereo mode plays dual-mono (centered); a stereo source in mono mode -downmixes (existing policy); the mode is per-instance state that survives project -save/reopen (component state, like the selected sample); the pure core's stereo render is -asserted against a known two-channel signal (mirror of `peaks`), and mono behavior is -unchanged (regression). -**Depends on:** S3 (extends the core), S4 (extends the process/bus shell). Independent of -S8/S9. - -- [x] Core channel dimension (pure, S3 extension): `SampleData` carries 1- or 2-channel - decoded PCM (`frames` + optional length-matched `framesR`; `channelCount()`); - `Voice::renderFrameStereo` + a `VoiceEngine::render(left,right,n)` overload produce a - per-channel frame sharing one read head + one envelope tick; stereo linear interpolation + - loop read per channel. Mono stays the degenerate case (`renderFrame` reads channel 0 only, - byte-identical). Tests: stereo render asserted against a known 2-channel signal; dual-mono; - per-channel repitch + additive mix; mono render unchanged (regression) — sampler_core_tests. -- [x] Channel-mode toggle as per-instance state: `ChannelMode {Mono,Stereo}` in the - instrument's own component state (v4 = v3 + a channel-mode byte; setState/getState); - default mono. Cross-mode policy in `decodeChannels`: **mono source + stereo mode → - dual-mono**; **stereo source + mono mode → downmix** (existing decode-side policy). The - toggle lives in the instrument, never written to the bank (D-B). v1/v2/v3 blobs lift to v4 - with mono default; round-trip + lift tests — sample_map_tests. -- [x] Shell: `decodeRelative` fills 1- or 2-channel `DecodedZonePcm` per the active mode - (source channel count from the WAV layout); the process path renders the host's negotiated - output channel count (stereo into ch0/ch1, mono into ch0) — RT discipline unchanged. -- [x] VST3 bus negotiation: `setBusArrangements` accepts only the mode's arrangement - (kMono/kStereo), else rejects (kResultFalse) but keeps a valid mode arrangement so - `getBusArrangement` (base default) reports it; a runtime mode change repoints the output bus - + calls `restartComponent(kIoChanged)` so REAPER re-negotiates. **Verified** against the - vendored Steinberg SDK (`ivstaudioprocessor.h` contract, `vstsinglecomponenteffect.cpp` - base impl, `ivsteditcontroller.h` kIoChanged); see handoff notes. - -## S8 — ingest through the bank (one gesture: capture/import into bank + assign to instance) -**Goal:** Loading a sample into the sampler is **one gesture** — capture/import-into-bank -**and** auto-assign to the active sampler instance. **The extension owns ingest** (it has -arrange access, media-explorer access, and drop-target surface on its own panels); the -instrument stays a **read-only bank consumer**. This lives in the *extension* codebase -(actions + bank_panel + capture/insert), routing through the existing capture add-path and -the live `"reasampler"` seam the instrument already reads. CONTEXT.md §Phase S -(ingest-through-bank contract). **Decided direction "option 1" (2026-07-26).** -**Verify (in DAW):** a one-click "capture selected item / time-selection into the bank and -assign to the active instance" action captures via the existing capture path (never -auto-inserting into the arrange — load-bearing principle intact) and the target instance -plays the new sample on its next reload; a Media Explorer file imports into the bank and -assigns the same way; a file dropped onto a ReaSampler panel surface ingests into the bank -and assigns; the instrument never captures or imports (read-only over the bank throughout). -**Depends on:** S4 (an instance to assign to), M7 capture add-path, B2 (active-bank add -target). Best paired with S9 so assignment refreshes hands-free; functional without it -(assign triggers a reload on the target instance directly). - -- [ ] "Capture selected item / time-selection into bank + assign to active instance" - action (`command_id`/`gaccel`/`hookcommand`, MIDI-bindable): reuse the existing capture - request path (`CountSelectedMediaItems`/`GetSelectedMediaItem` + `GetSet_LoopTimeRange` - as the capture inputs), add the resulting `Sample` to the active bank, then assign its - id to the target instance. **Never inserts a timeline item** (capture/placement stay - separate — the assignment is a bank-index + instance-selection act, not a placement). -- [ ] Media Explorer import → bank → assign: read the Media Explorer's current selection - via `MediaExplorerGetLastPlayedFileInfo` (path + selection range), import the file into - the bank (existing import/capture add-path), assign to the target instance. **Honest SDK - limit (verified against the vendored headers):** the Media-Explorer surface is thin — - `OpenMediaExplorer` (open/select) + `MediaExplorerGetLastPlayedFileInfo` (read the *one* - last-played/selected file + its range) 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 the user fires while a file is - selected in the ME), not a push/drop from inside the Media Explorer. **Spike:** confirm - `MediaExplorerGetLastPlayedFileInfo` returns a usable path+range for a merely-*selected* - (not-yet-played) file, or whether a play is required first. -- [ ] Drag-and-drop onto ReaSampler surfaces: accept an OS file drop onto the docked - `bank_panel` (and its bank/tab regions) → ingest into the bank → assign. **Honest SDK - limit (verified):** REAPER exposes **no** drag-drop registration API; drop handling is on - ReaSampler's *own* HWNDs via SWELL/Win32 (`WM_DROPFILES` / an `IDropTarget` on the panel - HWND), the same surface the panel already owns. **Assess-and-flag (spike, do not promise - here):** 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 to the extension over an agreed seam). Reported - honestly as a spike because it crosses the two-artifact boundary and the relay mechanism - is unproven; if it proves gnarly, drop-onto-panel is the shipped path and drop-onto-editor - is deferred. -- [ ] "Assign to instance" seam: how the ingest action names the target instance and hands - it the new sample id. Lean (build-time residual, not a fork): the active/last-focused - instance is the target, discovered via the host context the bridge already resolves; the - assignment is the same instance-owned selection state S4 already persists, so a reload - picks it up. If the change-detection seam (S9) exists, assignment refreshes hands-free; - without it, the ingest action pokes the target instance's reload directly. - -## S9 — bank-generation change-detection (recapture / ingest refreshes instances hands-free) -**Goal:** Because instances reference sample **ids**, a **recapture** (M10) landing under -the same id — or an **ingest** (S8) touching the active bank — should refresh playing -instances **hands-free**, without the user re-opening each editor. Add a **bank-generation -counter** to `"reasampler"` ext-state that the extension bumps on any bank-content -mutation, and that the instrument polls off the audio thread on a safe cadence, calling its -existing `reloadFromBank()` when the generation changes. CONTEXT.md §Phase S -(bank-generation seam). **Closes the missing change-detection trigger the recapture -auto-update story needs.** -**Verify (in DAW):** a recapture that regenerates a sample already assigned to a live -instance refreshes that instance's playback within a bounded cadence, no editor re-open; an -ingest (S8) that updates the active bank likewise refreshes assigned instances; the poll -runs off the audio thread (never in `process`) and triggers the existing off-thread reload -path; instances not referencing a changed sample do not audibly glitch (reload is atomic — -the S4 graveyard-reclaim handoff); a project with no generation stamp (pre-S9) defaults -cleanly (treated as generation 0; first bump refreshes). -**Depends on:** S4 (the off-thread `reloadFromBank` + atomic handoff this drives). Writer -side is extension-only and independent of S8; consumed by S8 and M10 recapture. Best landed -alongside S8. - -- [x] Writer (extension): a monotonic **bank-generation counter** stamped into - `"reasampler"` ext-state (new `ext_keys.h` constant — forever-stable spelling), 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. -- [x] Reader (instrument): poll the generation over the bridge on a safe **off-audio-thread - cadence** (a UI/timer tick, not `process`), compare to the last-seen value, and call the - existing `reloadFromBank()` on change — reusing S4's atomic pointer-swap handoff so a - refresh mid-play does not glitch. No new audio-thread work; no allocation in `process`. -- [x] Cadence + coalescing: pick a poll interval that is responsive but cheap (build-time - residual — a low-frequency UI timer, coalescing multiple bumps between polls into one - reload). **Must-verify before build:** that a bridge ext-state read on the instrument's - UI/timer thread is safe against a concurrent extension write (the read already tolerates a - stale value by design — it reloads on the *next* poll; confirm no torn-read hazard for the - single integer generation key). +> S9 has landed; archived in `COMPLETED.md`. > **S0-DS moved to Phase L (2026-07-26).** The shared LICE drawing kit that stood here is > now **Phase L point L1** on `dev` — see PLAN.md §Phase L + CONTEXT.md §Phase L and > `docs/product/visual-design-language.md` (all on `dev`). S10–S13 below build with the > current drawing and **adopt the L1 kit when it lands — not gated on Phase L.** -## S10 — capture-first editor: browser + guided single-capture setup ("ReaSampler 9000" UX overhaul, part 1) -**Goal (REVISED 2026-07-26 — workflow-first reframe, Daniel):** Rebuild the editor's -default face around the **primary flow = one capture, fast**, not a keymap. A giant list of -"item" blocks is visually useless; most instances play a *single capture*, and zones are a -nice-to-have. So the default view is a **capture browser** (scannable cards with peak -thumbnails, name, root/key badge; **bank filter**) feeding a **guided single-capture setup** -(root note, play-mode basics, level) — and the keyboard strip serves the *single-capture* -case first (shows where the capture sits / its root). **Time-to-first-note is the metric.** -Multi-zone keymap editing is **demoted to an opt-in "Zones" panel** (S10-Z below), not the -default. The keyboard-strip drag machinery is still built here, but in service of the -capture-first layout. All layout/hit-test math is **pure geometry** (new `keyboard_strip` + -a `capture_browser` layout module — mirrors of `mode_switch`/`editor_geometry`); the LICE -draw + drag-state machine is the editor shell. RT discipline untouched (edits commit -off-thread via `commitMapAndReload`); the instrument stays a **read-only bank consumer**. -CONTEXT.md §Phase S (ReaSampler 9000 UX — capture-first editor). +> S10, S10-Z, and S11 have landed; archived in `COMPLETED.md`. -**Policy reversal — fresh instance is SILENT, nothing auto-selected (was S4).** The S4 -"first sample plays" fallback is **removed**: on open with no stored selection, the -instrument plays **nothing** and the editor shows a clear **empty state** ("pick a capture") -— it does not auto-play sample #1. Retires the `selectSample` first-sample fallback -(`sample_map.cpp` "No stored id → fall back to the FIRST sample") and the processor's -Tier-0 fallback that resolved it; an empty stored id now resolves to silence. A capture is -loaded when the user picks one (or via S13 drop-to-load / S8 ingest). This is a deliberate -reversal of the S4 convenience default, not a regression. +> S12 has landed; archived in `COMPLETED.md`. -**Verify (in DAW):** a fresh instance plays **nothing** and shows the "pick a capture" -empty state (no auto-play of sample #1); the capture browser draws **peak thumbnails** -(the `Sample` peaks bank_model already carries — same data the dock panel thumbnails use), -name, and a root/key badge where present, and is **filterable by bank** (bank_book named -banks); picking a capture loads it, shows it (waveform/peaks + its root on the keyboard -strip), and it plays repitched from its root; time-to-first-note is a pick-then-play, not a -list-scroll; the keyboard strip shows the single capture's root and is draggable to set it; -the pure geometry modules are CTest-green (browser card/grid layout + hit-test; strip -edge-grab/body-move/key→note) with no host types at their boundary; the ±1 nudge-button row -is gone. -**Depends on:** S4 (the selection state + reload path this reverses the fallback on), S1 -(the LICE `IPlugView` drag/event routing — extends the click-only `wndProc` to -`WM_MOUSEMOVE`/`WM_LBUTTONUP`), S5 (the `PerformanceMap`/zone model the opt-in Zones panel -edits — but the default face does not require a keymap). **Adopts the Phase L kit when -available — not gated on Phase L.** S10 builds its browser cards + keyboard strip with the -current LICE drawing; when Phase L's L1 kit lands on `dev`, this surface adopts it (the one -source of drawing). The drag machine's `WM_MOUSEMOVE` tracking also lights the kit's -**hover** states at near-zero marginal cost once the kit is present. +> S13 (drop-to-load) has partially landed; archived in `COMPLETED.md`. Cross-artifact relay remains deferred — see §S13 above. -- [ ] No-auto-select + empty state (the policy reversal): remove the `selectSample` - first-sample fallback (`sample_map.cpp`) and the processor's Tier-0 fallback that - consumed it — an empty stored selection resolves to **silence**, not sample #1. The - editor draws a clear **empty state** ("pick a capture" affordance) when nothing is - selected. Pure change is testable (empty id → `nullopt`); the empty-state draw is shell. -- [ ] Capture browser (pure layout + shell draw): grow `SampleChoice` to carry the - **peak thumbnail data** (from the `Sample` peaks bank_model already stores — the same - peaks the dock panel draws), the **root/key badge** (S2 `rootNote` intrinsic / the - optional musical key), and its bank. A new pure `capture_browser` module lays out - scannable **cards/rows** (card rect grid, thumbnail rect, hit-test a point → card) — no - host types at the boundary, unit-tested. The shell draws each card's peak thumbnail + - name + badge in LICE (house palette) and routes a click to select. -- [ ] Bank filter (pure + shell): a filter/tab strip over the browser that narrows the - drawn cards to a chosen bank_book bank (or "all"). Filter-tab layout + hit-test pure - (mirror of `mode_switch`); the active-filter state is transient UI state; the shell draws - the tabs and applies the filter to the card list. (Type-to-filter search folds in from - S12 — see S12's boundary note; a name-substring filter over the same card list.) -- [ ] Guided single-capture setup (the fast path): once a capture is picked, a prominent, - self-explanatory setup surface — **root note** (settable on the keyboard strip / typed), - **play-mode basics**, **level** — sized for the single-capture case, not a zone table. - Graphic and descriptive; the point is to get from pick → set → play with no hunting. -- [ ] Pure `keyboard_strip` geometry module (serves the single-capture case first): map a - MIDI key span across a strip width (128 keys → pixels, reusing the S6 `embed_strip` - key-span idiom); a **root marker** for the loaded capture; `pixel→note` and a `keyAtPoint` - for click-to-set-root; a drag-delta resolver `(grabbedField, startNote, dxPixels) → - newNote`; **per-zone bar rect** + **edge-grab hit regions** (resize handles vs. body - move-handle) for the opt-in Zones panel. No VST3/REAPER/LICE types at the boundary; - unit-tested (root marker, edge grabs, body-move delta, key mapping, clamps low≤high, - boundary rounding). Mirror of `mode_switch`/`editor_geometry`. -- [ ] Editor shell drag-state machine: `WM_LBUTTONDOWN` grabs a card / a key / a zone - edge-or-body, `WM_MOUSEMOVE` updates the in-flight edit against the pure resolver, - `WM_LBUTTONUP` commits via the existing `commitMapAndReload` (off-thread reload; RT path - untouched). Live visual feedback while dragging; a single undo-coherent edit on release. +> S15 has landed; archived in `COMPLETED.md`. -### S10-Z — Zones panel (opt-in multi-zone keymap editing; demoted from the default face) -The multi-zone keymap editor is now an **opt-in view/panel** ("Zones" toggle), not the -default. It reuses the same `keyboard_strip` geometry and drag-state machine: each zone a -bar over the keys it covers; **drag an edge** → low/high note; **drag the bar body** → move -the zone (span preserved); **click a key** → set/relocate the zone's root. This is the -capability RS5K structurally lacks (multi-zone in one instrument), kept as a *nice-to-have* -per Daniel's hierarchy — "most of the time the zones won't be used." Add/select/delete a -zone; overlapping zones render legibly and resolve first-match. The seven ±1 nudge/delete -mini-buttons are retired everywhere; delete is one affordance (a small × on the bar or a -keystroke). The `zoneHitTest`/±1 nudge path in `editor_geometry` is retired (a numeric -fallback for accessibility is a build-time residual, not a fork). -**Verify (in DAW):** the Zones panel is reachable via an explicit toggle (default view is -the capture browser + single-capture setup, not this); a zone's range is set by **dragging -edges** (not nudge clicks); body-drag moves the span; click-a-key sets the root (audible on -the next held note); zone add/select/delete work; the ±1 nudge row is gone. +> S16 has landed; archived in `COMPLETED.md`. -- [ ] "Zones" panel toggle (opt-in): the default editor face is the capture browser + - single-capture setup; a toggle reveals the multi-zone keymap editor. Toggle state is - transient UI state (or per-instance component state if it should persist — build-time - residual). -- [ ] Zone edit via the shared strip: draw the keyboard strip + zone bars in LICE, drive - the shared drag-state machine (edge = resize, body = move, key = root), commit via - `commitMapAndReload`. Zone add/select/delete as single affordances; ±1 nudge row gone. +> S17 has landed; archived in `COMPLETED.md`. -## S11 — waveform view with draggable loop points (UX overhaul, part 2) -**Goal:** Give each sample/zone a **waveform display** with **draggable start/end/loop -markers** — the S2 loop-point intrinsics and the S5 performance map already carry the data; -today there is no way to *see* a sample or *set* its loop by eye. Selecting a zone (or a -bank sample) shows its waveform (peaks via the existing `peaks` module, fed the decoded -PCM the shell already loads); drag the **loop-start / loop-end** markers to set the sustain -loop, snapping to zero-crossings (the S2 spec's zero-crossing-aware requirement). Loop -points are a **performance-map override on the zone** where set, seeded from the bank -intrinsic (D-B split: the bank carries the file-fact default; the instrument's drag is the -performance choice). All marker/waveform layout + hit-test is pure geometry; peaks compute -reuses `peaks`; the draw + drag is the shell. CONTEXT.md §Phase S (ReaSampler 9000 UX — -waveform view). -**Verify (in DAW):** selecting a zone shows its sample's waveform; dragging the loop-start -and loop-end markers sets the sustain loop and a held note audibly loops that region; -markers snap to the nearest zero-crossing; a sample with no loop shows the "no loop" state -and a held note past the end goes silent (existing core behavior); the waveform peaks match -the audio (mirror of the `peaks` envelope assertion); the marker geometry module is -CTest-green (px↔frame mapping, marker grab regions, clamp start≤end). -**Depends on:** S2 (loop-point intrinsics), S3 (loop-aware sustain the markers drive), S5 -(the zone the loop attaches to), S10 (shares the editor's drag-state machine + shell). The -zero-crossing snap is a small pure helper over the decoded PCM. - -> **Boundary note (S10 reframe, 2026-07-26):** the waveform view is now **central to the -> single-capture fast path**, not just per-zone. Selecting a capture in S10's browser shows -> its waveform (this is "see it" in pick → see it → play it); the loop-marker drag here -> extends that same waveform surface. S11's waveform draw is the same one S10's picked- -> capture view uses — build it once, S10 shows it read-only for the single capture, S11 adds -> the draggable loop markers. No renumber; S11 stays the loop-editing point. - -- [ ] Pure waveform/marker geometry: `frame↔pixel` mapping across the waveform rect, marker - x-position from a frame index, marker grab regions (start/end/loop-start/loop-end), - drag-delta `(grabbedMarker, dxPixels) → newFrame` with clamps (start≤end, in-bounds). A - **zero-crossing snap** helper: nearest sign-change frame to a target (pure, over the - decoded mono PCM). No host types; unit-tested. -- [ ] Waveform draw: compute peaks with the existing `peaks` module from the shell's already- - decoded PCM (no new decode path, no new WAV reader); draw the envelope in LICE in the - house style; draw the loop markers over it. Reuses the S10 drag-state machine. -- [ ] Loop-point edit → performance-map override: a dragged loop writes a per-zone loop - override (seeded from the S2 bank intrinsic, D-B), committed off-thread via - `commitMapAndReload`; the bank intrinsic is never written back (instrument is a read-only - bank consumer). Extends `PerformanceZone` with an optional loop override (additive, same - shape as `rootOverride`) + its component-state (de)serialize (version bump, back-compat - with S5's v2 map blob — a truncated/older blob defaults the override absent). - -## S12 — editor scale + ergonomics (UX overhaul, part 3; scrollable/searchable list, direct entry) -**Goal:** Make the editor usable **at bank scale** and close the remaining RS5K-parity -gaps: the sample list **scrolls** (today a long bank's rows run off the panel with no way -to reach them) and has a **type-to-filter search**; add **direct numeric entry** for a -zone's low/high/root (a click-to-type field over the strip, for precision the drag can't -hit) and an **ADSR control** for the amp envelope (S3 already has the ADSR math; today it -is fixed — expose attack/decay/sustain/release as draggable sliders, per-instance state). -This is the "sensible list handling + direct manipulation of the parameters that exist" -tier. All slider/scroll/search-box layout + hit-test is pure geometry; the shell draws + -routes; ADSR/scroll/filter state is instrument-owned (component state / transient UI -state). CONTEXT.md §Phase S (ReaSampler 9000 UX — scale + ergonomics). -**Verify (in DAW):** a bank with more samples than fit **scrolls** (wheel + drag) and every -sample is reachable; typing filters the list to matching names; a zone's low/high/root can -be **typed** (not only dragged) via a click-to-edit field; the amp envelope's ADSR is -**adjustable** (four draggable controls) and the change is audible + persists across project -save/reopen (component state); the scroll/search/slider geometry is CTest-green. -**Depends on:** S10 (the editor shell + drag-state machine + the **capture browser** the -scroll/search now apply to), S3 (the `AdsrParams` the ADSR sliders drive — already wired -into the voice engine; today they are fixed defaults), S5 (the map the numeric fields edit). - -> **Boundary note (S10 reframe, 2026-07-26):** the "sample list" S12 originally scrolled and -> searched **is now S10's capture browser** (cards with peak thumbnails, bank filter). What -> pulled INTO S10: the browser layout itself, the peak thumbnails, and the **bank filter** -> (a bank_book tab, distinct from name search). What stays in S12 and applies **to S10's -> browser**: (a) **scroll** for a bank longer than the panel, and (b) **type-to-filter -> search** (a name-substring narrow over the same cards, composing with S10's bank filter — -> bank filter picks the bank, search narrows within it). The scroll/search geometry is pure, -> layered over the `capture_browser` module S10 builds. Net: S12 = scroll + search over the -> S10 browser + numeric entry + ADSR; the browser *card* work is S10's. **S12 now also -> carries the S15/S16 control surfaces** (per-zone Gate/Trigger mode toggle, AHDSR hold -> control, Trigger %-length/fade controls, Varispeed/Preserve engine toggle, and the AD pitch -> envelope depth/shape controls) — deferred here from S15 and S16 per spec. - -- [x] Scrollable, searchable capture browser: a scroll offset (wheel + scrollbar drag) so a - bank longer than the panel is fully reachable; a **type-to-filter search** that narrows - the drawn cards to matching display names, **composing with S10's bank filter** (bank - filter selects the bank; search narrows within it). Scroll/search layout + hit-test is - pure geometry (visible-card window, scrollbar thumb rect, search-box rect), layered over - S10's `capture_browser` module; filter/scroll state is transient UI state. **Landed:** - pure `browser_scroll` module (`browser_scroll_tests`) — scrollContentHeight / max / clamp, - visibleCardRange window, scrolledCardCellRect, scrollThumbRect + thumbDragToOffset inverse, - searchBoxRect, nameMatchesQuery + filterNameIndices. Editor shell wires wheel (`WM_MOUSEWHEEL`), - thumb-drag (`DragKind::kScrollThumb`), and the search box (`WM_CHAR` -> `onSearchChar`, - composed into `rebuildVisible`). Scroll/search are transient (never persisted). -- [x] Direct numeric entry for zone low/high/root: a click-to-edit field over the strip - (LICE text-entry idiom) so a precise note can be typed, not only dragged. Commits via - `commitAndReload` like every other edit. **Landed:** pure `note_entry` module - (`note_entry_tests`) — `parseNoteEntry` accepts a decimal integer OR a note name (C4==60), - clamps to [0,127], rejects garbage. Editor shell hosts three focusable fields (low/high/root) - on the Zones legend, committing on Enter through `commitAndReload`. -- [x] ADSR/AHDSR editor + S15/S16 control surfaces: draggable sliders over the S3 `AdsrParams` - (attack/**hold**/decay/sustain/release — hold is the S15 addition) plus the deferred S15/S16 - controls — per-zone Gate|Trigger mode toggle, Trigger %-length/fade-in/fade-out, Varispeed| - Preserve engine toggle, and the AD pitch-envelope enable/attack/decay/±semitone depth. All - edit the SELECTED zone's `ZonePlayParams` (instrument-owned, D-B; never the bank), round-trip - through the existing v3 component-state blob (no new persistence — the S15/S16 payload already - landed in the core pass), and commit off-thread via `commitAndReload`. **Landed:** pure - `param_slider` module (`param_slider_tests`) — control-panel stack layout, toggle-segment - split + hit-test, slider value<->pixel round-trip + clamping, point->control routing. The - shell owns the control-id -> engine-param binding + the value DOMAIN mapping (frames/fraction/ - semitones); the module stays engine-free. - -## S13 — drop-to-load: the S8 ingest story, folded into the editor UX (UX overhaul, part 4) -**Goal:** Make "load a sample into the sampler" **one gesture from the editor**: dropping -an OS file (or REAPER media item) **onto the editor window** ingests it into the bank and -assigns it to this instance — the RS5K "drag a file straight onto it" affordance, which is -the single biggest first-impression win RS5K has and we currently lack. This is the -**editor-window end of S8's `option 1` ingest** — the instrument does **not** ingest itself -(it stays a read-only bank consumer); the editor's drop handler **relays a bank-ingest -request to the extension** over the agreed cross-artifact seam, and the extension performs -the capture/import-into-bank + assign. S8 already flags drop-onto-editor as an unproven -cross-artifact **spike** — this point is where that spike is either proven and shipped or -falls back to the docked-panel drop path. CONTEXT.md §Phase S (ReaSampler 9000 UX — drop to -load / S8 relay). **Cross-artifact relay is a spike, not a promise — sequence after S8.** -**Verify (in DAW):** an OS file dropped onto the ReaSampler 9000 editor window ingests into -the active bank and this instance plays it (via the S8 capture/import add-path + S9 refresh, -or a direct reload if S9 absent) — **never** inserting a timeline item (capture/placement -separation intact); the instrument itself performs no capture/import/write (the editor only -*relays* the request to the extension); if the cross-artifact relay proves unworkable, the -drop-onto-docked-`bank_panel` path (S8) is the shipped ingest and this degrades cleanly with -a clear affordance pointing there. -**Depends on:** S8 (owns the extension-side capture/import + assign, and the relay seam), S1 -(the editor HWND that accepts the drop), S9 (hands-free refresh after assign; functional -without it via a direct reload). **Spike — do not promise the drop-onto-editor path until -the relay is proven.** - -- [x] Editor-window drop target: accept `WM_DROPFILES`/`IDropTarget` on the editor child - HWND (the same SWELL/Win32 surface `bank_panel` owns), extracting the dropped file - path(s). Windows-only (D5). This is the *acceptance* half; the ingest is the extension's. - **Landed:** the editor child window calls `DragAcceptFiles(TRUE)` on attach and handles - `WM_DROPFILES` (`reasampler_editor.cpp`). Windows-only (D5). -- [ ] Cross-artifact ingest relay (the S8-flagged spike): the editor hands the dropped - path + this instance's identity to the extension as a **bank-ingest request** over the - agreed seam (the instrument never writes the bank). **Prove the relay mechanism before - promising it**; if gnarly, fall back to the S8 docked-panel drop path and mark - drop-onto-editor deferred. **SPIKE VERDICT (ps-w12, 2026-07-27): DEGRADED — relay - deferred.** The instrument's REAPER bridge (`reaper_bridge`) is deliberately READ-ONLY - (resolves only `GetProjExtState`, never `SetProjExtState`); a relay would need (a) a new - instrument WRITE seam into ext-state and (b) an extension-side timer poller servicing a - drop-ingest inbox key with a claim/clear nonce — the SAME cross-process handshake race the - S17 spec rejected for its own alternative (A). Both the read-only-instrument boundary and - the new poller are load-bearing design calls, so the relay is deferred to a future wave and - surfaced as a decision, not crossed unilaterally. The shipped ingest gesture stays - drop-onto-docked-panel (S8). The drop-onto-editor path degrades cleanly (below). -- [x] UX degrade path: when the relay is unavailable/unproven, the editor shows a clear - "drop files on the ReaSampler panel to add" affordance rather than silently swallowing the - drop — the shipped ingest gesture stays discoverable either way. **Landed:** the editor - ACCEPTS the drop and flashes a transient banner ("drop files onto the ReaSampler bank panel - to add them") that decays over a few sync ticks, plus a persistent affordance line in the - empty state ("drop a file onto the ReaSampler bank panel"). No file is ingested; NO timeline - item is ever inserted (the hard invariant — the editor only displays guidance). - -## S15 — sampling modes: Trigger vs Gate (per-sample play-mode; core + editor) -**Goal:** Give each played sample a **play mode** — **Gate** (classic held note) or -**Trigger** (one-shot) — a per-sample/per-zone performance choice (D-B, instrument-owned). -**Gate** is today's behavior grown from ADSR to **AHDSR** (adds a Hold stage): note-on → -attack/hold/decay/sustain, note-off → release, sustain **loop points apply** (S11's -draggable loop UI is Gate-mode UI). **Trigger** is a one-shot drum-pad: note-on fires -playback of a defined **% of sample length** with a **fade-in** and **fade-out** ramp, -**ignores note-off**, and uses **no sustain loop**. **Both** modes carry a **modifiable -start point** (playback begins at an offset into the sample, not always frame 0). This is -an **S3-core extension** (the engine Daniel smoke-tests) plus editor surfacing — the mode + -its parameters are instrument performance-map state, never a bank fact. CONTEXT.md §Phase S -(Sampling modes — Trigger vs Gate). **Daniel's feature set is settled; the leans below are -build-time residuals, not open forks — except the flagged forks S15-F1/F2.** -**Verify (in DAW):** a sample in **Gate** mode plays held with the AHDSR envelope (hold -stage audible between attack and decay), releases on note-off, and loops its sustain region -if loop points are set; a sample in **Trigger** mode fires a fixed % of its length on -note-on with audible fade-in/out, **plays through to completion regardless of note-off**, -and never sustain-loops; the **start point** offsets playback in both modes (a note starts -partway into the sample); the mode + parameters are per-instance component state that -survive save/reopen; the pure core's Trigger envelope (fade-in → hold → fade-out over -%-length frames) and the AHDSR hold stage are asserted against known signals (mirror of -`peaks`); existing Gate/ADSR behavior is unchanged when hold=0 (regression). **Spec -channel-count-agnostic** — the mode/envelope logic is per-frame amplitude and read-position, -independent of the S7 channel dimension (§sequencing). -**Depends on:** S3 (extends the envelope + voice read-position machinery), S5 (the -`PerformanceZone` the mode + params attach to), S11 (Gate loop-point UI; Trigger's waveform -shows start + %-length + fades on the **same** waveform surface). Independent of S7 — -orthogonal dimensions (§sequencing note in CONTEXT.md). - -- [x] Core: `PlayMode { Gate, Trigger }` on the voice + the envelope split. **Gate** grows - `AdsrParams` → `AhdsrParams` (add `holdFrames` between attack and decay; hold=0 is the - exact current ADSR — back-compat). **Trigger** is a distinct envelope: play `[start, - start + lengthFraction·(frames−start))` with a **fade-in** ramp (0→1 over `fadeInFrames`) - and a **fade-out** ramp (1→0 over `fadeOutFrames` ending at the play-length end), - **ignoring note-off** (release is a no-op in Trigger). Fade curve default **equal-power** - (constant-power `sin`/`cos`, click-free on one-shots) with the shape noted; linear is a - build-time residual. Pure, unit-tested against a known signal. -- [x] Core: **modifiable start point** — the voice's initial `readPos_` is `startFrame` - (frame offset), applied in both modes; the existing per-frame `readPos_ += ratio_` read - and loop/interp machinery is otherwise unchanged. Clamp `0 ≤ startFrame < frames`. -- [x] Core: **% length → frames + fade mapping** for Trigger. `lengthFraction ∈ (0,1]` - resolves to `playEnd = start + round(lengthFraction·(frames − start))`; `fadeInFrames` / - `fadeOutFrames` clamp so their sum ≤ play length (fade-out anchored to `playEnd`). Note-off - in Trigger does nothing; the voice frees when `readPos_ ≥ playEnd` (mirror of the current - run-off-end idle). **Choke on note-off is NOT in scope** (fork S15-F1, held below). -- [x] Parameter ownership (per-sample/per-zone, instrument-owned): the play mode + its - params (Gate: AHDSR; Trigger: %-length, fade-in, fade-out; both: start point) attach to - the **capture selection / zone**, stored in the **performance map** (D-B). **Lean - (build-time residual):** start point joins `rootOverride`/loop-override as another - per-`PerformanceZone` optional override, and a per-zone `PlayMode` + its param struct is - added additively (version-bumped component state, back-compat — a truncated/older blob - defaults to **Gate**, hold=0, start=0, no fades = exactly today's behavior). **Fork - S15-F2 (flagged):** whether these live per-capture-selection (S10's single-capture flow) - **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 back-compat lift), - so one storage site serves both. Flagged because it touches S10's single-capture setup - surface shape. -- [x] Editor (S11 waveform surface, mode-aware): **Gate** shows draggable **start + loop - markers** (S11's loop UI); **Trigger** shows **start + %-length end + fade-in/out** - handles on the same waveform. A **mode toggle** per capture/zone in the guided setup - (S10) / Zones panel (S10-Z). Marker/handle geometry is pure (extends the S11 - `frame↔pixel` + marker-grab module); commits off-thread via `commitMapAndReload`. The - instrument stays a **read-only bank consumer** (mode/params are performance map, never - written to the bank). **Editor control surface deferred to S12 tier (spec-sanctioned).** - -> **S15 × S16 pitch-engine interaction (informs the S16 Preserve engine).** S15's amplitude -> semantics are defined over the voice's **source-frame** timeline, which the S16 pitch-engine -> mode (Varispeed vs Preserve) changes underneath them. Contracts to hold: -> - **Trigger %-length** — under **Preserve**, %-length is measured in **source frames** -> (`playEnd = start + round(lengthFraction·(frames − start))`, unchanged) but wall-clock is -> now **stable under transpose** (a transposed Trigger keeps its %-length duration). This is -> *cleaner* than Varispeed, where transposing a Trigger also scales its audible length. So -> S15's %-length spec is unchanged; Preserve just makes it pitch-independent. -> - **Gate sustain loop** — under **Preserve**, loop the **source read** (the `[loopStart, -> loopEnd)` source-frame region S15/S2 already defines) and feed the looped source stream -> into the shifter; the shifter transposes the **output**. Contract: *loop the source, shift -> the output* — the loop points stay source-frame facts (S11's markers are unchanged), and -> the Preserve engine sits after the loop read. Under Varispeed the loop read itself carries -> the pitch (today's behavior). -> - **Start point** — unaffected by engine: it is a source-frame offset (initial read -> position) in both, independent of how pitch is applied. -> These are S16-owned build details (the Preserve engine consumes S15's source-frame read); -> S15 lands its amplitude/read machinery source-frame-defined and channel-agnostic (S7), and -> S16's engine wraps it — no change to S15's committed points. - -## S16 — pitch engine modes (Varispeed vs Preserve) + pitch envelope (per-voice) -**Goal:** Give the sampler **two pitch behaviors** and a pitch envelope that rides whichever -is chosen. Repitch today is **Varispeed** — resampling that couples pitch and duration (an -octave up halves the note's duration; the classic sampler / RS5K default). Daniel's directive -(2026-07-26, verbatim: *"isn't that ratio stuff going to change the playback rate? I want -duration-preserving repitching"*) adds **Preserve** — duration-preserving repitch, where a -transposed note keeps its original length. Both are musically legitimate: **drums / one-shots -often want varispeed character** (the pitch-down-lengthens-the-hit sound), **tempo-locked -loops and phrases want Preserve** (a repitched loop still lines up to the bar). So the shape -is a **per-zone/per-capture pitch-engine mode** — a **Varispeed** engine (current, cheap, -`readPos_ += ratio_` resampling) vs a **Preserve** engine (duration-preserving pitch shift). -On top of either engine rides a per-voice **AD pitch envelope**, **off by default** — a short -attack-decay pitch modulation (the classic percussive **pitch drop**): under Varispeed it -biases `ratio_`; under Preserve it biases the shifter's shift amount. Per-instance -performance-map state (D-B). CONTEXT.md §Phase S (Pitch engine modes + pitch envelope). -**Feature settled per the directive; the engine default is a flagged Daniel fork (S16-F1), -the Preserve-engine implementation choice is a flagged fork (S16-F2).** -**Verify (in DAW):** -- **Varispeed engine** (per-zone): a note an octave up plays **half as long** as the root - note (pitch and duration coupled) — the current behavior, now explicitly the Varispeed mode. -- **Preserve engine** (per-zone): a note an octave up plays at the **same duration** as the - root note (pitch shifted, length held) — a Gate held note sustains as long as held; a - Trigger one-shot at %-length keeps its %-length wall-clock regardless of transpose. -- **Pitch envelope off** (default) under **either** engine: playback is identical to the - engine's un-modulated output (regression — no pitch modulation applied). -- **Pitch envelope on**: an AD envelope makes a note **start offset in pitch and glide to the - zone's base pitch** over attack+decay (percussive drop when the offset is positive-then- - settle); range settable in **semitones (±)**; per-voice (polyphonic notes each run their own). -- **Preserve CPU / voice-cap:** with a chord of Preserve-mode voices, CPU stays within budget - and no audio dropout at the polyphony cap; if Preserve is materially heavier, a **Preserve- - mode-specific voice cap** kicks in (below the Varispeed cap) rather than glitching. -- **Latency honesty:** a Preserve note has a small onset latency (the shifter's window); the - spec accepts this as a Preserve-mode property, and a **note-onset click/smear is absent** - (the shifter is pre-warmed at voice-allocation, not cold-started in `process`). -- **RT-safety:** no allocation in `process` for **either** engine — the Varispeed path is the - same per-frame tick idiom as the amp envelope; the Preserve shifter's buffers are - pre-sized/pre-warmed at voice allocation and reused (no queue growth in steady state). -- Pure-core assertions: the pitch-envelope curve against known values (offset at t=0, base at - t=attack+decay); the Varispeed ratio math; the Preserve engine's duration invariance (a - transposed render is the same frame-length as the un-transposed render). -**Depends on:** S3 (the voice read-increment + envelope tick idiom; the Varispeed path *is* -the current read loop), S5 (the `PerformanceZone` the mode + envelope attach to), S15 (the -per-zone param plumbing + component-state version bump the mode/envelope hang on; and the -Gate-loop / Trigger-%-length semantics the Preserve engine must honor — see S15 interaction -below). Independent of S7 (both engines operate per-frame, channel-count agnostic). - -- [x] Core: **pitch-engine mode on the voice/zone** — `PitchEngine { Varispeed, Preserve }`. - **Varispeed** = today's path (`readPos_ += ratio_`, `ratio_ = pitchRatio(note,root)`), pitch - and duration coupled. **Preserve** = duration-preserving: the read advances at the **source** - rate (duration held) while a pitch shifter transposes the output by - `2^((note−root)/12)`. Mode is per-`PerformanceZone` performance state (D-B), additive/ - version-bumped; **default is S16-F1 (flagged Daniel fork — lean Preserve, argued below).** - Absent/older blob → the fork's default. Pure where possible: the Varispeed math and the - duration-invariance contract are unit-tested; the Preserve DSP core is unit-tested for - duration invariance and transpose correctness against a known signal. -- [x] Core: **Preserve engine implementation (fork S16-F2, flagged).** Two viable routes, both - RT-disciplined (pre-allocated, no locks, no `process` allocation): - - **(a) `WDL_SimplePitchShifter`** (`vendor/WDL/WDL/simple_pitchshift.h`) — a per-voice - time-domain OLA shifter. **Now the right category** (duration-preserving is the - requirement, not the wrong tool it was under the varispeed-only framing). Viability from - the header (assessed this pass): push/pull block API (`GetBuffer`/`BufferDone`/ - `GetSamples`), `set_shift(2^(semi/12))` for pitch with `set_tempo(1.0)` for held duration - — pitch and duration are **separately controllable**, exactly Preserve. Per-instance memory - is modest (an OLA ring `bsize = window_ms·srate` ≈ a few KB/voice at the ~50 ms quality-0 - window, plus a bounded output queue). CPU is cheap (O(length), a few mults + one OLA - crossfade per frame — REAPER's "SimpleWindowed" mode, known-basic but usable), so N - polyphonic voices each running one is **feasible within RT discipline**. **Costs, stated:** - (i) **latency** — inherent ~half-window onset delay (~25 ms at the 50 ms window) plus - fill-up, so Preserve notes have a real onset lag; mitigated by pre-warming the shifter at - voice-allocation, and it lands mostly on sustained/loop material (Varispeed serves the - tight-transient one-shots); (ii) **queue allocation** — `BufferDone` grows `m_queue` via - `WDL_Queue::Add`, an RT hazard *only* until steady state; pre-warm with silence at voice- - allocation so the buffers settle and stop growing; (iii) **quality** — basic OLA, audible - warble on large transpositions and no formant preservation (`set_formant_shift` is an - empty stub), acceptable for the loop/phrase use case. **Implemented as hand-rolled pure - OLA (`pitch_shift` module, house pattern — CTest-testable, no WDL/REAPER/VST3 type at the - boundary); WDL_SimplePitchShifter excluded by include-chain (windows.h), held as swap.** - - **(b) hand-rolled OLA/granular pitch core** as a **pure module** (`pitch_shift`, mirroring - the house pattern — CTest-testable, no REAPER/VST3/WDL type at the boundary). More work, - but full control over latency/window/crossfade, RT-shape owned by us, and it sits natively - alongside `peaks`/`wav_trim`. **Lean: start with (a)** to prove the Preserve mode end-to- - end at low cost, and hold (b) as the quality/latency upgrade if the SimpleWindowed warble - or onset lag proves musically unacceptable — the mode's *contract* is identical either way, - so the engine swap is behind the `PitchEngine::Preserve` seam. **`WDL_Resampler` does not - apply here** — it is a *resampler* (couples duration), a Varispeed-quality option, not a - Preserve engine. **elastique is NOT available** (licensed zplane, not in the vendored tree - — restated, not worked around); JUCE / rubberband / signalsmith are **new-dependency forks - carrying full D-A weight** (bare-VST3-no-framework is locked D-A) — not proposed. -- [x] Core: a per-voice **AD pitch envelope**, engine-aware — `PitchEnvParams { enabled=false, - int64 attackFrames, int64 decayFrames, double peakSemitones }`. **Shape (lean, build-time - residual):** two-segment AD — at note-on the pitch offset rises to `peakSemitones` over - `attackFrames`, then falls to 0 over `decayFrames` (**zero attack** = the pure "start high, - drop to base" percussive drop). Off by default (`enabled=false` → offset always 0). **Applied - per engine:** under **Varispeed** the offset multiplies `ratio_` by - `2^(pitchEnvSemitones(frame)/12)` (the read-rate bias, as before); under **Preserve** the - offset is **added to the shifter's shift amount** — `set_shift(2^((note−root + - pitchEnvSemitones(frame))/12))` — so the pitch bends without touching duration. Pure, unit- - tested (t=0 offset, t=attack peak, t=attack+decay → 0; and the semitone→shift/ratio mapping - for both engines). -- [x] Parameter ownership + editor: pitch-engine mode + pitch envelope are per-zone - instrument performance-map state (D-B), additive/version-bumped (absent → engine default per - S16-F1, envelope disabled). Editor exposure: a **per-zone Varispeed/Preserve toggle** in the - S10 guided setup / S10-Z Zones panel (a two-state control next to the S15 mode toggle), plus - a small AD + ±semitone depth control for the envelope (folds into the S12 ADSR-editor tier). - Default-off envelope so the control is discoverable but inert until enabled. The instrument - stays a **read-only bank consumer** (mode/envelope are performance map, never written to the - bank). **Editor control surface deferred to S12 tier (spec-sanctioned).** - -> **S16-F1 (FLAGGED — Daniel fork): the default pitch engine.** **Lean: Preserve default.** -> Argued honestly both ways: -> - **For Preserve default** (the lean): Daniel asked for duration-preserving *unprompted*, -> which reads as the behavior he expects; and the capture workflow is **loop/phrase-heavy** -> (banks are captured slices of a project — tempo-locked material that benefits from -> duration preservation when transposed). For that material, Varispeed's tempo-drift on -> transpose is the surprising/wrong-feeling result. -> - **For Varispeed default** (the honest counter): **Varispeed is the classic-sampler -> expectation** (RS5K, hardware samplers, the whole tradition default to it); it is **cheaper -> and zero-latency** (no shifter, no onset lag); and it is bit-identical to the current -> shipped S3/S5 behavior, so a Preserve default is a *behavior change* for any existing feel. -> Percussive one-shot material specifically *wants* the varispeed character. -> - **Recommendation:** default **Preserve** because Daniel asked for it and the material skews -> loops, but make the per-zone toggle **prominent and cheap to flip** so drum/one-shot zones -> trivially opt into Varispeed. **Daniel's call.** - -> **S16-F2 (FLAGGED): the Preserve engine implementation.** `WDL_SimplePitchShifter` (route a, -> low-cost proof) vs a hand-rolled pure `pitch_shift` OLA/granular module (route b, more work, -> full control, house-native + CTest-testable). **Lean: (a) first, (b) as the held quality/ -> latency upgrade** — same `PitchEngine::Preserve` contract behind the seam either way. Not -> load-bearing for the *feature* decision (S16-F1); a build-time route choice flagged because -> it sets whether a new vendored-WDL usage or a new pure module enters the tree. - -> **WDL pitch capabilities — verified finding (feeds S16 build, not a committed point).** -> The full WDL pitch/resample surface was swept (`vendor/WDL/WDL/resample.h`, -> `simple_pitchshift.h` — the only two pitch/resample headers; no elastique, no -> formant-preserving/time-stretch anywhere in the vendored tree). Findings, honest: -> - **`WDL_Resampler`** (`resample.h`) — a real **sinc/linear resampler** (`SetMode(interp, -> filtercnt, sinc, sinc_size, sinc_interpsize)`; sinc up to 64-tap). It is **RT-suitable** -> (streaming `ResamplePrepare`/`ResampleOut`, prealloc-able, no per-block alloc if -> pre-sized) and its **sinc mode beats the core's current 2-point linear interp** for -> repitch quality (fewer aliasing artifacts on large transpositions) at a real CPU cost -> (64-tap conv per output sample vs. one lerp). **Fit:** an *optional quality upgrade for -> the **Varispeed** base repitch path* — a per-voice quality toggle (linear = cheap default, -> sinc = quality) — **not** required for S16 and **not** committed here. A resampler couples -> duration, so it is **not** a Preserve engine. Held as a Tier-2/3 Varispeed-quality option. -> - **`WDL_SimplePitchShifter`** (`simple_pitchshift.h`) — a **time-domain overlap-add, -> duration-preserving pitch shifter** (push/pull block API; `set_shift` for pitch and -> `set_tempo` as an independent duration knob; quality parameter selecting window/overlap -> sizes). **Under Daniel's duration-preserving directive this is the right category** — the -> candidate Preserve engine (fork S16-F2, route a). **Viability (from the header):** per-voice -> instantiable at modest memory (an OLA ring ≈ window·srate, a few KB/voice at the ~50 ms -> quality-0 window, plus a bounded output queue); CPU is cheap (O(length), a few mults + one -> OLA crossfade per frame — no FFT); N polyphonic voices each running one is **feasible in -> RT discipline** with **two caveats:** (i) **inherent latency** ~half-window (~25 ms @ 50 ms -> window) + fill-up → a real note-onset lag (pre-warm at voice-allocation; it lands on -> sustained/loop material where it is least harmful); (ii) `BufferDone` grows `m_queue` via -> `WDL_Queue::Add` — an allocation hazard **only until steady state**, pre-warmed away with a -> silence pass at voice-allocation. **Quality is basic** (SimpleWindowed warble on large -> transpositions) and **`set_formant_shift` is an empty stub** (no formant preservation) — -> acceptable for the loop/phrase Preserve use, replaceable by the hand-rolled route (b) if not. -> - **Formant-preserving / high-quality time-stretch (elastique-class): NOT in WDL, confirmed.** -> REAPER's elastique is **licensed (zplane), not part of the open WDL/reaper-sdk vendored -> tree** — grep of `vendor/WDL` for elastique/formant/time-stretch found only unrelated -> libpng/giflib string matches. Formant-correct / studio-grade duration-preserving repitch is -> **unavailable to the instrument** without a new third-party dependency (JUCE / rubberband / -> signalsmith would each be a **new-dependency fork carrying D-A weight** — bare-VST3-no- -> framework is the locked D-A choice — and are **not proposed**). **Stated, not worked around.** -> - **Recommendation:** the **Preserve** engine (S16-F2) is either `WDL_SimplePitchShifter` -> (route a, low-cost proof) or a hand-rolled pure `pitch_shift` module (route b, held quality -> upgrade). The **pitch-envelope** modulation stays hand-rolled over whichever engine (a per- -> frame `ratio_` multiply under Varispeed, a per-frame shift-amount add under Preserve). -> `WDL_Resampler` (sinc) remains a held **Varispeed-quality** upgrade only. +> S18 has landed; archived in `COMPLETED.md`. > **S14 moved to Phase L (2026-07-26).** The dock-panel refresh that stood here is now > **Phase L point L2** on `dev` — and, per Daniel's DS-3 call, expanded from a light re-skin @@ -952,251 +154,6 @@ is **ReaSampler 9000**. Framing + propagation surfaces: state. If REAPER does key partly on filename, fall back to keeping the current filename (display-strings-only) and record that as the shipped choice. -## S17 — drop-and-load: drag a capture onto a track's FX button → instantiate ReaSampler 9000 with the capture loaded -**Goal:** Turn a bank capture into a playable instrument in one gesture. Today a drag -out of the `bank_panel` becomes an OS file drag once it leaves the panel (M11 — -`drag_out` + `drag_out_win`, CF_HDROP). This wave adds a **second, internal drag mode**: -while a capture is dragged, a track's TCP **FX button** lights as a drop zone, and -dropping there instantiates a **ReaSampler 9000** (the Phase S VST3 sampler) on that -track with the dragged capture **already loaded and selected** for playback. The -extension drives the whole gesture itself — REAPER's FX button is not a native -plugin-with-file drop target, so this cannot ride the CF_HDROP path. CONTEXT.md §Phase S -(drop-and-load — internal-drag hover mode + the FX-button drop → add-VST + load-capture -seam). Product framing: `docs/product/midi-playback.md` (drop-and-load — the third -integration gesture). -**Consistent with the load-bearing principle (make the reasoning explicit):** this is an -**explicit, user-driven placement gesture** — the user is deliberately choosing to place -a playing instrument on a track, exactly as inserting an item into the arrange is a -deliberate placement act. It does **not** auto-capture (the file already exists in the -bank) and does **not** insert a media item into the timeline; it instantiates a *reader* -of the bank on a track and points it at one already-captured sample. Capture, placement, -and playback stay distinct acts; drop-and-load is a placement-of-the-player gesture, not -a capture and not a timeline insert. -**Two-part mechanism:** -- **(a) Internal-drag hover mode.** A drag armed with a *single* capture that stays - *inside* REAPER's own UI (does not cross to Explorer / another app) is tracked by the - extension: it detects the pointer hovering a track's TCP FX button, highlights it as a - drop target, and on release drives the insert. This is a *third* `DragGesture` beyond - the existing `Internal` (bank-to-bank) and `OsDrag` (M11) — call it `InstrumentDrop`. -- **(b) FX-button drop → add-VST + load-capture.** On drop, the extension adds a - ReaSampler 9000 instance to the target track via `TrackFX_AddByName` (verified present - in `reaper_plugin_functions.h`; signature - `int TrackFX_AddByName(MediaTrack*, const char* fxname, bool recFX, int instantiate)` — - use `"VST3:ReaSampler 9000"` and a negative `instantiate` to always create a new - instance), then pushes the dragged capture's identity into that instance so it plays - that sample — via the **load-capture seam** (below). -**The ReaSampler 9000 load-capture seam (the hard Phase S coupling — MUST be added):** -The current Phase S spec gives the instrument a *live-state read* seam (it reads the bank -index + mapping from `"reasampler"` ext-state via the bridge) but **no entry point for an -external actor to say "instantiate playing *this specific* capture."** This wave is the -reason to add that seam. It is a Phase S dependency, not extension-side, and must land in -the instrument before drop-and-load's drop half can work end-to-end. **Mechanism (SETTLED -— (B) VST3 component-state injection):** after `TrackFX_AddByName`, the extension writes the -new instance's component state directly via `TrackFX_SetNamedConfigParm(track, fx, -"vst_chunk", )` — **verified present** in `reaper_plugin_functions.h` (`bool -TrackFX_SetNamedConfigParm(MediaTrack*, int fx, const char* parmname, const char* value)`; -the header documents the `vst_chunk`/`vst_chunk_program` parms as the base64-encoded -VST-specific chunk write-path). Deterministic, no shared-state race, no cross-process -handshake. **Load-bearing caveat:** `vst_chunk` is the plugin's **own** base64-encoded -serialized chunk (its `getChunk`/`setChunk` FXP/FXB-style blob), **not** a raw VST3 -`IComponent::setState` stream REAPER re-marshals — so the extension must construct exactly -ReaSampler 9000's own state-blob bytes with the target capture pre-selected. That makes the -**component-state blob format a shared cross-artifact contract** — still being defined in -Phase S — and a coordination dependency between the extension and the instrument: both must -agree on the exact byte layout the instrument's `setChunk` accepts. Rejected alternative — -**(A) fresh-instance ext-state handshake** (extension writes a "pending load" hint into -`"reasampler"` ext-state, the fresh instance claims + clears it on init): loosely coupled -through the existing bridge, but loses on the claim/clear race — "which instance claims -which hint" needs a stable key and a cross-process handshake to get right. See CONTEXT.md -§Phase S (drop-and-load) for the full seam decision. -**Coexistence with the M11 OS drag-out (disambiguation, load-bearing):** the two drag -modes are disambiguated by **where the pointer goes**, not by a mode toggle. Inside the -panel client rect → `Internal` (unchanged). Left the panel but still over REAPER's own -window/UI → `InstrumentDrop` (new — hover-tracks the FX button). Left REAPER entirely -(Explorer / another app) → `OsDrag` (unchanged M11). The M11 `decideGesture` boundary -(pointer left the client rect) is **refined**, not replaced: leaving the client rect no -longer immediately means OS-bound; it means "resolve which of InstrumentDrop / OsDrag by -whether the pointer is over REAPER's UI." Single-capture vs. multi-capture also -disambiguates — see open questions. -**Verify (in DAW):** dragging a single capture from the dock over a track's FX button -highlights it; dropping instantiates ReaSampler 9000 on that track with the dragged -capture loaded, selected, and MIDI-playable immediately (no manual pick step); the OS -drag-out to Explorer / another DAW still works unchanged; the internal bank-to-bank drag -still works unchanged; no media item is ever inserted into the arrange; the instrument -holds no private copy (it reads the one authoritative bank). -**Depends on:** M11 (`drag_out` gesture machinery — the mode it extends); **Phase S S4** -(a loadable, playing ReaSampler 9000 instance must exist) **AND the new load-capture seam -added inside ReaSampler 9000 via (B) component-state injection — the shared component-state -blob contract must be defined so the extension can construct it and the instrument's -`setChunk` accept it**. Composes with — but is distinct from — **S8** (ingest -through the bank: capture/import/drop *into* the bank) and **S13** (drop-to-load *inside* -the editor). S17 is the third integration gesture: drop *onto a track's FX button* to -instantiate a player. Gated on the rest of Phase S; the instrument seam is a Phase S -artifact, not extension-only. - -- [x] Extend the `drag_out` pure module with the third gesture: `decideGesture` (or a - successor) returns `InstrumentDrop` when a drag armed with a single capture is over - REAPER's UI outside the panel client rect, `OsDrag` only when it has left REAPER - entirely, `Internal`/`OsDrag`/`None` otherwise unchanged. Pure over (drag state + - pointer + panel rect + an "over-own-UI" predicate the shell supplies). Unit-tested — - the existing `drag_out` invariants (M11) must not regress. **Landed:** `DragGesture:: - InstrumentDrop` + two defaulted `DragState` fields (`singleCapture`, `overReaperUi`, the - shell-supplied predicate). Defaults false, so an M11 caller filling only - `{dragging, hasArmedSamples}` gets byte-identical M11 behavior — the existing tests are - the non-regression proof. **OPEN QUESTION RESOLVED (multi-capture over FX button): - REJECT** — only `singleCapture` arms InstrumentDrop; a multi payload over REAPER's UI - falls through to `OsDrag` (the natural multi-file drag-out), matching the spec's Tier-0 - reject-or-first lean toward reject. -- [x] Shell (extension): hover-track the pointer over REAPER's UI during the drag, - resolve the hovered track + its FX button (verify the TCP/FX-button hit surface against - the SDK — see must-verify), highlight it as a drop target, and on release drive the - drop. Extends the `bank_panel` drag hook alongside the M11 `drag_out_win` path. - **Landed:** `instrument_drop_win::resolveFxDropTarget` wraps `GetThingFromPoint` - (verified present; its info string reports `"fx_chain"`/`"fx_N"` for the FX region and a - null-track-empty-info for off-REAPER). **OPEN QUESTION RESOLVED (FX hotspot vs. whole - TCP): FX HOTSPOT** — the drop target is the FX region specifically, decided from the SDK's - own hit-test string (info prefix `"fx_"`), not a home-grown geometry guess. The - bank_panel drag hook now hover-tracks outside the client rect (holding internal-drag - capture, NOT the modal OS loop) and only hands to `drag_out_win` (OsDrag) when the pointer - has left REAPER entirely. -- [x] Shell (extension): on drop, `TrackFX_AddByName(track, "VST3:ReaSampler 9000", - false, /*instantiate*/ negative)` to always add a fresh instance; capture the returned - FX index; then invoke the load-capture seam to point the new instance at the dragged - capture. Batched into one REAPER undo point (`Undo_BeginBlock2`/`EndBlock2`) so the - whole gesture is one Ctrl-Z (mirrors the bank-verb undo discipline). **Landed:** - `instrument_drop_win::performInstrumentDrop` — `TrackFX_AddByName` with the CHANNEL-correct - name (`"VST3:" + app_version::vstPluginName()`, so a beta extension drops the beta VST), - negative instantiate, then `TrackFX_SetNamedConfigParm(..., "vst_chunk", blob)`, all in one - `Undo_BeginBlock2`/`EndBlock2` block. NEVER inserts a timeline item. -- [x] **ReaSampler 9000 (Phase S artifact):** add the **load-capture seam** — the entry - point that lets the just-added instance be told which capture to play via **(B) - component-state injection**: the instrument's `getChunk`/`setChunk` must round-trip a - component-state blob whose byte layout is the **shared cross-artifact contract** (defined - in Phase S) that the extension constructs with the target capture pre-selected and writes - via `TrackFX_SetNamedConfigParm(..., "vst_chunk", ...)`. This is the cross-artifact half; - it lands in the instrument, not the extension. **Coordination dependency:** the blob - format must be agreed between extension and instrument before either half is final. - **Landed (no NEW instrument code needed — the seam already exists):** the instrument's - `setState`/`getState` already round-trip the full `ComponentState` via - `sample_map::serializeComponentState`/`deserializeComponentState` (S10). The extension side - REUSES that exact serializer through the new pure `instrument_drop` module - (`buildInstrumentDropChunk` -> `serializeComponentState` -> base64) — the shared-writer - requirement is met STRUCTURALLY (one serializer, called from both artifacts), so the blob - format cannot drift. Pure round-trip test decodes back through the instrument's OWN reader - (`deserializeComponentState`) and asserts the capture is selected. **DAW-VERIFY (the one - live unknown):** whether REAPER's `vst_chunk` write-parm expects the plugin's raw - IComponent-state bytes as we write them, or wraps them in a REAPER container header — the - load-bearing caveat is only confirmable in the DAW; if REAPER wraps, the fix is to match - its container, the shared serializer stays. -- [x] Tests: gesture disambiguation (inside-panel / over-REAPER-UI / left-REAPER) across - single- and multi-capture payloads; FX-button hit resolution (pure geometry where it - can be factored out); M11 OS drag-out and internal bank-to-bank drag both unchanged. - **Landed:** `test_drag_out.cpp` adds the InstrumentDrop cases (single over REAPER UI -> - InstrumentDrop; single inside -> Internal; single off-REAPER -> OsDrag; multi over UI -> - OsDrag; not-dragging short-circuits) with the M11 cases retained as the non-regression - guard; `test_instrument_drop.cpp` is the blob round-trip + base64 codec coverage. FX hit - resolution is REAPER-API-bound (`GetThingFromPoint`), so it is DAW-verified in the shell, - not pure-tested — noted honestly. - -## S18 — VST3 channel isolation: a beta ReaSampler 9000 that pairs with the beta extension only -**Goal:** Extend Phase V's beta/stable channel split (V4 — the *extension* is fully -isolated per channel) to the **ReaSampler 9000 VST3 instrument**, so a beta-built VST is a -distinct plugin that pairs only with the beta extension, and a stable VST pairs only with -stable — installable side-by-side in one REAPER with no collision. **What already works -(established from the tree, not re-derived): data pairing is done.** `ext_keys.h`'s -namespace is channel-derived (`kProjExtNamespace()` → `app_version::extStateNamespace()`), -so a beta-compiled VST already *reads* `"reasampler_beta"`; every wire key (`banks`, -`assign_request`, S9's future generation key, any future key) is a plain constant *under* -that namespace, so channel data-isolation is **structural, not per-key** — new keys inherit -it automatically. **What is missing is the VST's *plugin identity*:** its class UID, binary -filename, and display strings are single-valued today (same for both channels → a -UID/filename collision if both are installed). This wave closes that. Mirrors V4's -philosophy: **one channel per binary; all identity derives from the ONE -`REASAMPLER_CHANNEL_IS_BETA` bit via `app_version`, no scattered `#ifdef`s.** CONTEXT.md -§Phase S (VST3 channel identity — the UID-pair invariant + the pairing surface). Product -framing: `docs/product/midi-playback.md` §Addendum — VST channel isolation. -**Consistent with V4 (make the invariant explicit):** V4 already committed the extension to -*two* forever-stable command-id families and *two* forever-stable ext-state namespaces. This -wave commits the *instrument* to the parallel permanent cost: **two forever-stable VST3 class -UIDs** — the existing stable UID (S-NAME-1, locked) and a second beta UID (minted once, -locked forever the same way). Both are frozen forever; the channel bit selects which is -*compiled into this binary*. **One class per binary, not both in one binary** — this mirrors -V4's fully-isolated-binary philosophy (a channel build carries only its own identity), keeps -the factory registration a single `DEF_CLASS2`, and means a beta-installed VST cannot present -the stable identity. -**Verify (in DAW):** the stable VST3 (`reasampler_9000.vst3`, existing UID) and a beta VST3 -(`reasampler_9000_beta.vst3`, the new UID) install side-by-side in one REAPER and both appear -in the FX browser as distinct plugins ("ReaSampler 9000" and "ReaSampler 9000 beta"); a beta -instance reads only the beta extension's banks (its browser shows the beta banks, never -stable's) and a stable instance only stable's; a project saved with a **beta** instance -reopens rebinding to the beta VST (not the stable one) and restores its state; a project -saved with a **stable** instance opened where only the beta extension has banks shows a clean -empty "pick a capture" state (S10 policy), **not** an error; the S-NAME-1 save-rename-reopen -compat test extends to the beta UID (a beta instance rebinds by its own UID). **Nothing plays -differently** — this is an identity/pairing wave, no engine change. -**Depends on:** V4 (the `app_version` channel-identity single-source this extends), S1 (the -VST3 factory + `reasampler_vst.h` identity constants + the CMake second target it edits). -Consumes the S4 live-state seam only to *demonstrate* pairing; adds no new seam. **Disjoint -from the in-flight waves:** touches `vst_entry.cpp`, `reasampler_vst.h`, and the CMake VST3 -block — S9 (ext_keys additions) and S15/S16 (processor/editor) are elsewhere. **ext_keys -coordination note:** S9's new generation key is a plain constant under the channel-derived -namespace, so it inherits this isolation with no S18 change; no coordination edit is needed — -only the shared awareness that all wire keys must live under `kProjExtNamespace()` (already -the rule). Dispatchable in parallel with, or immediately after, the in-flight waves. - -- [x] **Beta VST3 class UID (the permanent commitment).** Mint a second FOREVER-STABLE - class UID in `reasampler_vst.h` alongside the existing `kReaSamplerProcessorUID` - (`REASAMPLER_PROC_UID_1..4`) — a distinct forever-frozen constant (e.g. - `REASAMPLER_PROC_UID_BETA_1..4` + `kReaSamplerProcessorUIDBeta`). The channel bit selects - which UID the factory registers (`DEF_CLASS2`'s `INLINE_UID` + the runtime `FUID`) — - compile-time, one class per binary. **Both UIDs are frozen forever once shipped** — the - same lock the stable UID carries (a saved project records the UID and rebinds by it; a - changed UID orphans every saved beta instance). Record the invariant in the header's - UID-lock comment. **Fork S18-F1 (flagged — Daniel's call):** whether the beta UID is - minted *now* (locked from this wave) or deferred to *first beta release* of the VST - (leaving a compile-time placeholder that must be replaced-once-and-locked before any beta - VST ships). Lean: **mint now** — mirrors how the stable UID was minted at the S1 spike - (locked long before ship), removes a "remember to mint before shipping" landmine, and the - cost of an unused-until-beta constant is zero. Flagged because it is a forever commitment. -- [x] **Channel-derived binary + display identity (no scattered `#ifdef`s — the V4 - invariant).** Route all VST identity through `app_version` accessors, mirroring how the - extension's `OUTPUT_NAME` already derives from `REASAMPLER_OUTPUT_NAME`. (a) **Binary - name:** the CMake VST3 target's `OUTPUT_NAME` forks by channel — `reasampler_9000` - (stable) / `reasampler_9000_beta` (beta) — driven by the same `REASAMPLER_CHANNEL` config - the extension target reads (add a `REASAMPLER_VST_OUTPUT_NAME` beside - `REASAMPLER_OUTPUT_NAME`, or reuse the one channel bit; **check what the extension does and - mirror it exactly**). (b) **Display name:** the factory `DEF_CLASS2` plug-in display string - is "ReaSampler 9000" / "ReaSampler 9000 beta" — sourced from an `app_version` VST-name - accessor (a new channel-derived accessor beside `binaryName()`/`dockTitle()`, e.g. - `vstPluginName()`), not a literal in `reasampler_vst.h`/`vst_entry.cpp`. (c) **Editor title - band + S6 embed-strip label** are channel-aware from the same accessor. All fan out from the - ONE channel bit — no per-file `#ifdef`. -- [x] **Factory vendor/version strings channel-aware where V4 does the equivalent.** The - `BEGIN_FACTORY` vendor/url/email and the `PClassInfo2` version string - (`REASAMPLER_VST_VERSION`, currently a fixed `"0.1.0.0"`) align with the channel where the - extension's V4 equivalents do — the version display carries the `-beta` render - (`appVersion()` already yields `"0.9.01-beta"` on beta); the vendor strings stay shared - unless V4 qualified them (**check V4's treatment and match it** — V4 kept the lane-name - prefix shared, so shared-where-V4-shares is the default). No new forever-stable string - beyond the UID and the id-family V4 already owns. -- [x] **Pairing-surface invariant recorded (no new code — a documented guarantee).** Write - the complete pairing surface as an invariant in CONTEXT.md: a channel's VST talks to that - channel's extension **only**, because (1) plugin identity (UID + filename + display) is - channel-forked here, and (2) **all** wire keys — `banks`, `assign_request`, S9's - generation key, and any future key — live under the channel-derived `kProjExtNamespace()`, - so the beta VST's bridge reads only `"reasampler_beta"`. The invariant to write: **channel - isolation is structural — no per-key opt-in — so a future wire key that forgets to isolate - is impossible by construction** (it keys under the namespace accessor, not a raw literal). - This is the guard that S9/S8/S17's cross-artifact keys inherit isolation for free. -- [x] **DAW-verify contract (the acceptance gate, no unit test — identity is a shell fact).** - Both channels installed side-by-side: each browser sees only its channel's banks; a - stable-project + beta-VST opens clean-empty (not error); the S-NAME-1 rename/rebind compat - test extended to the beta UID (save a beta instance, confirm it rebinds by the beta UID on - reopen). The pure `app_version` accessors (binary/display name per channel) are CTest-green - in `app_version_tests` (extend the existing V4 channel-string assertions to the new VST - accessors); the UID selection + factory wiring are DAW-verified (no host-free test path). - -## Phase S — held and optional-forever (noted, not specified) - **Tier 2 — "expressive" (HELD).** Velocity layers, round-robin (anti-machine-gun), full ADSR, per-sample tuning/gain trim, sustain loops. The next depth increment once Tier 0–1 proves the instrument belongs — **its points are not drawn up here.** @@ -1220,60 +177,6 @@ the rule). Dispatchable in parallel with, or immediately after, the in-flight wa *cut* (choke) on note-off or on a same-group re-trigger (hi-hat open/closed). Deliberately out of S15 scope (Trigger ignores note-off entirely there); a Tier-3 choke-group direction. -## Phase S — must-verify-before-build (carried from CONTEXT.md §Phase S) -- **Steinberg VST3 SDK surface** — interface members, base-class overrides, - factory-macro spellings, Windows module-export symbol names - (`InitDll`/`ExitDll`/`GetPluginFactory`), and whether VSTGUI is bundled. Several are - §1a experienced-estimates until S1 confirms them against the vendored SDK. -- **VST-host bridge** — ~~opcodes `0xdeadf00d`/`0xdeadf00e`~~ **verified (S1):** VST3 - path is `IReaperHostApplication::getReaperApi` (resolve-by-name) and - `getReaperParent(3)` (host context) via `reaper_vst3_interfaces.h`; the - `0xdeadf00d`/`0xdeadf00e` opcodes are VST2-only and do not apply. -- **`IReaperUIEmbedInterface`** — ~~embed contract + message/lifecycle, against - `reaper_plugin_fx_embed.h` (needed only at S6).~~ **verified (S6):** interface - exposed via `queryInterface` on the controller; inline strip drawn into REAPER's - embed bitmap (LICE idiom, no HWND); `WM_GETMINMAXINFO` size hints confirmed; - embed open/close/resize lifecycle clean. -- **VST3 bus arrangement (S7)** — ~~`setBusArrangements` / `getBusArrangement` and REAPER's - mono/stereo instrument-bus expectations, against the vendored Steinberg SDK + - `reaper_vst3_interfaces.h`. The channel-mode toggle depends on the output bus - re-negotiating cleanly.~~ **verified (S7):** `setBusArrangements` accepts only the mode's - arrangement (kMono/kStereo); `getBusArrangement` (base default) reports the valid mode; - a runtime mode change calls `restartComponent(kIoChanged)` so REAPER re-negotiates; - verified against the vendored Steinberg SDK (`ivstaudioprocessor.h`, - `vstsinglecomponenteffect.cpp` base impl, `ivsteditcontroller.h` kIoChanged). -- **Media Explorer surface (S8)** — confirmed thin against the vendored headers: - `OpenMediaExplorer` (open/select) + `MediaExplorerGetLastPlayedFileInfo` (read the one - last-played/selected file + range) are the whole contract; **no** enumerate-selected and - **no** ME-drop-handler API. Spike: does `MediaExplorerGetLastPlayedFileInfo` return a - usable path+range for a merely-selected (not-yet-played) file? -- **Drop targets (S8)** — REAPER exposes **no** drag-drop registration API (verified); drop - handling is on ReaSampler's own panel HWNDs via SWELL/Win32 (`WM_DROPFILES` / `IDropTarget`). - Drop-onto-VST3-editor relayed as a bank-ingest request is an **unproven cross-artifact - spike**, not a promise. -- **Bank-generation ext-state read (S9)** — confirm 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. -- **WDL pitch/resample surface (S15/S16)** — **verified this pass:** `resample.h` - (`WDL_Resampler`, sinc/linear, RT-suitable — a *resampler*, couples duration → Varispeed - path) and `simple_pitchshift.h` (`WDL_SimplePitchShifter`, time-domain OLA, **duration- - preserving** — the S16 Preserve-engine candidate, fork S16-F2 route a) are the **whole** - pitch/resample surface; **no** elastique / formant-preserving in the vendored WDL tree. - **S16 Preserve engine shipped as hand-rolled pure OLA (`pitch_shift` module); WDL excluded - by include-chain (windows.h), held as swap.** The pitch-envelope modulation is hand-rolled - over the engine. If the held sinc Varispeed-quality upgrade is ever taken, verify - `WDL_Resampler` streaming/prealloc against per-voice RT budget before use. -- **Drop-and-load (S17) — three surfaces.** (1) `TrackFX_AddByName` — **verified present** - in `reaper_plugin_functions.h` (signature confirmed; the `"VST3:"` name prefix and the - negative-`instantiate`-always-adds semantics are documented in the header comment). (2) - **TCP / FX-button hit resolution** — how the extension resolves the pointer-under-cursor - to a track and its FX-button hotspot during a drag: **not yet confirmed against the - SDK/SWELL** — `GetTrackFromPoint` / `GetThingFromPoint` are candidates to verify against - `reaper_plugin_functions.h`; whether the FX button specifically is addressable (vs. the - TCP as a whole) is an open verification. (3) The **ReaSampler 9000 load-capture seam** — - a *new* interface added inside the Phase S instrument; its mechanism is a Phase S design - choice (see CONTEXT.md §Phase S open question), not a pre-existing SDK surface. - --- # Phase L — Look-and-feel (system-wide visual design language)