@joewinke/jatui 0.30.0 → 0.31.1

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'

package/dist/components/ContextMenu.svelte

@@ -1,3 +1,8 @@
+<script lang="ts" module>
+	// Per-instance id source for the menu panel (see `menuId` below).
+	let menuSeq = 0;
+</script>
+
 <script lang="ts">
 	/**
 	 * ContextMenu Component
@@ -93,6 +98,21 @@
 	let submenuX = $state(0);
 	let submenuY = $state(0);
 
+	/**
+	 * Unique id for THIS menu panel. The roving-focus queries below target
+	 * `[data-context-menu="…"] > button` instead of `:scope > button` because
+	 * jsdom's selector engine (nwsapi) expands `:scope` to `tag + .classList[0]`
+	 * — and this panel's first class is the Tailwind arbitrary value
+	 * `min-w-[200px]`, which nwsapi then cannot parse (`[200px]` looks like an
+	 * attribute selector to it). Real browsers are fine either way; avoiding
+	 * `:scope` keeps every jsdom test suite free of the resulting unhandled
+	 * errors. The unique id preserves the direct-children semantics of
+	 * `:scope >`: a nested submenu panel is rendered INSIDE this panel and
+	 * carries its own id, so it can never leak its items into this level's
+	 * query.
+	 */
+	const menuId = `cm-${++menuSeq}`;
+
 	function closeSubmenu() {
 		if (submenuIndex === null) return;
 		submenuIndex = null;
@@ -179,9 +199,13 @@
 	function menuItemButtons(): HTMLButtonElement[] {
 		if (!menuEl) return [];
 		// Only DIRECT children — don't include nested submenu items when nav-ing
-		// this level.
+		// this level. The menu panel carries a unique data-context-menu id, so
+		// this can't be matched by a nested panel (see `menuId` for why this
+		// isn't a `:scope >` selector — nwsapi/jsdom).
 		return Array.from(
-			menuEl.querySelectorAll(':scope > button[role="menuitem"]:not(:disabled)')
+			menuEl.querySelectorAll(
+				`[data-context-menu="${menuId}"] > button[role="menuitem"]:not(:disabled)`
+			)
 		);
 	}
 
@@ -190,11 +214,24 @@
 		const activeBtn = document.activeElement as HTMLElement | null;
 		if (!activeBtn) return -1;
 		const buttons = Array.from(
-			menuEl.querySelectorAll(':scope > button[role="menuitem"]')
+			menuEl.querySelectorAll(`[data-context-menu="${menuId}"] > button[role="menuitem"]`)
 		) as HTMLButtonElement[];
 		return buttons.indexOf(activeBtn as HTMLButtonElement);
 	}
 
+	// First focusable item of the OPEN nested submenu. The submenu's panel is
+	// a direct child of this menu's panel (nested in-DOM so click-outside
+	// treats it as inside — see the SelfContextMenu render below); finding it
+	// by traversal instead of a `:scope >` selector keeps nwsapi (jsdom) out
+	// of the picture entirely.
+	function firstSubmenuItem(): HTMLButtonElement | null {
+		if (!menuEl) return null;
+		const panel = Array.from(menuEl.children).find(
+			(c) => c.getAttribute('role') === 'menu'
+		);
+		return (panel?.querySelector('button[role="menuitem"]:not(:disabled)') ?? null) as HTMLButtonElement | null;
+	}
+
 	function isEditableTarget(target: EventTarget | null): boolean {
 		const el = target as HTMLElement | null;
 		if (!el) return false;
@@ -230,12 +267,8 @@
 				// ArrowRight is an explicit "enter the submenu" gesture — focus
 				// its first item. Hover/onfocus open the submenu without moving
 				// focus (see autoFocus prop on the recursive instance).
-				const el = menuEl;
 				requestAnimationFrame(() => {
-					const first = el?.querySelector(
-						':scope > [role="menu"] > button[role="menuitem"]:not(:disabled)'
-					) as HTMLButtonElement | null;
-					first?.focus();
+					firstSubmenuItem()?.focus();
 				});
 			}
 			return;
@@ -274,12 +307,8 @@
 				if (item.submenu?.length) {
 					const buttons = menuItemButtons();
 					openSubmenuAt(buttons[idx], idx);
-					const el = menuEl;
 					requestAnimationFrame(() => {
-						const first = el?.querySelector(
-							':scope > [role="menu"] > button[role="menuitem"]:not(:disabled)'
-						) as HTMLButtonElement | null;
-						first?.focus();
+						firstSubmenuItem()?.focus();
 					});
 				} else {
 					handleItemClick(item, idx, e);
@@ -305,12 +334,8 @@
 	// by the time this effect runs, so focus-return-on-close still works.
 	$effect(() => {
 		if (open && menuEl && autoFocus) {
-			const el = menuEl;
 			requestAnimationFrame(() => {
-				const buttons = Array.from(
-					el.querySelectorAll(':scope > button[role="menuitem"]:not(:disabled)')
-				) as HTMLButtonElement[];
-				buttons[0]?.focus();
+				menuItemButtons()[0]?.focus();
 			});
 		}
 	});
@@ -326,6 +351,7 @@
 		bind:this={menuEl}
 		role="menu"
 		tabindex="-1"
+		data-context-menu={menuId}
 		class="min-w-[200px] bg-base-200 border border-base-300 rounded-md py-1 {className}"
 		style="z-index: {zIndex};"
 		use:floating={{ anchor, placement: 'bottom-start', flip: true, shift: true, offset: 2, onDismiss: close }}

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.30.0",
+  "version": "0.31.1",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",