@tristan2828/ui-foundation 4.15.0 → 4.17.0

package/dist/hooks/use-muted.js

@@ -0,0 +1,73 @@
+import { useCallback, useSyncExternalStore } from 'react';
+export function createMutedStore(getStorage) {
+    // Values this page set, for when storage refuses them.
+    const memory = new Map();
+    const listeners = new Map();
+    const notify = (key) => {
+        for (const listener of listeners.get(key) ?? [])
+            listener();
+    };
+    return {
+        get(key) {
+            const kept = memory.get(key);
+            if (kept !== undefined)
+                return kept;
+            try {
+                const stored = getStorage()?.getItem(key);
+                if (stored === 'true')
+                    return true;
+                if (stored === 'false')
+                    return false;
+            }
+            catch {
+                // Storage blocked: unmuted.
+            }
+            return false;
+        },
+        set(key, muted) {
+            memory.set(key, muted);
+            try {
+                getStorage()?.setItem(key, String(muted));
+            }
+            catch {
+                // Storage blocked or full: remembered in memory for this page only.
+            }
+            notify(key);
+        },
+        subscribe(key, listener) {
+            let set = listeners.get(key);
+            if (!set)
+                listeners.set(key, (set = new Set()));
+            set.add(listener);
+            return () => set.delete(listener);
+        },
+        changedElsewhere(key) {
+            memory.delete(key);
+            notify(key);
+        },
+    };
+}
+const browserStore = createMutedStore(() => (typeof window === 'undefined' ? undefined : window.localStorage));
+let listeningForOtherTabs = false;
+function listenForOtherTabs() {
+    if (listeningForOtherTabs || typeof window === 'undefined')
+        return;
+    listeningForOtherTabs = true;
+    window.addEventListener('storage', (event) => {
+        if (event.key !== null)
+            browserStore.changedElsewhere(event.key);
+    });
+}
+/**
+ * `[muted, setMuted]`, remembered on this device under `key` (name it for
+ * the app and screen: `"my-app:timer:muted"`). Unmuted until set.
+ */
+export function useMuted(key) {
+    const subscribe = useCallback((listener) => {
+        listenForOtherTabs();
+        return browserStore.subscribe(key, listener);
+    }, [key]);
+    const muted = useSyncExternalStore(subscribe, () => browserStore.get(key), () => false);
+    const setMuted = useCallback((next) => browserStore.set(key, next), [key]);
+    return [muted, setMuted];
+}

package/dist/hooks/use-prefers-reduced-motion.d.ts

@@ -0,0 +1,2 @@
+/** True while the system asks for reduced motion; false where it can't be read (and on the server). */
+export declare function usePrefersReducedMotion(): boolean;

package/dist/hooks/use-prefers-reduced-motion.js

@@ -0,0 +1,17 @@
+import { useSyncExternalStore } from 'react';
+// Whether the person asked their system for less motion, kept current as
+// they change it. A screen swaps movement (a sweeping ring, a breathing
+// circle) for a fade or a still state while it's true.
+const QUERY = '(prefers-reduced-motion: reduce)';
+function subscribe(onChange) {
+    if (typeof window === 'undefined' || !window.matchMedia)
+        return () => { };
+    const query = window.matchMedia(QUERY);
+    query.addEventListener('change', onChange);
+    return () => query.removeEventListener('change', onChange);
+}
+const getSnapshot = () => typeof window !== 'undefined' && !!window.matchMedia && window.matchMedia(QUERY).matches;
+/** True while the system asks for reduced motion; false where it can't be read (and on the server). */
+export function usePrefersReducedMotion() {
+    return useSyncExternalStore(subscribe, getSnapshot, () => false);
+}

package/dist/hooks/use-push-permission.d.ts

@@ -0,0 +1,72 @@
+import { type PushSubscriptionRequest } from '../api/gateway/push.js';
+/**
+ * - `unsupported`: this browser has no push.
+ * - `needs-install`: iPhone or iPad in a browser tab; push works once the
+ *   app is added to the Home Screen and opened from there.
+ * - `mock`: the page runs on MSW; reminders need the real backend.
+ * - `blocked`: the person said no; only the browser's site settings undo it.
+ * - `off`: can be turned on. `on`: this device gets reminders.
+ */
+export type PushStatus = 'unsupported' | 'needs-install' | 'mock' | 'blocked' | 'off' | 'on';
+type PushRegistration = {
+    active: {
+        scriptURL: string;
+    } | null;
+    pushManager: Pick<PushManager, 'getSubscription' | 'subscribe'>;
+};
+/** What createPushController needs from the browser and the backend. */
+export type PushEnvironment = {
+    notification: {
+        permission: NotificationPermission;
+        requestPermission: () => Promise<NotificationPermission>;
+    } | undefined;
+    serviceWorker: {
+        register: (url: string, options: RegistrationOptions) => Promise<unknown>;
+        getRegistration: () => Promise<PushRegistration | undefined>;
+        ready: () => Promise<PushRegistration>;
+        /** The script of the worker controlling this page, if any. */
+        controllerScript: () => string | undefined;
+    } | undefined;
+    /** `'PushManager' in window`. */
+    pushSupported: boolean;
+    /** Opened from the Home Screen (display-mode: standalone). */
+    standalone: boolean;
+    /** An iPhone or iPad, whatever the browser says it is. */
+    appleMobile: boolean;
+    api: {
+        getPublicKey: () => Promise<string>;
+        save: (subscription: PushSubscriptionRequest) => Promise<number>;
+        remove: (id: number) => Promise<void>;
+    };
+};
+export type PushController = {
+    status: () => Promise<PushStatus>;
+    /** Asks the browser, subscribes, and saves it. Call it straight from a click. */
+    enable: () => Promise<PushStatus>;
+    /** Stops sending to this device, and unsubscribes it. */
+    disable: () => Promise<PushStatus>;
+};
+export type PushControllerOptions = {
+    /** Where pwa() serves the worker. Default `/push-sw.js`. */
+    serviceWorkerUrl?: string;
+};
+export declare function createPushController(env: PushEnvironment, options?: PushControllerOptions): PushController;
+export declare const PUSH_STATUS_QUERY_KEY: readonly ["ui-foundation", "push-status"];
+/** What usePushPermission returns, and what AllowReminders shows. */
+export type PushPermission = {
+    /** Undefined while it's being worked out. */
+    status: PushStatus | undefined;
+    enable: () => void;
+    disable: () => void;
+    /** Turning on or off is under way. */
+    pending: boolean;
+    /** Why the last enable or disable failed, in words to show. */
+    error: string | null;
+};
+/**
+ * Whether this device gets reminders, and `enable`/`disable` for one
+ * button (AllowReminders is that button, with the words around it).
+ * `enable` asks the browser for permission: only ever call it from a click.
+ */
+export declare function usePushPermission(options?: PushControllerOptions): PushPermission;
+export {};

package/dist/hooks/use-push-permission.js

@@ -0,0 +1,154 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { deletePushSubscription, getPushPublicKey, savePushSubscription, } from '../api/gateway/push.js';
+const isMockWorker = (script) => !!script && script.includes('mockServiceWorker');
+function base64UrlToBytes(value) {
+    const base64 = value.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (value.length % 4)) % 4);
+    const binary = atob(base64);
+    const bytes = new Uint8Array(new ArrayBuffer(binary.length));
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+function sameKey(current, wanted) {
+    if (!current)
+        return false;
+    const bytes = new Uint8Array(current);
+    return bytes.length === wanted.length && bytes.every((byte, i) => byte === wanted[i]);
+}
+function toRequest(subscription) {
+    const json = subscription.toJSON();
+    const p256dh = json.keys?.p256dh;
+    const auth = json.keys?.auth;
+    if (!json.endpoint || !p256dh || !auth)
+        throw new Error('The browser gave a subscription without its keys.');
+    return { endpoint: json.endpoint, expirationTime: json.expirationTime ?? null, keys: { p256dh, auth } };
+}
+export function createPushController(env, options = {}) {
+    const workerUrl = options.serviceWorkerUrl ?? '/push-sw.js';
+    // What can be told without waiting on anything, so enable() can ask
+    // the browser in the same task as the click.
+    const knownNow = () => {
+        if (env.appleMobile && !env.standalone)
+            return 'needs-install';
+        if (!env.notification || !env.serviceWorker || !env.pushSupported)
+            return 'unsupported';
+        if (isMockWorker(env.serviceWorker.controllerScript()))
+            return 'mock';
+        if (env.notification.permission === 'denied')
+            return 'blocked';
+        return null;
+    };
+    const ours = (registration) => registration?.active && !isMockWorker(registration.active.scriptURL) ? registration : undefined;
+    return {
+        async status() {
+            const known = knownNow();
+            if (known)
+                return known;
+            const registration = await env.serviceWorker.getRegistration();
+            if (isMockWorker(registration?.active?.scriptURL))
+                return 'mock';
+            if (env.notification.permission !== 'granted')
+                return 'off';
+            const subscription = await ours(registration)?.pushManager.getSubscription();
+            return subscription ? 'on' : 'off';
+        },
+        async enable() {
+            const known = knownNow();
+            if (known)
+                return known;
+            const permission = await env.notification.requestPermission();
+            if (permission !== 'granted')
+                return permission === 'denied' ? 'blocked' : 'off';
+            await env.serviceWorker.register(workerUrl, { scope: '/' });
+            const registration = await env.serviceWorker.ready();
+            const key = base64UrlToBytes(await env.api.getPublicKey());
+            let subscription = await registration.pushManager.getSubscription();
+            // Made with another key (the backend's was replaced): it can't be
+            // sent to any more, so start again.
+            if (subscription && !sameKey(subscription.options.applicationServerKey, key)) {
+                await subscription.unsubscribe();
+                subscription = null;
+            }
+            subscription ??= await registration.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey: key });
+            await env.api.save(toRequest(subscription));
+            return 'on';
+        },
+        async disable() {
+            const subscription = await ours(await env.serviceWorker?.getRegistration())?.pushManager.getSubscription();
+            if (subscription) {
+                // Saving again is how the device learns its id (the same endpoint
+                // answers the same one), so nothing is kept on the device.
+                const id = await env.api.save(toRequest(subscription));
+                await env.api.remove(id);
+                await subscription.unsubscribe();
+            }
+            return 'off';
+        },
+    };
+}
+function browserEnvironment() {
+    const hasWindow = typeof window !== 'undefined';
+    const container = hasWindow && 'serviceWorker' in navigator ? navigator.serviceWorker : undefined;
+    const ua = hasWindow ? navigator.userAgent : '';
+    return {
+        notification: hasWindow && 'Notification' in window ? Notification : undefined,
+        serviceWorker: container && {
+            register: (url, options) => container.register(url, options),
+            getRegistration: () => container.getRegistration(),
+            ready: () => container.ready,
+            controllerScript: () => container.controller?.scriptURL,
+        },
+        pushSupported: hasWindow && 'PushManager' in window,
+        standalone: hasWindow &&
+            (window.matchMedia?.('(display-mode: standalone)').matches ||
+                navigator.standalone === true),
+        // iPadOS says it's a Mac; a Mac has no touch screen.
+        appleMobile: /iPhone|iPad|iPod/.test(ua) || (/Macintosh/.test(ua) && hasWindow && navigator.maxTouchPoints > 1),
+        api: { getPublicKey: getPushPublicKey, save: savePushSubscription, remove: deletePushSubscription },
+    };
+}
+function messageOf(error) {
+    const appError = error;
+    if (appError && typeof appError.kind === 'string') {
+        if (appError.kind === 'notfound')
+            return "This app's backend doesn't send reminders yet.";
+        if (appError.kind === 'network')
+            return "Couldn't reach the app. Check the connection and try again.";
+        return appError.message ?? 'Something went wrong. Try again.';
+    }
+    return "The browser couldn't turn on reminders. Try again, or check its notification settings.";
+}
+export const PUSH_STATUS_QUERY_KEY = ['ui-foundation', 'push-status'];
+/**
+ * Whether this device gets reminders, and `enable`/`disable` for one
+ * button (AllowReminders is that button, with the words around it).
+ * `enable` asks the browser for permission: only ever call it from a click.
+ */
+export function usePushPermission(options = {}) {
+    const queryClient = useQueryClient();
+    const controller = createPushController(browserEnvironment(), options);
+    const { data: status } = useQuery({
+        queryKey: PUSH_STATUS_QUERY_KEY,
+        queryFn: () => controller.status(),
+        staleTime: Infinity,
+    });
+    const settle = (next) => queryClient.setQueryData(PUSH_STATUS_QUERY_KEY, next);
+    // Each takes the run already started: enable() must ask the browser in
+    // the click itself, and mutate() may call its function a tick later.
+    const enable = useMutation({ mutationFn: (run) => run, onSuccess: settle });
+    const disable = useMutation({ mutationFn: (run) => run, onSuccess: settle });
+    const failed = enable.error ?? disable.error;
+    return {
+        status,
+        enable: () => {
+            disable.reset();
+            enable.mutate(controller.enable());
+        },
+        disable: () => {
+            enable.reset();
+            disable.mutate(controller.disable());
+        },
+        pending: enable.isPending || disable.isPending,
+        error: failed ? messageOf(failed) : null,
+    };
+}

package/dist/hooks/use-session-clock.d.ts

@@ -0,0 +1,42 @@
+export type SessionStatus = 'idle' | 'running' | 'done';
+export type SessionClockState = {
+    /** Milliseconds counted so far, paused time left out; `endsAt` at most. */
+    elapsed: number;
+    /** `idle` until `start()`, `running` until `endsAt` is reached, then `done`. */
+    status: SessionStatus;
+    /** Paused by `pause()`, while running. */
+    paused: boolean;
+};
+export type SessionClockStore = {
+    start: () => void;
+    pause: () => void;
+    resume: () => void;
+    /** Back to `idle` at zero. */
+    stop: () => void;
+    /** Whether time may count at all (the hook's `running`); false holds the clock still without pausing it. */
+    setRunning: (running: boolean) => void;
+    setEndsAt: (endsAt: number | undefined) => void;
+    /** Reads the time; the hook calls it each animation frame. */
+    tick: () => void;
+    subscribe: (listener: () => void) => () => void;
+    getSnapshot: () => SessionClockState;
+};
+export declare function createSessionClock(now: () => number): SessionClockStore;
+export type SessionClockOptions = {
+    /**
+     * Whether time may count (default true). False holds the clock still
+     * without pausing it: for time the session isn't on screen at all, such
+     * as its view closed or a confirmation in front of it.
+     */
+    running?: boolean;
+    /** The elapsed milliseconds at which the session is `done`. Without it, it runs until stopped. */
+    endsAt?: number;
+};
+export type SessionClock = SessionClockState & Pick<SessionClockStore, 'start' | 'pause' | 'resume' | 'stop'>;
+/**
+ * A drift-free clock with pause and resume, read from `performance.now()`
+ * each animation frame. It re-renders once per frame only while counting.
+ * A hidden tab draws no frames, but its time still counts: the first frame
+ * back catches up (and reaches `done` if it's due).
+ */
+export declare function useSessionClock({ running, endsAt }?: SessionClockOptions): SessionClock;

package/dist/hooks/use-session-clock.js

@@ -0,0 +1,111 @@
+import { useEffect, useState, useSyncExternalStore } from 'react';
+export function createSessionClock(now) {
+    let status = 'idle';
+    let paused = false;
+    let running = true;
+    let endsAt;
+    // Time counted before the current stretch, and when that stretch began
+    // (null while time isn't counting).
+    let banked = 0;
+    let since = null;
+    let snapshot = { elapsed: 0, status, paused };
+    const listeners = new Set();
+    const counting = () => status === 'running' && !paused && running;
+    const bank = () => {
+        if (since === null)
+            return;
+        banked += now() - since;
+        since = null;
+    };
+    const begin = () => {
+        if (counting() && since === null)
+            since = now();
+    };
+    const update = () => {
+        let elapsed = banked + (since === null ? 0 : now() - since);
+        if (status === 'running' && endsAt !== undefined && elapsed >= endsAt) {
+            status = 'done';
+            paused = false;
+            since = null;
+            banked = endsAt;
+            elapsed = endsAt;
+        }
+        if (elapsed === snapshot.elapsed && status === snapshot.status && paused === snapshot.paused)
+            return;
+        snapshot = { elapsed, status, paused };
+        for (const listener of listeners)
+            listener();
+    };
+    return {
+        start() {
+            status = 'running';
+            paused = false;
+            banked = 0;
+            since = null;
+            begin();
+            update();
+        },
+        pause() {
+            if (status !== 'running' || paused)
+                return;
+            bank();
+            paused = true;
+            update();
+        },
+        resume() {
+            if (status !== 'running' || !paused)
+                return;
+            paused = false;
+            begin();
+            update();
+        },
+        stop() {
+            status = 'idle';
+            paused = false;
+            banked = 0;
+            since = null;
+            update();
+        },
+        setRunning(next) {
+            if (next === running)
+                return;
+            bank();
+            running = next;
+            begin();
+            update();
+        },
+        setEndsAt(next) {
+            endsAt = next;
+            update();
+        },
+        tick: update,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        getSnapshot: () => snapshot,
+    };
+}
+/**
+ * A drift-free clock with pause and resume, read from `performance.now()`
+ * each animation frame. It re-renders once per frame only while counting.
+ * A hidden tab draws no frames, but its time still counts: the first frame
+ * back catches up (and reaches `done` if it's due).
+ */
+export function useSessionClock({ running = true, endsAt } = {}) {
+    const [clock] = useState(() => createSessionClock(() => performance.now()));
+    const state = useSyncExternalStore(clock.subscribe, clock.getSnapshot, clock.getSnapshot);
+    useEffect(() => clock.setRunning(running), [clock, running]);
+    useEffect(() => clock.setEndsAt(endsAt), [clock, endsAt]);
+    const counting = state.status === 'running' && !state.paused && running;
+    useEffect(() => {
+        if (!counting)
+            return;
+        let frame = requestAnimationFrame(function next() {
+            clock.tick();
+            frame = requestAnimationFrame(next);
+        });
+        return () => cancelAnimationFrame(frame);
+    }, [clock, counting]);
+    return { ...state, start: clock.start, pause: clock.pause, resume: clock.resume, stop: clock.stop };
+}

package/dist/hooks/use-wake-lock.d.ts

@@ -0,0 +1,18 @@
+/** What createWakeLock needs from the browser; `navigator.wakeLock` and `document` by default. */
+export type WakeLockEnvironment = {
+    wakeLock: Pick<WakeLock, 'request'> | undefined;
+    document: Pick<Document, 'visibilityState' | 'addEventListener' | 'removeEventListener'>;
+};
+export type WakeLockController = {
+    /** Hold the lock from now on, asking again whenever the tab comes back. */
+    activate: () => void;
+    /** Let it go, including a request still waiting for the browser's answer. */
+    deactivate: () => void;
+};
+export declare function createWakeLock(env: WakeLockEnvironment): WakeLockController;
+/**
+ * Keep the screen awake while `active`. Asked for again when the tab
+ * returns, released on `active` going false or unmount. Does nothing where
+ * the browser has no wake lock, or refuses it.
+ */
+export declare function useWakeLock(active: boolean): void;

package/dist/hooks/use-wake-lock.js

@@ -0,0 +1,70 @@
+import { useEffect } from 'react';
+export function createWakeLock(env) {
+    let active = false;
+    let sentinel = null;
+    // One request at a time: a second ask while the browser decides waits for
+    // that answer rather than ending up holding two locks.
+    let requesting = false;
+    const request = () => {
+        if (!active || !env.wakeLock || sentinel || requesting)
+            return;
+        if (env.document.visibilityState !== 'visible')
+            return;
+        requesting = true;
+        env.wakeLock.request('screen').then((lock) => {
+            requesting = false;
+            // Deactivated while the browser decided: let it go at once.
+            if (!active) {
+                void lock.release().catch(() => { });
+                return;
+            }
+            sentinel = lock;
+            lock.addEventListener('release', () => {
+                if (sentinel === lock)
+                    sentinel = null;
+            });
+        }, 
+        // Refused (no permission, low battery, an iframe without the policy):
+        // the screen may sleep, nothing else changes.
+        () => {
+            requesting = false;
+        });
+    };
+    const onVisibility = () => {
+        if (env.document.visibilityState === 'visible')
+            request();
+    };
+    return {
+        activate() {
+            if (active)
+                return;
+            active = true;
+            env.document.addEventListener('visibilitychange', onVisibility);
+            request();
+        },
+        deactivate() {
+            if (!active)
+                return;
+            active = false;
+            env.document.removeEventListener('visibilitychange', onVisibility);
+            const lock = sentinel;
+            sentinel = null;
+            if (lock)
+                void lock.release().catch(() => { });
+        },
+    };
+}
+/**
+ * Keep the screen awake while `active`. Asked for again when the tab
+ * returns, released on `active` going false or unmount. Does nothing where
+ * the browser has no wake lock, or refuses it.
+ */
+export function useWakeLock(active) {
+    useEffect(() => {
+        if (!active || typeof navigator === 'undefined')
+            return;
+        const controller = createWakeLock({ wakeLock: navigator.wakeLock, document });
+        controller.activate();
+        return () => controller.deactivate();
+    }, [active]);
+}

package/dist/index.d.ts

@@ -21,6 +21,8 @@ export { RichTextEditor, type RichTextEditorProps } from './components/app/rich-
 export { RouteErrorBoundary } from './components/app/route-error-boundary.js';
 export { PillFilter, type PillFilterOption, type PillFilterProps } from './components/app/pill-filter.js';
 export { SecondaryFilters, type ActiveFilter, type SecondaryFiltersProps } from './components/app/secondary-filters.js';
+export { SessionView, type SessionViewProps } from './components/app/session-view.js';
+export { AllowReminders, type AllowRemindersProps } from './components/app/allow-reminders.js';
 export { StageCircle, type StageCircleProps, type StageCircleStage, type StageCircleTone, } from './components/app/stage-circle.js';
 export { Notice, type NoticeProps, type NoticeTone } from './components/app/notice.js';
 export { SourceCredit, type Source, type SourceCreditProps } from './components/app/source-credit.js';
@@ -45,4 +47,10 @@ export type { TableView, UrlChanges } from './hooks/table-url-changes.js';
 export { useDebouncedValue } from './hooks/use-debounced-value.js';
 export { useRecordUpdate, type RecordChange, type RecordUpdateOptions, } from './hooks/use-record-update.js';
 export { useIsMobile } from './hooks/use-mobile.js';
+export { useWakeLock } from './hooks/use-wake-lock.js';
+export { useSessionClock, type SessionClock, type SessionClockOptions, type SessionClockState, type SessionStatus, } from './hooks/use-session-clock.js';
+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 { chime, hush, say, sequence, unlockAudio, vibrate, type ChimeOptions, type SayOptions, type SequenceOptions, } from './lib/audio-cues.js';

package/dist/index.js

@@ -26,6 +26,8 @@ export { RichTextEditor } from './components/app/rich-text-editor.js';
 export { RouteErrorBoundary } from './components/app/route-error-boundary.js';
 export { PillFilter } from './components/app/pill-filter.js';
 export { SecondaryFilters } from './components/app/secondary-filters.js';
+export { SessionView } from './components/app/session-view.js';
+export { AllowReminders } from './components/app/allow-reminders.js';
 export { StageCircle, } from './components/app/stage-circle.js';
 export { Notice } from './components/app/notice.js';
 export { SourceCredit } from './components/app/source-credit.js';
@@ -49,5 +51,12 @@ export { useTableUrlState } from './hooks/use-table-url-state.js';
 export { useDebouncedValue } from './hooks/use-debounced-value.js';
 export { useRecordUpdate, } from './hooks/use-record-update.js';
 export { useIsMobile } from './hooks/use-mobile.js';
+// Timed screens (docs/foundation/timed-screens.md)
+export { useWakeLock } from './hooks/use-wake-lock.js';
+export { useSessionClock, } from './hooks/use-session-clock.js';
+export { usePrefersReducedMotion } from './hooks/use-prefers-reduced-motion.js';
+export { useMuted } from './hooks/use-muted.js';
+export { createPushController, usePushPermission, } from './hooks/use-push-permission.js';
 // Utilities
 export { cn } from './lib/utils.js';
+export { chime, hush, say, sequence, unlockAudio, vibrate, } from './lib/audio-cues.js';

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

@@ -0,0 +1,52 @@
+export type ChimeOptions = {
+    /** Frequency in Hz (default 660, an E5). */
+    pitch?: number;
+    /** 0 to 1 at the chime's peak (default 0.25). */
+    volume?: number;
+    /** Milliseconds from strike to silence (default 1200). */
+    duration?: number;
+};
+export type SequenceOptions = {
+    /** Milliseconds between one chime's strike and the next's (default 180). */
+    spacing?: number;
+};
+export type SayOptions = {
+    /** A BCP 47 tag; the browser's default voice when left out. */
+    lang?: string;
+    /** 0.1 to 10 (default 1). */
+    rate?: number;
+    /** 0 to 1 (default 1). */
+    volume?: number;
+};
+export type AudioCuesEnvironment = {
+    AudioContext?: new () => AudioContext;
+    speechSynthesis?: Pick<SpeechSynthesis, 'speak' | 'cancel'>;
+    SpeechSynthesisUtterance?: new (text?: string) => SpeechSynthesisUtterance;
+    vibrate?: (pattern: number | number[]) => boolean;
+};
+export type AudioCues = {
+    /** Call from the click or tap that starts a session; sound is allowed from then on. */
+    unlockAudio: () => void;
+    chime: (options?: ChimeOptions) => void;
+    /** Several chimes in a row (a closing pair), `spacing` apart. */
+    sequence: (chimes: ChimeOptions[], options?: SequenceOptions) => void;
+    /** Speaks `text`, cutting off any line still being spoken. */
+    say: (text: string, options?: SayOptions) => void;
+    /** Stops whatever is being spoken. */
+    hush: () => void;
+    /** A vibration pattern in milliseconds; Android only, a no-op elsewhere. */
+    vibrate: (pattern: number | number[]) => void;
+};
+export declare function createAudioCues(env: AudioCuesEnvironment): AudioCues;
+/** Call from the click or tap that starts a session; sound is allowed from then on. */
+export declare const unlockAudio: AudioCues['unlockAudio'];
+/** A soft sine chime; dropped before unlockAudio() or where there's no Web Audio. */
+export declare const chime: AudioCues['chime'];
+/** Several chimes `spacing` ms apart (a closing pair). */
+export declare const sequence: AudioCues['sequence'];
+/** 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. */
+export declare const hush: AudioCues['hush'];
+/** A vibration pattern in ms; Android only, a no-op elsewhere. */
+export declare const vibrate: AudioCues['vibrate'];