From 34c398d310b75590e021aa771b66c6e97cd5b6fc Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Fri, 13 Nov 2026 05:24:21 +0700 Subject: [PATCH 1/5] docs(prd): lock approved gain FX rack and sends-on-faders operator contract --- ...RD_CONTEXTUAL_CONSOLE_GAIN_SOF_20261113.md | 83 +++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 docs/PRD_CONTEXTUAL_CONSOLE_GAIN_SOF_20261113.md diff --git a/docs/PRD_CONTEXTUAL_CONSOLE_GAIN_SOF_20261113.md b/docs/PRD_CONTEXTUAL_CONSOLE_GAIN_SOF_20261113.md new file mode 100644 index 000000000..c77fc46c7 --- /dev/null +++ b/docs/PRD_CONTEXTUAL_CONSOLE_GAIN_SOF_20261113.md @@ -0,0 +1,83 @@ +# PRD — Contextual Console: GAIN / FX RACK / Sends on Faders + +**Product decision:** Owner-approved 2026-11-13. **Status:** NORMATIVE REQUIREMENTS, **not** implementation / native PCM / release evidence. **Companion:** [ARD — Contextual Console](ARD_CONTEXTUAL_CONSOLE_GAIN_SOF_20261113.md). + +**Scope and precedence.** This addendum governs the GAIN / FX RACK view selector, Sends on Faders (SOF), send PRE/POST, send ON/OFF, source-channel digital gain, and related WIRE controls. It supersedes *conflicting UI and tap descriptions* in [PRD v5.2](PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md), [MS5](MS5_NATIVE_AUX_SENDS_ON_FADERS_20261031.md) and earlier wire preview proposals, **only for this scope**. [WIRE-first PRD](PRD_WIRE_FIRST_LIVE_ROUTING_20261104.md), [WIRE-first ARD](ARD_WIRE_FIRST_ZERO_ADDED_LATENCY_20261104.md), [AGENTS.md](../AGENTS.md), and the one approved \`/preview/\` take precedence on overall routing, UI authority, and safety. This does **not** authorize another GUI, audio engine, or independent mixer. + +## 1. Operator outcome + +An ordinary operator can (a) adjust a vocal channel's **digital** input gain with a knob and legible dB LCD, (b) return immediately to the existing FX rack, (c) select BUS A / FX return / another legally reachable send destination and move all contributing channels' **send** faders, (d) independently choose PRE or POST and enable/disable each send, and (e) return to the exact previous channel-fader mix **without changing the graph by viewing it**. + +Optimize for a genuine live digital console: low visual noise, compact premium physical controls, no cards/panels piled onto every strip, no extra wizard, no hidden monitoring/ARM step, no forced app/device restart, and no DAW timeline. Borrow **interaction patterns** from Yamaha DM7/StageMix SENDS ON FADER, Waves eMotion LV1 Fader Flip and Layer Modes, Allen & Heath Avantis Pre Mix, and Studio One per-send controls; do not copy their proprietary pixels, branding, icon artwork, DSP or assets. + +**Product naming:** ArSonMix is the mixer; **Harmonice** is an internal vocal-harmony FX/plugin, **not** the name of the entire mixer, GAIN, SOF, or spatial 8D-SonKu processor. + +## 2. One approved compact mixer, two operating contexts + +| Context | Toolbar / indication | Shared channel area below Input | Fader | PRE/POST object | +| --- | --- | --- | --- | --- | +| **MAIN / CHANNEL MIX** (default) | Interlocked \`GAIN | FX RACK\` selector; FX RACK initially selected | Either original full FX insert rack **or** digital input GAIN knob + numeric LCD, at **identical height/width** | Regular channel fader; pinned MAIN is normal MAIN | No hidden global send changes | +| **SENDS ON FADERS** | High-contrast \`SEND MIX → [destination]\`; dedicated target selector; conspicuous return-to-main action | **SEND CONTROLS** for this channel -> selected destination (send enabled, PRE/POST tap, status; send pan only if implemented) | Send level **only for that specific existing parallel EdgeId** | The selected **source -> selected target** send only | + +- The two GAIN / FX RACK buttons are a **mutually exclusive segmented view selector**, not independent effect-power switches or per-channel DSP toggles. Position near BANK/VIEW and SOF in the original toolbar; use existing button design tokens. At least one is selected in MAIN context. Switching views must **not** mute, unload, instantiate, reorder, bypass, or reset a VST3. +- SOF temporarily supersedes the center view on eligible source strips and remembers the operator's prior GAIN/FX RACK choice. On exit, restore that view and all channel fader positions, PAN, FX order, routes and active audio. The SOF target can be switched without leaving SOF. +- Keep **the same** approved metallic mixer skins, SVG fader cap, approved MUTE/SOLO/PRE/POST hardware PNG sprite state (current approved main; later versions only after merge), physical WIRE jacks/cable, channel identity, PAN, meters, density/bank, and pinned MAIN geometry. No competing public URL, detached mixer, oversized text/cards, permanent new rows or synthetic FX/routing widgets. +- MUTE/SOLO are **channel commands in both modes**, never relabeled as send ON/OFF. MASTER remains the actual MAIN fader in either mode and is never silently flipped to the selected bus. GROUP/FX targets remain independently controllable via their actual channels, not simulated duplicate strips. +- Visual authority must be specific: MAIN fader readout vs \`SEND → BUS A −12.0 dB\`; \`NO SEND · Patch with WIRE\`; \`PRIMARY ROUTE\`; \`PRE-FADER\`; \`POST-FADER\`; \`MIX\` when viewing mixed edges. Do not show a glowing/connected send when no actual accepted edge exists. +- Standard/Compact/Narrow should avoid clipping. SOF can minimize ancillary FX text or hide inactive detail in compact density, but WIRE, faders and current pinned MAIN geometry remain present. + +## 3. GAIN workflow and meaning + +1. Click **GAIN** in MAIN context -> the existing FX cell becomes a small responsive physical-style **knob**, with an LCD numeric \`+0.0 dB\` beneath. Click **FX RACK** -> exactly the existing live insert list returns. +2. Knob supports coarse drag/wheel, fine adjustment (Shift), keyboard accessibility, numeric LCD direct entry and reset to unity by deliberate double-click; avoid accidental reset on ordinary click. Preserve value and keyboard focus through re-renders; prefer local control updates rather than recreating whole bank on every gesture. +3. The value is **DIGITAL INPUT GAIN** before channel inserts, not the physical microphone preamp/ASIO driver's gain, not WIRE send level, not channel fader, and not a second FX. Clearly label it \`INPUT GAIN\`; WIRE's old \`GAIN\` inspector label becomes \`SEND LEVEL\` where a send is being edited. +4. Gain is stored by stable ChannelId and survives FX view switching, session save/reopen, device reconnect, channel rename, bank/density changes and ordinary WIRE replug. Stereo processing defaults to linked L/R gain; no invented independent control unless native supports it. Other node types must not show a functional **input** gain if they have no admitted gain stage. +5. A browser mock's current trim range (\`−24 .. +24 dB\`) is **not proof** of a native gain implementation, hardware capability or public range guarantee. Confirm native representability, headroom, metering, clipping behavior and rollback before exposing an active native control. + +## 4. SOF workflow and behavior + +1. User presses **Sends on Faders**, selects a **verified eligible destination** BUS, FX Return or legal internal ChannelId target. The target label is unambiguous, persists while paging through banks, and displays source and destination identity; names are display labels, never persistent identity. +2. Every eligible source channel displays its own existing \`(ChannelId, EdgeId) -> destination\` send. If an edge exists and is an independent send, the channel fader can adjust its level and show the actual accepted dB value. A source with **no send** shows \`NO SEND\`; fader is inactive until the user **explicitly** patches WIRE or chooses a clear connect operation. Never auto-create a WIRE by dragging a fader. +3. **SOF fader at minimum = silence for that send**, not a route removal. Repeated low/high movements must preserve **exact EdgeId, destination, tap, pan and send enabled state**; no route duplicate, accidental dry duplication or implicit MAIN feed. WIRE remove/retarget/route-only requires separate explicit user action. +4. **SEND ON/OFF is separate** from route topology and level: OFF suppresses contribution but retains saved level, tap, pan and EdgeId; ON restores precisely the prior values. An absent send is not the same as OFF and should not appear connected. Existing mute/solo/fader and channel safety semantics must not be silently repurposed. +5. **PRE/POST is per outgoing parallel send**, not a channel-global operation. For \`VOCAL -> MONITOR\` PRE and \`VOCAL -> REVERB\` POST, changing MONITOR must leave REVERB unchanged. Show PRE/POST in the SOF **SEND CONTROLS** area next to send ON/status. Outside SOF, the existing physical PRE/POST button may function only for one unambiguously selected edge, or serve as read-only/mixed indicator when multiple edges exist. Never bulk-retarget all sends via a single ambiguous button. +6. PRE means **post-insert PRE-FADER**; POST means **post-fader** (with documented post-pan policy). **PRE-FX** is a *different* tap. Until native DSP distinguishes these and ACKs the real result, the UI must say \`PRE-FX\` where that is what it actually implements; do not rename \`split\` to PRE-FADER just to make the badge look standard. Default newly connected independent sends to POST unless explicit operator choice applies. Primary exclusive OUT to MAIN/GROUP is not an independent PRE/POST send, and cannot be converted by the SOF PRE key. +7. Mono/stereo conversion, PAN/BALANCE, polarity, channel MUTE/SOLO, solo-safe and PFL/cue remain independently defined. **Product safety target:** MUTE gates all audio contributions including PRE sends; PRE must remain independent of channel **fader**, not create a secret bypass around MUTE. Any compatibility difference needs explicit verified migration and tests; do not silently reinterpret older .smix sessions. +8. A source-to-destination pair may already have a primary route. Do not pretend that primary route is a parallel send or make a second route just for SOF. Disable SOF fader appropriately, with a truthful explanation; primary OUT is controlled by the channel fader in MAIN context. + +## 5. Native truthfulness, failures and recovery + +- GUI mock / approved GitHub Pages \`/preview/\` may demonstrate view switching, but **does not provide PCM**. A native control is interactive only when the underlying typed intent, actual installed graph authority and correlated ACK + accepted readback exist. Absent capability: show explicit unavailable status; **never** move/send audio speculatively. Merely hiding/demo-disable may be acceptable temporarily, never as completed public feature. +- Live session should automatically preserve the operator's trusted last-used graph and useful audio across GUI toggles and device reconnect. Do not demand a Monitor ON/ARM/rebind wizard to return to valid audible output; do not override an intentional user MUTE, SOURCE ONLY, missing output or device safety failure. +- No audio drop, VST3 reset, FX GUI close, device reset, layout jump or stale fader value when clicking GAIN/FX RACK, entering/leaving SOF, switching target, or changing page. A failed native ACK must keep the **previous accepted** value and state, with specific feedback. +- Only one authoritative native callback/PCM graph. Preview model, JS local state, \`sendSlots\` legacy objects or device ordinal must not become competing routing owners. + +## 6. Acceptance criteria — must be witnessed + +| Scenario | Required evidence | +| --- | --- | +| GAIN/FX mode interlock | Same FX section dimensions; UI chooses one mode, restores correctly, plugin chain and audio continue unchanged; real native gain changes measured PCM and survives reopen | +| PRE vs POST on a channel | Real PCM fixture: reduce source fader to minimum -> PRE-FADER send still outputs signal (when not muted) and POST-FADER send goes silent; channel MUTE closes both under new approved policy | +| Two destination sends | MONITOR PRE and REVERB POST, each with own levels/pan/ON; changing only one EdgeId never alters the other or primary MAIN | +| Fader minimum/off | −∞/minimum produces zero send audio, with retained EdgeId and all send settings; toggling OFF/ON restores gain; unplug is the only explicit removal | +| No send / primary-only | SOF says NO SEND or PRIMARY ROUTE; fader action cannot auto-connect, auto-remove, promote or duplicate WIRE | +| SOF target and exit | Selected target changes only displayed send faders; MAIN/Channel fader and pinned MAIN never change; original GAIN/FX view returns | +| Hardware and persistence | Real ChannelId/EdgeId readback, .smix restore, restart/reconnect, native PCM and VST3 effects in both routes, explicit device epoch, ASIO primary isolation | +| GUI and performance | Single assembled \`/preview/\`; existing approved PNG/hardware faders unchanged; widths 1366, 1680, 1920 + applicable narrow; no lost focus, excess DOM rebuild, per-frame UI churn, realtime allocation or extra callback | + +**Evidence levels:** Browser/UI smoke proves presentation only; native deterministic PCM tests prove signal routing; native exact-SHA package verifies build; genuine ASIO device/operator FAT proves installed audio behavior. Never elevate one tier to another. + +## 7. Status ledger / next-thread handoff (as checked 2026-11-13) + +- Current main observed: \`6309d79b5ff8e873e64326f5319c177aba118235\` (refresh; not permanent authority). +- [PR #604](https://github.com/masarray/arsonmix/pull/604): open draft GAIN/FX interlock and contextual SOF browser reference, guards against −60 dB WIRE deletion and ambiguous bulk PRE changes. Do **not** claim native audio shipped. +- [PR #606](https://github.com/masarray/arsonmix/pull/606): open draft, more advanced integrated source base **including #604** and work on 8D-SonKu. Never independently merge both without reconciling duplicate changes. 8D-SonKu and Harmonice are separate plugins from this mixer feature. +- Native digital gain, a proper **PRE-FADER after FX** tap, SOF enabled state, native per-EdgeId level/tap/ON ACK/readback and physical ASIO proof remain **implementation work**, not documentation-complete. +- Before any code changes: refresh main, PR #604/#606 heads, actual source/CI/merged status. Implement one bounded integrated vertical milestone in the live advanced branch or a correctly rebased successor. Preserve the SonKu/editor changes; do not overwrite someone else's branch head. Follow [ARD](ARD_CONTEXTUAL_CONSOLE_GAIN_SOF_20261113.md), root [AGENTS.md](../AGENTS.md), and the [fast feature playbook](architecture/FEATURE_EXTENSION_PLAYBOOK.md). For docs-only updates no expensive Windows build is needed. + +## 8. References (patterns, not visual/DSP copies) + +- Waves eMotion LV1 Classic user guide: https://assets.wavescdn.com/user-guides/emotion-lv1-classic-console-user-guide.html +- Yamaha DM7 reference/StageMix manuals (FADER/SENDS mode, pre and on workflow): https://usa.yamaha.com/products/proaudio/mixers/dm7/downloads.html +- Allen & Heath Avantis user guides: https://www.allen-heath.com/hardware/avantis/avantis/resources/ +- Studio One / Fender Studio Pro Console/send workflow: https://fenderstudiopromanual.fender.com/en/Content/Mixing_Topics/Effects_Signal_Routing.htm From 4921f9edf0881fdad68413101917fb7f61d1e60a Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Fri, 13 Nov 2026 05:27:43 +0700 Subject: [PATCH 2/5] docs(ard): define single-graph gain SOF tap and send lifecycle contract --- ...RD_CONTEXTUAL_CONSOLE_GAIN_SOF_20261113.md | 154 ++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 docs/ARD_CONTEXTUAL_CONSOLE_GAIN_SOF_20261113.md diff --git a/docs/ARD_CONTEXTUAL_CONSOLE_GAIN_SOF_20261113.md b/docs/ARD_CONTEXTUAL_CONSOLE_GAIN_SOF_20261113.md new file mode 100644 index 000000000..770202250 --- /dev/null +++ b/docs/ARD_CONTEXTUAL_CONSOLE_GAIN_SOF_20261113.md @@ -0,0 +1,154 @@ +# ARD — Native Contextual Console, Digital Gain, and Per-Edge Sends on Faders + +**Decision date:** 2026-11-13. **Status:** NORMATIVE TARGET / implementation contract, **not** native-feature completion, public release, or physical FAT. **Companion:** [Owner-approved contextual PRD](PRD_CONTEXTUAL_CONSOLE_GAIN_SOF_20261113.md). + +**Scope precedence.** For contextual GAIN/FX RACK, SOF, send ON/OFF and PRE/POST behavior this document supersedes conflicting sections of the historical [ARD v5.2](ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md) and [MS5](MS5_NATIVE_AUX_SENDS_ON_FADERS_20261031.md). It preserves the [WIRE-first architecture](ARD_WIRE_FIRST_ZERO_ADDED_LATENCY_20261104.md), [single approved GUI](GITHUB_PAGES_PREVIEW.md), [root AGENTS](../AGENTS.md), current physical MUTE/SOLO/PRE/POST PNG material, audio/device safety, native PCM graph and approved plugin lifecycle. This specification must not become a duplicate JS engine or independent audio callback. + +## 0. The architectural invariant + +\`\`\`text +Approved assembled /preview/ (one DOM; visual/intent only) + -> web/approved-native-bridge.js + web/approved-native-contract.js + -> src/Main.cpp native message/CONTROL dispatch + -> src/NativeLogicalMixerControl.h / NativeLogicalMixerWorkspace.h + -> accepted MixerSessionDocument with stable ChannelId, EdgeId, InsertId + -> CONTROL: validation, DSP parameter staging / prepared-graph compilation + -> DynamicNativeSessionPublisher + existing realtime route publisher + -> ONE JUCE AudioIODeviceCallback / installed PCM graph + -> installed ACK, graph/device epoch + actual accepted readback -> same DOM +\`\`\` + +A logical-only offline edit, a retained graph, an installed graph and audible verified hardware are **different evidence levels**. Browser \`/preview/\` renders a **demonstration**. No CSS key frame, local \`wireEdges\`, simulated meter, 250ms polling result or optimistic DOM value may claim actual PCM. + +## 1. Ownership map (reuse existing seams, no substitute console) + +| Concern | Existing owners / entry points | Required behavior | +| --- | --- | --- | +| One GUI, layout modes | \`site/preview-v2/index.html\` is **internal build input**, \`site/preview-v2/assets/mixer-section-controls.css\`, approved PNG key CSS/atlas, \`scripts/build_pages.py\`, \`scripts/build_approved_native_gui.py\` | Build **only** approved \`/preview/\` for Pages and native; \`/preview-v2/\` is not a separate product GUI. View-only state separate from PCM model. Preserve channel/fader/master/physical WIRE geometry and artwork. | +| Native UI truth and transport | \`web/approved-native-bridge.js\`, \`web/approved-native-contract.js\`, \`integration/ApprovedNativeControlIntent.h\`, native host \`src/Main.cpp\` | Typed capability + requestId + graph revision + device epoch, rejected command feedback; only accepted value after correlated native ACK/readback. | +| Logical mixer, save/restore | \`src/NativeLogicalMixerControl.h\`, \`src/NativeLogicalMixerWorkspace.h\`, \`src/NativeMixerSessionDocument.h\`, \`src/NativeMixerSessionStore.h\`, \`engine/core/DynamicChannelRoster.h\` | Authoritative persisted ChannelId digital gain and EdgeId tap/level/enabled. Preserve old session data and stable IDs; schema migration, not shadow routing. | +| PCM and FX | \`engine/core/DynamicPreparedMixerBlock.h\`, \`engine/core/PreparedMixerBlock.h\`, \`engine/core/DynamicNativeSessionPublisher.h\`, \`src/LiveAudioEngine.h\`, \`src/LiveDryRoutingLab.h\` compatibility | Actual pre/post tap and parameter smoothing in one existing callback. Keep plugin lease processing once per routed channel/bus and preserve reported FX latency/PDC. | +| UI + PCM tests | \`tests/sof_contextual_console_smoke.py\` (in #604/#606 until merged), existing WIRE/publisher tests; nearest native PCM/bridge/session fixtures | Test distinct presentation and installed audio, not a text-only source assertion. No redundant Windows/installer per docs/UI edit. | + +The file list is an entrypoint, not a command to edit every file. Split large handlers only when replacing redundant responsibility with a tested single owner, not by layering new wrappers or independent state machines. + +## 2. State model — presentation is not routing + +\`\`\`text +ViewContext { + mixerMode: MAIN_MIX | SENDS_ON_FADERS; // ephemeral presentation + mainStripPane: FX_RACK | INPUT_GAIN; // remembered while SOF active + selectedSendDestination: ChannelId?; // stable ID, not name + selectedWireEdge: EdgeId?; +} +ChannelState { ChannelId, inputGainDb, faderGain, pan, mute, solo, inserts, ... } +SendEdge { EdgeId, source:ChannelId, destination:ChannelId, + role:PRIMARY_OUT|PARALLEL_SEND, tap:POST_FADER|PRE_FADER|PRE_FX, + gain, sendPan, enabled, ... } +\`\`\` + +**This is a target conceptual schema, not a claim these fields/enum strings exist today.** Expose only capabilities implemented by the installed native session. The existing browser \`wireTapMode=send|split\` and EdgeId \`mode=send|split\` are *legacy reference representations*, not proof of production PRE_FADER. \`split\` currently means PRE-FX in the preview, so migration must preserve meaning in saved sessions and not silently reinterpret it. + +Presentation changes (\`GAIN\` vs \`FX RACK\`, SOF enter/exit, selecting BUS, bank/paging, density and panel collapse) are **view-only commands**. They may re-render only affected controls, but must not issue a WIRE transaction, DSP/FX create/destroy, device apply or audio rebind. Persist actual DSP parameters in \`.smix\`; optional UI-view preference may live separately and must never gate startup sound. + +**Identity / topology:** +- \`ChannelId\`, \`EdgeId\`, \`InsertId\`, graph revision, requestId and device epoch form identity/ordering. Display name, strip ordinal, array index, AUX number and current bank are not identities. +- \`PRIMARY_OUT\` is one exclusive main route to MAIN/GROUP and follows the channel's normal fader semantics; it is **not** editable as a parallel PRE/POST send. \`PARALLEL_SEND\` may target only validated legal destinations without self/cycle/double-feed; established WIRE graph legality prevails. +- Selected source+target resolves one **accepted** parallel EdgeId; if no such edge, present \`NO SEND / Patch with WIRE\` and disable send gain/tap. Never auto-connect from send fader motion, nor auto-promote a primary route into a send. +- When a selected channel has several outgoing sends, an old channel-wide PRE/POST physical key cannot modify them all: use explicit selected EdgeId or show \`MIX\` and require selection. In SOF context the PRE/POST key is *per selected target*. + +## 3. Exact native signal graph and tap naming + +\`\`\`text +Actual physical/software capture (verified source/pin/epoch) + | + v +Source decode / mono-stereo ingress / polarity + | + v +DIGITAL INPUT GAIN [one ChannelId gain stage; never device mic-preamp] + | + +---- PRE_FX tap [only if separate legitimate capability is admitted] + | + v +Ordered internal FX + external VST3 inserts [actual DSP, known PDC] + | + +---- PRE_FADER tap --- independent send LEVEL/PAN/ENABLED ---> legal BUS/FX target + | (after FX; before channel fader) + v +Channel FADER + channel PAN/BALANCE + | + +---- POST_FADER tap -- independent send LEVEL/PAN/ENABLED ---> legal BUS/FX target + | + v +PRIMARY_OUT (GROUP / MAIN) -> bus FX/fader/OUTPUT -> verified device +\`\`\` + +This diagram is conceptual **channel-stage order**, not a second processing pass or an extra physical output path. \`PRE_FADER\` **must** carry fully processed inserts and not follow the source fader. \`POST_FADER\` **must** follow source fader and the documented pan/balance policy. \`PRE_FX\` is distinctly different and may be supported as an explicit advanced tap, not relabeled \`PRE\`. POST is the default for a newly created independent SEND unless an operator has deliberately chosen a different admitted tap. + +**MUTE rule:** Product safety policy for new qualified behavior is channel MUTE gates PRE and POST parallel sends as well as primary contribution, with deliberate click-free ramp. PRE ignores *fader position*, not MUTE. SOLO policy must preserve existing acknowledged live solo/monitor behavior and must be fixture-tested rather than silently rebuilt during this feature. Explicit channel mute/unmute or device loss must not be bypassed by SOF or by PRE wiring. Any legacy session compatibility distinction must be audited and migrated without changing old audio secretly. + +**Stereo/PAN:** For mono sources, compute legal mono->stereo projection using the destination/edge's defined pan law; for stereo channels preserve L/R, avoid unintended doubling or accidental 6dB dry mix. Per-send PAN is independent if admitted; do not falsely display a pan value without native support. Never insert a second plugin execution just to produce PRE and POST taps. Internal routing can add zero pipeline samples *only when the actual plugin/PDC/device latency permits*; avoid claiming 0ms absolute roundtrip. + +## 4. Commands, synchronization, idempotence + +These operation names are **proposed typed design names**; implement/reuse equivalent existing canonical commands if they exist, and do NOT expose names to clients before the capability snapshot advertises them. + +| Gesture | Target typed operation | Preconditions, postconditions | +| --- | --- | --- | +| View \`GAIN\` or \`FX RACK\` | UI-local \`SetStripPane\` | Pure view; preserve plugin state; bypass and FX UI unchanged | +| SOF enter/leave; target BUS selection | UI-local \`SetMixerMode\`, \`SelectSendDestination\` | Source/dest stable IDs; no DSP or route mutation | +| Move Input Gain knob / numeric entry | \`SET_CHANNEL_INPUT_GAIN\` (ChannelId, gainDb) | Prepare parameter for existing channel pre-insert gain; clamp only to advertised exact range; ACK native applied value + channel/graph revision; reject stale/invalid without optimistic audio claim | +| Drag a send fader | \`SET_SEND_LEVEL\` (EdgeId, gainDb/linear) | Parallel send exists, destination legal; only one edge gain changes; no \`CONNECT\`, \`REMOVE\`, \`ROUTE_ONLY\`, tap reset, or primary fader mutation | +| Toggle SEND ON/OFF | \`SET_SEND_ENABLED\` (EdgeId, bool) | OFF sets contribution to 0 but retains EdgeId, gain, tap, pan and destination; ON restores; no WIRE removal | +| Toggle PRE/POST | \`SET_SEND_TAP\` (EdgeId, PRE_FADER|POST_FADER) | One selected EdgeId; structural tap change off callback; validated new graph, atomic publish and ACK/readback; never use legacy PRE_FX as shorthand | +| Patch/remove/retarget a WIRE | Existing explicit \`WIRE_TRANSACTION\` contract | Operator-initiated topology edit, cycle/headroom checks, same stable EdgeId on replug as permitted | + +All native intents carry **requestId**, **expected logical/graph revision** and proper ChannelId/EdgeId; include **device epoch** when actual installed PCM/device binding is concerned. Validate identities, capability, finiteness, legal dB/linear representation, duplicate/replayed requests, expected graph version, role and destination before staging. + +**Reply categories:** \`REJECTED\` (no accepted state change), \`LOGICAL_ONLY\` (durable offline state, no audio claim), \`RETAINED\` (not installed PCM), and \`INSTALLED/ACKED\` (matching installed graph revision and parameter/tap). UI must match accepted snapshot; late/stale ACK cannot overwrite newer selection. Never silently present LOGICAL_ONLY as active sound; provide a compact status hint rather than noisy error text. + +**Realtime parameter path:** For gain/level/enabled on an unchanged edge, prefer a bounded preprepared parameter mailbox / existing DSP ramp with no graph rebuild per pointer movement. Coalesce GUI updates by target revision so wheel/drag does not flood CONTROL or trigger full bank DOM render; do not postpone **all** audible response to mouseup if it makes live mixing unusable. Apply click-free smoothing to gain changes and send OFF; preserve correct final accepted value. For actual tap/topology edits, prepare off-audio-thread immutable graph, verify cycles and plugin order, publish atomically at safe callback boundary, retire only after callback acknowledgment. Never allocate, lock, scan VST, log, await device, or construct JSON in the realtime callback. + +**Fader floor is a special case:** Browser reference may display \`−60 dB\` as minimum, but \(10^{-60/20}=0.001\), **not silence**. Define one *explicit* \`-∞ / OFF / zero-linear\` representation at the physical fader stop (or the negotiated minimum) so the DSP actually receives zero; do **not** map numeric \`−60 dB\` to 0.001 and assert silence. Most importantly, **never** convert this control value into a WIRE \`REMOVE\` operation. Release/ramp once, retain EdgeId. + +## 5. Native migration / current state gaps + +**Checkpoint checked on 2026-11-13** (refresh live before coding): main \`6309d79b5ff8e873e64326f5319c177aba118235\`. [#604](https://github.com/masarray/arsonmix/pull/604) is draft browser contextual-GAIN/SOF prototype; [#606](https://github.com/masarray/arsonmix/pull/606) is the **more advanced** draft including #604 and SonKu source. Neither is certified as merged or release-quality in this checkpoint. + +- Existing #604/#606 reference implementation has \`gainView/fxView\`, \`stripView\`, \`sectionGain\` and \`sectionSof\`, per-EdgeId PRE action, protected SOF gain, disabled absent edge, toolbar \`SEND MIX\` label, and owner-approved PNG sprite. **Reuse** this work if still live, not a competing rewrite. +- Present source: \`sectionGain\` in browser demonstrates \`t.trim\` range and LCD, but native input Gain is marked **pending**; native bridge hides/blocks unsupported demo-only actions. An *actual* native digital input-gain value and PCM node are required before enabling it. +- Present source: \`sectionSof\` PRE currently maps browser \`mode='split'\` to **PRE_FX**, not native post-insert PRE_FADER. Native \`SET_SEND_TAP\` graph transaction and truthful PRE_FADER readback are required, with migration for existing split edges. +- Present source: browser \`getSofEdge\` resolves an exact parallel edge; \`setSofLevel\` no longer removes a WIRE at minimum and will not auto-create a missing edge. Native per-send level and enabled commands still need capability and installed readback. +- Native bridge currently suppresses \`sofToggle/sofTarget\` as reference-only until acknowledged native send-gain routing exists. That is **honest**, but not a complete production SOF. No pseudo-native UI that works only with browser-local \`wireEdges\`. +- \`DynamicChannelRoster.h\`, \`NativeLogicalMixerWorkspace.h\`, \`ApprovedNativeControlIntent.h\`, \`PreparedMixerBlock.h\` already contain pieces of pre/post send/parameter mechanics; audit exact processing point, mute/solo, graph transactions and native coverage before adding new state. Do not create duplicate DSP support. + +## 6. Implementation order — one meaningful vertical milestone + +**M1: capability and genuine PCM contract.** Add/extend minimal canonical ChannelId input gain, EdgeId send level/ON/tap with saved doc schema, exact source/return staging, pre-fader after insert split, and accepted native graph snapshot; wire via existing transport/bridge. One integrated branch based on latest surviving in-scope PR (#606 includes #604 as of checkpoint); verify live refs first, do not overwrite another agent's head. + +**M2: contextual UI admission.** Reuse the current approved renderer and artwork from that branch, switch only relevant FX section contents, give SOF clear BUS target and accepted PRE/POST/ON state, re-enable controls only after actual native capability. MAIN fader, pinned MAIN, meter, WIRE and real plugin editor unchanged. No heavy additional layout system. + +**M3: focused qualification, then release gate.** Cross-check output with real PCM and .smix fixtures before one deliberate Windows milestone/FAT. This is *not* permission to perform heavy Windows/Chromium/installer builds on every docs or CSS tweak. Follow [fast feature playbook](architecture/FEATURE_EXTENSION_PLAYBOOK.md) and [smart CI runbook](SMART_CI_RUNNER_WORKFLOW.md). + +## 7. Specific fixture matrix + +1. **Gain order:** input 0, +6, negative gain, unity reset; capture -> gain -> real EQ/VST -> fader -> MAIN; clipping/headroom and mute; device reconnect, mono/stereo. Changing view must not reset FX state. +2. **Post-insert PRE:** deterministic nonlinear/known FX changes PRE sample as expected, while source channel fader at zero does not attenuate PRE; POST is silent. \`PRE_FX\` optional tap yields intentionally different PCM. Plugin processing is done once. +3. **PRE / POST + MUTE:** mute gates both under new behavior; explicit solo/monitor policies and intentional SOURCE ONLY remain correct, no leak into MAIN. +4. **Two simultaneous sends:** CH05 -> Monitor PRE and CH05 -> Reverb POST; only selected EdgeId changes; target change and bank swap do not retarget any audio. +5. **OFF / gain floor / remove:** send OFF and level floor silence PCM but retain EdgeId/settings; ON and fader restore. Only explicit Disconnect changes topology; primary route never converted/duplicated. Test from absent edge and primary-only path. +6. **Failure + concurrency:** stale revision/epoch, rapid gain drag, toggle+device restart, rejected invalid operation, late ACK, plugin open/close, graph retirement. No stale optimistic badge or callback allocation. +7. **Persistence:** .smix serializes ChannelId input gain and per-EdgeId tap/gain/enabled; legacy \`split\` migrates as PRE_FX, not silently PRE_FADER; optional UI mode does not become startup audio dependency. +8. **Viewport and genuine look:** assembled \`/preview/\` at 1366×768, 1680×900, 1920×1080 and relevant compact viewport; approved PNG visual states MUTE/SOLO/PRE/POST, native target context, equal-height sections, MASTER pinned, no new spinner/wizard, no console-wide idle repaint. +9. **Real external signal:** ASIO input -> input gain -> channel FX/VST3 -> PRE and POST bus -> verified outputs; secondary WASAPI/VB Cable independent; no unadmitted audio, hidden arming, or device takeover. +10. **Cost discipline:** docs-only = diff/links/contract checks, UI-only = cheap scripted smoke at milestones, PCM changes = unit and one deliberate exact-SHA native build, output/hardware changes = physical FAT; don't stack duplicate Windows runs. + +**Release rule:** The feature is not "DONE" on PR merge, green source assertions, GUI screenshot or browser smoke alone. It is DONE when its exact installed native PCM behavior and failure/recovery paths match PRD and are witnessed by the appropriate evidence tier. No public release claim without normal release qualification. + +## 8. Handoff instructions for the next thread + +1. Read root \`AGENTS.md\`, this ARD and [PRD](PRD_CONTEXTUAL_CONSOLE_GAIN_SOF_20261113.md), architecture map and actual current source. +2. Refresh live main, #604/#606 status/heads, compare changed paths, CI and earlier integrated work. Prefer latest survivor; #606 already includes #604 at this checkpoint. Do not reimplement the same code on main blindly or overwrite active SonKu/editor progress. +3. Deliver native end-to-end feature, not a larger design proposal; keep one authoritative ChannelId/EdgeId graph, one FX lease owner and one callback. +4. Document exactly what is REAL (GUI, logical-only, installed PCM, actual hardware) and what remains blocked. Use selective efficient tests; no unsupported "released" claim. From ba746d9b0ab36296cc2922bdbc23ad079a099703 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Fri, 13 Nov 2026 05:28:11 +0700 Subject: [PATCH 3/5] docs: promote contextual PRD/ARD into AGENTS next-thread entrypoint --- AGENTS.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 1d85d55be..9a9a1202c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,6 +6,12 @@ **ONLY approved/public/product GUI: https://masarray.github.io/arsonmix/preview/**. There must be ONE public preview, ONE actual rendered GUI, and ONE native Windows GUI. **/preview-v2/ is rejected**: do not display, promote, publish or base native design on it as a separate UI. Do not substitute another console from `web/index.html`, `web/mixer-layout.js`, `web/console-native.html`, PR #278 or old M3/V48 mock. **The JUCE ENGINE must stitch into the EXACT approved /preview/ GUI**, never redesign it. +## Binding contextual-console owner decision — 2026-11-13 + +**READ FIRST when working on input GAIN, FX RACK, Sends on Faders, PRE/POST, WIRE SEND, or related UI/PCM:** [Owner-approved Contextual Console PRD](docs/PRD_CONTEXTUAL_CONSOLE_GAIN_SOF_20261113.md) and [companion ARD](docs/ARD_CONTEXTUAL_CONSOLE_GAIN_SOF_20261113.md). These are **normative feature specifications** (not a claim the native DSP is already implemented); they supersede inconsistent older v5/MS5 contextual UI/tap descriptions for that scope. Preserve the exact single approved assembled `/preview/` mixer and hardware PNG/SVG styling; GAIN/FX RACK are one interlocked shared strip area, SOF is a target-specific fader-flip layout, and PRE/POST/ON/level belong to the selected **EdgeId**. PRE_FADER (post-insert) is NOT legacy PRE_FX. SOF minimum/OFF never deletes WIRE; no auto-patching. Real native controls require installed PCM ACK/readback. + +**2026-11-13 implementation starting point:** at that checkpoint [#604](https://github.com/masarray/arsonmix/pull/604) was a browser reference UI draft and [#606](https://github.com/masarray/arsonmix/pull/606) was the more advanced in-scope integration draft **including #604** and SonKu. Refresh live main and PR heads first; reconcile the most advanced source without reimplementing it, losing plugin/editor work, or double-merging. Harmonice is the **vocal FX plugin**, not the mixer name. Do not schedule Windows builds for specification-only changes. + ## Long-term maintainability execution — 2026-11-11 For real source ownership and future feature-extension work, read [Current Architecture](docs/architecture/README.md), [Maintainability Execution Blueprint](docs/architecture/MAINTAINABILITY_EXECUTION_V1_20261111.md), and [Fast Feature Playbook](docs/architecture/FEATURE_EXTENSION_PLAYBOOK.md). A [ready-to-copy next-thread implementation prompt](docs/architecture/NEXT_THREAD_EXECUTION_PROMPT.md) begins coding M1 instead of repeating architecture research. [Issue #527](https://github.com/masarray/arsonmix/issues/527) tracks progress. These are implementation aids, NOT an extra coordination gate or an override of the approved /preview/, single native PCM callback, hard RT/audio safety, owner-authorized smart CI, or physical FAT rules. Keep the plan updated after proven source changes; do not create a new high-level plan instead of shipping a testable milestone. From 2e9684bb01ec55d5194014c2daf031042aade704 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Fri, 13 Nov 2026 05:28:30 +0700 Subject: [PATCH 4/5] docs: link historical v5 PRD to approved contextual spec --- docs/PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md b/docs/PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md index 76c573f5a..fbbf27475 100644 --- a/docs/PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md +++ b/docs/PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md @@ -1,3 +1,5 @@ +> **OWNER-APPROVED 2026-11-13 CONTEXTUAL-CONSOLE PRD ADDENDUM:** For the current GAIN/FX RACK interlock, Sends on Faders, PRE/POST per EdgeId, SEND ON/OFF and user workflow, read [Contextual Console PRD](PRD_CONTEXTUAL_CONSOLE_GAIN_SOF_20261113.md) and its [ARD](ARD_CONTEXTUAL_CONSOLE_GAIN_SOF_20261113.md) first. Those scoped requirements override conflicting historical descriptions below, without replacing native/audio/WIRE safety rules. Status = specification, **not** native implementation proof. + > **FINAL 2026-11-04 GUI REPLACEMENT:** All GUI authority in this historical document is superseded by **https://masarray.github.io/arsonmix/preview/** (the only approved GUI, including its approved PNG button variant). Bare `/preview-v2/` is rejected. Only one public preview (redirect old URLs), one JUCE GUI, one native PCM graph. Read [single handoff](workstreams/HANDOFF_APPROVED_PREVIEW_V2_NATIVE_20261104.md) and root AGENTS.md. Older native DSP/safety/ABI/Show/FAT constraints remain valid. GUI work #389, engine #266/#387, FAT #270. # ArSonMix PRD v5.2 — Operator-First Live Mixer Console From 20310633002d13d4926c7e7518c93e70626dd11f Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Fri, 13 Nov 2026 05:28:33 +0700 Subject: [PATCH 5/5] docs: link historical v5 ARD to approved contextual spec --- docs/ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md b/docs/ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md index 6d9010205..4a83229ca 100644 --- a/docs/ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md +++ b/docs/ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md @@ -1,3 +1,5 @@ +> **OWNER-APPROVED 2026-11-13 CONTEXTUAL-CONSOLE ARD ADDENDUM:** For GAIN/FX RACK, SOF, post-insert PRE_FADER (distinct from PRE_FX), per-send EdgeId/tap/level/ON and PCM/ACK requirements, read [Contextual Console ARD](ARD_CONTEXTUAL_CONSOLE_GAIN_SOF_20261113.md) and [PRD](PRD_CONTEXTUAL_CONSOLE_GAIN_SOF_20261113.md) first. Those scoped requirements override conflicting historical sections below; single callback, real PCM, existing WIRE/device/VST3 safety remain binding. Specification **does not** establish native qualification. + > **FINAL 2026-11-04 GUI REPLACEMENT:** All GUI authority in this historical document is superseded by **https://masarray.github.io/arsonmix/preview/** (the only approved GUI, including its approved PNG button variant). Bare `/preview-v2/` is rejected. Only one public preview (redirect old URLs), one JUCE GUI, one native PCM graph. Read [single handoff](workstreams/HANDOFF_APPROVED_PREVIEW_V2_NATIVE_20261104.md) and root AGENTS.md. Older native DSP/safety/ABI/Show/FAT constraints remain valid. GUI work #389, engine #266/#387, FAT #270. # ArSonMix ARD v5.2 — Universal Realtime Mixer Graph + Operator-First Console