@joewinke/jatui 0.29.0 → 0.31.0

package/CLAUDE.md

@@ -229,7 +229,7 @@ const rec = createAudioRecorder({
 
 ### Sound (first-class sibling of motion)
 
-One preferences store every app sound goes through. UI + notification sounds are **off by default** (opt-in); the `incoming-call` ringer is **opt-out** (plays out of the box, muted via `categories.calls`). Semantic names (`confirm`, `error`, `notify`, `message`, `send`, `toggle`, `tap`, `incoming-call`, plus the booking-delight set `tick` 0.03 / `select` 0.08 / `chime` 0.12 / `attention` 0.10) map to bundled CC0 clips or a host's own file (`SOUND_CLIP_VARIANTS['error-soft']` is a gentler `error`). Policy per category: background tab, quiet hours and the quiet/reduced-motion mode silence `ui`/`notifications`; calls always ring. **Throttle:** per-name `minIntervalMs` (tick 80 ms, select 120 ms) drops — never queues — a play inside the window (`blocked: 'throttled'`); per-call `minIntervalMs` overrides. **Pitch:** `playSound('tick', { pitch: pentatonicPitch(i) })` (semitones → `playbackRate`; `playbackRate` also accepted). `tick` is the one hover sound — call it only on pointer-fine devices. **Site level:** host stamps `<html data-sound="off|subtle">` (like `data-motion`; `setSoundLevel` / `resolveSoundLevel` / `soundLevelDefaults`); `subtle` only starts UI sound on for a visitor with no saved preference — a saved preference (the panel mute) always wins, and `decideSound` is unchanged. Discipline doc: `docs/sound.md`.
+One preferences store every app sound goes through. UI + notification sounds are **off by default** (opt-in); the `incoming-call` ringer is **opt-out** (plays out of the box, muted via `categories.calls`). Semantic names (`confirm`, `error`, `notify`, `message`, `send`, `toggle`, `tap`, `incoming-call`, plus the booking-delight set `tick` 0.03 / `select` 0.08 / `chime` 0.12 / `attention` 0.10) map to bundled CC0 clips or a host's own file (`SOUND_CLIP_VARIANTS['error-soft']` is a gentler `error`). Policy per category: background tab, quiet hours and the quiet/reduced-motion mode silence `ui`/`notifications`; calls always ring. **Throttle:** per-name `minIntervalMs` (tick 80 ms, select 120 ms) drops — never queues — a play inside the window (`blocked: 'throttled'`); per-call `minIntervalMs` overrides. **Pitch:** `playSound('tick', { pitch: pentatonicPitch(i) })` (semitones → `playbackRate`; `playbackRate` also accepted). `tick` is the one hover sound — call it only on pointer-fine devices. **Site level:** host stamps `<html data-sound="off|subtle">` (like `data-motion`; `setSoundLevel` / `resolveSoundLevel` / `soundLevelDefaults`); `subtle` only starts UI sound on for a visitor with no saved preference — a saved preference (the panel mute) always wins, and `decideSound` is unchanged. **iOS unlock:** the player creates its AudioContext lazily (inside clip-decode promise chains), which iOS Safari leaves suspended forever — call `unlockSound()` from inside a user gesture (or `armSoundUnlock()` once for a one-shot first-gesture listener); custom backends implement optional `unlock()` / `unlocked` and the player delegates. Discipline doc: `docs/sound.md`.
 
 | Component | Purpose | Key Props |
 |-----------|---------|-----------|
@@ -238,10 +238,12 @@ One preferences store every app sound goes through. UI + notification sounds are
 ```typescript
 import {
   playSound,             // playSound('confirm') → SoundHandle { stop, playing, blocked } — never throws
-  getSoundPlayer,        // .register(name, src, spec?) · .play · .preload · .stopAll
+  getSoundPlayer,        // .register(name, src, spec?) · .play · .preload · .stopAll · .unlock()/.unlocked
   getSoundPreferences,   // .get · .set(patch) · .setCategory · .reset · .subscribe (localStorage 'jatui-sound-prefs', cross-tab)
   createSoundPreferences, createSoundPlayer,   // isolated instances (tests, demos)
   decideSound,           // the pure policy, for custom players
+  unlockSound,           // iOS/Safari gesture unlock — call inside a click/touchend handler
+  armSoundUnlock,        // one-shot first-gesture listener (self-removing, re-armable)
   SOUND_NAMES, SOUND_SPECS, SOUND_CATEGORIES
 } from "jatui"
 // handle.blocked: 'disabled' | 'category-muted' | 'hidden' | 'quiet-hours' | 'quiet' | 'silent'
@@ -310,6 +312,7 @@ const callbacks: AnnotationCallbacks = {
 | Component | Purpose | Key Props |
 |-----------|---------|-----------|
 | `ThemeSelector` | DaisyUI theme switcher with preview dots | `themes`, `defaultTheme`, `dropUp`, `storageKey`, `onThemeChange` |
+| `ThemeToggle` | Icon-only sun<->moon light/dark toggle with an animated morph (transform+opacity on motion tokens; instant under reduced-motion; spring flattens on `data-motion="calm"`). A pure control — flips the bindable `theme` and fires `onchange`; storage stays with the consumer. | `theme` (bindable), `lightTheme`, `darkTheme`, `onchange`, `size` |
 
 ### Keyboard Navigation
 

package/dist/components/ThemeToggle.svelte

@@ -0,0 +1,158 @@
+<script lang="ts">
+	/**
+	 * ThemeToggle — icon-only light/dark switch with an animated sun<->moon morph
+	 * (mos-p6o2d). The public-site counterpart to ThemeSelector: where a site
+	 * offers exactly two themes, a dropdown with visible "Dark mode" text is
+	 * chrome noise — this is a single icon button instead.
+	 *
+	 * The component is a CONTROL, not a theme manager: it flips the bindable
+	 * `theme` between `lightTheme` and `darkTheme` and fires `onchange`. It does
+	 * not touch localStorage, `document.documentElement` or any storage key —
+	 * persistence, pre-paint system-preference behaviour and DB theme overrides
+	 * stay with the consumer (see JST's PublicThemeToggle wrapper, which owns
+	 * the exact storage contract ThemeSelector established).
+	 *
+	 * Motion: the morph uses transform + opacity only, driven by the jatui
+	 * motion tokens (`--motion-fast` duration, spring for the settle, glide for
+	 * the cross-fade). Honours `data-motion="calm"` (tokens re-declared there —
+	 * springs flatten) and `prefers-reduced-motion` (instant swap, both via the
+	 * motion.css global floor and a component-local guard, since not every
+	 * consumer loads motion.css). Colours are token-only — no literals.
+	 */
+	let {
+		theme = $bindable('light'),
+		lightTheme = 'light',
+		darkTheme = 'dark',
+		onchange,
+		size = 'md'
+	}: {
+		/** Current theme name (bindable). Anything that is not `darkTheme` reads as light. */
+		theme?: string;
+		/** Theme name considered "light" (sun shown; the target when dark). */
+		lightTheme?: string;
+		/** Theme name considered "dark" (moon shown; the target when light). */
+		darkTheme?: string;
+		/** Fired after the toggle flips the bound theme. */
+		onchange?: (theme: string) => void;
+		/** Hit-target size — sm 40px, md 44px, lg 48px. Never below the 40px touch floor. */
+		size?: 'sm' | 'md' | 'lg';
+	} = $props();
+
+	let isDark = $derived(theme === darkTheme);
+
+	const BUTTON_SIZES = {
+		sm: 'size-10',
+		md: 'size-11',
+		lg: 'size-12'
+	} as const;
+
+	const ICON_SIZES = { sm: 18, md: 20, lg: 24 } as const;
+
+	const label = $derived(isDark ? 'Switch to light mode' : 'Switch to dark mode');
+
+	function toggle() {
+		const next = isDark ? lightTheme : darkTheme;
+		theme = next;
+		onchange?.(next);
+	}
+</script>
+
+<button
+	type="button"
+	class="jatui-theme-toggle inline-flex shrink-0 items-center justify-center rounded-full
+		text-base-content transition-colors duration-[var(--motion-instant,80ms)]
+		focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary
+		hover:bg-base-content/10 focus-visible:bg-base-content/10
+		active:bg-base-content/15 disabled:pointer-events-none disabled:opacity-50
+		{BUTTON_SIZES[size]}"
+	class:is-dark={isDark}
+	aria-label={label}
+	aria-pressed={isDark}
+	title={label}
+	onclick={toggle}
+>
+	<span
+		class="glyphs relative block"
+		style="width: {ICON_SIZES[size]}px; height: {ICON_SIZES[size]}px"
+		aria-hidden="true"
+	>
+		<!-- Sun: ring + eight rays, lucide geometry. -->
+		<svg
+			xmlns="http://www.w3.org/2000/svg"
+			viewBox="0 0 24 24"
+			fill="none"
+			stroke="currentColor"
+			stroke-width="2"
+			stroke-linecap="round"
+			stroke-linejoin="round"
+			class="glyph glyph-sun absolute inset-0"
+			width={ICON_SIZES[size]}
+			height={ICON_SIZES[size]}
+		>
+			<circle cx="12" cy="12" r="4" />
+			<path d="M12 2v2" />
+			<path d="M12 20v2" />
+			<path d="m4.93 4.93 1.41 1.41" />
+			<path d="m17.66 17.66 1.41 1.41" />
+			<path d="M2 12h2" />
+			<path d="M20 12h2" />
+			<path d="m6.34 17.66-1.41 1.41" />
+			<path d="m19.07 4.93-1.41 1.41" />
+		</svg>
+		<!-- Moon: crescent, lucide geometry. -->
+		<svg
+			xmlns="http://www.w3.org/2000/svg"
+			viewBox="0 0 24 24"
+			fill="none"
+			stroke="currentColor"
+			stroke-width="2"
+			stroke-linecap="round"
+			stroke-linejoin="round"
+			class="glyph glyph-moon absolute inset-0"
+			width={ICON_SIZES[size]}
+			height={ICON_SIZES[size]}
+		>
+			<path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z" />
+		</svg>
+	</span>
+</button>
+
+<style>
+	/*
+	 * Morph: transform + opacity ONLY (compositor-friendly, no layout thrash).
+	 * The outgoing glyph rotates away and shrinks while fading; the incoming
+	 * one rotates in. Spring carries the small-element settle; glide the fade.
+	 */
+	.glyph {
+		transition:
+			transform var(--motion-fast, 150ms) var(--motion-spring, cubic-bezier(0.34, 1.56, 0.64, 1)),
+			opacity var(--motion-fast, 150ms) var(--motion-glide, cubic-bezier(0.16, 1, 0.3, 1));
+	}
+
+	.glyph-sun {
+		opacity: 1;
+		transform: rotate(0deg) scale(1);
+	}
+
+	.glyph-moon {
+		opacity: 0;
+		transform: rotate(-90deg) scale(0.5);
+	}
+
+	.is-dark .glyph-sun {
+		opacity: 0;
+		transform: rotate(90deg) scale(0.5);
+	}
+
+	.is-dark .glyph-moon {
+		opacity: 1;
+		transform: rotate(0deg) scale(1);
+	}
+
+	/* Component-local reduced-motion guard — not every consumer loads motion.css. */
+	@media (prefers-reduced-motion: reduce) {
+		.glyph {
+			transition: none;
+		}
+	}
+</style>

package/dist/components/ThemeToggle.svelte.d.ts

@@ -0,0 +1,15 @@
+type $$ComponentProps = {
+    /** Current theme name (bindable). Anything that is not `darkTheme` reads as light. */
+    theme?: string;
+    /** Theme name considered "light" (sun shown; the target when dark). */
+    lightTheme?: string;
+    /** Theme name considered "dark" (moon shown; the target when light). */
+    darkTheme?: string;
+    /** Fired after the toggle flips the bound theme. */
+    onchange?: (theme: string) => void;
+    /** Hit-target size — sm 40px, md 44px, lg 48px. Never below the 40px touch floor. */
+    size?: 'sm' | 'md' | 'lg';
+};
+declare const ThemeToggle: import("svelte").Component<$$ComponentProps, {}, "theme">;
+type ThemeToggle = ReturnType<typeof ThemeToggle>;
+export default ThemeToggle;

package/dist/index.d.ts

@@ -93,6 +93,7 @@ export type { AudioRecordingResult } from './utils/audioRecorderCore';
 export { createAudioRecorder } from './utils/audioRecorder';
 export type { AudioRecorder, AudioRecorderCore, AudioRecorderError, AudioRecorderErrorKind, AudioRecorderFrame, AudioRecorderMode, AudioRecorderOptions, AudioRecorderPhase, AudioRecorderSnapshot } from './utils/audioRecorderCore';
 export { default as ThemeSelector } from './components/ThemeSelector.svelte';
+export { default as ThemeToggle } from './components/ThemeToggle.svelte';
 export { default as Sparkline } from './components/Sparkline.svelte';
 export { default as BurndownChart } from './components/BurndownChart.svelte';
 export { default as AvatarUpload } from './components/AvatarUpload.svelte';

package/dist/index.js

@@ -127,6 +127,7 @@ export { default as AudioRecorder } from './components/AudioRecorder.svelte';
 export { createAudioRecorder } from './utils/audioRecorder';
 // Components — from Headcount
 export { default as ThemeSelector } from './components/ThemeSelector.svelte';
+export { default as ThemeToggle } from './components/ThemeToggle.svelte';
 export { default as Sparkline } from './components/Sparkline.svelte';
 export { default as BurndownChart } from './components/BurndownChart.svelte';
 // Components — from JST

package/dist/sound/SoundSettings.svelte

@@ -68,7 +68,11 @@
 	}
 	function preview(name: SoundId) {
 		stopPreview();
-		previewing = (player ?? getSoundPlayer()).play(name, { preview: true, loop: false });
+		const p = player ?? getSoundPlayer();
+		// A preview click is a real gesture: unlock here too, so a first-ever
+		// preview on iOS actually sounds instead of resuming a dead context.
+		void p.unlock();
+		previewing = p.play(name, { preview: true, loop: false });
 		previewTimer = setTimeout(stopPreview, PREVIEW_MAX_MS);
 	}
 	onDestroy(stopPreview);

package/dist/sound/backend.d.ts

@@ -2,6 +2,11 @@
  * 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).
+ *
+ * Backends MAY implement `unlock()` / `unlocked` — the player's `unlock()`
+ * and `unlocked` delegate to them (see `sound/unlock.ts` for the host-facing
+ * helpers). A backend without them is assumed fine: it reports unlocked and
+ * the player's unlock is a no-op.
  */
 export interface SoundVoice {
     stop(): void;
@@ -20,5 +25,19 @@ 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;
+    /**
+     * Create/resume the output context from inside a user-gesture handler
+     * (click, touchend, keydown). OPTIONAL: only iOS/Safari needs it, and
+     * only for Web Audio — there the context must be created or resumed
+     * synchronously inside the gesture, or it stays suspended and every
+     * sound is silent (mos-rd6kw). `sound/unlock.ts` calls this for a host.
+     */
+    unlock?(): Promise<void>;
+    /**
+     * True when the output context is running. OPTIONAL: a backend that
+     * has neither `unlock` nor `unlocked` reports unlocked (nothing to
+     * unlock); one that unlocks should report its state honestly.
+     */
+    readonly unlocked?: boolean;
 }
 export declare function createWebAudioBackend(): SoundBackend;

package/dist/sound/backend.js

@@ -2,6 +2,11 @@
  * 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).
+ *
+ * Backends MAY implement `unlock()` / `unlocked` — the player's `unlock()`
+ * and `unlocked` delegate to them (see `sound/unlock.ts` for the host-facing
+ * helpers). A backend without them is assumed fine: it reports unlocked and
+ * the player's unlock is a no-op.
  */
 function dataUriBytes(uri) {
     const binary = atob(uri.slice(uri.indexOf(',') + 1));
@@ -12,13 +17,25 @@ function dataUriBytes(uri) {
 }
 export function createWebAudioBackend() {
     let ctx = null;
+    /**
+     * The context, memoized. It is created on the FIRST call — unlock()
+     * makes that first call happen synchronously inside a user gesture,
+     * which is the only way iOS Safari ever leaves it running (mos-rd6kw).
+     * Memoizing also means playback after an unlock reuses the unlocked
+     * context instead of lazily racing a second one.
+     */
     function context() {
         if (ctx)
             return ctx;
-        if (typeof AudioContext === 'undefined')
+        // Old WebKit only ever exposed the prefixed constructor.
+        const Ctx = typeof AudioContext === 'undefined'
+            ? globalThis
+                .webkitAudioContext
+            : AudioContext;
+        if (!Ctx)
             return null;
         try {
-            ctx = new AudioContext();
+            ctx = new Ctx();
         }
         catch {
             return null;
@@ -91,6 +108,26 @@ export function createWebAudioBackend() {
                     out.disconnect();
                 }
             };
+        },
+        /**
+         * Create and resume the context NOW — call from inside a user-gesture
+         * handler (see `sound/unlock.ts`). Everything up to and including the
+         * `resume()` call stays synchronous, which is what keeps the gesture;
+         * the await only wraps the promise. Desktop browsers permit this any
+         * time; iOS Safari is the reason it exists.
+         */
+        async unlock() {
+            try {
+                const audio = context();
+                if (audio?.state === 'suspended')
+                    await audio.resume();
+            }
+            catch {
+                /* the unlock must never break the gesture it runs in */
+            }
+        },
+        get unlocked() {
+            return ctx?.state === 'running';
         }
     };
 }

package/dist/sound/index.d.ts

@@ -17,4 +17,5 @@ export { createSoundPlayer, getSoundPlayer, setSoundPlayer, playSound, rateFor a
 export type { SoundId, SoundPlayer, SoundHandle, PlaySoundOptions, CreateSoundPlayerOptions } from './player';
 export { createWebAudioBackend } from './backend';
 export type { SoundBackend, SoundVoice, StartOptions as SoundStartOptions } from './backend';
+export { unlockSound, armSoundUnlock } from './unlock';
 export { default as SoundSettings } from './SoundSettings.svelte';

package/dist/sound/index.js

@@ -11,4 +11,7 @@ export { SOUND_LEVELS, DEFAULT_SOUND_LEVEL, SOUND_LEVEL_ATTR, isSoundLevel, pars
 export { decideSound, inQuietHours, readSoundEnvironment } from './policy';
 export { createSoundPlayer, getSoundPlayer, setSoundPlayer, playSound, rateFor as soundPlaybackRate } from './player';
 export { createWebAudioBackend } from './backend';
+// The iOS/Safari gesture unlock (mos-rd6kw): unlockSound() from inside a
+// gesture, or armSoundUnlock() once to listen for the first one.
+export { unlockSound, armSoundUnlock } from './unlock';
 export { default as SoundSettings } from './SoundSettings.svelte';

package/dist/sound/player.d.ts

@@ -50,6 +50,18 @@ 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;
+    /**
+     * Unlock audio output from inside a user-gesture handler (iOS/Safari
+     * keeps a context suspended unless the gesture created/resumed it —
+     * see `sound/unlock.ts`). Backends without an unlock concept resolve
+     * immediately. A cheap no-op once unlocked.
+     */
+    unlock(): Promise<void>;
+    /**
+     * True when the backend reports a running output context; a backend
+     * with no unlock concept always reports true. False before any unlock.
+     */
+    readonly unlocked: boolean;
     /** Decode clips ahead of time (defaults to every semantic name). */
     preload(names?: readonly SoundId[]): Promise<void>;
     stopAll(): void;

package/dist/sound/player.js

@@ -126,6 +126,20 @@ export function createSoundPlayer(options = {}) {
         async preload(names = SOUND_NAMES) {
             await Promise.all(names.map((n) => clipFor(n)));
         },
+        // The gesture unlock (mos-rd6kw): delegate to the backend — the
+        // default backend has the iOS-safe synchronous create+resume; a fake
+        // or a legacy backend without one resolves silently and reports
+        // unlocked, so a host that arms the unlock never has to branch.
+        async unlock() {
+            await audio().unlock?.();
+        },
+        get unlocked() {
+            // Reading this never creates the backend: nothing exists to be
+            // unlocked until something asked to play or unlock.
+            if (!backend)
+                return false;
+            return backend.unlocked ?? !backend.unlock;
+        },
         stopAll() {
             for (const a of [...active])
                 a.handle.stop();

package/dist/sound/unlock.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The iOS/Safari audio unlock (mos-rd6kw, found in MOS's booking panel).
+ *
+ * Safari keeps an AudioContext suspended unless it was created or resumed
+ * inside a user gesture's synchronous call stack. The player creates its
+ * context lazily — inside clip-loading promise chains — which is never a
+ * gesture, so on an iPhone every sound stays silent no matter how many taps
+ * happened before it. The fix is one call from inside the gesture:
+ *
+ *   button.addEventListener('click', () => void unlockSound());
+ *
+ * or, once at startup, the auto-installed one-shot listener:
+ *
+ *   armSoundUnlock();   // first pointerup / touchend / click / keydown
+ *
+ * Unlock creates AND resumes the context synchronously (the constructor and
+ * the `resume()` call land inside the gesture; only the promise is awaited),
+ * so the later plays through the same player are allowed to sound. When a
+ * cue must be heard in the gesture itself, play it right after unlock in
+ * that same handler. iOS can re-suspend the context after the tab is
+ * backgrounded — re-arm (`armed` is cleared once the listener fires) or call
+ * `unlockSound()` again from the gesture that follows. And a "silent" phone
+ * can still be the hardware ring/silent switch, which mutes Web Audio on
+ * iOS no matter how the context was unlocked.
+ */
+/**
+ * Create/resume the shared player's audio context. Call from inside a user
+ * gesture. Resolves even where audio is unsupported (no context here) and
+ * is a cheap no-op once the context is running.
+ */
+export declare function unlockSound(): Promise<void>;
+/**
+ * Install a ONE-SHOT unlock listener for the first pointer/key gesture on
+ * `target` (default: the document; pass an explicit target only where the
+ * gesture scope is narrower). Handy where no single call site owns "the
+ * first gesture" — a public page, a settings screen. Idempotent while
+ * armed: a second call before the first gesture is a no-op; the listeners
+ * remove themselves the first time any of the gestures fires, and calling
+ * this again re-arms (iOS can re-suspend the context after the tab is
+ * backgrounded — arm again on `visibilitychange`).
+ */
+export declare function armSoundUnlock(target?: Document | HTMLElement): void;

package/dist/sound/unlock.js

@@ -0,0 +1,63 @@
+/**
+ * The iOS/Safari audio unlock (mos-rd6kw, found in MOS's booking panel).
+ *
+ * Safari keeps an AudioContext suspended unless it was created or resumed
+ * inside a user gesture's synchronous call stack. The player creates its
+ * context lazily — inside clip-loading promise chains — which is never a
+ * gesture, so on an iPhone every sound stays silent no matter how many taps
+ * happened before it. The fix is one call from inside the gesture:
+ *
+ *   button.addEventListener('click', () => void unlockSound());
+ *
+ * or, once at startup, the auto-installed one-shot listener:
+ *
+ *   armSoundUnlock();   // first pointerup / touchend / click / keydown
+ *
+ * Unlock creates AND resumes the context synchronously (the constructor and
+ * the `resume()` call land inside the gesture; only the promise is awaited),
+ * so the later plays through the same player are allowed to sound. When a
+ * cue must be heard in the gesture itself, play it right after unlock in
+ * that same handler. iOS can re-suspend the context after the tab is
+ * backgrounded — re-arm (`armed` is cleared once the listener fires) or call
+ * `unlockSound()` again from the gesture that follows. And a "silent" phone
+ * can still be the hardware ring/silent switch, which mutes Web Audio on
+ * iOS no matter how the context was unlocked.
+ */
+import { getSoundPlayer } from './player';
+/**
+ * Create/resume the shared player's audio context. Call from inside a user
+ * gesture. Resolves even where audio is unsupported (no context here) and
+ * is a cheap no-op once the context is running.
+ */
+export async function unlockSound() {
+    await getSoundPlayer().unlock();
+}
+const GESTURES = ['pointerup', 'touchend', 'click', 'keydown'];
+/** The target `armSoundUnlock` installed its one-shot listener on, if any. */
+let armed = null;
+/**
+ * Install a ONE-SHOT unlock listener for the first pointer/key gesture on
+ * `target` (default: the document; pass an explicit target only where the
+ * gesture scope is narrower). Handy where no single call site owns "the
+ * first gesture" — a public page, a settings screen. Idempotent while
+ * armed: a second call before the first gesture is a no-op; the listeners
+ * remove themselves the first time any of the gestures fires, and calling
+ * this again re-arms (iOS can re-suspend the context after the tab is
+ * backgrounded — arm again on `visibilitychange`).
+ */
+export function armSoundUnlock(target) {
+    if (armed)
+        return;
+    const t = target ?? (typeof document === 'undefined' ? undefined : document);
+    if (!t)
+        return;
+    armed = t;
+    const fire = () => {
+        armed = null;
+        for (const g of GESTURES)
+            t.removeEventListener(g, fire);
+        void unlockSound();
+    };
+    for (const g of GESTURES)
+        t.addEventListener(g, fire, { passive: true });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",