@joewinke/jatui 0.12.0 → 0.13.0

package/dist/components/VideoPlayer.svelte

@@ -15,6 +15,8 @@
 	export type { VideoMarker } from '../video/band/markers';
 	// mos-5lzns.33 — night dimming.
 	export type { NightMode, NightWindow } from '../video/night/clock';
+	// mos-5lzns.31 — audio graph.
+	export type { AudioState, AudioStatus, AudioBrokenReason } from '../video/audio/graph';
 </script>
 
 <script lang="ts">
@@ -157,6 +159,13 @@
 		type NightFrame,
 		type NightState
 	} from '../video/night/track';
+	import {
+		createAudioSession,
+		routeSafety,
+		AUDIO_TARGET_DEFAULT,
+		type AudioBrokenReason,
+		type AudioState
+	} from '../video/audio';
 
 	let {
 		src,
@@ -214,6 +223,12 @@
 		strobeGuard = true,
 		onNightModeChange = undefined,
 		onNightBlind = undefined,
+		loudness = undefined,
+		loudnessTarget = AUDIO_TARGET_DEFAULT,
+		quietListening = undefined,
+		limiter = undefined,
+		onAudioState = undefined,
+		onAudioBroken = undefined,
 		class: className = ''
 	}: {
 		src: string;
@@ -350,6 +365,46 @@
 		onNightModeChange?: (mode: NightMode) => void;
 		/** Frame readback was refused (CORS-tainted canvas) — night fell back to a fixed level. */
 		onNightBlind?: () => void;
+		/**
+		 * Audio graph (mos-5lzns.31) — all three default OFF (absent = the
+		 * feature does not exist on this player and nothing is ever routed).
+		 *
+		 * `loudness`: a gated RMS meter rides the gain slowly toward
+		 * `loudnessTarget` (dBFS, −30…−12, default −20) so a whispered video and
+		 * a blaring one arrive at the same level; clamped 0.3–1.35×, it rescues a
+		 * quiet mix by a few dB and never becomes an amplifier.
+		 * `quietListening`: loudness-compensated tone that rises as the volume
+		 * drops (and sits a little on while night is armed).
+		 * `limiter`: catches peaks above −3 dBFS that the slow rider can't.
+		 *
+		 * ⚠ Routing into WebAudio is permanent for the element, and a source
+		 * that isn't CORS-clean routes to SILENCE. So the player routes only
+		 * when the src is blob:/data: or `crossorigin` is set ("anonymous" /
+		 * "use-credentials", with the server answering Access-Control-Allow-
+		 * Origin) — a same-origin URL is NOT enough, since it may redirect to
+		 * storage on another origin. Anything else is refused and plays
+		 * unprocessed (`status: 'cors'`). It also waits for the AudioContext to
+		 * be `running` (a user gesture); until then native audio plays.
+		 *
+		 * After routing it cannot be undone, so the player reports
+		 * `status: 'broken'` and calls `onAudioBroken(reason)`:
+		 * · 'unsafe-src' — the src later changed to one that isn't route-safe
+		 *   (or `crossorigin` was removed). Remount the player (a fresh element)
+		 *   for that source.
+		 * · 'silent' — bit-exact silence for 4s while the video plays audibly
+		 *   AND the browser shows decoded audio flowing (a video with no audio
+		 *   track never fires). Show a notice and/or turn the audio features
+		 *   off for that src — do NOT remount; it would loop.
+		 * · 'build-failed' — construction threw: plain audio for the session.
+		 */
+		loudness?: boolean;
+		loudnessTarget?: number;
+		quietListening?: boolean;
+		limiter?: boolean;
+		/** Graph status + the rider's live gain (≤5×/s while matching acts). */
+		onAudioState?: (state: AudioState) => void;
+		/** Entered `broken`: 'build-failed' | 'unsafe-src' | 'silent' (see above). */
+		onAudioBroken?: (reason: AudioBrokenReason) => void;
 		class?: string;
 	} = $props();
 
@@ -620,6 +675,74 @@
 		flashOsd(formatSpeedLabel(baseRate));
 	}
 
+	// ── Audio (video/audio/*) ───────────────────────────────────────────────
+	// The session owns the graph and its one-way door; this block only hands
+	// it the element (inside `route`) and re-applies on every input it reads.
+	// Inert until a feature is on: no context, no routing. Gestures anywhere
+	// on the page resume a suspended context and retry a pending route.
+	let audio: ReturnType<typeof createAudioSession> | null = null;
+	$effect(() => {
+		const v = videoEl;
+		if (!v) return;
+		const s = createAudioSession({
+			// The attribute is what will load next; currentSrc lags it until loadstart.
+			routable: () => routeSafety(v.getAttribute('src') || v.currentSrc, v.getAttribute('crossorigin')),
+			context: () => new AudioContext(),
+			route: (ctx) => (ctx as AudioContext).createMediaElementSource(v),
+			playback: () => {
+				const m = v as HTMLVideoElement & {
+					webkitAudioDecodedByteCount?: number;
+					mozHasAudio?: boolean;
+					audioTracks?: { length: number };
+				};
+				return {
+					playing: !v.paused && !v.ended,
+					hidden: document.hidden,
+					audible: !v.muted && v.volume > 0,
+					time: v.currentTime,
+					audioDecoded: typeof m.webkitAudioDecodedByteCount === 'number' ? m.webkitAudioDecodedByteCount : null,
+					audioPresent:
+						typeof m.mozHasAudio === 'boolean' ? m.mozHasAudio : m.audioTracks ? m.audioTracks.length > 0 : null
+				};
+			},
+			onState: (st) => onAudioState?.(st),
+			onBroken: (reason) => onAudioBroken?.(reason)
+		});
+		audio = s;
+		const sync = () => untrack(() => s.apply(audioOpts(v)));
+		const gesture = () => s.gesture();
+		const media = ['volumechange', 'loadstart', 'loadedmetadata'];
+		const gestures = ['pointerdown', 'pointerup', 'keydown', 'touchend'];
+		for (const e of media) v.addEventListener(e, sync);
+		v.addEventListener('play', gesture);
+		for (const e of gestures) window.addEventListener(e, gesture, { capture: true, passive: true });
+		return () => {
+			for (const e of media) v.removeEventListener(e, sync);
+			v.removeEventListener('play', gesture);
+			for (const e of gestures) window.removeEventListener(e, gesture, { capture: true });
+			s.dispose();
+			audio = null;
+		};
+	});
+	function audioOpts(v: HTMLVideoElement) {
+		return {
+			level: loudness === true,
+			target: loudnessTarget,
+			limiter: limiter === true,
+			quiet: quietListening === true,
+			volume: v.volume,
+			muted: v.muted,
+			night: nightArmedNow
+		};
+	}
+	$effect(() => {
+		const v = videoEl;
+		void crossorigin; // a CORS opt-in clears a 'cors' refusal; removing it after routing is 'unsafe-src'
+		void src;
+		const o = v ? audioOpts(v) : null;
+		if (o) untrack(() => audio?.apply(o));
+	});
+
 	// ── Night (video/night/*) ───────────────────────────────────────────────
 	// The modules decide; this block samples the frame and applies the answer
 	// as CSS variables that exist ONLY while night (or the strobe guard) is

package/dist/components/VideoPlayer.svelte.d.ts

@@ -3,11 +3,13 @@ export type { BandAxis, BandState } from '../video/band/axis';
 export type { VideoLumaTrack } from '../video/band/luma';
 export type { VideoMarker } from '../video/band/markers';
 export type { NightMode, NightWindow } from '../video/night/clock';
+export type { AudioState, AudioStatus, AudioBrokenReason } from '../video/audio/graph';
 import type { VideoBookmark, VideoChapter, VideoSpeakerTalkTime, VideoSpeakerTurn, VideoTranscriptSegment, VideoWaveform } from '../video/types';
 import { type BandState } from '../video/band/axis';
 import { type VideoLumaTrack } from '../video/band/luma';
 import { type VideoMarker } from '../video/band/markers';
 import { type NightMode, type NightWindow } from '../video/night/clock';
+import { type AudioBrokenReason, type AudioState } from '../video/audio';
 type $$ComponentProps = {
     src: string;
     poster?: string | null;
@@ -138,6 +140,46 @@ type $$ComponentProps = {
     onNightModeChange?: (mode: NightMode) => void;
     /** Frame readback was refused (CORS-tainted canvas) — night fell back to a fixed level. */
     onNightBlind?: () => void;
+    /**
+     * Audio graph (mos-5lzns.31) — all three default OFF (absent = the
+     * feature does not exist on this player and nothing is ever routed).
+     *
+     * `loudness`: a gated RMS meter rides the gain slowly toward
+     * `loudnessTarget` (dBFS, −30…−12, default −20) so a whispered video and
+     * a blaring one arrive at the same level; clamped 0.3–1.35×, it rescues a
+     * quiet mix by a few dB and never becomes an amplifier.
+     * `quietListening`: loudness-compensated tone that rises as the volume
+     * drops (and sits a little on while night is armed).
+     * `limiter`: catches peaks above −3 dBFS that the slow rider can't.
+     *
+     * ⚠ Routing into WebAudio is permanent for the element, and a source
+     * that isn't CORS-clean routes to SILENCE. So the player routes only
+     * when the src is blob:/data: or `crossorigin` is set ("anonymous" /
+     * "use-credentials", with the server answering Access-Control-Allow-
+     * Origin) — a same-origin URL is NOT enough, since it may redirect to
+     * storage on another origin. Anything else is refused and plays
+     * unprocessed (`status: 'cors'`). It also waits for the AudioContext to
+     * be `running` (a user gesture); until then native audio plays.
+     *
+     * After routing it cannot be undone, so the player reports
+     * `status: 'broken'` and calls `onAudioBroken(reason)`:
+     * · 'unsafe-src' — the src later changed to one that isn't route-safe
+     *   (or `crossorigin` was removed). Remount the player (a fresh element)
+     *   for that source.
+     * · 'silent' — bit-exact silence for 4s while the video plays audibly
+     *   AND the browser shows decoded audio flowing (a video with no audio
+     *   track never fires). Show a notice and/or turn the audio features
+     *   off for that src — do NOT remount; it would loop.
+     * · 'build-failed' — construction threw: plain audio for the session.
+     */
+    loudness?: boolean;
+    loudnessTarget?: number;
+    quietListening?: boolean;
+    limiter?: boolean;
+    /** Graph status + the rider's live gain (≤5×/s while matching acts). */
+    onAudioState?: (state: AudioState) => void;
+    /** Entered `broken`: 'build-failed' | 'unsafe-src' | 'silent' (see above). */
+    onAudioBroken?: (reason: AudioBrokenReason) => void;
     class?: string;
 };
 declare const VideoPlayer: import("svelte").Component<$$ComponentProps, {

package/dist/index.d.ts

@@ -12,7 +12,7 @@ export type { ChapterBlock } from './components/replay/ChapterTimeline.svelte';
 export { default as TranscriptPlayer } from './components/TranscriptPlayer.svelte';
 export type { TranscriptSegment, TranscriptBookmark, TranscriptChapter, TranscriptSpeakerTalkTime, } from './components/TranscriptPlayer.svelte';
 export { default as VideoPlayer } from './components/VideoPlayer.svelte';
-export type { VideoChapter, VideoSpeakerTurn, VideoTranscriptSegment, VideoBookmark, VideoWaveform, VideoSpeakerTalkTime, VideoLumaTrack, VideoMarker, BandState, BandAxis, NightMode, NightWindow, } from './components/VideoPlayer.svelte';
+export type { VideoChapter, VideoSpeakerTurn, VideoTranscriptSegment, VideoBookmark, VideoWaveform, VideoSpeakerTalkTime, VideoLumaTrack, VideoMarker, BandState, BandAxis, NightMode, NightWindow, AudioState, AudioStatus, AudioBrokenReason, } from './components/VideoPlayer.svelte';
 export { buildSilenceMap, boostAt, estimateSaving, type SilenceMap, type SilenceWave, type SilenceOpts, type BoostOpts } from './video/advisors/smart-speed';
 export { speakerPace, suggestRates, rateAt, describeRates, type SpeakerPace, type SpeakerPaceRow, type RateMap, type RateTurn, type RateSegment, type SuggestOpts } from './video/advisors/speaker-rate';
 export { snapResume, resumeLabel, type ResumePoint, type ResumeReason, type ResumeCtx, type ResumeOpts } from './video/advisors/resume-point';

package/dist/video/README.md

@@ -20,7 +20,7 @@ props + callback surfaces.
 | `rate.ts` | .28 (done) — filled by **.32** | The rate composer contract (`composeRate`, deadband, clamp), the `SPEED_STEPS` staircase, `formatSpeedLabel`. .32 adds the speaker-pace and silence-map advisors — they never write `playbackRate`; they advise. |
 | `deepLink.ts` | .28 (done) | `?t=` parse/format/read/write (replaceState, throttled, other params preserved). |
 | `settings.ts` | shared — knobs added by .30–.34 | `coerce` (never throws, never junk) + `VIDEO_SETTINGS` registry. A knob lands WITH its reader. |
-| `audio.ts` | **.31** | Loudness matching, quiet listening, limiter — audio-graph contract is in the file header. |
+| `audio.ts` + `audio/` | **.31** (done) | `audio.ts` is the barrel. `rider.ts` — pure: RMS dBFS (silence → null), the 12 dB relative-gated loud estimate (rise 0.08 / forget 0.01), want-gain clamped 0.3–1.35, the asymmetric ride (down 0.15 / up 0.02), limiter constants + `compressorMakeupDb`/`limiterTrim` (DynamicsCompressor's automatic makeup, cancelled by a trim node), `routeSafety` (only blob:/data: or a `crossorigin` load — a same-origin URL may redirect cross-origin and route to SILENCE). `graph.ts` — `createAudioSession`: source → gain → quiet chain → limiter → trim → destination, analyser on the source. Context first, route last: the element is taken only when a feature is on, the source is route-safe and `ctx.state === 'running'` (gestures resume + retry; never navigator.userActivation). After routing it watches: an unsafe src or bit-exact zeros while audibly playing ⇒ `broken` (`unsafe-src` / `silent`) via `onBroken`. A construction throw is a permanent `build-failed` (context closed if the element wasn't taken; kept with source → destination if it was). Level off cancels before it sets; limiter moves are ramped. The element never enters the module — the component passes a `route` closure. |
 | `night.ts` + `night/` | **.33** (done) | `night.ts` is the barrel. `meter.ts` — 32×18 frame bytes → Rec.709 luma + blown share, asymmetric smoothing, bias-light cells from the same bytes. `levels.ts` — luma → brightness/saturation/warmth/vignette off `NIGHT_FLOOR` 0.34, blind fixed level, the light-theme surround. `clock.ts` — local-clock `auto` window + the `N` auto/on/off cycle (no hyprsunset). `track.ts` — prediction (only ever adds dimming), flash intervals, `composeNight` (darker at once, brighter released per tick — never a jump). |
 | `presence.ts` | **.34** | Wind-down (Idle Detection), resume-at-sentence, FLIP open. |
 | `advisors/` | **.27 (done)** | The five extension-library pure advisors, ported verbatim: `smart-speed` (silence map + boost), `speaker-rate` (measured wpm + suggested rates), `resume-point` (sentence-snapping + the label), `quiet-listening` (tone-only chain + `amountFor`), `qr` (ISO 18004 encoder v1–10). Each has its own README row in `advisors/README.md`; the `--self-test` suites live on as vitest in `tests/unit/advisors/` (`npm run test:advisors`). |
@@ -44,8 +44,9 @@ feature task.
    the prompt).
 3. **Measuring code is an advisor; the component decides and applies.**
    Modules under `src/lib/video/` read no settings and touch no `<video>`
-   (the audio graph builder is the one exception, and it takes a
-   MediaElementAudioSourceNode, never the element). Knobs arrive as an
+   (the audio graph builder is the one exception: it touches AudioContext,
+   but takes the element only through a `route` closure the component owns
+   — never the element itself). Knobs arrive as an
    `opts` argument; a bad argument returns a safe neutral value rather than
    throwing. This is what keeps every module node-testable under
    `npm run test:unit` (the advisor vitest suites run under

package/dist/video/audio/graph.d.ts

@@ -0,0 +1,115 @@
+/** What the host asks for. Booleans are "feature on"; volume/muted/night feed quiet listening's amount. */
+export interface AudioOpts {
+    level: boolean;
+    target?: number;
+    limiter: boolean;
+    quiet: boolean;
+    volume?: number;
+    muted?: boolean;
+    night?: boolean;
+}
+/**
+ * · 'off'    — nothing routed (no feature on, no source yet, or the context is
+ *              still waiting for a gesture to start). Native audio plays.
+ * · 'live'   — routed and processing.
+ * · 'cors'   — a feature is on but the source isn't route-safe: refused,
+ *              audio plays unprocessed. Clears when the source does.
+ * · 'broken' — see `reason`.
+ */
+export type AudioStatus = 'off' | 'live' | 'cors' | 'broken';
+/**
+ * · 'build-failed' — construction threw; plain audio for the session (permanent).
+ * · 'unsafe-src'   — routed, then the src/crossorigin changed to one that is
+ *                    not route-safe: this element may now be SILENT.
+ * · 'silent'       — routed, playing audibly, clock advancing, decoded audio
+ *                    evidently flowing, and the analyser reads bit-exact
+ *                    zeros for SILENT_AFTER_MS. Show a notice / disable the
+ *                    features for this src — do NOT remount (it would loop).
+ */
+export type AudioBrokenReason = 'build-failed' | 'unsafe-src' | 'silent';
+export interface AudioState {
+    status: AudioStatus;
+    /** Why `status` is 'broken'; null otherwise. */
+    reason: AudioBrokenReason | null;
+    /** The rider's current gain, dB (0 when level matching is off or unmeasured). */
+    gainDb: number;
+    /** The gated loud-level estimate, dBFS — null until something has been heard. */
+    loudDb: number | null;
+    /** Quiet listening's current amount, 0..1. */
+    quiet: number;
+}
+interface ParamLike {
+    value: number;
+    setTargetAtTime?(v: number, t: number, tau: number): unknown;
+    setValueAtTime?(v: number, t: number): unknown;
+    cancelScheduledValues?(t: number): unknown;
+}
+interface NodeLike {
+    connect(dest: unknown): unknown;
+    disconnect?(): unknown;
+    gain?: ParamLike;
+    threshold?: ParamLike;
+    knee?: ParamLike;
+    ratio?: ParamLike;
+    attack?: ParamLike;
+    release?: ParamLike;
+    fftSize?: number;
+    getFloatTimeDomainData?(buf: Float32Array): void;
+}
+export interface AudioContextLike {
+    currentTime: number;
+    destination: unknown;
+    /** 'suspended' | 'running' | 'closed' — absent (a test double) reads as running. */
+    state?: string;
+    createGain(): NodeLike;
+    createDynamicsCompressor(): NodeLike;
+    createAnalyser(): NodeLike;
+    createBiquadFilter?(): unknown;
+    resume?(): unknown;
+    close?(): unknown;
+    addEventListener?(type: string, fn: () => void): void;
+}
+export interface AudioPlayback {
+    /** Not paused and not ended. */
+    playing: boolean;
+    /** Tab hidden — the rider holds its estimate. */
+    hidden: boolean;
+    /** Not muted and volume > 0 — silence would be a fault, not a choice. */
+    audible: boolean;
+    /** currentTime, seconds. */
+    time: number;
+    /**
+     * Evidence that the element HAS decoded audio. `audioDecoded`: Chromium's
+     * webkitAudioDecodedByteCount (must be RISING to count); `audioPresent`:
+     * Gecko's mozHasAudio or WebKit's audioTracks.length > 0. null = unknown.
+     * With no positive evidence the silence watchdog never fires.
+     */
+    audioDecoded?: number | null;
+    audioPresent?: boolean | null;
+}
+export interface AudioSessionDeps {
+    /** Is the element's current source route-safe? (rider.ts `routeSafety`) */
+    routable(): 'ok' | 'wait' | 'cors';
+    /** Create the AudioContext. Does NOT touch the element. */
+    context(): AudioContextLike;
+    /** Take the element: createMediaElementSource. The one-way door — called at most once. */
+    route(ctx: AudioContextLike): NodeLike;
+    playback(): AudioPlayback;
+    /** State changes + each rider tick. */
+    onState?(state: AudioState): void;
+    /** Entered `broken` (or its reason changed). */
+    onBroken?(reason: AudioBrokenReason): void;
+    /** Timer seam (tests). Defaults to setInterval/clearInterval. */
+    every?(ms: number, fn: () => void): () => void;
+}
+export interface AudioSession {
+    apply(opts: AudioOpts): void;
+    /** A user gesture (or play): resume the context, retry a pending route. */
+    gesture(): void;
+    /** One watchdog + rider step (the session's own timer calls this; exposed for tests). */
+    tick(): void;
+    state(): AudioState;
+    dispose(): void;
+}
+export declare function createAudioSession(deps: AudioSessionDeps): AudioSession;
+export {};

package/dist/video/audio/graph.js

@@ -0,0 +1,400 @@
+/**
+ * The audio graph (mos-5lzns.31) — the one module under src/lib/video/ that
+ * touches WebAudio. Ported from extension-library `library.js`
+ * (audioEnsure / audioTick / applyAudioSettings / applyQuietAmount).
+ *
+ *   source ─┬─► gain ─► quiet.input … quiet.output ─► limiter ─► trim ─► destination
+ *           └─► analyser   (taps the SOURCE: measure the material, not our
+ *                           own correction, or the loop chases its own tail)
+ *
+ * Quiet listening sits between level and limiter: it shapes TONE, so it acts
+ * on the signal at the level you'll hear, and the limiter is last by
+ * definition. `trim` cancels the limiter's automatic makeup gain (rider.ts
+ * `compressorMakeupDb`), so toggling the limiter moves no level. If the quiet
+ * chain can't build, the graph splices around it — tone is optional; sound
+ * is not.
+ *
+ * `createMediaElementSource` is a ONE-WAY DOOR — the spec has no way back once
+ * an element is routed. The contract is "never a silent player":
+ *
+ * 1. CONTEXT FIRST, ROUTE LAST. The context is created when a feature is on,
+ *    `resume()`d on every gesture, and the element is routed only once
+ *    `ctx.state === 'running'`. A suspended context on a routed element is
+ *    silence; a suspended context on an UNrouted element is nothing at all —
+ *    native audio keeps playing, and the next gesture retries. We never
+ *    consult navigator.userActivation: the context's own state is the truth.
+ * 2. ROUTE ONLY A CORS-CLEAN SOURCE (rider.ts `routeSafety`): blob:/data:, or
+ *    the element has `crossorigin`. A same-origin URL may 302 to storage on
+ *    another origin, and an opaque response routes to zeros.
+ * 3. AFTER ROUTING, WATCH. A later src that is not route-safe, or an analyser
+ *    reading bit-exact zeros for SILENT_AFTER_MS while the element plays
+ *    audibly AND there is positive evidence decoded audio is flowing (a
+ *    rising webkitAudioDecodedByteCount, mozHasAudio, audioTracks), is
+ *    reported as `broken` (`unsafe-src` / `silent`) via `onBroken`. A video
+ *    with no audio track never reads as silent. Both clear if the condition
+ *    clears. Remounting is right for `unsafe-src` (a fresh element); for
+ *    `silent` the host should show a notice and/or turn the audio features
+ *    off for that src — remounting would just loop.
+ * 4. A construction throw is a permanent `broken` (`build-failed`). If it
+ *    happened before the element was taken, the context is closed; if after,
+ *    the source is wired straight to the destination and the context KEPT —
+ *    closing it would silence the routed element.
+ *
+ * Disabled leaves no trace: level off CANCELS scheduled values before setting
+ * 1; the limiter's threshold ramps back to 0 dBFS with its trim to unity; the
+ * quiet chain rests at the identity (amount 0). A graph is never built just
+ * to neutralise it.
+ *
+ * The element itself never enters this module: the component passes `route`,
+ * a closure that calls createMediaElementSource on it.
+ */
+import { amountFor, createQuietChain } from '../advisors/quiet-listening';
+import { AUDIO_FFT_SIZE, AUDIO_TICK_MS, LIMITER, LIMITER_OFF_THRESHOLD, LIMITER_TAU, RIDE_TAU, SILENT_AFTER_MS, clampTarget, gainDb, gateLoud, limiterTrim, rideStep, rmsDb, wantGain } from './rider';
+const defaultEvery = (ms, fn) => {
+    const id = setInterval(fn, ms);
+    return () => clearInterval(id);
+};
+const safely = (fn) => {
+    try {
+        fn();
+    }
+    catch {
+        /* never throw out of the audio path */
+    }
+};
+export function createAudioSession(deps) {
+    let ctx = null;
+    let routed = false;
+    let buildFailed = false;
+    let unsafeSrc = false;
+    let silent = false;
+    let refusedCors = false;
+    let gain = null;
+    let limiter = null;
+    let trim = null;
+    let analyser = null;
+    let quiet = null;
+    let buf = null;
+    let ride = 1;
+    let loud = null;
+    let amount = 0;
+    let levelOn = false;
+    let limiterOn = false;
+    let target = clampTarget(undefined);
+    let stopTimer = null;
+    let lastOpts = null;
+    let anyOnLast = false;
+    let zeroMs = 0;
+    let lastDecoded = null;
+    let lastTime = Number.NaN;
+    let disposed = false;
+    let lastSent = '';
+    let lastBroken = null;
+    const reason = () => buildFailed ? 'build-failed' : routed && unsafeSrc ? 'unsafe-src' : routed && silent ? 'silent' : null;
+    const status = () => reason() ? 'broken' : routed ? 'live' : refusedCors ? 'cors' : 'off';
+    const state = () => ({
+        status: status(),
+        reason: reason(),
+        gainDb: levelOn ? gainDb(ride) : 0,
+        loudDb: loud,
+        quiet: amount
+    });
+    const emit = () => {
+        const s = state();
+        if (s.reason !== lastBroken) {
+            lastBroken = s.reason;
+            if (s.reason)
+                safely(() => deps.onBroken?.(s.reason));
+        }
+        const key = `${s.status}|${s.reason}|${s.gainDb.toFixed(2)}|${s.loudDb?.toFixed(1)}|${s.quiet.toFixed(2)}`;
+        if (key === lastSent)
+            return;
+        lastSent = key;
+        safely(() => deps.onState?.(s));
+    };
+    const now = () => (ctx && Number.isFinite(ctx.currentTime) ? ctx.currentTime : 0);
+    const running = () => !!ctx && (ctx.state === undefined || ctx.state === 'running');
+    const routable = () => {
+        try {
+            return deps.routable();
+        }
+        catch {
+            return 'wait';
+        }
+    };
+    /** Ask the context to start; on success retry whatever is pending. Never loops. */
+    function kick() {
+        if (!ctx || running())
+            return;
+        try {
+            const p = ctx.resume?.();
+            p?.then?.(() => {
+                if (!disposed && running() && lastOpts)
+                    apply(lastOpts);
+            }, () => { });
+        }
+        catch {
+            /* a refused resume just waits for the next gesture */
+        }
+    }
+    function closeCtx() {
+        const c = ctx;
+        ctx = null;
+        safely(() => {
+            const r = c?.close?.();
+            r?.catch?.(() => { });
+        });
+    }
+    /** Route the element and wire the graph. Only ever called with a running context. */
+    function build() {
+        const c = ctx;
+        let source = null;
+        try {
+            source = deps.route(c);
+            routed = true;
+            gain = c.createGain();
+            limiter = c.createDynamicsCompressor();
+            // Built at rest: threshold 0 dBFS, trim unity. configure() ramps them in.
+            limiter.threshold.value = LIMITER_OFF_THRESHOLD;
+            limiter.knee.value = LIMITER.knee;
+            limiter.ratio.value = LIMITER.ratio;
+            limiter.attack.value = LIMITER.attack;
+            limiter.release.value = LIMITER.release;
+            trim = c.createGain();
+            trim.gain.value = 1;
+            analyser = c.createAnalyser();
+            analyser.fftSize = AUDIO_FFT_SIZE;
+            buf = new Float32Array(AUDIO_FFT_SIZE);
+            // The quiet chain degrades to a unity wire or {input:null} on a context
+            // it doesn't recognise — splice around the null case instead of throwing
+            // into the catch below, where the element is already taken.
+            const q = createQuietChain(c);
+            quiet = q.input && q.output ? q : null;
+            source.connect(analyser);
+            source.connect(gain);
+            if (quiet) {
+                gain.connect(quiet.input);
+                quiet.output.connect(limiter);
+            }
+            else {
+                gain.connect(limiter);
+            }
+            limiter.connect(trim);
+            trim.connect(c.destination);
+            stopTimer = (deps.every ?? defaultEvery)(AUDIO_TICK_MS, tick);
+            return true;
+        }
+        catch {
+            buildFailed = true;
+            for (const n of [gain, limiter, trim, analyser])
+                safely(() => n?.disconnect?.());
+            quiet?.dispose();
+            quiet = gain = limiter = trim = analyser = null;
+            if (source) {
+                // The door closed behind us: a partly-built graph is silence. Wire the
+                // source straight out and KEEP the context — plain audio is all
+                // "broken" may mean.
+                safely(() => {
+                    source.disconnect?.();
+                    source.connect(c.destination);
+                });
+            }
+            else {
+                // Never took the element: nothing depends on this context.
+                routed = false;
+                closeCtx();
+            }
+            return false;
+        }
+    }
+    function setLevel(on) {
+        if (on === levelOn)
+            return;
+        levelOn = on;
+        if (on)
+            return;
+        // Hand the level back exactly as it was — cancel first, then set. A ramp
+        // toward 1 would leave a half-faded trace on the param timeline. The
+        // estimate resets too, so re-enabling starts clean, not stale.
+        ride = 1;
+        loud = null;
+        const p = gain?.gain;
+        if (!p)
+            return;
+        try {
+            p.cancelScheduledValues?.(now());
+            if (p.setValueAtTime)
+                p.setValueAtTime(1, now());
+            else
+                p.value = 1;
+        }
+        catch {
+            p.value = 1;
+        }
+    }
+    function setLimiter(on) {
+        if (on === limiterOn || !limiter?.threshold)
+            return;
+        limiterOn = on;
+        const th = on ? LIMITER.threshold : LIMITER_OFF_THRESHOLD;
+        // Ramped, never a .value write, and the trim moves with it so the
+        // compressor's makeup gain never reaches the output.
+        const ramp = (p, v) => {
+            if (!p)
+                return;
+            try {
+                if (p.setTargetAtTime)
+                    p.setTargetAtTime(v, now(), LIMITER_TAU);
+                else
+                    p.value = v;
+            }
+            catch {
+                p.value = v;
+            }
+        };
+        ramp(limiter.threshold, th);
+        ramp(trim?.gain, limiterTrim(th));
+    }
+    function tick() {
+        if (disposed || !routed || buildFailed || !analyser)
+            return;
+        let pb;
+        try {
+            pb = deps.playback();
+        }
+        catch {
+            return;
+        }
+        if (!pb.playing) {
+            lastTime = Number.NaN;
+            return;
+        }
+        try {
+            analyser.getFloatTimeDomainData?.(buf);
+        }
+        catch {
+            return;
+        }
+        // Watchdog: bit-exact zeros while audible, the clock advances AND there is
+        // positive evidence that decoded audio exists and is flowing. A video
+        // with no audio track reads zeros forever and must never be called
+        // "silent" — no evidence, no verdict.
+        const advanced = Number.isFinite(lastTime) && pb.time > lastTime;
+        lastTime = pb.time;
+        const decoded = Number.isFinite(pb.audioDecoded) ? pb.audioDecoded : null;
+        const flowing = decoded !== null
+            ? lastDecoded !== null && decoded > lastDecoded // Chromium: bytes still decoding
+            : pb.audioPresent === true; // Gecko mozHasAudio / WebKit audioTracks
+        lastDecoded = decoded;
+        if (!flowing) {
+            zeroMs = 0;
+            if (silent) {
+                silent = false;
+                emit();
+            }
+        }
+        else if (pb.audible && advanced) {
+            let zero = true;
+            for (let i = 0; i < buf.length; i++) {
+                if (buf[i] !== 0) {
+                    zero = false;
+                    break;
+                }
+            }
+            zeroMs = zero ? zeroMs + AUDIO_TICK_MS : 0;
+            const s = zeroMs >= SILENT_AFTER_MS;
+            if (s !== silent) {
+                silent = s;
+                emit();
+            }
+        }
+        // Rider. Hidden: the estimate holds.
+        if (!levelOn || pb.hidden || !gain?.gain)
+            return;
+        const level = rmsDb(buf);
+        if (level == null)
+            return; // silence carries no vote
+        loud = gateLoud(loud, level);
+        ride = rideStep(ride, wantGain(loud, target));
+        safely(() => gain.gain.setTargetAtTime?.(ride, now(), RIDE_TAU));
+        emit();
+    }
+    function configure(o, q) {
+        setLevel(o.level === true);
+        setLimiter(o.limiter === true);
+        amount = q && quiet ? amountFor(o.muted ? 0 : o.volume, !!o.night, {}) : 0;
+        quiet?.setAmount(amount);
+    }
+    function apply(opts) {
+        if (disposed)
+            return;
+        const o = opts ?? {};
+        lastOpts = o;
+        target = clampTarget(o.target);
+        const q = o.quiet === true;
+        const anyOn = o.level === true || o.limiter === true || q;
+        anyOnLast = anyOn;
+        if (buildFailed)
+            return emit();
+        if (routed) {
+            // The door is shut behind us; all we can do is watch and report.
+            unsafeSrc = routable() === 'cors';
+            configure(o, q);
+            return emit();
+        }
+        // Never create a context — let alone route — just to neutralise it.
+        if (!anyOn) {
+            refusedCors = false;
+            return emit();
+        }
+        const r = routable();
+        refusedCors = r === 'cors';
+        if (r !== 'ok')
+            return emit();
+        if (!ctx) {
+            try {
+                ctx = deps.context();
+                const c = ctx;
+                c.addEventListener?.('statechange', () => {
+                    if (!disposed && ctx === c && running() && !routed && lastOpts)
+                        apply(lastOpts);
+                });
+            }
+            catch {
+                ctx = null;
+                buildFailed = true;
+                return emit();
+            }
+        }
+        if (!running()) {
+            // Suspended: do NOT route. Native audio keeps playing; the resume below
+            // (or the next gesture's) retries.
+            kick();
+            return emit();
+        }
+        if (!build())
+            return emit();
+        configure(o, q);
+        emit();
+    }
+    function gesture() {
+        // All features off: a click is not our business (no context, no apply).
+        if (disposed || buildFailed || !anyOnLast)
+            return;
+        if (ctx && !running())
+            kick();
+        if (!routed && lastOpts)
+            apply(lastOpts);
+    }
+    function dispose() {
+        if (disposed)
+            return;
+        disposed = true;
+        stopTimer?.();
+        stopTimer = null;
+        quiet?.dispose();
+        closeCtx();
+        gain = limiter = trim = analyser = quiet = null;
+    }
+    return { apply, gesture, tick, state, dispose };
+}

package/dist/video/audio/rider.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Loudness matching — the pure half (mos-5lzns.31). Ported from
+ * extension-library `library.js` §Loudness matching (audioLevel / audioTick)
+ * and FEATURES.md §Loudness matching; every number below is the extension's.
+ *
+ * Shape: a gated RMS estimate of the programme's LOUD level drives a slow,
+ * asymmetric gain rider toward a target. The graph (./graph.ts) feeds this
+ * module the analyser's time-domain buffer every AUDIO_TICK_MS and lands the
+ * returned ride on the gain param; nothing here touches WebAudio.
+ *
+ * Not true LUFS — no K-weighting, no channel weighting. The thing being
+ * corrected is "this video is louder than the last one", and RMS answers that
+ * honestly at a fraction of the cost.
+ */
+/** How often the rider reads the meter. fftSize 2048 is ~46ms at 44.1kHz. */
+export declare const AUDIO_TICK_MS = 200;
+export declare const AUDIO_FFT_SIZE = 2048;
+/** Where matching aims, dBFS RMS. At −20 an ordinary video is left at ~1.0×. */
+export declare const AUDIO_TARGET_DEFAULT = -20;
+export declare const AUDIO_TARGET_MIN = -30;
+export declare const AUDIO_TARGET_MAX = -12;
+/** Below this RMS a window is silence — it carries no vote about level. */
+export declare const SILENCE_RMS = 0.00001;
+/**
+ * The gate is the whole difference between working and shouting. A 46ms
+ * window of speech runs ~−15 dB, the pause between sentences ~−40; driving
+ * gain off the instantaneous level climbs through every gap and blares the
+ * next word. So the estimate only listens to material within GATE_DB of what
+ * it already believes the loud level to be (EBU R128's relative-gate idea).
+ */
+export declare const GATE_DB = 12;
+/** Rise toward a louder reading quickly … */
+export declare const LOUD_RISE = 0.08;
+/** … and forget a quiet one very slowly (a new video does NOT reset it). */
+export declare const LOUD_FORGET = 0.01;
+/**
+ * The clamp. 1.35 is a deliberate ceiling, not a round number: measured
+ * across the extension's library, target −20 leaves normal material at 1.0×,
+ * lifts a quiet podcast by the full +2.6 dB and pulls a hot one down 10 dB.
+ * Matching may rescue a quiet mix by a few dB; it may NOT become an amplifier.
+ */
+export declare const GAIN_MIN = 0.3;
+export declare const GAIN_MAX = 1.35;
+/**
+ * Asymmetric ride — the opposite way round from night dimming: coming DOWN
+ * off something too loud is quick, going up is slow enough to be inaudible.
+ */
+export declare const RIDE_DOWN = 0.15;
+export declare const RIDE_UP = 0.02;
+/** setTargetAtTime constant the ride lands with, so the param smooths between ticks. */
+export declare const RIDE_TAU = 0.25;
+/**
+ * The limiter — the fast half. High ratio, knee 0, fast attack: it does
+ * nothing until something actually peaks. Off moves the threshold to 0 dBFS
+ * rather than rewiring the graph (rewiring a live graph clicks); the move is
+ * RAMPED (LIMITER_TAU), never a `.value` write.
+ *
+ * Not a straight wire on its own: DynamicsCompressorNode applies automatic
+ * makeup gain (see `compressorMakeupDb`) — ~+1.7 dB at −3 dBFS / 20:1 — so the
+ * graph follows the limiter with a trim GainNode at the inverse. Without the
+ * trim, "limiter on" is a 1.7 dB level jump, which is exactly the kind of
+ * trace a feature must not leave.
+ */
+export declare const LIMITER: Readonly<{
+    threshold: -3;
+    knee: 0;
+    ratio: 20;
+    attack: 0.003;
+    release: 0.25;
+}>;
+export declare const LIMITER_OFF_THRESHOLD = 0;
+/** Ramp constant for limiter threshold/trim moves — under an event, over a click. */
+export declare const LIMITER_TAU = 0.15;
+/**
+ * Silence watchdog: a routed element whose analyser reads EXACT zeros for this
+ * long while it is playing, audible, its clock advancing AND with positive
+ * evidence that decoded audio is flowing is reported as silent — the
+ * signature of a source that became CORS-tainted after routing (the node
+ * outputs zeros, never noise). Without that evidence (no audio track, or a
+ * browser that can't tell us) it never fires. Exact digital silence in a real
+ * track (a muted-mic screen recording) can still trip it, which is why the
+ * report asks for a notice, never a remount.
+ */
+export declare const SILENT_AFTER_MS = 4000;
+/**
+ * Short-term RMS of a time-domain buffer, in dBFS. `null` for silence (below
+ * SILENCE_RMS), an empty buffer or junk — never −Infinity, never NaN.
+ */
+export declare function rmsDb(buf: ArrayLike<number> | null | undefined): number | null;
+/**
+ * One step of the gated loud-level estimate. `loud` null means "no estimate
+ * yet" — the first real reading seeds it. A null/junk `level` (silence) leaves
+ * the estimate exactly where it was.
+ */
+export declare function gateLoud(loud: number | null, level: number | null): number | null;
+/** Clamp a target to the declared range; junk falls back to the default. */
+export declare function clampTarget(target: unknown): number;
+/**
+ * The gain that would put the measured loud level at `target`, clamped to
+ * [GAIN_MIN, GAIN_MAX]. No estimate yet ⇒ 1 (neutral): we never guess.
+ */
+export declare function wantGain(loud: number | null, target: unknown): number;
+/** One asymmetric step of the ride toward `want`. Junk in ⇒ neutral 1. */
+export declare function rideStep(ride: number, want: number): number;
+/** A ride as dB — for readouts. 1 ⇒ 0 dB; junk ⇒ 0. */
+export declare function gainDb(ride: number): number;
+/**
+ * DynamicsCompressorNode's automatic makeup gain, dB, for knee 0 — the Web
+ * Audio spec's "makeup gain" step (as Chromium/WebKit/Gecko implement it):
+ * fullRangeGain = the curve's output for a 0 dBFS input, makeup =
+ * (1 / fullRangeGain) ^ 0.6. For knee 0 the curve at 0 dBFS is
+ * threshold + (0 − threshold) / ratio, so the makeup is
+ * 0.6 × (−threshold) × (1 − 1/ratio): +1.71 dB at −3 dBFS / 20:1, 0 at a
+ * 0 dBFS threshold. Junk ⇒ 0.
+ */
+export declare function compressorMakeupDb(threshold: unknown, ratio: unknown): number;
+/** The trim gain (linear) that cancels a limiter's makeup at this threshold. */
+export declare function limiterTrim(threshold: number): number;
+/**
+ * Can this element's audio be routed through WebAudio without going SILENT?
+ *
+ * A media response that isn't CORS-clean makes a MediaElementAudioSourceNode
+ * output zeros — and routing is a one-way door, so that is silence with no
+ * way back. A same-origin URL is NOT enough: it may 302 to a signed storage
+ * URL on another origin (MardukOS file routes do exactly that), and without
+ * `crossorigin` the redirected response is opaque. So:
+ *
+ * · 'ok'   — blob:/data: (never leave the page's origin), or the element asked
+ *            for a CORS load (`crossorigin` set — the load is then CORS-clean
+ *            or it fails outright, never silently).
+ * · 'wait' — no source yet; nothing to decide.
+ * · 'cors' — anything else: refuse, play unprocessed.
+ */
+export declare function routeSafety(mediaUrl: unknown, crossorigin: unknown): 'ok' | 'wait' | 'cors';

package/dist/video/audio/rider.js

@@ -0,0 +1,187 @@
+/**
+ * Loudness matching — the pure half (mos-5lzns.31). Ported from
+ * extension-library `library.js` §Loudness matching (audioLevel / audioTick)
+ * and FEATURES.md §Loudness matching; every number below is the extension's.
+ *
+ * Shape: a gated RMS estimate of the programme's LOUD level drives a slow,
+ * asymmetric gain rider toward a target. The graph (./graph.ts) feeds this
+ * module the analyser's time-domain buffer every AUDIO_TICK_MS and lands the
+ * returned ride on the gain param; nothing here touches WebAudio.
+ *
+ * Not true LUFS — no K-weighting, no channel weighting. The thing being
+ * corrected is "this video is louder than the last one", and RMS answers that
+ * honestly at a fraction of the cost.
+ */
+/** How often the rider reads the meter. fftSize 2048 is ~46ms at 44.1kHz. */
+export const AUDIO_TICK_MS = 200;
+export const AUDIO_FFT_SIZE = 2048;
+/** Where matching aims, dBFS RMS. At −20 an ordinary video is left at ~1.0×. */
+export const AUDIO_TARGET_DEFAULT = -20;
+export const AUDIO_TARGET_MIN = -30;
+export const AUDIO_TARGET_MAX = -12;
+/** Below this RMS a window is silence — it carries no vote about level. */
+export const SILENCE_RMS = 1e-5;
+/**
+ * The gate is the whole difference between working and shouting. A 46ms
+ * window of speech runs ~−15 dB, the pause between sentences ~−40; driving
+ * gain off the instantaneous level climbs through every gap and blares the
+ * next word. So the estimate only listens to material within GATE_DB of what
+ * it already believes the loud level to be (EBU R128's relative-gate idea).
+ */
+export const GATE_DB = 12;
+/** Rise toward a louder reading quickly … */
+export const LOUD_RISE = 0.08;
+/** … and forget a quiet one very slowly (a new video does NOT reset it). */
+export const LOUD_FORGET = 0.01;
+/**
+ * The clamp. 1.35 is a deliberate ceiling, not a round number: measured
+ * across the extension's library, target −20 leaves normal material at 1.0×,
+ * lifts a quiet podcast by the full +2.6 dB and pulls a hot one down 10 dB.
+ * Matching may rescue a quiet mix by a few dB; it may NOT become an amplifier.
+ */
+export const GAIN_MIN = 0.3;
+export const GAIN_MAX = 1.35;
+/**
+ * Asymmetric ride — the opposite way round from night dimming: coming DOWN
+ * off something too loud is quick, going up is slow enough to be inaudible.
+ */
+export const RIDE_DOWN = 0.15;
+export const RIDE_UP = 0.02;
+/** setTargetAtTime constant the ride lands with, so the param smooths between ticks. */
+export const RIDE_TAU = 0.25;
+/**
+ * The limiter — the fast half. High ratio, knee 0, fast attack: it does
+ * nothing until something actually peaks. Off moves the threshold to 0 dBFS
+ * rather than rewiring the graph (rewiring a live graph clicks); the move is
+ * RAMPED (LIMITER_TAU), never a `.value` write.
+ *
+ * Not a straight wire on its own: DynamicsCompressorNode applies automatic
+ * makeup gain (see `compressorMakeupDb`) — ~+1.7 dB at −3 dBFS / 20:1 — so the
+ * graph follows the limiter with a trim GainNode at the inverse. Without the
+ * trim, "limiter on" is a 1.7 dB level jump, which is exactly the kind of
+ * trace a feature must not leave.
+ */
+export const LIMITER = Object.freeze({
+    threshold: -3,
+    knee: 0,
+    ratio: 20,
+    attack: 0.003,
+    release: 0.25
+});
+export const LIMITER_OFF_THRESHOLD = 0;
+/** Ramp constant for limiter threshold/trim moves — under an event, over a click. */
+export const LIMITER_TAU = 0.15;
+/**
+ * Silence watchdog: a routed element whose analyser reads EXACT zeros for this
+ * long while it is playing, audible, its clock advancing AND with positive
+ * evidence that decoded audio is flowing is reported as silent — the
+ * signature of a source that became CORS-tainted after routing (the node
+ * outputs zeros, never noise). Without that evidence (no audio track, or a
+ * browser that can't tell us) it never fires. Exact digital silence in a real
+ * track (a muted-mic screen recording) can still trip it, which is why the
+ * report asks for a notice, never a remount.
+ */
+export const SILENT_AFTER_MS = 4000;
+const finite = (n) => typeof n === 'number' && Number.isFinite(n);
+/**
+ * Short-term RMS of a time-domain buffer, in dBFS. `null` for silence (below
+ * SILENCE_RMS), an empty buffer or junk — never −Infinity, never NaN.
+ */
+export function rmsDb(buf) {
+    if (!buf || !(buf.length > 0))
+        return null;
+    let sum = 0;
+    for (let i = 0; i < buf.length; i++) {
+        const s = buf[i];
+        if (!finite(s))
+            return null;
+        sum += s * s;
+    }
+    const rms = Math.sqrt(sum / buf.length);
+    if (!(rms >= SILENCE_RMS))
+        return null;
+    return 20 * Math.log10(rms);
+}
+/**
+ * One step of the gated loud-level estimate. `loud` null means "no estimate
+ * yet" — the first real reading seeds it. A null/junk `level` (silence) leaves
+ * the estimate exactly where it was.
+ */
+export function gateLoud(loud, level) {
+    if (!finite(level))
+        return finite(loud) ? loud : null;
+    if (!finite(loud))
+        return level;
+    if (level > loud - GATE_DB) {
+        return loud + (level - loud) * (level > loud ? LOUD_RISE : LOUD_FORGET);
+    }
+    return loud;
+}
+/** Clamp a target to the declared range; junk falls back to the default. */
+export function clampTarget(target) {
+    if (!finite(target))
+        return AUDIO_TARGET_DEFAULT;
+    return Math.min(AUDIO_TARGET_MAX, Math.max(AUDIO_TARGET_MIN, target));
+}
+/**
+ * The gain that would put the measured loud level at `target`, clamped to
+ * [GAIN_MIN, GAIN_MAX]. No estimate yet ⇒ 1 (neutral): we never guess.
+ */
+export function wantGain(loud, target) {
+    if (!finite(loud))
+        return 1;
+    const want = Math.pow(10, (clampTarget(target) - loud) / 20);
+    return Math.min(GAIN_MAX, Math.max(GAIN_MIN, want));
+}
+/** One asymmetric step of the ride toward `want`. Junk in ⇒ neutral 1. */
+export function rideStep(ride, want) {
+    const r = finite(ride) ? ride : 1;
+    if (!finite(want))
+        return r;
+    return r + (want - r) * (want < r ? RIDE_DOWN : RIDE_UP);
+}
+/** A ride as dB — for readouts. 1 ⇒ 0 dB; junk ⇒ 0. */
+export function gainDb(ride) {
+    return finite(ride) && ride > 0 ? 20 * Math.log10(ride) : 0;
+}
+/**
+ * DynamicsCompressorNode's automatic makeup gain, dB, for knee 0 — the Web
+ * Audio spec's "makeup gain" step (as Chromium/WebKit/Gecko implement it):
+ * fullRangeGain = the curve's output for a 0 dBFS input, makeup =
+ * (1 / fullRangeGain) ^ 0.6. For knee 0 the curve at 0 dBFS is
+ * threshold + (0 − threshold) / ratio, so the makeup is
+ * 0.6 × (−threshold) × (1 − 1/ratio): +1.71 dB at −3 dBFS / 20:1, 0 at a
+ * 0 dBFS threshold. Junk ⇒ 0.
+ */
+export function compressorMakeupDb(threshold, ratio) {
+    if (!finite(threshold) || !finite(ratio) || ratio < 1 || threshold >= 0)
+        return 0;
+    return 0.6 * -threshold * (1 - 1 / ratio);
+}
+/** The trim gain (linear) that cancels a limiter's makeup at this threshold. */
+export function limiterTrim(threshold) {
+    return Math.pow(10, -compressorMakeupDb(threshold, LIMITER.ratio) / 20);
+}
+/**
+ * Can this element's audio be routed through WebAudio without going SILENT?
+ *
+ * A media response that isn't CORS-clean makes a MediaElementAudioSourceNode
+ * output zeros — and routing is a one-way door, so that is silence with no
+ * way back. A same-origin URL is NOT enough: it may 302 to a signed storage
+ * URL on another origin (MardukOS file routes do exactly that), and without
+ * `crossorigin` the redirected response is opaque. So:
+ *
+ * · 'ok'   — blob:/data: (never leave the page's origin), or the element asked
+ *            for a CORS load (`crossorigin` set — the load is then CORS-clean
+ *            or it fails outright, never silently).
+ * · 'wait' — no source yet; nothing to decide.
+ * · 'cors' — anything else: refuse, play unprocessed.
+ */
+export function routeSafety(mediaUrl, crossorigin) {
+    if (typeof mediaUrl !== 'string' || mediaUrl === '')
+        return 'wait';
+    if (crossorigin === 'anonymous' || crossorigin === 'use-credentials' || crossorigin === '') {
+        return 'ok';
+    }
+    return /^(blob|data):/i.test(mediaUrl.trim()) ? 'ok' : 'cors';
+}

package/dist/video/audio.d.ts

@@ -1,29 +1,40 @@
 /**
- * Audio module — CONTRACT ONLY (mos-5lzns.28). Implemented by mos-5lzns.31
- * ("audio graph — loudness matching, quiet listening, limiter").
+ * Audio module (mos-5lzns.31) — loudness matching, quiet listening, limiter.
+ * Ported from extension-library FEATURES.md §Loudness matching, §Quiet
+ * listening (library.js audioEnsure / audioTick / applyAudioSettings).
  *
- * What lands here (extension-library FEATURES.md §Loudness matching,
- * §Quiet listening), as ADVISORS + an audio graph builder:
+ * Layout:
  *
- * · loudness matching — a gated RMS meter drives a slow gain rider toward a
- *   target (~−20 dB). The gate forgets slowly so a new video doesn't reset
- *   the meter mid-lesson; the correction is measured, not a strength slider.
- * · quiet listening — loudness-compensated tone (two shelves + presence
- *   peak + gentle compressor), amount rising as volume drops, a floor after
- *   dark. Amount 0 rebuilds nothing: splicing a live graph mid-playback
- *   clicks — a constant few ms of silence is the trade.
- * · limiter — threshold −3 dBFS, catching what the slow rider cannot.
+ * · audio/rider.ts — pure, node-testable: short-term RMS in dBFS, the gated
+ *   loud-level estimate (12 dB relative gate, rise 0.08 / forget 0.01), the
+ *   clamped want-gain (0.3–1.35), the asymmetric ride (down 0.15 / up 0.02),
+ *   the limiter constants + `compressorMakeupDb`/`limiterTrim` (the
+ *   compressor's automatic makeup gain, cancelled by a trim node), and
+ *   `routeSafety` (only blob:/data: or a `crossorigin` load may be routed).
+ * · audio/graph.ts — `createAudioSession`, the graph builder + its state
+ *   machine: source → gain → quiet chain (advisors/quiet-listening) →
+ *   limiter → trim → destination, analyser tapping the source. Context
+ *   first, route last: the element is taken only once a feature is on, the
+ *   source is route-safe AND the context is `running`; gestures retry. After
+ *   routing, an unsafe src or bit-exact silence is reported `broken`. A
+ *   construction failure is a permanent `broken` that still plays plain
+ *   audio. Disabled = no trace on the param timeline.
  *
  * Module rules (README): no <video> access, no settings reads, no DOM. The
- * graph builder is the one exception that may touch AudioContext — it takes
- * a MediaElementAudioSourceNode the component creates, never the element.
- * Disabled ⇒ the graph is bypassed entirely: no residual filter, no half
- * ramp, no stale param (cancelScheduledValues before restoring). Off must be
- * indistinguishable from never having run.
+ * graph is the one exception that touches AudioContext — and even it never
+ * sees the element: the component passes a `context()` factory and a
+ * `route(ctx)` closure that calls createMediaElementSource.
+ *
+ * ⚠ CORS: WebAudio outputs SILENCE for a source that isn't CORS-clean — and
+ * a same-origin URL may redirect to one. The host must serve the media with
+ * Access-Control-Allow-Origin and pass `crossorigin="anonymous"` (or use a
+ * blob:/data: src); otherwise the player refuses to route (status 'cors')
+ * and plays the audio unprocessed.
  */
 /**
  * Neutral advisor product — the multiplicative identity every composer and
- * caller must get when audio correction is off or unmeasured. Exported so
- * .31's rate-relevant advisors (if any) share the exact collapse value.
+ * caller must get when audio correction is off or unmeasured.
  */
 export declare const AUDIO_NEUTRAL = 1;
+export * from './audio/rider';
+export * from './audio/graph';

package/dist/video/audio.js

@@ -1,29 +1,40 @@
 /**
- * Audio module — CONTRACT ONLY (mos-5lzns.28). Implemented by mos-5lzns.31
- * ("audio graph — loudness matching, quiet listening, limiter").
+ * Audio module (mos-5lzns.31) — loudness matching, quiet listening, limiter.
+ * Ported from extension-library FEATURES.md §Loudness matching, §Quiet
+ * listening (library.js audioEnsure / audioTick / applyAudioSettings).
  *
- * What lands here (extension-library FEATURES.md §Loudness matching,
- * §Quiet listening), as ADVISORS + an audio graph builder:
+ * Layout:
  *
- * · loudness matching — a gated RMS meter drives a slow gain rider toward a
- *   target (~−20 dB). The gate forgets slowly so a new video doesn't reset
- *   the meter mid-lesson; the correction is measured, not a strength slider.
- * · quiet listening — loudness-compensated tone (two shelves + presence
- *   peak + gentle compressor), amount rising as volume drops, a floor after
- *   dark. Amount 0 rebuilds nothing: splicing a live graph mid-playback
- *   clicks — a constant few ms of silence is the trade.
- * · limiter — threshold −3 dBFS, catching what the slow rider cannot.
+ * · audio/rider.ts — pure, node-testable: short-term RMS in dBFS, the gated
+ *   loud-level estimate (12 dB relative gate, rise 0.08 / forget 0.01), the
+ *   clamped want-gain (0.3–1.35), the asymmetric ride (down 0.15 / up 0.02),
+ *   the limiter constants + `compressorMakeupDb`/`limiterTrim` (the
+ *   compressor's automatic makeup gain, cancelled by a trim node), and
+ *   `routeSafety` (only blob:/data: or a `crossorigin` load may be routed).
+ * · audio/graph.ts — `createAudioSession`, the graph builder + its state
+ *   machine: source → gain → quiet chain (advisors/quiet-listening) →
+ *   limiter → trim → destination, analyser tapping the source. Context
+ *   first, route last: the element is taken only once a feature is on, the
+ *   source is route-safe AND the context is `running`; gestures retry. After
+ *   routing, an unsafe src or bit-exact silence is reported `broken`. A
+ *   construction failure is a permanent `broken` that still plays plain
+ *   audio. Disabled = no trace on the param timeline.
  *
  * Module rules (README): no <video> access, no settings reads, no DOM. The
- * graph builder is the one exception that may touch AudioContext — it takes
- * a MediaElementAudioSourceNode the component creates, never the element.
- * Disabled ⇒ the graph is bypassed entirely: no residual filter, no half
- * ramp, no stale param (cancelScheduledValues before restoring). Off must be
- * indistinguishable from never having run.
+ * graph is the one exception that touches AudioContext — and even it never
+ * sees the element: the component passes a `context()` factory and a
+ * `route(ctx)` closure that calls createMediaElementSource.
+ *
+ * ⚠ CORS: WebAudio outputs SILENCE for a source that isn't CORS-clean — and
+ * a same-origin URL may redirect to one. The host must serve the media with
+ * Access-Control-Allow-Origin and pass `crossorigin="anonymous"` (or use a
+ * blob:/data: src); otherwise the player refuses to route (status 'cors')
+ * and plays the audio unprocessed.
  */
 /**
  * Neutral advisor product — the multiplicative identity every composer and
- * caller must get when audio correction is off or unmeasured. Exported so
- * .31's rate-relevant advisors (if any) share the exact collapse value.
+ * caller must get when audio correction is off or unmeasured.
  */
 export const AUDIO_NEUTRAL = 1;
+export * from './audio/rider';
+export * from './audio/graph';

package/dist/video/settings.js

@@ -32,7 +32,14 @@
 export const VIDEO_SETTINGS = [
     // Read by VideoPlayer's `oneAxis` prop → video/band/axis.ts resolveAxis().
     { id: 'player.oneAxis', type: 'bool', default: true, owner: 'mos-5lzns.30', wired: true },
-    // { id: 'audio.level', type: 'bool', default: true, owner: 'mos-5lzns.31' },
+    // Read by VideoPlayer's `loudness` / `loudnessTarget` / `quietListening` /
+    // `limiter` props → video/audio/* (graph.createAudioSession, rider.*). As with
+    // night, the DEFAULT is the host's opt-in: an absent prop means nothing is
+    // ever routed through WebAudio on that player.
+    { id: 'audio.level', type: 'bool', default: true, owner: 'mos-5lzns.31', wired: true },
+    { id: 'audio.target', type: 'range', default: -20, min: -30, max: -12, step: 2, owner: 'mos-5lzns.31', wired: true },
+    { id: 'audio.quiet', type: 'bool', default: true, owner: 'mos-5lzns.31', wired: true },
+    { id: 'audio.limiter', type: 'bool', default: true, owner: 'mos-5lzns.31', wired: true },
     // { id: 'player.speakerRate', type: 'bool', default: false, owner: 'mos-5lzns.32' },
     // Read by VideoPlayer's `night` / `nightDepth` / `biasLight` / `predictive` /
     // `strobeGuard` props → video/night/* (clock.nightArmed, levels.nightLevels,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",