sonarium 0.6.0

package/src/core/matter-voice.ts

@@ -0,0 +1,240 @@
+/**
+ * MatterVoice — the woven, modular instrument (MATTER.md §3 + MODULAR.md §2).
+ * Harmonic core (custom spectrum + sub/shimmer partner + unison twin) through a wavefolder,
+ * audio-rate FM cable from oscB, breath + burst noise layers, and one LFO patched from CSS
+ * (vibrato / tremolo / filter wobble). Supports one-shot triggers, sustained ribbon gating,
+ * and sleeping (all sources stop when idle; restart in place). Imports Tone only.
+ */
+import * as Tone from 'tone'
+import { foldCurve } from '../math/modular'
+import type { MatterVoiceParams } from '../types'
+
+export interface MatterTrigger {
+  freqHz: number
+  velocity: number
+  durationS: number
+  releaseScaleBase: number
+  voice: MatterVoiceParams
+}
+
+const FOLD_CURVE = foldCurve()
+
+export class MatterVoice {
+  /** Pool connects this to the lane filter's frequency param (LFO wobble tap). */
+  readonly modFilterOut: Tone.Gain
+
+  private oscA: Tone.Oscillator
+  private oscA2: Tone.Oscillator
+  private oscB: Tone.Oscillator
+  private oscBGain: Tone.Gain
+  private fmGain: Tone.Gain
+  private foldPre: Tone.Gain
+  private foldShaper: Tone.WaveShaper
+  private foldWet: Tone.Gain
+  private foldDry: Tone.Gain
+  private unisonGain: Tone.Gain
+  private breathNoise: Tone.Noise
+  private breathFilter: Tone.Filter
+  private breathGain: Tone.Gain
+  private burstNoise: Tone.Noise
+  private burstFilter: Tone.Filter
+  private burstEnv: Tone.AmplitudeEnvelope
+  private ampEnv: Tone.AmplitudeEnvelope
+  private mix: Tone.Gain
+  private lfo: Tone.LFO
+  private lfoVib: Tone.Gain
+  private lfoTrem: Tone.Gain
+  private out: Tone.Gain
+  private startedSources = false
+  private held = false
+
+  constructor() {
+    this.out = new Tone.Gain(1)
+    this.mix = new Tone.Gain(0.9)
+
+    this.oscA = new Tone.Oscillator({ frequency: 220 })
+    this.oscA2 = new Tone.Oscillator({ frequency: 220 })
+    this.oscB = new Tone.Oscillator({ frequency: 110, type: 'sine' })
+    this.oscBGain = new Tone.Gain(0.2)
+
+    // The wavefolder (MODULAR.md M1): oscA splits dry/folded; envelope sweeps the fold.
+    this.foldPre = new Tone.Gain(0.3)
+    this.foldShaper = new Tone.WaveShaper(FOLD_CURVE)
+    this.foldWet = new Tone.Gain(0)
+    this.foldDry = new Tone.Gain(1)
+    this.oscA.connect(this.foldPre)
+    this.foldPre.connect(this.foldShaper)
+    this.foldShaper.connect(this.foldWet)
+    this.foldWet.connect(this.mix)
+    this.oscA.connect(this.foldDry)
+    this.foldDry.connect(this.mix)
+
+    // Unison twin stays clean (thickness without mud).
+    this.unisonGain = new Tone.Gain(0)
+    this.oscA2.connect(this.unisonGain)
+    this.unisonGain.connect(this.mix)
+
+    // The FM cable (M2): oscB modulates oscA's frequency at audio rate.
+    this.fmGain = new Tone.Gain(0)
+    this.oscB.connect(this.fmGain)
+    this.fmGain.connect(this.oscA.frequency)
+    this.oscB.connect(this.oscBGain)
+    this.oscBGain.connect(this.mix)
+
+    this.breathNoise = new Tone.Noise('pink')
+    this.breathFilter = new Tone.Filter({ type: 'bandpass', frequency: 600, Q: 1.1 })
+    this.breathGain = new Tone.Gain(0)
+    this.breathNoise.connect(this.breathFilter)
+    this.breathFilter.connect(this.breathGain)
+    this.breathGain.connect(this.mix)
+
+    this.ampEnv = new Tone.AmplitudeEnvelope({ attack: 0.01, decay: 0.2, sustain: 0.25, release: 0.3 })
+    this.mix.connect(this.ampEnv)
+    this.ampEnv.connect(this.out)
+
+    // The /k/ of kiki: bypasses the amp envelope so it stays a crisp onset event.
+    this.burstNoise = new Tone.Noise('white')
+    this.burstFilter = new Tone.Filter({ type: 'highpass', frequency: 3000 })
+    this.burstEnv = new Tone.AmplitudeEnvelope({ attack: 0.001, decay: 0.02, sustain: 0, release: 0.02 })
+    this.burstNoise.connect(this.burstFilter)
+    this.burstFilter.connect(this.burstEnv)
+    this.burstEnv.connect(this.out)
+
+    // One LFO, three depth taps (M4/M5): vibrato, tremolo, filter wobble.
+    this.lfo = new Tone.LFO({ frequency: 0.5, min: -1, max: 1, type: 'sine' })
+    this.lfoVib = new Tone.Gain(0)
+    this.lfoTrem = new Tone.Gain(0)
+    this.modFilterOut = new Tone.Gain(0)
+    this.lfo.connect(this.lfoVib)
+    this.lfo.connect(this.lfoTrem)
+    this.lfo.connect(this.modFilterOut)
+    this.lfoVib.connect(this.oscA.detune)
+    this.lfoVib.connect(this.oscA2.detune)
+    this.lfoTrem.connect(this.mix.gain)
+  }
+
+  connect(dest: Tone.InputNode): this {
+    this.out.connect(dest)
+    return this
+  }
+
+  private ensureRunning(when: number): void {
+    if (this.startedSources) return
+    this.startedSources = true
+    this.oscA.start(when)
+    this.oscA2.start(when)
+    this.oscB.start(when)
+    this.breathNoise.start(when)
+    this.burstNoise.start(when)
+    this.lfo.start(when)
+  }
+
+  /** MODULAR.md §4 — idle lanes power down completely; the next trigger restarts in place. */
+  sleep(): void {
+    if (!this.startedSources || this.held) return
+    this.startedSources = false
+    try {
+      this.oscA.stop()
+      this.oscA2.stop()
+      this.oscB.stop()
+      this.breathNoise.stop()
+      this.burstNoise.stop()
+      this.lfo.stop()
+    } catch { /* already stopped */ }
+  }
+
+  /** Everything both trigger() and gateOn() share: spectrum, patch, pitch, modulation. */
+  private applyVoice(t: MatterTrigger, when: number, baseCutoffHz: number): void {
+    const v = t.voice
+    this.ensureRunning(when)
+    this.oscA.partials = v.partials
+    this.oscA2.partials = v.partials
+
+    // Pitch behaviour: glide for round (+M6 portamento), jitter for rough texture.
+    const jitter = (Math.random() * 2 - 1) * v.jitterCents
+    this.oscA.detune.setValueAtTime(jitter, when)
+    const glide = v.glideS + v.patch.portamentoS
+    if (glide > 0.002 && !this.held) {
+      this.oscA.frequency.setValueAtTime(t.freqHz * 0.917, when)
+      this.oscA.frequency.rampTo(t.freqHz, glide, when)
+    } else {
+      this.oscA.frequency.setValueAtTime(t.freqHz, when)
+    }
+    this.oscA2.frequency.setValueAtTime(t.freqHz, when)
+    this.oscA2.detune.setValueAtTime(jitter + v.patch.unison.detuneCents, when)
+    this.unisonGain.gain.rampTo(v.patch.unison.mix, 0.02, when)
+    this.oscB.frequency.setValueAtTime(t.freqHz * Math.pow(2, v.subShimmer.interval / 12), when)
+    this.oscBGain.gain.rampTo(v.subShimmer.level, 0.02, when)
+
+    // Modular patch: fold drive/mix, FM index (× carrier), LFO rate/shape/depths.
+    this.foldPre.gain.rampTo(0.3 + v.patch.fold.drive * 1.2, 0.02, when)
+    this.foldWet.gain.rampTo(v.patch.fold.mix, 0.02, when)
+    this.foldDry.gain.rampTo(1 - v.patch.fold.mix * 0.7, 0.02, when)
+    this.fmGain.gain.rampTo(v.patch.fm.index * t.freqHz, 0.02, when)
+    const lfoOn = v.patch.lfo.rateHz > 0.01
+    this.lfo.frequency.value = Math.max(0.01, v.patch.lfo.rateHz)
+    this.lfo.type = v.patch.lfo.shape
+    this.lfoVib.gain.rampTo(lfoOn ? v.patch.lfo.vibratoCents : 0, 0.05, when)
+    this.lfoTrem.gain.rampTo(lfoOn ? 0.9 * v.patch.lfo.tremolo : 0, 0.05, when)
+    this.modFilterOut.gain.rampTo(lfoOn ? v.patch.lfo.filterDepth * baseCutoffHz : 0, 0.05, when)
+
+    // Breath rides the tone (common fate = fusion).
+    this.breathFilter.frequency.rampTo(Math.min(8000, t.freqHz * v.breath.bpRatio), 0.02, when)
+    this.breathGain.gain.rampTo(v.breath.level, 0.02, when)
+
+    // Envelope weave.
+    this.ampEnv.attack = v.envelope.attackS
+    this.ampEnv.decay = v.envelope.decayS
+    this.ampEnv.sustain = v.envelope.sustain
+    this.ampEnv.release = 0.3 * t.releaseScaleBase * v.envelope.releaseScale
+  }
+
+  trigger(t: MatterTrigger, when: number, baseCutoffHz = 4000): void {
+    this.applyVoice(t, when, baseCutoffHz)
+    this.ampEnv.triggerAttackRelease(t.durationS, when, t.velocity)
+    if (t.voice.transient.level > 0.02) {
+      this.burstFilter.frequency.setValueAtTime(t.voice.transient.hpHz, when)
+      this.burstEnv.decay = t.voice.transient.lengthS
+      this.burstEnv.triggerAttackRelease(t.voice.transient.lengthS, when, t.velocity * t.voice.transient.level)
+    }
+  }
+
+  // ----------------------------------------------------------- ribbon (MODULAR.md §3)
+
+  gateOn(t: MatterTrigger, when: number, baseCutoffHz = 4000): void {
+    this.applyVoice(t, when, baseCutoffHz)
+    this.held = true
+    this.ampEnv.sustain = Math.max(0.4, t.voice.envelope.sustain)
+    this.ampEnv.triggerAttack(when, t.velocity)
+  }
+
+  /** Ribbon pitch move — quantized upstream; the portamento IS the glissando feel. */
+  setFreq(freqHz: number, glideS: number, subInterval: number, fmIndex: number): void {
+    const g = Math.max(0.015, glideS)
+    this.oscA.frequency.rampTo(freqHz, g)
+    this.oscA2.frequency.rampTo(freqHz, g)
+    this.oscB.frequency.rampTo(freqHz * Math.pow(2, subInterval / 12), g)
+    this.fmGain.gain.rampTo(fmIndex * freqHz, g)
+  }
+
+  gateOff(when?: number): number {
+    this.held = false
+    this.ampEnv.triggerRelease(when ?? Tone.now())
+    return this.ampEnv.release as number
+  }
+
+  releaseTail(): number {
+    return this.ampEnv.release as number
+  }
+
+  dispose(): void {
+    for (const n of [
+      this.oscA, this.oscA2, this.oscB, this.oscBGain, this.fmGain,
+      this.foldPre, this.foldShaper, this.foldWet, this.foldDry, this.unisonGain,
+      this.breathNoise, this.breathFilter, this.breathGain,
+      this.burstNoise, this.burstFilter, this.burstEnv,
+      this.lfo, this.lfoVib, this.lfoTrem, this.modFilterOut,
+      this.ampEnv, this.mix, this.out,
+    ]) n.dispose()
+  }
+}

package/src/core/profile.ts

@@ -0,0 +1,313 @@
+/**
+ * L1 Page Reading — element → SonicProfile. Imports math + DOM, never Tone
+ * (ARCHITECTURE.md §1 dependency rules).
+ */
+import {
+  attackFromRoundness, brightnessTilt, cutoffFromDepth, degreeFromSize, durationFromElongation,
+  panX, panY, pitchNudgeFromRoundness, qFromRoundness, roundness, sendFromShadowBlur, sizeT,
+  stepsFromHeadingLevel, stepsFromSiblingIndex, velocityFromDepth, velocityFromSize,
+  waveFromRoundness, zBonusFromZIndex, zFromDepth,
+} from '../math/mapping'
+import { clamp } from '../math/util'
+import { degreeToMidi, midiToFreq, midiToNoteName, type SiteKey } from '../math/scales'
+import {
+  breath, deriveMatter, detuneJitterCents, envelopeWeave, filterWeave, genPartials, glideS,
+  reverbWeave, subShimmer, transient,
+} from '../math/matter'
+import {
+  attackScaleFromWarmth, brightnessFromLuminance, chromaOf, parseCssColor,
+  richnessFromSaturation, subBonusFromWarmth, velocityFromLuminance, type Chroma,
+} from '../math/chroma'
+import { massBonusFromFontWeight, patchFrom, type ModularVisuals } from '../math/modular'
+import { directivityFromRoundness, extentFromSize, sphereFromRect } from '../spatial/sphere'
+import { directivityFilterScale } from '../spatial/perceptual'
+import { DEG } from '../spatial/sh'
+import type { MatterVoiceParams, Rect, Role, SonicProfile, SphereProps, Theme, VoiceRecipe, Wave } from '../types'
+
+const HEADING = /^H[1-6]$/
+
+export function roleOf(el: Element): Role {
+  const aria = (el.getAttribute('role') || '').toLowerCase()
+  const override = (el as HTMLElement).dataset?.sonicRole as Role | undefined
+  if (override) return override
+  const tag = el.tagName
+  const type = (el.getAttribute('type') || '').toLowerCase()
+  if (tag === 'INPUT' && (type === 'checkbox' || type === 'radio')) return 'toggle'
+  if (aria === 'switch' || aria === 'checkbox' || tag === 'SUMMARY') return 'toggle'
+  if (tag === 'BUTTON' || aria === 'button' || (tag === 'INPUT' && (type === 'button' || type === 'submit' || type === 'reset'))) return 'button'
+  if ((tag === 'A' && el.hasAttribute('href')) || aria === 'link') return 'link'
+  if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || (el as HTMLElement).isContentEditable) return 'input'
+  if (HEADING.test(tag) || aria === 'heading') return 'heading'
+  if (tag === 'IMG' || tag === 'VIDEO' || tag === 'SVG' || tag === 'CANVAS' || tag === 'PICTURE' || tag === 'AUDIO') return 'media'
+  if (tag === 'LI' || tag === 'TR' || ['listitem', 'option', 'menuitem', 'tab'].includes(aria)) return 'item'
+  if (['NAV', 'SECTION', 'ARTICLE', 'ASIDE', 'FORM', 'FIELDSET', 'HEADER', 'FOOTER', 'MAIN', 'DIALOG'].includes(tag)) return 'container'
+  if (['navigation', 'region', 'group', 'list', 'menu', 'tablist', 'dialog'].includes(aria)) return 'container'
+  if (tag === 'P' || tag === 'BLOCKQUOTE' || tag === 'LABEL' || tag === 'SPAN') return 'text'
+  return 'container'
+}
+
+export function domDepth(el: Element, root: Element): number {
+  let d = 0
+  let n: Element | null = el
+  while (n && n !== root && d < 32) {
+    n = n.parentElement
+    d++
+  }
+  return d
+}
+
+function eligibleSiblingIndex(el: Element): number {
+  const parent = el.parentElement
+  if (!parent) return 0
+  let i = 0
+  for (const sib of Array.from(parent.children)) {
+    if (sib === el) return i
+    if (sib.tagName === el.tagName || roleOf(sib) === roleOf(el)) i++
+  }
+  return 0
+}
+
+function recipeFor(role: Role, theme: Theme): VoiceRecipe {
+  return { ...theme.defaults, ...(theme.roles[role] ?? {}) }
+}
+
+function isQuiet(el: Element): boolean {
+  let n: Element | null = el
+  while (n) {
+    if ((n as HTMLElement).dataset?.sonic === 'quiet') return true
+    n = n.parentElement
+  }
+  return false
+}
+
+const NOTE_RE = /^([A-Ga-g][#b]?)(-?\d)$/
+function pinnedMidi(spec: string | undefined): number | null {
+  if (!spec) return null
+  const m = spec.trim().match(NOTE_RE)
+  if (!m) return null
+  const pcs: 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 name = (m[1] as string).charAt(0).toUpperCase() + (m[1] as string).slice(1)
+  const pc = pcs[name]
+  if (pc === undefined) return null
+  return (parseInt(m[2] as string, 10) + 1) * 12 + pc
+}
+
+export interface ProfileEnv {
+  root: Element
+  key: SiteKey
+  theme: Theme
+  vw: number
+  vh: number
+}
+
+/** CSS custom property, trimmed; '' when unset. Inherits down the tree (the aural stylesheet). */
+function sonicVar(cs: CSSStyleDeclaration, name: string): string {
+  return cs.getPropertyValue(name).trim()
+}
+
+/** Compute the full acoustic identity of an element. Pure given (el state, env). */
+export function profileOf(el: Element, env: ProfileEnv): SonicProfile {
+  const { key, theme, vw, vh } = env
+  const html = el as HTMLElement
+  const reasons: Record<string, string> = {}
+
+  const cs = getComputedStyle(el)
+  const r = el.getBoundingClientRect()
+  const rect: Rect = { x: r.x, y: r.y, w: Math.max(1, r.width), h: Math.max(1, r.height) }
+  // Priority: data-sonic-role > --sonic-role > inference (CHROMA.md §4).
+  const role = (html.dataset?.sonicRole as Role | undefined)
+    || (sonicVar(cs, '--sonic-role') as Role | '')
+    || roleOf(el)
+  const recipe = recipeFor(role, theme)
+  reasons.role = `<${el.tagName.toLowerCase()}> reads as "${role}" → ${recipe.synthKind} voice (theme ${theme.name})`
+  // border-radius percentages survive into computed style — resolve against the box.
+  const radiusRaw = cs.borderTopLeftRadius
+  const radiusPx = radiusRaw.endsWith('%')
+    ? ((parseFloat(radiusRaw) || 0) / 100) * Math.min(rect.w, rect.h)
+    : parseFloat(radiusRaw) || 0
+  const opacity = parseFloat(cs.opacity)
+  const shadowBlur = parseShadowBlur(cs.boxShadow)
+  const zIndex = cs.position !== 'static' ? parseInt(cs.zIndex, 10) || 0 : 0
+
+  // Space (G1, G2, S1, S5)
+  const depth = domDepth(el, env.root)
+  const pan = {
+    x: panX(rect, vw),
+    y: panY(rect, vh),
+    z: zFromDepth(depth) + zBonusFromZIndex(zIndex),
+  }
+  reasons.position = `center (${Math.round(rect.x + rect.w / 2)}, ${Math.round(rect.y + rect.h / 2)}) px → (${pan.x.toFixed(1)}, ${pan.y.toFixed(1)}) m; depth ${depth} → ${pan.z.toFixed(1)} m away`
+
+  // Pitch (G4, S4, S6, G10) through the quantizer
+  const st = sizeT(rect, vw, vh)
+  const degree = degreeFromSize(st)
+  const round = roundness(radiusPx, rect)
+  let steps = stepsFromSiblingIndex(eligibleSiblingIndex(el), key.scale.length) + pitchNudgeFromRoundness(round)
+  if (role === 'heading') {
+    const level = HEADING.test(el.tagName) ? parseInt(el.tagName[1] as string, 10) : 2
+    steps += stepsFromHeadingLevel(level)
+  }
+  steps += recipe.octaveShift * key.scale.length
+  const pinned = pinnedMidi(html.dataset?.sonicNote ?? sonicVar(cs, '--sonic-note') ?? undefined)
+  const midi = pinned ?? degreeToMidi(degree, key, steps)
+  reasons.pitch = pinned !== null
+    ? `pinned by data-sonic-note → ${midiToNoteName(midi)}`
+    : `area ${(rect.w * rect.h / 1000).toFixed(1)}k px² (size ${st.toFixed(2)}) + sibling/heading offsets → ${midiToNoteName(midi)} in ${key.label}`
+
+  // Timbre (G6–G9) — Kiki/Bouba
+  const wave: Wave = (html.dataset?.sonicWave as Wave)
+    || (sonicVar(cs, '--sonic-wave') as Wave | '')
+    || recipe.pinWave
+    || waveFromRoundness(round)
+  const attack = attackFromRoundness(round)
+  reasons.timbre = `roundness ${round.toFixed(2)} (radius ${radiusPx}px) → ${wave} wave, ${(attack * 1000).toFixed(0)} ms attack`
+
+  // Duration (G11)
+  const durationS = durationFromElongation(rect)
+  reasons.duration = `aspect ${(Math.max(rect.w, rect.h) / Math.min(rect.w, rect.h)).toFixed(1)}:1 → ${durationS.toFixed(2)} s`
+
+  // Sphere — the 聲球 (SPATIAL.md SP1–SP5)
+  const dir = sphereFromRect(rect, vw, vh)
+  const extentOverride = parseFloat(html.dataset?.sonicExtent ?? sonicVar(cs, '--sonic-extent'))
+  const sphere: SphereProps = {
+    azimuth: dir.azimuth,
+    elevation: dir.elevation,
+    extent: isNaN(extentOverride) ? extentFromSize(st) : clamp(extentOverride, 0, 1),
+    directivity: directivityFromRoundness(round),
+  }
+  reasons.sphere = `az ${(sphere.azimuth / DEG).toFixed(0)}°, el ${(sphere.elevation / DEG).toFixed(0)}°, extent ${sphere.extent.toFixed(2)} (size wraps the listener), directivity ${sphere.directivity.toFixed(2)} (sharp beams, round radiates)`
+
+  // The Chroma weave (CHROMA.md §1) — the element's color as mood, extracted once, used below.
+  const chroma = elementChroma(el, cs, role)
+
+  // Filter (S2 · G3, G9, CH1) — depth, height, directivity and color luminance share the cutoff
+  const filterHz = cutoffFromDepth(depth) * brightnessTilt(rect, vh)
+    * directivityFilterScale(sphere.directivity) * brightnessFromLuminance(chroma.luminance)
+  reasons.filter = `depth ${depth} + vertical position + directivity + luminance → low-pass ${Math.round(filterHz)} Hz`
+
+  // Loudness (G5, G12, S3, CH2, quiet via attribute or --sonic custom property)
+  let velocityScale = recipe.baseVelocity * velocityFromSize(st) * velocityFromDepth(depth)
+    * (isNaN(opacity) ? 1 : opacity) * velocityFromLuminance(chroma.luminance)
+  const sonicMode = sonicVar(cs, '--sonic')
+  if (isQuiet(el) || sonicMode === 'quiet') velocityScale *= 0.4
+  if (sonicMode === 'off') {
+    velocityScale = 0
+    reasons.silenced = '--sonic: off (aural stylesheet)'
+  }
+  velocityScale = clamp(velocityScale, 0, 1.5)
+
+  // The Matter weave (MATTER.md §2) — one material, many co-varying cues.
+  const elongation = Math.max(rect.w, rect.h) / Math.max(1, Math.min(rect.w, rect.h))
+  const textish = role === 'text' || role === 'heading' || role === 'link' || role === 'button'
+  const fontWeight = textish ? parseInt(cs.fontWeight, 10) || 400 : 400
+  const matter = deriveMatter({
+    roundness: round,
+    sizeT: st,
+    depth,
+    shadowBlurPx: shadowBlur,
+    opacity: isNaN(opacity) ? 1 : opacity,
+    dashedBorder: cs.borderTopStyle === 'dashed' || cs.borderTopStyle === 'dotted',
+    isMedia: role === 'media',
+    backdropBlurPx: parseBackdropBlur(cs),
+    massBonus: massBonusFromFontWeight(fontWeight),
+  })
+
+  // The modular patch (MODULAR.md §1) — CSS plugs the cables.
+  const modVisuals: ModularVisuals = {
+    animationS: cs.animationName && cs.animationName !== 'none' ? firstSeconds(cs.animationDuration) : 0,
+    borderStyle: (['solid', 'dashed', 'dotted'].includes(cs.borderTopStyle) ? cs.borderTopStyle : 'none') as ModularVisuals['borderStyle'],
+    borderWidthPx: parseFloat(cs.borderTopWidth) || 0,
+    transitionS: firstSeconds(cs.transitionDuration),
+  }
+  const patch = patchFrom(matter, modVisuals)
+  // Chroma tints the matter (CH3–CH5) — never a second instrument.
+  const env0 = envelopeWeave(matter.edge, matter.mass)
+  const sub0 = subShimmer(matter.mass)
+  const voice: MatterVoiceParams = {
+    matter,
+    partials: Array.from(genPartials(matter.edge, elongation, richnessFromSaturation(chroma.saturation))),
+    transient: transient(matter.edge),
+    breath: breath(matter.texture),
+    subShimmer: {
+      interval: sub0.interval,
+      level: sub0.level + (sub0.interval < 0 ? subBonusFromWarmth(chroma.warmth) : 0),
+    },
+    glideS: glideS(matter.edge),
+    jitterCents: detuneJitterCents(matter.texture),
+    envelope: { ...env0, attackS: env0.attackS * attackScaleFromWarmth(chroma.warmth) },
+    filter: filterWeave(matter.edge),
+    reverb: reverbWeave(matter.edge, matter.mass, matter.texture),
+    patch,
+  }
+  if (patch.fold.mix > 0.05 || patch.fm.index > 0.05 || patch.lfo.rateHz > 0.01 || patch.unison.mix > 0) {
+    reasons.patch = [
+      patch.fold.mix > 0.05 ? `border drives the wavefolder ×${patch.fold.drive.toFixed(2)}` : '',
+      patch.fm.index > 0.05 ? `FM ring ${patch.fm.index.toFixed(2)}` : '',
+      patch.unison.mix > 0 ? `unison +${patch.unison.detuneCents.toFixed(0)}¢` : '',
+      patch.lfo.rateHz > 0.01 ? `${patch.lfo.shape} LFO ${patch.lfo.rateHz.toFixed(2)} Hz (${modVisuals.animationS > 0 ? 'css animation' : 'dashed border'})` : '',
+    ].filter(Boolean).join(' · ')
+  }
+  reasons.chroma = `warmth ${chroma.warmth.toFixed(2)} · sat ${chroma.saturation.toFixed(2)} · lum ${chroma.luminance.toFixed(2)} → ${chroma.warmth > 0.6 ? 'eager onset, full body' : chroma.warmth < 0.4 ? 'cool, unhurried onset' : 'neutral temperament'}${chroma.saturation > 0.5 ? ', vivid spectrum' : ''}`
+  reasons.matter = `edge ${matter.edge.toFixed(2)} · mass ${matter.mass.toFixed(2)} · texture ${matter.texture.toFixed(2)} · air ${matter.air.toFixed(2)} → ${voice.transient.level > 0.1 ? 'clicky' : 'soft'}, ${voice.breath.level > 0.05 ? 'breathy' : 'clean'}, ${voice.subShimmer.interval < 0 ? 'chest sub' : 'sparkle +8va'}, ${voice.reverb.bloom > 0.5 ? 'blooms into the room' : 'dry strike'}`
+
+  // Room (G13 + MATTER reverb weave + SP3 distance wetness)
+  const reverbSend = clamp(
+    (0.18 + sendFromShadowBlur(shadowBlur) + 0.05 * Math.min(depth, 10) * 0.5) * voice.reverb.sendScale,
+    0,
+    1.2,
+  )
+
+  return {
+    role, rect, pan, sphere,
+    midi, freqHz: midiToFreq(midi), degree,
+    wave, attack, release: 0.3 * recipe.releaseScale, durationS,
+    filterHz, filterQ: qFromRoundness(round),
+    velocityScale, reverbSend,
+    synthKind: recipe.synthKind, octaveShift: recipe.octaveShift,
+    voice, chroma,
+    reasons,
+  }
+}
+
+/** CHROMA.md §1 — text-ish roles speak in their text color; boxes speak in their background,
+ *  walking up past transparent ancestors. */
+function elementChroma(el: Element, cs: CSSStyleDeclaration, role: Role): Chroma {
+  if (role === 'text' || role === 'heading' || role === 'link') {
+    return chromaOf(parseCssColor(cs.color))
+  }
+  let probe: Element | null = el
+  let style: CSSStyleDeclaration | undefined = cs
+  for (let hops = 0; probe && hops < 6; hops++) {
+    const rgb = parseCssColor((style ?? getComputedStyle(probe)).backgroundColor)
+    if (rgb && rgb.a >= 0.05) return chromaOf(rgb)
+    probe = probe.parentElement
+    style = undefined
+  }
+  return chromaOf(parseCssColor(getComputedStyle(document.documentElement).backgroundColor))
+}
+
+/** First duration in a comma list ("2s, 0.5s" → 2; "250ms" → 0.25). */
+function firstSeconds(list: string): number {
+  const first = (list || '').split(',')[0]?.trim() ?? ''
+  if (!first) return 0
+  const v = parseFloat(first)
+  if (isNaN(v)) return 0
+  return first.endsWith('ms') ? v / 1000 : v
+}
+
+function parseBackdropBlur(cs: CSSStyleDeclaration): number {
+  const bf = cs.backdropFilter || (cs as unknown as Record<string, string>).webkitBackdropFilter || ''
+  const m = bf.match(/blur\((\d+(\.\d+)?)px\)/)
+  return m ? parseFloat(m[1] as string) : 0
+}
+
+function parseShadowBlur(boxShadow: string): number {
+  if (!boxShadow || boxShadow === 'none') return 0
+  // blur is the 3rd length in each shadow; take the max across shadows
+  let max = 0
+  for (const part of boxShadow.split(/,(?![^(]*\))/)) {
+    const lengths = part.match(/-?\d+(\.\d+)?px/g)
+    if (lengths && lengths.length >= 3) max = Math.max(max, parseFloat(lengths[2] as string))
+  }
+  return max
+}

package/src/core/room.ts

@@ -0,0 +1,135 @@
+/**
+ * L0 Acoustic Substrate — the Room: master chain (spatial input → warmth/brilliance shelves →
+ * volume → limiter), viewport-sized reverb (S7/S8), ambience (I13), visibility fading (I14),
+ * mute. In 'panner' mode it also owns the classic dry/wet routing; in 'ambisonic' mode the
+ * AmbisonicBackend consumes `reverb` and `spatialIn` directly (SPATIAL.md §6). Imports Tone only.
+ */
+import * as Tone from 'tone'
+import { ambienceCutoffFromViewport, reverbFromViewport } from '../math/mapping'
+import { clamp } from '../math/util'
+import { brillianceDb, warmthDb, type PerceptualFactors } from '../spatial/perceptual'
+import type { VoiceBuses } from './voices'
+
+export interface RoomOptions {
+  volumeDb: number
+  reverb: 'auto' | number
+  ambient: number
+  mode: 'panner' | 'ambisonic'
+}
+
+export class Room {
+  /** Classic v0.1 buses — meaningful in 'panner' mode (dryIn = spatialIn, wetIn = reverb). */
+  readonly buses: VoiceBuses
+  /** Everything audible enters here (gets the perceptual EQ + limiter). */
+  readonly spatialIn: Tone.Gain
+  readonly reverb: Tone.Reverb
+
+  private master: Tone.Volume
+  private limiter: Tone.Limiter
+  private lowShelf: Tone.Filter
+  private highShelf: Tone.Filter
+  private wetGain: Tone.Gain | null = null
+  private noise: Tone.Noise | null = null
+  private noiseFilter: Tone.Filter | null = null
+  private noiseGain: Tone.Gain | null = null
+  private rushGain: Tone.Gain | null = null
+  private resizeTimer: ReturnType<typeof setTimeout> | null = null
+  private mutedNow = false
+  private toneScale = 1
+
+  constructor(private opts: RoomOptions, vw: number, factors: PerceptualFactors) {
+    this.limiter = new Tone.Limiter(-1).toDestination()
+    this.master = new Tone.Volume(opts.volumeDb).connect(this.limiter)
+    this.highShelf = new Tone.Filter({ type: 'highshelf', frequency: 4000, gain: brillianceDb(factors.brilliance) }).connect(this.master)
+    this.lowShelf = new Tone.Filter({ type: 'lowshelf', frequency: 250, gain: warmthDb(factors.warmth) }).connect(this.highShelf)
+    this.spatialIn = new Tone.Gain(1).connect(this.lowShelf)
+
+    const { decay, wet } = this.roomParams(vw)
+    this.reverb = new Tone.Reverb({ decay, preDelay: 0.02, wet: 1 })
+    if (opts.mode === 'panner') {
+      this.wetGain = new Tone.Gain(wet).connect(this.spatialIn)
+      this.reverb.connect(this.wetGain)
+    }
+    this.buses = { dryIn: this.spatialIn, wetIn: this.reverb }
+  }
+
+  setFactors(f: PerceptualFactors): void {
+    this.lowShelf.gain.rampTo(warmthDb(f.warmth), 0.1)
+    this.highShelf.gain.rampTo(brillianceDb(f.brilliance), 0.1)
+  }
+
+  private roomParams(vw: number): { decay: number; wet: number } {
+    if (this.opts.reverb !== 'auto') {
+      const decay = clamp(Number(this.opts.reverb) || 1.5, 0.1, 12)
+      return { decay, wet: 0.25 }
+    }
+    return reverbFromViewport(vw)
+  }
+
+  /** Debounced: Tone.Reverb regenerates its impulse response when decay changes. */
+  resize(vw: number): void {
+    if (this.resizeTimer) clearTimeout(this.resizeTimer)
+    this.resizeTimer = setTimeout(() => {
+      const { decay, wet } = this.roomParams(vw)
+      try {
+        this.reverb.decay = decay
+        this.wetGain?.gain.rampTo(wet, 0.3)
+        this.noiseFilter?.frequency.rampTo(ambienceCutoffFromViewport(vw) * this.toneScale, 0.5)
+      } catch (err) {
+        console.warn('[sonarium] room resize failed', err)
+      }
+    }, 400)
+  }
+
+  /** I13 — room tone (sparkles became the phrase engine, PULSE.md §3). toneScale = CH7 warmth. */
+  startAmbience(vw: number, level: number, toneScale = 1): void {
+    if (level <= 0) return
+    this.toneScale = toneScale
+    this.noise = new Tone.Noise('brown')
+    this.noiseFilter = new Tone.Filter({ frequency: ambienceCutoffFromViewport(vw) * toneScale, type: 'lowpass' })
+    this.noiseGain = new Tone.Gain(Tone.dbToGain(-46) * clamp(level / 0.12, 0, 3))
+    this.noise.connect(this.noiseFilter)
+    this.noiseFilter.connect(this.noiseGain)
+    this.noiseGain.connect(this.spatialIn)
+    // Air-rush path (MATTER.md §2.2): scroll velocity swells the same room-tone noise.
+    this.rushGain = new Tone.Gain(0)
+    this.noiseFilter.connect(this.rushGain)
+    this.rushGain.connect(this.spatialIn)
+    this.noise.start()
+  }
+
+  /** MATTER.md §2.2 — moving through the page moves air. Swells fast, decays in ~450 ms. */
+  rush(level: number): void {
+    if (!this.rushGain || this.mutedNow) return
+    const now = Tone.now()
+    this.rushGain.gain.cancelScheduledValues(now)
+    this.rushGain.gain.rampTo(level, 0.05, now)
+    this.rushGain.gain.rampTo(0, 0.45, now + 0.07)
+  }
+
+  /** I14 — never sound in a background tab. */
+  setHidden(hidden: boolean): void {
+    if (this.mutedNow) return
+    this.master.volume.rampTo(hidden ? -Infinity : this.opts.volumeDb, 0.3)
+  }
+
+  setMuted(muted: boolean): void {
+    this.mutedNow = muted
+    this.master.volume.rampTo(muted ? -Infinity : this.opts.volumeDb, 0.15)
+  }
+
+  dispose(): void {
+    if (this.resizeTimer) clearTimeout(this.resizeTimer)
+    this.noise?.dispose()
+    this.noiseFilter?.dispose()
+    this.noiseGain?.dispose()
+    this.rushGain?.dispose()
+    this.reverb.dispose()
+    this.wetGain?.dispose()
+    this.spatialIn.dispose()
+    this.lowShelf.dispose()
+    this.highShelf.dispose()
+    this.master.dispose()
+    this.limiter.dispose()
+  }
+}