sonarium 0.6.0

package/src/math/pulse.ts

@@ -0,0 +1,64 @@
+/**
+ * The Pulse — PULSE.md made executable: tempo from the layout, grid offsets for echoes,
+ * metered strum spacing, and the calm system. Pure: no DOM, no Tone.
+ * THE LATENCY INVARIANT (PULSE.md §0): nothing here ever delays a primary hit.
+ */
+import { clamp, lerp } from './util'
+
+/** P1+P2 — layout density × page warmth → bpm, clamped to [56, 116]. */
+export function tempoFromPage(elementCount: number, warmthScale: number): number {
+  const base = lerp(66, 104, clamp(elementCount / 120, 0, 1))
+  return Math.round(clamp(base * warmthScale, 56, 116))
+}
+
+export const secondsPerBeat = (bpm: number): number => 60 / Math.max(1, bpm)
+
+/**
+ * P3 — offset (seconds from now) to the next grid boundary of `gridS` seconds that is at
+ * least `minAheadS` away. `phaseS` = seconds elapsed since the grid's epoch.
+ */
+export function nextGridOffset(phaseS: number, gridS: number, minAheadS: number): number {
+  if (gridS <= 0) return minAheadS
+  let offset = gridS - (((phaseS % gridS) + gridS) % gridS)
+  while (offset < minAheadS) offset += gridS
+  return offset
+}
+
+/** Strums step in 32nd notes — the same gesture, now in the groove. Seconds. */
+export const strumStepS = (bpm: number): number => secondsPerBeat(bpm) / 8
+
+/** Echoes answer on 8ths, one octave up, quiet (PULSE.md §2). */
+export const ECHO_TRANSPOSE = 12
+export const ECHO_VELOCITY_SCALE = 0.22
+export const ECHO_MIN_AHEAD_S = 0.08
+export const echoGridS = (bpm: number): number => secondsPerBeat(bpm) / 2
+
+// ------------------------------------------------------------- the calm system (P5)
+
+export const DUCK_RECOVERY_MS = 2000
+
+/** Activity count decays linearly: fully forgiven after count·2 s of silence. */
+export const decayCount = (count: number, dtMs: number): number =>
+  Math.max(0, count - dtMs / DUCK_RECOVERY_MS)
+
+/** Velocity multiplier: the 6th rapid repeat sits at ~40%, never below. */
+export const duckFactor = (count: number): number =>
+  Math.max(0.4, Math.pow(0.85, Math.max(0, count)))
+
+// ------------------------------------------------------------- phrases (P4)
+
+export const PHRASE_PROBABILITY = 0.55
+export const PHRASE_MIN_NOTES = 2
+export const PHRASE_MAX_NOTES = 4
+
+/** Reading order: rows of ~80 px, then left→right. Sort key for (top, left). */
+export const readingOrderKey = (top: number, left: number): number =>
+  Math.round(top / 80) * 100000 + clamp(left, 0, 99999)
+
+/**
+ * Window the score by scroll progress: with n elements and a phrase of len, the playhead
+ * starts at `progress·(n − len)`.
+ */
+export function phraseWindow(n: number, len: number, progress: number): number {
+  return Math.round(clamp(progress, 0, 1) * Math.max(0, n - len))
+}

package/src/math/scales.ts

@@ -0,0 +1,90 @@
+import { clamp, fnv1a } from './util'
+
+/** MAPPING.md §0 — the five scales reachable from a hostname hash. */
+export const SCALES: Record<string, readonly number[]> = {
+  pentMajor: [0, 2, 4, 7, 9],
+  pentMinor: [0, 3, 5, 7, 10],
+  dorian: [0, 2, 3, 5, 7, 9, 10],
+  lydian: [0, 2, 4, 6, 7, 9, 11],
+  mixolydian: [0, 2, 4, 5, 7, 9, 10],
+} as const
+
+export const SCALE_NAMES = Object.keys(SCALES) as (keyof typeof SCALES)[]
+
+export const OCTAVES = 3
+/** C3 — the bottom of the 3-octave pitch space. */
+export const BASE_MIDI = 48
+
+const NOTE_TO_PC: Record<string, number> = {
+  C: 0, 'C#': 1, Db: 1, D: 2, 'D#': 3, Eb: 3, E: 4, F: 5, 'F#': 6,
+  Gb: 6, G: 7, 'G#': 8, Ab: 8, A: 9, 'A#': 10, Bb: 10, B: 11,
+}
+
+const PC_TO_NOTE = ['C', 'C#', 'D', 'Eb', 'E', 'F', 'F#', 'G', 'Ab', 'A', 'Bb', 'B'] as const
+
+export interface SiteKey {
+  root: number
+  scaleName: string
+  scale: readonly number[]
+  label: string
+}
+
+/** Deterministic per-domain musical identity (T8 audio branding). Same host → same key, always. */
+export function siteKey(hostname: string): SiteKey {
+  const host = hostname || 'localhost'
+  const h = fnv1a(host)
+  const root = h % 12
+  const scaleName = SCALE_NAMES[(h >>> 4) % SCALE_NAMES.length] as string
+  const scale = SCALES[scaleName] as readonly number[]
+  return { root, scaleName, scale, label: `${PC_TO_NOTE[root]} ${scaleName}` }
+}
+
+/** Parse "D dorian" / "Eb pentMinor" → SiteKey. Returns null when unrecognized. */
+export function parseKey(spec: string): SiteKey | null {
+  const m = spec.trim().match(/^([A-Ga-g][#b]?)\s+(\w+)$/)
+  if (!m) return null
+  const note = (m[1] as string).charAt(0).toUpperCase() + (m[1] as string).slice(1)
+  const root = NOTE_TO_PC[note]
+  const scaleName = m[2] as string
+  const scale = SCALES[scaleName]
+  if (root === undefined || !scale) return null
+  return { root, scaleName, scale, label: `${PC_TO_NOTE[root]} ${scaleName}` }
+}
+
+/**
+ * The Musical Quantizer (Invariant #2): degree ∈ [0,1] → MIDI note inside the key,
+ * laid across OCTAVES octaves from BASE_MIDI + root. stepOffset shifts by whole scale steps
+ * (sibling melodies S4, heading registers S6, kiki nudge G10).
+ */
+export function degreeToMidi(degree: number, key: SiteKey, stepOffset = 0): number {
+  const steps = key.scale.length * OCTAVES
+  let idx = Math.round(clamp(degree, 0, 1) * (steps - 1)) + Math.round(stepOffset)
+  idx = clamp(idx, 0, steps - 1)
+  const oct = Math.floor(idx / key.scale.length)
+  const pc = key.scale[idx % key.scale.length] as number
+  return BASE_MIDI + key.root + oct * 12 + pc
+}
+
+export const midiToFreq = (m: number): number => 440 * Math.pow(2, (m - 69) / 12)
+
+/**
+ * Walk N scale steps up/down from a midi note, staying on the key's pitch classes
+ * (the ribbon controller's quantizer — MODULAR.md §3; Invariant #2 holds under drag).
+ */
+export function stepInScale(midi: number, key: SiteKey, steps: number): number {
+  if (steps === 0) return midi
+  const pcs = key.scale.map((s) => (s + key.root) % 12)
+  const dir = steps > 0 ? 1 : -1
+  let m = midi
+  for (let i = 0; i < Math.abs(steps); i++) {
+    do {
+      m += dir
+    } while (!pcs.includes(((m % 12) + 12) % 12) && m > 12 && m < 120)
+  }
+  return clamp(m, 12, 120)
+}
+
+export function midiToNoteName(m: number): string {
+  const pc = ((m % 12) + 12) % 12
+  return `${PC_TO_NOTE[pc]}${Math.floor(m / 12) - 1}`
+}

package/src/math/util.ts

@@ -0,0 +1,16 @@
+export const clamp = (v: number, a: number, b: number): number => Math.min(b, Math.max(a, v))
+
+export const lerp = (a: number, b: number, t: number): number => a + (b - a) * t
+
+/** Normalized position of v in [a, b], clamped to [0, 1]. */
+export const norm = (v: number, a: number, b: number): number => clamp((v - a) / (b - a), 0, 1)
+
+/** FNV-1a 32-bit — stable, dependency-free hash for site identity (MAPPING.md §0). */
+export function fnv1a(str: string): number {
+  let h = 0x811c9dc5
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i)
+    h = Math.imul(h, 0x01000193)
+  }
+  return h >>> 0
+}

package/src/spatial/backend.ts

@@ -0,0 +1,166 @@
+/**
+ * SpatialBackend — the seam between the voice pool and the spatial engine (SPATIAL.md §6).
+ * 'ambisonic' encodes every lane into the shared FOA field; 'panner' is the v0.1 per-voice
+ * HRTF path, kept as option and automatic fallback. Imports Tone only.
+ */
+import * as Tone from 'tone'
+import { clamp } from '../math/util'
+import type { SonicProfile } from '../types'
+import type { Room } from '../core/room'
+import { AmbisonicBus } from './bus'
+import { SourceEncoder } from './encoder'
+import { FoaRoom } from './room-foa'
+import { foaGains } from './sh'
+import type { Mat3 } from './rotation'
+import {
+  directGain, directivityDirectGain, directivitySendScale, resolveFactors,
+  roomGain, type PerceptualFactors,
+} from './perceptual'
+
+export interface LaneOutput {
+  /** The lane's filter connects here. */
+  input: Tone.InputNode
+  /** Place the voice in space from its profile (called at trigger time). */
+  setPlacement(profile: SonicProfile, when?: number): void
+  dispose(): void
+}
+
+export interface SpatialBackend {
+  readonly kind: 'ambisonic' | 'panner'
+  createOutput(): LaneOutput
+  setFactors(factors: PerceptualFactors): void
+  /** Rotate the field (ambisonic) — no-op on the panner backend. */
+  setRotation(m: Mat3): void
+  onViewport(vw: number): void
+  dispose(): void
+}
+
+// ---------------------------------------------------------------------------- ambisonic
+
+export class AmbisonicBackend implements SpatialBackend {
+  readonly kind = 'ambisonic' as const
+  private bus: AmbisonicBus
+  private foaRoom: FoaRoom
+  private factors: PerceptualFactors
+
+  constructor(private room: Room, decoderKind: 'binaural' | 'stereo', vw: number, factors?: Partial<PerceptualFactors>) {
+    this.factors = resolveFactors(factors)
+    this.bus = new AmbisonicBus(room.spatialIn, decoderKind)
+    this.foaRoom = new FoaRoom(this.bus.inputs, room.reverb, vw, this.factors)
+  }
+
+  createOutput(): LaneOutput {
+    const enc = new SourceEncoder(this.bus.inputs)
+    const send = new Tone.Gain(0.15)
+    // MATTER.md reverb weave: dark sources bloom dark — the tail is colored per voice.
+    const sendColor = new Tone.Filter({ type: 'lowpass', frequency: 5000, rolloff: -12 })
+    enc.input.connect(send)
+    send.connect(sendColor)
+    sendColor.connect(this.room.reverb)
+    enc.input.connect(this.foaRoom.erIn)
+    const backend = this
+    return {
+      input: enc.input,
+      setPlacement(profile: SonicProfile, when?: number) {
+        const t = when ?? Tone.now()
+        const s = profile.sphere
+        const w = profile.voice.reverb
+        const extent = clamp(s.extent + w.extentBonus, 0, 0.95)
+        const g = foaGains(s.azimuth, s.elevation, extent)
+        const direct = directGain(backend.factors.presence) * directivityDirectGain(s.directivity)
+        enc.set(g, direct, when)
+        const wetSend = clamp(
+          profile.reverbSend * directivitySendScale(s.directivity) * roomGain(backend.factors.roomPresence),
+          0,
+          1.5,
+        )
+        sendColor.frequency.rampTo(w.sendCutoffHz, 0.02, t)
+        send.gain.cancelScheduledValues(t)
+        if (w.bloom > 0.35) {
+          // round sources swell into the room over the note; sharp ones arrive dry-then-done
+          send.gain.setValueAtTime(wetSend * 0.35, t)
+          send.gain.rampTo(wetSend, Math.max(0.08, profile.durationS), t)
+        } else {
+          send.gain.rampTo(wetSend, 0.02, t)
+        }
+      },
+      dispose() {
+        enc.dispose()
+        send.dispose()
+        sendColor.dispose()
+      },
+    }
+  }
+
+  setFactors(factors: PerceptualFactors): void {
+    this.factors = factors
+    this.foaRoom.setFactors(factors)
+    this.room.setFactors(factors)
+  }
+
+  setRotation(m: Mat3): void {
+    this.bus.setRotation(m)
+  }
+
+  onViewport(vw: number): void {
+    this.foaRoom.setViewport(vw)
+  }
+
+  dispose(): void {
+    this.foaRoom.dispose()
+    this.bus.dispose()
+  }
+}
+
+// ---------------------------------------------------------------------------- panner (v0.1)
+
+export class PannerBackend implements SpatialBackend {
+  readonly kind = 'panner' as const
+
+  constructor(private room: Room, private panningModel: 'HRTF' | 'equalpower') {}
+
+  createOutput(): LaneOutput {
+    const panner = new Tone.Panner3D({
+      panningModel: this.panningModel,
+      distanceModel: 'inverse',
+      refDistance: 1,
+      rolloffFactor: 0.4,
+      positionX: 0, positionY: 0, positionZ: -2,
+    })
+    const dry = new Tone.Gain(1)
+    const send = new Tone.Gain(0.18)
+    const sendColor = new Tone.Filter({ type: 'lowpass', frequency: 5000, rolloff: -12 })
+    panner.connect(dry)
+    panner.connect(send)
+    send.connect(sendColor)
+    dry.connect(this.room.buses.dryIn)
+    sendColor.connect(this.room.buses.wetIn)
+    return {
+      input: panner,
+      setPlacement(profile: SonicProfile, when?: number) {
+        const t = when ?? Tone.now()
+        panner.positionX.rampTo(profile.pan.x, 0.02, t)
+        panner.positionY.rampTo(profile.pan.y, 0.02, t)
+        panner.positionZ.rampTo(profile.pan.z, 0.02, t)
+        sendColor.frequency.rampTo(profile.voice.reverb.sendCutoffHz, 0.02, t)
+        send.gain.rampTo(clamp(profile.reverbSend, 0, 1), 0.02, t)
+      },
+      dispose() {
+        panner.dispose()
+        dry.dispose()
+        send.dispose()
+        sendColor.dispose()
+      },
+    }
+  }
+
+  setFactors(factors: PerceptualFactors): void {
+    this.room.setFactors(factors)
+  }
+
+  setRotation(): void { /* the panner world rotates via Tone.Listener (ListenerRig) */ }
+
+  onViewport(): void { /* room resize handled by Room */ }
+
+  dispose(): void { /* lane outputs disposed by the pool */ }
+}

package/src/spatial/bus.ts

@@ -0,0 +1,114 @@
+/**
+ * AmbisonicBus — the field itself (SPATIAL.md §3): W/Y/Z/X summing buses → live 3×3 rotation
+ * (nine GainNodes; W invariant) → binaural decode through fixed virtual speakers, each rendered
+ * by one native HRTF PannerNode. Imports Tone only.
+ */
+import * as Tone from 'tone'
+import { CUBE_LAYOUT, decodeMatrix } from './decoder'
+import { IDENTITY, type Mat3 } from './rotation'
+import type { BusInputs } from './encoder'
+
+const SPEAKER_RADIUS = 2.5
+
+export class AmbisonicBus {
+  readonly inputs: BusInputs
+  private rot: Tone.Gain[][] // rot[out][in] over (X, Y, Z) = indices 0,1,2
+  private outW: Tone.Gain
+  private outXYZ: [Tone.Gain, Tone.Gain, Tone.Gain]
+  private nodes: { dispose(): void }[] = []
+
+  constructor(destination: Tone.InputNode, decoderKind: 'binaural' | 'stereo') {
+    this.inputs = { w: new Tone.Gain(1), y: new Tone.Gain(1), z: new Tone.Gain(1), x: new Tone.Gain(1) }
+    this.outW = new Tone.Gain(1)
+    this.outXYZ = [new Tone.Gain(1), new Tone.Gain(1), new Tone.Gain(1)]
+    this.inputs.w.connect(this.outW)
+
+    // Rotation matrix acts on the (X, Y, Z) triple: out = R · in.
+    const inXYZ = [this.inputs.x, this.inputs.y, this.inputs.z]
+    this.rot = []
+    for (let r = 0; r < 3; r++) {
+      const row: Tone.Gain[] = []
+      for (let c = 0; c < 3; c++) {
+        const g = new Tone.Gain(IDENTITY[r]![c]!)
+        inXYZ[c]!.connect(g)
+        g.connect(this.outXYZ[r]!)
+        row.push(g)
+      }
+      this.rot.push(row)
+    }
+
+    if (decoderKind === 'stereo') this.buildStereoDecode(destination)
+    else this.buildVirtualSpeakerDecode(destination)
+
+    this.nodes.push(this.inputs.w, this.inputs.y, this.inputs.z, this.inputs.x, this.outW, ...this.outXYZ, ...this.rot.flat())
+  }
+
+  /** SPATIAL.md §3.2 — 8 cube speakers, each a static mix of (W, X', Y', Z') into a fixed HRTF panner. */
+  private buildVirtualSpeakerDecode(destination: Tone.InputNode): void {
+    const rows = decodeMatrix(CUBE_LAYOUT)
+    rows.forEach((row, i) => {
+      const dir = CUBE_LAYOUT[i]!.dir
+      const sum = new Tone.Gain(1)
+      const mw = new Tone.Gain(row.w)
+      const mx = new Tone.Gain(row.x)
+      const my = new Tone.Gain(row.y)
+      const mz = new Tone.Gain(row.z)
+      this.outW.connect(mw)
+      this.outXYZ[0]!.connect(mx)
+      this.outXYZ[1]!.connect(my)
+      this.outXYZ[2]!.connect(mz)
+      mw.connect(sum)
+      mx.connect(sum)
+      my.connect(sum)
+      mz.connect(sum)
+      // AmbiX (+x fwd, +y left, +z up) → WebAudio (+x right, +y up, −z fwd).
+      const panner = new Tone.Panner3D({
+        panningModel: 'HRTF',
+        distanceModel: 'inverse',
+        refDistance: SPEAKER_RADIUS,
+        rolloffFactor: 0, // fixed-radius speakers: direction only, no distance shading
+        positionX: -dir[1] * SPEAKER_RADIUS,
+        positionY: dir[2] * SPEAKER_RADIUS,
+        positionZ: -dir[0] * SPEAKER_RADIUS,
+      })
+      sum.connect(panner)
+      panner.connect(destination)
+      this.nodes.push(sum, mw, mx, my, mz, panner)
+    })
+  }
+
+  /** Fallback decode without HRTF: two virtual cardioids at ±90° (SPATIAL.md §3.2). */
+  private buildStereoDecode(destination: Tone.InputNode): void {
+    const L = new Tone.Gain(1)
+    const R = new Tone.Gain(1)
+    const wL = new Tone.Gain(0.5)
+    const wR = new Tone.Gain(0.5)
+    const yL = new Tone.Gain(0.5)
+    const yR = new Tone.Gain(-0.5)
+    this.outW.connect(wL)
+    this.outW.connect(wR)
+    this.outXYZ[1]!.connect(yL)
+    this.outXYZ[1]!.connect(yR)
+    wL.connect(L)
+    yL.connect(L)
+    wR.connect(R)
+    yR.connect(R)
+    const merge = new Tone.Merge()
+    L.connect(merge, 0, 0)
+    R.connect(merge, 0, 1)
+    merge.connect(destination)
+    this.nodes.push(L, R, wL, wR, yL, yR, merge)
+  }
+
+  /** Rotate the whole field (FieldRig calls this with lookMatrix output). Ramped, zipper-free. */
+  setRotation(m: Mat3, rampS = 0.04): void {
+    for (let r = 0; r < 3; r++)
+      for (let c = 0; c < 3; c++)
+        this.rot[r]![c]!.gain.rampTo(m[r]![c]!, rampS)
+  }
+
+  dispose(): void {
+    for (const n of this.nodes) n.dispose()
+    this.nodes = []
+  }
+}

package/src/spatial/decoder.ts

@@ -0,0 +1,63 @@
+/**
+ * Pure FOA decoding — SPATIAL.md §3.2. Sampling decoder with max-rE weighting over a fixed
+ * virtual-speaker layout; each speaker is later rendered by one native HRTF panner.
+ */
+import { unitVector, type FoaGains } from './sh'
+
+export interface Speaker {
+  /** Unit direction in the AmbiX frame. */
+  dir: [number, number, number]
+  label: string
+}
+
+const C = 1 / Math.sqrt(3)
+
+/** Cube vertices: full-sphere coverage including elevation, symmetric, M = 8. */
+export const CUBE_LAYOUT: Speaker[] = [
+  { dir: [C, C, C], label: 'front-left-up' },
+  { dir: [C, -C, C], label: 'front-right-up' },
+  { dir: [C, C, -C], label: 'front-left-down' },
+  { dir: [C, -C, -C], label: 'front-right-down' },
+  { dir: [-C, C, C], label: 'back-left-up' },
+  { dir: [-C, -C, C], label: 'back-right-up' },
+  { dir: [-C, C, -C], label: 'back-left-down' },
+  { dir: [-C, -C, -C], label: 'back-right-down' },
+]
+
+/** max-rE weights for 3D first order (Zotter & Frank): g0 = 1, g1 = 1/√3. */
+export const MAXRE_G0 = 1
+export const MAXRE_G1 = 1 / Math.sqrt(3)
+
+export interface DecodeRow {
+  /** Per-ACN gains [w, y, z, x] for one speaker: s = w·W + y·Y + z·Z + x·X. */
+  w: number
+  y: number
+  z: number
+  x: number
+}
+
+/**
+ * Sampling decode matrix for SN3D input: sm = (1/M)·[g0·W + 3·g1·(X·xm + Y·ym + Z·zm)].
+ * The 3 re-normalizes first-order SN3D to N3D inside the projection.
+ */
+export function decodeMatrix(layout: Speaker[]): DecodeRow[] {
+  const M = layout.length
+  return layout.map(({ dir }) => ({
+    w: (1 / M) * MAXRE_G0,
+    x: (3 / M) * MAXRE_G1 * dir[0],
+    y: (3 / M) * MAXRE_G1 * dir[1],
+    z: (3 / M) * MAXRE_G1 * dir[2],
+  }))
+}
+
+/** Decode an encoded source to speaker signals (used by tests and the worklet path later). */
+export function decodeGains(rows: DecodeRow[], g: FoaGains): number[] {
+  return rows.map((r) => r.w * g.w + r.y * g.y + r.z * g.z + r.x * g.x)
+}
+
+/** Total decoded energy for a direction — tests assert flatness across the sphere. */
+export function decodedEnergy(rows: DecodeRow[], azimuth: number, elevation: number): number {
+  const v = unitVector(azimuth, elevation)
+  const g: FoaGains = { w: 1, x: v[0], y: v[1], z: v[2] }
+  return decodeGains(rows, g).reduce((acc, s) => acc + s * s, 0)
+}

package/src/spatial/encoder.ts

@@ -0,0 +1,54 @@
+/**
+ * SourceEncoder — one per voice lane: four GainNodes carrying the lane's mono signal into the
+ * W/Y/Z/X buses with first-order SH gains (SPATIAL.md §2). Imports Tone only.
+ */
+import * as Tone from 'tone'
+import type { FoaGains } from './sh'
+
+export interface BusInputs {
+  w: Tone.Gain
+  y: Tone.Gain
+  z: Tone.Gain
+  x: Tone.Gain
+}
+
+export class SourceEncoder {
+  readonly input: Tone.Gain
+  private gw: Tone.Gain
+  private gy: Tone.Gain
+  private gz: Tone.Gain
+  private gx: Tone.Gain
+
+  constructor(bus: BusInputs) {
+    this.input = new Tone.Gain(1)
+    this.gw = new Tone.Gain(1)
+    this.gy = new Tone.Gain(0)
+    this.gz = new Tone.Gain(0)
+    this.gx = new Tone.Gain(1)
+    this.input.connect(this.gw)
+    this.input.connect(this.gy)
+    this.input.connect(this.gz)
+    this.input.connect(this.gx)
+    this.gw.connect(bus.w)
+    this.gy.connect(bus.y)
+    this.gz.connect(bus.z)
+    this.gx.connect(bus.x)
+  }
+
+  /** Apply SH gains × an overall direct-path gain, ramped to avoid zipper noise. */
+  set(g: FoaGains, directGain: number, when?: number, rampS = 0.015): void {
+    const t = when ?? Tone.now()
+    this.gw.gain.rampTo(g.w * directGain, rampS, t)
+    this.gy.gain.rampTo(g.y * directGain, rampS, t)
+    this.gz.gain.rampTo(g.z * directGain, rampS, t)
+    this.gx.gain.rampTo(g.x * directGain, rampS, t)
+  }
+
+  dispose(): void {
+    this.input.dispose()
+    this.gw.dispose()
+    this.gy.dispose()
+    this.gz.dispose()
+    this.gx.dispose()
+  }
+}

package/src/spatial/field.ts

@@ -0,0 +1,75 @@
+/**
+ * FieldRig — embodiment for the ambisonic backend (SPATIAL.md §3.1): mouse-look on desktop,
+ * device attitude on mobile, lerped per frame into one field rotation. Exposes the same
+ * pointTo/tiltTo surface as the legacy ListenerRig so L2 drivers don't care which world they
+ * live in.
+ */
+import { clamp, lerp } from '../math/util'
+import { DEG } from './sh'
+import { lookMatrix } from './rotation'
+import type { SpatialBackend } from './backend'
+
+const POINTER_YAW_MAX = 40 * DEG
+const POINTER_PITCH_MAX = 20 * DEG
+const TILT_YAW_MAX = 35 * DEG
+const TILT_PITCH_MAX = 25 * DEG
+
+export class FieldRig {
+  private target = { yaw: 0, pitch: 0 }
+  private tilt = { yaw: 0, pitch: 0 }
+  private look = { yaw: 0, pitch: 0 }
+  private raf = 0
+  private running = false
+
+  constructor(
+    private backend: SpatialBackend,
+    private mode: 'pointer' | 'center',
+  ) {}
+
+  start(): void {
+    if (this.running) return
+    this.running = true
+    const step = () => {
+      if (!this.running) return
+      const gy = clamp(this.target.yaw + this.tilt.yaw, -Math.PI / 2, Math.PI / 2)
+      const gp = clamp(this.target.pitch + this.tilt.pitch, -Math.PI / 3, Math.PI / 3)
+      const ny = lerp(this.look.yaw, gy, 0.1)
+      const np = lerp(this.look.pitch, gp, 0.1)
+      if (Math.abs(ny - this.look.yaw) > 1e-4 || Math.abs(np - this.look.pitch) > 1e-4) {
+        this.look.yaw = ny
+        this.look.pitch = np
+        this.backend.setRotation(lookMatrix(this.look.yaw, this.look.pitch))
+      }
+      this.raf = requestAnimationFrame(step)
+    }
+    this.raf = requestAnimationFrame(step)
+  }
+
+  /** I9 — cursor (viewport-normalized 0..1) becomes look direction: right edge = look right. */
+  pointTo(tx: number, ty: number): void {
+    if (this.mode !== 'pointer') return
+    this.target.yaw = (2 * clamp(tx, 0, 1) - 1) * POINTER_YAW_MAX
+    this.target.pitch = (1 - 2 * clamp(ty, 0, 1)) * POINTER_PITCH_MAX
+  }
+
+  /** I10 — device attitude: γ right-tilt = look right, β beyond ~40° = look up/down. */
+  tiltTo(gamma: number, beta: number): void {
+    this.tilt.yaw = clamp(gamma / 45, -1, 1) * TILT_YAW_MAX
+    this.tilt.pitch = clamp((beta - 40) / 45, -1, 1) * -TILT_PITCH_MAX
+  }
+
+  /** Public look API (head tracking / WebXR later plugs in here). Radians, right/up positive. */
+  lookAt(yawRight: number, pitchUp: number): void {
+    this.target.yaw = yawRight
+    this.target.pitch = pitchUp
+  }
+
+  get state(): { yaw: number; pitch: number } {
+    return { yaw: this.look.yaw, pitch: this.look.pitch }
+  }
+
+  dispose(): void {
+    this.running = false
+    cancelAnimationFrame(this.raf)
+  }
+}

package/src/spatial/perceptual.ts

@@ -0,0 +1,43 @@
+/**
+ * Pure perceptual-factor formulas — SPATIAL.md §5. The spat5.oper surface: five factors in
+ * [0,1], each mapping monotonically to DSP parameters. Defaults mirror the spec table.
+ */
+import { clamp, lerp } from '../math/util'
+import type { PerceptualFactors } from '../types'
+
+export type { PerceptualFactors }
+
+export const DEFAULT_FACTORS: PerceptualFactors = {
+  presence: 0.7,
+  roomPresence: 0.5,
+  envelopment: 0.55,
+  warmth: 0.5,
+  brilliance: 0.5,
+}
+
+export function resolveFactors(partial: Partial<PerceptualFactors> | undefined): PerceptualFactors {
+  const f = { ...DEFAULT_FACTORS, ...(partial ?? {}) }
+  for (const k of Object.keys(f) as (keyof PerceptualFactors)[]) f[k] = clamp(f[k], 0, 1)
+  return f
+}
+
+/** presence → direct-path gain (linear). */
+export const directGain = (presence: number): number => lerp(0.5, 1.2, clamp(presence, 0, 1))
+
+/** roomPresence → early-reflection + reverb-send master (linear). */
+export const roomGain = (roomPresence: number): number => lerp(0, 1.6, clamp(roomPresence, 0, 1))
+
+/** envelopment → diffuse-tail extent (σ of the tail encoders) and tail level. */
+export const tailExtent = (envelopment: number): number => clamp(envelopment, 0, 1)
+export const tailLevel = (envelopment: number): number => lerp(0.7, 1.25, clamp(envelopment, 0, 1))
+
+/** warmth → low-shelf dB at 250 Hz. */
+export const warmthDb = (warmth: number): number => lerp(-3, 3, clamp(warmth, 0, 1))
+
+/** brilliance → high-shelf dB at 4 kHz. */
+export const brillianceDb = (brilliance: number): number => lerp(-4, 3, clamp(brilliance, 0, 1))
+
+/** directivity δ → source presence/brightness/room behaviour (SPATIAL.md §2). */
+export const directivityDirectGain = (d: number): number => lerp(0.75, 1.1, clamp(d, 0, 1))
+export const directivitySendScale = (d: number): number => lerp(1.35, 0.8, clamp(d, 0, 1))
+export const directivityFilterScale = (d: number): number => lerp(0.85, 1.15, clamp(d, 0, 1))