Revert "docs(product): spec S7 drop-and-load — drag capture onto TCP FX button to instantiate ReaSampler 9000 preloaded"

This reverts commit b8e8d47af5.
This commit is contained in:
2026-07-26 23:18:46 -04:00
parent 0f2bad1617
commit 52ac9b5eea
2 changed files with 0 additions and 240 deletions
-107
View File
@@ -248,103 +248,6 @@ build:** the `IReaperUIEmbedInterface` contract + embed message/lifecycle agains
- [ ] Embed lifecycle (open/close/resize/hit-test inline) handled cleanly; reflects
the live keymap/levels.
## S7 — 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. See CONTEXT.md
§Phase S for the two candidate seam mechanisms (fresh-instance ext-state handshake vs.
VST3 `setState` preset injection) and the open question on which is chosen.
**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**. Gated on **Phase S landing on dev** — the instrument and
its seam are on the `phase-s` worktree, not dev; this wave cannot be built on dev until
they merge (same gate posture as L3).
- [ ] 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.
- [ ] 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.
- [ ] 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).
- [ ] **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 (mechanism chosen
per the CONTEXT.md open question). This is the cross-artifact half; it lands in the
instrument, not the extension.
- [ ] 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.
> **Numbering reconciliation (load-bearing for doc-keeper).** On **dev**, Phase S runs
> S1S6; the next free label is **S7**, assigned here. **However**, the `phase-s`
> worktree carries additional, not-yet-merged Phase S points (a stereo point, an
> **ingest-relay** point, and an S10S13 UX overhaul — the "S10S13" the L3 coordination
> contract already references but which are not on dev). Drop-and-load is a **close
> sibling of the worktree's ingest-relay / drop-to-load work** (both are cross-artifact
> "get a capture into an instance" gestures). When `phase-s` merges to dev, **reconcile
> this S7 against the worktree's S7+ numbering** — likely by renumbering this wave and/or
> folding it into the ingest-relay family rather than shipping two overlapping
> drop-into-instrument specs. This label is provisional-on-dev, not a claim that the
> worktree's S7+ do not exist.
## 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
@@ -363,16 +266,6 @@ they merge (same gate posture as L3).
`video_processor.h` / `reaper_plugin_functions.h`.
- **`IReaperUIEmbedInterface`** — embed contract + message/lifecycle, against
`reaper_plugin_fx_embed.h` (needed only at S6).
- **Drop-and-load (S7) — 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.
---