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=[
'',
'',
+ '',
'',
'