@joewinke/jatui 0.46.0 → 0.48.0

package/README.md

@@ -12,6 +12,52 @@ Requires Svelte 5 and DaisyUI 5 as peer dependencies.
 
 ---
 
+## Ambience — generative background sound
+
+A headless Web Audio engine (`createAmbience` / `createDefaultAmbience`) plus the `AmbienceToggle` app-shell button — the audio twin of `ThemeToggle`. Everything is generative: no audio files, no libraries, one lazily-created AudioContext started only from a user gesture.
+
+```svelte
+<script>
+  // ONE engine, mounted once at the root layout, so sound survives navigation.
+  import { createDefaultAmbience } from 'jatui/ambience';
+  const engine = createDefaultAmbience(); // hibiscus, focus, brown/pink/white noise, rain, waves pre-registered
+</script>
+
+<AmbienceToggle {engine} />
+```
+
+`createDefaultAmbience()` registers every shipped scape (via the `jatui/ambience` subpath); register extras on top with `engine.register(myScape)`. Custom registry instead: `createAmbience()` + individually imported scapes (`hibiscusScape`, `focusScape`, `noiseScapes`, `rain`, `waves`).
+
+Key contract points:
+
+- **Gesture-gated** — `engine.play(id)` must run inside a click/keydown handler; it rejects otherwise. The AudioContext closes itself ~3 s after stop, and a play inside that window fades back in instead of restarting.
+- **Scape contract** — `{ id, label, group, description?, build(ctx) }`; `build` connects into `ctx.input` (never straight to `destination`), gets the shared `ctx.breath` clock and a lookahead scheduler. Scapes are re-buildable and tear themselves down on `stop`.
+- **Playlist scapes** — per-host, never in the default set. Build one with `createPlaylistScape({ id, label, manifestUrl })` and `engine.register()` it; the manifest is fetched lazily once on the first play, tracks stream through the master chain with gain-ramp crossfades, and the returned `PlaylistScape` adds `state()/subscribe()/skip()/setShuffle()` for the UI. Manifest shape (`title` optional at the manifest level; every track requires `title`, `composer`, `url` and `license` — tracks missing any are dropped — with `performer` and `sourceUrl` optional):
+
+```json
+{
+  "title": "Library",
+  "tracks": [
+    {
+      "title": "Nocturne Op. 9 No. 2",
+      "composer": "Frédéric Chopin",
+      "performer": "Public-domain recording",
+      "url": "/audio/nocturne-9-2.mp3",
+      "license": "Public domain",
+      "sourceUrl": "https://musopen.org/music/..."
+    }
+  ]
+}
+```
+
+Track URLs must be served with CORS headers (they are fetched as `HTMLAudioElement` sources fed into the Web Audio graph), and the host owns the manifest and its licensing claims — an example of public-domain Musopen recordings can be listed with attribution in the scape's `description`.
+- **Persistence** — volume + last scape persist through the engine (custom `storageKey`); restoring preselects but never autoplays.
+- **AmbienceToggle** — click plays/stops the last scape; ArrowDown, press-and-hold or right-click opens the grouped scape menu with volume; `aria-pressed` / `menuitemradio` / `aria-live` status wired; a rejected `play()` announces a transient “couldn't start — tap again” in the sr-only status, cleared by the next successful play; the glyph breathes with the shared breath clock and is static under reduced motion / `data-motion="calm"`.
+
+Demo: `/components/ambience-toggle` on the docs site.
+
+---
+
 ## Dialog Utilities
 
 `ConfirmDialog` and `InputDialog` are global, promise-based dialogs that replace the browser's native `confirm()` / `prompt()`. They're keyboard-accessible, animated, and theme-aware.

package/dist/ambience/README.md

@@ -0,0 +1,131 @@
+# jatui/ambience — headless scape engine
+
+Generative background sound for host apps: one shared `AudioContext`, a master
+chain (warm peaking tilt → lowpass → soft-clip limiter → 50% synthesized-convolution
+reverb), per-scape "scapes" that build a Web Audio graph into it, a ~250 ms
+lookahead tick, crossfades between scapes, volume persistence and a shared
+breath LFO. **Headless by design** — no UI, no `window` at import, the context
+is created lazily on the first gesture-driven `play()`.
+
+```ts
+import { createAmbience } from 'jatui/ambience'; // wired by the integration task
+import { playlistScape } from './scapes/playlist';
+
+const ambience = createAmbience();
+ambience.register(playlistScape({ id: 'library', label: 'Library', manifestUrl: '/ambience.json' }));
+// inside a click handler:
+await ambience.play('library');
+```
+
+- **The scape contract** lives in `src/lib/ambience/types.ts`: a `Scape` is
+  `{ id, label, group, description?, build(ctx) → ScapeInstance }`; an instance
+  is `{ start(at), stop(at, fade), setParam?(key, value) }`. A scape connects
+  into `ctx.input` — never into `destination` — and must be re-buildable (a
+  fresh graph per play, torn down by its own `stop()`).
+- **Teardown is wall-clock, never a lookahead tick.** The engine retires a
+  stopped instance's lookahead callbacks `fade*1000 + 250 ms` after `stop()`
+  (`retireCbs` in engine.ts) — a disconnect waiting on a tick can be dropped
+  with nodes still wired into the shared input. Schedule silencing on the
+  audio clock (gain ramps / `source.stop(at+fade)`) and disconnect from a
+  `setTimeout(fade*1000 + 50)`.
+- **Keep CPU low**: native nodes only, no per-sample JS. If you need noise,
+  generate the buffer once and loop it (randomized offsets so it never
+  audibly repeats).
+- **Lookahead is for scheduling sound, statelessly.** Re-anchor against
+  `ctx.currentTime` each tick (a background tab throttles `setInterval` to
+  ~1/min while the audio clock runs on) and cap events per tick, or a
+  returning tab fires every missed event at once.
+
+## Playlist scape — host-supplied manifest (phase 2)
+
+`src/lib/ambience/scapes/playlist.ts` — `createPlaylistScape()` streams a
+host-curated list of public-domain recordings through the master chain.
+**No audio files (and no manifest) ship in jatui** — the host supplies either
+inline `tracks` or a `manifestUrl`:
+
+| Option | Meaning |
+| --- | --- |
+| `id`, `label` | Scape identity (required). |
+| `manifestUrl` | Fetched **once, lazily, on the first play** — never at import. A failed fetch is not cached; the next play retries it. |
+| `tracks` | Inline track list — no fetch at all (resolved eagerly, a pure local filter). |
+| `crossfade` | Track-to-track crossfade in seconds, 0–30 (default 3). |
+| `shuffle` | Fisher–Yates play order over the engine's per-scape PRNG (default off). `setShuffle()` toggles live: the current track stays, the rest reorder. |
+| `gain` | Initial gain of the scape mix into the master chain, 0–1 (default 1). `setParam('gain', v)` ramps it live. |
+| `fetchFn`, `createMediaElement` | Injectable for tests (default `fetch` / `new Audio(url)`). |
+
+### Manifest format
+
+```json
+{
+  "title": "Evening piano — public domain",
+  "tracks": [
+    {
+      "title": "Nocturne in E-flat major, Op. 9 No. 2",
+      "composer": "Frédéric Chopin",
+      "performer": "Musopen performer recording",
+      "url": "https://cdn.example.org/chopin-nocturne-op9-2.mp3",
+      "license": "Public domain",
+      "sourceUrl": "https://musopen.org/music/4373-nocturnes-op-9/"
+    }
+  ]
+}
+```
+
+A bare `[ track, … ]` array is also accepted. Entries are validated: `title`,
+`composer`, `url` and `license` are required non-empty strings
+(`composer`/`performer`/`license` are exactly the attribution the toggle
+shows, `sourceUrl` is the link target); `performer` and `sourceUrl` are
+optional. Invalid entries are **filtered out**, not fatal — but a manifest
+with no valid tracks left puts the scape in the `error` state. In the example
+above the `url` is illustrative: point it at whatever stream the host serves
+(or an archive.org item). The **host is responsible for the manifest's
+licensing claims** — jatui only displays them.
+
+### Streaming + CORS
+
+Each track plays through `HTMLAudioElement → MediaElementAudioSourceNode →
+per-track gain → mix → ctx.input`, so the engine's warm tilt and soft-clip
+limiter shape the stream and crossfades are native gain ramps — no per-sample
+JS. Elements are created with `crossOrigin = 'anonymous'`, so **the host
+serving the audio must send CORS headers** (`Access-Control-Allow-Origin`);
+a non-CORS source then fails loudly per track (the scape skips to the next
+track) instead of playing silence into a tainted graph.
+
+### Behavior notes
+
+- Two ping-pong slots (element + source node + gain each) are **built once per
+  play** and reused for every track; the idle slot preloads the next track so
+  transitions don't wait on buffering.
+- End-of-track is detected statelessly in the lookahead (≤ `crossfade` +
+  0.25 s remaining) — at most one transition per tick, anchored at that tick's
+  `now`, so a throttled returning tab cannot burst missed transitions. A
+  stream without metadata falls back to the element's `ended` event with a
+  short ramp.
+- A single-track playlist loops its element instead of advancing.
+- A track that fails to play (bad URL, play() rejection, `error` event) is
+  skipped; if **every** track fails, the state goes `error` and the scape
+  fades itself out. The engine is not told (the Scape contract has no
+  failure channel) — the UI should surface `state().error`.
+- `stop()` flips the state to `idle` immediately, ramps the gains out on the
+  audio clock, then pauses the elements and disconnects every node
+  wall-clock (`fade*1000 + 50`). Nothing leaks into the shared input.
+
+### UI surface
+
+The returned object is a plain `Scape` for the engine plus a playlist surface:
+
+```ts
+const scape = playlistScape({ id: 'library', label: 'Library', manifestUrl });
+scape.subscribe((s) => {
+  // s.status: 'idle' | 'loading' | 'playing' | 'error'
+  // s.track: { title, composer, performer?, license, sourceUrl? } | null
+  // s.index, s.count, s.error?
+});
+scape.skip(); // crossfade to the next track now
+scape.setShuffle(true);
+scape.tracks(); // resolved list, or null until the manifest resolved
+```
+
+Cast a scape from `ambience.list()` to `PlaylistScape` in the toggle to reach
+it. The toggle renders the attribution line — `composer · performer · license`
+— linked to `sourceUrl` while a playlist scape is playing.

package/dist/ambience/breath.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The one shared breath LFO. Six breaths a minute on the hibiscus recipe; any
+ * scape can read it (and hosts sync visuals via engine.onBreath) so everything
+ * breathes together instead of each scape running its own wobble.
+ *
+ * Pure math on an elapsed-seconds accumulator — no WebAudio, no timers of its
+ * own; the engine's lookahead tick drives `update`.
+ */
+import type { BreathState } from './types';
+export declare const BREATHS_PER_MINUTE = 6;
+export declare class BreathClock {
+    #private;
+    get bpm(): number;
+    set bpm(v: number);
+    get running(): boolean;
+    start(now: number): void;
+    stop(): void;
+    reset(): void;
+    /** Advance the clock to `now` (seconds, same domain as ctx.currentTime). */
+    update(now: number): void;
+    get state(): BreathState;
+}

package/dist/ambience/breath.js

@@ -0,0 +1,43 @@
+export const BREATHS_PER_MINUTE = 6;
+export class BreathClock {
+    #bpm = BREATHS_PER_MINUTE;
+    #elapsed = 0;
+    #lastNow = null;
+    #running = false;
+    get bpm() {
+        return this.#bpm;
+    }
+    set bpm(v) {
+        this.#bpm = Math.max(0.5, v);
+    }
+    get running() {
+        return this.#running;
+    }
+    start(now) {
+        this.#lastNow = now;
+        this.#running = true;
+    }
+    stop() {
+        this.#running = false;
+        this.#lastNow = null;
+    }
+    reset() {
+        this.#elapsed = 0;
+    }
+    /** Advance the clock to `now` (seconds, same domain as ctx.currentTime). */
+    update(now) {
+        if (!this.#running || this.#lastNow === null) {
+            this.#lastNow = now;
+            return;
+        }
+        const dt = Math.max(0, now - this.#lastNow);
+        this.#lastNow = now;
+        this.#elapsed += dt;
+    }
+    get state() {
+        const half = 30 / this.#bpm; // seconds per inhale (== per exhale)
+        const t = this.#elapsed % (half * 2);
+        const rising = t < half;
+        return { value: rising ? t / half : 1 - (t - half) / half, rising };
+    }
+}

package/dist/ambience/default.d.ts

@@ -0,0 +1,24 @@
+/**
+ * createDefaultAmbience() — the "just works" engine.
+ *
+ * Every scape the library ships is pre-registered, in the menu order the
+ * AmbienceToggle groups them (meditation / focus / noise / nature). A host
+ * that supplies extra scapes (e.g. a playlist scape from a manifest of
+ * public-domain recordings) registers them on top — registry duplicate-id
+ * protection still applies.
+ *
+ * @example
+ *   import { createDefaultAmbience } from '../../../dist/ambience';
+ *   const ambience = createDefaultAmbience();
+ *   // inside a click handler:
+ *   await ambience.play('rain');
+ */
+import { type Ambience } from './engine';
+import type { Scape } from './types';
+/** The scapes the library ships, in canonical menu order. */
+export declare const DEFAULT_SCAPES: readonly Scape[];
+export interface DefaultAmbienceOptions {
+    /** Passed through to `createAmbience` (e.g. a custom `storageKey`). */
+    storageKey?: string;
+}
+export declare function createDefaultAmbience(options?: DefaultAmbienceOptions): Ambience;

package/dist/ambience/default.js

@@ -0,0 +1,34 @@
+/**
+ * createDefaultAmbience() — the "just works" engine.
+ *
+ * Every scape the library ships is pre-registered, in the menu order the
+ * AmbienceToggle groups them (meditation / focus / noise / nature). A host
+ * that supplies extra scapes (e.g. a playlist scape from a manifest of
+ * public-domain recordings) registers them on top — registry duplicate-id
+ * protection still applies.
+ *
+ * @example
+ *   import { createDefaultAmbience } from '../../../dist/ambience';
+ *   const ambience = createDefaultAmbience();
+ *   // inside a click handler:
+ *   await ambience.play('rain');
+ */
+import { createAmbience } from './engine';
+import { hibiscusScape } from './scapes/hibiscus';
+import { focusScape } from './scapes/focus';
+import { noiseScapes } from './scapes/noise';
+import { rain, waves } from './scapes/nature';
+/** The scapes the library ships, in canonical menu order. */
+export const DEFAULT_SCAPES = Object.freeze([
+    hibiscusScape,
+    focusScape,
+    ...noiseScapes,
+    rain,
+    waves
+]);
+export function createDefaultAmbience(options = {}) {
+    const ambience = createAmbience(options);
+    for (const scape of DEFAULT_SCAPES)
+        ambience.register(scape);
+    return ambience;
+}

package/dist/ambience/engine.d.ts

@@ -0,0 +1,21 @@
+import type { Ambience, AmbienceOptions } from './types';
+export declare const TIMING: Readonly<{
+    /** Lookahead tick interval (ms). */
+    TICK_MS: 250;
+    /** Crossfade between scapes (s). */
+    CROSSFADE: 2.5;
+    /** stop() fade-out (s). */
+    STOP_FADE: 0.55;
+    /** Seconds after stop() before the context closes. */
+    CLOSE_DELAY_MS: 3000;
+    /** Fade-back-in after a stop-then-play inside the close window (s). */
+    RESUME_FADE: 4;
+    /** setVolume ramp (s). */
+    VOLUME_RAMP: 0.3;
+    /** The fade handed to instance.stop() on kill — 0 = immediate. */
+    KILL_FADE: 0;
+    /** After a scape's stop fade, its un-released lookahead cbs are retired
+     *  this many ms past the fade end (margin so the last ticks still land). */
+    RETIRE_MARGIN_MS: 250;
+}>;
+export declare function createAmbience(options?: AmbienceOptions): Ambience;

package/dist/ambience/engine.js

@@ -0,0 +1,313 @@
+/**
+ * The ambience engine — the headless core. One AudioContext per engine,
+ * created lazily on the first gesture-driven play; a lookahead tick every
+ * 250 ms schedules ahead of currentTime (drift- and jitter-free); crossfades
+ * between scapes are ~2.5 s; stop() fades ~0.55 s and closes the context ~3 s
+ * later, and a play() inside that window cancels the close and fades back in
+ * over ~4 s; setVolume ramps 0.3 s; kill() is immediate. Persistence stores
+ * volume + last scape id only — restoring never autoplays.
+ *
+ * NO UI here. The AmbienceToggle task (jatui-b7qvr) hosts this module.
+ */
+import { BreathClock } from './breath';
+import { createMasterChain } from './master';
+import { loadPersisted, savePersisted } from './persist';
+import { ScapeRegistry } from './registry';
+export const TIMING = Object.freeze({
+    /** Lookahead tick interval (ms). */
+    TICK_MS: 250,
+    /** Crossfade between scapes (s). */
+    CROSSFADE: 2.5,
+    /** stop() fade-out (s). */
+    STOP_FADE: 0.55,
+    /** Seconds after stop() before the context closes. */
+    CLOSE_DELAY_MS: 3000,
+    /** Fade-back-in after a stop-then-play inside the close window (s). */
+    RESUME_FADE: 4,
+    /** setVolume ramp (s). */
+    VOLUME_RAMP: 0.3,
+    /** The fade handed to instance.stop() on kill — 0 = immediate. */
+    KILL_FADE: 0,
+    /** After a scape's stop fade, its un-released lookahead cbs are retired
+     *  this many ms past the fade end (margin so the last ticks still land). */
+    RETIRE_MARGIN_MS: 250
+});
+export function createAmbience(options = {}) {
+    const storageKey = options.storageKey ?? 'jatui:ambience';
+    const isGesture = options.isGesture ??
+        (() => {
+            // SSR/node: no navigator — permissive. In the browser the user's own
+            // activation state is the truth (the ctx would stay suspended anyway).
+            const nav = typeof navigator !== 'undefined' ? navigator : undefined;
+            return nav?.userActivation ? nav.userActivation.isActive : true;
+        });
+    const registry = new ScapeRegistry();
+    const breath = new BreathClock();
+    // Resting state restored from storage (never autoplays — preselect only).
+    const persisted = loadPersisted(storageKey);
+    let volume = clamp(typeof persisted.volume === 'number' ? persisted.volume : (options.defaultVolume ?? 0.6));
+    let currentId = persisted.lastScape ?? null;
+    let playing = false;
+    let ctx = null;
+    let chain = null;
+    let active = null;
+    let tick = null;
+    let closeTimer = null;
+    /** Monotonic token: any await in play() is followed by a `gen !== playGen`
+     *  check, so a superseded or killed play() never builds/starts a scape. */
+    let playGen = 0;
+    const stateSubs = new Set();
+    const breathSubs = new Set();
+    const lookaheadCbs = new Set();
+    function state() {
+        return { currentId, playing, volume };
+    }
+    function emit() {
+        const s = state();
+        for (const fn of stateSubs)
+            fn(s);
+    }
+    function clamp(v) {
+        return Math.min(1, Math.max(0, v));
+    }
+    function ensureContext() {
+        if (ctx)
+            return ctx;
+        // Lazy: never constructed at import or on load (SSR-safe, no autoplay).
+        ctx = options.createContext ? options.createContext() : new AudioContext();
+        chain = createMasterChain(ctx);
+        chain.bus.gain.value = 1;
+        chain.volume.gain.value = volume;
+        breath.reset();
+        breath.start(ctx.currentTime);
+        tick = setInterval(onTick, TIMING.TICK_MS);
+        return ctx;
+    }
+    function onTick() {
+        if (!ctx)
+            return;
+        const now = ctx.currentTime;
+        breath.update(now);
+        const b = breath.state;
+        for (const fn of breathSubs)
+            fn(b);
+        for (const cb of lookaheadCbs)
+            cb(now);
+    }
+    function scheduleLookaheadFor(cbs) {
+        return (cb) => {
+            cbs.add(cb);
+            lookaheadCbs.add(cb);
+            return () => {
+                cbs.delete(cb);
+                lookaheadCbs.delete(cb);
+            };
+        };
+    }
+    /** Retire an instance's lookahead cbs once its stop fade has fully elapsed
+     *  (with a small margin so its final scheduled ticks still land). */
+    function retireCbs(a, fade) {
+        const t = setTimeout(() => {
+            for (const cb of a.cbs)
+                lookaheadCbs.delete(cb);
+            a.retireTimers.clear();
+        }, fade * 1000 + TIMING.RETIRE_MARGIN_MS);
+        a.retireTimers.add(t);
+    }
+    function stopInstanceNow(fade) {
+        if (active && ctx) {
+            const a = active;
+            active = null;
+            try {
+                a.inst.stop(ctx.currentTime, fade);
+            }
+            catch {
+                /* a broken scape must not take the engine down */
+            }
+            retireCbs(a, fade);
+        }
+    }
+    function persist() {
+        savePersisted(storageKey, { volume, lastScape: currentId ?? undefined });
+    }
+    async function play(id) {
+        const scape = registry.get(id);
+        if (!scape)
+            throw new Error(`Unknown scape: ${id}`);
+        if (!isGesture())
+            throw new Error('play() must be called from a user gesture');
+        // Monotonic play token: a second play() (or a stop()/kill()) while this
+        // one is suspended at `await c.resume()` invalidates it — the loser
+        // returns without building or starting anything.
+        const gen = ++playGen;
+        // Inside the post-stop close window: cancel the close, fade back in.
+        const resuming = closeTimer !== null;
+        if (closeTimer !== null) {
+            clearTimeout(closeTimer);
+            closeTimer = null;
+        }
+        const c = ensureContext();
+        if (c.state === 'suspended')
+            await c.resume();
+        // Superseded (another play won) or killed (ctx/chain nulled) mid-resume.
+        if (gen !== playGen || ctx !== c || !chain)
+            return;
+        // Crossfade: old scape fades out over CROSSFADE while the new one starts.
+        stopInstanceNow(resuming ? TIMING.STOP_FADE : TIMING.CROSSFADE);
+        // A stop() stopped the breath clock; a resume inside the close window
+        // must restart it or the clock is dead for the rest of the session.
+        if (!breath.running)
+            breath.start(c.currentTime);
+        const instCbs = new Set();
+        const scapeCtx = {
+            audio: c,
+            input: chain.input,
+            breath,
+            lookahead: scheduleLookaheadFor(instCbs),
+            // Fresh PRNG per build: a shared stream would interleave between the
+            // outgoing and incoming scape during a crossfade.
+            rand: makeRand(id)
+        };
+        let inst;
+        try {
+            inst = scape.build(scapeCtx);
+        }
+        catch {
+            return; // a broken scape must not take the engine down
+        }
+        if (gen !== playGen)
+            return; // stop()/kill() raced the (sync) build
+        active = { inst, cbs: instCbs, retireTimers: new Set() };
+        if (resuming) {
+            // Fade the bus back in over RESUME_FADE — scheduled, no .value write.
+            const g = chain.bus.gain;
+            g.cancelScheduledValues(c.currentTime);
+            g.setValueAtTime(g.value, c.currentTime);
+            g.linearRampToValueAtTime(1, c.currentTime + TIMING.RESUME_FADE);
+        }
+        inst.start(c.currentTime);
+        // Tick the new scape once immediately so it can schedule ahead of "now".
+        for (const cb of instCbs)
+            cb(c.currentTime);
+        currentId = id;
+        playing = true;
+        persist();
+        emit();
+    }
+    function stop() {
+        playGen++; // invalidate any in-flight play()
+        if (!ctx || !playing) {
+            playing = false;
+            emit();
+            return;
+        }
+        const now = ctx.currentTime;
+        stopInstanceNow(TIMING.STOP_FADE + 0.05);
+        const g = chain.bus.gain;
+        g.cancelScheduledValues(now);
+        g.setValueAtTime(g.value, now);
+        g.linearRampToValueAtTime(0, now + TIMING.STOP_FADE);
+        breath.stop();
+        playing = false;
+        // Close the context after the window; a play() inside it cancels this.
+        if (closeTimer)
+            clearTimeout(closeTimer);
+        closeTimer = setTimeout(() => {
+            closeTimer = null;
+            kill();
+        }, TIMING.CLOSE_DELAY_MS);
+        emit();
+    }
+    function kill() {
+        playGen++; // invalidate any in-flight play()
+        if (closeTimer) {
+            clearTimeout(closeTimer);
+            closeTimer = null;
+        }
+        if (tick) {
+            clearInterval(tick);
+            tick = null;
+        }
+        if (ctx)
+            stopInstanceNow(TIMING.KILL_FADE); // immediate
+        // Retire every live scape's lookahead cbs NOW — no more ticks at all.
+        lookaheadCbs.clear();
+        if (active) {
+            for (const t of active.retireTimers)
+                clearTimeout(t);
+            active = null;
+        }
+        breath.stop();
+        if (chain) {
+            chain.dispose();
+            chain = null;
+        }
+        if (ctx) {
+            try {
+                ctx.close();
+            }
+            catch {
+                /* already closed */
+            }
+            ctx = null;
+        }
+        playing = false;
+        emit();
+    }
+    function setVolume(v) {
+        volume = clamp(v);
+        if (chain && ctx) {
+            const g = chain.volume.gain;
+            g.cancelScheduledValues(ctx.currentTime);
+            g.setValueAtTime(g.value, ctx.currentTime);
+            g.linearRampToValueAtTime(volume, ctx.currentTime + TIMING.VOLUME_RAMP);
+        }
+        persist();
+        emit();
+    }
+    // Deterministic PRNG scoped to ONE scape build (mulberry32, seeded by the
+    // scape id): fresh closure per play so crossfading scapes never share
+    // (and interleave) one stream.
+    function makeRand(id) {
+        let s = hashId(id) || 1;
+        return () => {
+            s = (s + 0x6d2b79f5) >>> 0;
+            let t = s;
+            t = Math.imul(t ^ (t >>> 15), t | 1);
+            t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+            return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+        };
+    }
+    return {
+        register(scape) {
+            registry.register(scape);
+        },
+        list() {
+            return registry.list();
+        },
+        play,
+        stop,
+        kill,
+        setVolume,
+        get state() {
+            return state();
+        },
+        subscribe(fn) {
+            stateSubs.add(fn);
+            fn(state());
+            return () => stateSubs.delete(fn);
+        },
+        onBreath(fn) {
+            breathSubs.add(fn);
+            return () => breathSubs.delete(fn);
+        }
+    };
+}
+function hashId(id) {
+    let h = 2166136261;
+    for (let i = 0; i < id.length; i++) {
+        h ^= id.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return h >>> 0;
+}

package/dist/ambience/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Ambience engine — public entry. Headless by design: hosts (e.g.
+ * AmbienceToggle.svelte) import createAmbience and wire their own UI.
+ *
+ * @example
+ *   import { createAmbience, createDefaultAmbience } from '../../../dist/ambience'; // once integration lands
+ *   const ambience = createDefaultAmbience(); // hibiscus, focus, noise, rain, waves pre-registered
+ *   ambience.register(myScape);
+ *   // inside a click handler:
+ *   await ambience.play('rain');
+ */
+export { createAmbience, TIMING } from './engine';
+export { createDefaultAmbience, DEFAULT_SCAPES, type DefaultAmbienceOptions } from './default';
+export { hibiscusScape } from './scapes/hibiscus';
+export { focusScape } from './scapes/focus';
+export { noiseScapes, brownNoiseScape, pinkNoiseScape, whiteNoiseScape } from './scapes/noise';
+export { rain, waves } from './scapes/nature';
+export { createPlaylistScape } from './scapes/playlist';
+export type { PlaylistScape, PlaylistScapeOptions, PlaylistManifest, PlaylistState, PlaylistStatus, PlaylistTrack } from './scapes/playlist';
+export { BreathClock, BREATHS_PER_MINUTE } from './breath';
+export { MASTER } from './master';
+export { ScapeRegistry } from './registry';
+export type { Ambience, AmbienceOptions, AmbienceState, BreathState, Scape, ScapeContext, ScapeGroup, ScapeInstance } from './types';