reasampler/docs/product/instrument-control-surface.md

Instrument control surface — Phase Γ (ReaSampler 9000)

The product-design reasoning behind Phase Γ: the deck's two-row reflow, the PITCH/RATE deck, the MASTER bus deck (limiter + meter), a consistent knob interaction law, the staged contour-trace defect, and a re-approach of the loop/crossfade markers.

Status: items A–F below are SETTLED (Daniel, 2026-08-01) from a direct interview; this doc records them, works out the design detail they imply, and states the arithmetic. The five forks this doc opened (Γ-F1…Γ-F5) were all ruled on by Daniel on 2026-08-01; their rulings are folded into the sections they affect and the rulings themselves are recorded in §8. §8 also carries one new fork, Γ-F6, which the Γ-F2 ruling surfaced from the vendored SDK and which Daniel did not have in front of him. The forward-looking VST3 automation parameter system is deliberately NOT in this phase — it has its own doc, docs/product/parameter-automation.md.

Every geometry number below was re-derived from src/core/instrument/ui/knob_deck.cpp's own width formula, not carried over from a prior measurement. The stale geometry block in docs/TODO.md ("The deck layout needs a real rework") is superseded by this doc — see §7.6.

---

0. TL;DR

• The spine is the reflow. The deck's controls are two categories — sound and contour — and the current three-row greedy wrap expresses neither. Row 1 is PITCH/RATE | FILTER | VELOCITY | VOICE (sound). Row 2 is PITCH ENV | FILTER ENV | AMP ENVELOPE (contour). MASTER spans both rows on the far right.
• The arithmetic closes, with room. Minimum/default window goes 980 × 680 → 1190 × 680, inside the settled 1280 × 720 ceiling with 90 px of headroom. The deck band drops 328 → 216 px, returning 112 px to the waveform (246 → 358 px at the floor). That 90 px is the governing budget for every future control addition — one deck cell is 60 px, so the layout has room for exactly one more, once. §1.6.
• The two rows align exactly, not nearly. At the floor width the row block is 1020 px, and at that width row 2's two gutters are equal (72 px each) and FILTER's right edge lands exactly on FILTER ENV's right edge (both at x = 636). That is the aesthetic tie between the rows and it falls out of the arithmetic — §1.3.
• PITCH becomes PITCH/RATE: three knobs (Key Trk | Rate | Pitch) under the existing Varisp|Presrv toggle. Rate 50–200 % exponential, Pitch ±24 st.
• MASTER becomes the post-voice-mixer deck it was always reserved to be: limiter toggle in the caption corner, gain knob upper-left, a full-double-height stereo peak meter down the right, an averted-clip bubble, and a one-cell reserved lower-left slot (Γ-F5).
• The limiter is a lookahead design with DYNAMIC reported latency (Γ-F2): zero when off, the lookahead when on, reported to the host's PDC. That buys a transparent true-peak limiter and costs a restartComponent(kLatencyChanged) on the toggle — which the SDK defines as a host deactivate/reactivate, not a re-tap. §3.1.1 is the whole of that cost and how it is contained.
• The cortex limiter does not clear the bar — §3.5. Read it, take nothing.
• Loop gets an explicit enable on the chrome row (Γ-F4), and the four-mark grammar sits under it. The core finding behind the re-approach: three identical bars draw a point and the two ends of a span in the same ink, and the crossfade is painted where its ingredient lives rather than where the event is heard. §6.

---

1. The reflow — the spine of the phase

Daniel's framing, verbatim intent: the deck controls are two categories — sound controls and contour controls — and the current three-row wrap is organizationally bad.

1.1 The two categories

Row	Category	Groups (left → right)
1	Sound — what the voice is	PITCH/RATE, FILTER, VELOCITY, VOICE
2	Contour — how it moves over time	PITCH ENV, FILTER ENV, AMP ENVELOPE
both	Bus — what happens after the mixer	MASTER (double-height, far right)

Row 1 is non-negotiably one row. Row 2 is the three envelope decks. deck_groups' existing signal-flow order (pitch → filter → amp) survives within each row, so the two rows read down the same axis: row 1's first two groups are the sound stages whose contours are row 2's first two groups.

1.2 The measured layout

deckGroupWidth(g) = max(captionRowWidth, knobRowWidth) + 2·kDeckGroupPadX, with captionRowWidth = captionWidth + Σ(kDeckToggleGap + 2·segWidth) + (radio ? 4 + 12 : 0) and knobRowWidth = |cellIds|·kDeckCellW (+ 4 + 2·segWidth for a rowToggle). Metrics: kDeckCellW 60, kDeckCellH 74, kDeckKnobSize 40, kDeckCellLabelH 16, kDeckCaptionH 20, kDeckToggleH 18, kDeckGroupPadX 6, kDeckGroupPadY 4, kDeckCaptionGap 2, kDeckToggleGap 4, kDeckGroupGap 12, kDeckRowGap 8, kDeckRadioSize 12, kDeckGroupH 104.

Group	Row	Caption run	Knob run	Width	Δ	Control inventory
PITCH/RATE	1	70 + 4 + 2·48 = 170	3 × 60 = 180	192	+42	3 cells Key Trk / Rate / Pitch; caption toggle Varisp|Presrv (48)
FILTER	1	46 + 4 + 2·32 + 4 + 2·44 = 206	7 × 60 = 420	432	−92	7 cells (morph, cutoff, Q, drive, mod amt, vel, key trk); caption toggle Off|On (32); caption toggle 2 Band|Notch (44) — moved from the knob row
VELOCITY	1	54	3 × 60 = 180	192	0	3 curve-popup cells (amp, pitch, filter)
VOICE	1	38 + 4 + 2·40 = 122	60 + 4 + 2·44 = 152	164	0	1 cell (voice count); caption toggle Poly|Mono (40); row toggle Retrig|Legato (44) stays — see note
PITCH ENV	2	58 + 4 + 64 + 4 + 46 + 4 + 12 = 192	4 × 60 = 240	252	0	4 cells (A, H, D, Depth); caption toggle Off|On; caption toggle 2 Staged|Spline; corner radio
FILTER ENV	2	66 + 4 + 46 + 4 + 12 = 132	5 × 60 = 300	312	0	5 slots (Gate: A,H,D,S,R / Trigger: A,H,D + 2 reserves); caption toggle 2; corner radio
AMP ENVELOPE	2	78 + 4 + 88 + 4 + 46 + 4 + 12 = 236	5 × 60 = 300	312	0	5 slots (Gate: A,H,D,S,R / Trigger: Len,A,H,D + 1 reserve); caption toggle Gate|Trig (44); caption toggle 2; corner radio
MASTER	1+2	46 + 4 + 2·32 + 4 + 12 = 130	60 + 8 + 62 = 130	142	+70	1 cell (gain, upper-left); 1 reserved lower-left slot; caption toggle Limiter Off|On (32); corner bubble (12, passive); meter column 62 px, full double height

Row totals.

	Natural content	Gutters at floor	Row width
Row 1	192 + 432 + 192 + 164 = 980	12 + 14 + 14 = 40	1020
Row 2	252 + 312 + 312 = 876	72 + 72 = 144	1020

Window floor.

deck band width = 1020 (row block) + 12 (kDeckGroupGap) + 142 (MASTER) = 1174
kEditorMinWidth = 1174 + 2·kPad(8)                                     = 1190
kEditorMinHeight                                                       =  680  (unchanged)
deck band height = 2·kDeckGroupH(104) + kDeckRowGap(8)                 =  216  (was 328)
waveform band at the floor = 680 − 90 (chrome) − 4 − 4 − 8 − 216       =  358  (was 246)

1190 × 680, against a 1280 × 720 ceiling — 90 px of width headroom, 40 px of height.

Three corrections to the arithmetic in the brief, all small and all in our favour:

1. MASTER at 142, not ~236. A 236-wide MASTER puts the floor at exactly 1280 — the ceiling with zero slack. 142 is what the deck's own content actually needs (§1.4) and it banks 94 px. MASTER may grow to 236 before the ceiling binds; that is the meter's growth room, not a target.
2. The row block is 1020, not 1016. The extra 4 px is deliberate and is what makes the two rows align exactly rather than 2 px apart — §1.3. It is the single cheapest aesthetic purchase in the phase.
3. VOICE keeps its row toggle — confirmed. Moving Retrig|Legato to the caption gives 38 + 4 + 80 + 4 + 88 = 214 → 226 px, wider than 164, because VOICE's caption row is the binding side and its knob row is nearly empty. Leave it.

PITCH/RATE's caption reserve is the one tight constant. The group is 192 only while captionWidth ≤ 80 (above that the caption row captionWidth + 100 overtakes the 180 px knob row). "PITCH/RATE" is 10 characters; against the existing reserves (FILTER ENV, also 10 characters incl. a space, reserves 66) 70 is the specified value and 80 is the hard ceiling. If the text does not fit at 80, the fallback is to narrow the Varisp|Presrv segments 48 → 44, which raises the ceiling to 88 — not to widen the group.

1.3 The justification law, and why the two rows read as one surface

Do not stretch the decks. Groups keep their natural widths; slack becomes inter-deck gutters. The law applies to both rows, not just row 2 — that is what makes the outer edges flush, which is the primary alignment signal:

Both rows are justified space-between within the row block. Slack = row block − Σ(group widths); it is divided equally among the row's (n − 1) gutters, with any integer residue distributed to the leftmost gutters. No gutter is ever narrower than kDeckGroupGap (12). MASTER is right-anchored outside the row block and is not part of either row's justification.

Four things carry the visual consistency, and the first three are exact rather than approximate:

1. Flush outer edges. Both rows begin at the deck band's left inset and end at the row block's right edge. PITCH/RATE and PITCH ENV share a left edge; VOICE and AMP ENVELOPE share a right edge.
2. The filter tie-line. At the floor width the two rows' filter groups end on the same pixel: row 1: 192 + 12 + 432 = 636 · row 2: 252 + 72 + 312 = 636. That is not a coincidence to be preserved by a special rule — it is what row-block width 1020 buys, and at 1020 row 2's two gutters are also exactly equal (72/72) and row 1's smallest gutter is exactly kDeckGroupGap. Three good properties at one width. This is why the floor is 1190 and not 1186.
3. Shared horizontal baselines. Every group is kDeckGroupH with identical interior offsets, so across both rows the caption text, the knob centrelines and the label bands sit on the same four lines. The reflow must not break this — it is free today and becomes load-bearing once two rows are visible at once.
4. MASTER is stitched to both rows, not parked beside them. Its two left-column cells sit at exactly the two rows' knob-row baselines (box-relative y = 26 and y = 138), so the gain knob is in line with FILTER's knobs and the reserved slot is in line with AMP ENVELOPE's. §1.4 shows the arithmetic is exact to the pixel.

Above the floor width, the tie-line drifts. Both rows gain slack; row 1 divides it over 3 gutters and row 2 over 2, so the filter edges separate. That is accepted and deliberate: pinning the tie-line at every width forces row 1's first gutter to grow at ~2× the rate of its other two, which reads as sloppy at large widths. The default size is the minimum size, so the exact case is the case almost every user sees; a stretched window reads as a stretched window rather than as a near-miss.

The aesthetic reading, stated plainly. Row 2 holds the contour of each of row 1's first two stages — pitch and filter. Its third, AMP ENVELOPE, has no sound-row counterpart because its static control is level, and level lives in MASTER. That is exactly why MASTER is the deck that spans both rows: it is the one axis whose static half and whose contour half sit on different rows. The double-height deck is therefore a statement about signal flow, not a container for a leftover knob.

1.4 MASTER — the double-height geometry

The double-height box is 2·kDeckGroupH + kDeckRowGap = 216, and the interior lands on the row baselines exactly:

box y  +0        top
       +4        padY
       +4..+24   caption row  (kDeckCaptionH 20)  ── caption text · limiter toggle · bubble
       +26..+100 left cell A  (kDeckCellH 74)     ── GAIN knob + label   [row 1 baseline]
       +100..+138 interior seam (38 px)
       +138..+212 left cell B (kDeckCellH 74)     ── RESERVED            [row 2 baseline]
       +212..+216 padY
       +26..+212  meter column (186 px)           ── full double height

Row 1's groups place their cells at box-relative +26; row 2's box top is +112 and its cells at +138. MASTER's two slots land on both, and the bottom padding closes at exactly 4 px.

Horizontally the group is 6 + 60 + 8 + 62 + 6 = 142.

Three rules an engineer must not generalise wrongly:

• MASTER's left column uses FIXED cell slots at the two baselines. It does NOT use the horizontal run-division law (knob_deck.h: "the cells present divide the whole reserved run"). Applying that law vertically would stretch the single gain knob over the full 186 px. The reserved lower slot reserves height at a fixed position.
• The reserved slot draws nothing. Blank interior reads as breathing room; a dashed placeholder reads as unfinished. It is reserved in layout only, so adding a control later reflows nothing.
• The meter column is one rect, spanning both baselines. It is not two per-row meters.

1.5 What the reflow costs, and what it returns

	Before	After
Deck rows at the floor width	3 (by greedy wrap)	2 (by construction)
Deck band height	328	216
Waveform band at the floor	246	358
Minimum / default window	980 × 680	1190 × 680
Ceiling headroom	—	90 px wide, 40 px tall

Costs, named. The floor width grows by 210 px — an existing saved instance's window grows on open (the same one-time effect Θ-W6-T1 already shipped at 840 → 980, so the behaviour is precedented, not new). The deck's wrap mechanism stops being the thing that decides row membership at the floor width (§7.3). And the phase spends its ceiling headroom budget — §1.6.

1.6 The 90 px headroom is the budget, and it governs every future control

Read this before proposing any new knob. The floor is 1190 against Daniel's hard 1280 ceiling. That is 90 px of width headroom for the life of this layout, and it is the single constraint every later addition spends from:

Purchase	Cost	Headroom after
One more 60 px deck cell on row 1	60	30
One more caption toggle on a group whose caption row is the binding side	0–48	42–90
Widening MASTER to a two-cell left column	60	30
A second cell and a wider MASTER	120	over ceiling

This is why MASTER's reserved lower-left slot is ONE cell and not two (Γ-F5, ruled by Daniel 2026-08-01). A two-cell reserve would spend 60 of the 90 up front, on a control nobody has named yet, and would effectively freeze row 1 forever: any later row-1 addition would then need the remaining 30 px and would not have it. One cell keeps the spare. If the future master-bus control turns out to be two knobs, widening MASTER then costs the same 60 px it would cost now, and by then the trade is being made against a real control instead of a guess. Reserving capacity you have not designed a use for is not free here — it is the whole budget.

Two corollaries for a reader who wants to add something:

• A caption toggle is the cheap slot; a cell is the expensive one. A group whose caption row is narrower than its knob row absorbs a toggle for nothing (that is exactly what FILTER's Band|Notch move exploits). A cell always costs its 60 px.
• The chrome row is a separate budget. The toolbar row's right-anchored control run is paid for out of the title slot, not out of the window floor — which is why the loop enable (§6.5) costs zero of the 90. That is a genuinely different purse and must not be confused with this one.

---

2. The PITCH/RATE deck

Settled. The PITCH deck becomes PITCH/RATE and carries three knobs plus the existing mode toggle. Left to right: Key Trk | Rate | Pitch. Key Trk is the existing control, unmoved.

2.1 The two new controls

	Rate	Pitch
Range	50 % … 200 %	−24 … +24 semitones
Default	100 %, at true knob centre	0 st, at true knob centre
Taper	exponential — linear in semitones over ±12 (50 % = −12 st, 200 % = +12 st)	log2 / centre-expanded (§4.3)
Display	%, one decimal below 100 %	st, signed, one decimal
Unit category (§4)	semitone	semitone
Commit tier	live-published, note-on-latched (§2.3)	live
Range constant	its own ±12 st	reads kPitchDepthMaxSemis — do not mint a second ±24

Pitch's ±24 is deliberately the same throw the pitch envelope's depth and the velocity→pitch curve already speak (kPitchDepthMaxSemis = kVelocityPitchRangeSemitones = 24.0, deck_values.h:26). That constant is load-bearing in the v12 wire format (component_state_io.h:93-95) and must not change — reusing it is the point; retuning it is forbidden.

2.2 What the existing pitch-engine toggle now governs

The Varisp|Presrv toggle stays in the caption corner and now governs both new knobs:

• Varispeed. Keytrack ratio × rate ratio × pitch-offset ratio all compound into a single read-increment multiply. The rate offset applies to the varispeed pitch — i.e. under Varispeed, Rate is a pitch control that happens to be labelled in %, and the two knobs are two views of one multiply. This composes with the pitch envelope's existing per-frame multiply of ratio_; it adds no new per-sample stage.
• Preserve. Rate is an absolute value driving duration only; keytrack and the pitch offset drive the pitch shifter. This is the mode where Rate is a genuine time-stretch.

Guardrail — do not misread this as reopening a settled invariant. core/instrument/CLAUDE.md says "WDL_Resampler is not a Preserve engine (it is a resampler that couples duration) — never wire it as the duration-preserving path." Under Preserve, Rate is supposed to change duration; a Preserve implementation that resamples the read rate and cancels the resulting pitch shift in the shifter is an explicit duration control, not a covert Preserve path. The invariant forbids using a resampler as the pitch-preserving mechanism, and that prohibition stands.

2.3 Rate is latched at note-on — and the reason matters more than the rule

Settled: Rate is latched at note-on for this phase (not live on sustaining voices). Two consequences the implementation must get right:

It is a latch, not a reload. isLiveDeckParam is currently a binary predicate whose false branch routes an edit to a full reload (bridge read, WAV re-decode, fresh engine) or an engine rebuild. Routing a swept knob down that path is unacceptable. Rate is therefore a third commit class: published into the live block like any live parameter, but read only by snapLive at note-on and never by applyLive on a sounding voice. The mechanism already exists — the invariant "A fresh note SNAPS, a sounding one holds φ" is exactly this split — but the classification does not.

Where this is recorded. core/instrument/CLAUDE.md states that "which controls are live is ONE decision, recorded in ONE place" — isLiveDeckParam / liveCommitFor in ui/deck_groups. Phase Γ widens that one decision from two states to three (Live / NoteOnLatched / Reload) rather than adding a second predicate elsewhere. This is also precisely the seam the automation work needs — see docs/product/parameter-automation.md §3.

Why Rate specifically. Rate is not latched because live rate would sound bad. It is latched because loop points scale with rate and contours scale with rate (settled), and both are note-on folds: resolveLoop runs once per note-on, and a normalized contour is resolved against the note's own span. Making Rate live means re-folding the resolved loop and re-mapping the contour mid-note, on a sounding voice, without a discontinuity. That is a real feature, not a plumbing detail, and it is out of scope here. Recording the reason is what makes the latch principled and tells the automation work exactly what it would have to build to lift it.

Pitch is live because it is not implicated: under Varispeed a live pitch offset is one more factor in a per-frame ratio_ multiply the pitch envelope already performs, and under Preserve it is an addend to a shift amount the pitch envelope already modulates.

2.4 Rate scaling — what "scales with rate" means, concretely

• Loop points scale with rate. The loop is a pair of source-frame facts. Under Varispeed the read increment changes and the loop is traversed proportionally faster — scaling is automatic and the stored frames are untouched. Under Preserve the read advances at rate × the source rate, so the loop's wall-clock period scales by 1/rate while its source-frame span is unchanged. In neither mode are the stored loop frames rewritten; the marks on the waveform do not move when Rate moves.
• Contours scale with rate. A drawn contour is a pure function of normalized sample position (core/instrument/CLAUDE.md: "Normalized is what makes a contour length-independent"), so it follows the read head by construction. The staged envelopes' stage times are wall-clock seconds and do NOT scale with rate — an attack of 30 ms is 30 ms at any rate. That asymmetry is correct and deliberate: a contour is of the sample, a staged envelope is of the performance.

2.5 The Preserve time-stretcher — quality bar, not algorithm

Preserve mode has no pitch-preserving time-stretch DSP today. pitch_shift is a correlation-aligned SOLA pitch shifter; composing it with a resampled read yields a working stretch, and that composition is the interim path Γ-W2-T1 ships so Rate is a complete feature the day it lands. A real stretcher, written from established state-of-the-art literature, follows as its own track.

Do not pick an algorithm in this document. The constraints:

• CPU stance (Daniel, verbatim intent): "we should be efficient but accept the cost of high-quality algorithm choices. It's 2026, most people's computers can handle audio with ease. Just don't be wasteful."
• RT-safe. No allocation, no file I/O, no lock in process(). Any window/FFT/analysis buffer is sized and allocated at voice allocation or at the off-audio-thread reload, on the pitch_shift pre-warm precedent.
• Per-voice state, and it must hold up at the 32-voice polyphony ceiling — the measure-and-report gate is 32 simultaneous Preserve voices at an extreme rate (50 % and 200 %), not one voice at 100 %.
• No new third-party dependency, matching pitch_shift's standing property.
• No dispatch on the per-sample path (phase-wide guardrail): concrete, inlineable types; no IStretcher.
• Onset behaviour is a regression surface. GA2 eliminated Preserve's ~25 ms onset latency by priming the ring with the actual upcoming source. A stretcher that reintroduces an onset delay or a first-frame smear is a regression, not a trade-off.
• Quality bar. No audible metallic/phasey artefacting on sustained tonal material at ±6 st and 75–133 % rate; no smearing of transient material at 50 %/200 % worse than the interim resample+SOLA path; the null case (rate 100 %, no shift) must be bit-identical to the un-stretched read.
• Gate. Measure and report before the algorithm is final: per-voice CPU at 32 voices, added latency (must be zero at the onset), and A/B recordings against the interim path on three material classes (one-shot, tonal sustain, full-mix bounce).

---

3. MASTER — the post-voice-mixer deck

deck_groups.cpp already records the reservation: "MASTER is reserved for post-voice-mixer concerns, which is why the curves sit in their own group immediately left of VOICE rather than there." Phase Γ fulfils that reservation rather than contradicting it.

The signal chain, stated once:

voice mixer → master gain (existing ramped multiply) → LIMITER (bypassable) → output bus
                                                                                  └── METER TAP

The meter is tapped at the audio bus output, post-limiter (settled).

3.1 The limiter

Settled: a single toggle, no configurable controls. Baked ceiling at −0.3 dBTP. Daniel's framing: "this is a safety device with potential for musical abuse, not a whole configurable limiter."

Behaviour:

• Toggle only, in MASTER's caption corner (a two-segment Off|On caption toggle, the same primitive kFilterEnable uses). Persisted in ComponentState.
• Default: off. The migration bar ("a project saved before a change reopens sounding identical") forbids any other default — an absent field must lift to bypassed.
• Transparent at rest. No makeup gain, ever. No upward gain of any kind. When nothing exceeds the ceiling the output is bit-identical to the un-limited path.
• Byte-identical when bypassed. With the limiter off, the per-sample path must be byte-identical to today's bare ramped multiply — the same discipline that makes live == nullptr byte-identical to the pre-live core and the filter's exact skip at modAmount == 0 hold the at-rest path unchanged. This is an acceptance criterion, not an aspiration.
• Ceiling −0.3 dBTP. dBTP is a true-peak target, so the detector must see inter-sample peaks — the standard route is an oversampled peak detector in the sidechain only, never oversampling the signal path. The oversampling factor is the engineer's call under the measure-and-report gate.
• Stereo-linked detection (max of |L|,|R| drives one gain), so the stereo image is not moved by the limiter.
• Gain reduction is published per block for the bubble indicator (§3.3).
• Lookahead, with DYNAMIC reported latency — §3.1.1.

3.1.1 Lookahead and dynamic latency (Γ-F2, ruled by Daniel 2026-08-01)

Settled: the limiter has lookahead, and the plugin reports latency dynamically. Daniel's reasoning, verbatim intent: true-peak detection needs oversampling and a transparent limiter wants lookahead, and he is willing to pay the latency provided it is latent only when the limiter is ON and the latency is reported to the host's PDC system. This overrides the zero-lookahead recommendation this doc previously carried.

The behaviour, stated as the contract:

• Limiter off → getLatencySamples() returns 0.
• Limiter on → getLatencySamples() returns the lookahead in samples.
• The toggle calls IComponentHandler::restartComponent(kLatencyChanged).

None of that exists today. There is no getLatencySamples override anywhere in src/, no kLatencyChanged, and no restartComponent call site — the plugin ships the SDK default of 0. This track is the first latency reporting the instrument has ever done, so there is no existing behaviour to preserve, only a new contract to get right.

What the vendored SDK actually says, and why it is more expensive than it looks

Two facts read directly out of vendor/vst3sdk, both load-bearing:

pluginterfaces/vst/ivstaudioprocessor.h:293-299 — "If during the use of the plug-in this latency change, the plug-in has to inform the host by using IComponentHandler::restartComponent (kLatencyChanged), this could lead to audio playback interruption because the host has to recompute its internal mixer delay compensation. Note that for player live recording this latency should be zero or small."

pluginterfaces/vst/ivsteditcontroller.h:105-108 — "kLatencyChanged: … The host has to deactivate and reactivate the plug-in, then afterwards the host could ask for the current latency."

The second is the sharp one. kLatencyChanged is not a "re-read the number" flag — the SDK defines it as a deactivate/reactivate cycle. And in this plugin, ReaSamplerProcessor::setActive is deliberately destructive in both directions (reasampler_processor.cpp:85-109):

• setActive(false) frees live_, draining_, and the graveyard — every sounding voice dies. The comment there explains why that is correct and must not be softened casually: a surviving live_ would be displaced into the drain slot on reactivate and "resurrect stale sustained voices as ghosts."
• setActive(true) calls reloadInstrument() — a bridge read, a WAV re-decode, and a fresh engine.

So the honest cost of the toggle is: every sounding note stops, and the sample is re-decoded from disk. That is a materially heavier consequence than "a brief click," and it is the reason §8's new fork Γ-F6 exists rather than this being fully closed.

The standing scar, and why this is nonetheless not the forbidden change

reasampler_processor.cpp:66-68 carries a warning in the codebase's own words:

"Do not reintroduce per-mode bus renegotiation: flipping kMono↔kStereo via restartComponent previously panned a dual-mono capture hard right in the host's pin re-routing (see testDualMonoStereoSampleRendersCentered)."

and src/shell/instrument/CLAUDE.md elevates that to an invariant.

A kLatencyChanged restart is a different flag from the kIoChanged-class bus renegotiation that caused that regression, and it is NOT forbidden by that invariant — the output bus stays permanently stereo and its arrangement is never renegotiated. But the precedent stands: mid-session restartComponent in this plugin has already shipped one real regression, in the host's re-routing rather than in our code. That history is the reason the following are acceptance criteria and not suggestions:

1. Verify the whole call sequence against the vendored Steinberg SDK before writing it — IAudioProcessor::getLatencySamples, IComponentHandler::restartComponent, the RestartFlags value, and the SDK's stated ordering (the new latency is what getLatencySamples returns after setActive(true), per ivsteditcontroller.h:106 — so the reported value must be derived from persisted state, not from a transient the deactivate clears).
2. Prove the restart does not disturb the output bus arrangement. After a latency-change restart the bus is still one stereo output with the same arrangement, and a dual-mono capture still renders centered.
3. Ship a regression test in the spirit of testDualMonoStereoSampleRendersCentered — a dual-mono capture rendered across a limiter toggle stays centered, with equal L and R. That test is the guard against the exact failure mode the scar records.
4. Never call restartComponent from process(). It is a main/UI-thread call. The toggle already arrives on the UI thread; the restart is issued there, and coalesced so a user clicking the toggle repeatedly produces one restart per settled state, not one per click.

Flipping the toggle during playback — the product decision

Ruling (mine, not deferred): the toggle applies immediately, the restart is requested immediately, and the resulting interruption is accepted and documented. It is NOT deferred to a transport boundary. Three reasons, in order of weight:

1. A deferred restart is a silent lie. If the limiter's audio engages now but the reported latency lands at the next transport stop, the plugin is misaligned by the lookahead for however long that takes — and a timing error on an instrument is invisible until it is printed. A visible interruption beats an inaudible misalignment.
2. We do not actually control the timing. Per the SDK, the plugin requests; the host schedules the deactivate/reactivate. Deferring our request buys uncertainty, not determinism.
3. The instrument is played live, not only sequenced. Auditioning a patch with the transport stopped is the common editing case; a transport-boundary deferral would mean the restart never lands at all in that case, which is the worst outcome of the three.

The mitigations that make this acceptable rather than merely defensible:

• The limiter's own output has no hard step. Within the plugin, the engage/disengage is covered by a short (≤ 10 ms) equal-gain crossfade between the pre- and post-toggle paths, so whatever the host does around it, we do not emit a discontinuity of our own making.
• The toggle is framed as a patch-design control, not a performance control. It is set once while building a sound. The editor should not encourage flipping it while playing, and nothing in the UI should make it a per-take gesture.
• The limiter enable is explicitly NOT automatable. This is the load-bearing consequence and it must be recorded where the parameter work will read it: an automation lane toggling a latency-changing parameter would request a host deactivate/reactivate on every flip. See docs/product/parameter-automation.md §3.8 — the limiter enable belongs in the not-automatable class, and it is emphatically not the plugin's kIsBypass parameter either.
• The interruption is verified in REAPER, and its severity recorded. The SDK mandates the deactivate/reactivate; what REAPER actually does with it — whether sounding notes cut, whether the re-decode is perceptible, whether transport hiccups — is DAW-verifiable only. That verification is W1-T2's first deliverable, and its outcome is what closes Γ-F6.

3.2 The meter

Vertical, 62 px wide, 186 px tall, down MASTER's right side, spanning both row baselines.

Property	Decision	Why
Bar count	One wide bar when the waveform draws one lane; two skinnier bars when it draws two	The bar count is resolved by the same LaneSplit decision waveformSurface already folds (channel mode ∧ source channel count) — not a second rule. A mono source in stereo mode is dual-mono: L ≡ R, and two identical bars would be a lie. One source, two views.
Bar geometry	22 px label gutter · 4 px gap · 36 px bar field. Mono: one 36 px bar. Stereo: two 17 px bars, 2 px apart.
Scale	Linear in dB, −60 … +6 dBFS. Ticks every 6 dB; numerals at 0, −12, −24, −36, −48, −60; the 0 dB tick drawn heavier.	66 dB over 186 px = 2.8 px/dB; 34 px between numerals at Font::Micro. Honest and simple; an expanded-top scale was considered and rejected as harder to read against a numeric label. Above 0 is shown because it is exactly what the limiter-off case needs to make visible.
Ballistics	Rise: instantaneous (a peak displays on the first UI frame after it occurs). Fall: 20 dB/second.	A peak meter must not smooth its attack or it under-reports. 20 dB/s is close to the IEC 60268-18 PPM fallback (20 dB in 1.7 s) and reads as responsive without flicker.
Peak hold	A 2 px horizontal tick at the running max, in text/primary. Holds 1.5 s after its last update, then falls at the same 20 dB/s.	A neutral bright tick reads cleanly over the bar's accent ink; a second accent would compete.
Clip	A cap at the top of the meter, latched warn when any block peak ≥ 0 dBFS. Click to clear.
Bar ink	accent/primary — it is the live signal.	warn stays reserved for clip states (visual-design-language.md §2.1). No green/yellow/red segmentation.

The clip indicator earns its keep precisely because the meter is post-limiter. With the limiter engaged, a post-limiter clip is essentially impossible; with it bypassed and gain driven up (the knob reaches +24 dB), clipping is easy. So the indicator quietly teaches what the toggle does: drive the gain, see red; engage the limiter, red stops. If the clip cap ever latches while the limiter is on, that is a defect report, not a user error.

RT discipline. The audio thread publishes, per block, as relaxed atomics: per-channel peak max|x|, a latched clip flag, and the block's maximum gain reduction. No dB conversion, no ballistics, no hold timers on the audio thread — the UI timer converts and runs the ballistics from the published block peaks and elapsed time. This matches the existing advisory-peak shape (reasampler_processor.h:109-113) and the standing rule that observation happens at block boundaries, never per frame. The existing advisory peak is not reusable as-is — no dB, no ballistics, no hold, no clip, mono only — but it is the right pattern to widen.

3.3 The gain-reduction bubble

Settled: the limiter shows a red bubble when the threshold is crossed and any gain reduction is applied.

• A round 12 px lamp in the caption row's far corner — the slot the three envelope decks use for their overlay radio. Round, not square, so it reads as a lamp rather than a control; the limiter toggle sits one slot to its left, which is the existing right-to-left caption grammar unchanged.
• Non-interactive. Either the existing captionRadio geometry with hit-test suppressed, or a passive-indicator slot in knob_deck — an implementation call, but the slot is the existing one and no new geometry is invented.
• Ink: warn. Legal under the palette's "warn is reserved for clip states" rule because gain reduction reports an averted clip — the same state class the clip cap reports, one stage earlier.
• Lit whenever the block's maximum gain reduction exceeds a small floor (the intent is "the limiter is working," not "a sample touched the threshold"); it follows the same 20 dB/s-style decay as the meter so a transient catch is visible rather than a single-frame flicker.

3.4 Where the master controls sit in the reset scope

Phase Ξ-W2's resample reset scope is settled by rule ("reset what the bake baked in"). Derived against that rule, surfaced for Ξ-W2's review rather than as a Daniel call: rate → reset, pitch offset → reset, limiter enabled → reset (master gain is already on the reset list, so the bake includes the master stage, so the limiter's effect is in the audio).

3.5 Assessment: the temp_cortex/ limiter reference

Read in full (temp_cortex/limiter_base.{hpp,cpp}, temp_cortex/fast_limiter.{hpp,cpp}, commit 3ad3094). Standing project rule: cortex code is a reference, not a transplant — if there is character in it worth having, it gets rebuilt as an explicit parameter rather than inherited as a side effect.

Verdict: it does not clear that bar. There is no character in it worth having. Read it as a reminder of the shape, take nothing.

What is structurally right: detection on the un-delayed signal with the gain applied to a delayed copy (that is correct lookahead), and stereo-linked max detection. Both are textbook and need no reference.

Everything else is disqualifying:

Finding	Why it disqualifies the code
Unconditional makeup gain — makeupGain = ceilingLinear / thresholdLinear, applied on every sample whether or not anything is limiting (fast_limiter.cpp:121,129). At the defaults that is a permanent +2.9 dB.	Directly contradicts "a safety device": the toggle would change loudness at rest. This is exactly the inherited-side-effect the standing rule exists to catch. Our limiter has no makeup gain at all.
uint8_t lookaheadSamples (fast_limiter.hpp:14, computed at .cpp:12). 5 ms at 96 kHz = 480 → silently wraps to 224.	An embedded-platform assumption (fixed low rate) that does not survive a DAW.
uint8_t peakHoldSamples, with dead guard code — if (peakHoldSamples > 255) (.cpp:50) can never be true; the cast already truncated.	Same class of defect, plus the guard reads as protection that isn't there.
Two powf calls per sample to convert constant dB values to linear (.cpp:94-95).	A transcendental on the per-sample path. The house rule (engine/loop/CLAUDE.md) explicitly forbids one there.
Cascaded double smoothing — envelope is attack/release smoothed, then currentGain is smoothed again with the same coefficients (.cpp:85-91, 112-118).	The realized timing is not the stated timing; the timing constants mean nothing.
A near-instant attack (0.01 ms) behind a 5 ms lookahead (limiter_base.cpp:6).	The lookahead's whole purpose is to let the gain reach its target before the peak arrives. With an instantaneous attack the lookahead only delays audio.
virtual void process(float[2], …) called per frame (limiter_base.hpp:16).	A vtable dispatch on the per-sample path — the phase-wide "no dispatch-stack blowouts anywhere" guardrail.
Sample-peak only, no ISP detection.	Cannot meet the settled −0.3 dBTP ceiling as written.
Startup mute — outputs silence until the delay line fills (.cpp:132-135); raw new[]/delete[]; depends on unvendored CircularBuffer.h and basicmaths.h.	Embedded idiom, not house idiom.

Recommendation: write ours from the literature against §3.1's constraints, and delete temp_cortex/ once the limiter lands (its removal is staff-engineer's, not mine).

---

4. The knob interaction law (item D)

Daniel scoped this as its own work item: a consistent, unit-category-driven interaction and taper rule across every variable control. The load-bearing property is that the rule is derived from the control's unit, so a control added later inherits it without anyone maintaining a list.

4.1 Modifiers

Gesture	Effect
Shift	Snap to whole numbers in the control's displayed unit (§4.2).
Ctrl	Scale the drag by 0.05 (1/20 sensitivity) — fine grain.
Shift + Ctrl	Shift wins; Ctrl is ignored. Not a compromise: when the output is quantized to integers, a finer drag produces the same sequence of values. Stated so nobody "fixes" it later.

Mid-drag modifier changes re-anchor. The knob drag is grab-anchored absolute (param_slider.cpp:138-143, kKnobDragRangePixels = 128), so flipping a modifier mid-drag without re-anchoring makes the value jump by (1 − 0.05) × the accumulated delta.

On every modifier transition — press or release — during an active drag, the drag re-anchors: the control's current value becomes the new anchor value and the cursor's current position becomes the new anchor position. The value is continuous across the transition; only the rate changes. This holds for Shift too: releasing Shift re-anchors from the snapped value, so a snapped knob does not jump back.

Plumbing. wndProc currently discards wParam for WM_MOUSEMOVE. The codebase already reads modifiers via GetKeyState in two other input paths (editor_input_curve.cpp:50, editor_input_waveform.cpp:38) — the precedent exists; the requirement is that all drag surfaces read it through one shared helper so they cannot drift into two modifier grammars.

Scope — and one explicit exclusion. The law is a property of the parameter, not the widget. Every surface that edits a unit-valued parameter honours it: deck knobs (outer ring and inner curve dial), envelope stage nodes, and curve knots. This follows from the standing invariant that node drags, knot drags and knob edits are "surfaces onto ONE model" — a snap available on one and not the others would be a divergence.

Waveform markers (start, loop start, loop end, crossfade) are excluded. They carry an existing zero-crossing snap gesture, and their domain is frames, which has no meaningful "whole number" above the frame. Overloading Shift there would collide with a shipped gesture. Recorded as a deliberate exclusion.

4.2 The snap unit, by category

Unit category	Controls	Shift snaps to
milliseconds	the 14 stage-time knobs (amp/filter Gate A,H,D,R; amp/filter Trigger A,D; pitch env A,D)	whole ms
semitones	pitch env depth, the new Pitch, and Rate	whole semitones — on Rate this means the 25 semitone steps between 50 % and 200 %, which is what makes an octave or a fifth reachable by hand
percent / fraction	sustain level, hold fraction, Trigger length, key-track (both), filter mod amt / vel amt / morph / cutoff / Q / drive	whole percent
exponent	the 12 inner curve dials (0.1 … 10)	whole numbers — which puts 1.0, the linear neutral, one snap away
decibels	master gain	whole dB
already integer	voice count, preview velocity	no change

4.3 The tapers

Both taper changes are SAFE for persistence and require no format bump. The ComponentState payload stores raw engine values as doubles — seconds, semitones, curve exponents (params_payload.cpp:358-408). Normalization exists only in ui/deck_values.cpp as a UI display/interaction layer. Re-tapering moves the needle angle and nothing else; saved projects reload bit-identical and sound identical.

Millisecond knobs become log-scaled. More resolution across 1–100 ms while still reaching the ceiling. A pure log map cannot include zero, and zero is a required value, so the taper is stated as acceptance criteria rather than a formula (the engineer picks the shape):

• Exactly 0 s at norm 0 and exactly kEnvTimeMaxSeconds at norm 1. Monotone and continuous throughout.
• 10 ms lands within 0.12 … 0.20 of travel; 100 ms within 0.42 … 0.52.
• kEnvTimeMaxSeconds is 2.0 s (deck_values.h:22, reading kGateStageMaxSeconds at envelope_overlay.h:85) and does not move in this phase — settled, Γ-F3. The AHDSR overlay's schematic scale is derived from it and the two must agree so a maxed knob lands exactly at the canvas edge; the agreement requirement is documented at deck_values.h:19-22. Daniel foresees wanting a 10 s ceiling for sound-design cases — his example, "a horrifically long decay with tight exp" — and that ambition is carried as a docs/TODO.md entry rather than dropped. Two things make it cheap later and both land in this phase: the log taper is precisely what makes a higher ceiling usable rather than unusable at the low end, and the reset-bypasses-the-taper change below removes the power-of-two dependency that would otherwise block a 10.0 s ceiling outright.

Semitone knobs become log2-scaled. More resolution across −7 … +7 st while still allowing the extremes:

• Symmetric about the centre; exactly 0 at norm 0.5; exactly ±kPitchDepthMaxSemis at the ends; monotone.
• ±7 st reached at 50 % … 58 % of each half-travel (so the musically useful middle gets more than half the knob on each side).
• Rate is the exception and keeps its settled taper: linear in semitones over ±12, i.e. exponential in ratio. It needs no centre expansion — ±12 st over the full travel is already 0.19 st per drag pixel — and Daniel settled it explicitly. The two laws coexist on one deck for a stated reason: centre expansion applies to semitone knobs whose throw exceeds ±12.

One correctness consequence, and it is required, not optional:

resetDeckParam must bypass the taper. It currently round-trips the default through norm → value (deck_values.cpp:200-203), and deck_values.h:42-46 documents that exact recovery depends on the map being linear over a power-of-two ceiling. A log taper makes that round-trip inexact. Reset must write the default value directly — the defaults are already read off a default-constructed PlaySeconds, so there is no second table to drift. This removes the power-of-two dependency rather than working around it; the comment at deck_values.h:42-46 becomes wrong and needs rewriting (source work, staff-engineer's).

This is also the unblocker for a future 10 s ceiling. 2.0 is a power of two; 10.0 is not, so under today's round-trip a 10 s ceiling would land every reset a mantissa bit off its own default. Landing the reset bypass here means the ceiling question later is a one-constant change plus an overlay-scale re-check, not a correctness problem.

4.4 Sequencing — why item D goes first

Item D lands before the two new PITCH/RATE knobs, so Rate and Pitch are authored into the finished law rather than retro-fitted into it. It lands well before any VST3 parameter work, for a much sharper reason: once parameters are exposed, the taper is the host-facing normalization, and re-tapering silently re-interprets every recorded automation point in every saved project. Taper changes are free now and permanently expensive later. See docs/product/parameter-automation.md §4.

---

5. Staged contour traces draw straight, not curved (item E)

Daniel's report. Changing a curve exponent from 1.0 moves the knot on the overlay, but the stage segment still draws as a straight line. Audio is correct; only the drawing is wrong.

Root cause, verified. editor_paint_waveform.cpp:218 does if (v.knot) continue; — knots are dropped from the trace and the remaining vertices are joined with straight strokes (:222). curveMap is never called in the paint path. The exponent is in scope (env.attackCurve / .decayCurve / .releaseCurve at :211) and simply never read. Knot positioning does honour the exponent via curveMidLevel (envelope_overlay.cpp:94-105) — which is the divergence: at any non-neutral exponent the knot visibly floats off its own trace.

The intended visual result (the tessellation approach is the engineer's call):

• Every sloped stage draws as the curve its exponent defines, evaluated through the same curveMap the audio uses — one source, so the trace and the sound cannot diverge.
• At exponent 1.0 the segment is visually identical to today's straight line (the regression guard).
• At every exponent the knot's centre lies on the trace, within 1 px. This is the observable acceptance criterion, because the knot/trace divergence is the reported defect.
• No visible faceting at the widest segment the canvas can produce (per-pixel-column or adaptive sampling; a fixed low tessellation count is not acceptable at full width).
• The trace keeps the established grammar: one weight, kEnvTracePx = 2.0, through the analytic stroker — Θ-W7's "both envelope traces are one grammar and one weight" holds.
• It is one paint path, so one fix covers all of it: amp / filter / pitch, Gate AHDSR and Trigger AHD, attack / decay / release. The drawn-EG (spline) overlay's own grammar is untouched — it already traces per column.
• Both overlay layout policies are honoured unchanged: the AHDSR's right-anchored schematic and the AHD's 1:1 mapping.

---

6. Loop and crossfade — the re-approach (item F)

Daniel: "the loop indicators and crossfade thingy are unintuitive as fuck. I don't understand what the three lines represent, so we need to re-approach that UX."

This is the one genuinely open design problem in the phase. What follows is a recommendation, the alternatives that lost, and the trade-offs.

6.1 Diagnosis — three root causes, one of them not in the complaint

Cause 1 — a category error in the drawing. The three bars are not the same kind of thing. Start is a point in time (where the head enters). Loop start and loop end are the two ends of a span (a region the head cycles inside). They are drawn in identical ink (Role::AccentSecondary for all three, editor_paint_waveform.cpp:35-36), at identical weight, full height, distinguishable only by position. Drawing a point and the ends of a span in one grammar is why the marks cannot be told apart, and it is the deeper answer to "what do the three lines represent."

Cause 2 — nothing is named. There is no label anywhere in the band. Every audio editor labels these marks; we do not. This is the blunt, unglamorous half of the fix and it is probably worth more than everything else combined.

Cause 3 — the crossfade is painted where its ingredient lives, not where the event is heard. Verified: the fade is pre-seam and one-tap — it fades material running into loopEnd toward material running into loopStart, using the read head one loop length earlier (loop_span.h:26-28). The audible event occupies the last crossfade frames before loopEnd. But the UI paints the shaded region before loopStart (editor_paint_waveform.cpp:108-116), and hangs the only grab affordance — a 10 px tab in the top strip with no line of its own — at loopStart − crossfade. The paint follows the handle, not the audible event. Both regions are real things (one is the ingredient, one is the event), but the drawing shows only the ingredient, and the handle is on the wrong side of the loop from the sound it controls.

6.2 Three directions considered

Direction 1 — "Two grammars: a point is a caret, a span is a bracket." Differentiate by category — start gets a distinct ink and a directional flag cap; the loop pair gets bracket caps so it reads as an enclosure; the crossfade moves to the audible location. Cheap, uses only primitives the kit already has, attacks all three causes.

Direction 2 — "Lane it." Add a dedicated 14–16 px marker rail along the top of the waveform band. All handles live in the rail; the waveform proper carries only quiet 1 px guide lines and the span fill. Structurally the strongest option: it would dissolve the overlay's claim-arbitration problem (resolveWaveformClaim) rather than tie-breaking it, and it would collapse two open docs/TODO.md entries. Rejected for this phase — it costs waveform height, needs a new pure geometry module, and re-routes every hit-test in the band, which is a much larger build than Daniel's complaint calls for. Retained as the named fallback if the recommended direction proves too crowded in the DAW. Precedent: REAPER's own ruler/marker lane; Sound Forge and Audacity's selection/loop handles.

Direction 3 — "Show the loop as a loop." An arc/ribbon above the waveform running from loop end back to loop start with an arrowhead, the crossfade drawn as the ribbon's taper. Extremely legible for "what is a loop," and there is good precedent (Ableton Simpler's loop arrow, Kontakt's loop-return arc). Rejected: it is a lot of ornament for one fact the user learns once, and it sits uncomfortably against the visual language's strict decoration policy (visual-design-language.md §3.5).

6.3 Recommended: "Name it, class it, and put the fade where it is heard"

Direction 1, with labels, in four moves. One grammar, four marks.

(a) One mark grammar: line + cap + label. The cap IS the grip.

Every mark draws as a full-height 2 px column, a shaped cap in the overlay's top strip, and a Font::Micro / TextDim label. The cap is both the mark's identity and its grab handle — which instantly answers "what is that tab?", because the crossfade's cap stops being a bare orphan rectangle and becomes the same kind of object as every other mark's.

Mark	Ink	Cap	Line	Label
Start	accent/primary	solid right-pointing triangle (a play flag — it points into the material that will play)	solid	START, right of the line
Loop start	accent/secondary	L-cap opening right	solid	LOOP, right of the line
Loop end	accent/secondary	L-cap opening left	solid	END, left of the line
Crossfade	accent/secondary, reduced alpha	ramp cap — a small right triangle whose hypotenuse rises left→right, drawing the fade-in shape	dashed — a soft boundary, not a hard one	XFADE, left of the line

Start is the only accent/primary mark in the band, because it is the only one that is always in effect (both Gate and Trigger). The loop pair's opposed L-caps read as [ … ] without needing to be explained. All four caps use primitives already in the kit (axis-aligned fills, AA-restroked triangles per visual-design-language.md §8).

(b) Labels, with an accepted overlap.

Labels draw in the top strip beneath the trace and handles in z-order. Where an envelope node overlaps a label, the node wins visually and the label is occluded — accepted, and named here so it is not filed as a defect. Labels are for learning; the cap shape carries the identity permanently. Two rules keep them honest:

• On hover or drag of a mark, that mark's label re-draws on top, so you always see what you grabbed.
• A label is suppressed if its box would overlap one already placed. Placement order is the grabbed/hovered mark first, then START, LOOP, END, XFADE.

A vertical inset of the overlay canvas to make room for labels was considered and rejected: it would change the envelope's level mapping (level 1.0 would no longer reach the canvas top), which moves both the forward and inverse overlay maps and their tests, for a cosmetic gain.

(c) The crossfade moves to where it is heard, and its ingredient becomes a ghost.

• The crossfade mark and its region move to [loopEnd − crossfade, loopEnd). The handle now lives on the loop-end side. Drag direction is unchanged — left lengthens the fade — so the muscle memory survives; only the anchor moves.

• The region draws as a top-and-bottom edge wedge, never as a second fill. A triangular band along the top and bottom edges of the overlay, growing from zero height at loopEnd − crossfade to ~10 px at loopEnd, in accent/secondary. It reads as the fade closing in on the seam and it leaves the middle of the waveform clean.

  This is a hard constraint, not a stylistic preference. The crossfade region is now inside the loop span, where a translucent fill would stack on the loop fill (0.20 + 0.10). The envelope trace crossing the loop fill is a known, accepted under-floor contrast pair at 2.25:1 against a 3:1 floor (editor_paint_waveform.cpp:28-34), whose own note says "If it is ever resolved, the FILL is what changes; do not nudge a color to chase it." A stacked fill would make an already-accepted failure worse. The edge wedge leaves the loop fill's peak alpha at 0.20 exactly as today, so the pair is untouched.

• The ingredient draws as a ghost. [loopStart − crossfade, loopStart) — the material actually being mixed in — draws the mirror wedge (growing right-to-left, peaking at loopStart) at half alpha, outside the loop fill. It carries no handle. At rest it is a hairline dashed outline; it fills in on hover or drag of the crossfade handle — a hover state in the sense §3.3 of the visual language means, revealing the relationship only when the user is asking about it.

• This makes the clamp self-explanatory. The hard clamp is crossfade ≤ min(start, loopLength) (loop_span.h:19, and its "no material ahead of the loop" reasoning in engine/loop/CLAUDE.md). With the ghost drawn, the fade stops growing exactly when the ghost's left edge reaches the START mark or the LOOP mark — the user sees the reason instead of hitting an invisible wall. That is the single best payoff in this design and it costs nothing extra.

(d) The off-state and the Trigger state get words, not just alpha.

• Loop off. The pair draws in the kit's Disabled state with a centred dim caption in the span — DRAG TO SET LOOP when no span has ever been set (the pair is parked at the last quarter, defaultLoopBounds), LOOP OFF when a span is retained. The full off-state machine, and what the explicit enable does to it, is §6.4.
• Trigger mode. Loop is Gate-only (resolveLoop refuses in Trigger) but the markers still draw at full strength today, which is marks that do nothing. In Trigger the loop pair and the crossfade mark draw Disabled and are not grabbable, with a dim LOOP — GATE ONLY caption in the span. Disabled rather than hidden, because that is the established grammar — the editor's Gate segment already refuses and paints Disabled off the splineActive predicate — and because hiding a set loop on a mode flip destroys information the user put there. The START mark stays fully live in both modes.

6.4 The explicit loop enable (Γ-F4, ruled by Daniel 2026-08-01)

Settled: there is an explicit loop enable, and it lives on the CHROME ROW.

The framing this doc previously carried — "an enable costs a cell, so it is a §1.2 layout decision" — was wrong, and Daniel corrected it: loop is a waveform-overlay concept and has no deck. There was never a right deck cell for it. It is not on the overlay either (an overlay control that governs the overlay is circular), and it is not in a deck group.

Where it sits, and why that is free

The chrome band's toolbar row carries a right-anchored control run — preview · velocity cell · Mono|Stereo · Browse — with the title taking whatever the run leaves (sample_chrome.h). The enable joins that run as a two-segment Loop Off|On toggle, immediately left of the channel toggle, giving a two-toggle mode cluster with Browse still rightmost:

[▶ preview] [VEL knob] [Loop Off|On] [Mono|Stereo] [Browse]

Three reasons for that exact slot:

1. It is the same class of control as the one next to it. Mono|Stereo is a playback mode of the loaded capture; so is loop-on. They belong adjacent, in the same two-segment primitive.
2. Browse stays rightmost. It is navigation, not a mode — moving it would break the established right-edge reading.
3. It costs zero window width. The run is right-anchored and the title slot absorbs it, so kEditorMinWidth does not move and none of §1.6's 90 px headroom is spent. Constraint: the title slot must still hold its text at the 1190 floor. If it will not, the enable's segments narrow — the floor does not move. That is a hard rule, because the floor is a phase-wide acceptance criterion.

What it is, in the model — and it needs no new persisted field

The enable IS SampleLoop::hasLoop. That field already exists (play_params.h:210), is already the predicate resolveLoop refuses on (loop_span.cpp:12), and is already persisted inside the params payload's loopOverride block — where start and end are written unconditionally, whatever hasLoop says (params_payload.cpp:31-36). So the wire can already carry "off, with a span remembered." No ComponentState field, no version bump, no format change. This track stays off the payload ladder entirely.

What does change is the field's provenance. Today hasLoop is derived: the editor sets it true whenever a marker is dragged (editor_input_waveform.cpp:255,258) and false whenever the span collapses (editor_session.cpp:236). After Γ it is user-owned, with the gestures as shortcuts onto it.

The interaction with collapse-to-off — one authority, two shortcuts

Collapse-to-off is not retired, and it does not become a second state machine. It becomes a shortcut that flips the enable. hasLoop is the single authority; three gestures reach it:

Gesture	Effect on the enable	Effect on the span	Effect on the crossfade
Click the enable → On	on	retained as-is	retained
Click the enable → Off	off	retained	retained
Collapse the span (drag one loop mark onto the other)	off	destroyed → re-parked at defaultLoopBounds	zeroed
Drag either loop mark while off	on	takes the drag	retained (re-clamped)

Two of those rows are behaviour changes and each has a reason:

• Toggle-off retains the span. This is what makes an enable worth having at all: a toggle whose off→on does not restore what was there is not a toggle, it is a delete button. Today pickedMarkers (editor_session.cpp:221-226) discards the stored span and re-parks at the default whenever hasLoop is false. That re-park must become conditional on the span being invalid, not on the enable being off — a collapsed, inverted or out-of-range span still re-parks (that rule exists so two coincident handles cannot become ungrabbable, and it is still right); a valid span under a user-set off keeps its position.
• Toggle-off retains the crossfade. Same argument, and it does not contradict the existing zeroing rule, which is scoped to a span that no longer exists: editor_session.cpp:240-243 zeroes the crossfade on OFF precisely because "leaving a stale length here would silently re-apply it (clamped) the next time a loop is dragged back in." With the span retained, its clamp bound min(start, loopLength) is retained too, so there is nothing stale to re-apply. The zeroing predicate moves from "the enable is off" to "the span was destroyed." The reasoning behind the original rule is preserved intact, not overruled.

What the enable does to the "drag me" affordance

The parked pair at the last quarter was carrying two messages in one alpha value: there is no loop and drag here to make one. The enable takes the first message; the pair keeps the second.

• Off, no span ever set — pair parked at defaultLoopBounds, drawn Disabled, caption DRAG TO SET LOOP. Dragging either mark turns the enable on. The shipped drag-to-create gesture survives intact, and it now teaches the enable by demonstration: the user drags and watches the chrome toggle light up.
• Off, span retained — pair drawn Disabled at its own positions, caption LOOP OFF. There is nothing to "set," so the drag-me copy would be wrong. Dragging still turns the enable on, by the same rule.
• On — full four-mark grammar of §6.3, unchanged.

A grab implies intent to loop. That is the one rule behind both off-states, and it is what keeps the enable from being a gate the user has to remember to open.

The Trigger case — the enable disables itself, it does not clear itself

Per the Disabled-not-hidden principle already established for the marks: in Trigger the chrome-row enable draws Disabled and inert, with its state preserved and restored on the return to Gate. It does not clear hasLoop, and it does not hide. The enable's Disabled state and the span's LOOP — GATE ONLY caption are the same message delivered at two scales — the chrome row says this control is unavailable here, the span says why.

This transitively covers the drawn-EG case: enforceGateUnavailableWhileDrawn (play_params.h:198-205) forces Trigger whenever any envelope is drawn, so a spline EG disables the loop enable through the same predicate rather than through a second rule.

Disabled-but-grabbable (the off marks) vs. Disabled-and-inert (Trigger) is a deliberate distinction, not an inconsistency, and the discriminator is who said no: the user's own off is reversible by the very gesture being offered, while Trigger's refusal comes from the engine and no marker drag can talk it out of it.

6.5 Trade-offs and consequences, named

• The crossfade handle moves sides. A real muscle-memory break for the only current user. Mitigated by the unchanged drag direction and by the mark finally being labelled.
• The enable puts a waveform-band control on the chrome row, one band away from what it governs. That distance is the price of it having no deck; it is mitigated by the marks themselves changing state visibly when it flips, so the two surfaces are never ambiguous about which one won. The alternative — a control on the overlay governing the overlay — is circular and was not seriously considered.
• The track gains a chrome surface it did not previously have. sample_chrome (pure), editor_paint_chrome and editor_input_chrome come into scope, and so do editor_session's pickedMarkers/applyMarkers for the retention rule. §7.9 records what that does to the wave's disjointness claim.
• hasLoop changes provenance from derived to user-owned. No format change, but every existing site that infers it (two in editor_input_waveform, two in editor_session) is now writing to a user-visible control rather than to an internal flag, and must be re-read in that light rather than left alone because it still compiles.
• Top-strip density. Four caps and up to four labels in a strip that also carries envelope nodes. Mitigated by the suppression rule and the hover promote; if it still reads crowded in the DAW, Direction 2's rail (§6.2) is the pre-named escalation.
• The claim-arbitration inputs change. Today markerHandleRect gives a tab to the crossfade only, and resolveWaveformClaim breaks ties by "smallest nominal target area among the candidates that actually hit." Giving every mark a cap-grip changes the candidate set and every nominal area in it. The arbitration must be re-derived, and the open docs/TODO.md entry "Pre-existing staged-envelope-node shadow at zero-attack" must be re-evaluated against the new cap geometry — it may be resolved by the change or made worse, and either outcome must be recorded rather than discovered.
• The geometry stays pure. Cap rects, label boxes and the suppression rule belong in waveform_view (which already owns markerHandleRect) as pure, CTest-covered geometry. No hit-test math moves into the painter.
• The model does not change. crossfade remains a stored frame count with the same clamp, resolveLoop is untouched, and no ComponentState version moves. This is entirely a drawing and hit-test change — which is what makes it a safe track to run in parallel with the parameter work.
• Not chased: the 2.25:1 trace-over-fill pair stays exactly as accepted (see the constraint in (c)).

---

7. Collisions with existing invariants

Each of these is a place where Phase Γ contradicts, invalidates, or widens something a CLAUDE.md currently states. Naming them is the point; resolving them in source is staff-engineer's.

7.1 — knob_deck.h's fourteen-pixels-of-headroom note is invalidated. The header records that "the deck has fourteen pixels of headroom on its first row at the editor's floor width — a rowToggle would widen the GROUP and wrap the deck to a fourth row, past what the minimum window holds." That measurement is against the 980 px floor and the greedy three-row wrap; the reflow replaces both. The reasoning survives (a caption toggle rides existing slack, a row toggle costs group width); the number does not. It must be re-derived, not deleted.

7.2 — FILTER becomes the first non-envelope group to use captionToggle2. The slot exists and is free on FILTER, so Band|Notch moving to the caption corner needs no new geometry — but deck_groups.cpp's kEnvModeSegW comment describes the second slot as though it belongs to the env decks. Also freed: that comment says "the ceiling is PITCH ENV's, whose caption row lands exactly on its four-cell knob row at 23. Raising it reflows the deck's first row." After the reflow PITCH ENV is on row 2 with 48 px of caption slack, and the binding ceiling on kEnvModeSegW rises from 23 to 47 (PITCH ENV binds at 47, AMP at 55). No change is required; the constraint simply stops being tight, and the comment stops being true.

7.3 — Deterministic whole-group wrap stops deciding row membership. deckRowCount / layoutDeck implement a greedy left-to-right wrap. After the reflow, row membership is a property of the group (sound vs. contour) and MASTER is a right-anchored double-height group outside both rows. DeckLayout::rowCount and ::height change meaning, and deckHeight becomes a constant 2·kDeckGroupH + kDeckRowGap at and above the floor width. Whether the greedy wrap survives at all as a sub-floor degrade is an engineer's call; what is not optional is that at and above the floor width the layout is the specified two-row-plus-spanning-deck arrangement, arrived at by construction and not by a wrap outcome.

7.4 — knob_deck.h's "cell metrics and the editor floor move as a pair" gains a second driver. The invariant is currently directional: wider cells ⇒ wider floor. Phase Γ changes the floor without touching cell metrics, because the group inventory and its row assignment now also drive it. Restate as: the deck's cell metrics AND its group/row composition both drive kEditorMinWidth; none of the three may move alone.

7.5 — isLiveDeckParam becomes three-valued. See §2.3. The exhaustive switch must classify the two new DeckParams or fail to compile — which is exactly what it is designed to do, and which is why the two new parameters are cheap to add now.

7.6 — docs/TODO.md's deck-rework entry is superseded and its geometry is stale. The entry "The deck layout needs a real rework — one row, taller decks, controls stacked within a deck" records an older directive of Daniel's that this doc supersedes (he confirmed this explicitly): the new shape is one row of single-height sound decks with knobs side-by-side, not taller decks with within-deck stacking. Its measured-geometry block (840 px floor, kDeckCellW 48, group widths PITCH 150 / FILTER 440 / …) predates Θ-W6-T1 and is wrong. The entry has been rewritten to point here.

7.7 — Root CLAUDE.md's "Project docs" list omits docs/PLAN.md. PLAN.md exists and is the active roadmap (it says so in its own header, and TODO-1.0.md defers to it). The root CLAUDE.md list of plan-style docs names only ARCHIVE / COMPLETED / TODO / TODO-1.0. Flagged for staff-engineer; not mine to edit.

7.8 — Not a collision, worth recording as a confirmation. deck_groups.cpp reserves MASTER for "post-voice-mixer concerns." The limiter and the output meter are exactly that. Phase Γ discharges the reservation; it does not overrule it.

7.9 — The loop enable widens Γ-W2-T2 onto the chrome band, and the wave's disjointness claim needs restating rather than repeating. Before Γ-F4, W2-T2 was purely a waveform-band drawing and hit-test track. It now also owns core/instrument/ui/sample_chrome (one rect in the toolbar's control run), editor_paint_chrome/editor_input_chrome (draw + hit-test for it), and editor_session's pickedMarkers/applyMarkers (the span/crossfade retention rule). W2-T1 and W2-T2 remain disjoint at the module level with one named exception: editor_session.cpp. W2-T1 may touch it for the third commit tier's routing; W2-T2 owns pickedMarkers/applyMarkers. The partition is by function and the two do not overlap, so this is a textual merge adjacency, not a semantic contention — but it is a shared file in a phase whose wave boundaries are otherwise single-writer surfaces, and pretending otherwise would be the kind of thing that surfaces as a surprise at merge. Stated, not hidden. Everything else stays clean: the enable needs no ComponentState change, so W2-T1 keeps sole ownership of the payload ladder (v15) exactly as specced.

7.10 — getLatencySamples is a new surface, not a changed one. No getLatencySamples override, no kLatencyChanged, and no restartComponent call site exists anywhere in src/ today; the plugin ships the SDK default of 0. W1-T2 introduces the plugin's first latency reporting. There is therefore no existing behaviour to preserve — but §3.1.1's four verification requirements bind, because the deactivate/reactivate the flag mandates lands squarely on ReaSamplerProcessor::setActive, which is deliberately destructive in both directions.

---

8. Forks — five ruled, one open

8.1 Ruled by Daniel, 2026-08-01

All five forks this doc opened are closed. The rulings are folded into the sections that depend on them; this table is the index, not a second copy of the reasoning.

Fork	Question	Ruling	Where it landed
Γ-F1	Does kEditorMinHeight move 680 → 720?	No — stays 680. The reflow's 112 px goes entirely to the waveform.	§1.2 / §1.5, unchanged
Γ-F2	Limiter lookahead, or zero-latency?	Lookahead with DYNAMIC reported latency — zero when off, the lookahead when on, reported to the host's PDC. Overrides this doc's zero-lookahead recommendation.	§3.1.1 (new), §7.10
Γ-F3	Does the log taper raise the 2 s stage-time ceiling?	Not in this phase — stays 2.0 s. The 10 s ambition is preserved as a docs/TODO.md entry with its rationale.	§4.3, docs/TODO.md
Γ-F4	Explicit loop enable?	Yes — on the CHROME ROW. Not a deck cell; loop is a waveform-overlay concept and has no deck.	§6.4 (new), §6.5, §7.9
Γ-F5	MASTER's reserved slot: one cell or two?	One cell. Two would spend 60 of the 90 px headroom on an unnamed control and freeze row 1 forever.	§1.6 (new), §1.4

Two of these corrected this doc rather than confirming it, and both corrections are worth remembering as pattern:

• Γ-F2 inverted the recommendation. The zero-lookahead pitch weighed "monitoring latency on every instance" against limiter transparency — but that trade only existed under the always-active delay line framing. Daniel's condition (latent only when on, and reported) dissolves it, at the cost of a dynamic-latency restart. The alternative I proposed was answering a constraint he did not accept.
• Γ-F4 was mis-framed as a layout question. "An enable costs a cell" presumed the enable belonged to a deck. It does not — nothing about loop belongs to a deck — and once that is seen, the chrome row is obvious and free. The reframe was the answer; the fork as posed had no good option in it.

8.2 Open — one fork, surfaced by the Γ-F2 ruling

Fork Γ-F6 — kLatencyChanged mandates a host deactivate/reactivate. Is that acceptable as the cost of the limiter toggle?

This was not visible when Γ-F2 was posed and Daniel did not have it in front of him. The vendored SDK (pluginterfaces/vst/ivsteditcontroller.h:105-108) defines the flag as: "The host has to deactivate and reactivate the plug-in." In this plugin, ReaSamplerProcessor::setActive is destructive in both directions (reasampler_processor.cpp:85-109) — deactivate frees every sounding voice, reactivate re-decodes the WAV from disk. So flipping the limiter cuts held notes and reloads the sample. Full detail in §3.1.1.

• (a) Ship it, accept the cut. The limiter is a patch-design control set once while building a sound, not a per-take gesture; the enable is classified not automatable so nothing can flip it at rate; the plugin's own output is crossfaded so we emit no step. Cost: a user who flips it mid-audition loses the note they were holding.
• (b) Constant reported latency — the delay line engaged whenever the limiter design ships, on or off, so the toggle never changes latency and never restarts. Cost: exactly the thing Daniel's ruling rejected — every instance pays the lookahead in live monitoring whether or not the limiter is used. Named here as the pre-agreed fallback, not as a re-litigation.
• (c) Zero-lookahead — the original §8 recommendation. Closed; do not reopen it here.

Recommendation: (a), gated on a DAW measurement. Ship the dynamic-latency design as ruled, and make W1-T2's first deliverable a verification spike in REAPER: flip the limiter with notes held, during playback and while stopped, and record what actually happens — whether notes cut, whether the re-decode is perceptible, whether transport hiccups. If the observed behaviour is as ugly as the SDK's worst case allows, (b) is the pre-agreed fallback and needs one word from Daniel, not a redesign — the DSP is identical either way and only the latency-reporting predicate changes.

This is the only open fork in the phase. Nothing in §§1–7 is awaiting a Daniel answer.

---

9. Build shape

Sequenced into docs/PLAN.md as Phase Γ (worktree slug prefix pg-), four waves:

Γ-W1  Foundations                                    [3 tracks, disjoint by surface]
      T1 knob-interaction-law ............ item D    (editor input + deck_values tapers)
      T2 master-bus-audio ................ item C    (pure limiter + meter ballistics +
                                                      processor + LATENCY REPORTING)
      T3 contour-trace-curves ............ item E    (waveform painter)
Γ-W2  New controls, and the overlay's marks          [2 tracks]
      T1 pitch-rate-deck ................. item A    (params + engine + deck descriptor)
      T2 loop-crossfade-ux ............... item F    (waveform painter + pure marker geometry
                                                      + the chrome-row loop enable)
Γ-W3  The reflow                                     [1 track]
      T1 deck-reflow ..................... item B + C's UI half
Γ-W4  Preserve time-stretch                          [1 track]
      T1 preserve-time-stretch ........... item A's quality half   [measure-and-report gate]

The wave boundaries are collision boundaries, not preferences: deck_values.cpp is written by W1-T1 then W2-T1; editor_paint_waveform.cpp by W1-T3 then W2-T2; the deck descriptors by W2-T1 then W3-T1; and one params-payload version bump per wave, owned by one track (W1-T2 takes v14 for the limiter flag, W2-T1 takes v15 for rate + pitch offset) so no two tracks contend for the format ladder. The Γ-F4 ruling adds a chrome surface to W2-T2 and one named shared file inside W2 — §7.9, which restates the wave's disjointness claim rather than repeating it. Full track specs, dependencies and acceptance criteria are in docs/PLAN.md.