# src/shell/instrument — ReaSampler 9000 VST3 shells

## Scope

The REAPER/VST3-facing shells for the ReaSampler 9000 instrument: the read-only bank
bridge, the processor, the editor, the embed strip, and the VST3 entry point — plus
two small identity/helper headers this directory owns outright
(`reasampler_vst.h`, `editor_internal.h`).

The pure engine/geometry core this shell wraps (`sampler_core`, `pitch_shift`,
`sample_map`, `component_state_io`, `play_params.h`, `editor_geometry`, `sample_bands`,
`sample_chrome`, `keyboard_strip`, `waveform_view`, `capture_browser`, `browser_scroll`,
`param_slider`, `trigger_seam`, `velocity_curve`, `embed_strip`, `knob_deck`,
`deck_groups`, `deck_values`, `bake_hold`, `curve_popup`, `spline_edit`, `master_gain`, `reasampler_uid.h`) lives in `core/instrument/*` and
`core/wire` and is documented there — this directory consumes it but does not own it.

## Invariants

**The build shape (D-A, settled 2026-07-26 — bare Steinberg VST3 SDK + LICE editor).**
Bare Steinberg VST3 SDK, no JUCE, with the editor drawn in the same LICE/SWELL stack
`bank_panel` already uses. `SingleComponentEffect` (the SDK's combined
processor+controller base) plus the SDK's factory macros is the audio-processing
scaffolding. Drawing the editor in a VST3 `IPlugView` that hosts a LICE surface reuses
the `bank_panel` docking muscle, keeps the look house-consistent, and avoids JUCE's
AGPL-or-pay license posture. The `IPlugView`↔LICE bridge (window lifecycle, sizing,
event routing from the host into the draw/hit-test loop) is the same class of work as
docking `bank_panel`, not a new competence.

**Embedded TCP/MCP UI (D-D) — `reasampler_embed`.** A REAPER-hosted VST3 can draw its
own UI inline in the track/mixer control panel via `reaper_plugin_fx_embed.h` (the
plugin implements `IReaperUIEmbedInterface` — the same Cockos surface REAPER's own
embedded FX use). Because this uses the same LICE-class drawing as the main editor
path, it composes naturally with the bare-SDK-plus-LICE build. **Must-verify:** the
`IReaperUIEmbedInterface` contract and embed message/lifecycle against
`vendor/reaper-sdk/sdk/reaper_plugin_fx_embed.h`.

**Channel mode (D-E) — current reality.** An earlier design (D-E, settled
2026-07-26) specified a per-instance mono/stereo toggle negotiating the REAPER
audio bus via `setBusArrangements`/`getBusArrangement`, with mono-source+stereo-mode
→ dual-mono and stereo-source+mono-mode → downmix as the cross-mode policy. **This
was superseded by the GA post-launch DAW-fix pass**: the output bus is now
permanently stereo, `ChannelMode` is decode-only (the dynamic mono↔stereo bus
renegotiation from the earlier design was deleted), and channel mode auto-defaults
from the loaded capture via `ComponentState` v9's `channelModeExplicit` flag + the
pure `channelModeFor` helper. Root `CLAUDE.md` is authoritative for this behavior —
do not reintroduce per-instance bus renegotiation.

**VST3 channel identity — the UID pair + the pairing surface (S18).** A beta-built VST
pairs with the beta extension only, a stable VST with stable only, both installable
side-by-side in one REAPER — one channel per binary; all channel identity derives from
the ONE `REASAMPLER_CHANNEL_IS_BETA` bit via the pure `app_version` module (no
scattered `#ifdef`s in the VST shell, except the one described below).
- **The UID-pair invariant is a permanent commitment.** The VST3 class UID is the
  plugin's identity — a saved REAPER project records it and rebinds a saved instance
  by it. BOTH channel UIDs (`reasampler_uid.h`'s stable + beta pairs) are frozen
  forever once shipped; the channel bit selects which one is compiled into this
  binary (one `DEF_CLASS2`, one class per binary — never both classes in one binary).
  The UID selection is the ONLY channel `#ifdef` in the VST shell, because an
  `INLINE_UID` needs literal brace-init tokens and cannot route through
  `app_version`'s runtime string accessors.
- **Binary + display identity are channel-derived**, sourced from `app_version`'s
  VST-name accessors — never a literal in `reasampler_vst.h`/`vst_entry.cpp`.
- **The complete pairing surface is structural, not per-key.** Plugin identity
  (UID + filename + display) is channel-forked, and all wire keys live under the
  channel-derived ext-state namespace — the two together make pairing complete: no
  per-key or per-seam isolation work is ever needed for a new wire key.
- **Verify** all identity/factory wiring against the vendored Steinberg SDK
  (`DEF_CLASS2` / `INLINE_UID` / `FUID` from `pluginfactory.h` + `funknown.h`).

**The three commit tiers (Θ-W3).** An edit reaches the audio by exactly one of three routes, and
which route a control takes is decided once, by the pure `isLiveDeckParam` / `liveCommitFor` pair
(`core/instrument/ui/deck_groups`) that the editor's `dragCommitsLive` only maps onto — see
`core/instrument/CLAUDE.md`'s "Live parameter delivery" for the rule and its rationale.
1. **Full reload** — `reloadInstrument`: bridge read, WAV re-decode, fresh engine, snapshot swap.
2. **Engine rebuild** — `rebuildVoiceEngine`: same drain-slot swap around the already-decoded
   `SampleData`. Voice count / mode / mono trigger.
3. **Live** — `publishLiveParams` (and `masterGain_`, the original of the shape): a lock-free
   publish the audio thread observes at block boundaries. No rebuild, no snapshot, no disk.

The editor's `commitLive` is the tier-3 peer of `commitAndReload`; why it still writes the
parameter set is recorded at its declaration in `reasampler_editor.h`, and why `liveParams_` is
declared ahead of the instrument slots at that member in `reasampler_processor.h`.

**Non-goals / guardrails.**
- The instrument never captures and never inserts into the arrange. Playback is a
  read-only act over the bank. Any instrument path that places a timeline item, or that
  writes bank state itself, is a bug. **The resample bake is not an exception to that
  and does not widen it:** the instrument RENDERS its own sound and REQUESTS a landing;
  the extension is what captures the file into the bank and writes the index. The
  instrument's whole outbound surface is one prefix-guarded request key plus one action
  id — see `instrument_bake` and `reaper_bridge` below.
- The instrument never ingests. Capture, import, and drop-ingest are *extension*
  acts; the instrument only reads and plays. A drop onto the editor window (if ever
  shipped) is relayed to the extension as an ingest request — the instrument never
  writes the bank itself.
- No cross-platform / multi-format. Windows-only, VST3-only, REAPER-only (D5). Do not
  add an AU/AAX/VST2/CLAP wrapper, a mac/Linux build, or a standalone host target.
- The pure core stays REAPER-free *and* VST3-free — the voice engine / envelope /
  repitch module takes no VST3 or REAPER type at its boundary; the shell
  marshals. Any VST3 or REAPER type leaking into `core/instrument` is a bug.
- Verify Steinberg SDK, bridge, embed, and LICE-view surfaces against the vendored
  headers before use.

## Modules

- `reaper_bridge` — READ-ONLY bank consumer: receives bank snapshots from the extension and exposes them as a read-only view. **Never writes to the extension's bank** — this is a load-bearing invariant; no mutation path exists in this module. It owns TWO prefix-guarded ext-state write entry points, `writeUsageExtState` (`rsusage_`) and `writeBakeExtState` (`rsbake_`), each refusing every other key; neither weakens the read-only-*bank* invariant, because neither payload is bank state and `banks`/`view`/`tail`/`assign` stay structurally unwritable. It also owns the bake crossing — `extensionActionAvailable` / `invokeExtensionAction` (`NamedCommandLookup` + `Main_OnCommandEx` with `getReaperParent(3)`, the instance's OWN project tab, as `proj` — a request, not a DAW-verified guarantee; see the header) and `projectTempoBpm`.
- `reasampler_processor` (`shell/instrument/`: `reasampler_processor.cpp` lifecycle + `process()`, `processor_state.cpp` component-state I/O + UI-thread parameter accessors, `processor_reload.cpp` the off-audio-thread `reloadInstrument`/publish family — Q-W2v, T4-12 split; `process()` and its per-block work stay ONE TU on purpose, no cross-TU call on the per-sample path) — VST3 `SingleComponentEffect` shell: declares event-input bus + **permanently stereo** output (GA fix: dynamic mono↔stereo bus renegotiation deleted; `ChannelMode` is now decode-only), marshals MIDI note-on/off into the VoiceEngine, renders audio; owns off-audio-thread `reloadInstrument` + atomic pointer swap so `process()` does no allocation, no file I/O, no bridge calls. The instance state is `{loaded capture id, one InstrumentParams}`, and `reloadInstrument` resolves + decodes exactly that one capture into the `SampleData` the engine plays. **Self-contained playback (pS):** `ComponentState` v10 adds a `SampleRefs` table — per referenced sample, a project-relative path + decode intrinsics (root, loop, channels, displayName); `reloadInstrument` decodes directly from `SampleRefs`, bank-free (plays with the extension absent). The bank/bridge is a browser source: loading a capture copies its reference in; the reopen-heal timer + poll-to-play apparatus are removed. `retireIdleDrain()` retires fully-idle drain snapshots on the UI-timer cadence. Voice-param edits (`setVoiceCount`/`setVoiceMode`/`setMonoTrigger`) rebuild the engine from the already-decoded `SampleData` via the drain-slot swap — no bank re-read, no WAV re-decode, no audible cut to ringing tails. **FB1:** applies the post-mixer `masterGainLinear` (from `ComponentState` v8) as a per-sample ramp over the summed output — no zipper noise. **GA v9:** `channelModeExplicit_` flag persisted; `channelModeFor()` auto-defaults the mode from the loaded capture's channel count when the flag is not set. **pS:** `ComponentState` bumped v9→v10 (`SampleRefs` table); pre-v10 blobs lift to empty refs and re-save self-contained. **pS-usage:** publishes instance usage (held `SampleRefs` paths) to `rsusage_<instanceGuid>` at the tail of `reloadInstrument` (off audio thread) via `reaper_bridge::writeUsageExtState`; `ComponentState` bumped v10→**v11** (`instanceGuid` field); pre-v11 blobs mint guid on first publish.
- `reasampler_editor` — VST3 `IPlugView` LICE editor shell: hosts a LICE-drawn child window; the Sample face is home and Browse is a modal picker over it. Split on the Sample face's BAND axis, mirroring the pure `sample_bands` allocator: `editor_session` (session/bridge state, caches, commit-and-reload), `editor_controls` (the ONE `faceLayout` band resolve every paint and hit-test path shares, the node-drag bounds, the value labels, and the per-instance controls the parameter set does not carry — the parameter-set binding itself is the pure `core/instrument/ui/deck_values` module this only adapts int ids onto), `editor_models` (the orthogonal half: which stored struct each transient editor selection names — the staged-envelope pack/unpack, the drawn contour, and the three velocity curves), then matching paint and input sets — `editor_paint`/`editor_input` (dispatch + drag router + hover dispatch), `_chrome`, `_waveform`, `_deck` — plus the two band-independent surfaces (`_browse` for the modal picker, `_curve` for the velocity-curve popup) and `editor_platform` (IPlugView/Win32 window plumbing). Shared internals in `editor_internal.h`, no TU of its own. Drop-onto-editor ingest is NOT shipped (deferred).
- `reasampler_embed` — implements `IReaperUIEmbedInterface` so the instrument draws inline in the TCP/MCP without a plugin-owned HWND; delegates layout to `embed_strip`. A read-only readout: the loaded capture across the keyboard span with its root marked, plus the activity level. It takes no mouse input (there is nothing on the strip to select).
- `editor_stroke` — the editor's LICE side of the analytic stroker: builds a coverage mask with the pure `core/ui/stroke_aa` and blends it into the bitmap ONCE, writing straight to the bitmap's bits (the arithmetic matches LICE's own mode-0 combine, so a stroke composites identically to every other kit draw). Every radial and spline stroke on the editor routes through `strokeArcAA` / `strokePolylineAA` / `strokeLineAA`. Holds the draw-thread-only scratch mask and arc point list — reuse, not a hidden dependency: threading a canvas through the eight paint sites would grow those signatures to carry an allocation detail. Deliberately does NOT touch `shell/panel/draw_kit`: the waveform stroke, the docked bank panel and the browse cards are out of this seam's blast radius.
- `instrument_bake` — the instrument's half of the resample chain, on the UI thread: render the dialed sound through the pure `core/instrument/bake` modules at the instance's PERSISTED PREVIEW VELOCITY (the velocity the user has been auditioning at — three velocity curves are live, so it is a property of the sound and not a render detail), stage the WAV OUTSIDE the bank folder, publish one `rsbake_<guid>` request, invoke the extension's landing action SYNCHRONOUSLY, read the outcome back over the same key, then adopt + reset in one act. What that key holds afterwards is classified by `core/wire`'s pure `classifyBakeAnswer`, and each of its five non-answers gets its OWN sentence — a silent no-answer stays a failure, but the user is told whether nothing wrote over the key, a stale generation was answered, the answer came in a wire this build cannot read, the request was cleared, or it was refused. All five name the key, because the extension prints one console line per key it scanned and the key is what correlates the two in a multi-instance session. None of them claims the landing never ran — nothing on this side can observe that. Two stack-RAII guards mirror `FxBypassGuard`'s discipline: the staged file and the request key are both cleared on every exit path, so a failed bake leaves no temp, no bank entry and no parameter reset. `bakeAvailable` is the affordance's paint gate. A cloned `instanceGuid` (two instances sharing one `rsbake_` key) is NOT handled here — the residual is contained by pre-existing tracking machinery instead: `planUsagePublish`'s sticky `unioned` poison plus `tiedUsageExists` (`core/tracking/tracking_authority.cpp`) force a clone's bake to `AddDistinct` rather than silently replacing a sibling's entry.
- `vst_entry` — VST3 entry point: `GetPluginFactory` export, class registration, channel-forked class UIDs.
- `editor_internal.h` — INTERNAL shared helpers for the `reasampler_editor` TU family, included only by the editor's own shell TUs (`editor_session` / `editor_controls` / `editor_paint_*` / `editor_input_*` / `editor_platform`), never a public seam: the `Rect`↔kit adapters, small draw primitives (knob face / title band), label helpers, and the velocity-curve box derivation — the helpers more than one band TU needs. The deck's control ids, group ids and group composition are the pure `deck_groups` module's, not this file's. The piano-strip and root-key draws live in `editor_paint_chrome`, their only consumer, not here.
- `reasampler_vst.h` — shared identity constants for the ReaSampler VST3 instrument (Phase S): the plugin's class UID (the channel-selected `Steinberg::FUID`, built from the FOREVER-FROZEN macros in `core/wire/reasampler_uid.h`), vendor name/URL/email, so the processor, factory, and editor agree. A class UID is FOREVER-STABLE once shipped — minted once, never regenerated. *(Newly authored per this dispatch's brief — no existing root-CLAUDE.md bullet; verified by reading `src/shell/instrument/reasampler_vst.h` directly.)*

## Gotchas

- **The bake click only ARMS; the editor's sync tick runs it.** Calling
  `Main_OnCommandEx` inline from `WM_LBUTTONDOWN` would run the extension's whole landing
  nested inside a mouse handler with `SetCapture` held, while the invoked action re-points
  the very instance whose frame is on the stack. Deferring by one tick is same-thread and
  in-instance — it is NOT a cross-process poller/nonce handshake, and it must not grow into
  one.
- The bake's availability probe runs on the SAME tick that paints the button, so the
  control can never be enabled on one tick and refuse on the next. The bake Hold control's
  applicability (`resolveBakeHoldNeeded`) rides the same tick for the same reason, and
  because answering it costs a bridge read + bank parse whenever no loop override is set —
  do not move either into the paint path.
- `editor_internal.h` is include-only — it has no TU of its own and must never become
  a public seam; only the `reasampler_editor` band-axis TUs include it.
- **The editor window class carries `CS_DBLCLKS`, which REPLACES the second button-down of
  a double-click** with `WM_?BUTTONDBLCLK`. Every surface that counts two downs — Browse's
  load accelerator, the spline surfaces' right-click delete — survives only because both
  DBLCLK handlers fall through to the ordinary down handler. Adding a new double-click
  consumer means preserving that fall-through, not bypassing it.
- The two VST3 class UIDs (`core/wire/reasampler_uid.h`, consumed via
  `reasampler_vst.h`) are FOREVER-FROZEN — never regenerate an already-shipped UID.
- The UID selection `#ifdef` in `reasampler_vst.h` is the one deliberate exception to
  "channel identity derives from `app_version` accessors, no scattered `#ifdef`s" —
  `INLINE_UID` needs literal brace-init tokens, so it can't route through a runtime
  string accessor.