Skip to content
107 changes: 50 additions & 57 deletions docs/HARMONICE_PHYSICAL_KEYS_SOF_CONTRACT.md
Original file line number Diff line number Diff line change
@@ -1,64 +1,57 @@
# Harmonice v9 physical MUTE / SOLO / PFL — SOF integration contract
# Approved v9 MUTE / SOLO / PFL hardware keys — MAIN MIX and SOF

## Artwork provenance and nonnegotiable look
**Owner correction — 13 November 2026.** This contract supersedes the
previous PR #610 rule that put PRE/POST in the Main Mix third-key position.
That caused the user-visible regression: PFL appeared only in SOF. The
operator-approved v9 physical key row is MUTE / SOLO / PFL in the normal
mixer **and** in Sends on Faders.

Use the user's approved **Harmonice_Thin_Flat_Bezel_v9_PFL_FontMatched_Assets.zip**.
The blue PFL PNG master has the same thin flat bezel, cap geometry, typography
and ON text debossing as the v9 MUTE/SOLO faces. Do not recreate it in CSS/SVG.
## Approved PNG, unchanged

- Existing production 4×3, 57×30-per-cell MUTE/SOLO/PRE/POST atlas remains
**exactly unchanged**:
`site/preview-buttons/assets/harmonice-thin-flat-v9-approved-off-shadow-57x30.png`.
- New approved **PFL OFF / PFL ON** raster is a separate 2×1 114×30 RGBA atlas:
`site/preview-buttons/assets/harmonice-thin-flat-v9-pfl-font-matched-57x30.png`.
- Original MUTE/SOLO/PRE/POST 228 x 90 approved asset remains byte-identical:
`site/preview-buttons/assets/harmonice-thin-flat-v9-approved-off-shadow-57x30.png`
- Approved 114 x 30 PFL OFF/ON FontMatched RGBA sprite remains byte-identical:
`site/preview-buttons/assets/harmonice-thin-flat-v9-pfl-font-matched-57x30.png`
- PFL sprite SHA256: `1ede18534fa678461ebcb1a100a61170700d75048b11607600cf09d9de8872fd`.
- Display through the same `mixer-control-keys.css` and existing
`strip(t)` renderer; the artwork remains PNG, never a CSS imitation.
- PFL OFF inherits the two approved v9 lower-alpha drop shadows; PFL ON does
**not** inherit OFF shadow. Neither frame alters button hitbox/strip height.
- The sole physical key owner is `mixer-control-keys.css`; no CSS substitute
for PNG, new glow, new button geometry, independent renderer, or extra skin.

## One workspace decides the third physical key
## Physical key row

| Context | Source audio strip | BUS/FX strip | MASTER |
| Workspace | Audio | BUS / FX | MASTER |
| --- | --- | --- | --- |
| MAIN MIX | MUTE, SOLO, PRE/POST | MUTE, SOLO, PRE/POST | MUTE, SOLO |
| SOF | **MUTE, SOLO, PFL** | MUTE, SOLO | MUTE, SOLO |

PFL is **not** a replacement for PRE/POST routing. In SOF, the selected
send's PRE/POST belongs in the contextual **FX/send processing panel** (PR
#604); its hardware key row uses PFL. The PFL key does not change the
SOF target's send tap/gain or the channel's PRIMARY MAIN edge.

## Monitoring and state contract

- Browser reference: PFL uses the existing per-channel `cue` state, purely
as visual feedback. The browser generates no real monitored audio and
**must not feed cue into MAIN**. PFL is initially OFF.
- Leaving SOF clears browser-only PFL requests; there must be no invisible
armed cue. Normal MUTE/SOLO survive workspace changes.
- Native: PFL is disabled / visibly OFF until a separate pre-fader MONITOR
L/R bus has a real native route and ACK/readback. The existing native
bridge `consumeAction('cue')` fails closed; the button must never simulate
monitor audio or claim native availability.
- Native SOF itself remains unavailable until native send gain/tap support is
admitted. This PR does **not** implement an audio PCM audition bus.

## Concurrent work: draft PR #604

**Do not overwrite or independently merge #604's experimental SOF branch.**
The SOF author must forward-port the third-key decision from `strip(t)`:
`sofPfl = sofEnabled && t.kind==='audio'`, `hasTap = t.kind!=='master' &&
!sofEnabled`. When SOF is active, preserve PFL in the MUTE/SOLO key row
and keep per-EdgeId PRE/POST in the contextual SOF panel. Preserve the one
existing key CSS owner, both approved raster sprites and native fail-closed
behavior. Do not restore PFL into MAIN MIX or the hidden Clear PFL toolbar.

## Regression evidence

- Fast `tests/harmonice_v7_keys_contract.py` checks SHA, dimensions, the
existing MUTE/SOLO sprite, renderer contracts and native guard.
- Existing Chromium Stage D checks both contexts, PFL OFF→ON without layout
changes, actual sprite URL/frame/shadow, no MASTER PFL, and reset on exiting
SOF. It does not assert any native PCM audio.
- Publish only the single `/preview/` GUI; `/preview-prod/` is a frozen
pre-v7 comparison and must remain unchanged.
| Main Mix (default) | MUTE / SOLO / **PFL** | MUTE / SOLO / **PFL** | MUTE / SOLO |
| Sends on Faders | MUTE / SOLO / **PFL** | MUTE / SOLO / **PFL** | MUTE / SOLO |

PFL is not a PRE/POST send tap. The Main Mix no longer installs a global
channel `tapMode` button that can unintentionally retarget *all* parallel
send edges. Send PRE/POST is a **per-EdgeId** routing control in the existing
WIRE Route Inspector; in the contextual SOF implementation (#604 included by
advanced #606), it belongs in the selected target's SEND CONTROLS section.
That experimental branch needs this v9 main-key change forward-ported
before integration; do not merge it over the approved current main.

The existing WIRE connection mode selector and per-edge tap controls remain.
Neither PFL nor switching workspaces may create, remove, or retarget WIRE.

## Truthful audio status

- Browser-only `cue` is a visual selection, **not audio**. Clicking PFL can
illuminate the exact approved blue PNG, but it does not alter MAIN,
send topology, faders, MUTE/SOLO, or monitoring sound.
- PFL is visible in both workspaces and its browser selection must survive
Main Mix <-> SOF changes; there is no hidden stale cue request.
- Native JUCE/WebView2: PFL must be visibly OFF/disabled until a genuinely
admitted independent pre-fader MONITOR L/R path has an engine ACK/readback.
Native bridge `consumeAction('cue')` already fails closed.
- This change is a GUI correction only, not a claim of native PFL audio,
Windows/ASIO FAT, or complete native SOF.

## Tests and publishing

The source/raster contract, the Stage D Chromium browser smoke, public
Pages PNG/WIRE browser smoke, and archive contract must check third-key PFL
in **default Main Mix before any SOF click**, then after SOF toggle, and the
MASTER-only two-key row. Original approved PNG hashes, PFL OFF shadows,
blue PFL ON, ON/OFF hitboxes, and WIRE per-edge controls are protected.
Publish only the assembled `/preview/`; historical `/preview-prod/` remains frozen.
19 changes: 18 additions & 1 deletion site/preview-buttons/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
# Approved PNG hardware keys — internal build dependency

This directory owns **only** the approved MUTE/SOLO/PRE/POST assets:
This directory owns the approved MUTE/SOLO/PRE/POST historical atlas and PFL FontMatched extension:
- `assets/harmonice-thin-flat-v9-approved-off-shadow-57x30.png`
- `assets/harmonice-thin-flat-v9-pfl-font-matched-57x30.png`
- `assets/mixer-control-keys.css`
- `assets/mixer-control-keys.js`

Expand All @@ -22,3 +23,19 @@ No outgoing parallel SEND: POST is rendered as a **non-illuminated graphite PNG*
## Harmonice v9 refined — approved physical OFF-only shadow

The authoritative raster is `assets/harmonice-thin-flat-v9-approved-off-shadow-57x30.png`, a 228×90 RGBA atlas built pixel-for-pixel from the **57×30 1× images embedded in** the user-approved `Harmonice_Thin_Flat_Bezel_v9_Refined_OFF_Shadow_Interactive_AB.html`. Frame mapping (4 columns × 3 rows) is unchanged from v8. The stylesheet adds only the exact two transparent alpha `drop-shadow` layers from the approved A/B HTML to OFF faces: MUTE OFF, SOLO OFF, PRE OFF. ON faces, POST idle/active and MIX get no added shadow. Outer bezel, cap, wording, scaling, alpha, glyphs, and device/routing behavior stay untouched. The shadow is painted on the raster `::before` alpha, not the clickable hitbox; PFL remains hidden and `/preview-prod/` remains the old historical archive.

## Current owner correction — 13 November 2026

The historical v7/v8/v9 PRE/POST row and hidden-PFL description above
documents **earlier designs**, not the current product behavior. PR #610
mistakenly limited approved PFL to SOF, leaving PRE/POST as the Main Mix third
button. This is superseded.

**Main Mix and SOF now display approved v9 MUTE / SOLO / PFL** on every
non-MASTER channel. MASTER retains MUTE/SOLO. The channel-global tap button
is removed; send PRE/POST remains available per EdgeId in the WIRE Route
Inspector, and belongs in the contextual SOF SEND CONTROLS under work in
#604/#606. PFL is still reference-only in a browser and disabled on native
until MONITOR L/R routing is truly admitted. PFL selection persists when
switching between Main Mix and SOF. The PNG originals are unchanged.
See `docs/HARMONICE_PHYSICAL_KEYS_SOF_CONTRACT.md`.
63 changes: 10 additions & 53 deletions site/preview-v2/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -698,38 +698,17 @@
code+=sectionFx(t)+sectionSend(t);
code+='<div class="section pan-section"><span class="pan-icon" title="Pan / Balance">PAN</span><span class="pan-control '+(t.pan===0?'is-centered':'')+'" style="'+panStyle(t.pan)+'"><input class="center-pan" type="range" min="-100" max="100" step="1" value="'+t.pan+'" data-field="pan" title="PAN center detent: capture ±7, hold ±12; release snaps center; double-click resets" aria-label="Channel pan; center detent" aria-valuetext="'+(t.pan===0?'Center':t.pan<0?'Left '+Math.abs(t.pan):'Right '+t.pan)+'"></span><output>'+panLabel(t.pan)+'</output></div>';

// PRE/POST describes the source channel's outgoing parallel WIRE sends
// only. A direct MAIN wire is not a PRE/POST send and cannot light this key.
const parallelSends=wireEdges.filter(e=>e.enabled&&e.sourceId===t.id&&e.kind==='send'&&e.destId!==master.id);
const allSendPost=parallelSends.length>0&&parallelSends.every(e=>e.mode==='send');
const allSendPre=parallelSends.length>0&&parallelSends.every(e=>e.mode==='split');
const tapMode=allSendPost?'send':allSendPre?'split':parallelSends.length?'mixed':t.wireTapMode==='split'?'split':'send';
const nativeTapUnavailable=!!window.__JUCE__?.backend;
// An unpatched channel has a future WIRE default, not an illuminated send.
// Four dedicated PNG frames avoid CSS-faked lighting: PRE, POST idle, POST
// routed, MIX (several outgoing SEND edges with different tap positions).
const tapVisual=nativeTapUnavailable?'idle':
parallelSends.length===0?(tapMode==='split'?'pre':'idle'):
tapMode==='mixed'?'mixed':tapMode==='split'?'pre':'post';
const tapText=tapVisual==='mixed'?'MIX':tapVisual==='pre'?'PRE':'POST';
const tapTitle=nativeTapUnavailable?'PRE/POST unavailable until native WIRE tap ACK; routing unchanged':
!parallelSends.length?'No parallel sends · '+(tapMode==='split'?'PRE':'POST')+
' is only the future WIRE default; primary MAIN unchanged':
tapMode==='mixed'?'Mixed PRE and POST parallel WIRE sends · click to set all POST':
(tapMode==='send'?'POST follows channel fader':'PRE independent before FX')+
' · '+parallelSends.length+' outgoing parallel SEND(s), primary MAIN unchanged';
// Shared v9 physical keys: MUTE/SOLO in both contexts, PFL only in SOF
// audio channels. PRE/POST remains the normal MAIN MIX routing control.
const sofPfl=sofEnabled&&t.kind==='audio';
const hasTap=t.kind!=='master'&&!sofEnabled;
// Approved v9 physical row: MUTE / SOLO / PFL on every non-MASTER strip
// in MAIN MIX and SOF. Send tap belongs to the selected WIRE EdgeId
// inspector (and the contextual SOF send panel), never this key row.
const showPfl=t.kind!=='master';
const isNative=!!window.__JUCE__?.backend;
const pflTitle=isNative?'PFL unavailable · independent native MONITOR L/R not admitted':
'PFL · visual audition request only; no monitoring audio in browser preview';
code+='<div class="section switch-section mx-hw-row" role="group" data-tap-applicable="'+hasTap+'" data-pfl-applicable="'+sofPfl+'" aria-label="Channel Mute Solo'+(sofPfl?' and PFL':hasTap?' and PRE/POST':'')+'">'
code+='<div class="section switch-section mx-hw-row" role="group" data-tap-applicable="false" data-pfl-applicable="'+showPfl+'" aria-label="Channel Mute Solo'+(showPfl?' and PFL':'')+'">'
+'<button type="button" class="mx-hw-key" data-hw-kind="mute" data-action="mute" title="Mute channel" aria-label="Mute channel" aria-pressed="'+t.mute+'"><span class="mx-hw-fallback">MUTE</span></button>'
+'<button type="button" class="mx-hw-key" data-hw-kind="solo" data-action="solo" title="Solo channel" aria-label="Solo channel" aria-pressed="'+t.solo+'"><span class="mx-hw-fallback">SOLO</span></button>';
if(hasTap)code+='<button type="button" class="mx-hw-key" data-hw-kind="tap" data-action="tapMode" data-tap-visual="'+tapVisual+'" title="'+escapeHtml(tapTitle)+'" aria-label="'+escapeHtml(t.name+' '+tapTitle)+'" aria-pressed="'+(tapMode==='mixed'&&!nativeTapUnavailable?'mixed':Boolean(parallelSends.length&&tapMode==='send'&&!nativeTapUnavailable))+'" '+(nativeTapUnavailable?'disabled':'')+'><span class="mx-hw-fallback">'+tapText+'</span></button>';
if(sofPfl)code+='<button type="button" class="mx-hw-key" data-hw-kind="pfl" data-action="cue" title="'+escapeHtml(pflTitle)+'" aria-label="'+escapeHtml(t.name+' '+pflTitle)+'" aria-pressed="'+Boolean(t.cue&&!isNative)+'" '+(isNative?'disabled':'')+'><span class="mx-hw-fallback">PFL</span></button>';
if(showPfl)code+='<button type="button" class="mx-hw-key" data-hw-kind="pfl" data-action="cue" title="'+escapeHtml(pflTitle)+'" aria-label="'+escapeHtml(t.name+' '+pflTitle)+'" aria-pressed="'+Boolean(t.cue&&!isNative)+'" '+(isNative?'disabled':'')+'><span class="mx-hw-fallback">PFL</span></button>';
code+='</div>';
code+=sectionFader(t);
code+='<div class="bottom-section"><div class="db-value">'+(sofEnabled&&t.kind==='audio'?'S ': '')+formatDb(sofEnabled&&t.kind==='audio'?getSofLevel(t):t.level)+'</div><div class="footer-label '+(t.kind==='master'?'master-label':t.kind==='bus'?'bus-label':'')+'"><span class="name" data-action="rename" title="Double-click to edit name, icon and color · F2" tabindex="0" role="button">'+escapeHtml(t.name)+'</span><span class="footer-icon" aria-hidden="true">'+escapeHtml(iconFor(t))+'</span><div class="color-strip"></div></div></div></article>';
Expand Down Expand Up @@ -838,8 +817,8 @@
function toggleSof(force){
sofEnabled=typeof force==='boolean'?force:!sofEnabled;
if(sofEnabled&&!sofTarget){sofEnabled=false;say('Create a Bus or FX Return to use Sends on Faders');return;}
// Don't leave a hidden browser-only PFL request armed outside SOF.
if(!sofEnabled){tracks.forEach(channel=>{channel.cue=false;});master.cue=false;}
// PFL is visible in both workspaces; changing fader context must not
// silently clear the channel's browser-only cue selection.
const btn=document.getElementById('sofToggle');btn.classList.toggle('active',sofEnabled);
btn.setAttribute('aria-pressed',String(sofEnabled));document.querySelector('.console-body').classList.toggle('sends-mode',sofEnabled);
render();say(sofEnabled?'SENDS ON FADERS: adjusting '+sofTarget+' send levels · main faders protected':'MAIN MIX: faders control primary channel level');
Expand Down Expand Up @@ -2042,36 +2021,14 @@
if(a==='openPlugin'){openFastPicker(t,Number(btn.dataset.slot),btn);return;}
if(a==='removeFx'){if(deferNativeFxIntent('Remove FX insert'))return;const i=Number(btn.dataset.slot);t.fx[i]='None';t.slotBypass[i]=false;if(t.fxInsertIds)t.fxInsertIds[i]=null;fxReorderUndo=null;refreshStrip(t);say(t.name+' · cleared FX insert '+(i+1));return;}
if(a==='slotPower'){if(deferNativeFxIntent('FX insert bypass'))return;const slot=Number(btn.dataset.slot);if(t.fx[slot]==='None'){say(t.name+': choose an effect before toggling bypass');return;}t.slotBypass[slot]=!t.slotBypass[slot];refreshStrip(t);say(t.name+': FX '+(slot+1)+(t.slotBypass[slot]?' bypassed':' enabled'));return;}
if(a==='tapMode'){
if(t.kind==='master')return;
// PRE/POST is a structural native DSP tap change, NOT a cosmetic button.
// The current native bridge rejects MODE without verified PCM ACK. Never
// alter the local presentation in native mode until that capability exists.
if(window.__JUCE__?.backend){
say('PRE/POST is unavailable for this native graph · routing unchanged');
return;
}
const sends=wireEdges.filter(edge=>edge.enabled&&edge.sourceId===t.id&&edge.kind==='send'&&edge.destId!==master.id);
// Mixed taps resolve predictably to POST on first click; next click selects PRE.
const allPost=sends.length>0&&sends.every(edge=>edge.mode==='send');
const next=sends.length?(allPost?'split':'send'):(t.wireTapMode==='split'?'send':'split');
if(sends.length&&!wireGraphCommit(sends.map(edge=>({type:'MODE',sourceId:t.id,edgeId:edge.id,mode:next}))))return;
t.wireTapMode=next;
if(wireSourceId===t.id){wireMode=next;document.getElementById('wireMode').value=next;}
refreshStrip(t);selectTrack(t);
say(t.name+' '+(next==='split'?'PRE (independent pre-FX)':'POST (follow fader)')+
' · outgoing parallel WIRE sends '+(sends.length?'updated':'default selected')+
' · primary MAIN unchanged · GUI reference only');
return;
}
if(a==='eq')t.eq=!t.eq;
else if(a==='fxOn'){if(deferNativeFxIntent('FX chain bypass'))return;t.fxOn=!t.fxOn;}
else if(a==='pre'){t.pre=!t.pre;syncActiveSend(t);}
else if(a==='sendOn'){say('Legacy SEND disabled; patch via WIRE');return;}
else if(a==='cue'){
// Only a browser-reference cue selection; never route to MAIN/audio.
if(!sofEnabled||t.kind!=='audio'||window.__JUCE__?.backend){
say('PFL requires SOF and an admitted independent native monitor');
if(t.kind==='master'||window.__JUCE__?.backend){
say('PFL requires an admitted independent native monitor');
return;
}
t.cue=!t.cue;
Expand Down
Loading
Loading