sonarium 0.6.0

package/src/spatial/room-foa.ts

@@ -0,0 +1,81 @@
+/**
+ * FoaRoom — the Spat room model in the field (SPATIAL.md §3.3): early reflections encoded at
+ * mirror directions + the diffuse tail whose extent IS the envelopment factor. Imports Tone only.
+ */
+import * as Tone from 'tone'
+import { foaGains, DEG } from './sh'
+import { reflectionScaleFromViewport } from './sphere'
+import { roomGain, tailExtent, tailLevel, type PerceptualFactors } from './perceptual'
+import { SourceEncoder, type BusInputs } from './encoder'
+
+const ER_BASE_TIMES = [0.013, 0.019, 0.027, 0.034]
+const ER_TAP_LEVELS = [1, 0.85, 0.7, 0.6]
+const ER_DIRECTIONS: Array<[number, number]> = [
+  [110 * DEG, 30 * DEG],
+  [-110 * DEG, 30 * DEG],
+  [110 * DEG, -30 * DEG],
+  [-110 * DEG, -30 * DEG],
+]
+
+export class FoaRoom {
+  /** Lanes tap their direct signal here (mono sum). */
+  readonly erIn: Tone.Gain
+  private erMaster: Tone.Gain
+  private delays: Tone.Delay[] = []
+  private split: Tone.Split
+  private tailL: SourceEncoder
+  private tailR: SourceEncoder
+  private nodes: { dispose(): void }[] = []
+
+  constructor(bus: BusInputs, reverb: Tone.Reverb, vw: number, factors: PerceptualFactors) {
+    this.erIn = new Tone.Gain(1)
+    this.erMaster = new Tone.Gain(0.22 * roomGain(factors.roomPresence))
+    this.erIn.connect(this.erMaster)
+
+    const scale = reflectionScaleFromViewport(vw)
+    ER_BASE_TIMES.forEach((t, i) => {
+      const delay = new Tone.Delay({ delayTime: t * scale, maxDelay: 0.12 })
+      const tap = new Tone.Gain(ER_TAP_LEVELS[i] as number)
+      const enc = new SourceEncoder(bus)
+      const [az, el] = ER_DIRECTIONS[i] as [number, number]
+      enc.set(foaGains(az, el, 0.35), 1)
+      this.erMaster.connect(delay)
+      delay.connect(tap)
+      tap.connect(enc.input)
+      this.delays.push(delay)
+      this.nodes.push(delay, tap, enc)
+    })
+
+    // Diffuse tail: reverb L/R become two wide sources at ±120°; their extent = envelopment.
+    this.split = new Tone.Split()
+    reverb.connect(this.split)
+    this.tailL = new SourceEncoder(bus)
+    this.tailR = new SourceEncoder(bus)
+    this.split.connect(this.tailL.input, 0)
+    this.split.connect(this.tailR.input, 1)
+    this.applyTail(factors)
+    this.nodes.push(this.erIn, this.erMaster, this.split, this.tailL, this.tailR)
+  }
+
+  private applyTail(f: PerceptualFactors): void {
+    const ext = tailExtent(f.envelopment)
+    const level = tailLevel(f.envelopment)
+    this.tailL.set(foaGains(120 * DEG, 0, ext), level)
+    this.tailR.set(foaGains(-120 * DEG, 0, ext), level)
+  }
+
+  setFactors(f: PerceptualFactors): void {
+    this.erMaster.gain.rampTo(0.22 * roomGain(f.roomPresence), 0.1)
+    this.applyTail(f)
+  }
+
+  setViewport(vw: number): void {
+    const scale = reflectionScaleFromViewport(vw)
+    this.delays.forEach((d, i) => d.delayTime.rampTo((ER_BASE_TIMES[i] as number) * scale, 0.3))
+  }
+
+  dispose(): void {
+    for (const n of this.nodes) n.dispose()
+    this.nodes = []
+  }
+}

package/src/spatial/rotation.ts

@@ -0,0 +1,73 @@
+/**
+ * Pure field rotation — SPATIAL.md §3.1. The 3×3 matrix acts on the (X, Y, Z) channel triple
+ * (W is rotation-invariant). Row-major: m[r][c], applied as X' = m00·X + m01·Y + m02·Z, etc.
+ * Composition R = Rz(yaw) · Ry(pitch) · Rx(roll). Angles in radians.
+ */
+
+export type Mat3 = [
+  [number, number, number],
+  [number, number, number],
+  [number, number, number],
+]
+
+export const IDENTITY: Mat3 = [
+  [1, 0, 0],
+  [0, 1, 0],
+  [0, 0, 1],
+]
+
+function mul(a: Mat3, b: Mat3): Mat3 {
+  const out: Mat3 = [
+    [0, 0, 0],
+    [0, 0, 0],
+    [0, 0, 0],
+  ]
+  for (let r = 0; r < 3; r++)
+    for (let c = 0; c < 3; c++)
+      out[r]![c] = a[r]![0]! * b[0]![c]! + a[r]![1]! * b[1]![c]! + a[r]![2]! * b[2]![c]!
+  return out
+}
+
+/** Acts on column vectors (X, Y, Z)ᵀ in the AmbiX frame (+x fwd, +y left, +z up). */
+export function rotationMatrix(yaw: number, pitch: number, roll = 0): Mat3 {
+  const cy = Math.cos(yaw), sy = Math.sin(yaw)
+  const cp = Math.cos(pitch), sp = Math.sin(pitch)
+  const cr = Math.cos(roll), sr = Math.sin(roll)
+  const Rz: Mat3 = [
+    [cy, -sy, 0],
+    [sy, cy, 0],
+    [0, 0, 1],
+  ]
+  const Ry: Mat3 = [
+    [cp, 0, sp],
+    [0, 1, 0],
+    [-sp, 0, cp],
+  ]
+  const Rx: Mat3 = [
+    [1, 0, 0],
+    [0, cr, -sr],
+    [0, sr, cr],
+  ]
+  return mul(mul(Rz, Ry), Rx)
+}
+
+export function applyMat3(m: Mat3, v: [number, number, number]): [number, number, number] {
+  return [
+    m[0]![0]! * v[0] + m[0]![1]! * v[1] + m[0]![2]! * v[2],
+    m[1]![0]! * v[0] + m[1]![1]! * v[1] + m[1]![2]! * v[2],
+    m[2]![0]! * v[0] + m[2]![1]! * v[1] + m[2]![2]! * v[2],
+  ]
+}
+
+/**
+ * Look semantics (SPATIAL.md §3.1): the field rotation is the INVERSE of the head's intrinsic
+ * yaw-then-pitch rotation. Looking right by α (head Rz(−α)) and up by β (head Ry(−β)) gives
+ * field R = (Rz(−α)·Ry(−β))⁻¹ = Ry(β)·Rz(α). The sign/composition decision lives here and
+ * only here, pinned by tests: look right → right-side sources arrive frontward; look up →
+ * overhead sources arrive frontward.
+ */
+export function lookMatrix(yawRight: number, pitchUp: number): Mat3 {
+  const pitch = rotationMatrix(0, pitchUp, 0) // = Ry(pitchUp)
+  const yaw = rotationMatrix(yawRight, 0, 0) //  = Rz(yawRight)
+  return mul(pitch, yaw)
+}

package/src/spatial/sh.ts

@@ -0,0 +1,38 @@
+/**
+ * Pure spherical-harmonic encoding — SPATIAL.md §1–2. AmbiX: ACN order [W, Y, Z, X],
+ * SN3D normalization, +x forward, +y left, +z up, +azimuth left. No DOM, no Tone.
+ */
+
+export const DEG = Math.PI / 180
+
+/** ACN channel indices, for readability everywhere else. */
+export const ACN = { W: 0, Y: 1, Z: 2, X: 3 } as const
+
+export interface FoaGains {
+  w: number
+  y: number
+  z: number
+  x: number
+}
+
+/**
+ * First-order encode of a plane wave from (azimuth, elevation), with extent σ blending the
+ * directional components into the omni channel (SPATIAL.md §2). Angles in radians.
+ */
+export function foaGains(azimuth: number, elevation: number, extent = 0): FoaGains {
+  const s = Math.min(1, Math.max(0, extent))
+  const cosEl = Math.cos(elevation)
+  const dir = 1 - s
+  return {
+    w: 1 + 0.41 * s,
+    y: dir * Math.sin(azimuth) * cosEl,
+    z: dir * Math.sin(elevation),
+    x: dir * Math.cos(azimuth) * cosEl,
+  }
+}
+
+/** Unit direction vector for (azimuth, elevation) in the AmbiX frame. */
+export function unitVector(azimuth: number, elevation: number): [number, number, number] {
+  const cosEl = Math.cos(elevation)
+  return [Math.cos(azimuth) * cosEl, Math.sin(azimuth) * cosEl, Math.sin(elevation)]
+}

package/src/spatial/sphere.ts

@@ -0,0 +1,36 @@
+/**
+ * Pure sphere mappings — SPATIAL.md §4 (canon rows SP1–SP5). The page is laid on the front
+ * hemisphere of a sphere around the listener; geometry becomes spherical source properties.
+ * No DOM, no Tone.
+ */
+import { clamp, norm } from '../math/util'
+import { DEG } from './sh'
+import type { Rect } from '../types'
+
+export const AZ_MAX = 70 * DEG
+export const EL_MAX = 45 * DEG
+
+/** SP1/SP2 — screen position → direction. Screen-right = −azimuth (sign tested). */
+export function sphereFromRect(rect: Rect, vw: number, vh: number): { azimuth: number; elevation: number } {
+  const tx = norm(rect.x + rect.w / 2, 0, vw)
+  const ty = norm(rect.y + rect.h / 2, 0, vh)
+  return {
+    azimuth: -(2 * tx - 1) * AZ_MAX,
+    elevation: (1 - 2 * ty) * EL_MAX,
+  }
+}
+
+/** SP4 — big elements wrap around the listener (T2 extended into space). */
+export function extentFromSize(sizeT: number): number {
+  return clamp(0.05 + 0.75 * Math.pow(clamp(sizeT, 0, 1), 1.2), 0, 0.95)
+}
+
+/** SP5 — Kiki/Bouba in the spatial domain: sharp beams, round radiates. */
+export function directivityFromRoundness(roundness: number): number {
+  return clamp(1 - roundness, 0, 1)
+}
+
+/** SP6 — early-reflection time scale follows the room (viewport). */
+export function reflectionScaleFromViewport(vw: number): number {
+  return 0.6 + norm(vw, 360, 2200) * 1.0
+}

package/src/themes/index.ts

@@ -0,0 +1,60 @@
+/**
+ * L3 Composition — themes are plain data (MAPPING.md §3). Adding a theme means adding an
+ * object here; no engine code may special-case a theme name.
+ */
+import type { Theme } from '../types'
+
+// v0.3: aurora speaks through the woven MatterVoice — geometry IS the instrument
+// (MATTER.md). fm bells (headings) and membrane thuds (media) stay as character voices.
+const aurora: Theme = {
+  name: 'aurora',
+  defaults: { synthKind: 'matter', octaveShift: 0, baseVelocity: 0.8, releaseScale: 1 },
+  roles: {
+    toggle: { synthKind: 'matter', baseVelocity: 0.7, releaseScale: 0.8 },
+    button: { synthKind: 'matter', baseVelocity: 0.9 },
+    link: { synthKind: 'matter', octaveShift: 1, baseVelocity: 0.6, releaseScale: 0.7 },
+    input: { synthKind: 'matter', baseVelocity: 0.55, releaseScale: 1.6 },
+    heading: { synthKind: 'fm', octaveShift: 0, baseVelocity: 0.75, releaseScale: 2.2 },
+    media: { synthKind: 'membrane', octaveShift: -1, baseVelocity: 0.8 },
+    item: { synthKind: 'matter', baseVelocity: 0.6, releaseScale: 0.8 },
+    text: { synthKind: 'matter', baseVelocity: 0.35, releaseScale: 1.8 },
+  },
+}
+
+const mono: Theme = {
+  name: 'mono',
+  defaults: { synthKind: 'synth', octaveShift: 0, baseVelocity: 0.7, releaseScale: 0.5 },
+  roles: {
+    toggle: { synthKind: 'noise', baseVelocity: 0.6 },
+    button: { synthKind: 'synth', pinWave: 'square', baseVelocity: 0.7, releaseScale: 0.4 },
+    link: { synthKind: 'noise', baseVelocity: 0.45, releaseScale: 0.3 },
+    input: { synthKind: 'synth', pinWave: 'sine', octaveShift: -1, baseVelocity: 0.5 },
+    heading: { synthKind: 'synth', pinWave: 'sine', octaveShift: 1, baseVelocity: 0.6 },
+    media: { synthKind: 'noise', baseVelocity: 0.55 },
+    item: { synthKind: 'noise', baseVelocity: 0.4, releaseScale: 0.3 },
+    text: { synthKind: 'synth', pinWave: 'sine', baseVelocity: 0 },
+  },
+}
+
+const paper: Theme = {
+  name: 'paper',
+  defaults: { synthKind: 'pluck', octaveShift: 0, baseVelocity: 0.8, releaseScale: 1 },
+  roles: {
+    toggle: { synthKind: 'pluck', baseVelocity: 0.7 },
+    button: { synthKind: 'pluck', baseVelocity: 0.9 },
+    link: { synthKind: 'pluck', octaveShift: 1, baseVelocity: 0.65 },
+    input: { synthKind: 'synth', pinWave: 'triangle', baseVelocity: 0.5, releaseScale: 1.4 },
+    heading: { synthKind: 'pluck', octaveShift: -1, baseVelocity: 0.85, releaseScale: 1.6 },
+    media: { synthKind: 'membrane', octaveShift: -1, baseVelocity: 0.7 },
+    item: { synthKind: 'pluck', baseVelocity: 0.6 },
+    text: { synthKind: 'synth', pinWave: 'sine', baseVelocity: 0.3, releaseScale: 1.6 },
+  },
+}
+
+export const THEMES: Record<string, Theme> = { aurora, mono, paper }
+
+export function resolveTheme(theme: string | Theme | undefined): Theme {
+  if (!theme) return aurora
+  if (typeof theme === 'string') return THEMES[theme] ?? aurora
+  return theme
+}

package/src/types.ts

@@ -0,0 +1,157 @@
+export type Wave = 'sine' | 'triangle' | 'sawtooth' | 'square'
+
+export type Role =
+  | 'toggle'
+  | 'button'
+  | 'link'
+  | 'input'
+  | 'heading'
+  | 'media'
+  | 'item'
+  | 'container'
+  | 'text'
+
+export type SynthKind = 'matter' | 'synth' | 'fm' | 'pluck' | 'membrane' | 'noise'
+
+export type Articulation =
+  | 'hit' | 'preview' | 'tick' | 'strum' | 'whisper' | 'toggle-on' | 'toggle-off' | 'motif'
+  | 'echo' | 'phrase' | 'ribbon'
+
+export interface Rect {
+  x: number
+  y: number
+  w: number
+  h: number
+}
+
+/** Spherical source properties — the 聲球 (SPATIAL.md §2, §4). */
+export interface SphereProps {
+  /** Radians, AmbiX convention: +azimuth = left. */
+  azimuth: number
+  /** Radians, + = up. */
+  elevation: number
+  /** Apparent angular size σ ∈ [0,1] — point source … wraps around the listener. */
+  extent: number
+  /** δ ∈ [0,1]: 1 = focused beam at the listener, 0 = omni radiator. */
+  directivity: number
+}
+
+/** The spat5.oper surface (SPATIAL.md §5) — all ∈ [0,1], perceptually monotonic. */
+export interface PerceptualFactors {
+  presence: number
+  roomPresence: number
+  envelopment: number
+  warmth: number
+  brilliance: number
+}
+
+/** The Matter weave, resolved per element (MATTER.md) — consumed by MatterVoice + backends. */
+export interface MatterVoiceParams {
+  matter: { edge: number; mass: number; texture: number; air: number }
+  /** 24 additive partial amplitudes, energy-normalized (the continuous spectrum). */
+  partials: number[]
+  transient: { lengthS: number; hpHz: number; level: number }
+  breath: { level: number; bpRatio: number }
+  subShimmer: { interval: number; level: number }
+  glideS: number
+  jitterCents: number
+  envelope: { attackS: number; decayS: number; sustain: number; releaseScale: number }
+  filter: { q: number; biteAmount: number; biteDecayS: number }
+  reverb: { sendScale: number; sendCutoffHz: number; bloom: number; extentBonus: number }
+  /** The modular patch (MODULAR.md): CSS plugs the cables. */
+  patch: {
+    fold: { drive: number; mix: number }
+    fm: { index: number }
+    unison: { detuneCents: number; mix: number }
+    lfo: { rateHz: number; shape: 'sine' | 'square'; vibratoCents: number; tremolo: number; filterDepth: number }
+    portamentoS: number
+  }
+}
+
+/** The contract between page reading (L1) and the audio substrate (L0). See ARCHITECTURE.md §2. */
+export interface SonicProfile {
+  role: Role
+  rect: Rect
+  pan: { x: number; y: number; z: number }
+  sphere: SphereProps
+  midi: number
+  freqHz: number
+  degree: number
+  wave: Wave
+  attack: number
+  release: number
+  durationS: number
+  filterHz: number
+  filterQ: number
+  velocityScale: number
+  reverbSend: number
+  synthKind: SynthKind
+  octaveShift: number
+  /** The full Matter weave (MATTER.md) — always computed; the 'matter' voice consumes all of
+   *  it, other synth kinds consume the reverb/filter threads. */
+  voice: MatterVoiceParams
+  /** The Chroma weave (CHROMA.md): the element's color as mood. */
+  chroma: { warmth: number; saturation: number; luminance: number }
+  /** Human-readable provenance of every parameter — describe() truth (PLAN.md Invariant #6). */
+  reasons: Record<string, string>
+}
+
+export interface VoiceRecipe {
+  synthKind: SynthKind
+  /** When set, geometry does not override the waveform (e.g. heading bells stay bells). */
+  pinWave?: Wave
+  octaveShift: number
+  baseVelocity: number
+  releaseScale: number
+}
+
+export interface Theme {
+  name: string
+  roles: Partial<Record<Role, Partial<VoiceRecipe>>>
+  defaults: VoiceRecipe
+}
+
+export interface SonariumOptions {
+  /** Root element to sonify. Default: document.body */
+  root?: Element
+  /** Sound palette. Default 'aurora'. */
+  theme?: 'aurora' | 'mono' | 'paper' | Theme
+  /** 'auto' = deterministic per-hostname key (MAPPING.md §0), or e.g. 'D dorian'. */
+  key?: string
+  /** Listener mode: cursor as ears, or fixed center. Default 'pointer'. */
+  listener?: 'pointer' | 'center'
+  /** Ambience level 0..1 (room tone + sparkles). Default 0.12; 0 disables. */
+  ambient?: number
+  /** Enable device tilt/shake drivers on mobile. Default true. */
+  motion?: boolean
+  /** Autoplay-unlock & mute UI. 'chip' = floating control, 'none' = bring your own. */
+  gate?: 'chip' | 'none'
+  /** Master volume in dB. Default -10. */
+  volume?: number
+  /** Max concurrent voices (pool size). Default 18, hard cap 24. */
+  maxVoices?: number
+  /** 'hrtf' (default) or 'equalpower' for low-end devices. */
+  panning?: 'hrtf' | 'equalpower'
+  /**
+   * Spatial engine (SPATIAL.md): 'ambisonic' (default) encodes everything into one rotatable
+   * FOA field, Spat-style; 'panner' is the v0.1 per-voice HRTF path (also the auto-fallback).
+   */
+  spatial?: 'ambisonic' | 'panner'
+  /** Spat-style perceptual factors (presence, roomPresence, envelopment, warmth, brilliance). */
+  perceptual?: Partial<PerceptualFactors>
+  /** Reverb: 'auto' sizes the room from viewport width, or a fixed decay in seconds. */
+  reverb?: 'auto' | number
+  /** Respect prefers-reduced-motion by softening output. Default true. */
+  respectReducedMotion?: boolean
+  /** Mirror every trigger to the first Web MIDI output (the page as a MIDI controller). Default false. */
+  midi?: boolean
+}
+
+export type SonariumEvent = 'start' | 'trigger' | 'mute' | 'dispose'
+
+export interface TriggerDetail {
+  el: Element
+  profile: SonicProfile
+  velocity: number
+  articulation: Articulation
+}

package/src/ui/gate.ts

@@ -0,0 +1,65 @@
+/**
+ * The unlock & mute chip — autoplay policy treated as a feature (PLAN.md R2).
+ * Shadow DOM so host styles can't break it; ARIA so keyboard/SR users get the same control.
+ */
+const STORAGE_KEY = 'sonarium:muted'
+
+export const isMutedPersisted = (): boolean => {
+  try { return localStorage.getItem(STORAGE_KEY) === '1' } catch { return false }
+}
+
+export const persistMuted = (muted: boolean): void => {
+  try { localStorage.setItem(STORAGE_KEY, muted ? '1' : '0') } catch { /* private mode */ }
+}
+
+export interface GateHandle {
+  setState: (state: 'armed' | 'on' | 'muted') => void
+  dispose: () => void
+}
+
+export function mountGate(onToggle: () => void): GateHandle {
+  const host = document.createElement('div')
+  host.setAttribute('data-sonic', 'off') // the chip itself must never sound
+  const shadow = host.attachShadow({ mode: 'open' })
+  shadow.innerHTML = `
+    <style>
+      button {
+        position: fixed; right: 16px; bottom: 16px; z-index: 2147483646;
+        width: 44px; height: 44px; border-radius: 50%; border: 1px solid rgba(255,255,255,.25);
+        background: rgba(20, 22, 30, .82); color: #fff; font-size: 18px; line-height: 1;
+        cursor: pointer; backdrop-filter: blur(8px); -webkit-backdrop-filter: blur(8px);
+        box-shadow: 0 4px 16px rgba(0,0,0,.35); transition: transform .15s ease, opacity .3s ease;
+      }
+      button:hover { transform: scale(1.08); }
+      button:focus-visible { outline: 2px solid #7cd4fd; outline-offset: 2px; }
+      button.armed { animation: pulse 1.6s ease-in-out infinite; }
+      @keyframes pulse { 0%,100% { box-shadow: 0 4px 16px rgba(0,0,0,.35); } 50% { box-shadow: 0 0 0 10px rgba(124,212,253,.18); } }
+    </style>
+    <button type="button" class="armed" aria-label="Enable sound" title="Sonarium — enable sound">🔇</button>
+  `
+  const btn = shadow.querySelector('button') as HTMLButtonElement
+  btn.addEventListener('click', (e) => {
+    e.stopPropagation()
+    onToggle()
+  })
+  document.body.appendChild(host)
+
+  return {
+    setState(state) {
+      btn.classList.toggle('armed', state === 'armed')
+      if (state === 'on') {
+        btn.textContent = '🔊'
+        btn.setAttribute('aria-label', 'Mute Sonarium')
+      } else if (state === 'muted') {
+        btn.textContent = '🔇'
+        btn.setAttribute('aria-label', 'Unmute Sonarium')
+      } else {
+        btn.textContent = '🔇'
+        btn.setAttribute('aria-label', 'Enable sound')
+      }
+    },
+    dispose() {
+      host.remove()
+    },
+  }
+}