@joewinke/jatui 0.27.0 → 0.28.0

package/dist/motion/transitions.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Token-built Svelte transitions — drop-in replacements for ad-hoc
+ * `svelte/transition` usage that read the `--motion-*` scheme and honour the
+ * surface's motion level (`data-motion`) and `prefers-reduced-motion`.
+ *
+ *   <div transition:motionFade>                       fade, --motion-enter
+ *   <div in:motionScale={{ easing: 'spring' }}>       pop (spring → glide when calm)
+ *   <section transition:motionSlide>                  height collapse, --motion-move
+ *   <aside in:glide={{ from: 'right' }}>              directional (transitions/glide)
+ *
+ * Shared params (all optional):
+ *   duration  a duration token ('instant'|'fast'|'enter'|'move') or a
+ *             STANDARD-level ms value — either way it is scaled by the level.
+ *   delay     standard-level ms, scaled the same way.
+ *   easing    an easing token ('glide'|'spring'|'standard') or a function.
+ *   level     pin the level instead of reading the nearest [data-motion].
+ *
+ * Reduced motion: duration and delay become 0 — the element appears/leaves
+ * in its end state. This matches the global floor in styles/motion.css.
+ */
+import { type EasingFn } from './easing';
+import { type MotionContext, type MotionDurationToken, type MotionEasingToken, type MotionLevel } from './level';
+export interface MotionTransitionParams {
+    duration?: MotionDurationToken | number;
+    delay?: number;
+    easing?: MotionEasingToken | EasingFn;
+    level?: MotionLevel;
+}
+export interface MotionTransitionConfig {
+    delay: number;
+    duration: number;
+    easing: EasingFn;
+    css: (t: number, u: number) => string;
+}
+export interface ResolvedMotionTiming {
+    ctx: MotionContext;
+    delay: number;
+    duration: number;
+    easing: EasingFn;
+}
+/** Resolve the level-aware timing for a transition on `node`. */
+export declare function resolveMotionTiming(node: Element | null, params: MotionTransitionParams, defaults: {
+    duration: MotionDurationToken | number;
+    easing: MotionEasingToken;
+}): ResolvedMotionTiming;
+export interface MotionFadeParams extends MotionTransitionParams {
+}
+/** Opacity fade. Defaults: --motion-enter, glide. */
+export declare function motionFade(node: Element, params?: MotionFadeParams): MotionTransitionConfig;
+export interface MotionScaleParams extends MotionTransitionParams {
+    /** Scale at the start of the enter. Default 0.95. */
+    start?: number;
+    /** Also fade. Default true. */
+    opacity?: boolean;
+}
+/**
+ * Scale + fade. Defaults: --motion-enter, glide. Pass `easing: 'spring'` for
+ * a state-confirmation pop on a SMALL element (policy: never on containers);
+ * calm and reduced surfaces get glide instead.
+ */
+export declare function motionScale(node: Element, params?: MotionScaleParams): MotionTransitionConfig;
+export interface MotionSlideParams extends MotionTransitionParams {
+    /** Collapse axis. Default 'y' (height). */
+    axis?: 'x' | 'y';
+    /** Also fade. Default false (matches svelte's slide). */
+    opacity?: boolean;
+}
+/**
+ * Size collapse/expand along an axis (svelte `slide`, on tokens).
+ * Defaults: --motion-move, standard — a container morph, symmetric move.
+ */
+export declare function motionSlide(node: Element, params?: MotionSlideParams): MotionTransitionConfig;

package/dist/motion/transitions.js

@@ -0,0 +1,112 @@
+/**
+ * Token-built Svelte transitions — drop-in replacements for ad-hoc
+ * `svelte/transition` usage that read the `--motion-*` scheme and honour the
+ * surface's motion level (`data-motion`) and `prefers-reduced-motion`.
+ *
+ *   <div transition:motionFade>                       fade, --motion-enter
+ *   <div in:motionScale={{ easing: 'spring' }}>       pop (spring → glide when calm)
+ *   <section transition:motionSlide>                  height collapse, --motion-move
+ *   <aside in:glide={{ from: 'right' }}>              directional (transitions/glide)
+ *
+ * Shared params (all optional):
+ *   duration  a duration token ('instant'|'fast'|'enter'|'move') or a
+ *             STANDARD-level ms value — either way it is scaled by the level.
+ *   delay     standard-level ms, scaled the same way.
+ *   easing    an easing token ('glide'|'spring'|'standard') or a function.
+ *   level     pin the level instead of reading the nearest [data-motion].
+ *
+ * Reduced motion: duration and delay become 0 — the element appears/leaves
+ * in its end state. This matches the global floor in styles/motion.css.
+ */
+import { motionEasing } from './easing';
+import { effectiveEasing, getMotionContext, motionContextFor, motionDuration, prefersReducedMotion } from './level';
+/** Resolve the level-aware timing for a transition on `node`. */
+export function resolveMotionTiming(node, params, defaults) {
+    const ctx = params.level
+        ? motionContextFor(params.level, prefersReducedMotion())
+        : getMotionContext(node);
+    const duration = motionDuration(params.duration ?? defaults.duration, ctx);
+    const delay = motionDuration(params.delay ?? 0, ctx);
+    const easing = typeof params.easing === 'function'
+        ? params.easing
+        : motionEasing(effectiveEasing(params.easing ?? defaults.easing, ctx));
+    return { ctx, delay, duration, easing };
+}
+const clamp01 = (n) => (n < 0 ? 0 : n > 1 ? 1 : n);
+function baseOpacity(node) {
+    if (typeof getComputedStyle !== 'function')
+        return 1;
+    const o = parseFloat(getComputedStyle(node).opacity);
+    return Number.isFinite(o) ? o : 1;
+}
+/** Opacity fade. Defaults: --motion-enter, glide. */
+export function motionFade(node, params = {}) {
+    const { delay, duration, easing } = resolveMotionTiming(node, params, {
+        duration: 'enter',
+        easing: 'glide'
+    });
+    const o = baseOpacity(node);
+    return { delay, duration, easing, css: (t) => `opacity: ${clamp01(t) * o}` };
+}
+/**
+ * Scale + fade. Defaults: --motion-enter, glide. Pass `easing: 'spring'` for
+ * a state-confirmation pop on a SMALL element (policy: never on containers);
+ * calm and reduced surfaces get glide instead.
+ */
+export function motionScale(node, params = {}) {
+    const { delay, duration, easing } = resolveMotionTiming(node, params, {
+        duration: 'enter',
+        easing: 'glide'
+    });
+    const start = params.start ?? 0.95;
+    const fade = params.opacity ?? true;
+    const o = baseOpacity(node);
+    const existing = typeof getComputedStyle === 'function' ? getComputedStyle(node).transform : 'none';
+    const prefix = existing && existing !== 'none' ? `${existing} ` : '';
+    return {
+        delay,
+        duration,
+        easing,
+        css: (t) => `transform: ${prefix}scale(${start + (1 - start) * t});` +
+            (fade ? ` opacity: ${clamp01(t) * o};` : '')
+    };
+}
+/**
+ * Size collapse/expand along an axis (svelte `slide`, on tokens).
+ * Defaults: --motion-move, standard — a container morph, symmetric move.
+ */
+export function motionSlide(node, params = {}) {
+    const { delay, duration, easing } = resolveMotionTiming(node, params, {
+        duration: 'move',
+        easing: 'standard'
+    });
+    const axis = params.axis ?? 'y';
+    const fade = params.opacity ?? false;
+    if (typeof getComputedStyle !== 'function') {
+        return { delay, duration, easing, css: () => '' };
+    }
+    const style = getComputedStyle(node);
+    const o = +style.opacity || 1;
+    const size = axis === 'y' ? 'height' : 'width';
+    const [a, b] = axis === 'y' ? ['top', 'bottom'] : ['left', 'right'];
+    const px = (prop) => parseFloat(style.getPropertyValue(prop)) || 0;
+    const full = px(size);
+    const padA = px(`padding-${a}`);
+    const padB = px(`padding-${b}`);
+    const marA = px(`margin-${a}`);
+    const marB = px(`margin-${b}`);
+    const borA = px(`border-${a}-width`);
+    const borB = px(`border-${b}-width`);
+    return {
+        delay,
+        duration,
+        easing,
+        css: (t) => 'overflow: hidden;' +
+            (fade ? ` opacity: ${Math.min(t * 20, 1) * o};` : '') +
+            ` ${size}: ${t * full}px;` +
+            ` padding-${a}: ${t * padA}px; padding-${b}: ${t * padB}px;` +
+            ` margin-${a}: ${t * marA}px; margin-${b}: ${t * marB}px;` +
+            ` border-${a}-width: ${t * borA}px; border-${b}-width: ${t * borB}px;` +
+            (axis === 'y' ? ' min-height: 0;' : ' min-width: 0;')
+    };
+}

package/dist/sound/SoundSettings.svelte

@@ -0,0 +1,209 @@
+<script lang="ts">
+	/**
+	 * SoundSettings — drop-in "Sounds" section for an account/settings page.
+	 * A view over the shared sound preferences store: master on/off, volume,
+	 * per-category switches, the quiet (reduced-motion) mode and quiet hours.
+	 * Every change persists immediately (per device), so no save button.
+	 */
+	import { onDestroy } from 'svelte';
+	import Button from '../components/Button.svelte';
+	import { SOUND_CATEGORIES, type SoundCategory } from './names';
+	import {
+		getSoundPreferences,
+		type SoundPreferences,
+		type SoundPreferencesStore,
+		type SoundQuietMode
+	} from './preferences';
+	import { getSoundPlayer, type SoundId, type SoundPlayer } from './player';
+
+	interface Props {
+		/** Defaults to the app-wide store. */
+		preferences?: SoundPreferencesStore;
+		/** Player used by the preview buttons. Defaults to the app-wide player. */
+		player?: SoundPlayer;
+		/** Which category rows to show (an app without calls hides that row). */
+		categories?: SoundCategory[];
+		/** Show the quiet-hours row. */
+		showQuietHours?: boolean;
+		title?: string;
+		class?: string;
+	}
+
+	let {
+		preferences = getSoundPreferences(),
+		player,
+		categories = [...SOUND_CATEGORIES],
+		showQuietHours = true,
+		title = 'Sounds',
+		class: className = ''
+	}: Props = $props();
+
+	const CATEGORY_COPY: Record<SoundCategory, { label: string; hint: string; preview: SoundId }> = {
+		ui: { label: 'Interface', hint: 'Confirmations, errors and toggles', preview: 'confirm' },
+		notifications: { label: 'Notifications', hint: 'Messages and alerts you didn’t trigger', preview: 'notify' },
+		calls: { label: 'Calls', hint: 'Incoming call ringer — plays even in a background tab', preview: 'incoming-call' }
+	};
+
+	const QUIET_OPTIONS: { value: SoundQuietMode; label: string }[] = [
+		{ value: 'auto', label: 'When my device asks for reduced motion' },
+		{ value: 'on', label: 'Always' },
+		{ value: 'off', label: 'Never' }
+	];
+
+	let prefs = $state<SoundPreferences>(preferences.get());
+	const unsubscribe = preferences.subscribe((p) => (prefs = p));
+	onDestroy(unsubscribe);
+
+	const uid = `sound-settings-${Math.random().toString(36).slice(2, 9)}`;
+	const volumePct = $derived(Math.round(prefs.volume * 100));
+
+	// A preview is capped so a long host ringer file can't keep playing.
+	const PREVIEW_MAX_MS = 3000;
+	let previewing: { stop(): void } | null = null;
+	let previewTimer: ReturnType<typeof setTimeout> | undefined;
+	function stopPreview() {
+		clearTimeout(previewTimer);
+		previewing?.stop();
+		previewing = null;
+	}
+	function preview(name: SoundId) {
+		stopPreview();
+		previewing = (player ?? getSoundPlayer()).play(name, { preview: true, loop: false });
+		previewTimer = setTimeout(stopPreview, PREVIEW_MAX_MS);
+	}
+	onDestroy(stopPreview);
+
+	function setQuietHours(on: boolean) {
+		preferences.set({ quietHours: on ? (prefs.quietHours ?? { start: '22:00', end: '07:00' }) : null });
+	}
+</script>
+
+<fieldset class="flex flex-col gap-4 {className}">
+	<legend class="text-base-content mb-2 text-base font-semibold">{title}</legend>
+
+	<label class="flex cursor-pointer items-center justify-between gap-4">
+		<span>
+			<span class="text-base-content block text-sm font-medium">Play interface &amp; notification sounds</span>
+			<span class="text-base-content/60 block text-xs">Off by default. Calls ring unless muted below. Saved on this device only.</span>
+		</span>
+		<input
+			type="checkbox"
+			class="toggle toggle-primary"
+			checked={prefs.enabled}
+			onchange={(e) => preferences.set({ enabled: e.currentTarget.checked })}
+		/>
+	</label>
+
+	<div class="flex flex-col gap-4">
+		<div class="flex flex-col gap-1">
+			<label for="{uid}-volume" class="text-base-content flex justify-between text-sm font-medium">
+				<span>Volume</span>
+				<span class="text-base-content/60 tabular-nums">{volumePct}%</span>
+			</label>
+			<input
+				id="{uid}-volume"
+				type="range"
+				class="range range-sm range-primary"
+				min="0"
+				max="100"
+				step="5"
+				value={volumePct}
+				aria-valuetext="{volumePct} percent"
+				oninput={(e) => preferences.set({ volume: Number(e.currentTarget.value) / 100 })}
+			/>
+		</div>
+
+		<ul class="flex flex-col gap-3">
+			{#each categories as cat (cat)}
+				{@const copy = CATEGORY_COPY[cat]}
+				{@const gated = cat !== 'calls' && !prefs.enabled}
+				<li class="flex items-center justify-between gap-4" class:opacity-50={gated}>
+					<label class="flex flex-1 cursor-pointer items-center justify-between gap-4">
+						<span>
+							<span class="text-base-content block text-sm font-medium">{copy.label}</span>
+							<span class="text-base-content/60 block text-xs">{copy.hint}</span>
+						</span>
+						<input
+							type="checkbox"
+							class="toggle toggle-sm"
+							checked={prefs.categories[cat]}
+							disabled={gated}
+							onchange={(e) => preferences.setCategory(cat, e.currentTarget.checked)}
+						/>
+					</label>
+					<Button
+						variant="ghost"
+						size="sm"
+						disabled={gated || !prefs.categories[cat]}
+						aria-label="Preview {copy.label} sound"
+						onclick={() => preview(copy.preview)}
+					>
+						▷
+					</Button>
+				</li>
+			{/each}
+		</ul>
+
+		<div class="flex flex-col gap-1" class:opacity-50={!prefs.enabled}>
+			<label for="{uid}-quiet" class="text-base-content text-sm font-medium">
+				Silence interface sounds
+			</label>
+			<select
+				id="{uid}-quiet"
+				class="select select-sm w-full"
+				value={prefs.quiet}
+				disabled={!prefs.enabled}
+				onchange={(e) => preferences.set({ quiet: e.currentTarget.value as SoundQuietMode })}
+			>
+				{#each QUIET_OPTIONS as opt (opt.value)}
+					<option value={opt.value}>{opt.label}</option>
+				{/each}
+			</select>
+			<span class="text-base-content/60 text-xs">Errors still play. Notifications and calls are unaffected.</span>
+		</div>
+
+		{#if showQuietHours}
+			<div class="flex flex-col gap-2" class:opacity-50={!prefs.enabled}>
+				<label class="flex cursor-pointer items-center justify-between gap-4">
+					<span>
+						<span class="text-base-content block text-sm font-medium">Quiet hours</span>
+						<span class="text-base-content/60 block text-xs">Only calls ring inside this window.</span>
+					</span>
+					<input
+						type="checkbox"
+						class="toggle toggle-sm"
+						checked={prefs.quietHours != null}
+						disabled={!prefs.enabled}
+						onchange={(e) => setQuietHours(e.currentTarget.checked)}
+					/>
+				</label>
+				{#if prefs.quietHours}
+					<div class="flex items-center gap-2 text-sm">
+						<label for="{uid}-qs" class="text-base-content/70">From</label>
+						<input
+							id="{uid}-qs"
+							type="time"
+							class="input input-sm w-32"
+							value={prefs.quietHours.start}
+							disabled={!prefs.enabled}
+							onchange={(e) =>
+								e.currentTarget.value &&
+								preferences.set({ quietHours: { start: e.currentTarget.value, end: prefs.quietHours!.end } })}
+						/>
+						<label for="{uid}-qe" class="text-base-content/70">to</label>
+						<input
+							id="{uid}-qe"
+							type="time"
+							class="input input-sm w-32"
+							value={prefs.quietHours.end}
+							disabled={!prefs.enabled}
+							onchange={(e) =>
+								e.currentTarget.value &&
+								preferences.set({ quietHours: { start: prefs.quietHours!.start, end: e.currentTarget.value } })}
+						/>
+					</div>
+				{/if}
+			</div>
+		{/if}
+	</div>
+</fieldset>

package/dist/sound/SoundSettings.svelte.d.ts

@@ -0,0 +1,18 @@
+import { type SoundCategory } from './names';
+import { type SoundPreferencesStore } from './preferences';
+import { type SoundPlayer } from './player';
+interface Props {
+    /** Defaults to the app-wide store. */
+    preferences?: SoundPreferencesStore;
+    /** Player used by the preview buttons. Defaults to the app-wide player. */
+    player?: SoundPlayer;
+    /** Which category rows to show (an app without calls hides that row). */
+    categories?: SoundCategory[];
+    /** Show the quiet-hours row. */
+    showQuietHours?: boolean;
+    title?: string;
+    class?: string;
+}
+declare const SoundSettings: import("svelte").Component<Props, {}, "">;
+type SoundSettings = ReturnType<typeof SoundSettings>;
+export default SoundSettings;

package/dist/sound/backend.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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).
+ */
+export interface SoundVoice {
+    stop(): void;
+}
+export interface StartOptions {
+    gain: number;
+    loop: boolean;
+    /** Gap between repeats when looping; 0 = seamless. */
+    loopGapMs: number;
+    /** Called once when a non-looping voice finishes on its own. */
+    onEnded?: () => void;
+}
+export interface SoundBackend {
+    /** Decode a data URI or URL. Resolves `null` when it can't be played here. */
+    load(src: string): Promise<unknown | null>;
+    start(clip: unknown, options: StartOptions): SoundVoice | null;
+}
+export declare function createWebAudioBackend(): SoundBackend;

package/dist/sound/backend.js

@@ -0,0 +1,95 @@
+/**
+ * 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, 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.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,18 @@
+/**
+ * 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, isSoundName, soundSpecFor } 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 { decideSound, inQuietHours, readSoundEnvironment } from './policy';
+export type { SoundEnvironment, SoundRequest, SoundDecision, SoundBlockReason } from './policy';
+export { createSoundPlayer, getSoundPlayer, setSoundPlayer, playSound } 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,13 @@
+/**
+ * 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, isSoundName, soundSpecFor } from './names';
+export { DEFAULT_SOUND_PREFERENCES, SOUND_PREFS_STORAGE_KEY, LEGACY_SOUND_ENABLED_KEY, createSoundPreferences, getSoundPreferences, setSoundPreferences, normalizeSoundPreferences } from './preferences';
+export { decideSound, inQuietHours, readSoundEnvironment } from './policy';
+export { createSoundPlayer, getSoundPlayer, setSoundPlayer, playSound } from './player';
+export { createWebAudioBackend } from './backend';
+export { default as SoundSettings } from './SoundSettings.svelte';

package/dist/sound/names.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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' | '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;
+    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>>;