@tollbooth-dpyc/web 1.3.1 → 1.4.0

package/dist/react/FundingStatus.js

@@ -0,0 +1,120 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Funding and credential health, as a list of rows that are read fresh and
+ * stamped with when: `PatronFundingStatus` (sign-in proof, credit balance and
+ * tranche expiry) and `OperatorFundingStatus` (credentials, Authority balance,
+ * database, background jobs).
+ *
+ * `OperatorFundingStatus` renders nothing — and asks nothing operator-only —
+ * unless the signed-in npub is the operator npub `session_status` reports, the
+ * rule the fleet's copies used. That decides only what the page shows; the
+ * server enforces its own ACL.
+ *
+ * Mechanics only: the calls, the rules (`funding.ts`) and the states. Every
+ * visual choice is the site's, through `classNames`, with `ok` / `warning` /
+ * `blocked` added to a row, its state word and the heading's summary mark.
+ * `siteRows` adds the site's own checks (an upstream OAuth connection, say);
+ * `renderRow` draws a row yourself. Refresh is a chip.
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+import { composeAuthorityRow, composeCreditsRow, composeDurableJobsRow, composeOnboardingRow, composePersistenceRow, composeProofRow, isOperator, worstState, } from "../funding.js";
+import { currentClaim } from "../identity.js";
+import { canSignFor } from "../signedIn.js";
+import { checkAuthorityBalance, checkBalance, checkProofStatus, getOperatorOnboardingStatus, serviceStatus, sessionStatus, } from "../standardTools.js";
+import { formatDateTime } from "../timezone.js";
+import { cx } from "./cx.js";
+import { useTimezone } from "./useTimezone.js";
+const STATE_LABELS = { ok: "ok", warning: "warning", blocked: "blocked" };
+/**
+ * Rows from `read`, read on mount and on Refresh; null rows means "show
+ * nothing". The latest `read` is used, but a new one (a site passing
+ * `thresholds` or `siteRows` inline) does not trigger a re-read.
+ */
+function useRows(read) {
+    const latest = useRef(read);
+    latest.current = read;
+    const [rows, setRows] = useState(null);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const refresh = useCallback(async () => {
+        setLoading(true);
+        setError(null);
+        try {
+            setRows(await latest.current());
+        }
+        catch (e) {
+            setError(e.message);
+        }
+        finally {
+            setLoading(false);
+        }
+    }, []);
+    useEffect(() => {
+        void refresh();
+    }, [refresh]);
+    return { rows, loading, error, refresh };
+}
+function StatusList({ heading, intro, stateLabels = {}, renderRow, refreshLabel = "Refresh", classNames: c = {}, rows, loading, error, refresh, }) {
+    const [, zone] = useTimezone();
+    const overall = worstState(rows);
+    return (_jsxs("section", { className: c.root, children: [_jsxs("div", { className: c.header, children: [heading && _jsx("div", { className: c.heading, children: heading }), rows.length > 0 && !loading && (_jsx("span", { className: cx(c.overall, c[overall]), children: stateLabels[overall] ?? STATE_LABELS[overall] })), refreshLabel !== null && (_jsx("button", { type: "button", onClick: refresh, disabled: loading, className: c.chip, children: loading ? "Checking…" : refreshLabel }))] }), intro && _jsx("p", { className: c.intro, children: intro }), error && _jsx("p", { className: c.error, children: error }), loading && rows.length === 0 && _jsx("p", { className: c.loading, children: "Checking\u2026" }), rows.length > 0 && (_jsx("ul", { className: c.list, children: rows.map((r) => {
+                    const checked = formatDateTime(r.checked_at, zone);
+                    return (_jsx("li", { className: cx(c.row, c[r.state]), children: renderRow ? (renderRow(r, checked)) : (_jsxs(_Fragment, { children: [_jsx("span", { className: c.dependency, children: r.dependency }), " ", _jsx("span", { className: cx(c.state, c[r.state]), children: stateLabels[r.state] ?? STATE_LABELS[r.state] }), _jsx("p", { className: c.detail, children: r.detail }), _jsxs("p", { className: c.checked, children: ["checked ", checked] })] })) }, r.id));
+                }) }))] }));
+}
+function failedBalance(e) {
+    return { success: false, error: e.message };
+}
+async function proofKind() {
+    const claim = currentClaim();
+    if (canSignFor(claim))
+        return { kind: "session_nsec" };
+    if (!claim.proof)
+        return { kind: "none" };
+    const s = await checkProofStatus(claim.npub, claim.proof).catch(() => null);
+    const status = s?.status === "valid" || s?.status === "expired" ? s.status : "unknown";
+    return { kind: "dm_proof", status, expiresInSec: s?.expires_in_seconds ?? null };
+}
+/** The patron's own health: sign-in proof and credit balance. */
+export function PatronFundingStatus({ thresholds, siteRows, heading = "Account health", ...rest }) {
+    const read = async () => {
+        const checkedAt = new Date().toISOString();
+        const [site, proof, bal] = await Promise.all([
+            siteRows ? siteRows(checkedAt) : Promise.resolve([]),
+            proofKind(),
+            checkBalance().catch(failedBalance),
+        ]);
+        return [...site, composeProofRow(proof, checkedAt), composeCreditsRow(bal, checkedAt, thresholds)];
+    };
+    const state = useRows(read);
+    return _jsx(StatusList, { heading: heading, ...rest, ...state, rows: state.rows ?? [], refresh: () => void state.refresh() });
+}
+/** What only the operator can fix. Renders nothing for anyone else. */
+export function OperatorFundingStatus({ authorityThresholds, siteRows, heading = "Operator dependencies", ...rest }) {
+    const read = async () => {
+        const checkedAt = new Date().toISOString();
+        // Gate first: a patron fires none of the operator's probes.
+        const life = await sessionStatus();
+        if (!isOperator(currentClaim().npub, life))
+            return null;
+        const [site, svc, onb, auth] = await Promise.all([
+            siteRows ? siteRows(checkedAt) : Promise.resolve([]),
+            serviceStatus().catch(() => ({})),
+            getOperatorOnboardingStatus().catch((e) => ({ error: e.message })),
+            checkAuthorityBalance().catch(failedBalance),
+        ]);
+        const jobs = composeDurableJobsRow(svc, checkedAt);
+        return [
+            ...site,
+            composeOnboardingRow(onb, checkedAt),
+            composeAuthorityRow(auth, checkedAt, authorityThresholds),
+            composePersistenceRow(life, svc, onb, checkedAt),
+            ...(jobs ? [jobs] : []),
+        ];
+    };
+    const state = useRows(read);
+    // Nothing until the viewer is known to be the operator — no flash for patrons.
+    if (state.rows === null)
+        return null;
+    return _jsx(StatusList, { heading: heading, ...rest, ...state, rows: state.rows, refresh: () => void state.refresh() });
+}

package/dist/react/PagedTable.js

@@ -1,9 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { ariaSort, clampPage, lastPage, nextSort } from "../table.js";
-function cx(...parts) {
-    const s = parts.filter(Boolean).join(" ");
-    return s || undefined;
-}
+import { cx } from "./cx.js";
 /** A header cell. Tapping the sorted column flips it; another column starts at `initialDir`. */
 export function SortHeader({ label, col, activeCol, dir, onSort, initialDir = "desc", as = "th", classNames: c = {}, }) {
     const Cell = as;

package/dist/react/TableFilter.js

@@ -19,12 +19,9 @@ import { useEffect, useLayoutEffect, useRef, useState } from "react";
 import { Search, SlidersHorizontal, X } from "lucide-react";
 import { filterActive } from "../table.js";
 import { oncePerFrame, reclampPanel } from "./panelPlacement.js";
+import { cx } from "./cx.js";
 /** The panel keeps this many px from each edge of the viewport. */
 const EDGE = 8;
-function cx(...parts) {
-    const s = parts.filter(Boolean).join(" ");
-    return s || undefined;
-}
 export default function TableFilter({ search, dates, questions, onClear, clearPlacement = "beside", searchIcon = _jsx(Search, { size: "1em", "aria-hidden": true }), clearLabel = (_jsxs(_Fragment, { children: [_jsx(X, { size: "1em", "aria-hidden": true }), " Clear"] })), classNames: c = {}, }) {
     const active = filterActive({ search: search?.value, dateFrom: dates?.from, dateTo: dates?.to }, questions?.summary ?? "");
     const clear = active ? (_jsx("button", { type: "button", onClick: onClear, className: c.chip, children: clearLabel })) : null;

package/dist/react/TimezonePicker.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The display time zone as a select: "Automatic (<the browser's zone>)" and a
+ * list of zones. Choosing one stores it under `<prefix>:timezone` and every
+ * clock using `useTimezone` follows. Mechanics only — `classNames` styles it,
+ * `autoLabel` / `optionLabel` word it, `options` picks the zones offered. A
+ * stored zone that is not in `options` is still shown, so the select never
+ * lies about the pick.
+ */
+export interface TimezoneOption {
+    value: string;
+    label: string;
+}
+export interface TimezonePickerClassNames {
+    root?: string;
+    label?: string;
+    select?: string;
+}
+export interface TimezonePickerProps {
+    /** The zones offered. Default `TIMEZONE_OPTIONS` (major cities and UTC). */
+    options?: readonly TimezoneOption[];
+    /** A visible label above the select; without one the select is labelled "Time zone". */
+    label?: string;
+    /** Text of the "auto" choice, given the browser's zone. Default "Automatic (<zone>)". */
+    autoLabel?: (detected: string) => string;
+    /** Text of each zone. Default its label. */
+    optionLabel?: (option: TimezoneOption) => string;
+    id?: string;
+    classNames?: TimezonePickerClassNames;
+}
+export default function TimezonePicker({ options, label, autoLabel, optionLabel, id, classNames: c, }: TimezonePickerProps): import("react").JSX.Element;

package/dist/react/TimezonePicker.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The display time zone as a select: "Automatic (<the browser's zone>)" and a
+ * list of zones. Choosing one stores it under `<prefix>:timezone` and every
+ * clock using `useTimezone` follows. Mechanics only — `classNames` styles it,
+ * `autoLabel` / `optionLabel` word it, `options` picks the zones offered. A
+ * stored zone that is not in `options` is still shown, so the select never
+ * lies about the pick.
+ */
+import { TIMEZONE_OPTIONS, detectBrowserTimeZone } from "../timezone.js";
+import { useTimezone } from "./useTimezone.js";
+const defaultAuto = (detected) => `Automatic (${detected})`;
+const defaultOption = (o) => o.label;
+export default function TimezonePicker({ options = TIMEZONE_OPTIONS, label, autoLabel = defaultAuto, optionLabel = defaultOption, id = "tb-timezone", classNames: c = {}, }) {
+    const [pref, , setPref] = useTimezone();
+    const listed = pref === "auto" || options.some((o) => o.value === pref);
+    const shown = listed ? options : [...options, { value: pref, label: pref }];
+    return (_jsxs("div", { className: c.root, children: [label && (_jsx("label", { htmlFor: id, className: c.label, children: label })), _jsxs("select", { id: id, value: pref, onChange: (e) => setPref(e.target.value), "aria-label": label ? undefined : "Time zone", className: c.select, children: [_jsx("option", { value: "auto", children: autoLabel(detectBrowserTimeZone()) }), shown.map((o) => (_jsx("option", { value: o.value, children: optionLabel(o) }, o.value)))] })] }));
+}

package/dist/react/UsageSummary.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The account-statement card: balance and lifetime totals, what the last N
+ * days spent and bought, and the tools the sats went to.
+ *
+ * Mechanics only — the `account_statement` call, loading and error states and
+ * the arithmetic (`usageFacts`). Every visual choice is the site's, through
+ * `classNames`; `figures` picks which numbers show and in what order, `labels`
+ * words them, and `renderRow` draws a tool row yourself (a display name for a
+ * raw tool name, say). Refresh is a chip.
+ */
+import { type ReactNode } from "react";
+import { type ToolSpend } from "../usage.ts";
+export type UsageFigure = "balance" | "deposited" | "consumed" | "expired" | "spent" | "calls" | "credited";
+export interface UsageSummaryClassNames {
+    root?: string;
+    /** The heading row: title and the Refresh chip. */
+    header?: string;
+    heading?: string;
+    chip?: string;
+    figures?: string;
+    figure?: string;
+    value?: string;
+    label?: string;
+    /** The heading over the tools. */
+    subheading?: string;
+    list?: string;
+    row?: string;
+    tool?: string;
+    calls?: string;
+    sats?: string;
+    loading?: string;
+    error?: string;
+    empty?: string;
+}
+export interface UsageSummaryProps {
+    /** The period asked of the server. Default 30. */
+    days?: number;
+    /** Default "Last <days> days". */
+    heading?: ReactNode;
+    /** The numbers shown, in order. Default all; "expired" only when above zero. */
+    figures?: readonly UsageFigure[];
+    labels?: Partial<Record<UsageFigure, ReactNode>>;
+    /** How many tools to list. 0 hides the list. Default 5. */
+    topTools?: number;
+    /** Default "Top tools". */
+    toolsHeading?: ReactNode;
+    /** Draw a tool row yourself. */
+    renderRow?: (tool: ToolSpend) => ReactNode;
+    /** Shown when the period has no paid calls. Default "No paid calls in this period." */
+    empty?: ReactNode;
+    /** Content of the Refresh chip; null for none. Default "Refresh". */
+    refreshLabel?: ReactNode;
+    classNames?: UsageSummaryClassNames;
+}
+export default function UsageSummary({ days, heading, figures, labels, topTools, toolsHeading, renderRow, empty, refreshLabel, classNames: c, }: UsageSummaryProps): import("react").JSX.Element;

package/dist/react/UsageSummary.js

@@ -0,0 +1,53 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The account-statement card: balance and lifetime totals, what the last N
+ * days spent and bought, and the tools the sats went to.
+ *
+ * Mechanics only — the `account_statement` call, loading and error states and
+ * the arithmetic (`usageFacts`). Every visual choice is the site's, through
+ * `classNames`; `figures` picks which numbers show and in what order, `labels`
+ * words them, and `renderRow` draws a tool row yourself (a display name for a
+ * raw tool name, say). Refresh is a chip.
+ */
+import { useCallback, useEffect, useState } from "react";
+import { getAccountStatement } from "../standardTools.js";
+import { usageFacts } from "../usage.js";
+const ALL = ["balance", "deposited", "consumed", "expired", "spent", "calls", "credited"];
+const LABELS = {
+    balance: "Balance",
+    deposited: "Deposited",
+    consumed: "Consumed",
+    expired: "Expired",
+    spent: "Spent",
+    calls: "Calls",
+    credited: "Bought",
+};
+export default function UsageSummary({ days = 30, heading, figures = ALL, labels = {}, topTools = 5, toolsHeading = "Top tools", renderRow, empty = "No paid calls in this period.", refreshLabel = "Refresh", classNames: c = {}, }) {
+    const [facts, setFacts] = useState(null);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const load = useCallback(async () => {
+        setLoading(true);
+        setError(null);
+        try {
+            const stmt = await getAccountStatement(days);
+            const f = usageFacts(stmt, days, topTools);
+            if (f)
+                setFacts(f);
+            else
+                setError(stmt.error ?? "No statement available.");
+        }
+        catch (e) {
+            setError(e.message);
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [days, topTools]);
+    useEffect(() => {
+        void load();
+    }, [load]);
+    const shown = facts ? figures.filter((f) => f !== "expired" || facts.expired > 0) : [];
+    return (_jsxs("section", { className: c.root, children: [_jsxs("div", { className: c.header, children: [_jsx("div", { className: c.heading, children: heading ?? `Last ${days} days` }), refreshLabel !== null && (_jsx("button", { type: "button", onClick: () => void load(), disabled: loading, className: c.chip, children: loading ? "Loading…" : refreshLabel }))] }), error ? (_jsx("p", { className: c.error, children: error })) : !facts ? (loading && _jsx("p", { className: c.loading, children: "Loading\u2026" })) : (_jsxs(_Fragment, { children: [_jsx("div", { className: c.figures, children: shown.map((f) => (_jsxs("div", { className: c.figure, children: [_jsx("div", { className: c.value, children: facts[f].toLocaleString() }), _jsx("div", { className: c.label, children: labels[f] ?? LABELS[f] })] }, f))) }), topTools > 0 &&
+                        (facts.tools.length === 0 ? (empty && _jsx("p", { className: c.empty, children: empty })) : (_jsxs(_Fragment, { children: [toolsHeading && _jsx("div", { className: c.subheading, children: toolsHeading }), _jsx("ul", { className: c.list, children: facts.tools.map((t) => (_jsx("li", { className: c.row, children: renderRow ? (renderRow(t)) : (_jsxs(_Fragment, { children: [_jsx("span", { className: c.tool, children: t.tool }), " ", _jsxs("span", { className: c.calls, children: [t.calls.toLocaleString(), " call", t.calls === 1 ? "" : "s"] }), " ", _jsxs("span", { className: c.sats, children: [t.sats.toLocaleString(), " sats"] })] })) }, t.tool))) })] })))] }))] }));
+}

package/dist/react/WalletPage.js

@@ -20,13 +20,10 @@ import { checkBalance, getAccountStatement, } from "../standardTools.js";
 import { amountReducer, formatSats, parseSats, presetChosen } from "../wallet.js";
 import CouponsPanel, {} from "./CouponsPanel.js";
 import { useTopUp } from "./useTopUp.js";
+import { cx } from "./cx.js";
 const DEFAULT_TOP_UPS = [1_000, 5_000, 25_000];
 const localDate = (iso) => new Date(iso).toLocaleDateString();
 const localDateTime = (iso) => new Date(iso).toLocaleString();
-function cx(...parts) {
-    const s = parts.filter(Boolean).join(" ");
-    return s || undefined;
-}
 export default function WalletPage({ heading = "Wallet", topUps = DEFAULT_TOP_UPS, customAmount = true, poll, coupons = true, statement = true, formatDate = localDate, formatDateTime = localDateTime, before, children, classNames: c = {}, }) {
     const [bal, setBal] = useState(null);
     const [balError, setBalError] = useState(null);

package/dist/react/cx.d.ts

@@ -0,0 +1,2 @@
+/** Join the class names that are set; undefined when none are, so no empty `class=""`. */
+export declare function cx(...parts: (string | false | null | undefined)[]): string | undefined;

package/dist/react/cx.js

@@ -0,0 +1,5 @@
+/** Join the class names that are set; undefined when none are, so no empty `class=""`. */
+export function cx(...parts) {
+    const s = parts.filter(Boolean).join(" ");
+    return s || undefined;
+}

package/dist/react/index.d.ts

@@ -1,8 +1,10 @@
 export { default as Avatar } from "./Avatar.tsx";
 export { default as AvatarPicker } from "./AvatarPicker.tsx";
+export { default as BuildInfoPanel, type BuildInfoFrontend, type BuildInfoLicence, type BuildInfoPanelClassNames, type BuildInfoPanelProps, } from "./BuildInfoPanel.tsx";
 export { default as CouponsPanel, type CouponsPanelProps, type CouponsPanelClassNames } from "./CouponsPanel.tsx";
 export { default as DebugPanel, type DebugPanelProps } from "./DebugPanel.tsx";
 export { default as ErrorBoundary, type ErrorBoundaryProps, type ErrorBoundaryClassNames, type ErrorFallbackProps, } from "./ErrorBoundary.tsx";
+export { OperatorFundingStatus, PatronFundingStatus, type FundingStatusClassNames, type FundingStatusProps, type OperatorFundingStatusProps, type PatronFundingStatusProps, } from "./FundingStatus.tsx";
 export { default as NpubGate } from "./NpubGate.tsx";
 export { default as NostrProfilePanel } from "./NostrProfilePanel.tsx";
 export { PageControls, SortHeader, TableShell, type PageControlsProps, type PageControlsClassNames, type SortHeaderProps, type SortHeaderClassNames, type TableShellClassNames, } from "./PagedTable.tsx";
@@ -10,9 +12,12 @@ export { default as QuoteScroller, type QuoteScrollerProps, type QuoteScrollerCl
 export { default as SessionKeyClaim } from "./SessionKeyClaim.tsx";
 export { default as TableFilter, type DateFieldOption, type FilterQuestion, type TableFilterProps, type TableFilterClassNames, type TableFilterDates, type TableFilterQuestions, type TableFilterSearch, } from "./TableFilter.tsx";
 export { default as ThemeToggle, type ThemeToggleProps, type ThemeToggleClassNames } from "./ThemeToggle.tsx";
+export { default as TimezonePicker, type TimezoneOption, type TimezonePickerClassNames, type TimezonePickerProps, } from "./TimezonePicker.tsx";
+export { default as UsageSummary, type UsageFigure, type UsageSummaryClassNames, type UsageSummaryProps, } from "./UsageSummary.tsx";
 export { default as WalletCard, type WalletCardProps, type WalletCardClassNames } from "./WalletCard.tsx";
 export { default as WalletPage, type WalletPageProps, type WalletPageClassNames } from "./WalletPage.tsx";
 export { useSession, type Session } from "./useSession.ts";
 export { useDebugLog } from "./useDebugLog.ts";
 export { useTheme } from "./useTheme.ts";
+export { useTimezone } from "./useTimezone.ts";
 export { useTopUp, type TopUp, type UseTopUpOptions } from "./useTopUp.ts";

package/dist/react/index.js

@@ -1,8 +1,10 @@
 export { default as Avatar } from "./Avatar.js";
 export { default as AvatarPicker } from "./AvatarPicker.js";
+export { default as BuildInfoPanel, } from "./BuildInfoPanel.js";
 export { default as CouponsPanel } from "./CouponsPanel.js";
 export { default as DebugPanel } from "./DebugPanel.js";
 export { default as ErrorBoundary, } from "./ErrorBoundary.js";
+export { OperatorFundingStatus, PatronFundingStatus, } from "./FundingStatus.js";
 export { default as NpubGate } from "./NpubGate.js";
 export { default as NostrProfilePanel } from "./NostrProfilePanel.js";
 export { PageControls, SortHeader, TableShell, } from "./PagedTable.js";
@@ -10,9 +12,12 @@ export { default as QuoteScroller } from "./QuoteScroller.js";
 export { default as SessionKeyClaim } from "./SessionKeyClaim.js";
 export { default as TableFilter, } from "./TableFilter.js";
 export { default as ThemeToggle } from "./ThemeToggle.js";
+export { default as TimezonePicker, } from "./TimezonePicker.js";
+export { default as UsageSummary, } from "./UsageSummary.js";
 export { default as WalletCard } from "./WalletCard.js";
 export { default as WalletPage } from "./WalletPage.js";
 export { useSession } from "./useSession.js";
 export { useDebugLog } from "./useDebugLog.js";
 export { useTheme } from "./useTheme.js";
+export { useTimezone } from "./useTimezone.js";
 export { useTopUp } from "./useTopUp.js";

package/dist/react/useTimezone.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The display time zone as React state: `[pref, zone, setPref]` — the stored
+ * preference ("auto" or an IANA name), the zone it resolves to now, and a
+ * setter. Every component using it re-renders when any of them sets it, and
+ * when another tab does.
+ */
+import { type TimezonePref } from "../timezone.ts";
+export declare function useTimezone(): [TimezonePref, string, (next: TimezonePref) => void];

package/dist/react/useTimezone.js

@@ -0,0 +1,34 @@
+/**
+ * The display time zone as React state: `[pref, zone, setPref]` — the stored
+ * preference ("auto" or an IANA name), the zone it resolves to now, and a
+ * setter. Every component using it re-renders when any of them sets it, and
+ * when another tab does.
+ */
+import { useCallback, useMemo, useSyncExternalStore } from "react";
+import { onTimezoneChange, readTimezonePref, resolveTimeZone, timezoneStorageKey, writeTimezonePref, } from "../timezone.js";
+function subscribe(changed) {
+    const stopPage = onTimezoneChange(changed);
+    const onStorage = (e) => {
+        try {
+            if (e.key === timezoneStorageKey())
+                changed();
+        }
+        catch {
+            /* not configured yet: nothing of ours changed */
+        }
+    };
+    globalThis.addEventListener?.("storage", onStorage);
+    return () => {
+        stopPage();
+        globalThis.removeEventListener?.("storage", onStorage);
+    };
+}
+const onServer = () => "auto";
+export function useTimezone() {
+    const pref = useSyncExternalStore(subscribe, readTimezonePref, onServer);
+    const zone = useMemo(() => resolveTimeZone(pref), [pref]);
+    const setPref = useCallback((next) => {
+        writeTimezonePref(next);
+    }, []);
+    return [pref, zone, setPref];
+}

package/dist/timezone.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The patron's display time zone, and the conversions every clock on a page
+ * needs. Storage stays UTC; this converts at the edges — rendering an instant,
+ * reading an <input type="datetime-local">, turning a day filter into bounds.
+ *
+ * The preference is "auto" (the browser's own zone) or an IANA name, kept under
+ * `<prefix>:timezone`. Never a fixed offset: an offset is right for half the
+ * year. A stored name the browser does not know reads as "auto".
+ *
+ * Pure apart from the preference's storage, so it is tested without a browser.
+ * Lifted from eXcalibur's `lib/timezone.ts` (roastify held a copy).
+ */
+export type TimezonePref = "auto" | (string & {});
+/** A starter set of major cities, west to east, plus UTC. Values are IANA names. */
+export declare const TIMEZONE_OPTIONS: readonly {
+    value: string;
+    label: string;
+}[];
+/** The browser's own zone, or UTC when it will not say. */
+export declare function detectBrowserTimeZone(): string;
+/** True when `tz` is a zone name this browser knows. An offset ("+05:00") is not. */
+export declare function isValidTimeZone(tz: string): boolean;
+/** "auto", or the name when the browser knows it; anything else is "auto". */
+export declare function normalizeTimezonePref(pref: string | null | undefined): TimezonePref;
+/** The IANA zone a preference means right now. */
+export declare function resolveTimeZone(pref: TimezonePref): string;
+/** `<prefix>:timezone` — for a `storage` event listener. */
+export declare function timezoneStorageKey(): string;
+export declare function readTimezonePref(): TimezonePref;
+/** Store the preference (normalized) and tell every listener on the page. */
+export declare function writeTimezonePref(next: string): TimezonePref;
+/** Hear every `writeTimezonePref` on this page. Returns an unsubscribe. */
+export declare function onTimezoneChange(fn: (pref: TimezonePref) => void): () => void;
+/** The zone every clock should use: the stored preference, resolved. */
+export declare function displayTimeZone(): string;
+export interface ZonedParts {
+    year: number;
+    /** 1–12 */
+    month: number;
+    day: number;
+    /** 0–23 */
+    hour: number;
+    minute: number;
+    second: number;
+}
+/** The calendar and clock of an instant as seen in `timeZone`. */
+export declare function getZonedParts(date: Date, timeZone: string): ZonedParts;
+/** The zone's offset from UTC at an instant, in ms (New York in winter: −5 h). */
+export declare function getTimeZoneOffsetMs(date: Date, timeZone: string): number;
+/**
+ * A wall time in `timeZone` as a UTC instant (epoch ms).
+ *
+ * Around a DST change a wall time can be missing or doubled. A missing one
+ * (02:30 on New York's spring-forward day) is read with the offset from before
+ * the change, so it lands an hour later (03:30); a doubled one (01:30 on the
+ * fall-back day) is the earlier of the two. Temporal calls this "compatible".
+ */
+export declare function zonedWallTimeToUtcMs(year: number, month: number, day: number, hour: number, minute: number, second: number, timeZone: string): number;
+export declare function formatDateTime(iso: string | null | undefined, timeZone: string, opts?: Intl.DateTimeFormatOptions): string;
+export declare function formatDate(iso: string | null | undefined, timeZone: string, opts?: Intl.DateTimeFormatOptions): string;
+export declare function formatTime(iso: string | null | undefined, timeZone: string, opts?: Intl.DateTimeFormatOptions): string;
+/** An hour of the day (0–23) as the patron's locale writes it: "9 AM", "21". */
+export declare function formatHourLabel(hour: number, timeZone: string): string;
+/** The hour (0–23) of an instant in `timeZone`, or null for a bad instant. */
+export declare function hourInZone(iso: string, timeZone: string): number | null;
+/** A UTC instant → the value for a datetime-local input showing `timeZone`. */
+export declare function isoToDatetimeLocalValue(iso: string, timeZone: string): string;
+/** A datetime-local value, read as a wall time in `timeZone` → UTC ISO. */
+export declare function datetimeLocalValueToIso(value: string, timeZone: string): string | null;
+/** The patron's midnight starting `day`, as UTC ISO (an inclusive lower bound). */
+export declare function startOfLocalDayIso(day: string, timeZone: string): string | null;
+/** The patron's midnight after `day`, as UTC ISO (an exclusive upper bound). */
+export declare function startOfNextLocalDayIso(day: string, timeZone: string): string | null;
+/**
+ * A from/to day filter as the instants a server can compare: from the patron's
+ * midnight starting `dateFrom` up to (not including) the one after `dateTo`.
+ * An empty or malformed day is left out.
+ */
+export declare function localDateFilterBounds(dateFrom: string, dateTo: string, timeZone: string): {
+    dateFrom?: string;
+    dateTo?: string;
+};