docs: scope MIDI-playback instrument as Phase S (native VST3, second artifact)

Settle forks D-A..D-D: bare Steinberg VST3 SDK + LICE editor; split seam
with root-note/loop-points on Sample now; Tier 0-1 committed; embedded
TCP/MCP UI scheduled. Phase S added to PLAN.md and CONTEXT.md spec.

PLAN.md

@@ -475,3 +475,208 @@ CONTEXT.md §Prune (Settled forks).
   locked in:** a second forever-stable command-id prefix and a second ext-state
   namespace. **Dev-ops:** the build now produces two named artifacts (stable + beta)
   per platform.
+
+---
+
+# 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`.
+>
+> **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).
+>
+> **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.
+
+## 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.
+
+- [ ] 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**).
+- [ ] `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.
+- [ ] `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.)
+- [ ] Bridge read spike: resolve `GetProjExtState`/`EnumProjExtState` by name over the
+  host callback (`hostcb` opcode `0xdeadf00d`), fetch host project context
+  (`0xdeadf00e`), and read a known `"reasampler"` ext-state value. **Verify opcodes +
+  marshalling against `reaper_plugin.h` / `video_processor.h` /
+  `reaper_plugin_functions.h`.**
+
+## 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).
+
+- [ ] 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).
+- [ ] Populate the fields on capture where derivable (root note) / settable (loop
+  points); leave them cleanly empty otherwise. No existing `Sample` field changes.
+- [ ] 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 — 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).
+
+- [ ] Voice engine: polyphonic voice allocation (note-on/off, bounded voice stealing),
+  per-voice state, mono-and-basic-polyphony sufficient for Tier 0.
+- [ ] Amplitude envelope (ADSR) math — asserted against a known signal.
+- [ ] Repitch/interpolation from root note (chromatic pitch ratio across the
+  keyboard); loop-point-aware sustain for held notes.
+- [ ] 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.
+- [ ] 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.
+
+- [ ] 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.
+- [ ] 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).
+- [ ] Sample selection UI (minimal, in the `IPlugView` LICE editor or a
+  parameters-only default view): choose which bank sample this instance plays.
+- [ ] Tier-0 playback: chromatic-from-root, basic polyphony, amp envelope,
+  velocity→volume — plays in REAPER's routing/record/render path like any VSTi.
+
+## 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.
+
+- [ ] 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).
+- [ ] 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.
+- [ ] Performance-map persistence: the keymap (zones, per-sample assignment) is the
+  instrument's own state — held in the instrument (read/written over the live
+  `"reasampler"` seam per D-B's data-ownership split), 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`.
+
+- [ ] Implement `IReaperUIEmbedInterface` on the VST3; draw a compact keymap/level
+  strip inline in the TCP/MCP using the same LICE surface as the editor.
+- [ ] Embed lifecycle (open/close/resize/hit-test inline) handled cleanly; reflects
+  the live keymap/levels.
+
+## 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.**
+- **Tier 3 — "instrument polish" (optional-forever).** Filters, filter/pitch
+  envelopes, LFOs, per-voice pan, choke groups, a modest FX slot. A direction to leave
+  room for, never a commitment.
+
+## 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` (resolve-by-name) / `0xdeadf00e` (host
+  context) and the exact call marshalling, against `reaper_plugin.h` /
+  `video_processor.h` / `reaper_plugin_functions.h`.
+- **`IReaperUIEmbedInterface`** — embed contract + message/lifecycle, against
+  `reaper_plugin_fx_embed.h` (needed only at S6).