@tristan2828/ui-foundation 4.15.0 → 4.17.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`. For reminders (`docs/foundation/reminders.md`): `AllowReminders`, `usePushPermission` |
 | `@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,20 @@ 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`).
+
+## Reminders
+A notification at a time the user chose, with the app closed, is Web
+Push: `pwa()` in `vite.config.ts`, `AllowReminders` with
+`usePushPermission()`, and the backend's `send_push` and reminders job.
+Follow `docs/foundation/reminders.md`. Never ask for notification
+permission on page load: only from the click on "Allow reminders".
+
 ## 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/reminders.md

@@ -0,0 +1,85 @@
+# Reminders
+
+A notification at a time the user chose ("time for your morning routine",
+"a short break at 3 pm", a habit, a medication) that reaches them with the
+app closed. It's Web Push: the browser subscribes with its push service
+(Google's, Mozilla's, Apple's, Microsoft's), the backend encrypts a message
+to that subscription and posts it there, and the push service delivers it
+to the device, where the app's service worker shows it.
+
+| Part | Where | What it does |
+|---|---|---|
+| `pwa({ name })` | `vite.config.ts`, from `@tristan2828/ui-foundation/vite` | The app installable: a manifest, icons in the theme's colours, and `/push-sw.js`, the service worker that shows pushes and opens their path |
+| `usePushPermission()` | the package | Whether this device gets reminders, and `enable`/`disable` |
+| `AllowReminders` | the package | The control: says what reminders are, then asks, on a click |
+| `/push/public-key`, `/push/subscriptions` | `openapi.yaml`, the foundation's part (optional) | The VAPID key to subscribe with; this device's subscription saved or dropped |
+| `app/push.py` | the reference backend | `send_push(session, user_id, title, body, url)`: encrypted (RFC 8291), signed (VAPID), to every device the user allowed |
+| `app/reminders.py`, `reminders` | the reference backend | A reminder row (when, which days, the text, the path), and the `send-reminders` job that sends each one when it's due |
+
+Off until the backend turns it on (`PUSH_ENABLED`, `docs/deploy.md`
+"Reminders (Web Push)"). An app without reminders leaves `/push/*` out of
+`openapi.yaml` and `pwa()` out of its config.
+
+## Allowing reminders
+
+```tsx
+import { AllowReminders, usePushPermission } from '@tristan2828/ui-foundation'
+
+const push = usePushPermission()
+<AllowReminders push={push} description="We'll remind you when it's time for your routine." />
+```
+
+- **Never ask on page load.** A prompt nobody expected gets refused, and a
+  refusal is final: only the browser's site settings undo it. The button
+  says what reminders are first; `enable()` asks then, from the click.
+- **Put it where reminders are set**: the top of the reminders list, or a
+  settings page. One per device: each phone or browser allows its own.
+- **Every state says what to do next.** `AllowReminders` shows them all
+  (the package's Storybook, `app/AllowReminders`):
+
+| `status` | Means | Shows |
+|---|---|---|
+| `off` | Can be turned on | The description and "Allow reminders" |
+| `on` | This device gets them | "Reminders are on for this device", and "Turn off" |
+| `needs-install` | iPhone or iPad in a browser tab | How to add the app to the Home Screen |
+| `blocked` | The person said no | Where to allow it again |
+| `unsupported` | No push in this browser | That it can't |
+| `mock` | The app runs on MSW | That reminders need the real backend |
+
+## On iPhone and iPad
+
+Push works only in the app added to the Home Screen (Share, then Add to
+Home Screen) and opened from there, on iOS 16.4 or later. In a Safari tab
+there is no push at all, so `usePushPermission` says `needs-install` and
+`AllowReminders` shows the steps. `pwa()`'s manifest (`display:
+standalone`) is what makes the Home Screen app an app.
+
+## A reminder is the app's own row
+
+The reference backend has a `reminders` table and the job that sends it;
+what a reminder means is the app's. Give it an API and screens like any
+entity (`add-an-entity.md`): its fields are `title`, `body`, `url` (a
+path in the app, opened when it's tapped), `timeOfDay` ("07:30"), `days`
+(some of mon,tue,wed,thu,fri,sat,sun), `timeZone` (the person's IANA
+zone: `Intl.DateTimeFormat().resolvedOptions().timeZone`) and `enabled`.
+Scope it to the signed-in user, as Widgets are.
+
+- **The job** (`send-reminders`, every minute, with `JOBS_ENABLED`)
+  sends a reminder when today is one of its days in its time zone and the
+  time has come, once a day at most. More than 15 minutes late (the
+  backend was down) and it's skipped for the day rather than sent late.
+- **Something else to send?** Call `send_push` from the app's own code or
+  job: a message when a long task finishes, a daily summary. The `url` is
+  always the app's own path.
+- **Time zones** come from the system's time zone database. On Windows
+  that's the `tzdata` package, which the backend doesn't install: a
+  Windows dev machine reads only `UTC` until it's added.
+
+## Testing
+
+Under MSW the page is held by MSW's service worker, so `usePushPermission`
+reads `mock` and never subscribes: screens show the `mock` state, and a
+Playwright spec checks it the same way. The rest is the backend's: its
+tests decrypt every message as a browser would. To try it end to end, run
+the real backend with push on, allow reminders in the browser, then
+`backend/scripts/send_test_push.py <email>`.

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/api/gateway/push.d.ts

@@ -0,0 +1,8 @@
+import type { components } from "../schema.js";
+export type PushSubscriptionRequest = components["schemas"]["PushSubscriptionRequest"];
+/** The key to subscribe with. A 404 is a backend with push turned off. */
+export declare function getPushPublicKey(): Promise<string>;
+/** Saves the subscription; the same device again answers the same id. */
+export declare function savePushSubscription(subscription: PushSubscriptionRequest): Promise<number>;
+/** Already gone (404) counts as done. */
+export declare function deletePushSubscription(id: number): Promise<void>;

package/dist/api/gateway/push.js

@@ -0,0 +1,25 @@
+import { safeFetch, toAppError } from "./errors.js";
+/** The key to subscribe with. A 404 is a backend with push turned off. */
+export async function getPushPublicKey() {
+    const res = await safeFetch("/push/public-key");
+    if (res.status !== 200)
+        throw toAppError(res.status, res.body, res.headers);
+    return res.body.publicKey;
+}
+/** Saves the subscription; the same device again answers the same id. */
+export async function savePushSubscription(subscription) {
+    const res = await safeFetch("/push/subscriptions", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(subscription),
+    });
+    if (res.status !== 201)
+        throw toAppError(res.status, res.body, res.headers);
+    return res.body.id;
+}
+/** Already gone (404) counts as done. */
+export async function deletePushSubscription(id) {
+    const res = await safeFetch(`/push/subscriptions/${id}`, { method: "DELETE" });
+    if (res.status !== 204 && res.status !== 404)
+        throw toAppError(res.status, res.body, res.headers);
+}

package/dist/api/schema.d.ts

@@ -131,6 +131,63 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/push/public-key": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * The app's VAPID public key, which a browser subscribes to push with
+         * @description For usePushPermission. 404 when the backend has push turned off.
+         */
+        get: operations["getPushPublicKey"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/push/subscriptions": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Save this device's push subscription for the signed-in user
+         * @description The browser's PushSubscription.toJSON(). The same endpoint again replaces its keys and owner and answers the same id. The endpoint must be a push service's (422 otherwise): the backend POSTs to it.
+         */
+        post: operations["savePushSubscription"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/push/subscriptions/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post?: never;
+        /** Stop sending to one of the signed-in user's devices */
+        delete: operations["deletePushSubscription"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 export type webhooks = Record<string, never>;
 export interface components {
@@ -185,6 +242,23 @@ export interface components {
             /** @description The frontend build (its commit). */
             release?: string;
         };
+        PushPublicKey: {
+            /** @description The P-256 public key, base64url (applicationServerKey). */
+            publicKey: string;
+        };
+        PushSubscriptionRequest: {
+            /** @description The push service's URL for this device. */
+            endpoint: string;
+            /** @description Milliseconds since the epoch, sent by some browsers, ignored. */
+            expirationTime?: number | null;
+            keys: {
+                p256dh: string;
+                auth: string;
+            };
+        };
+        PushSubscriptionCreated: {
+            id: number;
+        };
         /** @description FastAPI's default 422 shape (RequestValidationError). */
         ValidationErrorBody: {
             detail: {
@@ -442,4 +516,78 @@ export interface operations {
             500: components["responses"]["ServerError"];
         };
     };
+    getPushPublicKey: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PushPublicKey"];
+                };
+            };
+            401: components["responses"]["UnauthorizedError"];
+            404: components["responses"]["NotFoundError"];
+            500: components["responses"]["ServerError"];
+        };
+    };
+    savePushSubscription: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["PushSubscriptionRequest"];
+            };
+        };
+        responses: {
+            /** @description Saved. */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PushSubscriptionCreated"];
+                };
+            };
+            401: components["responses"]["UnauthorizedError"];
+            404: components["responses"]["NotFoundError"];
+            422: components["responses"]["ValidationError"];
+            500: components["responses"]["ServerError"];
+        };
+    };
+    deletePushSubscription: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Deleted. */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            401: components["responses"]["UnauthorizedError"];
+            404: components["responses"]["NotFoundError"];
+            500: components["responses"]["ServerError"];
+        };
+    };
 }

package/dist/components/app/allow-reminders.d.ts

@@ -0,0 +1,9 @@
+import type { ReactNode } from 'react';
+import type { PushPermission } from '../../hooks/use-push-permission.js';
+export type AllowRemindersProps = {
+    push: PushPermission;
+    /** What reminders are for, in the app's words, shown before asking. */
+    description?: ReactNode;
+    className?: string;
+};
+export declare function AllowReminders({ push, description, className }: AllowRemindersProps): import("react").JSX.Element;

package/dist/components/app/allow-reminders.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { BellIcon, BellOffIcon } from 'lucide-react';
+import { cn } from 'cn';
+import { Button } from '../ui/button.js';
+import { Skeleton } from '../ui/skeleton.js';
+import { Notice } from './notice.js';
+const DEFAULT_DESCRIPTION = 'Get a notification on this device at the times you set, even when the app is closed. Your browser will ask first.';
+export function AllowReminders({ push, description = DEFAULT_DESCRIPTION, className }) {
+    const { status, pending, error } = push;
+    return (_jsxs("div", { "data-slot": "allow-reminders", className: cn('flex flex-col gap-3', className), "aria-busy": status === undefined || pending, children: [status === undefined && _jsx(Skeleton, { className: "h-9 w-full max-w-md" }), status === 'off' && (_jsxs(_Fragment, { children: [_jsx("p", { className: "text-sm text-foreground", children: description }), _jsx("div", { children: _jsxs(Button, { onClick: push.enable, disabled: pending, children: [_jsx(BellIcon, { "aria-hidden": "true" }), pending ? 'Turning on…' : 'Allow reminders'] }) })] })), status === 'on' && (_jsx(Notice, { tone: "success", icon: BellIcon, action: _jsxs(Button, { size: "sm", variant: "outline", onClick: push.disable, disabled: pending, children: [_jsx(BellOffIcon, { "aria-hidden": "true" }), pending ? 'Turning off…' : 'Turn off'] }), children: "Reminders are on for this device." })), status === 'needs-install' && (_jsx(Notice, { title: "Add the app to your Home Screen first", children: "On iPhone and iPad, reminders work in the app from the Home Screen. Tap Share, then Add to Home Screen, open the app from there and allow reminders." })), status === 'blocked' && (_jsx(Notice, { tone: "warning", title: "Notifications are blocked", icon: BellOffIcon, children: "This browser was told not to show this app\u2019s notifications. Allow them in the site\u2019s settings (the icon beside the address), then reload." })), status === 'unsupported' && (_jsx("p", { className: "text-sm text-muted-foreground", children: "This browser can\u2019t show reminders." })), status === 'mock' && (_jsx("p", { className: "text-sm text-muted-foreground", children: "Reminders need the real backend: with mock data nothing can send them." })), error && (_jsx("p", { role: "alert", className: "text-sm text-destructive-text", children: error }))] }));
+}

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 {};