@tristan2828/ui-foundation 4.15.0 → 4.16.0

package/README.md

@@ -18,7 +18,7 @@ than installing this by hand:
 
 | Import | What |
 |---|---|
-| `@tristan2828/ui-foundation` | `AppShell`, `DataTable`, `EntityView` (with `EditableValue`, `editInPlace`), `EntityForm`, `Markdown`, `RichTextEditor`, `ErrorState`, `MultiChoice`, `MultiReference`, `ListEditor`, `PasswordInput`, `RouteErrorBoundary`, `FoundationProviders`, `DataEnvironmentBanner`, `LoginRoute`, `RegisterRoute`, `useAuth`, `useTableUrlState`, `useRecordUpdate`, `useDebouncedValue`, `createQueryClient`, `cn`; types `Page`, `AppError`, `QuerySpec` |
+| `@tristan2828/ui-foundation` | `AppShell`, `DataTable`, `EntityView` (with `EditableValue`, `editInPlace`), `EntityForm`, `Markdown`, `RichTextEditor`, `ErrorState`, `MultiChoice`, `MultiReference`, `ListEditor`, `PasswordInput`, `RouteErrorBoundary`, `FoundationProviders`, `DataEnvironmentBanner`, `LoginRoute`, `RegisterRoute`, `useAuth`, `useTableUrlState`, `useRecordUpdate`, `useDebouncedValue`, `createQueryClient`, `cn`; types `Page`, `AppError`, `QuerySpec`. For timed screens (`docs/foundation/timed-screens.md`): `SessionView`, `useSessionClock`, `useWakeLock`, `useMuted`, `usePrefersReducedMotion`, and the audio cues `unlockAudio`, `chime`, `sequence`, `say`, `hush`, `vibrate` |
 | `@tristan2828/ui-foundation/ui/<name>` | shadcn primitives: badge, button, calendar, card, checkbox, combobox, dialog, empty, field, input, input-group, label, popover, select, separator, sheet, sidebar, skeleton, sonner, spinner, switch, table, textarea, tooltip |
 | `@tristan2828/ui-foundation/gateway` | `safeFetch`, `toAppError`, `networkError` — for an app's `src/api/gateway/` only |
 | `@tristan2828/ui-foundation/mocks` | MSW: `authHandlers`, `environmentHandlers`, `resetMockAuth`, `getMockCurrentUser`, `MOCK_USER`, `exposeMswForE2E` |

package/conventions/AGENTS.md

@@ -89,6 +89,13 @@ A pattern the foundation lacks is worth raising there: the design language
 grows in the package so every app gets it, with axe contrast coverage in
 both themes.
 
+## Timed Screens
+A screen that runs on its own for minutes (a timer, a player, a paced
+routine) is built from the package's parts: `SessionView`,
+`useSessionClock`, `useWakeLock`, the audio cues and `useMuted`. Follow
+`docs/foundation/timed-screens.md`, including its Playwright recipe
+(`clock.install()` before `goto`, then `fastForward`, never `runFor`).
+
 ## Scope and Stopping
 - Do the task you were given and nothing beyond it. A task is done when
   `npm run verify` passes — not when it feels complete.

package/conventions/docs/timed-screens.md

@@ -0,0 +1,155 @@
+# Timed Screens
+
+A screen that runs on its own for minutes: a paced timer, a step-by-step
+player, a recipe step, anything followed from across the room. The
+package has the parts, so a screen like this is assembled, not rebuilt:
+
+| Part | What it does |
+|---|---|
+| `SessionView` | The whole viewport over the app shell: a modal named by its title, focus kept inside, Esc closes it. Optional real fullscreen and a held wake lock |
+| `useSessionClock` | A clock that doesn't drift, with pause and resume: `idle`, `running`, `done` |
+| `useWakeLock` | Keeps the screen on while a session runs (`SessionView`'s `keepAwake` uses it) |
+| `unlockAudio`, `chime`, `sequence`, `say`, `hush`, `vibrate` | Sound cues with no audio files |
+| `useMuted` | A mute toggle remembered on this device |
+| `usePrefersReducedMotion` | Whether to swap movement for a fade |
+
+All of them are imported from `@tristan2828/ui-foundation`. The package's
+Storybook has the whole thing working together: `app/SessionView`, the
+Timer story.
+
+## The view
+
+```tsx
+const [open, setOpen] = useState(false)
+// The clock lives above the view: closing it holds the time, reopening
+// carries on. Inside the view, it would start over on every open.
+const clock = useSessionClock({ running: open, endsAt: 5 * 60_000 })
+const primary = useRef<HTMLButtonElement>(null)
+
+<Button onClick={() => setOpen(true)}>Start the routine</Button>
+<SessionView
+  open={open}
+  onOpenChange={setOpen}
+  title="Morning routine"
+  keepAwake
+  fullscreenControl
+  initialFocus={primary}
+>
+  …the screen, with its main control as `ref={primary}`
+</SessionView>
+```
+
+- **The title is required.** It names the dialog for screen readers and
+  heads the view. The header also holds Close and, with
+  `fullscreenControl`, a "Full screen" toggle.
+- **Real fullscreen** asks the browser to take the whole screen too
+  (hiding its own bars). Where the browser can't (iOS Safari on a phone),
+  the control isn't shown. The view already covers the page. Closing the
+  view leaves fullscreen if the view entered it.
+- **Safe areas.** The view pads itself by the phone's safe-area insets.
+  They are zero unless the app's `index.html` viewport meta has
+  `viewport-fit=cover`. Without it the browser keeps the page out of the
+  notch on its own. With it, check the rest of the app at phone width too.
+- **Never build this from `DialogContent`** with its classes overridden
+  piece by piece. That fights the primitive's own classes on every
+  upgrade, and gets the details above wrong.
+
+## The clock
+
+`useSessionClock({ running?, endsAt? })` returns
+`{ elapsed, status, paused, start, pause, resume, stop }`.
+
+- `elapsed` is in milliseconds, read from `performance.now()` each
+  animation frame. It is never summed from ticks, so it doesn't drift.
+  Paused time is left out, so `resume()` carries on exactly where
+  `pause()` stopped.
+- `status` is `idle` until `start()`, then `running`, then `done` once
+  `elapsed` reaches `endsAt`. `elapsed` stops at `endsAt`. Without
+  `endsAt` it runs until `stop()`, which goes back to `idle` at zero.
+- `paused` is the person's own pause. `running: false` is different: it
+  holds the clock still without pausing it. Use it for time the session
+  isn't on screen at all, such as the view closed or a confirmation in
+  front of it.
+- It re-renders once per frame, only while counting. Format what it shows
+  from `elapsed`, never by counting renders.
+- A hidden tab draws no frames, but its time still counts. The first frame
+  back catches up, and reaches `done` if it's due.
+
+For phases (stretch two minutes, rest thirty seconds), keep one clock for
+the whole session and work out the phase from `elapsed`. A clock per
+phase drifts by the gap between one ending and the next starting.
+
+## Sound
+
+Browsers block sound until the person has clicked or tapped. So:
+
+- **Call `unlockAudio()` from the click that starts the session**, in the
+  click handler itself, not in an effect after it. Every cue before that
+  is dropped rather than played late. iOS also needs speech started from
+  a click, and `unlockAudio()` does that too.
+- `chime({ pitch?, volume?, duration? })`: a soft sine tone, a short
+  attack and a slow fade. `pitch` is in Hz (660 by default). For a
+  closing pair, use `sequence([{ pitch: 660 }, { pitch: 880 }])`, 180 ms
+  apart by default.
+- `say(text)` speaks a line ("Next: stretch, 2 minutes"), cutting off any
+  line still being spoken. `hush()` stops it. Call `hush()` when the
+  session stops or the view closes.
+- `vibrate(pattern)` only works on Android. Elsewhere it does nothing.
+- 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')`,
+  and check `muted` before each cue. Name the key for the app and screen.
+  It's remembered on this device. Where storage is blocked it still works
+  for the page's life. Show the toggle as a pressed button
+  (`aria-pressed={muted}`) named "Mute".
+- **Cue on a change of state** in an effect that compares the previous
+  state with the current one, so the cue plays once. Never play a cue
+  during render.
+
+## Motion
+
+`usePrefersReducedMotion()` is true while the person's system asks for
+less motion. Swap a sweeping ring or a breathing circle for a fade or a
+still state then. Don't drop the information it carried.
+
+## Testing a timed screen in Playwright
+
+**Install the fake clock before `goto`, then `fastForward` to each state:**
+
+```ts
+test('running, paused and done', async ({ page }) => {
+  await page.clock.install()          // before goto, or the page keeps the real clock
+  await page.goto('/routine')
+  await page.getByRole('button', { name: 'Start' }).click()
+
+  await page.clock.fastForward('00:20')
+  await expect(page.getByRole('timer', { name: 'Time left' })).toHaveText('4:40')
+
+  await page.getByRole('button', { name: 'Pause' }).click()
+  await page.clock.fastForward('05:00')
+  await expect(page.getByRole('timer', { name: 'Time left' })).toHaveText('4:40')
+
+  await page.getByRole('button', { name: 'Resume' }).click()
+  await page.clock.fastForward('04:40')
+  await expect(page.getByRole('status')).toHaveText('Done')
+})
+```
+
+- **`fastForward`, not `runFor`.** `runFor` over a long span doesn't fire
+  every animation frame. A screen that adds time up per frame comes out
+  short: a one-minute session ended about 20 seconds early in a real
+  app's tests. `useSessionClock` reads the time each frame, so one frame
+  after `fastForward` lands on the right state.
+- Give the time on screen `role="timer"` and a name, and the state line
+  `role="status"`, so tests (and screen readers) find them by role.
+- **The wake lock** does nothing in headless Chromium. To check it's
+  held, replace `navigator.wakeLock` in `page.addInitScript` with one that
+  records `request` and `release`. The package's own spec does this
+  (`e2e/session-view.spec.ts` in the foundation repo).
+- **Sound in tests.** Headless browsers play to nothing, so a test never
+  needs sound off to pass. To check what's spoken, wrap
+  `speechSynthesis.speak` in `addInitScript` and record each
+  utterance's `text`. To run a headed test in silence, set the mute key
+  before the page loads:
+  `page.addInitScript(() => localStorage.setItem('my-app:routine:muted', 'true'))`.
+- **Reduced motion:** `await page.emulateMedia({ reducedMotion: 'reduce' })`.

package/dist/components/app/session-view.d.ts

@@ -0,0 +1,19 @@
+import * as React from 'react';
+import { Dialog as DialogPrimitive } from '@base-ui/react/dialog';
+export type SessionViewProps = {
+    open: boolean;
+    /** Called with false on Esc and on the Close button. */
+    onOpenChange: (open: boolean) => void;
+    /** Names the view for screen readers, and heads it on screen. */
+    title: React.ReactNode;
+    children: React.ReactNode;
+    /** Hold a screen wake lock while the view is open (useWakeLock). */
+    keepAwake?: boolean;
+    /** Show a "Full screen" control that asks the browser for real fullscreen too. */
+    fullscreenControl?: boolean;
+    /** What takes focus on open (default: the first focusable control, which is the header's). */
+    initialFocus?: DialogPrimitive.Popup.Props['initialFocus'];
+    /** On the area below the header, which holds `children`. */
+    className?: string;
+};
+export declare function SessionView({ open, onOpenChange, title, children, keepAwake, fullscreenControl, initialFocus, className, }: SessionViewProps): React.JSX.Element;

package/dist/components/app/session-view.js

@@ -0,0 +1,68 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// A full-screen view for a timed screen (a paced timer, a step-by-step
+// player, anything followed from across the room): the whole viewport over
+// the app shell, inside the phone's safe-area insets. It's a modal dialog,
+// so focus stays in it and Esc closes it through onOpenChange, and it's
+// named by its title. It fades in, never zooms.
+//
+// Optional: a "Full screen" control that also asks the browser for real
+// fullscreen and quietly isn't there where the browser can't (iOS Safari
+// on a phone), and keepAwake, which holds a screen wake lock while open.
+// Recipes for its states in Playwright: docs/foundation/timed-screens.md.
+import * as React from 'react';
+import { Dialog as DialogPrimitive } from '@base-ui/react/dialog';
+import { Maximize2Icon, Minimize2Icon, XIcon } from 'lucide-react';
+import { cn } from 'cn';
+import { Button } from '../ui/button.js';
+import { Dialog, DialogClose, DialogPortal, DialogTitle } from '../ui/dialog.js';
+import { useWakeLock } from '../../hooks/use-wake-lock.js';
+export function SessionView({ open, onOpenChange, title, children, keepAwake = false, fullscreenControl = false, initialFocus, className, }) {
+    useWakeLock(open && keepAwake);
+    const fullscreen = useDocumentFullscreen(open);
+    return (_jsx(Dialog, { open: open, onOpenChange: (next) => onOpenChange(next), children: _jsx(DialogPortal, { children: _jsxs(DialogPrimitive.Popup, { "data-slot": "session-view", initialFocus: initialFocus, className: cn('fixed inset-0 z-50 flex flex-col bg-background text-foreground outline-none', 
+                // The insets are 0 unless the page's viewport meta has viewport-fit=cover.
+                'pt-[env(safe-area-inset-top)] pr-[env(safe-area-inset-right)] pb-[env(safe-area-inset-bottom)] pl-[env(safe-area-inset-left)]', 'duration-150 data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0'), children: [_jsxs("header", { className: "flex items-center gap-1 px-4 py-2", children: [_jsx(DialogTitle, { className: "min-w-0 flex-1 truncate type-section-title", children: title }), fullscreenControl && fullscreen.supported && (_jsx(Button, { variant: "ghost", size: "icon", "aria-label": "Full screen", "aria-pressed": fullscreen.active, onClick: fullscreen.toggle, children: fullscreen.active ? _jsx(Minimize2Icon, {}) : _jsx(Maximize2Icon, {}) })), _jsx(DialogClose, { render: _jsx(Button, { variant: "ghost", size: "icon", "aria-label": "Close" }), children: _jsx(XIcon, {}) })] }), _jsx("div", { className: cn('flex min-h-0 flex-1 flex-col overflow-auto px-4 pb-4', className), children: children })] }) }) }));
+}
+// The whole page in the browser's fullscreen (not the view's own element:
+// popups inside the view portal to <body>, and would vanish outside a
+// fullscreen element). Followed through `fullscreenchange`, since the
+// browser's own Esc leaves it too. Left when the view closes, if the view
+// was what entered it.
+function useDocumentFullscreen(open) {
+    const [supported] = React.useState(() => typeof document !== 'undefined' && document.fullscreenEnabled === true && !!document.documentElement.requestFullscreen);
+    const [active, setActive] = React.useState(false);
+    const entered = React.useRef(false);
+    React.useEffect(() => {
+        if (!supported)
+            return;
+        const onChange = () => {
+            const now = document.fullscreenElement !== null;
+            setActive(now);
+            if (!now)
+                entered.current = false;
+        };
+        document.addEventListener('fullscreenchange', onChange);
+        return () => document.removeEventListener('fullscreenchange', onChange);
+    }, [supported]);
+    React.useEffect(() => {
+        if (open || !entered.current)
+            return;
+        entered.current = false;
+        if (document.fullscreenElement)
+            void document.exitFullscreen().catch(() => { });
+    }, [open]);
+    React.useEffect(() => () => {
+        if (entered.current && document.fullscreenElement)
+            void document.exitFullscreen().catch(() => { });
+    }, []);
+    const toggle = () => {
+        if (document.fullscreenElement) {
+            void document.exitFullscreen().catch(() => { });
+            return;
+        }
+        // Refused (no gesture, a policy, an iframe without allowfullscreen):
+        // the view stays as it is, already covering the page.
+        document.documentElement.requestFullscreen().then(() => (entered.current = true), () => { });
+    };
+    return { supported, active, toggle };
+}

package/dist/hooks/use-muted.d.ts

@@ -0,0 +1,15 @@
+type StorageLike = Pick<Storage, 'getItem' | 'setItem'>;
+export type MutedStore = {
+    get: (key: string) => boolean;
+    set: (key: string, muted: boolean) => void;
+    subscribe: (key: string, listener: () => void) => () => void;
+    /** Another tab changed `key` (a `storage` event): forget the in-memory value and re-read. */
+    changedElsewhere: (key: string) => void;
+};
+export declare function createMutedStore(getStorage: () => StorageLike | undefined): MutedStore;
+/**
+ * `[muted, setMuted]`, remembered on this device under `key` (name it for
+ * the app and screen: `"my-app:timer:muted"`). Unmuted until set.
+ */
+export declare function useMuted(key: string): readonly [boolean, (muted: boolean) => void];
+export {};

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-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,7 @@ 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 { 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 +46,9 @@ 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 { 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,7 @@ 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 { StageCircle, } from './components/app/stage-circle.js';
 export { Notice } from './components/app/notice.js';
 export { SourceCredit } from './components/app/source-credit.js';
@@ -49,5 +50,11 @@ 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';
 // 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'];

package/dist/lib/audio-cues.js

@@ -0,0 +1,138 @@
+// Sound cues for timed screens, with no audio files: a sine-tone chime
+// (a short attack, a slow fade) from Web Audio, spoken lines from the
+// browser's speech synthesis, and a vibration on Android.
+//
+// Browsers block sound until the person has clicked or tapped, so a
+// session's start button calls unlockAudio() from its click; every cue
+// before that is silently dropped rather than played late. Everything
+// here is a no-op where the browser can't make the sound
+// (docs/foundation/timed-screens.md "Sound").
+//
+// 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;
+export function createAudioCues(env) {
+    let context = null;
+    // 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;
+    const playable = () => context !== null && (context.state === 'running' || resuming);
+    const strike = (ctx, { pitch = 660, volume = 0.25, duration = 1200 }, delay) => {
+        const start = ctx.currentTime + delay / 1000;
+        const end = start + Math.max(duration, 50) / 1000;
+        const peak = Math.min(Math.max(volume, SILENT), 1);
+        const oscillator = ctx.createOscillator();
+        oscillator.type = 'sine';
+        oscillator.frequency.setValueAtTime(pitch, start);
+        const gain = ctx.createGain();
+        gain.gain.setValueAtTime(SILENT, start);
+        gain.gain.exponentialRampToValueAtTime(peak, start + ATTACK);
+        gain.gain.exponentialRampToValueAtTime(SILENT, end);
+        oscillator.connect(gain).connect(ctx.destination);
+        oscillator.start(start);
+        oscillator.stop(end + 0.05);
+    };
+    return {
+        unlockAudio() {
+            if (env.AudioContext) {
+                try {
+                    context ??= new env.AudioContext();
+                    if (context.state !== 'running' && context.state !== 'closed') {
+                        resuming = true;
+                        context.resume().then(() => (resuming = false), () => (resuming = false));
+                    }
+                }
+                catch {
+                    context = null;
+                }
+            }
+            // iOS speaks only once speech has started from a gesture: a silent,
+            // empty line here lets later cues through.
+            if (env.speechSynthesis && env.SpeechSynthesisUtterance) {
+                try {
+                    const primer = new env.SpeechSynthesisUtterance('');
+                    primer.volume = 0;
+                    env.speechSynthesis.speak(primer);
+                }
+                catch {
+                    // No speech: say() stays a no-op.
+                }
+            }
+        },
+        chime(options = {}) {
+            if (!playable() || !context)
+                return;
+            strike(context, options, 0);
+        },
+        sequence(chimes, { spacing = 180 } = {}) {
+            if (!playable() || !context)
+                return;
+            const ctx = context;
+            chimes.forEach((options, index) => strike(ctx, options, index * spacing));
+        },
+        say(text, { lang, rate, volume } = {}) {
+            if (!env.speechSynthesis || !env.SpeechSynthesisUtterance)
+                return;
+            try {
+                env.speechSynthesis.cancel();
+                const line = new env.SpeechSynthesisUtterance(text);
+                if (lang)
+                    line.lang = lang;
+                if (rate !== undefined)
+                    line.rate = rate;
+                if (volume !== undefined)
+                    line.volume = volume;
+                env.speechSynthesis.speak(line);
+            }
+            catch {
+                // Speech unavailable: the cue is dropped.
+            }
+        },
+        hush() {
+            try {
+                env.speechSynthesis?.cancel();
+            }
+            catch {
+                // Nothing to stop.
+            }
+        },
+        vibrate(pattern) {
+            try {
+                env.vibrate?.(pattern);
+            }
+            catch {
+                // No vibration motor, or not allowed here.
+            }
+        },
+    };
+}
+let shared = null;
+function browserCues() {
+    if (shared)
+        return shared;
+    const win = typeof window === 'undefined' ? undefined : window;
+    shared = createAudioCues({
+        AudioContext: win?.AudioContext ?? win?.webkitAudioContext,
+        speechSynthesis: win?.speechSynthesis,
+        SpeechSynthesisUtterance: win?.SpeechSynthesisUtterance,
+        vibrate: typeof navigator !== 'undefined' && typeof navigator.vibrate === 'function'
+            ? (pattern) => navigator.vibrate(pattern)
+            : undefined,
+    });
+    return shared;
+}
+/** Call from the click or tap that starts a session; sound is allowed from then on. */
+export const unlockAudio = () => browserCues().unlockAudio();
+/** A soft sine chime; dropped before unlockAudio() or where there's no Web Audio. */
+export const chime = (options) => browserCues().chime(options);
+/** Several chimes `spacing` ms apart (a closing pair). */
+export const sequence = (chimes, options) => browserCues().sequence(chimes, options);
+/** 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. */
+export const hush = () => browserCues().hush();
+/** A vibration pattern in ms; Android only, a no-op elsewhere. */
+export const vibrate = (pattern) => browserCues().vibrate(pattern);

package/package.json

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