sonarium 0.6.0

package/src/core/scanner.ts

@@ -0,0 +1,176 @@
+/**
+ * L1 Page Reading — eligibility, registry, observers, visible set (ARCHITECTURE.md §5).
+ * Imports DOM only; produces data + callbacks, triggers nothing audible itself.
+ */
+import type { SonicProfile } from '../types'
+import { profileOf, roleOf, type ProfileEnv } from './profile'
+
+export const ELIGIBLE_SELECTOR = [
+  'button', '[role=button]', 'input', 'textarea', 'select', '[contenteditable]',
+  'a[href]', '[role=link]', 'summary', '[role=switch]', '[role=checkbox]',
+  'h1', 'h2', 'h3', 'h4', 'h5', 'h6', '[role=heading]',
+  'img', 'video', 'canvas', 'svg', 'picture',
+  'li', 'tr', '[role=listitem]', '[role=option]', '[role=menuitem]', '[role=tab]',
+  'nav', 'section', 'article', 'aside', 'form', 'fieldset', 'dialog',
+  '[data-sonic-role]', '[data-sonic-note]',
+].join(',')
+
+const MAX_TRACKED = 400
+
+interface Entry {
+  profile: SonicProfile | null
+  visible: boolean
+}
+
+export interface ScannerCallbacks {
+  /** Fired when an element scrolls/loads into view after the initial scan (I7 whisper). */
+  onAppear: (el: Element) => void
+}
+
+export class Scanner {
+  readonly registry = new Map<Element, Entry>()
+  private io: IntersectionObserver | null = null
+  private mo: MutationObserver | null = null
+  private capWarned = false
+  private initialScanDone = false
+  private mutationTimer: ReturnType<typeof setTimeout> | null = null
+
+  constructor(
+    private env: ProfileEnv,
+    private cb: ScannerCallbacks,
+  ) {}
+
+  scan(): void {
+    if (typeof IntersectionObserver !== 'undefined') {
+      this.io = new IntersectionObserver((entries) => {
+        for (const e of entries) {
+          const entry = this.registry.get(e.target)
+          if (!entry) continue
+          const was = entry.visible
+          entry.visible = e.isIntersecting
+          if (e.isIntersecting) entry.profile = null // rect changed while away; recompute lazily
+          if (e.isIntersecting && !was && this.initialScanDone) this.cb.onAppear(e.target)
+        }
+      }, { threshold: 0.15 })
+    }
+
+    this.register(this.env.root)
+    for (const el of Array.from(this.env.root.querySelectorAll(ELIGIBLE_SELECTOR))) this.register(el)
+
+    if (typeof MutationObserver !== 'undefined') {
+      this.mo = new MutationObserver((muts) => this.queueMutations(muts))
+      this.mo.observe(this.env.root, { subtree: true, childList: true, attributes: true, attributeFilter: ['class', 'style', 'data-sonic', 'data-sonic-note', 'data-sonic-wave', 'data-sonic-role'] })
+    }
+
+    // Let the initial IntersectionObserver flood settle before treating entries as "appearances".
+    setTimeout(() => { this.initialScanDone = true }, 300)
+  }
+
+  private register(el: Element): void {
+    if (this.registry.has(el) || this.isOff(el)) return
+    if (this.registry.size >= MAX_TRACKED) {
+      if (!this.capWarned) {
+        this.capWarned = true
+        console.warn(`[sonarium] page exceeds ${MAX_TRACKED} tracked elements; extra elements stay silent`)
+      }
+      return
+    }
+    this.registry.set(el, { profile: null, visible: false })
+    this.io?.observe(el)
+  }
+
+  private unregister(el: Element): void {
+    if (!this.registry.has(el)) return
+    this.registry.delete(el)
+    this.io?.unobserve(el)
+  }
+
+  isOff(el: Element): boolean {
+    let n: Element | null = el
+    while (n) {
+      if ((n as HTMLElement).dataset?.sonic === 'off') return true
+      n = n.parentElement
+    }
+    return false
+  }
+
+  private queueMutations(muts: MutationRecord[]): void {
+    if (this.mutationTimer) clearTimeout(this.mutationTimer)
+    const records = muts
+    this.mutationTimer = setTimeout(() => {
+      for (const m of records) {
+        if (m.type === 'attributes' && m.target instanceof Element) {
+          const entry = this.registry.get(m.target)
+          if (entry) entry.profile = null
+          continue
+        }
+        for (const node of Array.from(m.addedNodes)) {
+          if (!(node instanceof Element)) continue
+          if (node.matches?.(ELIGIBLE_SELECTOR)) this.register(node)
+          for (const el of Array.from(node.querySelectorAll?.(ELIGIBLE_SELECTOR) ?? [])) this.register(el)
+        }
+        for (const node of Array.from(m.removedNodes)) {
+          if (!(node instanceof Element)) continue
+          this.unregister(node)
+          for (const el of Array.from(node.querySelectorAll?.(ELIGIBLE_SELECTOR) ?? [])) this.unregister(el)
+        }
+      }
+    }, 150)
+  }
+
+  /** Profile with lazy compute + cache (cheap path: geometry invalidation only nulls it). */
+  profileFor(el: Element): SonicProfile | null {
+    if (this.isOff(el)) return null
+    let entry = this.registry.get(el)
+    if (!entry) {
+      // Untracked but asked for (e.g. describe() on an arbitrary element): compute one-off.
+      return safeProfile(el, this.env)
+    }
+    if (!entry.profile) entry.profile = safeProfile(el, this.env)
+    return entry.profile
+  }
+
+  /** Geometry changed globally (scroll/resize): rects are stale, voices params survive. */
+  invalidateRects(): void {
+    for (const entry of this.registry.values()) entry.profile = null
+  }
+
+  visibleElements(): Element[] {
+    const out: Element[] = []
+    for (const [el, entry] of this.registry) if (entry.visible) out.push(el)
+    return out
+  }
+
+  /** The element (or nearest registered ancestor) the scanner knows about. */
+  resolve(target: Element | null): Element | null {
+    let n: Element | null = target
+    while (n) {
+      if (this.registry.has(n)) return n
+      n = n.parentElement
+    }
+    return null
+  }
+
+  updateEnv(vw: number, vh: number): void {
+    this.env.vw = vw
+    this.env.vh = vh
+  }
+
+  dispose(): void {
+    if (this.mutationTimer) clearTimeout(this.mutationTimer)
+    this.io?.disconnect()
+    this.mo?.disconnect()
+    this.registry.clear()
+  }
+}
+
+function safeProfile(el: Element, env: ProfileEnv): SonicProfile | null {
+  try {
+    return profileOf(el, env)
+  } catch (err) {
+    console.warn('[sonarium] profile failed', err)
+    return null
+  }
+}
+
+export { roleOf }

package/src/core/voices.ts

@@ -0,0 +1,222 @@
+/**
+ * L0 Acoustic Substrate — VoicePool (ARCHITECTURE.md §4).
+ * Profiles are data; voices are rented lanes configured at trigger time. Spatial placement is
+ * delegated to the active SpatialBackend (ambisonic field or per-voice panners — SPATIAL.md §6).
+ * Imports Tone only; never reads the DOM.
+ */
+import * as Tone from 'tone'
+import { clamp } from '../math/util'
+import type { SonicProfile, SynthKind } from '../types'
+import type { LaneOutput, SpatialBackend } from '../spatial/backend'
+import { MatterVoice } from './matter-voice'
+
+type AnySynth = Tone.Synth | Tone.FMSynth | Tone.PluckSynth | Tone.MembraneSynth | Tone.NoiseSynth | MatterVoice
+
+interface Lane {
+  kind: SynthKind
+  synth: AnySynth
+  filter: Tone.Filter
+  out: LaneOutput
+  busyUntil: number
+}
+
+export interface VoiceBuses {
+  dryIn: Tone.InputNode
+  wetIn: Tone.InputNode
+}
+
+export class VoicePool {
+  private lanes: Lane[] = []
+  private sleepTimer: ReturnType<typeof setInterval>
+
+  constructor(
+    private backend: SpatialBackend,
+    private maxVoices: number,
+  ) {
+    this.maxVoices = clamp(maxVoices, 4, 24)
+    // MODULAR.md §4 — idle matter lanes power down (silent page ⇒ ~zero steady-state CPU).
+    this.sleepTimer = setInterval(() => {
+      const now = Tone.now()
+      for (const lane of this.lanes) {
+        if (lane.synth instanceof MatterVoice && lane.busyUntil < now - 30) lane.synth.sleep()
+      }
+    }, 10000)
+  }
+
+  private createSynth(kind: SynthKind): AnySynth {
+    switch (kind) {
+      case 'matter':
+        return new MatterVoice()
+      case 'fm':
+        return new Tone.FMSynth({ harmonicity: 3, modulationIndex: 8, envelope: { attack: 0.01, decay: 0.3, sustain: 0.1, release: 1.4 }, modulationEnvelope: { attack: 0.01, decay: 0.4, sustain: 0.2, release: 1 } })
+      case 'pluck':
+        return new Tone.PluckSynth({ attackNoise: 1, dampening: 3000, resonance: 0.92 })
+      case 'membrane':
+        return new Tone.MembraneSynth({ pitchDecay: 0.04, octaves: 5, envelope: { attack: 0.001, decay: 0.35, sustain: 0.01, release: 0.6 } })
+      case 'noise':
+        return new Tone.NoiseSynth({ noise: { type: 'white' }, envelope: { attack: 0.001, decay: 0.06, sustain: 0, release: 0.05 } })
+      default:
+        return new Tone.Synth({ oscillator: { type: 'triangle' }, envelope: { attack: 0.01, decay: 0.1, sustain: 0.25, release: 0.3 } })
+    }
+  }
+
+  private createLane(kind: SynthKind): Lane {
+    const synth = this.createSynth(kind)
+    const filter = new Tone.Filter({ frequency: 4000, type: 'lowpass', rolloff: -12, Q: 1 })
+    const out = this.backend.createOutput()
+    synth.connect(filter)
+    filter.connect(out.input)
+    // The LFO's filter-wobble tap (MODULAR.md M4/M5) modulates the lane filter additively.
+    if (synth instanceof MatterVoice) synth.modFilterOut.connect(filter.frequency)
+    const lane: Lane = { kind, synth, filter, out, busyUntil: 0 }
+    this.lanes.push(lane)
+    return lane
+  }
+
+  private acquire(kind: SynthKind): Lane {
+    const now = Tone.now()
+    let candidate: Lane | null = null
+    let oldestSameKind: Lane | null = null
+    let oldestAny: Lane | null = null
+    for (const lane of this.lanes) {
+      if (lane.kind === kind) {
+        if (lane.busyUntil <= now) { candidate = lane; break }
+        if (!oldestSameKind || lane.busyUntil < oldestSameKind.busyUntil) oldestSameKind = lane
+      }
+      if (!oldestAny || lane.busyUntil < oldestAny.busyUntil) oldestAny = lane
+    }
+    if (candidate) return candidate
+    if (this.lanes.length < this.maxVoices) return this.createLane(kind)
+    if (oldestSameKind) return oldestSameKind
+    // Cap reached and no lane of this kind: recycle the globally oldest lane into this kind.
+    const victim = oldestAny ?? (this.lanes[0] as Lane)
+    victim.synth.dispose()
+    victim.synth = this.createSynth(kind)
+    victim.synth.connect(victim.filter)
+    victim.kind = kind
+    return victim
+  }
+
+  /** Configure a lane from the profile, then sound it. `when` lets strums schedule ahead. */
+  trigger(profile: SonicProfile, velocity: number, when?: number): void {
+    const raw = velocity * profile.velocityScale
+    if (raw <= 0.01) return // silent roles (e.g. mono theme text) stay silent
+    const t = when ?? Tone.now()
+    const vel = clamp(raw, 0.03, 1)
+    const lane = this.acquire(profile.synthKind)
+
+    const baseCutoff = Math.max(200, profile.filterHz)
+    if (lane.kind === 'matter') {
+      // EDGE bite: the filter strikes bright then settles (MATTER.md filter weave).
+      const w = profile.voice
+      lane.filter.Q.rampTo(w.filter.q, 0.02, t)
+      lane.filter.frequency.cancelScheduledValues(t)
+      lane.filter.frequency.setValueAtTime(Math.min(12000, baseCutoff * w.filter.biteAmount), t)
+      lane.filter.frequency.exponentialRampTo(baseCutoff, w.filter.biteDecayS, t)
+    } else {
+      lane.filter.frequency.rampTo(baseCutoff, 0.02, t)
+      lane.filter.Q.rampTo(profile.filterQ, 0.02, t)
+    }
+    lane.out.setPlacement(profile, t)
+
+    const dur = profile.durationS
+    try {
+      switch (lane.kind) {
+        case 'matter': {
+          const mv = lane.synth as MatterVoice
+          mv.trigger({
+            freqHz: profile.freqHz,
+            velocity: vel,
+            durationS: dur,
+            releaseScaleBase: profile.release / 0.3,
+            voice: profile.voice,
+          }, t, baseCutoff)
+          lane.busyUntil = t + dur + mv.releaseTail()
+          return
+        }
+        case 'noise': {
+          ;(lane.synth as Tone.NoiseSynth).triggerAttackRelease(Math.min(dur, 0.2), t, vel)
+          break
+        }
+        case 'pluck': {
+          const pluck = lane.synth as Tone.PluckSynth
+          pluck.set({ dampening: clamp(profile.filterHz, 400, 7000) })
+          pluck.triggerAttackRelease(profile.freqHz, dur, t, vel)
+          break
+        }
+        case 'membrane': {
+          const mem = lane.synth as Tone.MembraneSynth
+          mem.set({ envelope: { attack: Math.max(0.001, profile.attack / 4), release: profile.release } })
+          mem.triggerAttackRelease(Math.max(30, profile.freqHz / 4), dur, t, vel)
+          break
+        }
+        case 'fm': {
+          const fm = lane.synth as Tone.FMSynth
+          fm.set({ envelope: { attack: profile.attack, release: profile.release * 2 } })
+          fm.triggerAttackRelease(profile.freqHz, dur, t, vel)
+          break
+        }
+        default: {
+          const syn = lane.synth as Tone.Synth
+          syn.set({
+            oscillator: { type: profile.wave },
+            envelope: { attack: profile.attack, decay: 0.08, sustain: 0.25, release: profile.release },
+          })
+          syn.triggerAttackRelease(profile.freqHz, dur, t, vel)
+        }
+      }
+      lane.busyUntil = t + dur + profile.release
+    } catch (err) {
+      console.warn('[sonarium] trigger failed', err)
+    }
+  }
+
+  get activeCount(): number {
+    const now = Tone.now()
+    return this.lanes.filter((l) => l.busyUntil > now).length
+  }
+
+  /** MODULAR.md §3 — a sustained ribbon voice. Returns null when no matter lane can gate. */
+  sustain(profile: SonicProfile, velocity: number): { setFreq(hz: number, glideS: number): void; release(): void } | null {
+    const raw = velocity * profile.velocityScale
+    if (raw <= 0.01) return null
+    const lane = this.acquire('matter')
+    if (!(lane.synth instanceof MatterVoice)) return null
+    const mv = lane.synth
+    const t = Tone.now()
+    const baseCutoff = Math.max(200, profile.filterHz)
+    lane.filter.Q.rampTo(profile.voice.filter.q, 0.02, t)
+    lane.filter.frequency.cancelScheduledValues(t)
+    lane.filter.frequency.setValueAtTime(Math.min(12000, baseCutoff * profile.voice.filter.biteAmount), t)
+    lane.filter.frequency.exponentialRampTo(baseCutoff, profile.voice.filter.biteDecayS, t)
+    lane.out.setPlacement(profile, t)
+    mv.gateOn({
+      freqHz: profile.freqHz,
+      velocity: clamp(raw, 0.03, 1),
+      durationS: 9999,
+      releaseScaleBase: profile.release / 0.3,
+      voice: profile.voice,
+    }, t, baseCutoff)
+    lane.busyUntil = t + 9999
+    const voice = profile.voice
+    return {
+      setFreq(hz: number, glideS: number) {
+        mv.setFreq(hz, glideS, voice.subShimmer.interval, voice.patch.fm.index)
+      },
+      release() {
+        const tail = mv.gateOff()
+        lane.busyUntil = Tone.now() + tail
+      },
+    }
+  }
+
+  dispose(): void {
+    clearInterval(this.sleepTimer)
+    for (const lane of this.lanes) {
+      lane.synth.dispose()
+      lane.filter.dispose()
+      lane.out.dispose()
+    }
+    this.lanes = []
+  }
+}

package/src/index.ts

@@ -0,0 +1,74 @@
+/**
+ * Sonarium — drop-in acoustic UX.
+ * One script tag turns any webpage into a spatial sound field: layout becomes a stereo stage,
+ * geometry becomes timbre (Kiki/Bouba), the DOM tree becomes depth and harmony, the viewport
+ * becomes a room, and your cursor becomes your ears.
+ *
+ *   import { create } from 'sonarium'         // ESM
+ *   const space = create({ theme: 'aurora' })
+ *
+ *   <script src=".../sonarium.iife.js" data-auto></script>   // zero-code
+ *
+ * Docs: https://github.com/frank890417/sonarium — start with docs/PLAN.md.
+ */
+import { Engine } from './core/engine'
+import type { SonariumOptions } from './types'
+
+export const version = '0.6.0'
+
+export type {
+  SonariumOptions, SonicProfile, Theme, VoiceRecipe, Role, Wave, SynthKind,
+  Articulation, TriggerDetail, SonariumEvent, SphereProps, PerceptualFactors,
+} from './types'
+export { THEMES } from './themes/index'
+export { siteKey, parseKey, degreeToMidi, midiToFreq, midiToNoteName, stepInScale, SCALES } from './math/scales'
+export * as mapping from './math/mapping'
+export * as matter from './math/matter'
+export * as chroma from './math/chroma'
+export * as pulse from './math/pulse'
+export * as modular from './math/modular'
+// The pure spatial layer (SPATIAL.md) — reusable beyond the DOM.
+export { foaGains, unitVector, DEG } from './spatial/sh'
+export { rotationMatrix, lookMatrix, applyMat3 } from './spatial/rotation'
+export { CUBE_LAYOUT, decodeMatrix, decodeGains } from './spatial/decoder'
+export * as sphereMapping from './spatial/sphere'
+export { DEFAULT_FACTORS } from './spatial/perceptual'
+export type { Engine }
+
+/**
+ * Create a Sonarium instance. Safe to call before any user gesture: audio arms itself and
+ * starts on the first pointer/key interaction (browser autoplay policy treated as a feature).
+ */
+export function create(options: SonariumOptions = {}): Engine {
+  return new Engine(options)
+}
+
+// ---------------------------------------------------------------------------- auto-init
+// <script src="sonarium.iife.js" data-auto data-theme="paper" data-ambient="0.2"></script>
+function autoInit(): void {
+  if (typeof document === 'undefined') return
+  const script = document.currentScript as HTMLScriptElement | null
+  if (!script || script.dataset.auto === undefined) return
+  const opts: SonariumOptions = {}
+  if (script.dataset.theme) opts.theme = script.dataset.theme as SonariumOptions['theme']
+  if (script.dataset.key) opts.key = script.dataset.key
+  if (script.dataset.ambient) opts.ambient = parseFloat(script.dataset.ambient)
+  if (script.dataset.listener) opts.listener = script.dataset.listener as SonariumOptions['listener']
+  if (script.dataset.volume) opts.volume = parseFloat(script.dataset.volume)
+  if (script.dataset.panning) opts.panning = script.dataset.panning as SonariumOptions['panning']
+  const boot = () => {
+    try {
+      const engine = create(opts)
+      ;(window as unknown as Record<string, unknown>).sonarium = engine
+    } catch (err) {
+      console.warn('[sonarium] auto-init failed', err)
+    }
+  }
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', boot, { once: true })
+  } else {
+    boot()
+  }
+}
+
+autoInit()

package/src/interact/activate.ts

@@ -0,0 +1,56 @@
+/**
+ * L2 — activation: full notes on press (I2), container strums (I3), toggle intervals (I6).
+ */
+import type { Engine } from '../core/engine'
+import { ELIGIBLE_SELECTOR } from '../core/scanner'
+
+const DEDUPE_MS = 80
+
+export function attachActivate(engine: Engine): () => void {
+  const lastHit = new WeakMap<Element, number>()
+
+  const activate = (target: Element | null) => {
+    const el = engine.scanner?.resolve(target)
+    if (!el) return
+    const now = performance.now()
+    if (now - (lastHit.get(el) ?? -Infinity) < DEDUPE_MS) return
+    lastHit.set(el, now)
+
+    const profile = engine.scanner.profileFor(el)
+    if (!profile) return
+    if (profile.role === 'toggle') return // sounded by the change handler (I6)
+    if (profile.role === 'container') {
+      const children = Array.from(el.querySelectorAll(ELIGIBLE_SELECTOR))
+        .filter((c) => c.parentElement && engine.scanner.resolve(c) === c)
+        .filter((c) => {
+          const r = c.getBoundingClientRect()
+          return r.width > 0 && r.bottom > 0 && r.top < window.innerHeight
+        })
+      if (children.length >= 2) {
+        engine.strum(children, 0.5)
+        return
+      }
+    }
+    engine.excite(el, 0.75, 'hit')
+  }
+
+  // pointerdown for latency (<30 ms budget); click catches keyboard activation (Enter/Space).
+  const onPointerDown = (e: PointerEvent) => activate(e.target as Element | null)
+  const onClick = (e: MouseEvent) => activate(e.target as Element | null)
+
+  const onChange = (e: Event) => {
+    const t = e.target
+    if (!(t instanceof HTMLInputElement) || (t.type !== 'checkbox' && t.type !== 'radio')) return
+    const on = t.checked
+    engine.excite(t, 0.5, on ? 'toggle-on' : 'toggle-off')
+  }
+
+  window.addEventListener('pointerdown', onPointerDown, { passive: true })
+  window.addEventListener('click', onClick, { passive: true })
+  window.addEventListener('change', onChange, { passive: true })
+  return () => {
+    window.removeEventListener('pointerdown', onPointerDown)
+    window.removeEventListener('click', onClick)
+    window.removeEventListener('change', onChange)
+  }
+}

package/src/interact/drag.ts

@@ -0,0 +1,52 @@
+/**
+ * L2 — drag glissando (MODULAR.md §3): press an interactive element and drag — the pointer
+ * becomes a ribbon controller sweeping scale degrees. The initial hit stays immediate (the
+ * ribbon only gates after 14 px of travel; latency invariant untouched).
+ */
+import type { Engine } from '../core/engine'
+
+const START_PX = 14
+
+export function attachDrag(engine: Engine): () => void {
+  let session: { x0: number; el: Element; handle: ReturnType<Engine['ribbon']> } | null = null
+
+  const onDown = (e: PointerEvent) => {
+    if (!e.isPrimary) return
+    const el = engine.scanner?.resolve(e.target as Element | null)
+    if (!el) return
+    const p = engine.scanner.profileFor(el)
+    if (!p || p.role === 'container' || p.role === 'text') return
+    session = { x0: e.clientX, el, handle: null }
+  }
+
+  const onMove = (e: PointerEvent) => {
+    if (!session) return
+    const dx = e.clientX - session.x0
+    if (!session.handle) {
+      if (Math.abs(dx) < START_PX) return
+      session.handle = engine.ribbon(session.el)
+      if (!session.handle) {
+        session = null
+        return
+      }
+    }
+    session.handle.move(dx)
+  }
+
+  const end = () => {
+    session?.handle?.release()
+    session = null
+  }
+
+  window.addEventListener('pointerdown', onDown, { passive: true })
+  window.addEventListener('pointermove', onMove, { passive: true })
+  window.addEventListener('pointerup', end, { passive: true })
+  window.addEventListener('pointercancel', end, { passive: true })
+  return () => {
+    end()
+    window.removeEventListener('pointerdown', onDown)
+    window.removeEventListener('pointermove', onMove)
+    window.removeEventListener('pointerup', end)
+    window.removeEventListener('pointercancel', end)
+  }
+}

package/src/interact/keyboard.ts

@@ -0,0 +1,48 @@
+/**
+ * L2 — keyboard: focus previews for Tab navigation (I4, accessibility parity) and
+ * typing ticks that rise as the field fills (I5).
+ */
+import type { Engine } from '../core/engine'
+
+const TICK_THROTTLE_MS = 30
+// Pentatonic-safe intervals: ticks climb without ever clashing with the site key.
+const FILL_INTERVALS = [0, 2, 4, 7, 9, 12, 14, 16] as const
+
+export function attachKeyboard(engine: Engine): () => void {
+  let lastTick = 0
+  let lastPointerDownT = -Infinity
+
+  // Clicking focuses too — that focus must stay silent or every click sounds twice
+  // (ghost-trigger fix, v0.5). Only keyboard-driven focus (Tab) previews.
+  const onPointerDown = () => {
+    lastPointerDownT = performance.now()
+  }
+
+  const onFocus = (e: FocusEvent) => {
+    if (performance.now() - lastPointerDownT < 500) return
+    const el = engine.scanner?.resolve(e.target as Element | null)
+    if (el) engine.excite(el, 0.35, 'preview')
+  }
+
+  const onKeydown = (e: KeyboardEvent) => {
+    const t = e.target
+    const editable = t instanceof HTMLElement
+      && (t instanceof HTMLInputElement || t instanceof HTMLTextAreaElement || t.isContentEditable)
+    if (!editable) return
+    const now = performance.now()
+    if (now - lastTick < TICK_THROTTLE_MS) return
+    lastTick = now
+    const len = (t as HTMLInputElement).value?.length ?? t.textContent?.length ?? 0
+    const interval = FILL_INTERVALS[Math.min(FILL_INTERVALS.length - 1, Math.floor(len / 4))] as number
+    engine.excite(t, 0.15, 'tick', undefined, interval)
+  }
+
+  window.addEventListener('pointerdown', onPointerDown, { passive: true, capture: true })
+  window.addEventListener('focusin', onFocus, { passive: true })
+  window.addEventListener('keydown', onKeydown, { passive: true })
+  return () => {
+    window.removeEventListener('pointerdown', onPointerDown, { capture: true })
+    window.removeEventListener('focusin', onFocus)
+    window.removeEventListener('keydown', onKeydown)
+  }
+}

package/src/interact/midi.ts

@@ -0,0 +1,40 @@
+/**
+ * L2-out — Web MIDI bridge (option `midi: true`): every trigger mirrors to the first MIDI
+ * output as note events, channel per role. The page becomes a MIDI controller — record your
+ * browsing into a DAW, or drive hardware from the DOM. Feature-detected; silent elsewhere.
+ */
+import type { Engine } from '../core/engine'
+import type { Role, TriggerDetail } from '../types'
+
+const ROLE_CHANNEL: Partial<Record<Role, number>> = {
+  button: 0, link: 1, toggle: 2, input: 3, heading: 4, media: 5, item: 6, text: 7, container: 8,
+}
+
+export function attachMidi(engine: Engine): () => void {
+  const nav = navigator as Navigator & { requestMIDIAccess?: () => Promise<unknown> }
+  if (typeof nav.requestMIDIAccess !== 'function') return () => {}
+  let out: { send(data: number[]): void } | null = null
+  let off: (() => void) | null = null
+
+  nav.requestMIDIAccess()
+    .then((access) => {
+      const a = access as unknown as { outputs: Map<string, { send(data: number[]): void }> }
+      out = a.outputs.values().next().value ?? null
+      if (!out) return
+      off = engine.on('trigger', (detail) => {
+        const d = detail as TriggerDetail
+        const note = Math.max(0, Math.min(127, Math.round(d.profile.midi)))
+        const vel = Math.max(1, Math.min(127, Math.round(d.velocity * d.profile.velocityScale * 127)))
+        const ch = ROLE_CHANNEL[d.profile.role] ?? 9
+        try {
+          out!.send([0x90 | ch, note, vel])
+          setTimeout(() => {
+            try { out?.send([0x80 | ch, note, 0]) } catch { /* device gone */ }
+          }, Math.min(4000, d.profile.durationS * 1000 + 60))
+        } catch { /* device gone */ }
+      })
+    })
+    .catch(() => { /* permission denied — stay silent */ })
+
+  return () => off?.()
+}