@joewinke/jatui 0.27.1 → 0.29.0

package/dist/sound/backend.js

@@ -0,0 +1,96 @@
+/**
+ * Audio output backend. The player talks to this interface so its policy and
+ * bookkeeping run in node tests with a fake; `createWebAudioBackend` is the
+ * real one (lazy AudioContext, decoded-buffer playback through a GainNode).
+ */
+function dataUriBytes(uri) {
+    const binary = atob(uri.slice(uri.indexOf(',') + 1));
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes.buffer;
+}
+export function createWebAudioBackend() {
+    let ctx = null;
+    function context() {
+        if (ctx)
+            return ctx;
+        if (typeof AudioContext === 'undefined')
+            return null;
+        try {
+            ctx = new AudioContext();
+        }
+        catch {
+            return null;
+        }
+        return ctx;
+    }
+    return {
+        async load(src) {
+            const audio = context();
+            if (!audio)
+                return null;
+            try {
+                const bytes = src.startsWith('data:')
+                    ? dataUriBytes(src)
+                    : await (await fetch(src)).arrayBuffer();
+                return await audio.decodeAudioData(bytes);
+            }
+            catch {
+                return null; // codec unsupported / network error — stay silent
+            }
+        },
+        start(clip, { gain, loop, loopGapMs, playbackRate = 1, onEnded }) {
+            const audio = context();
+            if (!audio || !clip)
+                return null;
+            // Autoplay policy: the context starts suspended until a user gesture.
+            if (audio.state === 'suspended')
+                audio.resume().catch(() => { });
+            const out = audio.createGain();
+            out.gain.value = gain;
+            out.connect(audio.destination);
+            let source = null;
+            let timer = null;
+            let stopped = false;
+            const once = () => {
+                if (stopped)
+                    return;
+                source = audio.createBufferSource();
+                source.buffer = clip;
+                source.playbackRate.value = playbackRate;
+                source.loop = loop && loopGapMs <= 0;
+                source.connect(out);
+                source.onended = () => {
+                    if (stopped)
+                        return;
+                    if (loop && loopGapMs > 0)
+                        timer = setTimeout(once, loopGapMs);
+                    else if (!loop) {
+                        stopped = true;
+                        out.disconnect();
+                        onEnded?.();
+                    }
+                };
+                source.start();
+            };
+            once();
+            return {
+                stop() {
+                    if (stopped)
+                        return;
+                    stopped = true;
+                    if (timer)
+                        clearTimeout(timer);
+                    try {
+                        source?.stop();
+                    }
+                    catch {
+                        // already ended
+                    }
+                    out.disconnect();
+                }
+            };
+        }
+    };
+}

package/dist/sound/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Sound — first-class sibling of motion (jatui-kf62q).
+ *
+ * One preferences store every app sound goes through, semantic sound names
+ * mapped to bundled CC0 clips (or a host's own files), a pure policy function,
+ * and a drop-in SoundSettings section. Discipline: docs/sound.md.
+ */
+export { SOUND_CATEGORIES, SOUND_NAMES, SOUND_SPECS, CUSTOM_SOUND_SPEC, BUILTIN_CLIPS, SOUND_CLIP_VARIANTS, PENTATONIC_STEPS, isSoundName, soundSpecFor, pentatonicPitch } from './names';
+export type { SoundCategory, SoundName, SoundSpec } from './names';
+export { DEFAULT_SOUND_PREFERENCES, SOUND_PREFS_STORAGE_KEY, LEGACY_SOUND_ENABLED_KEY, createSoundPreferences, getSoundPreferences, setSoundPreferences, normalizeSoundPreferences } from './preferences';
+export type { SoundPreferences, SoundPreferencesPatch, SoundPreferencesStore, SoundPreferencesStorage, SoundQuietMode, QuietHours, CreateSoundPreferencesOptions } from './preferences';
+export { SOUND_LEVELS, DEFAULT_SOUND_LEVEL, SOUND_LEVEL_ATTR, isSoundLevel, parseSoundLevel, resolveSoundLevel, setSoundLevel, soundLevelDefaults } from './level';
+export type { SoundLevel } from './level';
+export { decideSound, inQuietHours, readSoundEnvironment } from './policy';
+export type { SoundEnvironment, SoundRequest, SoundDecision, SoundBlockReason } from './policy';
+export { createSoundPlayer, getSoundPlayer, setSoundPlayer, playSound, rateFor as soundPlaybackRate } from './player';
+export type { SoundId, SoundPlayer, SoundHandle, PlaySoundOptions, CreateSoundPlayerOptions } from './player';
+export { createWebAudioBackend } from './backend';
+export type { SoundBackend, SoundVoice, StartOptions as SoundStartOptions } from './backend';
+export { default as SoundSettings } from './SoundSettings.svelte';

package/dist/sound/index.js

@@ -0,0 +1,14 @@
+/**
+ * Sound — first-class sibling of motion (jatui-kf62q).
+ *
+ * One preferences store every app sound goes through, semantic sound names
+ * mapped to bundled CC0 clips (or a host's own files), a pure policy function,
+ * and a drop-in SoundSettings section. Discipline: docs/sound.md.
+ */
+export { SOUND_CATEGORIES, SOUND_NAMES, SOUND_SPECS, CUSTOM_SOUND_SPEC, BUILTIN_CLIPS, SOUND_CLIP_VARIANTS, PENTATONIC_STEPS, isSoundName, soundSpecFor, pentatonicPitch } from './names';
+export { DEFAULT_SOUND_PREFERENCES, SOUND_PREFS_STORAGE_KEY, LEGACY_SOUND_ENABLED_KEY, createSoundPreferences, getSoundPreferences, setSoundPreferences, normalizeSoundPreferences } from './preferences';
+export { SOUND_LEVELS, DEFAULT_SOUND_LEVEL, SOUND_LEVEL_ATTR, isSoundLevel, parseSoundLevel, resolveSoundLevel, setSoundLevel, soundLevelDefaults } from './level';
+export { decideSound, inQuietHours, readSoundEnvironment } from './policy';
+export { createSoundPlayer, getSoundPlayer, setSoundPlayer, playSound, rateFor as soundPlaybackRate } from './player';
+export { createWebAudioBackend } from './backend';
+export { default as SoundSettings } from './SoundSettings.svelte';

package/dist/sound/level.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Site sound level — the host's say in whether UI sound starts on.
+ *
+ * A host stamps `data-sound="off|subtle"` on `<html>` (or any subtree) the
+ * same way it stamps `data-motion`, usually from per-site config. The level
+ * only changes the DEFAULT for a visitor with no saved preference:
+ *
+ *   off     the library default — UI + notification sounds start off.
+ *   subtle  they start on (`enabled: true`) for a visitor who never chose.
+ *
+ * A saved visitor preference (the panel mute, SoundSettings) always wins,
+ * because `createSoundPreferences` applies `defaults` only when nothing is
+ * saved. The level never touches volume, categories, quiet hours or the
+ * `decideSound` policy — hidden tabs, quiet hours and `quiet: auto` (reduced
+ * motion) still silence what they silence.
+ */
+import type { SoundPreferencesPatch } from './preferences';
+export type SoundLevel = 'off' | 'subtle';
+export declare const SOUND_LEVELS: readonly SoundLevel[];
+export declare const DEFAULT_SOUND_LEVEL: SoundLevel;
+/** The attribute a host sets on `<html>` or any subtree. */
+export declare const SOUND_LEVEL_ATTR = "data-sound";
+export declare function isSoundLevel(value: unknown): value is SoundLevel;
+/** Coerce any attribute/config value to a level; unknown values become `off`. */
+export declare function parseSoundLevel(value: unknown, fallback?: SoundLevel): SoundLevel;
+/**
+ * The level in force for `node`: its nearest `[data-sound]` ancestor
+ * (inclusive), else `<html>`'s, else `off`. An unknown value counts as `off`
+ * — a typo fails silent, never loud. SSR-safe (`off`).
+ */
+export declare function resolveSoundLevel(node?: Element | null): SoundLevel;
+/**
+ * Set the level on a surface (default `<html>`). `null` removes the attribute.
+ * No-op without a DOM. Set it before the first sound plays: the shared
+ * preferences store reads the level once, when it is created.
+ */
+export declare function setSoundLevel(level: SoundLevel | null, target?: Element | null): void;
+/**
+ * The preference defaults a level implies, for `createSoundPreferences({ defaults })`.
+ * A panel scoping its own store to a subtree passes `soundLevelDefaults(resolveSoundLevel(panelEl))`.
+ */
+export declare function soundLevelDefaults(level: SoundLevel): SoundPreferencesPatch;

package/dist/sound/level.js

@@ -0,0 +1,63 @@
+/**
+ * Site sound level — the host's say in whether UI sound starts on.
+ *
+ * A host stamps `data-sound="off|subtle"` on `<html>` (or any subtree) the
+ * same way it stamps `data-motion`, usually from per-site config. The level
+ * only changes the DEFAULT for a visitor with no saved preference:
+ *
+ *   off     the library default — UI + notification sounds start off.
+ *   subtle  they start on (`enabled: true`) for a visitor who never chose.
+ *
+ * A saved visitor preference (the panel mute, SoundSettings) always wins,
+ * because `createSoundPreferences` applies `defaults` only when nothing is
+ * saved. The level never touches volume, categories, quiet hours or the
+ * `decideSound` policy — hidden tabs, quiet hours and `quiet: auto` (reduced
+ * motion) still silence what they silence.
+ */
+export const SOUND_LEVELS = ['off', 'subtle'];
+export const DEFAULT_SOUND_LEVEL = 'off';
+/** The attribute a host sets on `<html>` or any subtree. */
+export const SOUND_LEVEL_ATTR = 'data-sound';
+export function isSoundLevel(value) {
+    return typeof value === 'string' && SOUND_LEVELS.includes(value);
+}
+/** Coerce any attribute/config value to a level; unknown values become `off`. */
+export function parseSoundLevel(value, fallback = DEFAULT_SOUND_LEVEL) {
+    if (typeof value !== 'string')
+        return fallback;
+    const v = value.trim().toLowerCase();
+    return isSoundLevel(v) ? v : fallback;
+}
+/**
+ * The level in force for `node`: its nearest `[data-sound]` ancestor
+ * (inclusive), else `<html>`'s, else `off`. An unknown value counts as `off`
+ * — a typo fails silent, never loud. SSR-safe (`off`).
+ */
+export function resolveSoundLevel(node) {
+    const el = (node ?? (typeof document !== 'undefined' ? document.documentElement : null));
+    if (!el || typeof el.closest !== 'function')
+        return DEFAULT_SOUND_LEVEL;
+    const host = el.closest(`[${SOUND_LEVEL_ATTR}]`);
+    return host ? parseSoundLevel(host.getAttribute(SOUND_LEVEL_ATTR)) : DEFAULT_SOUND_LEVEL;
+}
+/**
+ * Set the level on a surface (default `<html>`). `null` removes the attribute.
+ * No-op without a DOM. Set it before the first sound plays: the shared
+ * preferences store reads the level once, when it is created.
+ */
+export function setSoundLevel(level, target) {
+    const el = target ?? (typeof document !== 'undefined' ? document.documentElement : null);
+    if (!el)
+        return;
+    if (level === null)
+        el.removeAttribute(SOUND_LEVEL_ATTR);
+    else
+        el.setAttribute(SOUND_LEVEL_ATTR, level);
+}
+/**
+ * The preference defaults a level implies, for `createSoundPreferences({ defaults })`.
+ * A panel scoping its own store to a subtree passes `soundLevelDefaults(resolveSoundLevel(panelEl))`.
+ */
+export function soundLevelDefaults(level) {
+    return level === 'subtle' ? { enabled: true } : {};
+}

package/dist/sound/names.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Semantic sound names — what an app SAYS ("confirm", "incoming-call"), not
+ * which file it plays. Each name carries the policy facts the preferences
+ * layer needs: its category, a base volume, whether it is essential (survives
+ * the quiet/reduced-motion preference), and how it loops.
+ *
+ * Hosts can re-point any name at their own file (`player.register('incoming-call',
+ * '/ringer.mp3')`) and can register names of their own; unknown names fall back
+ * to `CUSTOM_SOUND_SPEC` (a non-essential UI sound).
+ */
+export type SoundCategory = 'ui' | 'notifications' | 'calls';
+export declare const SOUND_CATEGORIES: readonly SoundCategory[];
+export type SoundName = 'confirm' | 'error' | 'notify' | 'message' | 'send' | 'toggle' | 'tap' | 'tick' | 'select' | 'chime' | 'attention' | 'incoming-call';
+export declare const SOUND_NAMES: readonly SoundName[];
+export interface SoundSpec {
+    category: SoundCategory;
+    /** Base gain 0–1 before the master volume is applied. */
+    volume: number;
+    /** Essential UI sounds still play when the quiet preference is active. */
+    essential: boolean;
+    /** Loop until the returned handle is stopped (call ringers). */
+    loop: boolean;
+    /**
+     * Silence between repeats when looping, in ms. 0 = seamless loop (a real
+     * ringer file); >0 replays a short clip on an interval (the built-in ring).
+     */
+    loopGapMs: number;
+    /**
+     * Throttle floor in ms: a play within this long of the last one that
+     * actually sounded is DROPPED (never queued). 0 = no throttle.
+     */
+    minIntervalMs: number;
+    description: string;
+}
+export declare const SOUND_SPECS: Record<SoundName, SoundSpec>;
+/** Spec for a host-registered name that is not one of the semantic names. */
+export declare const CUSTOM_SOUND_SPEC: SoundSpec;
+export declare function isSoundName(name: string): name is SoundName;
+export declare function soundSpecFor(name: string): SoundSpec;
+/**
+ * The bundled CC0 clip for each semantic name, loaded on first use so apps
+ * that never play a sound never ship the base64 payloads in their entry chunk.
+ */
+export declare const BUILTIN_CLIPS: Record<SoundName, () => Promise<string>>;
+/**
+ * Alternative bundled clips a host can point a name at:
+ *
+ *   await getSoundPlayer().register('error', await SOUND_CLIP_VARIANTS['error-soft'](), { volume: 0.08 })
+ *
+ * `error-soft` is two low sine tones (392 → 330 Hz) with no buzz — for
+ * surfaces where the stock error buzz is too harsh (booking flows).
+ */
+export declare const SOUND_CLIP_VARIANTS: {
+    'error-soft': () => Promise<string>;
+};
+/** Semitone offsets of a rising major pentatonic — one per step of a 7-item strip. */
+export declare const PENTATONIC_STEPS: readonly number[];
+/**
+ * Semitone offset for item `index` on a rising pentatonic (wraps up an octave
+ * past the table), for `playSound('tick', { pitch: pentatonicPitch(i) })`.
+ */
+export declare function pentatonicPitch(index: number): number;

package/dist/sound/names.js

@@ -0,0 +1,196 @@
+/**
+ * Semantic sound names — what an app SAYS ("confirm", "incoming-call"), not
+ * which file it plays. Each name carries the policy facts the preferences
+ * layer needs: its category, a base volume, whether it is essential (survives
+ * the quiet/reduced-motion preference), and how it loops.
+ *
+ * Hosts can re-point any name at their own file (`player.register('incoming-call',
+ * '/ringer.mp3')`) and can register names of their own; unknown names fall back
+ * to `CUSTOM_SOUND_SPEC` (a non-essential UI sound).
+ */
+export const SOUND_CATEGORIES = ['ui', 'notifications', 'calls'];
+export const SOUND_NAMES = [
+    'confirm',
+    'error',
+    'notify',
+    'message',
+    'send',
+    'toggle',
+    'tap',
+    'tick',
+    'select',
+    'chime',
+    'attention',
+    'incoming-call'
+];
+export const SOUND_SPECS = {
+    confirm: {
+        category: 'ui',
+        volume: 0.15,
+        essential: false,
+        loop: false,
+        loopGapMs: 0,
+        minIntervalMs: 0,
+        description: 'An important action succeeded (saved, paid, published)'
+    },
+    error: {
+        category: 'ui',
+        volume: 0.2,
+        essential: true,
+        loop: false,
+        loopGapMs: 0,
+        minIntervalMs: 0,
+        description: 'An action failed'
+    },
+    notify: {
+        category: 'notifications',
+        volume: 0.3,
+        essential: false,
+        loop: false,
+        loopGapMs: 0,
+        minIntervalMs: 0,
+        description: 'Something happened the user did not cause'
+    },
+    message: {
+        category: 'notifications',
+        volume: 0.3,
+        essential: false,
+        loop: false,
+        loopGapMs: 0,
+        minIntervalMs: 0,
+        description: 'A message arrived from another person'
+    },
+    send: {
+        category: 'ui',
+        volume: 0.15,
+        essential: false,
+        loop: false,
+        loopGapMs: 0,
+        minIntervalMs: 0,
+        description: 'The user sent a message or submitted a form'
+    },
+    toggle: {
+        category: 'ui',
+        volume: 0.12,
+        essential: false,
+        loop: false,
+        loopGapMs: 0,
+        minIntervalMs: 0,
+        description: 'A switch changed state'
+    },
+    tap: {
+        category: 'ui',
+        volume: 0.1,
+        essential: false,
+        loop: false,
+        loopGapMs: 0,
+        minIntervalMs: 0,
+        description: 'A deliberate, low-frequency press'
+    },
+    tick: {
+        category: 'ui',
+        volume: 0.03,
+        essential: false,
+        loop: false,
+        loopGapMs: 0,
+        minIntervalMs: 80,
+        description: 'The pointer or keyboard focus crossed onto a choice (pointer-fine only, pitch by position)'
+    },
+    select: {
+        category: 'ui',
+        volume: 0.08,
+        essential: false,
+        loop: false,
+        loopGapMs: 0,
+        minIntervalMs: 120,
+        description: 'The user chose something (a card, a day, a time, an answer)'
+    },
+    chime: {
+        category: 'ui',
+        volume: 0.12,
+        essential: false,
+        loop: false,
+        loopGapMs: 0,
+        minIntervalMs: 0,
+        description: 'A big thing just went right (the visit is booked) — rarer and warmer than confirm'
+    },
+    attention: {
+        category: 'ui',
+        volume: 0.1,
+        essential: false,
+        loop: false,
+        loopGapMs: 0,
+        minIntervalMs: 0,
+        description: 'Read this before you continue — calm, never an alarm'
+    },
+    'incoming-call': {
+        category: 'calls',
+        volume: 0.5,
+        essential: true,
+        loop: true,
+        loopGapMs: 1200,
+        minIntervalMs: 0,
+        description: 'Someone is calling — rings until answered or declined'
+    }
+};
+/** Spec for a host-registered name that is not one of the semantic names. */
+export const CUSTOM_SOUND_SPEC = {
+    category: 'ui',
+    volume: 0.15,
+    essential: false,
+    loop: false,
+    loopGapMs: 0,
+    minIntervalMs: 0,
+    description: 'Host-registered sound'
+};
+/** Pre-semantic clip names (utils/sound.ts era) mapped to their semantic spec. */
+const LEGACY_ALIASES = { success: 'confirm', pop: 'tap' };
+export function isSoundName(name) {
+    return SOUND_NAMES.includes(name);
+}
+export function soundSpecFor(name) {
+    if (isSoundName(name))
+        return SOUND_SPECS[name];
+    const alias = LEGACY_ALIASES[name];
+    return alias ? SOUND_SPECS[alias] : CUSTOM_SOUND_SPEC;
+}
+/**
+ * The bundled CC0 clip for each semantic name, loaded on first use so apps
+ * that never play a sound never ship the base64 payloads in their entry chunk.
+ */
+export const BUILTIN_CLIPS = {
+    confirm: () => import('../assets/sounds/success').then((m) => m.successSound),
+    error: () => import('../assets/sounds/error').then((m) => m.errorSound),
+    notify: () => import('../assets/sounds/notify').then((m) => m.notifySound),
+    message: () => import('../assets/sounds/notify').then((m) => m.notifySound),
+    send: () => import('../assets/sounds/send').then((m) => m.sendSound),
+    toggle: () => import('../assets/sounds/toggle').then((m) => m.toggleSound),
+    tap: () => import('../assets/sounds/pop').then((m) => m.popSound),
+    tick: () => import('../assets/sounds/tick').then((m) => m.tickSound),
+    select: () => import('../assets/sounds/select').then((m) => m.selectSound),
+    chime: () => import('../assets/sounds/chime').then((m) => m.chimeSound),
+    attention: () => import('../assets/sounds/attention').then((m) => m.attentionSound),
+    'incoming-call': () => import('../assets/sounds/notify').then((m) => m.notifySound)
+};
+/**
+ * Alternative bundled clips a host can point a name at:
+ *
+ *   await getSoundPlayer().register('error', await SOUND_CLIP_VARIANTS['error-soft'](), { volume: 0.08 })
+ *
+ * `error-soft` is two low sine tones (392 → 330 Hz) with no buzz — for
+ * surfaces where the stock error buzz is too harsh (booking flows).
+ */
+export const SOUND_CLIP_VARIANTS = {
+    'error-soft': () => import('../assets/sounds/error-soft').then((m) => m.errorSoftSound)
+};
+/** Semitone offsets of a rising major pentatonic — one per step of a 7-item strip. */
+export const PENTATONIC_STEPS = [0, 2, 4, 7, 9, 12, 14];
+/**
+ * Semitone offset for item `index` on a rising pentatonic (wraps up an octave
+ * past the table), for `playSound('tick', { pitch: pentatonicPitch(i) })`.
+ */
+export function pentatonicPitch(index) {
+    const i = Math.max(0, Math.floor(index));
+    const n = 5; // notes per octave — the table's last two entries are the next octave
+    return PENTATONIC_STEPS[i % n] + 12 * Math.floor(i / n);
+}

package/dist/sound/player.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The sound player — semantic names in, policy-gated audio out.
+ *
+ *   const sound = getSoundPlayer()
+ *   sound.play('confirm')
+ *   await sound.register('incoming-call', '/sounds/ringer.mp3', { loopGapMs: 0 })
+ *   const ring = sound.play('incoming-call')   // loops
+ *   ring.stop()                                 // answered / declined
+ *
+ * `play` is synchronous and never throws: a sound that is blocked, missing or
+ * still decoding returns a handle anyway (`handle.blocked` says why it is
+ * silent). Looping sounds are re-checked whenever preferences change, so
+ * turning sound off or muting "calls" silences a ringing call immediately.
+ */
+import { type SoundBackend } from './backend';
+import { type SoundBlockReason, type SoundEnvironment } from './policy';
+import { type SoundPreferencesStore } from './preferences';
+import { type SoundCategory, type SoundName, type SoundSpec } from './names';
+/** A semantic name, or any name the host registered itself. */
+export type SoundId = SoundName | (string & {});
+export interface PlaySoundOptions {
+    /** Base gain 0–1, replacing the spec's (still scaled by master volume). */
+    volume?: number;
+    category?: SoundCategory;
+    essential?: boolean;
+    loop?: boolean;
+    /**
+     * Pitch offset in semitones, applied through `playbackRate` (so it also
+     * shortens/lengthens the clip). `pentatonicPitch(i)` gives a rising scale.
+     */
+    pitch?: number;
+    /** Explicit playback rate; multiplied with `pitch` when both are given. */
+    playbackRate?: number;
+    /** Throttle floor in ms for this play, replacing the spec's `minIntervalMs`. */
+    minIntervalMs?: number;
+    /**
+     * Explicit user test (a "Preview" button in settings): bypasses every gate
+     * except master volume (and the throttle). Never use it for app-triggered sounds.
+     */
+    preview?: boolean;
+}
+export interface SoundHandle {
+    stop(): void;
+    /** True while audible or still decoding toward audible. */
+    readonly playing: boolean;
+    /** Why it is silent, when the policy blocked it. */
+    readonly blocked: SoundBlockReason | null;
+}
+export interface SoundPlayer {
+    /** Point a name at a clip (data URI or URL) and decode it. */
+    register(name: SoundId, src: string, spec?: Partial<SoundSpec>): Promise<void>;
+    play(name: SoundId, options?: PlaySoundOptions): SoundHandle;
+    /** Decode clips ahead of time (defaults to every semantic name). */
+    preload(names?: readonly SoundId[]): Promise<void>;
+    stopAll(): void;
+    destroy(): void;
+}
+export interface CreateSoundPlayerOptions {
+    preferences?: SoundPreferencesStore;
+    environment?: () => SoundEnvironment;
+    backend?: SoundBackend;
+    /** Monotonic ms clock for the throttle (test seam). Defaults to `performance.now`. */
+    now?: () => number;
+}
+export declare function createSoundPlayer(options?: CreateSoundPlayerOptions): SoundPlayer;
+/** Effective playback rate for a play: `playbackRate × 2^(pitch/12)`, clamped to a sane range. */
+export declare function rateFor(opts: Pick<PlaySoundOptions, 'pitch' | 'playbackRate'>): number;
+/** The app-wide player, bound to the shared preferences store. */
+export declare function getSoundPlayer(): SoundPlayer;
+/** Test seam: replace (or with no argument, drop) the shared player. */
+export declare function setSoundPlayer(player: SoundPlayer | null): void;
+/** Shorthand for `getSoundPlayer().play(name, options)`. */
+export declare function playSound(name: SoundId, options?: PlaySoundOptions): SoundHandle;