Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 64 additions & 0 deletions docs/HARMONICE_PHYSICAL_KEYS_SOF_CONTRACT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# Harmonice v9 physical MUTE / SOLO / PFL — SOF integration contract

## Artwork provenance and nonnegotiable look

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.

- 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`.
- 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.

## One workspace decides the third physical key

| Context | Source audio strip | BUS/FX strip | 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.
3 changes: 2 additions & 1 deletion scripts/build_pages.py
Original file line number Diff line number Diff line change
Expand Up @@ -56,11 +56,12 @@
canonical_html=(canonical/'index.html').read_text(encoding='utf-8')
special=('mixer-control-keys.css','mixer-control-keys.js')
sprite='harmonice-thin-flat-v9-approved-off-shadow-57x30.png'
pfl_sprite='harmonice-thin-flat-v9-pfl-font-matched-57x30.png'
for src in sorted((canonical/'assets').iterdir()):
if not src.is_file(): raise SystemExit('Unexpected nested preview-v2 asset: '+str(src))
if src.name not in special:
shutil.copy2(src,buttons_dest/'assets'/src.name)
for name in (*special,sprite):
for name in (*special,sprite,pfl_sprite):
src=buttons_source/name
if not src.is_file(): raise SystemExit('Approved PNG asset missing: '+str(src))
shutil.copy2(src,buttons_dest/'assets'/name)
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
13 changes: 12 additions & 1 deletion site/preview-buttons/assets/mixer-control-keys.css
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
border-bottom:1px solid #415463!important;
box-shadow:inset 0 1px 0 #ffffff0a!important;
}
.app .console-body .strip .mx-hw-row[data-tap-applicable="false"]{
.app .console-body .strip .mx-hw-row[data-tap-applicable="false"]:not([data-pfl-applicable="true"]){
grid-template-columns:repeat(2,minmax(0,33%))!important;
justify-content:center!important;
}
Expand Down Expand Up @@ -89,13 +89,24 @@
.app .console-body .strip .mx-hw-row>button.mx-hw-key[data-hw-kind="tap"][data-tap-visual="idle"]{--mx-native-x:33.333333%}
.app .console-body .strip .mx-hw-row>button.mx-hw-key[data-hw-kind="tap"][data-tap-visual="post"]{--mx-native-x:66.666667%}
.app .console-body .strip .mx-hw-row>button.mx-hw-key[data-hw-kind="tap"][data-tap-visual="mixed"]{--mx-native-x:100%}
/* Approved v9 PFL FontMatched source: physical 57x30 OFF + ON PNGs.
Two frames are a separate extension to the original MUTE/SOLO/tap atlas:
no repaint or reallocation of any previously approved control. */
.app .console-body .strip .mx-hw-row>button.mx-hw-key[data-hw-kind="pfl"]::before{
background-image:url("harmonice-thin-flat-v9-pfl-font-matched-57x30.png")!important;
background-size:200% 100%!important;
background-position:var(--mx-native-x,0%) 0%!important;
}
.app .console-body .strip .mx-hw-row>button.mx-hw-key[data-hw-kind="pfl"][aria-pressed="true"]{--mx-native-x:100%}
.app .console-body .strip .mx-hw-row>button.mx-hw-key[data-hw-kind="pfl"][aria-pressed="false"]{--mx-native-x:0%}
/* Approved v9 HTML, physical 1x: --shadow-u:1px.
Exactly the two OFF-only alpha drop-shadow layers from the signed-off
Harmonice_Thin_Flat_Bezel_v9_Refined_OFF_Shadow_Interactive_AB.html.
Shadow lives on the raster pseudo-element (alpha contour); never on
the clickable box or ON face. No artwork repaint or geometry change. */
.app .console-body .strip .mx-hw-row>button.mx-hw-key[data-hw-kind="mute"][aria-pressed="false"]::before,
.app .console-body .strip .mx-hw-row>button.mx-hw-key[data-hw-kind="solo"][aria-pressed="false"]::before,
.app .console-body .strip .mx-hw-row>button.mx-hw-key[data-hw-kind="pfl"][aria-pressed="false"]::before,
.app .console-body .strip .mx-hw-row>button.mx-hw-key[data-hw-kind="tap"][data-tap-visual="pre"]::before{
filter:
drop-shadow(0 .8px 1.15px rgba(0,0,0,.42))
Expand Down
27 changes: 24 additions & 3 deletions site/preview-v2/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -718,10 +718,18 @@
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';
code+='<div class="section switch-section mx-hw-row" role="group" data-tap-applicable="'+(t.kind!=='master')+'" aria-label="Channel Mute Solo'+(t.kind==='master'?'':' and PRE/POST')+'">'
// 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;
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':'')+'">'
+'<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(t.kind!=='master')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(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>';
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 @@ -830,6 +838,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;}
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 @@ -2058,7 +2068,18 @@
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(['mute','solo','cue','mon','phase'].includes(a)){
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');
return;
}
t.cue=!t.cue;
refreshStrip(t);
say(t.name+' PFL '+(t.cue?'selected':'cleared')+' · visual reference only; no monitor audio');
return;
}
else if(['mute','solo','mon','phase'].includes(a)){
t[a]=!t[a];
if(t.group&&(a==='mute'||a==='solo')){
tracks.filter(other=>other.group===t.group&&other.id!==t.id).forEach(other=>{other[a]=t[a];refreshStrip(other);});
Expand Down
37 changes: 37 additions & 0 deletions tests/approved_css_stage_d_single_bundle_smoke.py
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,43 @@ async def main():
assert await key.get_attribute("aria-pressed") == "true"
on_filter=await key.evaluate("(e)=>getComputedStyle(e,'::before').filter")
assert on_filter=="none","MUTE ON must not inherit raised OFF shadow: "+on_filter
if size[0]==1680:
# Real SOF toolbar workflow; no private graph API or
# alternate renderer. Verify the exact user-approved PFL
# raster, OFF alpha shadow, ON image and workspace isolation.
await page.locator("#sofToggle").click()
row=page.locator("#tracks .strip[data-id='1'] .mx-hw-row")
assert await row.locator("button.mx-hw-key").count()==3
assert await row.locator("[data-hw-kind='mute']").count()==1
assert await row.locator("[data-hw-kind='solo']").count()==1
assert await row.locator("[data-hw-kind='tap']").count()==0
pfl=row.locator("[data-hw-kind='pfl']")
assert await pfl.count()==1
assert await pfl.get_attribute("aria-pressed")=="false"
off_pfl=await pfl.evaluate("""el=>({
image:getComputedStyle(el,'::before').backgroundImage,
position:getComputedStyle(el,'::before').backgroundPosition,
shadow:getComputedStyle(el,'::before').filter
})""")
assert "harmonice-thin-flat-v9-pfl-font-matched-57x30.png" in off_pfl["image"]
assert off_pfl["position"].startswith("0%"),off_pfl
assert "drop-shadow(" in off_pfl["shadow"],off_pfl
assert await page.locator("#master [data-hw-kind='pfl']").count()==0
await pfl.click()
assert await pfl.get_attribute("aria-pressed")=="true"
on_pfl=await pfl.evaluate("""el=>({
position:getComputedStyle(el,'::before').backgroundPosition,
shadow:getComputedStyle(el,'::before').filter
})""")
assert on_pfl["position"].startswith("100%"),on_pfl
assert on_pfl["shadow"]=="none",on_pfl
# Hidden PFL requests cannot survive leaving SOF.
await page.locator("#sofToggle").click()
assert await page.locator("#tracks [data-hw-kind='pfl']").count()==0
assert await page.locator("#tracks .strip[data-id='1'] [data-hw-kind='tap']").count()==1
await page.locator("#sofToggle").click()
assert await page.locator("#tracks .strip[data-id='1'] [data-hw-kind='pfl']").get_attribute("aria-pressed")=="false"
await page.locator("#sofToggle").click()
assert len(css_requests) == 1, (size,css_requests)
await page.close()
print("PASS Stage D one stylesheet / 17 requests eliminated:",
Expand Down
26 changes: 25 additions & 1 deletion tests/harmonice_v7_keys_contract.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
"""Harmonice v9 approved PNG button integration — fast source/asset guard.

Tests one owner, physical PNG, PFL hidden (not deleted), atomic reference tap
Tests one owner, physical PNG, PFL only in SOF (not main), atomic reference tap
transactions and native fail-closed behavior. This is NOT hardware PCM proof.
"""
from pathlib import Path
Expand Down Expand Up @@ -55,6 +55,30 @@ def test_reference_prepost_atomic_and_main_independent(self):
self.assertIn("if(t.kind!=='master')code+='<button", HTML)
self.assertIn("const next=sends.length?(allPost?'split':'send')", HTML)\n self.assertIn("data-tap-visual", HTML)\n self.assertIn("tapVisual=nativeTapUnavailable?'idle'", HTML)\n self.assertIn("parallelSends.length===0?(tapMode==='split'?'pre':'idle')", HTML)\n self.assertIn("tapMode==='mixed'?'mixed'", HTML)\n self.assertIn('data-tap-applicable="', HTML)

def test_approved_pfl_fontmatched_png_and_sof_scope(self):
pfl = "harmonice-thin-flat-v9-pfl-font-matched-57x30.png"
png = (OWNER / pfl).read_bytes()
self.assertEqual(png[:8], bytes.fromhex("89504e470d0a1a0a"))
self.assertEqual(struct.unpack(">II", png[16:24]), (114, 30))
self.assertEqual(png[25], 6, "PFL must retain the approved true RGBA transparency")
self.assertEqual(hashlib.sha256(png).hexdigest(),
"1ede18534fa678461ebcb1a100a61170700d75048b11607600cf09d9de8872fd",
"PFL-ON glyph and alpha must stay byte-for-byte user-approved")
self.assertIn("pfl_sprite='" + pfl + "'", BUILD)
self.assertIn("for name in (*special,sprite,pfl_sprite):", BUILD)
self.assertIn('background-image:url("' + pfl + '")', CSS)
self.assertIn("background-size:200% 100%", CSS)
self.assertIn('[data-hw-kind="pfl"][aria-pressed="true"]', CSS)
self.assertIn('[data-hw-kind="pfl"][aria-pressed="false"]::before', CSS)
self.assertIn("const sofPfl=sofEnabled&&t.kind==='audio'", HTML)
self.assertIn("const hasTap=t.kind!=='master'&&!sofEnabled", HTML)
self.assertIn('if(sofPfl)code+=', HTML)
self.assertIn('data-action="cue"', HTML)
self.assertIn("t.cue=!t.cue", HTML)
self.assertIn("if(!sofEnabled){tracks.forEach(channel=>{channel.cue=false;});master.cue=false;}", HTML)
self.assertIn("PFL requires a separate MONITOR L/R pair", BRIDGE)
self.assertIn("if(!sofEnabled||t.kind!=='audio'||window.__JUCE__?.backend)", HTML)

def test_native_pcm_never_fakes_prepost_state(self):
self.assertIn('if(action==="tapMode"){', BRIDGE)
self.assertIn('routing unchanged', BRIDGE)
Expand Down
2 changes: 1 addition & 1 deletion tests/pages_png_buttons_wire_reconciliation_smoke.py
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ def verify_bundle(dist):
# byte identity against this build's generated public root, not unrelated
# developer-local files or an older locked GUI reference.
favicons={"favicon.ico","favicon-16x16.png","favicon-32x32.png"}
expected=canonical|{SPRITE,"arsonmix-approved-runtime.css"}|favicons
expected=canonical|{SPRITE,"harmonice-thin-flat-v9-pfl-font-matched-57x30.png","arsonmix-approved-runtime.css"}|favicons
assert published==expected,("asset set drift",published^expected)
for name in favicons:
assert (generated/"assets"/name).read_bytes()==(dist/name).read_bytes(),name
Expand Down
Loading