diff --git a/.github/workflows/sonku-p72-native-xyz.yml b/.github/workflows/sonku-p72-native-xyz.yml index 46d3ab14e..7c2f38064 100644 --- a/.github/workflows/sonku-p72-native-xyz.yml +++ b/.github/workflows/sonku-p72-native-xyz.yml @@ -8,6 +8,10 @@ on: - 'engine/builtin_fx/SonKuSpatialProcessor.h' - 'engine/builtin_fx/sonku/**' - 'tests/sonku_p72_*' + - 'src/SonKuNativeBridgeContract.h' + - 'site/preview-v2/assets/mixer-native-sonku.js' + - 'tests/sonku_p73_*' + - 'tests/native_peq_assembly_test.py' - 'CMakeLists.txt' - '.github/workflows/sonku-p72-native-xyz.yml' permissions: @@ -31,6 +35,12 @@ jobs: run: | test "$(git rev-parse HEAD)" = "$EXPECTED" echo "SONKU_P72_EXACT_SHA=$EXPECTED" + - name: P7.3 JS grammar, actual geometry/capability and bridge regression + run: | + set -euo pipefail + node --check site/preview-v2/assets/mixer-native-sonku.js + node tests/sonku_p73_gui_contract_test.js + python -m unittest discover -s tests -p native_peq_assembly_test.py - name: Compile and execute original default native PCM contracts run: | set -euo pipefail diff --git a/docs/SONKU_P73_NATIVE_GUI_BRIDGE_CONTRACT_20261114.md b/docs/SONKU_P73_NATIVE_GUI_BRIDGE_CONTRACT_20261114.md new file mode 100644 index 000000000..bbbdaa3c0 --- /dev/null +++ b/docs/SONKU_P73_NATIVE_GUI_BRIDGE_CONTRACT_20261114.md @@ -0,0 +1,59 @@ +# SonKu P7.3 — native GUI/bridge contract research milestone +Date: 14 November 2026 | stacked P7.3 → #685 (P7.2) → #681 (P7.1) + +## Scope / actual implementation + +The existing `src/Main.cpp` SonKu native action dispatcher now delegates both +typed incoming `nativeSonKuSet.settings` and outbound accepted +`nativeSonKuSnapshot.settings` to **one** +`src/SonKuNativeBridgeContract.h`, rather than maintaining a divergent +manual v2 parse and snapshot. This is a CONTROL-thread-only codec and +contains no second audio renderer or graph. It checks finite typed numbers, +native `Settings::valid()`, bool types, geometric admissibility and all +mandatory v1 fields. Optional legacy v2 ROOM fields remain backwards +compatible. The native SPSC callback and native applied ACK remain the +sole authoritative audio state. + +- **Production default:** `ARMIX_SONKU_EXPERIMENTAL_NATIVE_XYZ_RT=OFF` + means `schemaVersion=2`, the bridge snapshot has no elevation, v2-only + settings **reject** unexpected `directElevationDegrees`; the normal + 46-byte SONK v2 FX state persists unchanged. +- **Experimental:** option ON means `schemaVersion=3`, the same typed + settings codec admits measured `directElevationDegrees` jointly with + radial distance/ROOM. Missing elevation from old browser clients defaults + exactly 0°. P7.2 native FX persists v3 50 bytes and can restore v1/v2. + No second `.smix` document schema or unverified host path introduced. + +The existing SonKu editor (same `/preview-v2/` asset, no cloned UI) shows +a single compact **SOURCE ELEVATION** slider *only after* an exact +ChannelId/instance/deviceEpoch/graphRevision matched native snapshot +advertises v3 with valid elevation. Range is derived from actual source +radial distance and room height, respecting ear clearance and measured +bank angle; room/distance changes transparently fit existing elevation +within the new room. The main 2D top-down SVG is still the azimuth +control; elevation is one independent, keyboard-accessible source height +control. The stage caption changes from 0° to measured 3D only when +native capability is established. + +All gestures continue to use pre-existing 25Hz bounded SPSC intent, +latest-wins coalescing, and **ACK + snapshot appliedRequestId** +verification before claiming DSP APPLIED. The new slider is not a +WebAudio panner or a speculative optimistic DSP state. A stale graph +revision/device epoch snapshot cannot arm v3 capability. `hidden` +overrides the existing grid display rule so **public v2 GUI size and +layout are unchanged**. + +## Evidence / non-claims + +- C++ native Windows CTests compile and run v2/v3 actual typed JSON codec, + including invalid elevation, NaN, incompatible room distance, wrong types, + and fail-atomic decode. P7.2 real JUCE PCM callback/ACK and v1/v2/v3 state + tests are reused; no entire installer/full-application rebuild. +- Linux Node checks actual SonKu GUI script syntax and physical room + geometry (old v2, source height, fit), plus native GUI bridge source + regression. P0–P7.2 PCM negative controls remain in scoped CI. +- Still **NOT proven:** full `ARMixConsole` Windows integration build, + physical ASIO + WIRE/VST3, human HRTF/dearVR listening, published + `.smix` end-to-end click/open/save/restore in a native tester, release + licensing, or P7.3 interaction design certification. Keep all stacked PRs + DRAFT and the production XYZ feature OFF until these gates are proven. diff --git a/site/preview-v2/assets/mixer-fx-rack.css b/site/preview-v2/assets/mixer-fx-rack.css index b56cd4972..8d4ba687d 100644 --- a/site/preview-v2/assets/mixer-fx-rack.css +++ b/site/preview-v2/assets/mixer-fx-rack.css @@ -1355,6 +1355,7 @@ .mx-sonku .sk-space-options button[aria-pressed="true"]{color:#e8fbff; border-color:#6fc6d7;background:#24556a;box-shadow:inset 0 1px #ffffff19} .mx-sonku .sk-space-options button:focus-visible{outline:2px solid #9bdae8;outline-offset:1px} +.mx-sonku .sk-controls .sk-space-slider[hidden]{display:none!important} .mx-sonku .sk-controls .sk-space-slider{display:grid!important; grid-template-columns:1fr auto;gap:3px!important;align-items:center; font-size:9px;letter-spacing:.4px;color:#a6c5d1;margin:0} diff --git a/site/preview-v2/assets/mixer-native-sonku.js b/site/preview-v2/assets/mixer-native-sonku.js index d9e22054f..89d48b032 100644 --- a/site/preview-v2/assets/mixer-native-sonku.js +++ b/site/preview-v2/assets/mixer-native-sonku.js @@ -7,6 +7,24 @@ const defaults=()=>({startAzimuthDegrees:0,revolutionSeconds:12, stereoSpreadDegrees:60,spatialMix:1,outputTrim:.75,moving:true,clockwise:true, spacePreset:0,sourceDistanceMeters:1.6,roomAmount:.55,ambience:.30}); const normalizeSettings=s=>({...defaults(),...s}); +// Native schema v3 is the ONLY authority that enables elevation controls. +// Public v2 never receives, edits or serializes a speculative XYZ field. +const roomHeights=[3.2,3.2,4.8,7.2]; +const elevationLimits=s=>{ + const distance=s.sourceDistanceMeters; + const height=roomHeights[s.spacePreset]; + if(!Number.isFinite(distance)||!height)return {min:0,max:0}; + const bottom=Math.max(-40,Math.asin(Math.max(-1,Math.min(1,(.5-1.45)/distance)))*180/Math.PI); + const top=Math.min(60,Math.asin(Math.max(-1,Math.min(1,(height-.5-1.45)/distance)))*180/Math.PI); + // Keep a 0.1 degree safety margin for C++ float boundary rounding. + return {min:Math.ceil((bottom+0.001)*10)/10, + max:Math.floor((top-0.001)*10)/10}; +}; +const fitElevation=s=>{ + if(!Object.prototype.hasOwnProperty.call(s,"directElevationDegrees"))return s; + const {min,max}=elevationLimits(s); + return {...s,directElevationDegrees:Math.min(max,Math.max(min,s.directElevationDegrees))}; +}; // Legacy v1/v2 states already persist a LINEAR outputTrim number (0..1). // Keep the native JSON key and its meaning intact; the visible GAIN dial // now expresses the SAME linear multiplier in dB and can exceed unity. @@ -26,7 +44,14 @@ const valid=s=>s && Number.isFinite(s.startAzimuthDegrees) && Number.isFinite(s.sourceDistanceMeters) && s.sourceDistanceMeters>=1.6 && s.sourceDistanceMeters<=roomMaxDistance[s.spacePreset]+.0001 && Number.isFinite(s.roomAmount) && s.roomAmount>=0 && s.roomAmount<=1 && - Number.isFinite(s.ambience) && s.ambience>=0 && s.ambience<=1; + Number.isFinite(s.ambience) && s.ambience>=0 && s.ambience<=1 && + (s.directElevationDegrees===undefined || ( + Number.isFinite(s.directElevationDegrees) && + s.directElevationDegrees>= -40 && s.directElevationDegrees<=60 && + s.sourceDistanceMeters*Math.cos(s.directElevationDegrees*Math.PI/180)>=.7 && + 1.45+s.sourceDistanceMeters*Math.sin(s.directElevationDegrees*Math.PI/180)>=.5 && + 1.45+s.sourceDistanceMeters*Math.sin(s.directElevationDegrees*Math.PI/180)<= + roomHeights[s.spacePreset]-.5)); const backend=()=>window.__JUCE__?.backend; const native=()=>typeof backend()?.emitEvent==="function"; const snapshot=()=>window.__ARMIX_NATIVE_M2__?.fxEditorState?.()|| @@ -129,6 +154,8 @@ root.innerHTML=[ '', '', + '', '', '