sonarium 0.6.0

package/src/interact/motion.ts

@@ -0,0 +1,61 @@
+/**
+ * L2 — embodied motion: device tilt steers the ears (I10), a shake strums the visible
+ * page left→right (I11). iOS 13+ requires a permission request from a user gesture; attach()
+ * runs inside the unlock gesture, so we ask immediately and degrade silently if refused.
+ */
+import type { Engine } from '../core/engine'
+
+const SHAKE_THRESHOLD = 18 // m/s² deviation from gravity
+const SHAKE_REFRACTORY_MS = 600
+
+export function attachMotion(engine: Engine): () => void {
+  if (typeof DeviceOrientationEvent === 'undefined') return () => {}
+
+  let lastShake = 0
+  let attached = false
+
+  const onOrientation = (e: DeviceOrientationEvent) => {
+    if (e.gamma == null || e.beta == null) return
+    engine.rig?.tiltTo(e.gamma, e.beta)
+  }
+
+  const onMotion = (e: DeviceMotionEvent) => {
+    const a = e.accelerationIncludingGravity
+    if (!a || a.x == null || a.y == null || a.z == null) return
+    const magnitude = Math.abs(Math.sqrt(a.x * a.x + a.y * a.y + a.z * a.z) - 9.81)
+    const now = performance.now()
+    if (now - lastShake <= SHAKE_REFRACTORY_MS) return
+    if (magnitude > SHAKE_THRESHOLD) {
+      lastShake = now
+      engine.strum(engine.scanner.visibleElements(), 0.5)
+      return
+    }
+    // Directional flick (v0.6 gesture grammar): a horizontal jab strums in its direction.
+    if (Math.abs(a.x) > 12 && Math.abs(a.x) > 2 * Math.abs(a.y)) {
+      lastShake = now
+      engine.strum(engine.scanner.visibleElements(), 0.4, 'strum', a.x > 0)
+    }
+  }
+
+  const listen = () => {
+    if (attached) return
+    attached = true
+    window.addEventListener('deviceorientation', onOrientation, { passive: true })
+    window.addEventListener('devicemotion', onMotion, { passive: true })
+  }
+
+  const request = (DeviceOrientationEvent as unknown as { requestPermission?: () => Promise<string> }).requestPermission
+  if (typeof request === 'function') {
+    request.call(DeviceOrientationEvent)
+      .then((state) => { if (state === 'granted') listen() })
+      .catch(() => { /* user said no, or we were outside a gesture — stay silent */ })
+  } else {
+    listen()
+  }
+
+  return () => {
+    if (!attached) return
+    window.removeEventListener('deviceorientation', onOrientation)
+    window.removeEventListener('devicemotion', onMotion)
+  }
+}

package/src/interact/pointer.ts

@@ -0,0 +1,65 @@
+/**
+ * L2 — pointer: hover previews (I1) + look-around (I9).
+ * Ghost-trigger guards (v0.5, user-reported): a "hover" only counts when the POINTER moved onto
+ * the element. Scrolling moves elements under a stationary cursor and DOM mutations appear under
+ * it — both fire pointerover without any user hover intent, and both are suppressed here.
+ */
+import type { Engine } from '../core/engine'
+import type { Role } from '../types'
+
+const PREVIEW_ROLES: ReadonlySet<Role> = new Set(['button', 'link', 'toggle', 'input', 'item', 'heading', 'media', 'text'])
+const HOVER_THROTTLE_MS = 80
+/** pointerover within this window after a scroll = the page moved, not the hand. */
+const SCROLL_SUPPRESS_MS = 250
+/** pointerover needs pointer movement at most this long ago to count as intentional. */
+const MOVE_FRESHNESS_MS = 400
+/** The resolved element must be within this many ancestors of the actual target —
+ *  hovering a blank region must not preview some distant registered container. */
+const MAX_RESOLVE_HOPS = 4
+
+export function attachPointer(engine: Engine): () => void {
+  const lastHover = new WeakMap<Element, number>()
+  let lastScrollT = -Infinity
+  let lastMoveT = -Infinity
+
+  const onMove = (e: PointerEvent) => {
+    lastMoveT = performance.now()
+    engine.rig?.pointTo(e.clientX / window.innerWidth, e.clientY / window.innerHeight)
+  }
+
+  const onScroll = () => {
+    lastScrollT = performance.now()
+  }
+
+  const withinHops = (target: Element, resolved: Element): boolean => {
+    let n: Element | null = target
+    for (let d = 0; n && d <= MAX_RESOLVE_HOPS; d++) {
+      if (n === resolved) return true
+      n = n.parentElement
+    }
+    return false
+  }
+
+  const onOver = (e: PointerEvent) => {
+    const now = performance.now()
+    if (now - lastScrollT < SCROLL_SUPPRESS_MS) return // page slid under the cursor
+    if (now - lastMoveT > MOVE_FRESHNESS_MS) return //   nothing moved the pointer here
+    const target = e.target as Element | null
+    const el = engine.scanner?.resolve(target)
+    if (!el || !target || !withinHops(target, el)) return
+    const profile = engine.scanner.profileFor(el)
+    if (!profile || !PREVIEW_ROLES.has(profile.role)) return
+    if (now - (lastHover.get(el) ?? -Infinity) < HOVER_THROTTLE_MS) return
+    lastHover.set(el, now)
+    engine.excite(el, 0.25, 'preview')
+  }
+
+  window.addEventListener('pointermove', onMove, { passive: true })
+  window.addEventListener('pointerover', onOver, { passive: true })
+  window.addEventListener('scroll', onScroll, { passive: true, capture: true })
+  return () => {
+    window.removeEventListener('pointermove', onMove)
+    window.removeEventListener('pointerover', onOver)
+    window.removeEventListener('scroll', onScroll, { capture: true })
+  }
+}

package/src/interact/scroll.ts

@@ -0,0 +1,43 @@
+/**
+ * L2 — scroll & resize: cached rects go stale (I8), the room follows the viewport (S7/S8),
+ * and scroll velocity becomes air rushing past (MATTER.md §2.2).
+ */
+import { airRushGain } from '../math/matter'
+import type { Engine } from '../core/engine'
+
+export function attachScroll(engine: Engine): () => void {
+  let scrollQueued = false
+  let lastY = window.scrollY
+  let lastT = performance.now()
+  const onScroll = () => {
+    if (scrollQueued) return
+    scrollQueued = true
+    requestAnimationFrame(() => {
+      scrollQueued = false
+      engine.geometryChanged()
+      const now = performance.now()
+      const dt = Math.max(1, now - lastT)
+      const v = Math.abs(window.scrollY - lastY) / dt // px per ms
+      lastY = window.scrollY
+      lastT = now
+      engine.airRush(airRushGain(v))
+    })
+  }
+
+  let resizeQueued = false
+  const onResize = () => {
+    if (resizeQueued) return
+    resizeQueued = true
+    requestAnimationFrame(() => {
+      resizeQueued = false
+      engine.roomResized()
+    })
+  }
+
+  window.addEventListener('scroll', onScroll, { passive: true, capture: true })
+  window.addEventListener('resize', onResize, { passive: true })
+  return () => {
+    window.removeEventListener('scroll', onScroll, { capture: true })
+    window.removeEventListener('resize', onResize)
+  }
+}

package/src/math/chroma.ts

@@ -0,0 +1,111 @@
+/**
+ * The Chroma weave — CHROMA.md made executable. Color tints the Matter voice per element and
+ * chooses the musical mode per page. Pure: no DOM, no Tone.
+ */
+import { clamp, lerp } from './util'
+
+export interface Rgb {
+  r: number
+  g: number
+  b: number
+  a: number
+}
+
+export interface Hsl {
+  h: number
+  s: number
+  l: number
+}
+
+export interface Chroma {
+  /** 0 cool … 1 warm (desaturated colors regress to 0.5) */
+  warmth: number
+  saturation: number
+  luminance: number
+}
+
+/** Computed styles emit rgb()/rgba(). Returns null for anything else (treat as no color). */
+export function parseCssColor(css: string): Rgb | null {
+  const m = css.trim().match(/^rgba?\(\s*(\d+(?:\.\d+)?)\s*,\s*(\d+(?:\.\d+)?)\s*,\s*(\d+(?:\.\d+)?)\s*(?:,\s*(\d*(?:\.\d+)?)\s*)?\)$/)
+  if (!m) return null
+  return {
+    r: clamp(parseFloat(m[1] as string) / 255, 0, 1),
+    g: clamp(parseFloat(m[2] as string) / 255, 0, 1),
+    b: clamp(parseFloat(m[3] as string) / 255, 0, 1),
+    a: m[4] === undefined ? 1 : clamp(parseFloat(m[4] as string), 0, 1),
+  }
+}
+
+export function rgbToHsl({ r, g, b }: Rgb): Hsl {
+  const max = Math.max(r, g, b)
+  const min = Math.min(r, g, b)
+  const l = (max + min) / 2
+  const d = max - min
+  if (d < 1e-6) return { h: 0, s: 0, l }
+  const s = d / (1 - Math.abs(2 * l - 1))
+  let h: number
+  if (max === r) h = ((g - b) / d) % 6
+  else if (max === g) h = (b - r) / d + 2
+  else h = (r - g) / d + 4
+  h *= 60
+  if (h < 0) h += 360
+  return { h, s: clamp(s, 0, 1), l }
+}
+
+/** CHROMA.md §1 — cosine distance of hue from 30° (orange); greys regress to neutral 0.5. */
+export function warmthFromHue(h: number, s: number): number {
+  const raw = 0.5 + 0.5 * Math.cos(((h - 30) * Math.PI) / 180)
+  return lerp(0.5, raw, clamp(s * 2, 0, 1))
+}
+
+export function chromaOf(rgb: Rgb | null): Chroma {
+  if (!rgb || rgb.a < 0.05) return { warmth: 0.5, saturation: 0, luminance: 0.5 }
+  const { h, s, l } = rgbToHsl(rgb)
+  return { warmth: warmthFromHue(h, s), saturation: s, luminance: l }
+}
+
+// ------------------------------------------------------------- element weave (CH1–CH5)
+
+/** CH1 — dark UI sounds dark. */
+export const brightnessFromLuminance = (l: number): number => lerp(0.78, 1.22, clamp(l, 0, 1))
+
+/** CH2 — bright lifts, gently. */
+export const velocityFromLuminance = (l: number): number => lerp(0.92, 1.06, clamp(l, 0, 1))
+
+/** CH3 — warm = energetic onset (thesis T5). Multiplier on the woven attack. */
+export const attackScaleFromWarmth = (w: number): number => lerp(1.18, 0.82, clamp(w, 0, 1))
+
+/** CH4 — warm = full-bodied: bonus on the sub oscillator level (subs only, not shimmer). */
+export const subBonusFromWarmth = (w: number): number => 0.08 * clamp(w, 0, 1)
+
+/** CH5 — vivid color = vivid spectrum: richness passed to genPartials (rolloff reduction). */
+export const richnessFromSaturation = (s: number): number => 0.35 * clamp(s, 0, 1)
+
+// ------------------------------------------------------------- page weave (CH6–CH8)
+
+export type ModeName = 'lydian' | 'mixolydian' | 'dorian' | 'pentMinor' | null
+
+/**
+ * CH6 — the palette chooses the mode; null = neutral, keep the hostname-hashed scale
+ * (identity unchanged). Root pitch-class always stays hostname-hashed (S9).
+ */
+export function modeFromPalette(pal: Chroma): ModeName {
+  if (pal.warmth >= 0.55) return pal.luminance >= 0.5 ? 'lydian' : 'mixolydian'
+  if (pal.warmth <= 0.45) return pal.luminance >= 0.5 ? 'dorian' : 'pentMinor'
+  return null
+}
+
+/** Visual weight of the page: bg dominates, text tints. */
+export function pagePalette(bg: Chroma, text: Chroma): Chroma {
+  return {
+    warmth: bg.warmth * 0.7 + text.warmth * 0.3,
+    saturation: bg.saturation * 0.7 + text.saturation * 0.3,
+    luminance: bg.luminance * 0.7 + text.luminance * 0.3,
+  }
+}
+
+/** CH7 — warm rooms hum warmer. Multiplier on the ambience cutoff. */
+export const roomToneScaleFromWarmth = (w: number): number => lerp(0.85, 1.25, clamp(w, 0, 1))
+
+/** CH8 — warm pages run slightly faster (consumed by PULSE.md P2). */
+export const tempoScaleFromWarmth = (w: number): number => lerp(0.94, 1.06, clamp(w, 0, 1))

package/src/math/mapping.ts

@@ -0,0 +1,100 @@
+/**
+ * Every formula in MAPPING.md §1–2, one named pure function each.
+ * This file is the executable form of the Mapping Canon: no DOM, no Tone, no side effects.
+ * Change a formula here ⇄ change MAPPING.md in the same commit (PLAN.md Invariant #3).
+ */
+import { clamp, lerp, norm } from './util'
+import type { Rect, Wave } from '../types'
+
+export const ROOM_HALF_W = 8 // meters — G1
+export const ROOM_HALF_H = 4 // meters — G2
+
+/** G1 — element center x → azimuth (positionX, meters). */
+export function panX(rect: Rect, vw: number): number {
+  return (2 * norm(rect.x + rect.w / 2, 0, vw) - 1) * ROOM_HALF_W
+}
+
+/** G2 — element center y → elevation (positionY, meters; screen-top = up). */
+export function panY(rect: Rect, vh: number): number {
+  return (1 - 2 * norm(rect.y + rect.h / 2, 0, vh)) * ROOM_HALF_H
+}
+
+/** G3 — vertical position → brightness tilt multiplier on the filter cutoff. */
+export function brightnessTilt(rect: Rect, vh: number): number {
+  return lerp(1.45, 0.7, norm(rect.y + rect.h / 2, 0, vh))
+}
+
+/** G4 — log-normalized size 0 (tiny) … 1 (viewport-filling). */
+export function sizeT(rect: Rect, vw: number, vh: number): number {
+  const a = Math.max(1, rect.w * rect.h)
+  const A = Math.max(1, vw * vh)
+  return norm(Math.log(1 + (100 * a) / A), 0, Math.log(101))
+}
+
+/**
+ * G4 — pitch degree, inverted: big elements speak low (T2). Compressed into [0.1, 0.85] so
+ * sibling/heading step offsets have melodic headroom instead of clamping at the edges.
+ */
+export const degreeFromSize = (t: number): number => 0.1 + 0.75 * (1 - t)
+
+/** G5 — big elements speak louder (T2). */
+export const velocityFromSize = (t: number): number => lerp(0.85, 1.25, t)
+
+/** G6 — roundness r ∈ [0,1]: 0 = razor corner (kiki), 1 = pill/circle (bouba). */
+export function roundness(radiusPx: number, rect: Rect): number {
+  const half = Math.min(rect.w, rect.h) / 2
+  return half <= 0 ? 0 : clamp(radiusPx / half, 0, 1)
+}
+
+/** G7 — the Kiki/Bouba waveform ladder. */
+export function waveFromRoundness(r: number): Wave {
+  if (r < 0.15) return 'square'
+  if (r < 0.45) return 'sawtooth'
+  if (r < 0.8) return 'triangle'
+  return 'sine'
+}
+
+/** G8 — sharp = plosive onset, round = soft bloom. Seconds. */
+export const attackFromRoundness = (r: number): number => lerp(0.002, 0.045, r)
+
+/** G9 — sharp edges ring with resonance. */
+export const qFromRoundness = (r: number): number => lerp(2.4, 0.5, r)
+
+/** G10 — sharper ↔ slightly higher (T1), in whole scale steps. */
+export const pitchNudgeFromRoundness = (r: number): number => (1 - r) * 1
+
+/** G11 — elongation → duration: long elements sweep, squares tick. Seconds. */
+export function durationFromElongation(rect: Rect): number {
+  const e = Math.max(rect.w, rect.h) / Math.max(1, Math.min(rect.w, rect.h))
+  return clamp(0.18 * Math.sqrt(e), 0.12, 1.6)
+}
+
+/** G13 — box-shadow blur lifts the element into the room's reverb. */
+export const sendFromShadowBlur = (blurPx: number): number => clamp(blurPx / 40, 0, 0.5)
+
+/** S1 — DOM depth → distance behind the sound stage (listener at z=0 facing −z). */
+export const zFromDepth = (depth: number): number => -(1 + 0.7 * Math.min(depth, 10))
+
+/** S2 — deeper nesting = duller voice. Hz. */
+export const cutoffFromDepth = (depth: number): number => Math.max(700, 9000 * Math.pow(0.82, depth))
+
+/** S3 — deeper nesting = quieter (distance loudness, Zahorik 2002). */
+export const velocityFromDepth = (depth: number): number => Math.max(0.55, Math.pow(0.97, depth))
+
+/** S5 — positive z-index pulls the element toward the listener. Meters toward z=0. */
+export const zBonusFromZIndex = (z: number): number => clamp(z / 50, 0, 1) * 0.8
+
+/** S4 — siblings climb the scale, wrapping each octave (do-re-mi…-do) so long lists stay melodic. */
+export const stepsFromSiblingIndex = (i: number, scaleLen = 7): number => i % Math.max(1, scaleLen)
+
+/** S6 — headings: h1 lands lowest/grandest. Whole scale steps (negative = down). */
+export const stepsFromHeadingLevel = (level: number): number => -(7 - clamp(level, 1, 6)) * 2
+
+/** S7/S8 — the viewport is the room. */
+export function reverbFromViewport(vw: number): { decay: number; wet: number } {
+  const t = norm(vw, 360, 2200)
+  return { decay: lerp(0.6, 4.5, t), wet: lerp(0.08, 0.32, t) }
+}
+
+/** I13 — room tone color follows room size. Hz. */
+export const ambienceCutoffFromViewport = (vw: number): number => lerp(400, 1400, norm(vw, 360, 2200))

package/src/math/matter.ts

@@ -0,0 +1,201 @@
+/**
+ * The Matter weave — MATTER.md made executable. Four macro-dimensions condensed from visual
+ * properties, each woven into bundles of co-varying synthesis parameters so the ear hears one
+ * coherent object (Bregman fusion; Grey/McAdams timbre axes). Pure: no DOM, no Tone.
+ * Change a formula here ⇄ change MATTER.md §2 in the same commit (Invariant #3).
+ */
+import { clamp, lerp } from './util'
+
+export interface Matter {
+  /** boundary abruptness, kiki↔bouba: 1 − roundness */
+  edge: number
+  /** size/weight: log-area sizeT */
+  mass: number
+  /** surface noisiness/airiness: shadows, translucency, dashed borders, media */
+  texture: number
+  /** distance into the room: normalized DOM depth */
+  air: number
+}
+
+export interface MatterVisuals {
+  roundness: number
+  sizeT: number
+  depth: number
+  shadowBlurPx: number
+  opacity: number
+  dashedBorder: boolean
+  isMedia: boolean
+  backdropBlurPx: number
+  /** MODULAR.md M7 — typography enters the weave (bold text carries weight). Default 0. */
+  massBonus?: number
+}
+
+export function deriveMatter(v: MatterVisuals): Matter {
+  const texture = clamp(
+    clamp(v.shadowBlurPx / 40, 0, 0.4) +
+      (1 - clamp(v.opacity, 0, 1)) * 0.6 +
+      (v.dashedBorder ? 0.15 : 0) +
+      (v.isMedia ? 0.35 : 0) +
+      clamp(v.backdropBlurPx / 40, 0, 0.2),
+    0,
+    1,
+  )
+  return {
+    edge: clamp(1 - v.roundness, 0, 1),
+    mass: clamp(v.sizeT + (v.massBonus ?? 0), 0, 1),
+    texture,
+    air: clamp(Math.min(v.depth, 10) / 10, 0, 1),
+  }
+}
+
+// ------------------------------------------------------------------ spectrum (MATTER.md §2.1)
+
+export const PARTIAL_COUNT = 24
+
+/**
+ * Continuous spectrum: EDGE sets the rolloff (bright↔pure), elongation sets hollowness
+ * (long thin elements = pipes = odd harmonics), richness (CHROMA.md CH5: saturation)
+ * subtracts from the rolloff exponent — vivid color = vivid spectrum. Normalized to Σa² = 1
+ * so the whole continuum sits at equal loudness.
+ */
+export function genPartials(edge: number, elongation: number, richness = 0): Float32Array {
+  const p = Math.max(0.8, 1 + 2.6 * (1 - clamp(edge, 0, 1)) - clamp(richness, 0, 0.5))
+  const evenness = lerp(1, 0.12, clamp((elongation - 1) / 4, 0, 1))
+  const a = new Float32Array(PARTIAL_COUNT)
+  let energy = 0
+  for (let k = 1; k <= PARTIAL_COUNT; k++) {
+    const amp = (k % 2 === 1 ? 1 : evenness) / Math.pow(k, p)
+    a[k - 1] = amp
+    energy += amp * amp
+  }
+  const norm = 1 / Math.sqrt(energy || 1)
+  for (let i = 0; i < PARTIAL_COUNT; i++) a[i] = (a[i] as number) * norm
+  return a
+}
+
+// ------------------------------------------------------------------ noise weaves
+
+export interface TransientSpec {
+  /** noise burst length, seconds */
+  lengthS: number
+  /** high-pass corner of the burst, Hz */
+  hpHz: number
+  /** burst level relative to the voice (×velocity) */
+  level: number
+}
+
+/** EDGE → the /k/ of kiki: a filtered click at onset. edge 0 → none. */
+export function transient(edge: number): TransientSpec {
+  const e = clamp(edge, 0, 1)
+  return {
+    lengthS: lerp(0.005, 0.025, e),
+    hpHz: 2000 + 4000 * e,
+    level: 0.7 * e,
+  }
+}
+
+export interface BreathSpec {
+  /** sustained airy layer level (0 = pure tone) */
+  level: number
+  /** band-pass center as a ratio of the fundamental */
+  bpRatio: number
+}
+
+/** TEXTURE → breath: translucent/soft-shadowed things are airy. */
+export function breath(texture: number): BreathSpec {
+  const t = clamp(texture, 0, 1)
+  return { level: 0.22 * t, bpRatio: lerp(2.5, 1.2, t) }
+}
+
+/** TEXTURE → detune jitter in cents (rough surfaces are pitch-unstable). */
+export const detuneJitterCents = (texture: number): number => 6 * clamp(texture, 0, 1)
+
+// ------------------------------------------------------------------ pitch behaviour
+
+export interface SubShimmerSpec {
+  /** semitone offset of osc B: −12 chest sub for massive, +12 sparkle for tiny */
+  interval: number
+  level: number
+}
+
+/** MASS → the second oscillator: big = chest, tiny = sparkle. */
+export function subShimmer(mass: number): SubShimmerSpec {
+  const m = clamp(mass, 0, 1)
+  return {
+    interval: m >= 0.45 ? -12 : 12,
+    level: lerp(0.1, 0.38, clamp(Math.abs(m - 0.45) * 2, 0, 1)),
+  }
+}
+
+/** ROUND → glide: the bouba swoop-in. Returns portamento seconds (0 for sharp). */
+export const glideS = (edge: number): number => lerp(0.028, 0, clamp(edge, 0, 1))
+
+// ------------------------------------------------------------------ envelope weave
+
+export interface EnvelopeSpec {
+  attackS: number
+  decayS: number
+  sustain: number
+  releaseScale: number
+}
+
+/** EDGE strikes, MASS adds inertia. */
+export function envelopeWeave(edge: number, mass: number): EnvelopeSpec {
+  const e = clamp(edge, 0, 1)
+  const m = clamp(mass, 0, 1)
+  return {
+    attackS: lerp(0.045, 0.002, e) + 0.008 * m,
+    decayS: lerp(0.4, 0.12, e),
+    sustain: lerp(0.35, 0.15, e),
+    releaseScale: lerp(0.8, 1.5, m),
+  }
+}
+
+// ------------------------------------------------------------------ filter weave
+
+export interface FilterWeaveSpec {
+  q: number
+  /** transient brightness bite: cutoff multiplier at onset, decaying to 1 */
+  biteAmount: number
+  biteDecayS: number
+}
+
+/** EDGE rings and bites. (Base cutoff itself comes from AIR via S2 + tilt, as before.) */
+export function filterWeave(edge: number): FilterWeaveSpec {
+  const e = clamp(edge, 0, 1)
+  return {
+    q: lerp(0.5, 2.4, e),
+    biteAmount: 1 + 3 * e,
+    biteDecayS: lerp(0.15, 0.06, e),
+  }
+}
+
+// ------------------------------------------------------------------ reverb weave
+
+export interface ReverbWeaveSpec {
+  /** multiplier on the profile's base send */
+  sendScale: number
+  /** low-pass on the way into the reverb: dark sources bloom dark. Hz */
+  sendCutoffHz: number
+  /** 0 = arrive at full send immediately (sharp); 1 = swell from 35% over the note (round) */
+  bloom: number
+  /** spatial extent bonus from airy texture */
+  extentBonus: number
+}
+
+export function reverbWeave(edge: number, mass: number, texture: number): ReverbWeaveSpec {
+  const e = clamp(edge, 0, 1)
+  const m = clamp(mass, 0, 1)
+  const t = clamp(texture, 0, 1)
+  return {
+    sendScale: lerp(1.3, 0.7, e) * lerp(0.85, 1.15, m),
+    sendCutoffHz: lerp(1200, 7000, e),
+    bloom: 1 - e,
+    extentBonus: 0.15 * t,
+  }
+}
+
+// ------------------------------------------------------------------ interaction weave
+
+/** I8 — scroll velocity (px/ms) → air-rush gain on the room tone, decaying over ~400 ms. */
+export const airRushGain = (pxPerMs: number): number => clamp(pxPerMs * 0.06, 0, 0.18)

package/src/math/modular.ts

@@ -0,0 +1,99 @@
+/**
+ * The Modular patch — MODULAR.md made executable. CSS properties plug modulation cables:
+ * border-width drives the wavefolder, texture×edge sets FM, mass thickens unison, animation
+ * and dashed borders patch the LFO. Pure: no DOM, no Tone.
+ */
+import { clamp } from './util'
+
+export interface ModularVisuals {
+  /** seconds; 0 = no animation */
+  animationS: number
+  borderStyle: 'solid' | 'dashed' | 'dotted' | 'none'
+  borderWidthPx: number
+  /** seconds; 0 = no transition */
+  transitionS: number
+}
+
+export interface PatchParams {
+  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
+}
+
+/** M1 — heavy borders saturate: drive ∈ [0,1], mix follows. */
+export function foldFromBorder(borderWidthPx: number, edge: number): PatchParams['fold'] {
+  const drive = clamp(borderWidthPx / 6, 0, 1) * (0.25 + 0.75 * clamp(edge, 0, 1))
+  return { drive, mix: drive > 0.01 ? 0.25 + 0.55 * drive : 0 }
+}
+
+/** M2 — rough sharp surfaces ring metallic (audio-rate FM index, × carrier Hz in-voice). */
+export const fmIndex = (texture: number, edge: number): number =>
+  1.5 * clamp(texture, 0, 1) * clamp(edge, 0, 1)
+
+/** M3 — big elements are thick, not just low. */
+export function unisonFromMass(mass: number): PatchParams['unison'] {
+  const m = clamp(mass, 0, 1)
+  return m >= 0.45 ? { detuneCents: 4 + 10 * m, mix: 0.4 } : { detuneCents: 0, mix: 0 }
+}
+
+/** M4/M5 — the LFO patch bay: animation owns it; dashed/dotted borders chop; else idle. */
+export function lfoFromCss(animationS: number, borderStyle: ModularVisuals['borderStyle']): PatchParams['lfo'] {
+  if (animationS > 0.05) {
+    return {
+      rateHz: clamp(1 / animationS, 0.08, 8),
+      shape: borderStyle === 'dashed' || borderStyle === 'dotted' ? 'square' : 'sine',
+      vibratoCents: 6,
+      tremolo: 0.18,
+      filterDepth: 0.25,
+    }
+  }
+  if (borderStyle === 'dashed' || borderStyle === 'dotted') {
+    return {
+      rateHz: borderStyle === 'dotted' ? 7 : 3.5,
+      shape: 'square',
+      vibratoCents: 0,
+      tremolo: 0.3,
+      filterDepth: 0.35,
+    }
+  }
+  return { rateHz: 0, shape: 'sine', vibratoCents: 0, tremolo: 0, filterDepth: 0 }
+}
+
+/** M6 — elements that ease visually ease in pitch. Seconds added to the glide. */
+export const portamentoFromTransition = (transitionS: number): number =>
+  clamp(transitionS / 2, 0, 0.25)
+
+/** M7 — typography enters the weave: bold text carries weight (MASS bonus). */
+export const massBonusFromFontWeight = (weight: number): number =>
+  clamp((weight - 400) / 300, 0, 1) * 0.12
+
+export function patchFrom(matter: { edge: number; mass: number; texture: number }, visuals: ModularVisuals): PatchParams {
+  return {
+    fold: foldFromBorder(visuals.borderWidthPx, matter.edge),
+    fm: { index: fmIndex(matter.texture, matter.edge) },
+    unison: unisonFromMass(matter.mass),
+    lfo: lfoFromCss(visuals.animationS, visuals.borderStyle),
+    portamentoS: portamentoFromTransition(visuals.transitionS),
+  }
+}
+
+/**
+ * The wavefolder transfer curve: y = sin(2.5·(π/2)·x). Near-linear for quiet signals,
+ * folding for hot ones — the amp envelope sweeps the spectrum through the fold every note.
+ */
+export function foldCurve(samples = 2049): Float32Array {
+  const out = new Float32Array(samples)
+  for (let i = 0; i < samples; i++) {
+    const x = (i / (samples - 1)) * 2 - 1
+    out[i] = Math.sin(2.5 * (Math.PI / 2) * x)
+  }
+  return out
+}
+
+/** Drag-glissando ribbon (MODULAR.md §3): horizontal travel → scale-step offset, ±1 octave. */
+export function ribbonSteps(dxPx: number, vw: number, scaleLen: number): number {
+  const t = clamp(dxPx / (vw * 0.6), -1, 1)
+  return Math.round(t * scaleLen)
+}