@tristan2828/ui-foundation 4.29.3 → 4.30.0

package/conventions/docs/timed-screens.md

@@ -113,6 +113,17 @@ Browsers block sound until the person has clicked or tapped. So:
   session: `const [vibrates] = useState(canVibrate)`. Show the toggle (a
   pressed button named "Vibrate", like Mute) only when `vibrates` is
   true, and check the setting before each `vibrate()` call.
+- **`keepAudioAlive({ title, onToggle? })`** keeps the sound going with the
+  phone locked. iOS pauses a page's audio on the lock screen unless the
+  page is playing media, so this plays a silent looped track and shows
+  `title` with Pause and Play on the lock screen; `onToggle(playing)` is
+  called when the person presses them, to pause or resume the run. Call it
+  from the click that starts the run, and keep it **behind a setting that
+  is off by default**: it takes the device's audio session, which pauses
+  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.
 - 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')`,
@@ -159,6 +170,28 @@ phase ends. Web Audio's own clock keeps time, so:
   Safari may suspend audio in a background tab altogether; nothing in a
   web page gets round that.
 
+### Interruptions
+
+On iOS the audio clock **stops** while the context is interrupted: speech
+speaking, a notification, a call, the lock screen. Booked strikes after
+that are silent, or come late by as long as the clock stood still. The
+package resumes the context as soon as it stops (and again when the page is
+visible, and on the next `unlockAudio()`), but only the screen knows where
+its run is now, so it rebooks:
+
+- **`onCuesRecovered(callback)`** calls back when the audio runs again
+  after stopping, and returns the unsubscribe. By then every booked strike
+  has been taken back, since each would have struck late, so the callback
+  books again from the run's position, the same way as when counting
+  starts. Subscribe in an effect and return the unsubscribe from its
+  cleanup. The context's first run, after the start click, isn't a
+  recovery.
+- **`cuesInSync()`** is false when the audio clock has drifted from
+  `Date.now()` by more than 250 ms since the bookings were made, or the
+  audio is stopped. It's true when nothing is booked. Check it on a tick,
+  for where no recovery was announced: when it's false, `cancelCues()` and
+  book again.
+
 ## Motion
 
 `usePrefersReducedMotion()` is true while the person's system asks for
@@ -218,9 +251,17 @@ test.beforeEach(async ({ page }) => {
     Object.defineProperty(document, 'visibilityState', { get: () => visibility })
     Object.defineProperty(document, 'hidden', { get: () => visibility === 'hidden' })
     const booked: { pitch: number; at: number; cancelled: boolean }[] = []
+    const contexts: RecordingAudioContext[] = []
     class RecordingAudioContext {
       state = 'running'; currentTime = 0; destination = {}
-      resume = async () => {}
+      listeners: (() => void)[] = []
+      addEventListener = (_type: string, listener: () => void) => void this.listeners.push(listener)
+      resume = async () => this.change('running')
+      change(state: string) {
+        this.state = state
+        this.listeners.forEach((listener) => listener())
+      }
+      constructor() { contexts.push(this) }
       last = { pitch: 0, at: 0, cancelled: false }
       createOscillator() {
         const cue = (this.last = { pitch: 0, at: 0, cancelled: false })
@@ -243,6 +284,7 @@ test.beforeEach(async ({ page }) => {
     Object.assign(window, {
       AudioContext: RecordingAudioContext,
       __booked: booked,
+      __interrupt: () => contexts.forEach((context) => context.change('interrupted')),
       __hide() {
         visibility = 'hidden'
         window.requestAnimationFrame = () => 0   // a hidden tab draws no frames
@@ -268,6 +310,11 @@ test('the end is booked ahead, and the title counts down while hidden', async ({
 Pause, Skip and Back are asserted the same way: the earlier booking's
 `cancelled` turns true and a new one appears at the new time.
 
+An interruption is the same again: `__interrupt()` stops the stand-in
+context, which the package resumes. Expect the earlier booking's
+`cancelled` to turn true and a new one to appear from the run's position,
+the screen's `onCuesRecovered` callback having rebooked.
+
 **An open-ended count-up: pause the fake clock.** After
 `clock.install()` the fake clock still moves in real time between
 steps, so every reading picks up however long the machine took since the

package/dist/index.d.ts

@@ -58,4 +58,5 @@ export { usePrefersReducedMotion } from './hooks/use-prefers-reduced-motion.js';
 export { useMuted } from './hooks/use-muted.js';
 export { createPushController, usePushPermission, type PushController, type PushControllerOptions, type PushEnvironment, type PushPermission, type PushStatus, } from './hooks/use-push-permission.js';
 export { cn } from './lib/utils.js';
-export { canVibrate, cancelCues, chime, hush, say, sequence, unlockAudio, vibrate, type ChimeOptions, type Cue, type CueTime, type SayOptions, type SequenceOptions, } from './lib/audio-cues.js';
+export { canVibrate, cancelCues, chime, cuesInSync, hush, onCuesRecovered, say, sequence, unlockAudio, vibrate, type ChimeOptions, type Cue, type CueTime, type SayOptions, type SequenceOptions, } from './lib/audio-cues.js';
+export { keepAudioAlive, type KeepAudioAlive, type KeepAudioAliveOptions, } from './lib/keep-audio-alive.js';

package/dist/index.js

@@ -63,4 +63,5 @@ export { useMuted } from './hooks/use-muted.js';
 export { createPushController, usePushPermission, } from './hooks/use-push-permission.js';
 // Utilities
 export { cn } from './lib/utils.js';
-export { canVibrate, cancelCues, chime, hush, say, sequence, unlockAudio, vibrate, } from './lib/audio-cues.js';
+export { canVibrate, cancelCues, chime, cuesInSync, hush, onCuesRecovered, say, sequence, unlockAudio, vibrate, } from './lib/audio-cues.js';
+export { keepAudioAlive, } from './lib/keep-audio-alive.js';

package/dist/lib/audio-cues.d.ts

@@ -38,6 +38,8 @@ export type AudioCuesEnvironment = {
     vibrate?: (pattern: number | number[]) => boolean;
     /** The clock `at` is read on (default `Date.now`). */
     now?: () => number;
+    /** The page, for noticing it's visible again after the audio stopped. */
+    document?: Pick<Document, 'addEventListener' | 'visibilityState'>;
 };
 export type AudioCues = {
     /** Call from the click or tap that starts a session; sound is allowed from then on. */
@@ -47,6 +49,21 @@ export type AudioCues = {
     sequence: (chimes: ChimeOptions[], options?: SequenceOptions) => Cue;
     /** Takes back every booked strike that hasn't sounded yet. */
     cancelCues: () => void;
+    /**
+     * Calls `callback` when the audio runs again after something stopped it (a
+     * call, a notification, speech, the lock screen on iOS). The package has
+     * already taken back every booked strike by then, since they would strike
+     * late, so the callback books again from where the run is now. Returns the
+     * unsubscribe.
+     */
+    onCuesRecovered: (callback: () => void) => () => void;
+    /**
+     * False when the audio clock has drifted from `Date.now()` by more than
+     * 250 ms since the bookings were made, or the audio is stopped: rebook
+     * (`cancelCues()`, then book again). True when nothing is booked. Check it
+     * on a tick, for where no recovery was announced. `now` is for tests.
+     */
+    cuesInSync: (now?: number) => boolean;
     /** Speaks `text`, cutting off any line still being spoken. */
     say: (text: string, options?: SayOptions) => void;
     /** Stops whatever is being spoken. */
@@ -73,6 +90,14 @@ export declare const chime: AudioCues['chime'];
 export declare const sequence: AudioCues['sequence'];
 /** Takes back every booked chime that hasn't sounded yet: on pause, skip, back or leaving. */
 export declare const cancelCues: AudioCues['cancelCues'];
+/**
+ * Calls back when the audio runs again after an interruption, with every
+ * booked chime already taken back: book again from where the run is now.
+ * Returns the unsubscribe (call it in an effect's cleanup).
+ */
+export declare const onCuesRecovered: AudioCues['onCuesRecovered'];
+/** False when booked chimes have drifted from `Date.now()` (or the audio is stopped): rebook. */
+export declare const cuesInSync: AudioCues['cuesInSync'];
 /** Speaks a line, cutting off the one before. A no-op without speech synthesis. */
 export declare const say: AudioCues['say'];
 /** Stops whatever is being spoken. */

package/dist/lib/audio-cues.js

@@ -14,12 +14,21 @@
 // booked strike that hasn't sounded yet (on pause, skip or leaving), so a
 // screen rebooks from its new position.
 //
+// On iOS the audio clock stops whenever the context is interrupted (speech
+// speaking, a call, the lock screen) and booked strikes go silent or late.
+// The context is resumed as soon as it stops, and once it runs again every
+// booking is taken back and onCuesRecovered() callbacks fire, so the screen
+// rebooks from where its run is now (#217). cuesInSync() catches the case
+// where no statechange came, by comparing the audio clock with Date.now().
+//
 // createAudioCues takes the browser's APIs, so the rules are unit tested
 // against fakes (tests/audio-cues.test.ts); the functions exported below
 // are one shared instance over the real ones.
 const ATTACK = 0.015;
 // An exponential ramp can't reach zero, so a chime starts and ends here.
 const SILENT = 0.0001;
+// How far the audio clock may drift from Date.now() before cuesInSync() says so.
+const SYNC_MARGIN = 250;
 const NO_CUE = { cancel: () => { } };
 export function createAudioCues(env) {
     const now = env.now ?? Date.now;
@@ -29,6 +38,15 @@ export function createAudioCues(env) {
     // A resume asked for from a click: the context is still "suspended" for
     // a moment, and a chime from that same click should still play.
     let resuming = false;
+    // Whether the context has run, and whether it has stopped since: a context
+    // that never ran is just waiting for the click.
+    let everRan = false;
+    let stopped = false;
+    let watchingPage = false;
+    const recovered = new Set();
+    // The audio clock against Date.now() when the first of the current bookings
+    // was made, for cuesInSync().
+    let anchor = null;
     const playable = () => context !== null && (context.state === 'running' || resuming);
     const strike = (ctx, { pitch = 660, volume = 0.25, duration = 1200 }, delay) => {
         const start = ctx.currentTime + Math.max(delay, 0) / 1000;
@@ -48,15 +66,18 @@ export function createAudioCues(env) {
         for (const old of booked)
             if (old.end < ctx.currentTime)
                 booked.delete(old);
+        if (booked.size === 0)
+            anchor = { audio: ctx.currentTime, wall: now() };
         booked.add(booking);
         oscillator.onended = () => booked.delete(booking);
         return booking;
     };
-    // Silences a strike that hasn't sounded yet: one already sounding rings out.
-    const unbook = (ctx, booking) => {
+    // Silences a strike that hasn't sounded yet: one already sounding rings out,
+    // unless `force`, for a clock that stood still (what was sounding is long over).
+    const unbook = (ctx, booking, force = false) => {
         if (!booked.has(booking))
             return;
-        if (booking.start <= ctx.currentTime)
+        if (!force && booking.start <= ctx.currentTime)
             return;
         booked.delete(booking);
         try {
@@ -71,14 +92,72 @@ export function createAudioCues(env) {
         cancel: () => strikes.forEach((booking) => unbook(ctx, booking)),
     });
     const delayUntil = (at) => (at === undefined ? 0 : at - now());
+    const resume = (ctx) => {
+        try {
+            Promise.resolve(ctx.resume()).catch(() => { });
+        }
+        catch {
+            // Not allowed yet: the next click or return to the page tries again.
+        }
+    };
+    // Safari's own "interrupted" isn't in the DOM types, hence the string.
+    const stoppedState = (state) => state !== 'running' && state !== 'closed';
+    // Called on every statechange, on the page becoming visible again and
+    // after unlockAudio()'s resume: notices the audio stopping (and resumes
+    // it) and running again (and says so).
+    const check = () => {
+        const ctx = context;
+        if (!ctx)
+            return;
+        if (ctx.state === 'running') {
+            everRan = true;
+            if (!stopped)
+                return;
+            stopped = false;
+            for (const booking of [...booked])
+                unbook(ctx, booking, true);
+            anchor = null;
+            for (const callback of [...recovered]) {
+                try {
+                    callback();
+                }
+                catch {
+                    // One screen's callback failing mustn't keep the others from rebooking.
+                }
+            }
+        }
+        else if (everRan && stoppedState(ctx.state)) {
+            stopped = true;
+            resume(ctx);
+        }
+    };
+    const watch = (ctx) => {
+        ctx.addEventListener?.('statechange', check);
+        const page = env.document;
+        if (page && !watchingPage) {
+            watchingPage = true;
+            page.addEventListener('visibilitychange', () => {
+                if (page.visibilityState === 'visible')
+                    check();
+            });
+        }
+    };
     return {
         unlockAudio() {
             if (env.AudioContext) {
                 try {
-                    context ??= new env.AudioContext();
+                    if (!context) {
+                        context = new env.AudioContext();
+                        watch(context);
+                    }
+                    check();
                     if (context.state !== 'running' && context.state !== 'closed') {
                         resuming = true;
-                        context.resume().then(() => (resuming = false), () => (resuming = false));
+                        const done = () => {
+                            resuming = false;
+                            check();
+                        };
+                        context.resume().then(done, done);
                     }
                 }
                 catch {
@@ -117,6 +196,18 @@ export function createAudioCues(env) {
             for (const booking of [...booked])
                 unbook(ctx, booking);
         },
+        onCuesRecovered(callback) {
+            recovered.add(callback);
+            return () => void recovered.delete(callback);
+        },
+        cuesInSync(at = now()) {
+            if (!context || !anchor || booked.size === 0)
+                return true;
+            if (stopped)
+                return false;
+            const audioElapsed = (context.currentTime - anchor.audio) * 1000;
+            return Math.abs(audioElapsed - (at - anchor.wall)) <= SYNC_MARGIN;
+        },
         say(text, { lang, rate, volume } = {}) {
             if (!env.speechSynthesis || !env.SpeechSynthesisUtterance)
                 return;
@@ -171,6 +262,7 @@ function browserCues() {
         AudioContext: win?.AudioContext ?? win?.webkitAudioContext,
         speechSynthesis: win?.speechSynthesis,
         SpeechSynthesisUtterance: win?.SpeechSynthesisUtterance,
+        document: typeof document === 'undefined' ? undefined : document,
         vibrate: canVibrate() ? (pattern) => navigator.vibrate(pattern) : undefined,
     });
     return shared;
@@ -186,6 +278,14 @@ export const chime = (options) => browserCues().chime(options);
 export const sequence = (chimes, options) => browserCues().sequence(chimes, options);
 /** Takes back every booked chime that hasn't sounded yet: on pause, skip, back or leaving. */
 export const cancelCues = () => browserCues().cancelCues();
+/**
+ * Calls back when the audio runs again after an interruption, with every
+ * booked chime already taken back: book again from where the run is now.
+ * Returns the unsubscribe (call it in an effect's cleanup).
+ */
+export const onCuesRecovered = (callback) => browserCues().onCuesRecovered(callback);
+/** False when booked chimes have drifted from `Date.now()` (or the audio is stopped): rebook. */
+export const cuesInSync = (now) => browserCues().cuesInSync(now);
 /** Speaks a line, cutting off the one before. A no-op without speech synthesis. */
 export const say = (text, options) => browserCues().say(text, options);
 /** Stops whatever is being spoken. */

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

@@ -0,0 +1,35 @@
+export type KeepAudioAliveOptions = {
+    /** Shown on the lock screen and in the control centre. */
+    title: string;
+    /**
+     * Called when the person presses Pause or Play on the lock screen or in the
+     * control centre, with whether it's now playing: pause or resume the run.
+     */
+    onToggle?: (playing: boolean) => void;
+};
+export type KeepAudioAlive = {
+    /** Pauses the track and shows Play; `onToggle` isn't called. Call keepAudioAlive() from a click to start again. */
+    pause: () => void;
+    /** Ends it and takes the title off the lock screen. */
+    stop: () => void;
+};
+export type KeepAudioAliveEnvironment = {
+    Audio?: new (src?: string) => Pick<HTMLAudioElement, 'loop' | 'src' | 'play' | 'pause' | 'removeAttribute' | 'load'>;
+    mediaSession?: Pick<MediaSession, 'setActionHandler'> & {
+        metadata: MediaMetadata | null;
+        playbackState: MediaSessionPlaybackState;
+    };
+    MediaMetadata?: new (init?: MediaMetadataInit) => MediaMetadata;
+    createObjectURL?: (blob: Blob) => string;
+    revokeObjectURL?: (url: string) => void;
+};
+/** One second of silent 8-bit mono audio as a WAV file. */
+export declare function silentWav(): Uint8Array;
+export declare function createKeepAudioAlive(env: KeepAudioAliveEnvironment): ({ title, onToggle }: KeepAudioAliveOptions) => KeepAudioAlive;
+/**
+ * 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.
+ */
+export declare const keepAudioAlive: (options: KeepAudioAliveOptions) => KeepAudioAlive;

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

@@ -0,0 +1,136 @@
+// Keeps a page's audio going with the phone locked (#217). 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").
+//
+// 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
+// unit tested against fakes (tests/keep-audio-alive.test.ts); the function
+// exported below is one shared instance over the real ones.
+const SAMPLE_RATE = 8000;
+const SECONDS = 1;
+/** One second of silent 8-bit mono audio as a WAV file. */
+export function silentWav() {
+    const samples = SAMPLE_RATE * SECONDS;
+    const bytes = new Uint8Array(44 + samples);
+    const view = new DataView(bytes.buffer);
+    const text = (offset, value) => {
+        for (let i = 0; i < value.length; i++)
+            bytes[offset + i] = value.charCodeAt(i);
+    };
+    text(0, 'RIFF');
+    view.setUint32(4, 36 + samples, true);
+    text(8, 'WAVE');
+    text(12, 'fmt ');
+    view.setUint32(16, 16, true);
+    view.setUint16(20, 1, true); // PCM
+    view.setUint16(22, 1, true); // mono
+    view.setUint32(24, SAMPLE_RATE, true);
+    view.setUint32(28, SAMPLE_RATE, true); // bytes per second
+    view.setUint16(32, 1, true); // bytes per frame
+    view.setUint16(34, 8, true); // bits per sample
+    text(36, 'data');
+    view.setUint32(40, samples, true);
+    // 8-bit PCM is unsigned: silence is the midpoint.
+    bytes.fill(128, 44);
+    return bytes;
+}
+const NO_KEEP_ALIVE = { pause: () => { }, stop: () => { } };
+export function createKeepAudioAlive(env) {
+    let active = null;
+    return function keepAudioAlive({ title, onToggle }) {
+        active?.stop();
+        if (!env.Audio || !env.createObjectURL)
+            return NO_KEEP_ALIVE;
+        let url;
+        let audio;
+        try {
+            url = env.createObjectURL(new Blob([silentWav()], { type: 'audio/wav' }));
+            audio = new env.Audio(url);
+        }
+        catch {
+            return NO_KEEP_ALIVE;
+        }
+        audio.loop = true;
+        const session = env.mediaSession;
+        const play = () => {
+            // Refused without a click: the lock screen then shows nothing to keep.
+            Promise.resolve(audio.play()).catch(() => { });
+            if (session)
+                session.playbackState = 'playing';
+        };
+        const pause = () => {
+            audio.pause();
+            if (session)
+                session.playbackState = 'paused';
+        };
+        const handle = (action, handler) => {
+            try {
+                session?.setActionHandler(action, handler);
+            }
+            catch {
+                // This browser doesn't offer the action.
+            }
+        };
+        if (session) {
+            try {
+                if (env.MediaMetadata)
+                    session.metadata = new env.MediaMetadata({ title });
+            }
+            catch {
+                // No metadata: the lock screen shows the page's own.
+            }
+            handle('play', () => {
+                play();
+                onToggle?.(true);
+            });
+            handle('pause', () => {
+                pause();
+                onToggle?.(false);
+            });
+        }
+        play();
+        const keeping = {
+            pause,
+            stop() {
+                if (active !== keeping)
+                    return;
+                active = null;
+                audio.pause();
+                audio.removeAttribute('src');
+                audio.load();
+                env.revokeObjectURL?.(url);
+                if (session) {
+                    handle('play', null);
+                    handle('pause', null);
+                    session.metadata = null;
+                    session.playbackState = 'none';
+                }
+            },
+        };
+        active = keeping;
+        return keeping;
+    };
+}
+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.
+ */
+export const keepAudioAlive = (options) => {
+    if (!shared) {
+        const hasWindow = typeof window !== 'undefined';
+        shared = createKeepAudioAlive({
+            Audio: hasWindow ? window.Audio : undefined,
+            mediaSession: typeof navigator !== 'undefined' && 'mediaSession' in navigator ? navigator.mediaSession : undefined,
+            MediaMetadata: hasWindow ? window.MediaMetadata : undefined,
+            createObjectURL: typeof URL !== 'undefined' ? (blob) => URL.createObjectURL(blob) : undefined,
+            revokeObjectURL: typeof URL !== 'undefined' ? (url) => URL.revokeObjectURL(url) : undefined,
+        });
+    }
+    return shared(options);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.29.3",
+  "version": "4.30.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": {