@joewinke/jatui 0.46.0 → 0.48.0

package/dist/ambience/scapes/hibiscus.js

@@ -0,0 +1,345 @@
+export const HIBISCUS = Object.freeze({
+    /** Drone partials: F2 + fifth (C3), tenth (A3), twelfth (C4). */
+    DRONE_HZ: [87.31, 130.81, 220.0, 261.63],
+    /** Relative level of each drone partial, brightest at the bottom. */
+    DRONE_GAINS: [1, 0.55, 0.32, 0.2],
+    /** Stereo pair detune (± cents) — the "width" of the pad. */
+    DETUNE_CENTS: 7,
+    /** Where the detuned pairs sit in the stereo field. */
+    PAD_PAN: 0.35,
+    /** Soft wave: y = x + SOFT_3RD·x³ + SOFT_5TH·x⁵, normalised — odd
+     *  symmetry, so a sine keeps its fundamental and gains a little 3rd and
+     *  5th harmonic and nothing else. */
+    SOFT_3RD: 0.16,
+    SOFT_5TH: 0.05,
+    /** Pad lowpass: resting frequency and the in-breath lift (+Hz at peak). */
+    PAD_BASE_HZ: 420,
+    PAD_BREATH_HZ: 180,
+    PAD_Q: 0.6,
+    PAD_LEVEL: 0.15,
+    /** How much of each section's level rides the breath (0..1 — the level
+     *  sinks to (1 - depth)·level at the bottom of the exhale). */
+    PAD_BREATH_DEPTH: 0.25,
+    FLOAT_LEVEL: 0.09,
+    FLOAT_BREATH_DEPTH: 0.2,
+    NOISE_LEVEL: 0.01,
+    NOISE_BREATH_DEPTH: 0.25,
+    /** Floating tones: F4 → A4 → C5 → A4 (→ F4 …). */
+    TONES_HZ: [349.23, 440.0, 523.25, 440.0],
+    TONE_HOLD_S: 70,
+    TONE_JITTER_S: 8,
+    TONE_FADE_S: 16,
+    /** Chimes: the current chord an octave up (F5, A5, C6), first 3 partials. */
+    CHIME_HZ: [698.46, 880.0, 1046.5],
+    CHIME_PARTIAL_GAINS: [1, 0.35, 0.18],
+    CHIME_MIN_GAP_S: 35,
+    CHIME_MAX_GAP_S: 65,
+    CHIME_ATTACK_S: 2.5,
+    CHIME_TAU_S: 3.5,
+    /** Oscillators stop after this many decay taus. */
+    CHIME_TAILS: 7,
+    CHIME_LEVEL: 0.05,
+    CHIME_PAN_SPREAD: 0.8,
+    /** Air noise. */
+    AIR_SECONDS: 4,
+    AIR_HP_HZ: 80,
+    AIR_LP_HZ: 420,
+    /** Internal entrance fade — the engine bus fade handles crossfades; this
+     *  just keeps a fresh build from stepping in at full level. */
+    ENTRANCE_S: 6,
+    /** Smoothing tau for the per-tick breath modulation. */
+    MOD_TAU_S: 0.45
+});
+/** A soft wave curve: fundamental plus a little 3rd and 5th, nothing else. */
+export function softWaveCurve(n = 1024) {
+    const { SOFT_3RD: a, SOFT_5TH: b } = HIBISCUS;
+    const curve = new Float32Array(n);
+    let max = 0;
+    for (let i = 0; i < n; i++) {
+        const x = (i / (n - 1)) * 2 - 1;
+        const y = x + a * x ** 3 + b * x ** 5;
+        curve[i] = y;
+        max = Math.max(max, Math.abs(y));
+    }
+    for (let i = 0; i < n; i++)
+        curve[i] /= max;
+    return curve;
+}
+/** Pink noise (Paul Kellet's filter), one channel's worth, in place. */
+function fillPink(data, rand) {
+    let b0 = 0, b1 = 0, b2 = 0, b3 = 0, b4 = 0, b5 = 0, b6 = 0;
+    for (let i = 0; i < data.length; i++) {
+        const w = rand() * 2 - 1;
+        b0 = 0.99886 * b0 + w * 0.0555179;
+        b1 = 0.99332 * b1 + w * 0.0750759;
+        b2 = 0.969 * b2 + w * 0.1538522;
+        b3 = 0.8665 * b3 + w * 0.3104856;
+        b4 = 0.55 * b4 + w * 0.5329522;
+        b5 = -0.7616 * b5 - w * 0.016898;
+        data[i] = (b0 + b1 + b2 + b3 + b4 + b5 + b6 + w * 0.5362) * 0.11;
+        b6 = w * 0.115926;
+    }
+}
+/** A stereo panner when the context has one, a plain gain otherwise (the
+ *  test fake — and any context too old to pan — falls back to mono). */
+function makePan(audio, pan) {
+    if (typeof audio.createStereoPanner === 'function') {
+        const p = audio.createStereoPanner();
+        p.pan.value = pan;
+        return p;
+    }
+    return audio.createGain();
+}
+export const hibiscusScape = {
+    id: 'hibiscus',
+    label: 'Hibiscus',
+    group: 'meditation',
+    description: 'Warm F-major drone, floating tones and soft chimes — six breaths a minute.',
+    build(scapeCtx) {
+        const { audio, rand } = scapeCtx;
+        const H = HIBISCUS;
+        /** Every node this build created — the final disconnect walks it. */
+        const allNodes = [];
+        const keep = (node) => {
+            allNodes.push(node);
+            return node;
+        };
+        function disconnectAll(nodes) {
+            for (const n of nodes) {
+                try {
+                    n.disconnect();
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+        }
+        // ---- pad ------------------------------------------------------------
+        const padFilter = keep(audio.createBiquadFilter());
+        padFilter.type = 'lowpass';
+        padFilter.frequency.value = H.PAD_BASE_HZ;
+        padFilter.Q.value = H.PAD_Q;
+        const padGain = keep(audio.createGain());
+        padGain.gain.value = 0;
+        padFilter.connect(padGain);
+        padGain.connect(scapeCtx.input);
+        const padOscs = [];
+        H.DRONE_HZ.forEach((hz, i) => {
+            const shaper = keep(audio.createWaveShaper());
+            shaper.curve = softWaveCurve();
+            const partial = keep(audio.createGain());
+            partial.gain.value = H.DRONE_GAINS[i];
+            shaper.connect(partial);
+            partial.connect(padFilter);
+            for (const side of [-1, 1]) {
+                const osc = keep(audio.createOscillator());
+                osc.type = 'sine';
+                osc.frequency.value = hz;
+                osc.detune.value = side * H.DETUNE_CENTS;
+                const pan = keep(makePan(audio, side * H.PAD_PAN));
+                osc.connect(pan).connect(shaper);
+                padOscs.push(osc);
+            }
+        });
+        // ---- floating pair ----------------------------------------------------
+        const floatGain = keep(audio.createGain());
+        floatGain.gain.value = 0;
+        floatGain.connect(scapeCtx.input);
+        const voices = [0, 1].map(() => {
+            const osc = keep(audio.createOscillator());
+            osc.type = 'sine';
+            const gain = keep(audio.createGain());
+            gain.gain.value = 0;
+            osc.connect(gain);
+            gain.connect(floatGain);
+            return { osc, gain };
+        });
+        // ---- air --------------------------------------------------------------
+        const rate = audio.sampleRate;
+        const airBuffer = audio.createBuffer(2, Math.floor(rate * H.AIR_SECONDS), rate);
+        for (let ch = 0; ch < 2; ch++)
+            fillPink(airBuffer.getChannelData(ch), rand);
+        const airSrc = keep(audio.createBufferSource());
+        airSrc.buffer = airBuffer;
+        airSrc.loop = true;
+        const airHp = keep(audio.createBiquadFilter());
+        airHp.type = 'highpass';
+        airHp.frequency.value = H.AIR_HP_HZ;
+        const airLp = keep(audio.createBiquadFilter());
+        airLp.type = 'lowpass';
+        airLp.frequency.value = H.AIR_LP_HZ;
+        const airGain = keep(audio.createGain());
+        airGain.gain.value = 0;
+        airSrc.connect(airHp);
+        airHp.connect(airLp);
+        airLp.connect(airGain);
+        airGain.connect(scapeCtx.input);
+        // ---- chime bus ----------------------------------------------------------
+        const chimeGain = keep(audio.createGain());
+        chimeGain.gain.value = 1;
+        chimeGain.connect(scapeCtx.input);
+        // ---- scheduler state ----------------------------------------------------
+        let toneIdx = 1; // voice 0 starts on TONES[0]; the next drift goes to A4
+        let activeVoice = 0;
+        let nextToneAt = Number.POSITIVE_INFINITY;
+        let nextChimeAt = Number.POSITIVE_INFINITY;
+        let chimesOn = true;
+        let entranceUntil = 0;
+        let unsub = null;
+        let activeChimes = [];
+        const gap = () => H.CHIME_MIN_GAP_S + rand() * (H.CHIME_MAX_GAP_S - H.CHIME_MIN_GAP_S);
+        function breathMul(value, depth) {
+            return 1 - depth * (1 - value);
+        }
+        function rampTo(param, v, at, dur) {
+            param.cancelScheduledValues(at);
+            param.setValueAtTime(param.value, at);
+            param.linearRampToValueAtTime(v, at + dur);
+        }
+        /** Hand the drift to the other voice: set its tone, cross-fade the two
+         *  gains over TONE_FADE_S, re-arm the next drift ~TONE_HOLD_S out. */
+        function driftTone(now) {
+            const freq = H.TONES_HZ[toneIdx % H.TONES_HZ.length];
+            toneIdx++;
+            const incoming = voices[1 - activeVoice];
+            const outgoing = voices[activeVoice];
+            incoming.osc.frequency.setValueAtTime(freq, now);
+            rampTo(incoming.gain.gain, 1, now, H.TONE_FADE_S);
+            rampTo(outgoing.gain.gain, 0, now, H.TONE_FADE_S);
+            activeVoice = 1 - activeVoice;
+            nextToneAt = now + H.TONE_HOLD_S + (rand() - 0.5) * 2 * H.TONE_JITTER_S;
+        }
+        /** One soft rounded chime: 3 partials of a chord tone, a slow swell,
+         *  then a long exponential decay (setTargetAtTime), random pan. */
+        function chime(now) {
+            const f = H.CHIME_HZ[Math.floor(rand() * H.CHIME_HZ.length)];
+            const pan = keep(makePan(audio, (rand() * 2 - 1) * H.CHIME_PAN_SPREAD));
+            pan.connect(chimeGain);
+            const env = keep(audio.createGain());
+            env.gain.value = 0;
+            env.connect(pan);
+            const oscs = [];
+            const pgs = [];
+            H.CHIME_PARTIAL_GAINS.forEach((g, i) => {
+                const osc = keep(audio.createOscillator());
+                osc.type = 'sine';
+                osc.frequency.value = f * (i + 1);
+                const pg = keep(audio.createGain());
+                pg.gain.value = g;
+                osc.connect(pg);
+                pg.connect(env);
+                oscs.push(osc);
+                pgs.push(pg);
+            });
+            const tail = H.CHIME_ATTACK_S + H.CHIME_TAILS * H.CHIME_TAU_S;
+            for (const osc of oscs) {
+                osc.start(now);
+                osc.stop(now + tail);
+            }
+            // A swell, not a strike: slow attack, then exponential decay.
+            env.gain.setValueAtTime(0, now);
+            env.gain.linearRampToValueAtTime(H.CHIME_LEVEL, now + H.CHIME_ATTACK_S);
+            env.gain.setTargetAtTime(0.0001, now + H.CHIME_ATTACK_S, H.CHIME_TAU_S);
+            // Self-cleaning: disconnect on a timer once the tail is done — never
+            // on a lookahead cb (a stopped instance's cbs get retired mid-fade).
+            const nodes = [pan, env, ...pgs, ...oscs];
+            const timer = setTimeout(() => disconnectAll(nodes), (tail + 0.05) * 1000);
+            activeChimes.push({ oscs, nodes, until: now + tail, timer });
+            nextChimeAt = now + gap();
+        }
+        /** The ONE per-tick callback: breath modulation, chime retirement,
+         *  tone drift, chime scheduling. Runs every engine tick (~250 ms). */
+        function onTick(now) {
+            const b = scapeCtx.breath.state;
+            // The pad filter opens ~180 Hz on the in-breath; the three section
+            // levels swell with it. During the entrance the ramps own the
+            // levels (the filter is silent-safe and starts modulating at once).
+            padFilter.frequency.setTargetAtTime(H.PAD_BASE_HZ + H.PAD_BREATH_HZ * b.value, now, H.MOD_TAU_S);
+            if (now >= entranceUntil) {
+                padGain.gain.setTargetAtTime(H.PAD_LEVEL * breathMul(b.value, H.PAD_BREATH_DEPTH), now, H.MOD_TAU_S);
+                floatGain.gain.setTargetAtTime(H.FLOAT_LEVEL * breathMul(b.value, H.FLOAT_BREATH_DEPTH), now, H.MOD_TAU_S);
+                airGain.gain.setTargetAtTime(H.NOISE_LEVEL * breathMul(b.value, H.NOISE_BREATH_DEPTH), now, H.MOD_TAU_S);
+            }
+            // Bookkeeping only — no disconnects here (teardown never rides the
+            // lookahead queue). Chimes past their tail prune themselves; their
+            // nodes were already disconnected by their own timers.
+            if (activeChimes.length) {
+                activeChimes = activeChimes.filter((c) => now < c.until);
+            }
+            if (now >= nextToneAt)
+                driftTone(now);
+            if (chimesOn && now >= nextChimeAt)
+                chime(now);
+        }
+        function tryStop(node, at) {
+            try {
+                node.stop(at);
+            }
+            catch {
+                /* already stopped */
+            }
+        }
+        return {
+            start(at) {
+                // Entrance: sections rise from silence over ENTRANCE_S; breath
+                // modulation of the levels takes over once they arrive.
+                entranceUntil = at + H.ENTRANCE_S;
+                rampTo(padGain.gain, H.PAD_LEVEL, at, H.ENTRANCE_S);
+                rampTo(floatGain.gain, H.FLOAT_LEVEL, at, H.ENTRANCE_S);
+                rampTo(airGain.gain, H.NOISE_LEVEL, at, H.ENTRANCE_S);
+                // Voice 0 holds the first tone; voice 1 waits silent.
+                voices[0].osc.frequency.setValueAtTime(H.TONES_HZ[0], at);
+                voices[0].gain.gain.setValueAtTime(1, at);
+                nextToneAt = at + H.TONE_HOLD_S + (rand() - 0.5) * 2 * H.TONE_JITTER_S;
+                nextChimeAt = at + gap();
+                for (const osc of padOscs)
+                    osc.start(at);
+                voices[0].osc.start(at);
+                voices[1].osc.start(at);
+                // Random loop offset: the air never audibly repeats.
+                airSrc.start(at, rand() * H.AIR_SECONDS);
+                unsub = scapeCtx.lookahead(onTick);
+            },
+            stop(at, fade) {
+                unsub?.();
+                unsub = null;
+                const end = at + fade;
+                for (const g of [padGain, floatGain, airGain, chimeGain, voices[0].gain, voices[1].gain]) {
+                    rampTo(g.gain, 0, at, fade);
+                }
+                for (const osc of padOscs)
+                    tryStop(osc, end);
+                tryStop(voices[0].osc, end);
+                tryStop(voices[1].osc, end);
+                tryStop(airSrc, end);
+                for (const c of activeChimes) {
+                    for (const osc of c.oscs)
+                        tryStop(osc, end);
+                    clearTimeout(c.timer); // the final disconnect covers them
+                }
+                // Final teardown OFF the lookahead path: the engine retires a
+                // stopped instance's cbs at fade·1000 + 250 ms, so anything
+                // waiting for one more tick can be dropped mid-fade and leave
+                // nodes connected to the shared input. Disconnect on a timer
+                // instead — after the gains have finished ramping to 0.
+                setTimeout(() => disconnectAll(allNodes), fade * 1000 + 50);
+            },
+            setParam(key, value) {
+                if (key === 'breathsPerMinute') {
+                    // The SHARED clock — every sounding scape breathes together.
+                    scapeCtx.breath.bpm = Math.min(15, Math.max(1, value));
+                }
+                else if (key === 'chimes') {
+                    chimesOn = value !== 0;
+                    if (chimesOn) {
+                        // A fresh full gap, not an instant chime on re-enable.
+                        nextChimeAt = audio.currentTime + gap();
+                    }
+                    else {
+                        nextChimeAt = Number.POSITIVE_INFINITY;
+                    }
+                }
+            }
+        };
+    }
+};

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

@@ -0,0 +1,36 @@
+/**
+ * Nature scapes — rain and waves (phase 2, jatui-5y1y7).
+ *
+ * Two scapes against the Scape contract in ../types.ts. Nothing here is
+ * registered globally — the integration task wires the default registry.
+ *
+ *   rain   a filtered noise bed plus sparse randomized droplet transients
+ *          (short bandpassed noise bursts with varied pitch, pan and level,
+ *          scheduled on the engine's lookahead tick; `density` sets how busy
+ *          the patter is)
+ *   waves  noise through a slowly swelling bandpass with a scheduler-driven
+ *          level LFO — randomized 8–12 s swell periods, each swell rising
+ *          over ~45% of its period and decaying into a soft wash tail
+ *          (setTargetAtTime with a multi-second tau)
+ *
+ * CPU rules (task brief): no per-sample JS — everything is AudioBufferSource
+ * loops and native filter/gain nodes. The noise buffer is generated ONCE per
+ * AudioContext (WeakMap cache) and every user of it — bed and droplets alike
+ * — loops or slices it with a randomized start offset, so the bed never
+ * audibly repeats and droplets never land on the same grain twice.
+ *
+ * Cleanup contract (per WideFrost's contract note): the engine RETIRES a
+ * stopped instance's lookahead callbacks at fade*1000 + 250 ms — so teardown
+ * must NOT wait for a lookahead tick (it would race the retire and can be
+ * dropped, leaving nodes wired to the shared input). stop(at, fade) schedules
+ * source.stop(at+fade) on the AUDIO clock and disconnects every node on a
+ * wall-clock setTimeout(fade*1000 + 50) — comfortably ahead of the retire.
+ * Lookahead ticks only ever schedule sound (and prune long-play droplets).
+ *
+ * Background tabs: browsers throttle setInterval (down to ~1/min) while the
+ * audio clock keeps running, so both schedulers resync after a tick gap
+ * instead of firing every missed event as a burst when the tab returns.
+ */
+import type { Scape } from '../types';
+export declare const rain: Scape;
+export declare const waves: Scape;