@joewinke/jatui 0.46.0 → 0.48.0

package/dist/ambience/scapes/nature.js

@@ -0,0 +1,325 @@
+/** How far ahead of `now` tick-driven events are scheduled (s). */
+const LEAD_S = 0.75;
+/** Seconds of white noise per channel — long enough to loop invisibly. */
+const NOISE_SECONDS = 2;
+const noiseCache = new WeakMap();
+/** White noise, generated once per AudioContext, shared by bed and droplets. */
+function noiseBuffer(audio) {
+    const cached = noiseCache.get(audio);
+    if (cached)
+        return cached;
+    const len = Math.max(1, Math.floor(audio.sampleRate * NOISE_SECONDS));
+    const buf = audio.createBuffer(2, len, audio.sampleRate);
+    for (let ch = 0; ch < 2; ch++) {
+        const data = buf.getChannelData(ch);
+        for (let i = 0; i < len; i++)
+            data[i] = Math.random() * 2 - 1;
+    }
+    noiseCache.set(audio, buf);
+    return buf;
+}
+/** Random loop/slice offset — Math.random, not ctx.rand: variety across
+ *  plays matters here, determinism does not (the engine's rand is seeded by
+ *  scape id, so it would replay the same offsets every session). */
+function randomOffset(audio) {
+    const buf = noiseBuffer(audio);
+    return Math.random() * (buf.length / buf.sampleRate);
+}
+/** Rain: mean seconds between droplets at density 0 → 1. */
+const RAIN_DENSITY = Object.freeze({
+    MIN_INTERVAL: 2.4,
+    MAX_INTERVAL: 0.12,
+    DEFAULT: 0.4
+});
+/** Max droplets scheduled in ONE tick — a background tab's throttled interval
+ *  must never come back as a burst of missed droplets fired into the past. */
+const DROPS_PER_TICK_CAP = 32;
+export const rain = {
+    id: 'rain',
+    label: 'Rain',
+    group: 'nature',
+    description: 'Steady rain on leaves — a soft noise bed with sparse droplet patter.',
+    build(ctx) {
+        const { audio, input, rand } = ctx;
+        let density = RAIN_DENSITY.DEFAULT;
+        const out = audio.createGain();
+        out.gain.value = 1;
+        // Bed: looped stereo noise → highpass (rumble out) → lowpass (hiss out)
+        // → bed level → out. The master lowpass (1100 Hz) sits downstream.
+        const bed = audio.createBufferSource();
+        bed.buffer = noiseBuffer(audio);
+        bed.loop = true;
+        const bedHP = audio.createBiquadFilter();
+        bedHP.type = 'highpass';
+        bedHP.frequency.value = 220;
+        const bedLP = audio.createBiquadFilter();
+        bedLP.type = 'lowpass';
+        bedLP.frequency.value = 1000;
+        const bedGain = audio.createGain();
+        bedGain.gain.value = 0.13;
+        bed.connect(bedHP);
+        bedHP.connect(bedLP);
+        bedLP.connect(bedGain);
+        bedGain.connect(out);
+        out.connect(input);
+        const droplets = [];
+        const allSrcs = [bed];
+        let nextAt = 0;
+        let stopping = false;
+        let teardownTimer = null;
+        let unsub = null;
+        function meanInterval() {
+            return RAIN_DENSITY.MAX_INTERVAL + (RAIN_DENSITY.MIN_INTERVAL - RAIN_DENSITY.MAX_INTERVAL) * (1 - density);
+        }
+        /** One droplet: a short slice of the noise buffer through a randomized
+         *  bandpass (pitch), a pluck envelope (level), and a pan (when the
+         *  context has a StereoPanner — the node-side test fake may not). */
+        function scheduleDroplet(t) {
+            const buf = noiseBuffer(audio);
+            const src = audio.createBufferSource();
+            src.buffer = buf;
+            const bp = audio.createBiquadFilter();
+            bp.type = 'bandpass';
+            bp.frequency.value = 320 + rand() * 680; // 320–1000 Hz (master lowpass above)
+            bp.Q.value = 4 + rand() * 8;
+            const g = audio.createGain();
+            const peak = 0.06 + rand() * 0.24;
+            const tau = 0.05 + rand() * 0.08;
+            g.gain.setValueAtTime(0, t);
+            g.gain.linearRampToValueAtTime(peak, t + 0.004);
+            g.gain.setTargetAtTime(0, t + 0.004, tau);
+            let tail = g;
+            let panner = null;
+            if (typeof audio.createStereoPanner === 'function') {
+                panner = audio.createStereoPanner();
+                panner.pan.setValueAtTime(rand() * 1.6 - 0.8, t);
+                g.connect(panner);
+                tail = panner;
+            }
+            src.connect(bp);
+            bp.connect(g);
+            tail.connect(out);
+            const dur = 0.2 + tau * 3;
+            src.start(t, randomOffset(audio) % Math.max(buf.length / buf.sampleRate - dur, 0.01), dur);
+            allSrcs.push(src);
+            const nodes = panner ? [src, bp, g, panner] : [src, bp, g];
+            droplets.push({ until: t + dur + tau * 2, src, nodes });
+        }
+        function teardown() {
+            if (teardownTimer) {
+                clearTimeout(teardownTimer);
+                teardownTimer = null;
+            }
+            unsub?.();
+            unsub = null;
+            for (const n of [out, bed, bedHP, bedLP, bedGain]) {
+                try {
+                    n.disconnect();
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+            for (const d of droplets) {
+                for (const n of d.nodes) {
+                    try {
+                        n.disconnect();
+                    }
+                    catch {
+                        /* already gone */
+                    }
+                }
+            }
+            droplets.length = 0;
+        }
+        const tick = (now) => {
+            if (stopping)
+                return; // after stop: no scheduling, no teardown here
+            // Prune droplets whose burst has fully decayed.
+            for (let i = droplets.length - 1; i >= 0; i--) {
+                if (droplets[i].until <= now - 0.05) {
+                    for (const n of droplets[i].nodes) {
+                        try {
+                            n.disconnect();
+                        }
+                        catch {
+                            /* already gone */
+                        }
+                    }
+                    droplets.splice(i, 1);
+                }
+            }
+            // Catch-up resync: browsers throttle setInterval in a background tab
+            // (down to ~1/min) while the audio clock keeps running — without this,
+            // the first tick after returning would fire every missed droplet at
+            // once (a loud crackle burst). Skip the gap, don't play it.
+            if (nextAt < now)
+                nextAt = now + meanInterval() * rand();
+            let budget = DROPS_PER_TICK_CAP;
+            while (nextAt < now + LEAD_S && budget-- > 0) {
+                scheduleDroplet(nextAt);
+                nextAt += meanInterval() * (0.4 + 1.2 * rand());
+            }
+        };
+        return {
+            start(at) {
+                bed.start(at, randomOffset(audio));
+                nextAt = at + meanInterval() * (0.4 + 1.2 * rand());
+                unsub = ctx.lookahead(tick);
+            },
+            stop(at, fade) {
+                stopping = true;
+                const g = out.gain;
+                g.cancelScheduledValues(at);
+                g.setValueAtTime(g.value, at);
+                g.linearRampToValueAtTime(0, at + Math.max(fade, 0.001));
+                for (const s of allSrcs) {
+                    try {
+                        s.stop(at + fade); // audio clock — the fade is audible
+                    }
+                    catch {
+                        /* already stopped */
+                    }
+                }
+                if (fade <= 0) {
+                    teardown(); // kill(): immediate
+                }
+                else {
+                    // Disconnect on the WALL clock: the engine retires our lookahead
+                    // cbs at fade*1000 + 250 ms, so a tick-based teardown would race
+                    // it and can be dropped. 50 ms after the fade is safely ahead.
+                    teardownTimer = setTimeout(teardown, fade * 1000 + 50);
+                }
+            },
+            setParam(key, value) {
+                if (key === 'density')
+                    density = Math.min(1, Math.max(0, value));
+            }
+        };
+    }
+};
+/* ----------------------------------------------------------------- waves */
+/** Waves: swell period range (s) and level shaping. */
+const WAVES_SWELL = Object.freeze({
+    MIN_PERIOD: 8,
+    MAX_PERIOD: 12,
+    BASE: 0.05,
+    PEAK: 0.3
+});
+/** Max swells scheduled in ONE tick — same background-tab catch-up guard as
+ *  rain: never stack missed swells into the past. */
+const SWELLS_PER_TICK_CAP = 2;
+export const waves = {
+    id: 'waves',
+    label: 'Ocean waves',
+    group: 'nature',
+    description: 'Slow ocean swells — noise breathing through a band filter, soft wash tail.',
+    build(ctx) {
+        const { audio, input, rand } = ctx;
+        let intensity = 1;
+        const out = audio.createGain();
+        out.gain.value = 1;
+        // Looping stereo noise → bandpass (the "swelling band") → swell level
+        // → out. Both the band center and the level are driven by the lookahead
+        // scheduler (a scheduled LFO — randomized period, no oscillator nodes).
+        const src = audio.createBufferSource();
+        src.buffer = noiseBuffer(audio);
+        src.loop = true;
+        const bp = audio.createBiquadFilter();
+        bp.type = 'bandpass';
+        bp.frequency.value = 420;
+        bp.Q.value = 0.7;
+        const swell = audio.createGain();
+        swell.gain.value = WAVES_SWELL.BASE;
+        src.connect(bp);
+        bp.connect(swell);
+        swell.connect(out);
+        out.connect(input);
+        let nextSwellAt = 0;
+        let stopping = false;
+        let teardownTimer = null;
+        let unsub = null;
+        /** Schedule one swell starting at t0; returns its period so the next
+         *  swell lands a fresh randomized 8–12 s later. */
+        function scheduleSwell(t0) {
+            const period = WAVES_SWELL.MIN_PERIOD + rand() * (WAVES_SWELL.MAX_PERIOD - WAVES_SWELL.MIN_PERIOD);
+            const rise = period * 0.45;
+            const base = WAVES_SWELL.BASE * intensity;
+            const peak = WAVES_SWELL.PEAK * (0.55 + rand() * 0.45) * intensity;
+            const tau = 2.2 + rand() * 1.3; // wash tail: 2.2–3.5 s decay constant
+            const fBase = 380 + rand() * 120;
+            const fPeak = fBase + 260 + rand() * 180;
+            const g = swell.gain;
+            g.cancelScheduledValues(t0);
+            g.linearRampToValueAtTime(base, t0); // glide from the previous tail into base
+            g.linearRampToValueAtTime(peak, t0 + rise);
+            g.setTargetAtTime(base, t0 + rise, tau);
+            const f = bp.frequency;
+            f.cancelScheduledValues(t0);
+            f.linearRampToValueAtTime(fBase, t0);
+            f.linearRampToValueAtTime(fPeak, t0 + rise);
+            f.setTargetAtTime(fBase, t0 + rise, tau + 0.8); // the band "breathes" with the swell
+            return period;
+        }
+        function teardown() {
+            if (teardownTimer) {
+                clearTimeout(teardownTimer);
+                teardownTimer = null;
+            }
+            unsub?.();
+            unsub = null;
+            for (const n of [out, src, bp, swell]) {
+                try {
+                    n.disconnect();
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+        }
+        const tick = (now) => {
+            if (stopping)
+                return; // after stop: no scheduling, no teardown here
+            // Swells are long, absolute-time events — keep ~2 s ahead.
+            // Catch-up resync (see rain): after a throttled-tab gap, swells restart
+            // from now instead of stacking every missed swell into the past.
+            if (nextSwellAt < now)
+                nextSwellAt = now;
+            let budget = SWELLS_PER_TICK_CAP;
+            while (nextSwellAt < now + 2 && budget-- > 0) {
+                nextSwellAt += scheduleSwell(nextSwellAt);
+            }
+        };
+        return {
+            start(at) {
+                src.start(at, randomOffset(audio));
+                nextSwellAt = at;
+                unsub = ctx.lookahead(tick);
+            },
+            stop(at, fade) {
+                stopping = true;
+                const g = out.gain;
+                g.cancelScheduledValues(at);
+                g.setValueAtTime(g.value, at);
+                g.linearRampToValueAtTime(0, at + Math.max(fade, 0.001));
+                try {
+                    src.stop(at + fade); // audio clock — the fade is audible
+                }
+                catch {
+                    /* already stopped */
+                }
+                if (fade <= 0) {
+                    teardown(); // kill(): immediate
+                }
+                else {
+                    // Wall-clock disconnect — see the rain note; never a lookahead cb.
+                    teardownTimer = setTimeout(teardown, fade * 1000 + 50);
+                }
+            },
+            setParam(key, value) {
+                if (key === 'intensity')
+                    intensity = Math.min(2, Math.max(0, value));
+            }
+        };
+    }
+};

package/dist/ambience/scapes/noise.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Ambience scapes — noise generators: brown, pink, white (jatui-uglol).
+ *
+ * Three scapes, one file. Each is built the same way, differing only in the
+ * noise colour, its loudness trim and its copy:
+ *
+ *   buffer source (one looped 10 s mono buffer, generated ONCE per build)
+ *     ─► lowshelf ─► highshelf   (the `tone` tilt: darker ⇄ lighter)
+ *     ─► level gain              (base = loudness trim; drift LFOs wobble it)
+ *     ─► ctx.input               (the shared master chain — never destination)
+ *
+ * CPU: no per-sample JS at runtime and no lookahead ticks at all. The buffer
+ * is generated once in build() and looped; tone and drift are native nodes
+ * (two biquads, two slow sines into a gain param). Nothing to schedule.
+ *
+ * Loop seam: raw noise has a step where the buffer wraps, and on brown (big
+ * low-frequency wander) that step is an audible thump every cycle. So the
+ * generator produces BUFFER_SECONDS + one crossfade, and the last crossfade
+ * of the buffer blends into the audio that follows the wrap — the seam
+ * disappears for all three colours.
+ *
+ * Never audibly repeats: the loop start offset is drawn from ctx.rand() each
+ * build, so a given play begins somewhere else in the buffer. The buffer is
+ * long enough (10 s) that the cycle itself is below perception for noise.
+ *
+ * Loudness matching: all three buffers are normalized to the same RMS, then
+ * each colour gets a fixed perceptual trim (NOISE.TRIMS). The trims equalize
+ * the A-weighted loudness of what survives the master chain's 1100 Hz
+ * lowpass (white keeps only ~5% of its power in band, pink ~79%, brown
+ * ~99% — but brown sits where hearing is least sensitive), referenced to
+ * pink. They are documented approximations, ±2 dB, and the tone control is
+ * there for the rest.
+ *
+ * The scape contract lives in ../types.ts (jatui-km0qy); this file imports
+ * only those types. Registration is the integration task's job (jatui-poq30)
+ * — nothing is registered, mutated or played at import time.
+ */
+import type { Scape } from '../types';
+/** Tuning constants — exported for tests and for the integration docs. */
+export declare const NOISE: Readonly<{
+    /** Loop length of the generated buffer (s). */
+    BUFFER_SECONDS: 10;
+    /** Crossfade that hides the loop seam (s). */
+    LOOP_CROSSFADE_SECONDS: 0.1;
+    /** RMS every buffer is normalized to (before the per-colour trim). Sized
+     *  so even brown's worst crest (~6x) stays under the peak ceiling. */
+    TARGET_RMS: 0.15;
+    /** Hard ceiling on |sample| after normalization (headroom for the master limiter). */
+    PEAK_CEILING: 0.97;
+    /** Tilt filter corners (Hz) — inside the master chain's 1100 Hz band. */
+    TILT_LOW_HZ: 240;
+    TILT_HIGH_HZ: 900;
+    /** Total tilt range across the tone param, in dB — ±4 dB per shelf. */
+    TILT_RANGE_DB: 8;
+    /** Smoothing time constant for live tone changes (s) — no zipper, no click. */
+    TILT_TC: 0.12;
+    /** Level drift: two slow sines at irrational-ratio periods summed into the
+     *  level gain, so the wobble itself never repeats. Depths are fractions of
+     *  the trim (worst case ≈ ±0.8 dB — felt, not heard). */
+    DRIFT: Readonly<{
+        PERIOD_A_S: 41;
+        PERIOD_B_S: 67;
+        DEPTH_A: 0.06;
+        DEPTH_B: 0.045;
+    }>;
+    /** Perceptual loudness trims on top of equal-RMS buffers (see header). */
+    TRIMS: Record<NoiseKind, number>;
+}>;
+export type NoiseKind = 'brown' | 'pink' | 'white';
+/** Deep low-end rumble — integrated white noise, the darkest of the three. */
+export declare const brownNoiseScape: Scape;
+/** Flat power per octave — the natural, balanced middle of the three. */
+export declare const pinkNoiseScape: Scape;
+/** Full-spectrum hiss — the brightest of the three, best at masking speech. */
+export declare const whiteNoiseScape: Scape;
+/** For the integration task's default registry — nothing here registers itself. */
+export declare const noiseScapes: Scape[];

package/dist/ambience/scapes/noise.js

@@ -0,0 +1,226 @@
+/** Tuning constants — exported for tests and for the integration docs. */
+export const NOISE = Object.freeze({
+    /** Loop length of the generated buffer (s). */
+    BUFFER_SECONDS: 10,
+    /** Crossfade that hides the loop seam (s). */
+    LOOP_CROSSFADE_SECONDS: 0.1,
+    /** RMS every buffer is normalized to (before the per-colour trim). Sized
+     *  so even brown's worst crest (~6x) stays under the peak ceiling. */
+    TARGET_RMS: 0.15,
+    /** Hard ceiling on |sample| after normalization (headroom for the master limiter). */
+    PEAK_CEILING: 0.97,
+    /** Tilt filter corners (Hz) — inside the master chain's 1100 Hz band. */
+    TILT_LOW_HZ: 240,
+    TILT_HIGH_HZ: 900,
+    /** Total tilt range across the tone param, in dB — ±4 dB per shelf. */
+    TILT_RANGE_DB: 8,
+    /** Smoothing time constant for live tone changes (s) — no zipper, no click. */
+    TILT_TC: 0.12,
+    /** Level drift: two slow sines at irrational-ratio periods summed into the
+     *  level gain, so the wobble itself never repeats. Depths are fractions of
+     *  the trim (worst case ≈ ±0.8 dB — felt, not heard). */
+    DRIFT: Object.freeze({ PERIOD_A_S: 41, PERIOD_B_S: 67, DEPTH_A: 0.06, DEPTH_B: 0.045 }),
+    /** Perceptual loudness trims on top of equal-RMS buffers (see header). */
+    TRIMS: Object.freeze({ brown: 1.8, pink: 1.0, white: 4.7 })
+});
+/** Brown noise: leaky integrator over white — a −6 dB/oct drift bounded by a
+ *  ~15 Hz leak, so it can wander but never run away. */
+const BROWN_LEAK = 0.998;
+const BROWN_DRIVE = 0.02;
+/**
+ * Paul Kellet's precision pink filter (three-ish poles + correction): flat
+ * power per octave, the spectral shape of steady rain and wind.
+ */
+function generateSource(kind, count, rand) {
+    // Generate past both ends: a warm-up tail the filters settle in (and the
+    // integrator forgets its zero start), discarded before normalization.
+    const warm = Math.floor(count * 0.08);
+    const total = warm + count;
+    const raw = new Float32Array(total);
+    let brown = 0;
+    let b0 = 0, b1 = 0, b2 = 0, b3 = 0, b4 = 0, b5 = 0, b6 = 0;
+    for (let i = 0; i < total; i++) {
+        const w = rand() * 2 - 1;
+        if (kind === 'white') {
+            raw[i] = w;
+        }
+        else if (kind === 'brown') {
+            brown += w * BROWN_DRIVE;
+            brown *= BROWN_LEAK;
+            raw[i] = brown;
+        }
+        else {
+            b0 = 0.99886 * b0 + w * 0.0555179;
+            b1 = 0.99332 * b1 + w * 0.0750759;
+            b2 = 0.969 * b2 + w * 0.153852;
+            b3 = 0.8665 * b3 + w * 0.3104856;
+            b4 = 0.55 * b4 + w * 0.5329522;
+            b5 = -0.7616 * b5 - w * 0.016898;
+            raw[i] = b0 + b1 + b2 + b3 + b4 + b5 + b6 + w * 0.5362;
+            b6 = w * 0.115926;
+        }
+    }
+    return raw.subarray(warm);
+}
+/** Scale in place to a target RMS — the loudness-match foundation. */
+function normalizeToRms(data, target) {
+    let sum = 0;
+    for (let i = 0; i < data.length; i++)
+        sum += data[i] * data[i];
+    const rms = Math.sqrt(sum / data.length);
+    const k = rms > 0 ? target / rms : 1;
+    for (let i = 0; i < data.length; i++)
+        data[i] *= k;
+}
+/**
+ * Assemble the looped buffer: body = source[data offset .. ], with the final
+ * crossfade blending the natural continuation into the audio that follows
+ * the wrap (see header). Applies the peak ceiling last.
+ */
+function makeLoopBuffer(ctx, data, fadeSamples, sampleRate) {
+    const count = data.length - fadeSamples;
+    const buf = ctx.createBuffer(1, count, sampleRate);
+    const out = buf.getChannelData(0);
+    for (let i = 0; i < count - fadeSamples; i++)
+        out[i] = data[fadeSamples + i];
+    for (let k = 0; k < fadeSamples; k++) {
+        const w = k / fadeSamples;
+        out[count - fadeSamples + k] = data[count + k] * (1 - w) + data[k] * w;
+    }
+    let peak = 0;
+    for (let i = 0; i < count; i++)
+        peak = Math.max(peak, Math.abs(out[i]));
+    if (peak > NOISE.PEAK_CEILING) {
+        const k = NOISE.PEAK_CEILING / peak;
+        for (let i = 0; i < count; i++)
+            out[i] *= k;
+    }
+    return buf;
+}
+/** The one factory all three colours go through — differences are data, not code. */
+function createNoiseScape(kind, id, label, description) {
+    return {
+        id,
+        label,
+        group: 'noise',
+        description,
+        build(ctx) {
+            const audio = ctx.audio;
+            const rate = audio.sampleRate;
+            const fadeSamples = Math.max(1, Math.round(NOISE.LOOP_CROSSFADE_SECONDS * rate));
+            const count = Math.round(NOISE.BUFFER_SECONDS * rate);
+            const trim = NOISE.TRIMS[kind];
+            const source = generateSource(kind, count + fadeSamples, ctx.rand);
+            normalizeToRms(source, NOISE.TARGET_RMS);
+            const buf = makeLoopBuffer(audio, source, fadeSamples, rate);
+            const src = audio.createBufferSource();
+            src.buffer = buf;
+            src.loop = true;
+            // Tone tilt: two shelves around the band the master chain leaves
+            // audible. tone 0.5 = neutral (both 0 dB); 0 = darker, 1 = lighter.
+            const shelfLow = audio.createBiquadFilter();
+            shelfLow.type = 'lowshelf';
+            shelfLow.frequency.value = NOISE.TILT_LOW_HZ;
+            shelfLow.gain.value = 0;
+            const shelfHigh = audio.createBiquadFilter();
+            shelfHigh.type = 'highshelf';
+            shelfHigh.frequency.value = NOISE.TILT_HIGH_HZ;
+            shelfHigh.gain.value = 0;
+            // Level: base = loudness trim, wobbled by two slow drift LFOs.
+            const level = audio.createGain();
+            level.gain.value = trim;
+            const driftA = audio.createGain();
+            driftA.gain.value = trim * NOISE.DRIFT.DEPTH_A;
+            const driftB = audio.createGain();
+            driftB.gain.value = trim * NOISE.DRIFT.DEPTH_B;
+            const oscA = audio.createOscillator();
+            oscA.type = 'sine';
+            oscA.frequency.value = 1 / NOISE.DRIFT.PERIOD_A_S;
+            const oscB = audio.createOscillator();
+            oscB.type = 'sine';
+            oscB.frequency.value = 1 / NOISE.DRIFT.PERIOD_B_S;
+            src.connect(shelfLow);
+            shelfLow.connect(shelfHigh);
+            shelfHigh.connect(level);
+            level.connect(ctx.input);
+            oscA.connect(driftA);
+            driftA.connect(level.gain);
+            oscB.connect(driftB);
+            driftB.connect(level.gain);
+            // Everything this build created — disconnected once the fade lands,
+            // so a stopped scape leaves no nodes hanging off the master bus.
+            const all = [src, shelfLow, shelfHigh, level, driftA, driftB, oscA, oscB];
+            let tornDown = false;
+            const teardown = () => {
+                if (tornDown)
+                    return;
+                tornDown = true;
+                for (const n of all) {
+                    try {
+                        n.disconnect();
+                    }
+                    catch {
+                        /* context already closed */
+                    }
+                }
+            };
+            return {
+                start(at) {
+                    // Random offset: each play begins somewhere else in the loop.
+                    const offset = ctx.rand() * (buf.length / rate);
+                    src.start(at, offset);
+                    oscA.start(at);
+                    oscB.start(at);
+                    // Fires exactly at the stop time on a real context; the fake
+                    // ignores it and the wall-clock fallback in stop() covers tests.
+                    src.onended = teardown;
+                },
+                stop(at, fade) {
+                    const g = level.gain;
+                    try {
+                        g.cancelScheduledValues(at);
+                        g.setValueAtTime(g.value, at);
+                        g.linearRampToValueAtTime(0, at + fade);
+                    }
+                    catch {
+                        /* context already closed */
+                    }
+                    const end = at + fade;
+                    try {
+                        src.stop(end);
+                        oscA.stop(end);
+                        oscB.stop(end);
+                    }
+                    catch {
+                        /* never started */
+                    }
+                    // Disconnect only after the fade — a wall-clock fallback for
+                    // environments where onended never fires (and for the fake).
+                    const ms = Math.max(0, (end - audio.currentTime) * 1000) + 50;
+                    setTimeout(teardown, ms);
+                },
+                setParam(key, value) {
+                    if (key !== 'tone')
+                        return; // the only live control a noise scape has
+                    const t = Math.min(1, Math.max(0, value));
+                    const db = (0.5 - t) * NOISE.TILT_RANGE_DB;
+                    try {
+                        shelfLow.gain.setTargetAtTime(db, audio.currentTime, NOISE.TILT_TC);
+                        shelfHigh.gain.setTargetAtTime(-db, audio.currentTime, NOISE.TILT_TC);
+                    }
+                    catch {
+                        /* context already closed */
+                    }
+                }
+            };
+        }
+    };
+}
+/** Deep low-end rumble — integrated white noise, the darkest of the three. */
+export const brownNoiseScape = createNoiseScape('brown', 'noise-brown', 'Brown Noise', 'Deep, soft low-end rumble — the darkest and heaviest of the three, good under everything else.');
+/** Flat power per octave — the natural, balanced middle of the three. */
+export const pinkNoiseScape = createNoiseScape('pink', 'noise-pink', 'Pink Noise', 'Even, balanced hiss like steady rain — the natural-sounding middle of the three.');
+/** Full-spectrum hiss — the brightest of the three, best at masking speech. */
+export const whiteNoiseScape = createNoiseScape('white', 'noise-white', 'White Noise', 'Bright, full-spectrum hiss — the most uniform colour, strongest at masking voices.');
+/** For the integration task's default registry — nothing here registers itself. */
+export const noiseScapes = [brownNoiseScape, pinkNoiseScape, whiteNoiseScape];