@tristan2828/ui-foundation 4.16.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`. 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` | `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

@@ -96,6 +96,13 @@ routine) is built from the package's parts: `SessionView`,
 `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/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/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/index.d.ts

@@ -22,6 +22,7 @@ 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';
@@ -50,5 +51,6 @@ 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

@@ -27,6 +27,7 @@ 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';
@@ -55,6 +56,7 @@ 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/mocks/index.d.ts

@@ -1,5 +1,6 @@
 export { authHandlers, getMockCurrentUser, isMockAuthenticated, MOCK_PASSWORD, MOCK_RECOVERY_CODE, MOCK_TOTP_CODE, MOCK_TOTP_USER, MOCK_USER, resetMockAuth, setMockAuthenticated, } from './auth.js';
 export { clientErrorHandlers, getMockClientErrors, resetMockClientErrors } from './client-errors.js';
 export { environmentHandlers } from './environment.js';
+export { getMockPushSubscriptions, MOCK_PUSH_PUBLIC_KEY, pushHandlers, resetMockPush } from './push.js';
 export { exposeMswForE2E } from './e2e-hooks.js';
 export type { MswHandle, MswOverride } from './override.js';

package/dist/mocks/index.js

@@ -4,4 +4,5 @@
 export { authHandlers, getMockCurrentUser, isMockAuthenticated, MOCK_PASSWORD, MOCK_RECOVERY_CODE, MOCK_TOTP_CODE, MOCK_TOTP_USER, MOCK_USER, resetMockAuth, setMockAuthenticated, } from './auth.js';
 export { clientErrorHandlers, getMockClientErrors, resetMockClientErrors } from './client-errors.js';
 export { environmentHandlers } from './environment.js';
+export { getMockPushSubscriptions, MOCK_PUSH_PUBLIC_KEY, pushHandlers, resetMockPush } from './push.js';
 export { exposeMswForE2E } from './e2e-hooks.js';

package/dist/mocks/push.d.ts

@@ -0,0 +1,9 @@
+import type { components } from '../api/schema.js';
+type PushSubscriptionRequest = components['schemas']['PushSubscriptionRequest'];
+/** RFC 8291's example key: a valid P-256 point, and nobody's real one. */
+export declare const MOCK_PUSH_PUBLIC_KEY = "BP4z9KsN6nGRTbVYI_c7VJSPQTBtkgcy27mlmlMoZIIgDll6e3vCYLocInmYWAmS6TlzAC8wEqKK6PBru3jl7A8";
+/** What POST /push/subscriptions has saved since the last reset. */
+export declare function getMockPushSubscriptions(): readonly PushSubscriptionRequest[];
+export declare function resetMockPush(): void;
+export declare const pushHandlers: import("msw").HttpHandler[];
+export {};

package/dist/mocks/push.js

@@ -0,0 +1,40 @@
+// MSW handlers for /push/* (openapi/foundation.yaml), for an app whose
+// contract has them. Like the reference backend they need the mock
+// session, and a device subscribing again gets its id back. Nothing is
+// ever sent: under MSW, usePushPermission reads 'mock' and never
+// subscribes, since MSW's own worker holds the page.
+import { http, HttpResponse } from 'msw';
+import { isMockAuthenticated } from './auth.js';
+/** RFC 8291's example key: a valid P-256 point, and nobody's real one. */
+export const MOCK_PUSH_PUBLIC_KEY = 'BP4z9KsN6nGRTbVYI_c7VJSPQTBtkgcy27mlmlMoZIIgDll6e3vCYLocInmYWAmS6TlzAC8wEqKK6PBru3jl7A8';
+let subscriptions = new Map();
+let nextId = 1;
+/** What POST /push/subscriptions has saved since the last reset. */
+export function getMockPushSubscriptions() {
+    return [...subscriptions.values()].map(({ request }) => request);
+}
+export function resetMockPush() {
+    subscriptions = new Map();
+    nextId = 1;
+}
+const unauthorized = () => HttpResponse.json({ detail: 'Not authenticated' }, { status: 401 });
+export const pushHandlers = [
+    http.get('*/api/push/public-key', () => isMockAuthenticated() ? HttpResponse.json({ publicKey: MOCK_PUSH_PUBLIC_KEY }) : unauthorized()),
+    http.post('*/api/push/subscriptions', async ({ request }) => {
+        if (!isMockAuthenticated())
+            return unauthorized();
+        const body = (await request.json());
+        const id = subscriptions.get(body.endpoint)?.id ?? nextId++;
+        subscriptions.set(body.endpoint, { id, request: body });
+        return HttpResponse.json({ id }, { status: 201 });
+    }),
+    http.delete('*/api/push/subscriptions/:id', ({ params }) => {
+        if (!isMockAuthenticated())
+            return unauthorized();
+        const entry = [...subscriptions.entries()].find(([, value]) => String(value.id) === params.id);
+        if (!entry)
+            return HttpResponse.json({ detail: 'No such subscription.' }, { status: 404 });
+        subscriptions.delete(entry[0]);
+        return new HttpResponse(null, { status: 204 });
+    }),
+];

package/openapi/foundation.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: UI Foundation — the contract every app shares
-  version: "4.1.0"
+  version: "4.17.0"
   description: >
     The part of an app's API contract that the foundation package's own code
     calls: session-cookie auth under /auth/*, and the two error envelopes the
@@ -13,8 +13,8 @@ info:
 
     A path marked `x-optional: true` may be left out of an app's spec (an
     app without self-service sign-up omits /auth/register, an app that
-    doesn't render DataEnvironmentBanner omits /environment), but if
-    present it must match.
+    doesn't render DataEnvironmentBanner omits /environment, an app without
+    reminders omits /push/*), but if present it must match.
 
 servers:
   - url: /api
@@ -161,6 +161,68 @@ paths:
         "422": { $ref: "#/components/responses/ValidationError" }
         "500": { $ref: "#/components/responses/ServerError" }
 
+  /push/public-key:
+    x-optional: true
+    get:
+      operationId: getPushPublicKey
+      summary: The app's VAPID public key, which a browser subscribes to push with
+      description: >
+        For usePushPermission. 404 when the backend has push turned off.
+      tags: [push]
+      responses:
+        "200":
+          description: OK.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/PushPublicKey" }
+        "401": { $ref: "#/components/responses/UnauthorizedError" }
+        "404": { $ref: "#/components/responses/NotFoundError" }
+        "500": { $ref: "#/components/responses/ServerError" }
+
+  /push/subscriptions:
+    x-optional: true
+    post:
+      operationId: savePushSubscription
+      summary: 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.
+      tags: [push]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/PushSubscriptionRequest" }
+      responses:
+        "201":
+          description: Saved.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/PushSubscriptionCreated" }
+        "401": { $ref: "#/components/responses/UnauthorizedError" }
+        "404": { $ref: "#/components/responses/NotFoundError" }
+        "422": { $ref: "#/components/responses/ValidationError" }
+        "500": { $ref: "#/components/responses/ServerError" }
+
+  /push/subscriptions/{id}:
+    x-optional: true
+    delete:
+      operationId: deletePushSubscription
+      summary: Stop sending to one of the signed-in user's devices
+      tags: [push]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema: { type: integer }
+      responses:
+        "204":
+          description: Deleted.
+        "401": { $ref: "#/components/responses/UnauthorizedError" }
+        "404": { $ref: "#/components/responses/NotFoundError" }
+        "500": { $ref: "#/components/responses/ServerError" }
+
 components:
   schemas:
     DataEnvironment:
@@ -235,6 +297,40 @@ components:
         status: { type: integer, minimum: 100, maximum: 599, description: The HTTP status of a failed request. }
         release: { type: string, maxLength: 100, description: The frontend build (its commit). }
 
+    PushPublicKey:
+      type: object
+      required: [publicKey]
+      properties:
+        publicKey:
+          type: string
+          minLength: 1
+          description: The P-256 public key, base64url (applicationServerKey).
+
+    PushSubscriptionRequest:
+      type: object
+      required: [endpoint, keys]
+      properties:
+        endpoint:
+          type: string
+          minLength: 1
+          maxLength: 2048
+          description: The push service's URL for this device.
+        expirationTime:
+          type: ["number", "null"]
+          description: Milliseconds since the epoch, sent by some browsers, ignored.
+        keys:
+          type: object
+          required: [p256dh, auth]
+          properties:
+            p256dh: { type: string, minLength: 1, maxLength: 100 }
+            auth: { type: string, minLength: 1, maxLength: 32 }
+
+    PushSubscriptionCreated:
+      type: object
+      required: [id]
+      properties:
+        id: { type: integer }
+
     ValidationErrorBody:
       type: object
       description: FastAPI's default 422 shape (RequestValidationError).

package/package.json

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

package/vite/index.d.ts

@@ -24,3 +24,30 @@ export type BuildInfoOptions = {
  * `BUILD_REPO_URL`.
  */
 export default function buildInfo(options?: BuildInfoOptions): Plugin
+
+export type PwaOptions = {
+  /** The app's name, as the Home Screen and the install prompt show it. */
+  name: string
+  /** A shorter one for under the icon. Defaults to `name`; its first letter is the SVG icon's. */
+  shortName?: string
+  description?: string
+  /** `#rrggbb`. Defaults to the package's `--primary` token. */
+  themeColor?: string
+  /** The letter's colour on the SVG icon, `#rrggbb`. Defaults to `--primary-foreground`. */
+  themeForegroundColor?: string
+  /** The splash screen's, `#rrggbb`. Defaults to `--background`. */
+  backgroundColor?: string
+  /**
+   * The app's own icon, a square PNG of at least 512×512 (path from the Vite
+   * root). Replaces the generated ones everywhere.
+   */
+  icon?: string
+}
+
+/**
+ * Makes the app installable and receives reminders: serves and builds
+ * `/manifest.webmanifest`, `/icons/*` and `/push-sw.js` (the service worker
+ * usePushPermission registers), and adds the manifest, theme-color and
+ * apple-touch-icon tags to index.html.
+ */
+export function pwa(options: PwaOptions): Plugin

package/vite/index.js

@@ -26,6 +26,8 @@
 import fs from 'node:fs'
 import path from 'node:path'
 
+export { pwa } from './pwa.js'
+
 const OWN_FIELDS = ['api', 'commit', 'pr', 'builtAt', 'schema']
 
 /** @param {string | undefined} value */

package/vite/push-sw.js

@@ -0,0 +1,46 @@
+// The app's service worker, written by pwa() (./index.js) as /push-sw.js.
+// Push and notification clicks only: no fetch handler, so it never caches
+// the app or stands between it and Vite's hashed files. Registered by
+// usePushPermission's enable(), not on load. ICON is set by pwa().
+/* global self, clients */
+const ICON = '__ICON__'
+
+self.addEventListener('install', () => self.skipWaiting())
+self.addEventListener('activate', (event) => event.waitUntil(self.clients.claim()))
+
+// app/push.py sends {title, body, url, tag}. Anything else still shows.
+self.addEventListener('push', (event) => {
+  let data = {}
+  try {
+    data = event.data ? event.data.json() : {}
+  } catch {
+    data = { body: event.data ? event.data.text() : '' }
+  }
+  const options = { body: data.body || '', icon: ICON, data: { url: data.url || '/' } }
+  if (data.tag) options.tag = data.tag
+  event.waitUntil(self.registration.showNotification(data.title || 'Reminder', options))
+})
+
+// Opens the message's path in the app: in a window already open on the
+// app if there is one, else a new one. Never another site.
+self.addEventListener('notificationclick', (event) => {
+  event.notification.close()
+  const target = new URL((event.notification.data && event.notification.data.url) || '/', self.location.origin)
+  if (target.origin !== self.location.origin) return
+  event.waitUntil(
+    (async () => {
+      const windows = await clients.matchAll({ type: 'window', includeUncontrolled: true })
+      const open = windows.find((client) => new URL(client.url).origin === target.origin)
+      if (open) {
+        await open.focus()
+        try {
+          await open.navigate(target.href)
+          return
+        } catch {
+          // An uncontrolled window can't be navigated from here.
+        }
+      }
+      await clients.openWindow(target.href)
+    })(),
+  )
+})

package/vite/pwa.d.ts

@@ -0,0 +1,18 @@
+// The helpers behind pwa(), typed for the package's own tests. Apps use
+// `pwa` from `@tristan2828/ui-foundation/vite` (./index.d.ts).
+import type { HtmlTagDescriptor, Plugin } from 'vite'
+import type { PwaOptions } from './index'
+
+export function themeToken(css: string, name: string): string
+export function oklchToHex(value: string): string
+export function solidPng(size: number, hex: string): Buffer
+export function letterSvg(name: string, background: string, foreground: string): string
+export function pwaFiles(
+  options: PwaOptions,
+  base?: string,
+  root?: string,
+): {
+  files: Map<string, { type: string; source: string | Buffer }>
+  tags: (HtmlTagDescriptor & { attrs: Record<string, string> })[]
+}
+export function pwa(options: PwaOptions): Plugin

package/vite/pwa.js

@@ -0,0 +1,230 @@
+// `pwa()` from `@tristan2828/ui-foundation/vite`: the app installable (a web
+// manifest and icons) and the service worker reminders arrive through
+// (issue #167). An app's vite.config.ts:
+//
+//   import buildInfo, { pwa } from '@tristan2828/ui-foundation/vite'
+//   plugins: [react(), tailwindcss(), buildInfo(), pwa({ name: 'Morning Routines', shortName: 'Routines' })]
+//
+// Serves and builds, at the site root:
+// - /manifest.webmanifest: the name, `display: standalone` (which iOS needs
+//   before push works there), and the theme's colours.
+// - /icons/: an SVG with the name's first letter (Chrome, Android) and
+//   plain PNGs in the theme colour (iOS's Home Screen icon must be a PNG,
+//   and drawing a letter into one needs a font rasteriser the package
+//   doesn't carry). `icon` replaces them all with the app's own PNG.
+// - /push-sw.js: ./push-sw.js, showing pushes and opening their path.
+// And adds the manifest, theme-color and apple-touch-icon tags to
+// index.html. Registering the worker is usePushPermission's, on a click.
+//
+// Colours default to the package's tokens (styles/theme.css: --primary,
+// --primary-foreground, --background), converted to hex as a manifest
+// needs. An app that changed its tokens passes its own.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import zlib from 'node:zlib'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const THEME_CSS = path.join(HERE, '..', 'styles', 'theme.css')
+const WORKER_SOURCE = path.join(HERE, 'push-sw.js')
+const HEX = /^#[0-9a-f]{6}$/i
+
+// ------------------------------------------------------------- colours
+
+/** The value of `--name` in theme.css's :root block, var() followed. */
+export function themeToken(css, name, seen = new Set()) {
+  const root = css.slice(css.indexOf(':root'), css.indexOf('.dark'))
+  const match = new RegExp(`--${name}:\\s*([^;]+);`).exec(root)
+  if (!match) throw new Error(`pwa: no --${name} in the theme.`)
+  const value = match[1].trim()
+  const reference = /^var\(--([\w-]+)\)$/.exec(value)
+  if (!reference) return value
+  if (seen.has(name)) throw new Error(`pwa: --${name} refers to itself.`)
+  seen.add(name)
+  return themeToken(css, reference[1], seen)
+}
+
+/** `oklch(L C H)` → `#rrggbb` (sRGB, clipped). */
+export function oklchToHex(value) {
+  const match = /^oklch\(\s*([\d.]+)(%?)\s+([\d.]+)\s+([\d.]+)(?:deg)?\s*\)$/.exec(value.trim())
+  if (!match) throw new Error(`pwa: can't read ${value} as oklch(L C H); pass the colour as #rrggbb.`)
+  const l = Number(match[1]) / (match[2] ? 100 : 1)
+  const c = Number(match[3])
+  const h = (Number(match[4]) * Math.PI) / 180
+  const a = c * Math.cos(h)
+  const b = c * Math.sin(h)
+  // OKLab → LMS (cubed) → linear sRGB (Björn Ottosson's matrices).
+  const l_ = (l + 0.3963377774 * a + 0.2158037573 * b) ** 3
+  const m_ = (l - 0.1055613458 * a - 0.0638541728 * b) ** 3
+  const s_ = (l - 0.0894841775 * a - 1.291485548 * b) ** 3
+  const linear = [
+    4.0767416621 * l_ - 3.3077115913 * m_ + 0.2309699292 * s_,
+    -1.2684380046 * l_ + 2.6097574011 * m_ - 0.3413193965 * s_,
+    -0.0041960863 * l_ - 0.7034186147 * m_ + 1.707614701 * s_,
+  ]
+  const toByte = (x) => {
+    const clipped = Math.min(1, Math.max(0, x))
+    const gamma = clipped <= 0.0031308 ? 12.92 * clipped : 1.055 * clipped ** (1 / 2.4) - 0.055
+    return Math.round(gamma * 255)
+  }
+  return `#${linear.map((x) => toByte(x).toString(16).padStart(2, '0')).join('')}`
+}
+
+function colour(value, token) {
+  if (value !== undefined) {
+    if (!HEX.test(value)) throw new Error(`pwa: ${token} must be #rrggbb, not ${value}.`)
+    return value.toLowerCase()
+  }
+  return oklchToHex(themeToken(fs.readFileSync(THEME_CSS, 'utf8'), token))
+}
+
+// ---------------------------------------------------------------- icons
+
+const CRC_TABLE = Array.from({ length: 256 }, (_, n) => {
+  let c = n
+  for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1
+  return c >>> 0
+})
+
+function crc32(bytes) {
+  let crc = 0xffffffff
+  for (const byte of bytes) crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8)
+  return (crc ^ 0xffffffff) >>> 0
+}
+
+function chunk(type, data) {
+  const length = Buffer.alloc(4)
+  length.writeUInt32BE(data.length)
+  const body = Buffer.concat([Buffer.from(type, 'ascii'), data])
+  const crc = Buffer.alloc(4)
+  crc.writeUInt32BE(crc32(body))
+  return Buffer.concat([length, body, crc])
+}
+
+/** A `size`×`size` PNG of one colour (#rrggbb). */
+export function solidPng(size, hex) {
+  const rgb = [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16))
+  const header = Buffer.alloc(13)
+  header.writeUInt32BE(size, 0)
+  header.writeUInt32BE(size, 4)
+  header.set([8, 2, 0, 0, 0], 8) // 8-bit RGB, no interlace
+  const row = Buffer.alloc(1 + size * 3) // filter byte 0, then the pixels
+  for (let x = 0; x < size; x++) row.set(rgb, 1 + x * 3)
+  const pixels = zlib.deflateSync(Buffer.concat(Array.from({ length: size }, () => row)))
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk('IHDR', header),
+    chunk('IDAT', pixels),
+    chunk('IEND', Buffer.alloc(0)),
+  ])
+}
+
+const escapeXml = (text) =>
+  text.replace(/[<>&'"]/g, (ch) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', "'": '&apos;', '"': '&quot;' })[ch])
+
+/** A square SVG: the name's first letter on the theme colour. */
+export function letterSvg(name, background, foreground) {
+  const letter = escapeXml([...name.trim()][0]?.toUpperCase() ?? '')
+  return (
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">` +
+    `<rect width="512" height="512" fill="${background}"/>` +
+    `<text x="256" y="256" dominant-baseline="central" text-anchor="middle" ` +
+    `font-family="system-ui, -apple-system, 'Segoe UI', sans-serif" font-size="288" font-weight="600" ` +
+    `fill="${foreground}">${letter}</text></svg>\n`
+  )
+}
+
+// --------------------------------------------------------------- plugin
+
+/**
+ * Everything pwa() serves, by path from the site root, for `base`.
+ * @param {import('./index').PwaOptions} options
+ */
+export function pwaFiles(options, base = '/', root = process.cwd()) {
+  if (!options?.name?.trim()) throw new Error('pwa: `name` is required (the app as the Home Screen names it).')
+  const name = options.name.trim()
+  const shortName = options.shortName?.trim() || name
+  const theme = colour(options.themeColor, 'primary')
+  const onTheme = colour(options.themeForegroundColor, 'primary-foreground')
+  const background = colour(options.backgroundColor, 'background')
+  const at = (file) => `${base}${file}`
+
+  /** @type {Map<string, { type: string, source: string | Buffer }>} */
+  const files = new Map()
+  let icons
+  let touchIcon
+  if (options.icon) {
+    const own = path.resolve(root, options.icon)
+    if (!own.endsWith('.png') || !fs.existsSync(own)) throw new Error(`pwa: icon must be a PNG file; ${own} isn't one.`)
+    files.set('icons/icon.png', { type: 'image/png', source: fs.readFileSync(own) })
+    icons = [{ src: at('icons/icon.png'), sizes: '512x512', type: 'image/png', purpose: 'any' }]
+    touchIcon = 'icons/icon.png'
+  } else {
+    files.set('icons/icon.svg', { type: 'image/svg+xml', source: letterSvg(shortName, theme, onTheme) })
+    for (const size of [192, 512]) files.set(`icons/icon-${size}.png`, { type: 'image/png', source: solidPng(size, theme) })
+    files.set('icons/apple-touch-icon.png', { type: 'image/png', source: solidPng(180, theme) })
+    icons = [
+      { src: at('icons/icon.svg'), sizes: 'any', type: 'image/svg+xml', purpose: 'any' },
+      { src: at('icons/icon-192.png'), sizes: '192x192', type: 'image/png', purpose: 'any' },
+      { src: at('icons/icon-512.png'), sizes: '512x512', type: 'image/png', purpose: 'any' },
+      // One colour edge to edge: safe to crop to any mask shape.
+      { src: at('icons/icon-512.png'), sizes: '512x512', type: 'image/png', purpose: 'maskable' },
+    ]
+    touchIcon = 'icons/apple-touch-icon.png'
+  }
+  const manifest = {
+    name,
+    short_name: shortName,
+    ...(options.description ? { description: options.description } : {}),
+    start_url: base,
+    scope: base,
+    display: 'standalone',
+    theme_color: theme,
+    background_color: background,
+    icons,
+  }
+  files.set('manifest.webmanifest', {
+    type: 'application/manifest+json',
+    source: `${JSON.stringify(manifest, null, 2)}\n`,
+  })
+  const worker = fs.readFileSync(WORKER_SOURCE, 'utf8').replace('__ICON__', options.icon ? at('icons/icon.png') : at('icons/icon-192.png'))
+  files.set('push-sw.js', { type: 'text/javascript', source: worker })
+  return {
+    files,
+    tags: [
+      { tag: 'link', attrs: { rel: 'manifest', href: at('manifest.webmanifest') }, injectTo: 'head' },
+      { tag: 'meta', attrs: { name: 'theme-color', content: theme }, injectTo: 'head' },
+      { tag: 'link', attrs: { rel: 'apple-touch-icon', href: at(touchIcon) }, injectTo: 'head' },
+    ],
+  }
+}
+
+/** @param {import('./index').PwaOptions} options */
+export function pwa(options) {
+  if (!options?.name?.trim()) throw new Error('pwa: `name` is required (the app as the Home Screen names it).')
+  /** @type {ReturnType<typeof pwaFiles>} */
+  let built
+  return {
+    name: 'ui-foundation:pwa',
+    configResolved(config) {
+      built = pwaFiles(options, config.base, config.root)
+    },
+    configureServer(server) {
+      server.middlewares.use((req, res, next) => {
+        const base = server.config.base
+        const url = (req.url ?? '').split('?')[0]
+        const file = url.startsWith(base) ? built.files.get(url.slice(base.length)) : undefined
+        if (!file) return next()
+        res.setHeader('Content-Type', file.type)
+        res.end(file.source)
+      })
+    },
+    transformIndexHtml() {
+      return built.tags
+    },
+    generateBundle() {
+      for (const [fileName, file] of built.files) this.emitFile({ type: 'asset', fileName, source: file.source })
+    },
+  }
+}