@tristan2828/ui-foundation 4.43.0 → 4.44.0

package/conventions/docs/timed-screens.md

@@ -6,11 +6,11 @@
 - [The view](#the-view) · lines 36–109
   - [The dark stage](#the-dark-stage) · lines 73–109
 - [The clock](#the-clock) · lines 111–141
-- [Sound](#sound) · lines 143–190
-- [Background tabs](#background-tabs) · lines 192–246
-  - [Interruptions](#interruptions) · lines 226–246
-- [Motion](#motion) · lines 248–252
-- [Testing a timed screen in Playwright](#testing-a-timed-screen-in-playwright) · lines 254–408
+- [Sound](#sound) · lines 143–193
+- [Background tabs](#background-tabs) · lines 195–249
+  - [Interruptions](#interruptions) · lines 229–249
+- [Motion](#motion) · lines 251–255
+- [Testing a timed screen in Playwright](#testing-a-timed-screen-in-playwright) · lines 257–411
 
 <!-- /index -->
 
@@ -176,7 +176,10 @@ Browsers block sound until the person has clicked or tapped. So:
   another app's music. It returns `{ pause(), stop() }`: `pause()` shows
   Play (without calling `onToggle`), `stop()` ends it (on done, on leaving);
   to start again after `pause()`, call `keepAudioAlive` again from a click.
-  Only one runs at a time.
+  Only one runs at a time. Where Safari has an audio session
+  (`navigator.audioSession`) it's set to `"playback"` while the track
+  runs, so the ringer switch doesn't mute the cues either, and put back on
+  `stop()`.
 - Every one of them is a no-op where the browser can't make the sound, so
   none needs a check around it.
 - **Mute** is the app's: `const [muted, setMuted] = useMuted('my-app:routine:muted')`,

package/dist/lib/keep-audio-alive.d.ts

@@ -22,6 +22,10 @@ export type KeepAudioAliveEnvironment = {
     MediaMetadata?: new (init?: MediaMetadataInit) => MediaMetadata;
     createObjectURL?: (blob: Blob) => string;
     revokeObjectURL?: (url: string) => void;
+    /** Safari's `navigator.audioSession`, where it has one. */
+    audioSession?: {
+        type: string;
+    };
 };
 /** One second of silent 8-bit mono audio as a WAV file. */
 export declare function silentWav(): Uint8Array;
@@ -30,6 +34,8 @@ export declare function createKeepAudioAlive(env: KeepAudioAliveEnvironment): ({
  * Plays a silent looped track so iOS keeps the page's sound going with the
  * phone locked, with `title` and Pause and Play on the lock screen. Call it
  * from the click that starts the run, behind a setting that's off by default:
- * it pauses other apps' music. A no-op where the browser can't play audio.
+ * it pauses other apps' music. Where Safari has an audio session it's set to
+ * "playback" meanwhile, so the ringer switch doesn't mute the cues. A no-op
+ * where the browser can't play audio.
  */
 export declare const keepAudioAlive: (options: KeepAudioAliveOptions) => KeepAudioAlive;

package/dist/lib/keep-audio-alive.js

@@ -1,9 +1,12 @@
-// Keeps a page's audio going with the phone locked (#217). iOS pauses a
+// Keeps a page's audio going with the phone locked (#217, #261). iOS pauses a
 // page's sound on the lock screen unless the page is playing media, so
 // keepAudioAlive() plays a silent looped track, which also puts the page's
 // title and a Pause and Play on the lock screen (the Media Session). It's
 // opt-in and off by default: it takes the device's audio session, which
 // pauses another app's music (docs/foundation/timed-screens.md "Sound").
+// Where Safari has an audio session (navigator.audioSession, iOS 17+) it's
+// set to "playback" while the track runs, so the ringer switch doesn't mute
+// the page's cues either, and put back on stop().
 //
 // The track is a few bytes of silence made here, so there is no file to
 // ship. createKeepAudioAlive takes the browser's APIs, so the rules are
@@ -55,6 +58,18 @@ export function createKeepAudioAlive(env) {
         }
         audio.loop = true;
         const session = env.mediaSession;
+        const audioSession = env.audioSession;
+        let typeBefore = null;
+        try {
+            if (audioSession) {
+                typeBefore = audioSession.type;
+                audioSession.type = 'playback';
+            }
+        }
+        catch {
+            // A type this Safari doesn't take: the silent track alone.
+            typeBefore = null;
+        }
         const play = () => {
             // Refused without a click: the lock screen then shows nothing to keep.
             Promise.resolve(audio.play()).catch(() => { });
@@ -102,6 +117,14 @@ export function createKeepAudioAlive(env) {
                 audio.removeAttribute('src');
                 audio.load();
                 env.revokeObjectURL?.(url);
+                if (audioSession && typeBefore !== null) {
+                    try {
+                        audioSession.type = typeBefore;
+                    }
+                    catch {
+                        // Left as playback: harmless once the track has stopped.
+                    }
+                }
                 if (session) {
                     handle('play', null);
                     handle('pause', null);
@@ -119,7 +142,9 @@ let shared = null;
  * Plays a silent looped track so iOS keeps the page's sound going with the
  * phone locked, with `title` and Pause and Play on the lock screen. Call it
  * from the click that starts the run, behind a setting that's off by default:
- * it pauses other apps' music. A no-op where the browser can't play audio.
+ * it pauses other apps' music. Where Safari has an audio session it's set to
+ * "playback" meanwhile, so the ringer switch doesn't mute the cues. A no-op
+ * where the browser can't play audio.
  */
 export const keepAudioAlive = (options) => {
     if (!shared) {
@@ -130,6 +155,7 @@ export const keepAudioAlive = (options) => {
             MediaMetadata: hasWindow ? window.MediaMetadata : undefined,
             createObjectURL: typeof URL !== 'undefined' ? (blob) => URL.createObjectURL(blob) : undefined,
             revokeObjectURL: typeof URL !== 'undefined' ? (url) => URL.revokeObjectURL(url) : undefined,
+            audioSession: typeof navigator !== 'undefined' ? navigator.audioSession : undefined,
         });
     }
     return shared(options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.43.0",
+  "version": "4.44.0",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {