@marinoscar/platform-web 0.1.0-next.3 → 0.1.0-next.5

package/dist/host/ui/maintenance-page.js

@@ -0,0 +1,179 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * Admin → Settings → Maintenance (`/admin/settings/maintenance`).
+ *
+ * Issue #258, epic #254. A REGISTRY CARD and nothing else, per `CLAUDE.md`'s
+ * MANDATORY Settings UI Pattern: one entry in `ADMIN_SECTIONS`
+ * (`config/adminSections.tsx`), one route in `App.tsx` gated on the same
+ * permission string, and no tab anywhere. The hub, the Console rail and the
+ * compact AppBar title all pick this page up from that single declaration.
+ *
+ * It is deliberately NOT a section or a tab on another settings page: a tab
+ * gate is about CONTENT within one destination, and this is a destination of
+ * its own — the one screen an operator navigates straight to during an
+ * incident.
+ *
+ * WHY IT DOES NOT USE `SystemSettingsSection` (the render-prop wrapper
+ * `NotificationSettingsPage` uses). That component is bound to
+ * `useSystemSettings`: it loads the whole system settings document and PATCHes
+ * one branch of it. The maintenance window is a different controller with a response this page exists
+ * to render — `source` and `layers`, which the settings document does not carry
+ * — and a write that must be a `PUT` of `{ enabled, … }` so the API can stamp
+ * the window's provenance. `EmailSettingsPage` (#124) made the same departure
+ * for the same reason, and what is shared is the CHROME, reproduced here field
+ * for field: container, `h4` title, mirrored card description, "(read-only)"
+ * suffix, `Paper` body, save snackbar.
+ *
+ * =============================================================================
+ * THE LAYERS ARE THE POINT OF THIS PAGE, NOT DECORATION
+ * =============================================================================
+ *
+ * A switch would have been three lines. "I turned it off and it is still on" is
+ * the question an operator asks at the worst possible moment, and its honest
+ * answer — "because `MAINTENANCE_MODE=true` is still in this deployment's
+ * environment, and it outranks the row you just wrote" — is invisible unless
+ * every contributing layer is on screen next to the effective state. The API
+ * publishes all three for exactly this reason; a page that rendered only
+ * `enabled` would throw that away and send the operator to a shell.
+ *
+ * =============================================================================
+ * WHAT AN ENVIRONMENT OVERRIDE DISABLES, AND WHAT IT DOES NOT
+ * =============================================================================
+ *
+ * `MAINTENANCE_MODE` carries a BOOLEAN AND NOTHING ELSE. In
+ * `MaintenanceModeService.resolve` the env layer decides `enabled`, while
+ * `message` and `allowAdmins` are resolved independently from the highest layer
+ * that actually supplies them — which, with no in-memory override, is the
+ * persisted row this page writes.
+ *
+ * So an env override disables the ON/OFF SWITCH ONLY. Greying the whole form
+ * out would be the easy gesture and the wrong one: it would stop an operator
+ * preparing the message and the `allowAdmins` value that take effect the moment
+ * the variable is removed — and those are the settings that a window forced
+ * open from the environment is *still using right now*.
+ */
+import { useEffect, useState } from 'react';
+import { Alert, AlertTitle, Box, Button, Chip, Container, Divider, FormControlLabel, Paper, Snackbar, Stack, Switch, TextField, Typography, } from '@mui/material';
+import { Navigate } from 'react-router-dom';
+import { PageSlotsFrame } from '../../core/index.js';
+import { usePermissions } from '../../identity/index.js';
+import { isDecidingLayer } from '../headless/maintenance-block.js';
+import { useMaintenance } from '../headless/use-maintenance.js';
+import { LoadingSpinner } from './loading-spinner.js';
+/** Mirrors the `Maintenance` card in `config/adminSections.tsx`, word for word. */
+const PAGE_TITLE = 'Maintenance';
+const PAGE_DESCRIPTION = 'Take the application out of service for planned work, with a message for anyone who tries to use it.';
+/** The API's own ceiling on the message (`systemMaintenanceSchema`, `.max(1000)`). */
+const MAX_MESSAGE_LENGTH = 1000;
+function toFormState(status) {
+    return {
+        // The EFFECTIVE values, not `layers.persisted.value`. With no override the
+        // two agree; with one, showing the persisted row would put a switch reading
+        // "off" above a banner saying the application is out of service.
+        enabled: status.enabled,
+        message: status.message,
+        allowAdmins: status.allowAdmins,
+    };
+}
+/** Human copy for `source`. Never rendered as the raw enum — an operator is not reading a DTO. */
+const SOURCE_LABEL = {
+    env: 'Environment variable',
+    memory: 'Server task',
+    persisted: 'Saved setting',
+};
+/**
+ * One layer, with a badge on whichever one is winning.
+ *
+ * The badge is the single most useful pixel on this page: it converts "here are
+ * three values, work it out" into "this one is the answer", which is the whole
+ * difference between the layers being diagnostic and being noise.
+ */
+function LayerRow({ label, deciding, children }) {
+    return (_jsxs(Box, { sx: { py: 1.5 }, children: [_jsxs(Stack, { direction: "row", spacing: 1, sx: { alignItems: 'center', flexWrap: 'wrap' }, children: [_jsx(Typography, { variant: "subtitle2", children: label }), deciding && _jsx(Chip, { size: "small", color: "primary", label: "Deciding" })] }), _jsx(Typography, { variant: "body2", color: "text.secondary", children: children })] }));
+}
+/**
+ * Admin → Settings → Maintenance: open or close the maintenance window, with
+ * every contributing layer (environment, server task, saved setting) shown
+ * beside the effective state. Redirects to `/` without `system_settings:read`;
+ * the controls are disabled without `system_settings:write`.
+ *
+ * @returns the page element.
+ *
+ * @example
+ * ```tsx
+ * <Route path="/admin/settings/maintenance" element={<RequirePermission permission="system_settings:read"><MaintenancePage /></RequirePermission>} />
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export function MaintenancePage(props = {}) {
+    const { slots } = props;
+    const { hasPermission } = usePermissions();
+    const { status, isLoading, loadError, isSaving, saveError, save } = useMaintenance();
+    const [form, setForm] = useState(null);
+    const [savedMessage, setSavedMessage] = useState(null);
+    // Re-seed from the server's answer whenever it changes — on load, and after a
+    // save. The response is the baseline, never the input: an env override can
+    // make the state after a write differ from what was written, and the operator
+    // must be shown what is true rather than what they asked for.
+    useEffect(() => {
+        if (status)
+            setForm(toFormState(status));
+    }, [status]);
+    // Defence, not the gate — `App.tsx` wraps the route in `RequirePermission`
+    // with this same string, exactly as every sibling admin page does. This
+    // catches the page mounted from anywhere else, and sits after every hook so
+    // the hook order never changes.
+    if (!hasPermission('system_settings:read')) {
+        return _jsx(Navigate, { to: "/", replace: true });
+    }
+    const canWrite = hasPermission('system_settings:write');
+    if (isLoading || (!form && !loadError)) {
+        return _jsx(LoadingSpinner, {});
+    }
+    const envOverride = status?.layers.env;
+    // The environment decides ON/OFF and nothing else — see the file header.
+    const enabledLocked = !!envOverride?.present;
+    const messageTooLong = !!form && form.message.trim().length > MAX_MESSAGE_LENGTH;
+    const messageEmpty = !!form && form.message.trim().length === 0;
+    const isDirty = !!form && !!status && JSON.stringify(form) !== JSON.stringify(toFormState(status));
+    const update = (key, value) => {
+        setForm((prev) => (prev ? { ...prev, [key]: value } : prev));
+    };
+    const handleSubmit = async (event) => {
+        event.preventDefault();
+        if (!form || !canWrite || messageTooLong || messageEmpty)
+            return;
+        const ok = await save({
+            enabled: form.enabled,
+            message: form.message.trim(),
+            allowAdmins: form.allowAdmins,
+        });
+        if (ok)
+            setSavedMessage('Maintenance settings saved');
+    };
+    return (_jsx(Container, { maxWidth: "lg", children: _jsxs(Box, { sx: { py: 4 }, children: [_jsxs(PageSlotsFrame, { slots: slots, headerProps: { title: PAGE_TITLE, description: PAGE_DESCRIPTION, readOnly: !canWrite, actions: null }, header: _jsxs(_Fragment, { children: [_jsx(Typography, { variant: "h4", component: "h1", gutterBottom: true, children: PAGE_TITLE }), _jsxs(Typography, { color: "text.secondary", sx: { mb: 3 }, children: [PAGE_DESCRIPTION, !canWrite && ' (read-only)'] })] }), children: [loadError && (_jsx(Alert, { severity: "error", sx: { mb: 3 }, children: loadError })), saveError && (_jsx(Alert, { severity: "error", sx: { mb: 3 }, children: saveError })), status && form && (_jsxs(_Fragment, { children: [_jsxs(Alert, { severity: status.enabled ? 'warning' : 'success', sx: { mb: 3 }, children: [_jsx(AlertTitle, { children: status.enabled
+                                                ? 'Maintenance mode is ON — the application is out of service'
+                                                : 'Maintenance mode is off — the application is serving normally' }), _jsxs(Stack, { spacing: 0.5, children: [_jsxs("span", { children: ["Decided by: ", _jsx("strong", { children: SOURCE_LABEL[status.source] })] }), status.enabled && (_jsx("span", { children: status.allowAdmins
+                                                        ? 'Administrators keep access; everyone else is turned away.'
+                                                        : 'Everyone is turned away, administrators included.' })), status.startedAt && (_jsxs("span", { children: ["Opened ", new Date(status.startedAt).toLocaleString()] }))] })] }), enabledLocked && (_jsxs(Alert, { severity: "info", sx: { mb: 3 }, children: [_jsxs(AlertTitle, { children: ["This deployment\u2019s environment is forcing maintenance mode", ' ', envOverride?.enabled ? 'ON' : 'OFF'] }), _jsxs("span", { children: ["The ", _jsx("code", { children: "MAINTENANCE_MODE" }), " variable outranks anything saved here, so the switch below cannot change what the application does. Remove the variable from the environment and restart the API to hand control back to this page. The message and administrator access below still apply and can still be edited."] })] })), _jsx(Paper, { sx: { p: { xs: 2, sm: 3 }, mb: 3 }, children: _jsxs(Box, { component: "form", onSubmit: handleSubmit, noValidate: true, children: [_jsx(FormControlLabel, { control: _jsx(Switch, { checked: form.enabled, onChange: (e) => update('enabled', e.target.checked), 
+                                                    // Disabled by an env override as well as by permission:
+                                                    // a control that accepted a change it cannot make would
+                                                    // be a lie the operator only discovers after saving.
+                                                    disabled: !canWrite || isSaving || enabledLocked, slotProps: { input: { 'aria-label': 'Maintenance mode' } } }), label: "Turn maintenance mode on" }), _jsx(Typography, { variant: "body2", color: "text.secondary", sx: { ml: 4, mb: 2 }, children: "Every API request answers 503 with the message below, except signing in, signing out and this page." }), _jsx(Divider, { sx: { my: 3 } }), _jsx(TextField, { fullWidth: true, multiline: true, minRows: 3, label: "Message shown to users", value: form.message, onChange: (e) => update('message', e.target.value), disabled: !canWrite || isSaving, error: messageTooLong || messageEmpty, helperText: messageEmpty
+                                                    ? 'A message is required — it is the only thing a blocked user is told.'
+                                                    : messageTooLong
+                                                        ? `Keep the message to ${MAX_MESSAGE_LENGTH} characters or fewer.`
+                                                        : 'Shown verbatim on the maintenance screen. Say what is happening and when you expect to be back.' }), _jsx(FormControlLabel, { sx: { mt: 2 }, control: _jsx(Switch, { checked: form.allowAdmins, onChange: (e) => update('allowAdmins', e.target.checked), disabled: !canWrite || isSaving, slotProps: { input: { 'aria-label': 'Allow administrators' } } }), label: "Let administrators keep using the application" }), !form.allowAdmins && (_jsxs(Alert, { severity: "warning", sx: { mt: 1 }, children: ["With this off, administrators are turned away too. This page and signing in stay reachable, but if that is ever not enough the only way back is to set ", _jsx("code", { children: "MAINTENANCE_MODE=false" }), " in the environment and restart."] })), _jsx(Box, { sx: { mt: 3 }, children: _jsx(Button, { type: "submit", variant: "contained", disabled: !canWrite || isSaving || !isDirty || messageTooLong || messageEmpty, children: isSaving ? 'Saving...' : 'Save Changes' }) })] }) }), _jsxs(Paper, { sx: { p: { xs: 2, sm: 3 } }, children: [_jsx(Typography, { variant: "h6", gutterBottom: true, children: "Where this setting comes from" }), _jsx(Typography, { variant: "body2", color: "text.secondary", sx: { mb: 1 }, children: "Three layers can turn maintenance mode on, and the first one that has an answer wins. This is what each of them currently says." }), _jsxs(Stack, { divider: _jsx(Divider, { flexItem: true }), children: [_jsx(LayerRow, { label: "1. Environment variable", deciding: isDecidingLayer(status, 'env'), children: status.layers.env.present
+                                                        ? `MAINTENANCE_MODE is set to “${status.layers.env.enabled}”, forcing maintenance mode ${status.layers.env.enabled ? 'on' : 'off'}.`
+                                                        : 'MAINTENANCE_MODE is not set, so this layer has no opinion.' }), _jsx(LayerRow, { label: "2. Server task", deciding: isDecidingLayer(status, 'memory'), children: status.layers.memory.present
+                                                        ? `A task running on the API has taken the window (${status.layers.memory.override?.enabled ? 'on' : 'off'}). It is held in memory only and is released when the task finishes.`
+                                                        : 'No task on the API is holding the window.' }), _jsx(LayerRow, { label: "3. Saved setting", deciding: isDecidingLayer(status, 'persisted'), children: status.layers.persisted.readable
+                                                        ? `Saved as ${status.layers.persisted.value.enabled ? 'on' : 'off'}, administrators ${status.layers.persisted.value.allowAdmins ? 'allowed' : 'not allowed'}. This is the layer the form above writes.`
+                                                        : // Named plainly, because it changes what the values above
+                                                            // mean: the API could not read the row and is reporting
+                                                            // the last state it saw.
+                                                            'The saved setting could not be read, so the values shown are the last ones the API saw. This is expected while a database restore is in progress.' })] })] })] }))] }), _jsx(Snackbar, { open: !!savedMessage, autoHideDuration: 3000, onClose: () => setSavedMessage(null), message: savedMessage })] }) }));
+}
+//# sourceMappingURL=maintenance-page.js.map

package/dist/host/ui/maintenance-page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance-page.js","sourceRoot":"","sources":["../../../src/host/ui/maintenance-page.tsx"],"names":[],"mappings":"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"}

package/dist/host/ui/maintenance-screen.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The maintenance screen — issue #258, epic #254.
+ *
+ * What a user sees INSTEAD of the generic error, when and only when the API has
+ * answered a `503` carrying `details.reason === 'MAINTENANCE_MODE'`. That
+ * condition is decided in exactly one place (`maintenance-block.ts`,
+ * consumed by the app's HTTP client), and it is the whole reason this page is
+ * allowed to exist: without the marker, a page saying "we will be back shortly"
+ * would be an unverifiable guess that would also appear the day the API simply
+ * crashed. `MaintenanceGate` is what chooses between this page and the
+ * application; an unmarked 503 never reaches here.
+ *
+ * NOT A ROUTE. There is deliberately no `/maintenance` path: the URL a user
+ * asked for is still the URL they want, and redirecting them off it would cost
+ * them their place for a window that may be over in two minutes. Rendering in
+ * place means the retry below resumes exactly where they were.
+ *
+ * MOUNTED OUTSIDE `Layout`, so there is no AppBar, no rail and no bell — every
+ * one of which is a control that would 503 the moment it was touched.
+ */
+import type { ReactNode } from 'react';
+import type { MaintenanceBlock } from '../headless/maintenance-block.js';
+/**
+ * Props of {@link MaintenanceScreen}.
+ *
+ * @stability experimental
+ */
+export interface MaintenanceScreenProps {
+    /** The product name, as the heading says it: "<appName> is under maintenance". */
+    appName: string;
+    /** What the API said when it refused the request. */
+    block: MaintenanceBlock;
+    /**
+     * Forget the block and let the application render again.
+     *
+     * The children remount when the gate swaps back, so their own effects re-run
+     * and re-issue the requests that failed. That is why retrying needs no
+     * `window.location.reload()`: a full reload would discard the in-memory
+     * access token and send the user back through sign-in for a window that may
+     * already be over.
+     */
+    onRetry: () => void;
+    /**
+     * Replaces the wrench icon above the heading (the app's logo). Drawn inside
+     * the same centred block, so give it its own size; omitted, the icon the
+     * screen always had.
+     */
+    logo?: ReactNode;
+    /**
+     * Extra controls after "Try again" and the retry-after note (a status page
+     * link, a support address). Omitted, nothing is added.
+     */
+    actions?: ReactNode;
+    /**
+     * Extra content under the operator's message and above the retry controls (a
+     * link to the status page, an expected duration). Omitted, nothing is added.
+     */
+    children?: ReactNode;
+}
+/**
+ * The public maintenance screen: what a blocked viewer sees instead of the
+ * application while a deliberate maintenance window is open. Not a route; the
+ * app's gate renders it in place, outside the layout.
+ *
+ * @param props - see {@link MaintenanceScreenProps}. `logo`, `actions` and `children` are the
+ *   optional parts an app adds; a screen given none is the screen it always was.
+ * @returns the screen element.
+ *
+ * @example
+ * ```tsx
+ * const { block, clear } = useMaintenanceBlock();
+ * if (block) return <MaintenanceScreen appName={APP_NAME} block={block} onRetry={clear} logo={<AppLogo />} />;
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export declare function MaintenanceScreen({ appName, block, onRetry, logo, actions, children }: MaintenanceScreenProps): import("react").JSX.Element;
+//# sourceMappingURL=maintenance-screen.d.ts.map

package/dist/host/ui/maintenance-screen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance-screen.d.ts","sourceRoot":"","sources":["../../../src/host/ui/maintenance-screen.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAOvC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,KAAK,EAAE,gBAAgB,CAAC;IACxB;;;;;;;;OAQG;IACH,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,sBAAsB,+BAyG7G"}

package/dist/host/ui/maintenance-screen.js

@@ -0,0 +1,48 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Button, Card, CardContent, Chip, Stack, Typography, useTheme } from '@mui/material';
+import { Link as RouterLink } from 'react-router-dom';
+import BuildCircleOutlinedIcon from '@mui/icons-material/BuildCircleOutlined';
+import RefreshIcon from '@mui/icons-material/Refresh';
+import { usePermissions } from '../../identity/index.js';
+import { MAINTENANCE_ADMIN_PATH } from '../headless/maintenance-block.js';
+/**
+ * The public maintenance screen: what a blocked viewer sees instead of the
+ * application while a deliberate maintenance window is open. Not a route; the
+ * app's gate renders it in place, outside the layout.
+ *
+ * @param props - see {@link MaintenanceScreenProps}. `logo`, `actions` and `children` are the
+ *   optional parts an app adds; a screen given none is the screen it always was.
+ * @returns the screen element.
+ *
+ * @example
+ * ```tsx
+ * const { block, clear } = useMaintenanceBlock();
+ * if (block) return <MaintenanceScreen appName={APP_NAME} block={block} onRetry={clear} logo={<AppLogo />} />;
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export function MaintenanceScreen({ appName, block, onRetry, logo, actions, children }) {
+    const theme = useTheme();
+    // The maintenance switch is gated on `system_settings:read`, so this is the
+    // same question "can this person do anything about it?" — asked of the
+    // session that is already in memory, never of the API, which is refusing.
+    const { hasPermission } = usePermissions();
+    const canManage = hasPermission('system_settings:read');
+    return (_jsx(Box, { sx: {
+            minHeight: '100vh',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            backgroundColor: theme.palette.background.default,
+            p: 2,
+        }, children: _jsx(Card, { sx: { maxWidth: 520, width: '100%', boxShadow: theme.shadows[10] }, children: _jsx(CardContent, { sx: { p: { xs: 3, sm: 4 } }, children: _jsxs(Stack, { spacing: 2.5, children: [_jsxs(Box, { sx: { textAlign: 'center' }, children: [logo ?? (_jsx(BuildCircleOutlinedIcon, { color: "warning", sx: { fontSize: 56 }, "aria-hidden": true })), _jsxs(Typography, { variant: "h5", component: "h1", sx: { mt: 1 }, children: [appName, " is under maintenance"] })] }), _jsx(Typography, { color: "text.secondary", sx: {
+                                textAlign: 'center',
+                                // The operator wrote this in a textarea and may well have used
+                                // line breaks to structure it. Honour them rather than
+                                // collapsing a three-line notice into one paragraph.
+                                whiteSpace: 'pre-wrap',
+                            }, children: block.message }), children, _jsxs(Stack, { spacing: 1, sx: { alignItems: 'center' }, children: [_jsx(Button, { variant: "contained", startIcon: _jsx(RefreshIcon, {}), onClick: onRetry, children: "Try again" }), _jsxs(Typography, { variant: "caption", color: "text.secondary", children: ["The application asked us to wait about ", block.retryAfterSeconds, " seconds."] }), actions] }), block.allowAdmins && !canManage && (_jsx(Typography, { variant: "body2", color: "text.secondary", sx: { textAlign: 'center' }, children: "Administrators can still use the application during this window." })), canManage && (_jsxs(Stack, { spacing: 1, sx: { alignItems: 'center' }, children: [_jsx(Chip, { size: "small", label: "You can manage this window", variant: "outlined" }), _jsx(Button, { component: RouterLink, to: MAINTENANCE_ADMIN_PATH, size: "small", children: "Open maintenance settings" })] }))] }) }) }) }));
+}
+//# sourceMappingURL=maintenance-screen.js.map

package/dist/host/ui/maintenance-screen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance-screen.js","sourceRoot":"","sources":["../../../src/host/ui/maintenance-screen.tsx"],"names":[],"mappings":"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"}

package/dist/host/ui/update-prompt.d.ts

@@ -0,0 +1,109 @@
+import type { Dispatch, SetStateAction } from 'react';
+/**
+ * What vite-plugin-pwa's `useRegisterSW` returns.
+ *
+ * @stability experimental
+ */
+export interface RegisterServiceWorkerResult {
+    /** `[true, set]` once a new worker is installed and waiting. */
+    needRefresh: [boolean, Dispatch<SetStateAction<boolean>>];
+    /** `[true, set]` once the app shell is cached for offline use. */
+    offlineReady: [boolean, Dispatch<SetStateAction<boolean>>];
+    /** Posts `SKIP_WAITING` to the waiting worker; the hook reloads the page. */
+    updateServiceWorker: (reloadPage?: boolean) => Promise<void>;
+}
+/**
+ * The shape of vite-plugin-pwa's `useRegisterSW` (from the virtual module
+ * `virtual:pwa-register/react`), which only the app's bundler can resolve and
+ * so is injected into {@link UpdatePrompt} rather than imported.
+ *
+ * @stability experimental
+ */
+export type UseRegisterServiceWorker = () => RegisterServiceWorkerResult;
+/**
+ * Props of {@link UpdatePrompt}.
+ *
+ * @stability experimental
+ */
+export interface UpdatePromptProps {
+    /**
+     * vite-plugin-pwa's `useRegisterSW`, imported by the app from
+     * `virtual:pwa-register/react`. Called on every render, so pass the same
+     * function every time.
+     */
+    useRegisterSW: UseRegisterServiceWorker;
+}
+/**
+ * The "a new version is available" prompt, and the thing that REGISTERS the
+ * service worker at all.
+ *
+ * Issue #219, epic #215. Issue #218 shipped the worker with
+ * `registerType: 'prompt'` and `injectRegister: 'auto'`, which is a working
+ * registration with no user-visible half: a new worker installs, moves to
+ * `waiting`, and stays there. Because that worker PRECACHES THE APP SHELL, the
+ * browser keeps serving the shell of whichever revision installed first — so a
+ * deploy reaches nobody until every tab of the origin is closed, which on a
+ * pinned-tab enterprise app can be weeks. This component is the missing half:
+ * it surfaces the waiting worker and posts the `SKIP_WAITING` message that
+ * `src/sw.ts` already listens for.
+ *
+ * =============================================================================
+ * WHY NOT `registerType: 'autoUpdate'`, WHICH WOULD DELETE THIS FILE
+ * =============================================================================
+ *
+ * `autoUpdate` activates the new worker the moment it installs and reloads the
+ * page underneath the user. In a form-heavy application that is not a
+ * convenience, it is a DATA-LOSS BUG: every unsaved field in the settings
+ * pages, the JSON in the advanced editor, a half-written allowlist entry — all
+ * of it is discarded, mid-keystroke, by a deploy the user had no part in. The
+ * user cannot retry what they cannot see, and the failure is invisible in
+ * aggregate because nothing errors.
+ *
+ * `prompt` costs exactly one click and makes the reload the user's decision,
+ * which is why `pwa/service-worker.ts` pins it and why its test asserts it.
+ * Do not "simplify" this away.
+ *
+ * =============================================================================
+ * THIS COMPONENT OWNS REGISTRATION
+ * =============================================================================
+ *
+ * `useRegisterSW` registers the worker itself, which is why
+ * `pwa/service-worker.ts` now sets `injectRegister: null` — with `'auto'` the
+ * injected `registerSW.js` would register it a second time, from a script the
+ * React tree cannot observe. One registration, in one place, whose state is
+ * the state this component renders.
+ *
+ * It follows that this must be mounted on EVERY route, including `/login`: an
+ * unauthenticated user sitting on a stale shell has the same problem, and the
+ * worker is also what makes notifications possible on Android (see `src/sw.ts`)
+ * long before any page asks for permission. See `App.tsx` for the mount point.
+ *
+ * =============================================================================
+ * IT RENDERS NOTHING IN THE DEFAULT STATE
+ * =============================================================================
+ *
+ * No waiting worker and no fresh install means `null` — not a hidden element,
+ * not an empty `Snackbar`. A normal page load is pixel-identical to one without
+ * this component, which is what keeps the visual-regression suite honest.
+ *
+ * The one moment anything appears unprompted is the VERY FIRST visit in a
+ * browser profile, where `offlineReady` fires as the worker installs and shows
+ * a four-second confirmation. That is the intended behaviour and it cannot
+ * reach the pixel suite: `apps/web/visual/vite.config.ts` deliberately omits
+ * `VitePWA` and its harness mounts its own tree rather than `App.tsx`, so
+ * neither the worker nor this component exists there.
+ *
+ * @param props - see {@link UpdatePromptProps}.
+ * @returns the snackbar, or `null`.
+ *
+ * @example
+ * ```tsx
+ * import { useRegisterSW } from 'virtual:pwa-register/react';
+ * <UpdatePrompt useRegisterSW={useRegisterSW} />
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export declare function UpdatePrompt({ useRegisterSW }: UpdatePromptProps): import("react").JSX.Element | null;
+//# sourceMappingURL=update-prompt.d.ts.map

package/dist/host/ui/update-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-prompt.d.ts","sourceRoot":"","sources":["../../../src/host/ui/update-prompt.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAEtD;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,gEAAgE;IAChE,WAAW,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC1D,kEAAkE;IAClE,YAAY,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3D,6EAA6E;IAC7E,mBAAmB,EAAE,CAAC,UAAU,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9D;AAED;;;;;;GAMG;AACH,MAAM,MAAM,wBAAwB,GAAG,MAAM,2BAA2B,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,aAAa,EAAE,wBAAwB,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,wBAAgB,YAAY,CAAC,EAAE,aAAa,EAAE,EAAE,iBAAiB,sCA2EhE"}

package/dist/host/ui/update-prompt.js

@@ -0,0 +1,121 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback } from 'react';
+import { Button, IconButton, Snackbar } from '@mui/material';
+import { Close as CloseIcon } from '@mui/icons-material';
+/**
+ * The "a new version is available" prompt, and the thing that REGISTERS the
+ * service worker at all.
+ *
+ * Issue #219, epic #215. Issue #218 shipped the worker with
+ * `registerType: 'prompt'` and `injectRegister: 'auto'`, which is a working
+ * registration with no user-visible half: a new worker installs, moves to
+ * `waiting`, and stays there. Because that worker PRECACHES THE APP SHELL, the
+ * browser keeps serving the shell of whichever revision installed first — so a
+ * deploy reaches nobody until every tab of the origin is closed, which on a
+ * pinned-tab enterprise app can be weeks. This component is the missing half:
+ * it surfaces the waiting worker and posts the `SKIP_WAITING` message that
+ * `src/sw.ts` already listens for.
+ *
+ * =============================================================================
+ * WHY NOT `registerType: 'autoUpdate'`, WHICH WOULD DELETE THIS FILE
+ * =============================================================================
+ *
+ * `autoUpdate` activates the new worker the moment it installs and reloads the
+ * page underneath the user. In a form-heavy application that is not a
+ * convenience, it is a DATA-LOSS BUG: every unsaved field in the settings
+ * pages, the JSON in the advanced editor, a half-written allowlist entry — all
+ * of it is discarded, mid-keystroke, by a deploy the user had no part in. The
+ * user cannot retry what they cannot see, and the failure is invisible in
+ * aggregate because nothing errors.
+ *
+ * `prompt` costs exactly one click and makes the reload the user's decision,
+ * which is why `pwa/service-worker.ts` pins it and why its test asserts it.
+ * Do not "simplify" this away.
+ *
+ * =============================================================================
+ * THIS COMPONENT OWNS REGISTRATION
+ * =============================================================================
+ *
+ * `useRegisterSW` registers the worker itself, which is why
+ * `pwa/service-worker.ts` now sets `injectRegister: null` — with `'auto'` the
+ * injected `registerSW.js` would register it a second time, from a script the
+ * React tree cannot observe. One registration, in one place, whose state is
+ * the state this component renders.
+ *
+ * It follows that this must be mounted on EVERY route, including `/login`: an
+ * unauthenticated user sitting on a stale shell has the same problem, and the
+ * worker is also what makes notifications possible on Android (see `src/sw.ts`)
+ * long before any page asks for permission. See `App.tsx` for the mount point.
+ *
+ * =============================================================================
+ * IT RENDERS NOTHING IN THE DEFAULT STATE
+ * =============================================================================
+ *
+ * No waiting worker and no fresh install means `null` — not a hidden element,
+ * not an empty `Snackbar`. A normal page load is pixel-identical to one without
+ * this component, which is what keeps the visual-regression suite honest.
+ *
+ * The one moment anything appears unprompted is the VERY FIRST visit in a
+ * browser profile, where `offlineReady` fires as the worker installs and shows
+ * a four-second confirmation. That is the intended behaviour and it cannot
+ * reach the pixel suite: `apps/web/visual/vite.config.ts` deliberately omits
+ * `VitePWA` and its harness mounts its own tree rather than `App.tsx`, so
+ * neither the worker nor this component exists there.
+ *
+ * @param props - see {@link UpdatePromptProps}.
+ * @returns the snackbar, or `null`.
+ *
+ * @example
+ * ```tsx
+ * import { useRegisterSW } from 'virtual:pwa-register/react';
+ * <UpdatePrompt useRegisterSW={useRegisterSW} />
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export function UpdatePrompt({ useRegisterSW }) {
+    const { needRefresh: [needRefresh, setNeedRefresh], offlineReady: [offlineReady, setOfflineReady], updateServiceWorker, } = useRegisterSW();
+    const dismiss = useCallback(() => {
+        setNeedRefresh(false);
+        setOfflineReady(false);
+    }, [setNeedRefresh, setOfflineReady]);
+    const reload = useCallback(() => {
+        // This posts `SKIP_WAITING` to the waiting worker; `src/sw.ts` answers it
+        // with `self.skipWaiting()`, and the hook's own `controlling` listener
+        // reloads the page once the new worker has taken over. Not awaited: the
+        // document is replaced out from under the promise.
+        //
+        // The `true` is the documented "reload the page" argument, kept because it
+        // states the intent at the call site — but note that vite-plugin-pwa has
+        // IGNORED this parameter since 0.13.2 (it is `_reloadPage` in the source).
+        // The reload is wired by the hook regardless, so do not read this argument
+        // as the thing that causes it.
+        void updateServiceWorker(true);
+    }, [updateServiceWorker]);
+    // The update always wins if both are somehow true: "there is a newer version
+    // of this app" is actionable, "the shell is cached" is a note.
+    if (!needRefresh && !offlineReady) {
+        return null;
+    }
+    return (_jsx(Snackbar, { open: true, 
+        // The update prompt does NOT auto-hide: it is the only route by which an
+        // update reaches a long-lived tab, and a message that vanishes after five
+        // seconds is one the user is entitled to miss. The offline confirmation
+        // does auto-hide — it is an FYI about something that already succeeded.
+        autoHideDuration: needRefresh ? null : 4000, onClose: (_event, reason) => {
+            // Click-away must not dismiss the update prompt; the user is expected
+            // to keep working in the page behind it and decide when to reload.
+            if (reason === 'clickaway')
+                return;
+            dismiss();
+        }, message: needRefresh ? 'A new version is available' : 'Ready to work offline', 
+        // Clears the fixed `BottomNav`, which exists only below `sm` — the same
+        // breakpoint `<main>`'s `pb: { xs: 10, sm: 3 }` in `Layout.tsx` clears it
+        // at. This is a static responsive STYLE, not a sixth `useMediaQuery`
+        // mount gate (see `Layout.tsx`'s five coupled gates and
+        // `NotificationBell.tsx`'s note on not adding to them), so it changes
+        // nothing about what is in the tree.
+        sx: { bottom: { xs: 72, sm: 24 } }, action: _jsxs(_Fragment, { children: [needRefresh && (_jsx(Button, { color: "secondary", size: "small", onClick: reload, children: "Reload" })), _jsx(IconButton, { size: "small", "aria-label": "Dismiss update notice", color: "inherit", onClick: dismiss, children: _jsx(CloseIcon, { fontSize: "small" }) })] }) }));
+}
+//# sourceMappingURL=update-prompt.js.map

package/dist/host/ui/update-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-prompt.js","sourceRoot":"","sources":["../../../src/host/ui/update-prompt.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAwCzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,MAAM,UAAU,YAAY,CAAC,EAAE,aAAa,EAAqB;IAC/D,MAAM,EACJ,WAAW,EAAE,CAAC,WAAW,EAAE,cAAc,CAAC,EAC1C,YAAY,EAAE,CAAC,YAAY,EAAE,eAAe,CAAC,EAC7C,mBAAmB,GACpB,GAAG,aAAa,EAAE,CAAC;IAEpB,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE;QAC/B,cAAc,CAAC,KAAK,CAAC,CAAC;QACtB,eAAe,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC,EAAE,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC,CAAC;IAEtC,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,EAAE;QAC9B,0EAA0E;QAC1E,uEAAuE;QACvE,wEAAwE;QACxE,mDAAmD;QACnD,EAAE;QACF,2EAA2E;QAC3E,yEAAyE;QACzE,2EAA2E;QAC3E,2EAA2E;QAC3E,+BAA+B;QAC/B,KAAK,mBAAmB,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC,EAAE,CAAC,mBAAmB,CAAC,CAAC,CAAC;IAE1B,6EAA6E;IAC7E,+DAA+D;IAC/D,IAAI,CAAC,WAAW,IAAI,CAAC,YAAY,EAAE,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,CACL,KAAC,QAAQ,IACP,IAAI;QACJ,yEAAyE;QACzE,0EAA0E;QAC1E,wEAAwE;QACxE,wEAAwE;QACxE,gBAAgB,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAC3C,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE;YAC1B,sEAAsE;YACtE,mEAAmE;YACnE,IAAI,MAAM,KAAK,WAAW;gBAAE,OAAO;YACnC,OAAO,EAAE,CAAC;QACZ,CAAC,EACD,OAAO,EACL,WAAW,CAAC,CAAC,CAAC,4BAA4B,CAAC,CAAC,CAAC,uBAAuB;QAEtE,wEAAwE;QACxE,0EAA0E;QAC1E,qEAAqE;QACrE,wDAAwD;QACxD,sEAAsE;QACtE,qCAAqC;QACrC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAClC,MAAM,EACJ,8BACG,WAAW,IAAI,CACd,KAAC,MAAM,IAAC,KAAK,EAAC,WAAW,EAAC,IAAI,EAAC,OAAO,EAAC,OAAO,EAAE,MAAM,uBAE7C,CACV,EACD,KAAC,UAAU,IACT,IAAI,EAAC,OAAO,gBACD,uBAAuB,EAClC,KAAK,EAAC,SAAS,EACf,OAAO,EAAE,OAAO,YAEhB,KAAC,SAAS,IAAC,QAAQ,EAAC,OAAO,GAAG,GACnB,IACZ,GAEL,CACH,CAAC;AACJ,CAAC"}