@marinoscar/platform-web 0.0.0-stage → 0.1.0-next.4

package/dist/host/headless/use-about.d.ts

@@ -0,0 +1,67 @@
+/**
+ * What is deployed here, read from `GET /api/admin/about` (issue #401, epic
+ * #397).
+ *
+ * Deliberately the canonical "one GET, no params" fetch hook — the same shape
+ * as the other one-GET fetch hooks, down to the three `useState`s, the `useIsMounted`
+ * guard on every `setState` past an `await`, the `useCallback` fetch and the
+ * `{ data, isLoading, error, refresh }` return. There is nothing special about
+ * this endpoint from the client's side: it takes no parameters, it is not
+ * paginated, it is not polled, and it is not cached across mounts.
+ *
+ * =============================================================================
+ * ⚠ `error` MEANS THE REQUEST FAILED. IT NEVER MEANS "THE DEPLOYMENT IS BROKEN".
+ * =============================================================================
+ *
+ * This is the one thing a reader of this hook has to get right, and it is a
+ * property of the API rather than a convention of this file. `GET /api/admin/about`
+ * ALWAYS answers 200 for an authorized caller — a missing
+ * deploy document is `deployInfoStatus: 'absent'`, an unreadable one is
+ * `'invalid'`, a run that failed partway is `run.outcome: 'failure'` beside a
+ * complete document, and a database that did not answer is `database: null`
+ * with a `databaseError` string. Every one of those arrives here as a
+ * successful `data`, and the PAGE renders each as a fact.
+ *
+ * So `error` being non-null here means something else entirely went wrong: a
+ * 403 (the caller does not hold `system_settings:read`), a network failure, or
+ * a maintenance window. Treating `deployInfoStatus !== 'ok'` as an error — or
+ * surfacing `databaseError` through this field — would throw away exactly the
+ * facts an operator opened the page to read, at the moment they came for them.
+ *
+ * NOT POLLED, deliberately. A deployment's identity changes when somebody
+ * deploys, which is not something that happens while you watch — unlike the
+ * worker fleet's health, which a polling hook exists for. `refresh` is
+ * exposed so the page can offer an explicit re-read (the API re-reads the file
+ * from disk on every request, so that genuinely picks up a fresh deploy without
+ * a restart or a reload).
+ */
+import type { AboutResponse } from './contract.js';
+/**
+ * What {@link useAbout} returns.
+ *
+ * @stability experimental
+ */
+export interface UseAboutReturn {
+    /** `null` until the first read resolves — never a signal about the deployment itself. */
+    data: AboutResponse | null;
+    /** `true` while a read is in flight. */
+    isLoading: boolean;
+    /** The REQUEST failed (403, network, maintenance). Never a deploy-document state. */
+    error: string | null;
+    /** Re-read the report (the API re-reads the deploy document on every request). */
+    refresh: () => Promise<void>;
+}
+/**
+ * Reads `GET /api/admin/about` once on mount; `refresh` re-reads it.
+ *
+ * @returns the report, the loading flag, the request error and `refresh`.
+ *
+ * @example
+ * ```tsx
+ * const { data, isLoading, error, refresh } = useAbout();
+ * ```
+ *
+ * @stability experimental
+ */
+export declare function useAbout(): UseAboutReturn;
+//# sourceMappingURL=use-about.d.ts.map

package/dist/host/headless/use-about.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-about.d.ts","sourceRoot":"","sources":["../../../src/host/headless/use-about.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGnD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,yFAAyF;IACzF,IAAI,EAAE,aAAa,GAAG,IAAI,CAAC;IAC3B,wCAAwC;IACxC,SAAS,EAAE,OAAO,CAAC;IACnB,qFAAqF;IACrF,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,kFAAkF;IAClF,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,IAAI,cAAc,CAkCzC"}

package/dist/host/headless/use-about.js

@@ -0,0 +1,87 @@
+/**
+ * What is deployed here, read from `GET /api/admin/about` (issue #401, epic
+ * #397).
+ *
+ * Deliberately the canonical "one GET, no params" fetch hook — the same shape
+ * as the other one-GET fetch hooks, down to the three `useState`s, the `useIsMounted`
+ * guard on every `setState` past an `await`, the `useCallback` fetch and the
+ * `{ data, isLoading, error, refresh }` return. There is nothing special about
+ * this endpoint from the client's side: it takes no parameters, it is not
+ * paginated, it is not polled, and it is not cached across mounts.
+ *
+ * =============================================================================
+ * ⚠ `error` MEANS THE REQUEST FAILED. IT NEVER MEANS "THE DEPLOYMENT IS BROKEN".
+ * =============================================================================
+ *
+ * This is the one thing a reader of this hook has to get right, and it is a
+ * property of the API rather than a convention of this file. `GET /api/admin/about`
+ * ALWAYS answers 200 for an authorized caller — a missing
+ * deploy document is `deployInfoStatus: 'absent'`, an unreadable one is
+ * `'invalid'`, a run that failed partway is `run.outcome: 'failure'` beside a
+ * complete document, and a database that did not answer is `database: null`
+ * with a `databaseError` string. Every one of those arrives here as a
+ * successful `data`, and the PAGE renders each as a fact.
+ *
+ * So `error` being non-null here means something else entirely went wrong: a
+ * 403 (the caller does not hold `system_settings:read`), a network failure, or
+ * a maintenance window. Treating `deployInfoStatus !== 'ok'` as an error — or
+ * surfacing `databaseError` through this field — would throw away exactly the
+ * facts an operator opened the page to read, at the moment they came for them.
+ *
+ * NOT POLLED, deliberately. A deployment's identity changes when somebody
+ * deploys, which is not something that happens while you watch — unlike the
+ * worker fleet's health, which a polling hook exists for. `refresh` is
+ * exposed so the page can offer an explicit re-read (the API re-reads the file
+ * from disk on every request, so that genuinely picks up a fresh deploy without
+ * a restart or a reload).
+ */
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { isPlatformApiError, usePlatformApi } from '../../core/index.js';
+import { useIsMounted } from '../internal/use-is-mounted.js';
+import { createHostApi } from './host-client.js';
+/**
+ * Reads `GET /api/admin/about` once on mount; `refresh` re-reads it.
+ *
+ * @returns the report, the loading flag, the request error and `refresh`.
+ *
+ * @example
+ * ```tsx
+ * const { data, isLoading, error, refresh } = useAbout();
+ * ```
+ *
+ * @stability experimental
+ */
+export function useAbout() {
+    const api = usePlatformApi();
+    const hostApi = useMemo(() => createHostApi(api), [api]);
+    const [data, setData] = useState(null);
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState(null);
+    // Every `setState` past an `await` is guarded: a request that settles after
+    // the component is gone must not schedule an update on it. Same rule as the
+    // other fetch hooks in this directory.
+    const isMounted = useIsMounted();
+    const fetchAbout = useCallback(async () => {
+        try {
+            setIsLoading(true);
+            setError(null);
+            const response = await hostApi.getAbout();
+            if (isMounted())
+                setData(response);
+        }
+        catch (err) {
+            if (isMounted()) {
+                setError(isPlatformApiError(err) ? err.message : 'Failed to load deployment information');
+            }
+        }
+        finally {
+            if (isMounted())
+                setIsLoading(false);
+        }
+    }, [hostApi, isMounted]);
+    useEffect(() => {
+        void fetchAbout();
+    }, [fetchAbout]);
+    return { data, isLoading, error, refresh: fetchAbout };
+}
+//# sourceMappingURL=use-about.js.map

package/dist/host/headless/use-about.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-about.js","sourceRoot":"","sources":["../../../src/host/headless/use-about.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAE7D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAkBjD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,QAAQ;IACtB,MAAM,GAAG,GAAG,cAAc,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACzD,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAuB,IAAI,CAAC,CAAC;IAC7D,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IACjD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAgB,IAAI,CAAC,CAAC;IAExD,4EAA4E;IAC5E,4EAA4E;IAC5E,uCAAuC;IACvC,MAAM,SAAS,GAAG,YAAY,EAAE,CAAC;IAEjC,MAAM,UAAU,GAAG,WAAW,CAAC,KAAK,IAAI,EAAE;QACxC,IAAI,CAAC;YACH,YAAY,CAAC,IAAI,CAAC,CAAC;YACnB,QAAQ,CAAC,IAAI,CAAC,CAAC;YACf,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC;YAC1C,IAAI,SAAS,EAAE;gBAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;QACrC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,SAAS,EAAE,EAAE,CAAC;gBAChB,QAAQ,CACN,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,uCAAuC,CAChF,CAAC;YACJ,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,IAAI,SAAS,EAAE;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QACvC,CAAC;IACH,CAAC,EAAE,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC;IAEzB,SAAS,CAAC,GAAG,EAAE;QACb,KAAK,UAAU,EAAE,CAAC;IACpB,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC;IAEjB,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;AACzD,CAAC"}

package/dist/host/headless/use-maintenance.d.ts

@@ -0,0 +1,122 @@
+/**
+ * The two maintenance hooks — issue #258, epic #254.
+ *
+ * They sit in one file because they are two views of one feature, but they read
+ * from OPPOSITE ENDS of it and share no state:
+ *
+ *   * `useMaintenanceBlock()` reads the module store in `maintenance-block.ts`
+ *     — what the API told a caller it had just refused. Its subscriber is
+ *     `MaintenanceGate`, and it never makes a request of its own: by definition
+ *     the viewer is being blocked, so asking the API anything is the one thing
+ *     that cannot work.
+ *
+ *   * `useMaintenance()` reads `GET /api/admin/maintenance` — the operator's
+ *     view, including every contributing layer. Its consumers are the admin page
+ *     and the banner, both of which are rendered by somebody who is NOT blocked.
+ *
+ * The second is shaped after `useEmailSettings` (#124): same `isMounted`
+ * discipline, same "an error is a string the page renders" contract, same
+ * `save` that resolves a boolean instead of throwing, because every caller is a
+ * click handler that needs to branch rather than a place to handle an exception
+ * already captured for rendering.
+ */
+import type { MaintenanceStatus, UpdateMaintenanceInput } from './contract.js';
+import type { MaintenanceBlock } from './maintenance-block.js';
+/**
+ * How often `MaintenanceBanner` re-asks whether the window is still open.
+ *
+ * A POLL IS NECESSARY HERE AND NOWHERE ELSE IN THIS FEATURE. Everybody else
+ * learns about a window by being refused, which arrives by itself; an
+ * administrator who is being let THROUGH one is refused nothing and would
+ * otherwise never find out — including the administrator who opened the window
+ * on another tab, or a colleague who did. Sixty seconds is well inside the
+ * period over which forgetting matters, and it is one cheap request a minute on
+ * a page only `system_settings:read` holders render at all.
+ *
+ * @stability experimental
+ */
+export declare const MAINTENANCE_POLL_INTERVAL_MS = 60000;
+/**
+ * What {@link useMaintenanceBlock} returns.
+ *
+ * @stability experimental
+ */
+export interface UseMaintenanceBlockReturn {
+    /** What the API said when it refused a request, or `null` when nothing is blocked. */
+    block: MaintenanceBlock | null;
+    /** Forget the block, so the application renders again and its pages re-fetch. */
+    clear: () => void;
+}
+/**
+ * Subscribe to the maintenance block recorded centrally by the app's HTTP client.
+ *
+ * `useSyncExternalStore` rather than `useState` + an effect: the store is
+ * written from a `fetch` handler outside React's knowledge, and this is the
+ * supported way to read one without tearing under concurrent rendering. It is
+ * also why `getMaintenanceBlock` must return a stable reference between
+ * changes — see its own comment.
+ *
+ * @returns the block (or `null`) and `clear`.
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export declare function useMaintenanceBlock(): UseMaintenanceBlockReturn;
+/**
+ * Options of {@link useMaintenance}.
+ *
+ * @stability experimental
+ */
+export interface UseMaintenanceOptions {
+    /**
+     * Whether to talk to the API at all. Default `true`.
+     *
+     * `false` is for a caller that already knows the request would 403 — the
+     * banner, mounted in the app shell for EVERY user, of whom most hold no
+     * `system_settings:read`. Rendering nothing but still firing the request
+     * would buy a 403 per minute per viewer and fill the audit-adjacent logs of
+     * every deployment with failures that were predictable from the session.
+     */
+    enabled?: boolean;
+    /** Re-fetch on this interval, in ms. `0` (the default) never polls. */
+    pollIntervalMs?: number;
+}
+/**
+ * What {@link useMaintenance} returns.
+ *
+ * @stability experimental
+ */
+export interface UseMaintenanceReturn {
+    /** The effective state and its layers, or `null` before the first successful load. */
+    status: MaintenanceStatus | null;
+    /** `true` while the status is being loaded. */
+    isLoading: boolean;
+    /** Failure to LOAD. Distinct from `saveError`: one means "nothing to show", the other "your change did not stick". */
+    loadError: string | null;
+    /** `true` while a save is in flight. */
+    isSaving: boolean;
+    /** Why the last save failed, or `null`. */
+    saveError: string | null;
+    /** Resolves `true` when the write landed, `false` when it did not — never throws. */
+    save: (input: UpdateMaintenanceInput) => Promise<boolean>;
+    /** Re-read the status. */
+    refresh: () => Promise<void>;
+}
+/**
+ * The operator's view of the window: `GET`/`PUT /api/admin/maintenance`, with
+ * every contributing layer, an optional poll and a `save` that resolves a
+ * boolean.
+ *
+ * @param options - see {@link UseMaintenanceOptions}.
+ * @returns the status, the load and save states, `save` and `refresh`.
+ *
+ * @example
+ * ```tsx
+ * const { status, save } = useMaintenance({ enabled: canRead, pollIntervalMs: MAINTENANCE_POLL_INTERVAL_MS });
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export declare function useMaintenance(options?: UseMaintenanceOptions): UseMaintenanceReturn;
+//# sourceMappingURL=use-maintenance.d.ts.map

package/dist/host/headless/use-maintenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-maintenance.d.ts","sourceRoot":"","sources":["../../../src/host/headless/use-maintenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,OAAO,KAAK,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAO/E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAEnD;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,sFAAsF;IACtF,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC/B,iFAAiF;IACjF,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,IAAI,yBAAyB,CAO/D;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uEAAuE;IACvE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,sFAAsF;IACtF,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjC,+CAA+C;IAC/C,SAAS,EAAE,OAAO,CAAC;IACnB,sHAAsH;IACtH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,wCAAwC;IACxC,QAAQ,EAAE,OAAO,CAAC;IAClB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,qFAAqF;IACrF,IAAI,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,0BAA0B;IAC1B,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,oBAAoB,CAiHxF"}

package/dist/host/headless/use-maintenance.js

@@ -0,0 +1,185 @@
+/**
+ * The two maintenance hooks — issue #258, epic #254.
+ *
+ * They sit in one file because they are two views of one feature, but they read
+ * from OPPOSITE ENDS of it and share no state:
+ *
+ *   * `useMaintenanceBlock()` reads the module store in `maintenance-block.ts`
+ *     — what the API told a caller it had just refused. Its subscriber is
+ *     `MaintenanceGate`, and it never makes a request of its own: by definition
+ *     the viewer is being blocked, so asking the API anything is the one thing
+ *     that cannot work.
+ *
+ *   * `useMaintenance()` reads `GET /api/admin/maintenance` — the operator's
+ *     view, including every contributing layer. Its consumers are the admin page
+ *     and the banner, both of which are rendered by somebody who is NOT blocked.
+ *
+ * The second is shaped after `useEmailSettings` (#124): same `isMounted`
+ * discipline, same "an error is a string the page renders" contract, same
+ * `save` that resolves a boolean instead of throwing, because every caller is a
+ * click handler that needs to branch rather than a place to handle an exception
+ * already captured for rendering.
+ */
+import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from 'react';
+import { isPlatformApiError, usePlatformApi } from '../../core/index.js';
+import { useIsMounted } from '../internal/use-is-mounted.js';
+import { createHostApi } from './host-client.js';
+import { clearMaintenanceBlock, getMaintenanceBlock, subscribeToMaintenanceBlock, } from './maintenance-block.js';
+/**
+ * How often `MaintenanceBanner` re-asks whether the window is still open.
+ *
+ * A POLL IS NECESSARY HERE AND NOWHERE ELSE IN THIS FEATURE. Everybody else
+ * learns about a window by being refused, which arrives by itself; an
+ * administrator who is being let THROUGH one is refused nothing and would
+ * otherwise never find out — including the administrator who opened the window
+ * on another tab, or a colleague who did. Sixty seconds is well inside the
+ * period over which forgetting matters, and it is one cheap request a minute on
+ * a page only `system_settings:read` holders render at all.
+ *
+ * @stability experimental
+ */
+export const MAINTENANCE_POLL_INTERVAL_MS = 60_000;
+/**
+ * Subscribe to the maintenance block recorded centrally by the app's HTTP client.
+ *
+ * `useSyncExternalStore` rather than `useState` + an effect: the store is
+ * written from a `fetch` handler outside React's knowledge, and this is the
+ * supported way to read one without tearing under concurrent rendering. It is
+ * also why `getMaintenanceBlock` must return a stable reference between
+ * changes — see its own comment.
+ *
+ * @returns the block (or `null`) and `clear`.
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export function useMaintenanceBlock() {
+    const block = useSyncExternalStore(subscribeToMaintenanceBlock, getMaintenanceBlock);
+    return {
+        block,
+        clear: clearMaintenanceBlock,
+    };
+}
+/**
+ * The operator's view of the window: `GET`/`PUT /api/admin/maintenance`, with
+ * every contributing layer, an optional poll and a `save` that resolves a
+ * boolean.
+ *
+ * @param options - see {@link UseMaintenanceOptions}.
+ * @returns the status, the load and save states, `save` and `refresh`.
+ *
+ * @example
+ * ```tsx
+ * const { status, save } = useMaintenance({ enabled: canRead, pollIntervalMs: MAINTENANCE_POLL_INTERVAL_MS });
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export function useMaintenance(options = {}) {
+    const { enabled = true, pollIntervalMs = 0 } = options;
+    const api = usePlatformApi();
+    const hostApi = useMemo(() => createHostApi(api), [api]);
+    const [status, setStatus] = useState(null);
+    // Starts `false` when disabled: a hook that will never fetch must not report
+    // a load that is permanently in progress, or the banner would sit forever in
+    // a state its consumer reads as "not known yet".
+    const [isLoading, setIsLoading] = useState(enabled);
+    const [loadError, setLoadError] = useState(null);
+    const [isSaving, setIsSaving] = useState(false);
+    const [saveError, setSaveError] = useState(null);
+    // Every `setState` past an `await` is guarded, the same rule
+    // `useEmailSettings` and `useSystemSettings` follow: a request that settles
+    // after the component is gone must not schedule an update on it. Only the
+    // state write is skipped; what these functions return is unchanged.
+    const isMounted = useIsMounted();
+    const fetchStatus = useCallback(async () => {
+        if (!enabled)
+            return;
+        try {
+            setIsLoading(true);
+            setLoadError(null);
+            const data = await hostApi.getMaintenanceStatus();
+            if (isMounted())
+                setStatus(data);
+        }
+        catch (err) {
+            if (isMounted()) {
+                // 403 is named explicitly because it is the one failure whose remedy is
+                // a permission rather than a fix — the same treatment
+                // `useEmailSettings` gives it.
+                if (isPlatformApiError(err) && err.status === 403) {
+                    setLoadError('You do not have permission to view maintenance mode');
+                }
+                else {
+                    setLoadError(isPlatformApiError(err) ? err.message : 'Failed to load maintenance mode');
+                }
+            }
+        }
+        finally {
+            if (isMounted())
+                setIsLoading(false);
+        }
+    }, [enabled, hostApi, isMounted]);
+    useEffect(() => {
+        void fetchStatus();
+    }, [fetchStatus]);
+    useEffect(() => {
+        if (!enabled || pollIntervalMs <= 0)
+            return;
+        const timer = setInterval(() => {
+            void fetchStatus();
+        }, pollIntervalMs);
+        return () => clearInterval(timer);
+    }, [enabled, pollIntervalMs, fetchStatus]);
+    /**
+     * Write the window, and adopt whatever the server says the state now is.
+     *
+     * THE RESPONSE IS THE NEW BASELINE, NEVER THE INPUT, and here that is more
+     * than the usual hygiene it is in `useEmailSettings`. An environment override
+     * outranks anything this writes, so `save({ enabled: false })` can correctly
+     * come back `enabled: true, source: 'env'` — and a page that trusted its own
+     * payload would then tell the operator the window is closed while the
+     * application is still refusing every request. `source` and `layers` are
+     * exactly what that operator has to see, and only the response carries them.
+     */
+    const save = useCallback(async (input) => {
+        try {
+            setIsSaving(true);
+            setSaveError(null);
+            const data = await hostApi.updateMaintenance(input);
+            if (isMounted())
+                setStatus(data);
+            // The one place in the app that KNOWS a window closed, so the one place
+            // entitled to drop a recorded block. Keyed on the server's effective
+            // answer rather than on `input.enabled`: with an env override forcing
+            // the window open, the save succeeded and the application is still out
+            // of service, and clearing the gate then would show this operator an
+            // application that immediately blocks them again.
+            if (!data.enabled) {
+                clearMaintenanceBlock();
+            }
+            return true;
+        }
+        catch (err) {
+            if (isMounted()) {
+                setSaveError(isPlatformApiError(err) ? err.message : 'Failed to update maintenance mode');
+            }
+            return false;
+        }
+        finally {
+            if (isMounted())
+                setIsSaving(false);
+        }
+    }, [hostApi, isMounted]);
+    return {
+        status,
+        isLoading,
+        loadError,
+        isSaving,
+        saveError,
+        save,
+        refresh: fetchStatus,
+    };
+}
+//# sourceMappingURL=use-maintenance.js.map

package/dist/host/headless/use-maintenance.js.map

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

package/dist/host/internal/format-duration.d.ts

@@ -0,0 +1,2 @@
+export declare function formatDuration(ms: number | null | undefined): string;
+//# sourceMappingURL=format-duration.d.ts.map

package/dist/host/internal/format-duration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-duration.d.ts","sourceRoot":"","sources":["../../../src/host/internal/format-duration.ts"],"names":[],"mappings":"AAMA,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAiBpE"}

package/dist/host/internal/format-duration.js

@@ -0,0 +1,25 @@
+// A private copy of the jobs slice's `formatDuration` (a slice may import only
+// the slices `packages/platform-slices.json` lists for it, and the jobs slice
+// has no index). Same rules: the largest unit that still says something
+// (`850 ms`, `1.5 s`, `4m 05s`, `2h 03m`, `3d 4h`) and an em dash for `null`.
+// Not exported.
+export function formatDuration(ms) {
+    if (ms === null || ms === undefined || !Number.isFinite(ms))
+        return '—';
+    if (ms < 1000)
+        return `${Math.round(ms)} ms`;
+    const totalSeconds = ms / 1000;
+    if (totalSeconds < 60)
+        return `${totalSeconds.toFixed(1)} s`;
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = Math.round(totalSeconds % 60);
+    if (minutes < 60)
+        return `${minutes}m ${String(seconds).padStart(2, '0')}s`;
+    const hours = Math.floor(minutes / 60);
+    const remainingMinutes = minutes % 60;
+    if (hours < 24)
+        return `${hours}h ${String(remainingMinutes).padStart(2, '0')}m`;
+    const days = Math.floor(hours / 24);
+    return `${days}d ${hours % 24}h`;
+}
+//# sourceMappingURL=format-duration.js.map

package/dist/host/internal/format-duration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-duration.js","sourceRoot":"","sources":["../../../src/host/internal/format-duration.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,8EAA8E;AAC9E,wEAAwE;AACxE,8EAA8E;AAC9E,gBAAgB;AAEhB,MAAM,UAAU,cAAc,CAAC,EAA6B;IAC1D,IAAI,EAAE,KAAK,IAAI,IAAI,EAAE,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QAAE,OAAO,GAAG,CAAC;IACxE,IAAI,EAAE,GAAG,IAAI;QAAE,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC;IAE7C,MAAM,YAAY,GAAG,EAAE,GAAG,IAAI,CAAC;IAC/B,IAAI,YAAY,GAAG,EAAE;QAAE,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IAE7D,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,EAAE,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,EAAE,CAAC,CAAC;IAC9C,IAAI,OAAO,GAAG,EAAE;QAAE,OAAO,GAAG,OAAO,KAAK,MAAM,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC;IAE5E,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;IACvC,MAAM,gBAAgB,GAAG,OAAO,GAAG,EAAE,CAAC;IACtC,IAAI,KAAK,GAAG,EAAE;QAAE,OAAO,GAAG,KAAK,KAAK,MAAM,CAAC,gBAAgB,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC;IAEjF,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC;IACpC,OAAO,GAAG,IAAI,KAAK,KAAK,GAAG,EAAE,GAAG,CAAC;AACnC,CAAC"}

package/dist/host/internal/relative-time.d.ts

@@ -0,0 +1,2 @@
+export declare function formatRelativeTime(iso: string, now?: Date): string;
+//# sourceMappingURL=relative-time.d.ts.map

package/dist/host/internal/relative-time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relative-time.d.ts","sourceRoot":"","sources":["../../../src/host/internal/relative-time.ts"],"names":[],"mappings":"AAiBA,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,IAAiB,GAAG,MAAM,CAY9E"}

package/dist/host/internal/relative-time.js

@@ -0,0 +1,29 @@
+// The fallback "3 minutes ago" formatter, used when the host supplies no
+// `formatRelativeTime`. Same rules as the reference app's
+// `utils/relativeTime.ts`: Intl.RelativeTimeFormat, "Just now" under 45 s (a
+// clock-skew guard), the ISO string on an unparseable input. Not exported.
+const UNITS = [
+    { limit: 60_000, ms: 1_000, unit: 'second' },
+    { limit: 3_600_000, ms: 60_000, unit: 'minute' },
+    { limit: 86_400_000, ms: 3_600_000, unit: 'hour' },
+    { limit: 604_800_000, ms: 86_400_000, unit: 'day' },
+    { limit: 2_629_800_000, ms: 604_800_000, unit: 'week' },
+    { limit: 31_557_600_000, ms: 2_629_800_000, unit: 'month' },
+    { limit: Infinity, ms: 31_557_600_000, unit: 'year' },
+];
+const JUST_NOW_MS = 45_000;
+export function formatRelativeTime(iso, now = new Date()) {
+    const time = new Date(iso).getTime();
+    if (Number.isNaN(time))
+        return iso;
+    const elapsed = now.getTime() - time;
+    if (elapsed < JUST_NOW_MS)
+        return 'Just now';
+    const formatter = new Intl.RelativeTimeFormat(undefined, { numeric: 'auto' });
+    for (const { limit, ms, unit } of UNITS) {
+        if (elapsed < limit)
+            return formatter.format(-Math.floor(elapsed / ms), unit);
+    }
+    return iso;
+}
+//# sourceMappingURL=relative-time.js.map

package/dist/host/internal/relative-time.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relative-time.js","sourceRoot":"","sources":["../../../src/host/internal/relative-time.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,0DAA0D;AAC1D,6EAA6E;AAC7E,2EAA2E;AAE3E,MAAM,KAAK,GAAuE;IAChF,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE;IAC5C,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE;IAChD,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE;IAClD,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE;IACnD,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE;IACvD,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,OAAO,EAAE;IAC3D,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE;CACtD,CAAC;AAEF,MAAM,WAAW,GAAG,MAAM,CAAC;AAE3B,MAAM,UAAU,kBAAkB,CAAC,GAAW,EAAE,MAAY,IAAI,IAAI,EAAE;IACpE,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC;IACrC,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;QAAE,OAAO,GAAG,CAAC;IAEnC,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC;IACrC,IAAI,OAAO,GAAG,WAAW;QAAE,OAAO,UAAU,CAAC;IAE7C,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,kBAAkB,CAAC,SAAS,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IAC9E,KAAK,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,KAAK,EAAE,CAAC;QACxC,IAAI,OAAO,GAAG,KAAK;YAAE,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;IAChF,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/host/internal/use-is-mounted.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Returns a stable getter for "is this component still mounted?".
+ *
+ * Used to guard `setState` in the tail of an async operation. A ref rather
+ * than state, and a getter rather than the ref itself, so callers can hold it
+ * in a `useCallback` dependency list without invalidating on every render.
+ */
+export declare function useIsMounted(): () => boolean;
+//# sourceMappingURL=use-is-mounted.d.ts.map

package/dist/host/internal/use-is-mounted.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-is-mounted.d.ts","sourceRoot":"","sources":["../../../src/host/internal/use-is-mounted.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,MAAM,OAAO,CAW5C"}

package/dist/host/internal/use-is-mounted.js

@@ -0,0 +1,19 @@
+import { useCallback, useEffect, useRef } from 'react';
+/**
+ * Returns a stable getter for "is this component still mounted?".
+ *
+ * Used to guard `setState` in the tail of an async operation. A ref rather
+ * than state, and a getter rather than the ref itself, so callers can hold it
+ * in a `useCallback` dependency list without invalidating on every render.
+ */
+export function useIsMounted() {
+    const mounted = useRef(true);
+    useEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+        };
+    }, []);
+    return useCallback(() => mounted.current, []);
+}
+//# sourceMappingURL=use-is-mounted.js.map

package/dist/host/internal/use-is-mounted.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-is-mounted.js","sourceRoot":"","sources":["../../../src/host/internal/use-is-mounted.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAE7B,SAAS,CAAC,GAAG,EAAE;QACb,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;QACvB,OAAO,GAAG,EAAE;YACV,OAAO,CAAC,OAAO,GAAG,KAAK,CAAC;QAC1B,CAAC,CAAC;IACJ,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO,WAAW,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAChD,CAAC"}