feat(static): client-side alteration engine (port of player.alteration/audio)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

tests/test_alteration_js_parity.py

@@ -0,0 +1,21 @@
+"""The static build reimplements plan_alteration/resolve_audio in JS
+(simulator/static/alteration.js). This pins the numeric contract so the Python
+and JS cannot silently diverge — if you change the engine, change both (the
+mirrored JS cases live in simulator/unit/alteration.test.js)."""
+from hef.selection import Coordinate
+from player.alteration import plan_alteration, render_plan_to_dict
+from player.audio import resolve_audio, resolve_visual
+
+
+def test_engine_contract_matches_js_expectations():
+    # mirrors the cases asserted in simulator/unit/alteration.test.js
+    p = render_plan_to_dict(plan_alteration(Coordinate(left=2, right=4, dark=0, light=0)))
+    assert p["overlay"] == {"level": 2, "intensity": 0.5}
+    assert p["dream"] == {"strength": 4, "intensity": 1.0}
+    assert p["affect"] == {"strength": 4, "intensity": 1.0}
+    assert render_plan_to_dict(plan_alteration(Coordinate(0, 0, 0, 4)))["grade"]["tone"] == 1.0
+    assert render_plan_to_dict(plan_alteration(Coordinate(0, 0, 4, 0)))["grade"]["tone"] == -1.0
+    assert render_plan_to_dict(plan_alteration(Coordinate(0, 0, 0, 0)))["is_identity"] is True
+    assert resolve_visual("off") is False
+    a = resolve_audio("soundtrack", scale_audio="cosmos.mp3")
+    assert a.url == "/media/audio/cosmos.mp3" and a.altitude_coupled is True