@tollbooth-dpyc/web 0.5.0 → 1.1.0

package/dist/react/debugSpacer.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The room the DebugPanel keeps for itself.
+ *
+ * The panel is fixed to the bottom of the viewport, so on its own it would sit
+ * over whatever the page puts last — on a phone, a loading quote or a Save
+ * button. Beside it the panel renders an in-flow spacer as tall as the panel is
+ * right now (the collapsed tab, or the open log), plus the iOS home-indicator
+ * inset, so the page can always scroll its last line clear of the bar.
+ */
+/** The collapsed tab: one `min-h-10` (2.5rem) button. Used until measured. */
+export declare const DEBUG_BAR_PX = 40;
+/** Whole CSS pixels for a measured height; the collapsed bar when unmeasured. */
+export declare function debugSpacerPx(measured: number | null | undefined): number;
+/** The spacer's CSS height: the panel's height plus the safe-area inset. */
+export declare function debugSpacerHeight(measured: number | null | undefined): string;

package/dist/react/debugSpacer.js

@@ -0,0 +1,21 @@
+/**
+ * The room the DebugPanel keeps for itself.
+ *
+ * The panel is fixed to the bottom of the viewport, so on its own it would sit
+ * over whatever the page puts last — on a phone, a loading quote or a Save
+ * button. Beside it the panel renders an in-flow spacer as tall as the panel is
+ * right now (the collapsed tab, or the open log), plus the iOS home-indicator
+ * inset, so the page can always scroll its last line clear of the bar.
+ */
+/** The collapsed tab: one `min-h-10` (2.5rem) button. Used until measured. */
+export const DEBUG_BAR_PX = 40;
+/** Whole CSS pixels for a measured height; the collapsed bar when unmeasured. */
+export function debugSpacerPx(measured) {
+    if (typeof measured !== "number" || !Number.isFinite(measured) || measured <= 0)
+        return DEBUG_BAR_PX;
+    return Math.ceil(measured);
+}
+/** The spacer's CSS height: the panel's height plus the safe-area inset. */
+export function debugSpacerHeight(measured) {
+    return `calc(${debugSpacerPx(measured)}px + env(safe-area-inset-bottom, 0px))`;
+}

package/dist/react/index.d.ts

@@ -1,10 +1,18 @@
 export { default as Avatar } from "./Avatar.tsx";
 export { default as AvatarPicker } from "./AvatarPicker.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 { 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";
 export { default as QuoteScroller, type QuoteScrollerProps, type QuoteScrollerClassNames } from "./QuoteScroller.tsx";
 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 WalletCard } 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 { useTopUp, type TopUp, type UseTopUpOptions } from "./useTopUp.ts";

package/dist/react/index.js

@@ -1,10 +1,18 @@
 export { default as Avatar } from "./Avatar.js";
 export { default as AvatarPicker } from "./AvatarPicker.js";
+export { default as CouponsPanel } from "./CouponsPanel.js";
 export { default as DebugPanel } from "./DebugPanel.js";
+export { default as ErrorBoundary, } from "./ErrorBoundary.js";
 export { default as NpubGate } from "./NpubGate.js";
 export { default as NostrProfilePanel } from "./NostrProfilePanel.js";
+export { PageControls, SortHeader, TableShell, } from "./PagedTable.js";
 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 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 { useTopUp } from "./useTopUp.js";

package/dist/react/useTheme.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The theme pick as React state: persisted under `<prefix>:theme`, applied to
+ * <html>, followed across tabs, and — in "system" — following the OS live.
+ * Call `bootstrapTheme()` in main.tsx too, so the first frame is right.
+ */
+import { type Theme } from "../theme.ts";
+export declare function useTheme(fallback?: Theme): [Theme, (next: Theme) => void];

package/dist/react/useTheme.js

@@ -0,0 +1,44 @@
+/**
+ * The theme pick as React state: persisted under `<prefix>:theme`, applied to
+ * <html>, followed across tabs, and — in "system" — following the OS live.
+ * Call `bootstrapTheme()` in main.tsx too, so the first frame is right.
+ */
+import { useCallback, useEffect, useState } from "react";
+import { applyTheme, readTheme, themeStorageKey, writeTheme } from "../theme.js";
+export function useTheme(fallback = "dark") {
+    const [theme, setTheme] = useState(() => readTheme(fallback));
+    // Another tab changed it.
+    useEffect(() => {
+        let key;
+        try {
+            key = themeStorageKey();
+        }
+        catch {
+            return;
+        }
+        const onStorage = (e) => {
+            if (e.key !== key)
+                return;
+            const next = readTheme(fallback);
+            setTheme(next);
+            applyTheme(next);
+        };
+        window.addEventListener("storage", onStorage);
+        return () => window.removeEventListener("storage", onStorage);
+    }, [fallback]);
+    // In "system", the OS changed its mind.
+    useEffect(() => {
+        if (theme !== "system" || !window.matchMedia)
+            return;
+        const mq = window.matchMedia("(prefers-color-scheme: dark)");
+        const onChange = () => applyTheme("system");
+        mq.addEventListener("change", onChange);
+        return () => mq.removeEventListener("change", onChange);
+    }, [theme]);
+    const update = useCallback((next) => {
+        writeTheme(next);
+        applyTheme(next);
+        setTheme(next);
+    }, []);
+    return [theme, update];
+}

package/dist/react/useTopUp.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A Lightning top-up as a hook: purchase_credits → an invoice → check_payment
+ * until it settles, expires or the patron gives up.
+ *
+ * The state machine is `topUpReducer` (framework-free, tested). This adds the
+ * calls and the polling: while an invoice is out and the tab is visible,
+ * check_payment runs every `pollMs` — it is free and safe to repeat — up to
+ * `maxChecks` times, after which the patron's own "check" still works.
+ */
+import { type TopUpState } from "../wallet.ts";
+export interface UseTopUpOptions {
+    /** How often to check an open invoice, in ms. 0 turns polling off. Default 5000. */
+    pollMs?: number;
+    /** Stop polling after this many checks. Default 60 (five minutes at the default rate). */
+    maxChecks?: number;
+    /** Called once when an invoice settles, with the sats credited — refresh a balance here. */
+    onSettled?: (credited: number) => void;
+}
+export interface TopUp {
+    state: TopUpState;
+    /** Ask the service for an invoice of `sats`. Ignored while one is being made or is out. */
+    create: (sats: number) => void;
+    /** Check the open invoice now. */
+    check: () => void;
+    /** Drop the open invoice (it simply expires at BTCPay). */
+    cancel: () => void;
+    /** Back to idle after a settlement or failure. */
+    reset: () => void;
+}
+export declare function useTopUp({ pollMs, maxChecks, onSettled }?: UseTopUpOptions): TopUp;

package/dist/react/useTopUp.js

@@ -0,0 +1,74 @@
+/**
+ * A Lightning top-up as a hook: purchase_credits → an invoice → check_payment
+ * until it settles, expires or the patron gives up.
+ *
+ * The state machine is `topUpReducer` (framework-free, tested). This adds the
+ * calls and the polling: while an invoice is out and the tab is visible,
+ * check_payment runs every `pollMs` — it is free and safe to repeat — up to
+ * `maxChecks` times, after which the patron's own "check" still works.
+ */
+import { useCallback, useEffect, useReducer, useRef, useState } from "react";
+import { checkPayment, purchaseCredits } from "../standardTools.js";
+import { shouldPoll, TOP_UP_IDLE, topUpReducer } from "../wallet.js";
+function messageOf(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+function tabHidden() {
+    return typeof document !== "undefined" && document.visibilityState === "hidden";
+}
+export function useTopUp({ pollMs = 5000, maxChecks = 60, onSettled } = {}) {
+    const [state, dispatch] = useReducer(topUpReducer, TOP_UP_IDLE);
+    const latest = useRef(state);
+    latest.current = state;
+    const settledRef = useRef(onSettled);
+    settledRef.current = onSettled;
+    // Bumped when the tab comes back, so a poll skipped while hidden is re-armed.
+    const [wake, setWake] = useState(0);
+    const create = useCallback((sats) => {
+        const s = latest.current;
+        if (s.phase === "creating" || s.phase === "awaiting")
+            return;
+        dispatch({ type: "create", sats });
+        purchaseCredits(sats).then((result) => dispatch({ type: "created", result }), (e) => dispatch({ type: "error", message: messageOf(e) }));
+    }, []);
+    const check = useCallback(() => {
+        const s = latest.current;
+        if (s.phase !== "awaiting" || s.checking)
+            return;
+        const id = s.invoice.id;
+        dispatch({ type: "check" });
+        checkPayment(id).then((result) => {
+            // A late answer for an invoice the patron has since cancelled is dropped.
+            const now = latest.current;
+            if (now.phase === "awaiting" && now.invoice.id === id)
+                dispatch({ type: "checked", result });
+        }, (e) => dispatch({ type: "error", message: messageOf(e) }));
+    }, []);
+    const cancel = useCallback(() => dispatch({ type: "cancel" }), []);
+    const reset = useCallback(() => dispatch({ type: "reset" }), []);
+    useEffect(() => {
+        if (!(pollMs > 0) || !shouldPoll(state, maxChecks))
+            return;
+        const t = setTimeout(() => {
+            if (tabHidden())
+                return; // re-armed by the visibility listener below
+            check();
+        }, pollMs);
+        return () => clearTimeout(t);
+    }, [state, pollMs, maxChecks, check, wake]);
+    useEffect(() => {
+        if (typeof document === "undefined")
+            return;
+        const onVisible = () => {
+            if (!tabHidden())
+                setWake((n) => n + 1);
+        };
+        document.addEventListener("visibilitychange", onVisible);
+        return () => document.removeEventListener("visibilitychange", onVisible);
+    }, []);
+    useEffect(() => {
+        if (state.phase === "settled")
+            settledRef.current?.(state.credited);
+    }, [state]);
+    return { state, create, check, cancel, reset };
+}

package/dist/standardTools.d.ts

@@ -45,13 +45,36 @@ export interface ProofStatusResult {
     error_code?: string;
 }
 export declare function checkProofStatus(patronNpub: string, dpopToken: string): Promise<ProofStatusResult>;
+/** One credit tranche: a purchase (or grant) and what is left of it. */
+export interface CreditTranche {
+    id: string;
+    amount_sats: number;
+    remaining_sats: number;
+    expires_at: string | null;
+    created_at: string | null;
+}
 export interface CheckBalanceResult {
     success?: boolean;
     balance_api_sats?: number;
     total_deposited_api_sats?: number;
     total_consumed_api_sats?: number;
+    total_expired_api_sats?: number;
+    pending_invoices?: number;
+    pending_invoice_ids?: string[];
+    last_deposit_at?: string | null;
     next_expiration_iso?: string;
     expiring_within_24h_sats?: number;
+    active_tranches?: number;
+    tranches?: CreditTranche[];
+    expired_tranches?: CreditTranche[];
+    seed_balance_granted?: boolean;
+    /** The ledger could not be read: the figures may be stale or zero. */
+    vault_unavailable?: boolean;
+    warning?: string;
+    today_usage?: Record<string, {
+        calls: number;
+        api_sats: number;
+    }>;
     error?: string;
     error_code?: string;
 }
@@ -93,19 +116,99 @@ export interface CheckPaymentResult {
     error_code?: string;
 }
 export declare function checkPayment(invoiceId: string): Promise<CheckPaymentResult>;
-export interface AccountStatementResult {
-    success?: boolean;
-    balance_api_sats?: number;
-    total_deposited_api_sats?: number;
-    total_consumed_api_sats?: number;
-    total_expired_api_sats?: number;
-    today_usage?: Record<string, {
+export interface StatementInvoice {
+    invoice_id: string;
+    status: string;
+    amount_sats: number;
+    api_sats_credited: number;
+    multiplier?: number;
+    created_at: string | null;
+    settled_at?: string;
+}
+export interface StatementTranche {
+    granted_at: string | null;
+    original_sats: number;
+    remaining_sats: number;
+    invoice_id: string | null;
+    expires_at?: string;
+}
+export interface StatementToolUsage {
+    tool: string;
+    calls: number;
+    api_sats: number;
+}
+export interface StatementDay {
+    date: string;
+    total_calls: number;
+    total_api_sats: number;
+    tools: Record<string, {
         calls: number;
         api_sats: number;
     }>;
+}
+/** The wheel's `account_statement`: history, tranches and usage, newest first. */
+export interface AccountStatementResult {
+    success?: boolean;
+    generated_at?: string;
+    statement_period_days?: number;
+    account_summary?: {
+        balance_api_sats: number;
+        total_deposited_api_sats: number;
+        total_consumed_api_sats: number;
+        total_expired_api_sats: number;
+    };
+    purchase_history?: StatementInvoice[];
+    active_tranches?: StatementTranche[];
+    tool_usage_all_time?: StatementToolUsage[];
+    daily_usage?: StatementDay[];
     error?: string;
+    error_code?: string;
 }
 export declare function getAccountStatement(days?: number): Promise<AccountStatementResult>;
+export interface PatronCoupon {
+    coupon_id: string;
+    name: string;
+    discount_percent: number;
+    valid_from: string;
+    valid_until: string;
+    uses_per_patron: number | null;
+    use_count: number;
+    uses_remaining: number | null;
+    total_uses: number | null;
+    total_remaining: number | null;
+    /** active | window_closed | window_not_started | patron_limit | total_limit */
+    status: string;
+}
+export interface ListMyCouponsResult {
+    success?: boolean;
+    count?: number;
+    coupons?: PatronCoupon[];
+    error?: string;
+    error_code?: string;
+}
+export interface RedeemCouponResult {
+    success?: boolean;
+    coupon_id?: string;
+    name?: string;
+    discount_percent?: number;
+    valid_until?: string;
+    uses_remaining?: number | null;
+    uses_per_patron?: number | null;
+    error?: string;
+    error_code?: string;
+}
+export interface ForgetCouponResult {
+    success?: boolean;
+    coupon_id?: string;
+    error?: string;
+    error_code?: string;
+}
+/** The coupons this patron has redeemed here. Free. */
+export declare function listMyCoupons(): Promise<ListMyCouponsResult>;
+/** Redeem an operator's code once; the discount then applies on its own. Free. */
+export declare function redeemCoupon(code: string): Promise<RedeemCouponResult>;
+/** Take a coupon off the patron's list. The code stays re-redeemable while its window allows. */
+export declare function forgetCoupon(couponId: string): Promise<ForgetCouponResult>;
 export interface Kind0 {
     name?: string;
     display_name?: string;

package/dist/standardTools.js

@@ -56,6 +56,18 @@ export function checkPayment(invoiceId) {
 export function getAccountStatement(days = 30) {
     return callTool("account_statement", { days });
 }
+/** The coupons this patron has redeemed here. Free. */
+export function listMyCoupons() {
+    return callTool("list_my_coupons", {});
+}
+/** Redeem an operator's code once; the discount then applies on its own. Free. */
+export function redeemCoupon(code) {
+    return callTool("redeem_coupon", { code });
+}
+/** Take a coupon off the patron's list. The code stays re-redeemable while its window allows. */
+export function forgetCoupon(couponId) {
+    return callTool("forget_coupon", { coupon_id: couponId });
+}
 export function getNostrProfile(npub) {
     return callTool("get_nostr_profile", { npub });
 }

package/dist/table.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Paging, sorting and filtering arithmetic for a table, without a framework.
+ *
+ * Pages are zero-based. A table may be paged by the server (it sends one page
+ * and a total) or in the browser (`pageRows` over the whole list); the
+ * arithmetic is the same either way.
+ */
+export type SortDir = "asc" | "desc";
+/** The last page's index for `total` rows. Zero when there are none. */
+export declare function lastPage(total: number, pageSize: number): number;
+/** A page index that exists: whole, and between 0 and the last page. */
+export declare function clampPage(page: number, total: number, pageSize: number): number;
+export declare function pageCount(total: number, pageSize: number): number;
+/** One page of an in-memory list. */
+export declare function pageRows<T>(rows: readonly T[], page: number, pageSize: number): T[];
+/**
+ * The sort after a header is tapped: the active column flips direction; a new
+ * column starts at `initial` (descending by default — newest, largest first).
+ */
+export declare function nextSort(col: string, activeCol: string, dir: SortDir, initial?: SortDir): {
+    col: string;
+    dir: SortDir;
+};
+/**
+ * A case-insensitive test for `pattern`. It is read as a regular expression
+ * when it is one, and as plain text when it is not, so a stray "(" in a search
+ * box finds the bracket rather than throwing. An empty pattern matches all.
+ */
+export declare function searchMatcher(pattern: string): (text: string) => boolean;
+/** The calendar day ("YYYY-MM-DD") of an ISO stamp or date, or null. */
+export declare function dayOf(value: string | null | undefined): string | null;
+/**
+ * Whether `value` falls in the inclusive range [from, to], compared by day.
+ * An empty bound is open. A row with no date is outside any range that has
+ * a bound, and inside one that has none.
+ */
+export declare function inDateRange(value: string | null | undefined, from: string, to: string): boolean;
+export interface RowFilter {
+    search: string;
+    dateFrom: string;
+    dateTo: string;
+}
+export declare const NO_FILTER: RowFilter;
+export declare function filterActive(f: Partial<RowFilter>, summary?: string): boolean;
+/**
+ * Filter rows in the browser, for a table the server does not filter.
+ * `text` gives what the search reads; `date` the stamp the range reads.
+ */
+export declare function filterRows<T>(rows: readonly T[], f: Partial<RowFilter>, by: {
+    text: (row: T) => string;
+    date?: (row: T) => string | null | undefined;
+}): T[];

package/dist/table.js

@@ -0,0 +1,95 @@
+/**
+ * Paging, sorting and filtering arithmetic for a table, without a framework.
+ *
+ * Pages are zero-based. A table may be paged by the server (it sends one page
+ * and a total) or in the browser (`pageRows` over the whole list); the
+ * arithmetic is the same either way.
+ */
+/** The last page's index for `total` rows. Zero when there are none. */
+export function lastPage(total, pageSize) {
+    if (!(pageSize > 0) || !(total > 0))
+        return 0;
+    return Math.max(0, Math.ceil(total / pageSize) - 1);
+}
+/** A page index that exists: whole, and between 0 and the last page. */
+export function clampPage(page, total, pageSize) {
+    const p = Number.isFinite(page) ? Math.trunc(page) : 0;
+    return Math.min(Math.max(0, p), lastPage(total, pageSize));
+}
+export function pageCount(total, pageSize) {
+    return lastPage(total, pageSize) + 1;
+}
+/** One page of an in-memory list. */
+export function pageRows(rows, page, pageSize) {
+    if (!(pageSize > 0))
+        return [...rows];
+    const p = clampPage(page, rows.length, pageSize);
+    return rows.slice(p * pageSize, (p + 1) * pageSize);
+}
+/**
+ * The sort after a header is tapped: the active column flips direction; a new
+ * column starts at `initial` (descending by default — newest, largest first).
+ */
+export function nextSort(col, activeCol, dir, initial = "desc") {
+    if (col === activeCol)
+        return { col, dir: dir === "desc" ? "asc" : "desc" };
+    return { col, dir: initial };
+}
+// ── Filtering ──────────────────────────────────────────────────────────────
+/**
+ * A case-insensitive test for `pattern`. It is read as a regular expression
+ * when it is one, and as plain text when it is not, so a stray "(" in a search
+ * box finds the bracket rather than throwing. An empty pattern matches all.
+ */
+export function searchMatcher(pattern) {
+    const p = pattern.trim();
+    if (!p)
+        return () => true;
+    try {
+        const re = new RegExp(p, "i");
+        return (text) => re.test(text);
+    }
+    catch {
+        const needle = p.toLowerCase();
+        return (text) => text.toLowerCase().includes(needle);
+    }
+}
+/** The calendar day ("YYYY-MM-DD") of an ISO stamp or date, or null. */
+export function dayOf(value) {
+    if (!value)
+        return null;
+    const m = /^(\d{4}-\d{2}-\d{2})/.exec(value);
+    return m ? m[1] : null;
+}
+/**
+ * Whether `value` falls in the inclusive range [from, to], compared by day.
+ * An empty bound is open. A row with no date is outside any range that has
+ * a bound, and inside one that has none.
+ */
+export function inDateRange(value, from, to) {
+    if (!from && !to)
+        return true;
+    const day = dayOf(value);
+    if (!day)
+        return false;
+    if (from && day < from)
+        return false;
+    if (to && day > to)
+        return false;
+    return true;
+}
+export const NO_FILTER = { search: "", dateFrom: "", dateTo: "" };
+export function filterActive(f, summary = "") {
+    return !!(f.search?.trim() || f.dateFrom || f.dateTo || summary);
+}
+/**
+ * Filter rows in the browser, for a table the server does not filter.
+ * `text` gives what the search reads; `date` the stamp the range reads.
+ */
+export function filterRows(rows, f, by) {
+    const match = searchMatcher(f.search ?? "");
+    const from = f.dateFrom ?? "";
+    const to = f.dateTo ?? "";
+    const ranged = !!(from || to) && !!by.date;
+    return rows.filter((r) => match(by.text(r)) && (!ranged || inDateRange(by.date(r), from, to)));
+}

package/dist/theme.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Light, dark or the system's choice — kept under `<prefix>:theme` so a
+ * returning patron keeps their pick, and applied to <html> before first paint.
+ *
+ * Mechanics only; the colours are the site's. Applying a theme sets all three
+ * hooks a stylesheet might key on, so every fleet site's CSS keeps working:
+ *   - the `dark` class (Tailwind `darkMode: "class"`, `@custom-variant dark`),
+ *   - `data-theme="light" | "dark"` (the package's theme.css and token sheets),
+ *   - `color-scheme` (native form controls and scrollbars).
+ * "system" resolves to the OS preference and follows it live.
+ */
+export type Theme = "dark" | "light" | "system";
+export type EffectiveTheme = "dark" | "light";
+export declare const THEMES: readonly Theme[];
+export declare function isTheme(v: unknown): v is Theme;
+/** The stored pick, or `fallback` when nothing (or nonsense) is stored. */
+export declare function parseTheme(raw: string | null | undefined, fallback?: Theme): Theme;
+export declare function themeStorageKey(): string;
+export declare function readTheme(fallback?: Theme): Theme;
+export declare function writeTheme(theme: Theme): void;
+export declare function systemPrefersDark(): boolean;
+export declare function resolveTheme(theme: Theme, prefersDark?: boolean): EffectiveTheme;
+/** The part of <html> a theme touches — narrow, so it is testable without a DOM. */
+export interface ThemeTarget {
+    classList: {
+        toggle(token: string, force?: boolean): unknown;
+    };
+    setAttribute(name: string, value: string): void;
+    style: {
+        colorScheme: string;
+    };
+}
+export declare function applyTheme(theme: Theme, target?: ThemeTarget, prefersDark?: boolean): EffectiveTheme;
+/**
+ * Apply the stored theme. Call once in main.tsx, after `configureTollbooth`
+ * and before rendering, so the first frame has the right palette.
+ */
+export declare function bootstrapTheme(fallback?: Theme): Theme;
+/** The pick after `current`, for a single chip that cycles. */
+export declare function nextTheme(current: Theme, order?: readonly Theme[]): Theme;

package/dist/theme.js

@@ -0,0 +1,76 @@
+/**
+ * Light, dark or the system's choice — kept under `<prefix>:theme` so a
+ * returning patron keeps their pick, and applied to <html> before first paint.
+ *
+ * Mechanics only; the colours are the site's. Applying a theme sets all three
+ * hooks a stylesheet might key on, so every fleet site's CSS keeps working:
+ *   - the `dark` class (Tailwind `darkMode: "class"`, `@custom-variant dark`),
+ *   - `data-theme="light" | "dark"` (the package's theme.css and token sheets),
+ *   - `color-scheme` (native form controls and scrollbars).
+ * "system" resolves to the OS preference and follows it live.
+ */
+import { tollboothConfig } from "./config.js";
+export const THEMES = ["dark", "light", "system"];
+export function isTheme(v) {
+    return v === "dark" || v === "light" || v === "system";
+}
+/** The stored pick, or `fallback` when nothing (or nonsense) is stored. */
+export function parseTheme(raw, fallback = "dark") {
+    return isTheme(raw) ? raw : fallback;
+}
+export function themeStorageKey() {
+    return `${tollboothConfig().storagePrefix}:theme`;
+}
+export function readTheme(fallback = "dark") {
+    try {
+        return parseTheme(globalThis.localStorage?.getItem(themeStorageKey()), fallback);
+    }
+    catch {
+        return fallback; // blocked site data, or not configured yet
+    }
+}
+export function writeTheme(theme) {
+    try {
+        globalThis.localStorage?.setItem(themeStorageKey(), theme);
+    }
+    catch {
+        /* the choice still applies for this page */
+    }
+}
+export function systemPrefersDark() {
+    try {
+        return !!globalThis.matchMedia?.("(prefers-color-scheme: dark)").matches;
+    }
+    catch {
+        return false;
+    }
+}
+export function resolveTheme(theme, prefersDark = systemPrefersDark()) {
+    if (theme === "system")
+        return prefersDark ? "dark" : "light";
+    return theme;
+}
+export function applyTheme(theme, target, prefersDark) {
+    const effective = resolveTheme(theme, prefersDark);
+    const el = target ?? globalThis.document?.documentElement;
+    if (el) {
+        el.classList.toggle("dark", effective === "dark");
+        el.setAttribute("data-theme", effective);
+        el.style.colorScheme = effective;
+    }
+    return effective;
+}
+/**
+ * Apply the stored theme. Call once in main.tsx, after `configureTollbooth`
+ * and before rendering, so the first frame has the right palette.
+ */
+export function bootstrapTheme(fallback = "dark") {
+    const theme = readTheme(fallback);
+    applyTheme(theme);
+    return theme;
+}
+/** The pick after `current`, for a single chip that cycles. */
+export function nextTheme(current, order = THEMES) {
+    const i = order.indexOf(current);
+    return order[(i + 1) % order.length] ?? order[0];
+}