docs: close out wave Theta-W4, and defer the deck layout rework to TODO

This commit is contained in:
2026-07-31 20:31:53 -04:00
parent a32ab4b5b2
commit f115904e4f
3 changed files with 98 additions and 77 deletions
+9 -77
View File
@@ -197,83 +197,15 @@ is the Gate-mode sustain the AHDSR releases out of, and T2's bipolar pitch/filte
modulate targets whose envelopes W3 just reshaped. T2 additionally depends on W2-T1 for
the filter's existence and on W2-T3 for the preview button's toolbar position.
**Two tracks, in priority order.** Disjoint: T1 owns the engine loop path and the
waveform band's marker layer; T2 owns the deck band, the curve popup, and the preview
button in the chrome band. Neither touches the other's band.
#### Θ-W4-T1 — `gate-loop-sustain`
**Has landed** — see `docs/COMPLETED.md` for the full narrative. Loop points are now a
usable feature and a Gate-mode loop functions as the sustain. The regression half
resolved as present-but-unreachable, not removed: nothing in any capture path ever wrote
`Sample::loop`, so every capture opened with `hasLoop == false`, and the ghost default
parked `loopStart` at frame 0 directly under the start marker, where `markerAtPoint`'s
first-in-draw-order tie-break made the handle ungrabbable. Fixed by moving the ghost
span to `defaultLoopBounds` (last quarter, both handles clear), making a collapsed span
the explicit OFF gesture, and adding a parameterized crossfade — stored in source
frames, not ms (a deliberate divergence from the plan's ms lean, following
`sample_map.h`'s source-frame rule), linear rather than equal-power, and normalized over
`crossfade 1` (a review Major fixed a residual seam discontinuity) so the last
rendered frame lands exactly on the incoming tap. New pure module
`src/core/instrument/engine/loop/` (`loop_span`) holds the loop math; the editing
surface is the waveform markers plus a new top-strip `markerHandleRect` grab tab, a
general fix for markers sharing a frame. Params payload is v11 (`kParamsLoopVersion`);
slot 12 is reserved for T2. Left to Daniel: whether the seam sounds smooth on real
material, the top-strip tab's discoverability, the LICE rendering of the tab and
crossfade fill, and whether the crossfade default should stay 0.
---
#### Θ-W4-T2 — `velocity-deck-and-bipolar-curves`
**Goal.** Give the three velocity-curve popups one home, make the pitch and filter curves
bipolar and off-by-default, and replace the preview button's text with a glyph.
**Consolidates item 11.**
**Surface boundary — owns:** `core/instrument/engine/velocity_curve` (bipolar y-domain),
`core/instrument/ui/curve_popup`, the **deck band** (the new VELOCITY group), and **the
preview button in the chrome band** at the toolbar position W2-T3 gave it. Does not touch
the waveform band.
**Behavior.**
- **The VELOCITY deck.** All three velocity-curve popup buttons (amp, pitch, filter) live
**together in a new control deck group labelled "VELOCITY", placed to the left of the
VOICE group.** This **supersedes the original ask's per-section placement** — Daniel
confirmed the MASTER placement was a real contention point: **MASTER is reserved for
other, post-voice-mixer concerns** he will add to later, so the velocity curves do not
belong there. No velocity-curve button appears in MASTER, PITCH, or Filter.
- **Bipolar pitch/filter transfer functions.** Pitch and filter velocity transfer
functions are **bipolar: y range [1, 1], default y = 0** — flat at zero, meaning
velocity modulation of pitch and filter is **off until the user draws a curve**.
- **Amp stays unipolar at [0, 1]**, and its existing flat-unity default is unchanged.
- **Storage:** the curves live in the instrument's one parameter set.
- **Preview glyph.** The preview button's inner text is replaced with a glyph. Proposed
at product level: a right-pointing **play triangle** — the universal audition read.
**Daniel's constraint: no new dependencies** — a statically embedded bitmap or
equivalent that plays nicely with the existing LICE drawing path.
**Acceptance criteria.**
- The three velocity-curve buttons sit together in a deck group labelled **VELOCITY**,
immediately to the left of the VOICE group; no velocity-curve button appears in MASTER,
PITCH, or Filter.
- Opening the pitch or filter curve shows a **bipolar editor ([1, 1]) defaulted flat at
y = 0**; played velocities produce no pitch/filter modulation until a curve is drawn,
then audibly follow it.
- The amp curve's domain ([0, 1]) and flat-unity default are unchanged.
- The velocity curves persist in the one parameter set and round-trip save/reload.
- The preview button shows the glyph (no text) and stays legible in **all** interaction
states; **no new build or runtime dependency is introduced.**
**Open questions.**
- **Does a user-facing pitch velocity transfer curve already exist, or does this item
introduce it? [verify]** Unverifiable in the source doc under its no-code-reads
constraint. If absent, this track introduces it. Check before scoping.
- **Bipolar rendering in the shared spline editor [propose].** Item 3 (Θ-W5) enhances the
one spline implementation for hard points; this track must render and edit a bipolar
y-domain alongside the amp curve's unipolar one. Land the bipolar domain here in the
existing editor; Θ-W5 then adds hard points to the same editor without re-deciding the
domain.
**Both tracks have landed** — Θ-W4-T1 (`gate-loop-sustain`) and Θ-W4-T2
(`velocity-deck-and-bipolar-curves`) — see `docs/COMPLETED.md` for the full narrative of
each. Between them: loop points are now a usable feature, with a Gate-mode loop acting
as the sustain and a parameterized crossfade at the seam; and the three velocity-curve
popups (amp, pitch, filter) now live together in a new VELOCITY deck group, with the
pitch and filter curves bipolar and flat-by-default so their modulation is off until
drawn, while the amp curve stays unipolar and unchanged, and the preview button's text
is replaced by a drawn play-triangle glyph. Params payload reached v11 with T1's loop
block and v12 with T2's velocity→pitch curve appended after it.
---