@tollbooth-dpyc/web 1.0.0 → 1.1.0

package/README.md

@@ -10,7 +10,11 @@ features. It is the peer of the `tollbooth-dpyc` Python wheel.
 - **MCP client** — one shared connection to the operator, typed wrappers for
   the standard tools (balance, top-up, statement, price, profile)
 - **React components** — `NpubGate`, `NostrProfilePanel`, `SessionKeyClaim`, `WalletCard`,
-  `AvatarPicker`, `DebugPanel`, `QuoteScroller`, `useSession`, `useDebugLog`
+  `WalletPage`, `CouponsPanel`, `TableFilter`, `SortHeader` / `PageControls` /
+  `TableShell`, `ThemeToggle`, `ErrorBoundary`, `AvatarPicker`, `DebugPanel`,
+  `QuoteScroller`, `useSession`, `useTopUp`, `useTheme`, `useDebugLog`
+- **Mechanics, not looks** — the newer components take `classNames` per part
+  and add no typography or colour of their own; actions are chips
 - **Debug log** — every call, result and error from `callTool`, scrubbed of
   nsecs, hex keys, tokens and proofs before it is stored
 - **Pages proxy** — the `/mcp` Cloudflare Pages Function
@@ -41,6 +45,64 @@ import { makeMcpProxy } from "@tollbooth-dpyc/web/pages-proxy";
 export const onRequest = makeMcpProxy("https://chartremotely-mcp.fastmcp.app/mcp");
 ```
 
+### Network failures
+
+`callTool` throws a `NetworkError` when the call never reached the service
+(offline, fetch failed, timed out before an answer, the proxy could not reach
+the operator) and a plain `Error` for anything the service said. Only the
+first is safe to queue and send again:
+
+```ts
+import { callTool, isNetworkError } from "@tollbooth-dpyc/web";
+
+try {
+  await callTool("task_save", task);
+} catch (e) {
+  if (isNetworkError(e)) outbox.push({ tool: "task_save", args: task }); // e.tool is the runtime name
+  else throw e;
+}
+```
+
+### Wallet, coupons, tables, theme, error boundary
+
+Mechanics only: the calls, states, paging and persistence are the package's;
+every class is yours. Pass `classNames` (each component's type lists its
+parts); without them the markup is plain and inherits from the page.
+
+```tsx
+import { bootstrapTheme, filterRows, pageRows } from "@tollbooth-dpyc/web";
+import {
+  CouponsPanel, ErrorBoundary, PageControls, SortHeader, TableFilter, TableShell,
+  ThemeToggle, WalletPage,
+} from "@tollbooth-dpyc/web/react";
+
+bootstrapTheme();            // main.tsx, after configureTollbooth: <prefix>:theme → <html>
+
+<ErrorBoundary classNames={{ root: "p-6", chip: "chip" }}>
+  <App />
+</ErrorBoundary>
+
+<WalletPage
+  topUps={[1_000, 5_000, 25_000]}
+  formatDateTime={(iso) => formatInZone(iso, zone)}
+  before={<FundingStatus />}
+  coupons={{ classNames: { root: "card", chip: "chip" } }}
+  classNames={{ section: "card p-5", figure: "text-3xl", chip: "chip", chipActive: "chip-on" }}
+/>
+
+<ThemeToggle themes={["dark", "light", "system"]} classNames={{ chip: "chip", active: "chip-on" }} />
+
+<TableFilter
+  search={{ value: search, onSearch: setSearch, title: "Case-insensitive regular expression" }}
+  dates={{ from, to, onFrom: setFrom, onTo: setTo, field, fields, onField: setField }}
+  onClear={clearAll}
+  classNames={{ root: "flex gap-2", input: "field", chip: "chip" }}
+/>
+```
+
+`useTopUp` is the wallet's top-up on its own (purchase_credits → invoice →
+check_payment, polled while the tab is visible) for a site drawing its own.
+
 ### Debug panel
 
 `callTool` logs to a shared, scrubbed ring buffer; `DebugPanel` shows it as a

package/dist/client.d.ts

@@ -10,6 +10,7 @@
  * 3. Bootstrap tools take no envelope and are safe before sign-in.
  */
 import { type ImageBlock } from "./toolResult.ts";
+export { isNetworkError, NetworkError } from "./networkError.ts";
 /** A paid call bounced for a lapsed or missing proof. The gate re-arms sign-in. */
 export declare class ProofRequiredError extends Error {
     constructor(message: string);
@@ -36,7 +37,10 @@ export interface ToolAnswer<T> {
 /**
  * Call a tool by its short name ("snapshot_display", not
  * "chart_snapshot_display") and get both its answer and any images it sent.
+ *
+ * Throws a `NetworkError` when the call never reached the service (offline,
+ * fetch failed, timed out before an answer) — safe to queue and send again —
+ * and a plain `Error` for anything the service answered, which is not.
  */
 export declare function callToolWithContent<T = unknown>(tool: string, args?: Record<string, unknown>, opts?: CallOptions): Promise<ToolAnswer<T>>;
 export declare function callTool<T = unknown>(tool: string, args?: Record<string, unknown>, opts?: CallOptions): Promise<T>;
-export {};

package/dist/client.js

@@ -15,6 +15,7 @@ import { tollboothConfig, toolName } from "./config.js";
 import { debugPush } from "./debugLog.js";
 import { clearStoredProof, forgetRecentLogin, getStoredNpub, getStoredProof, } from "./identity.js";
 import { signInlineProof } from "./inlineProof.js";
+import { isTransportFailure, NetworkError } from "./networkError.js";
 import { clearSessionNsec, hasSessionNsec, sessionNsecNpub } from "./sessionNsec.js";
 import { errorText, looksFailed, proofBounceMessage, readToolResult, } from "./toolResult.js";
 /**
@@ -84,6 +85,7 @@ function proofFor(tool) {
     }
     return getStoredProof();
 }
+export { isNetworkError, NetworkError } from "./networkError.js";
 /** A paid call bounced for a lapsed or missing proof. The gate re-arms sign-in. */
 export class ProofRequiredError extends Error {
     constructor(message) {
@@ -114,6 +116,10 @@ function emitProofExpired(message) {
 /**
  * Call a tool by its short name ("snapshot_display", not
  * "chart_snapshot_display") and get both its answer and any images it sent.
+ *
+ * Throws a `NetworkError` when the call never reached the service (offline,
+ * fetch failed, timed out before an answer) — safe to queue and send again —
+ * and a plain `Error` for anything the service answered, which is not.
  */
 export async function callToolWithContent(tool, args = {}, opts = {}) {
     const cfg = tollboothConfig();
@@ -133,9 +139,16 @@ export async function callToolWithContent(tool, args = {}, opts = {}) {
         result = (await c.callTool({ name, arguments: merged }, undefined, { timeout: opts.timeoutMs ?? 120_000 }));
     }
     catch (e) {
+        const why = e instanceof Error ? e.message : String(e);
+        if (isTransportFailure(e)) {
+            // Never reached the service, or no answer came back: safe to retry.
+            if (!quiet)
+                debugPush("error", `${name}: unreachable — ${why}`);
+            throw new NetworkError(name, e);
+        }
         if (!quiet)
-            debugPush("error", `${name}: ${e.message}`);
-        throw new Error(`${name}: ${e.message}`);
+            debugPush("error", `${name}: ${why}`);
+        throw new Error(`${name}: ${why}`, { cause: e });
     }
     if (result.isError) {
         const text = errorText(result);

package/dist/errorReport.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The text a crash screen offers to copy: the error, where it was thrown, the
+ * component stack, and the recent activity log (already scrubbed of secrets).
+ */
+export declare function errorReport(error: unknown, componentStack?: string, log?: string): string;

package/dist/errorReport.js

@@ -0,0 +1,14 @@
+/**
+ * The text a crash screen offers to copy: the error, where it was thrown, the
+ * component stack, and the recent activity log (already scrubbed of secrets).
+ */
+export function errorReport(error, componentStack = "", log = "") {
+    const e = error instanceof Error ? error : null;
+    const message = e ? e.message : String(error ?? "(unknown)");
+    return [
+        `Error: ${message}`,
+        e?.stack ? `\n${e.stack}` : "",
+        componentStack ? `\nComponent stack:${componentStack}` : "",
+        log ? `\n\n--- recent activity ---\n${log}` : "",
+    ].join("");
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { configureTollbooth, tollboothConfig, toolName, type TollboothConfig } from "./config.ts";
-export { callTool, callToolWithContent, onProofExpired, ProofRequiredError, type CallOptions, type ToolAnswer, } from "./client.ts";
+export { callTool, callToolWithContent, isNetworkError, NetworkError, onProofExpired, ProofRequiredError, type CallOptions, type ToolAnswer, } from "./client.ts";
 export type { ImageBlock } from "./toolResult.ts";
 export * from "./identity.ts";
 export * from "./standardTools.ts";
@@ -11,5 +11,10 @@ export { canSignFor, isProven, type Claim } from "./signedIn.ts";
 export { readSignInFailure, type Situation } from "./signInSituation.ts";
 export { canSignProfile, fetchProfile, publishProfile } from "./nostrProfile.ts";
 export * from "./avatar.ts";
+export { isTransportFailure } from "./networkError.ts";
+export * from "./wallet.ts";
+export * from "./table.ts";
+export * from "./theme.ts";
+export { errorReport } from "./errorReport.ts";
 export { loadQuotes, peekQuotes, shuffle, validQuotes, type Quote } from "./quotes.ts";
 export { captureGlobalErrors, clearDebug, configureDebugLog, debugEntries, debugLogText, debugPush, debugSeverity, onDebug, redact, type DebugEntry, type DebugLogOptions, type DebugSeverity, } from "./debugLog.ts";

package/dist/index.js

@@ -1,5 +1,5 @@
 export { configureTollbooth, tollboothConfig, toolName } from "./config.js";
-export { callTool, callToolWithContent, onProofExpired, ProofRequiredError, } from "./client.js";
+export { callTool, callToolWithContent, isNetworkError, NetworkError, onProofExpired, ProofRequiredError, } from "./client.js";
 export * from "./identity.js";
 export * from "./standardTools.js";
 export { clearSessionNsec, getSessionNsec, getSessionNsecBytes, hasSessionNsec, sessionNsecNpub, setSessionNsec, } from "./sessionNsec.js";
@@ -10,5 +10,10 @@ export { canSignFor, isProven } from "./signedIn.js";
 export { readSignInFailure } from "./signInSituation.js";
 export { canSignProfile, fetchProfile, publishProfile } from "./nostrProfile.js";
 export * from "./avatar.js";
+export { isTransportFailure } from "./networkError.js";
+export * from "./wallet.js";
+export * from "./table.js";
+export * from "./theme.js";
+export { errorReport } from "./errorReport.js";
 export { loadQuotes, peekQuotes, shuffle, validQuotes } from "./quotes.js";
 export { captureGlobalErrors, clearDebug, configureDebugLog, debugEntries, debugLogText, debugPush, debugSeverity, onDebug, redact, } from "./debugLog.js";

package/dist/networkError.d.ts

@@ -0,0 +1,29 @@
+/**
+ * "The call never reached the service" as its own kind of failure.
+ *
+ * A page that queues writes while offline (an outbox) must tell a call that
+ * never arrived — safe to send again later — from one the service answered
+ * with a refusal, which must not be replayed. `callTool` throws a
+ * `NetworkError` for the first kind only; everything the service said,
+ * including a tool's `isError` answer and an HTTP status it returned, stays a
+ * plain `Error`.
+ *
+ * Pure: it inspects the thrown value and imports nothing from the MCP SDK, so
+ * it is tested without a network.
+ */
+export declare class NetworkError extends Error {
+    /** The runtime tool name the call was for, e.g. "goodearth_task_save". */
+    readonly tool: string;
+    constructor(tool: string, cause: unknown);
+}
+export declare function isNetworkError(e: unknown): e is NetworkError;
+/**
+ * Whether a thrown value means the call did not reach the service (or no
+ * answer came back): the browser is offline, fetch itself failed, the request
+ * was aborted or timed out before a response, or the site's Pages proxy could
+ * not reach the operator (its 502 "Proxy error").
+ *
+ * `online` is `navigator.onLine`; when the browser knows it is offline, any
+ * failure is a network one.
+ */
+export declare function isTransportFailure(e: unknown, online?: boolean): boolean;

package/dist/networkError.js

@@ -0,0 +1,61 @@
+/**
+ * "The call never reached the service" as its own kind of failure.
+ *
+ * A page that queues writes while offline (an outbox) must tell a call that
+ * never arrived — safe to send again later — from one the service answered
+ * with a refusal, which must not be replayed. `callTool` throws a
+ * `NetworkError` for the first kind only; everything the service said,
+ * including a tool's `isError` answer and an HTTP status it returned, stays a
+ * plain `Error`.
+ *
+ * Pure: it inspects the thrown value and imports nothing from the MCP SDK, so
+ * it is tested without a network.
+ */
+export class NetworkError extends Error {
+    /** The runtime tool name the call was for, e.g. "goodearth_task_save". */
+    tool;
+    constructor(tool, cause) {
+        const why = cause instanceof Error ? cause.message : String(cause);
+        super(`${tool}: ${why}`, { cause });
+        this.name = "NetworkError";
+        this.tool = tool;
+    }
+}
+export function isNetworkError(e) {
+    return e instanceof NetworkError;
+}
+// What each browser's fetch says when the request never left, or never came
+// back: Chrome "Failed to fetch", Safari "Load failed", Firefox "NetworkError
+// when attempting to fetch resource.", Node/undici "fetch failed".
+const FETCH_FAILED = /failed to fetch|load failed|networkerror|fetch failed|network request failed|network connection was lost/i;
+// The SDK's own codes for "no answer came": the connection closed, or the
+// request timed out waiting.
+const MCP_CONNECTION_CLOSED = -32000;
+const MCP_REQUEST_TIMEOUT = -32001;
+/**
+ * Whether a thrown value means the call did not reach the service (or no
+ * answer came back): the browser is offline, fetch itself failed, the request
+ * was aborted or timed out before a response, or the site's Pages proxy could
+ * not reach the operator (its 502 "Proxy error").
+ *
+ * `online` is `navigator.onLine`; when the browser knows it is offline, any
+ * failure is a network one.
+ */
+export function isTransportFailure(e, online = globalThis.navigator?.onLine ?? true) {
+    if (!online)
+        return true;
+    if (!(e instanceof Error))
+        return false;
+    if (e.name === "AbortError" || e.name === "TimeoutError")
+        return true;
+    if (e instanceof TypeError)
+        return FETCH_FAILED.test(e.message);
+    const code = e.code;
+    if (e.name === "McpError")
+        return code === MCP_REQUEST_TIMEOUT || code === MCP_CONNECTION_CLOSED;
+    // StreamableHTTPError: the HTTP status the page got back. Only the proxy's
+    // own 502 — its fetch to the operator threw — means the operator never saw it.
+    if (e.message.startsWith("Streamable HTTP error:"))
+        return code === 502 && /Proxy error/.test(e.message);
+    return false;
+}

package/dist/react/CouponsPanel.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The patron's coupons: redeem an operator's code once, see what is held, and
+ * take one off the list.
+ *
+ * Mechanics only — the calls (list_my_coupons, redeem_coupon, forget_coupon),
+ * the states and the words. Every visual choice is the site's, through
+ * `classNames`; with none, the panel is plain markup inheriting from the page.
+ * Actions (Redeem, Remove) are chips: `classNames.chip`.
+ */
+import { type ReactNode } from "react";
+import { type PatronCoupon } from "../standardTools.ts";
+export interface CouponsPanelClassNames {
+    root?: string;
+    heading?: string;
+    intro?: string;
+    /** The code box and the Redeem chip. */
+    form?: string;
+    input?: string;
+    /** Every action: Redeem, Remove. */
+    chip?: string;
+    /** Added to the message after a redeem, with `ok` or `error`. */
+    message?: string;
+    ok?: string;
+    error?: string;
+    loading?: string;
+    empty?: string;
+    list?: string;
+    row?: string;
+    name?: string;
+    discount?: string;
+    /** The status · uses · expiry line. */
+    meta?: string;
+    /** Added to the status word when the coupon is active. */
+    active?: string;
+}
+export interface CouponsPanelProps {
+    heading?: ReactNode;
+    intro?: ReactNode;
+    /** Shown when the patron holds no coupons. */
+    empty?: ReactNode;
+    placeholder?: string;
+    /** Content of the Redeem chip. */
+    redeemLabel?: ReactNode;
+    /** Content of each row's Remove chip. */
+    forgetLabel?: ReactNode;
+    /** Asked before a coupon is removed. Default: the browser's confirm(). */
+    confirmForget?: (coupon: PatronCoupon) => boolean | Promise<boolean>;
+    classNames?: CouponsPanelClassNames;
+    /** Draw a coupon's row yourself; `forget` removes it (after confirmForget). */
+    renderCoupon?: (coupon: PatronCoupon, forget: () => void) => ReactNode;
+}
+export default function CouponsPanel({ heading, intro, empty, placeholder, redeemLabel, forgetLabel, confirmForget, classNames: c, renderCoupon, }: CouponsPanelProps): import("react").JSX.Element;

package/dist/react/CouponsPanel.js

@@ -0,0 +1,98 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The patron's coupons: redeem an operator's code once, see what is held, and
+ * take one off the list.
+ *
+ * Mechanics only — the calls (list_my_coupons, redeem_coupon, forget_coupon),
+ * the states and the words. Every visual choice is the site's, through
+ * `classNames`; with none, the panel is plain markup inheriting from the page.
+ * Actions (Redeem, Remove) are chips: `classNames.chip`.
+ */
+import { useCallback, useEffect, useState } from "react";
+import { forgetCoupon, listMyCoupons, redeemCoupon } from "../standardTools.js";
+import { couponExpiryText, couponStatusLabel, couponUsesText, redeemedText } from "../wallet.js";
+const DEFAULT_INTRO = "Redeem an operator's code once. The discount applies on its own to later paid calls until its uses or its window run out.";
+const DEFAULT_EMPTY = "No coupons yet. Paste a code above to claim its discount.";
+function defaultConfirm() {
+    return (typeof window === "undefined" ||
+        window.confirm("Remove this coupon from your list? You can redeem the code again while its window allows."));
+}
+function cx(...parts) {
+    const s = parts.filter(Boolean).join(" ");
+    return s || undefined;
+}
+export default function CouponsPanel({ heading = "My coupons", intro = DEFAULT_INTRO, empty = DEFAULT_EMPTY, placeholder = "Coupon code", redeemLabel = "Redeem", forgetLabel = "Remove", confirmForget = defaultConfirm, classNames: c = {}, renderCoupon, }) {
+    const [coupons, setCoupons] = useState([]);
+    const [loading, setLoading] = useState(true);
+    const [loadError, setLoadError] = useState(null);
+    const [code, setCode] = useState("");
+    const [redeeming, setRedeeming] = useState(false);
+    const [msg, setMsg] = useState(null);
+    const refresh = useCallback(async () => {
+        setLoading(true);
+        setLoadError(null);
+        try {
+            const r = await listMyCoupons();
+            if (r.error)
+                setLoadError(r.error);
+            else
+                setCoupons(r.coupons ?? []);
+        }
+        catch (e) {
+            setLoadError(e.message);
+        }
+        finally {
+            setLoading(false);
+        }
+    }, []);
+    useEffect(() => {
+        void refresh();
+    }, [refresh]);
+    async function redeem() {
+        const trimmed = code.trim();
+        if (!trimmed || redeeming)
+            return;
+        setRedeeming(true);
+        setMsg(null);
+        try {
+            const r = await redeemCoupon(trimmed);
+            if (r.success) {
+                setMsg({ ok: true, text: redeemedText(r) });
+                setCode("");
+                void refresh();
+            }
+            else {
+                setMsg({ ok: false, text: r.error ?? "That code could not be redeemed." });
+            }
+        }
+        catch (e) {
+            setMsg({ ok: false, text: e.message });
+        }
+        finally {
+            setRedeeming(false);
+        }
+    }
+    async function forget(coupon) {
+        if (!(await confirmForget(coupon)))
+            return;
+        try {
+            const r = await forgetCoupon(coupon.coupon_id);
+            if (r.error)
+                setMsg({ ok: false, text: r.error });
+            else
+                setCoupons((cs) => cs.filter((x) => x.coupon_id !== coupon.coupon_id));
+        }
+        catch (e) {
+            setMsg({ ok: false, text: e.message });
+        }
+    }
+    return (_jsxs("section", { className: c.root, children: [heading && _jsx("div", { className: c.heading, children: heading }), intro && _jsx("p", { className: c.intro, children: intro }), _jsxs("div", { className: c.form, children: [_jsx("input", { type: "text", value: code, onChange: (e) => setCode(e.target.value.toUpperCase()), onKeyDown: (e) => {
+                            if (e.key === "Enter")
+                                void redeem();
+                        }, placeholder: placeholder, "aria-label": "Coupon code", autoCapitalize: "characters", autoCorrect: "off", spellCheck: false, disabled: redeeming, className: c.input }), _jsx("button", { type: "button", onClick: () => void redeem(), disabled: redeeming || !code.trim(), className: c.chip, children: redeeming ? "Redeeming…" : redeemLabel })] }), msg && (_jsx("p", { role: "status", className: cx(c.message, msg.ok ? c.ok : c.error), children: msg.text })), loading ? (_jsx("p", { className: c.loading, children: "Loading\u2026" })) : loadError ? (_jsx("p", { className: cx(c.message, c.error), children: loadError })) : coupons.length === 0 ? (empty && _jsx("p", { className: c.empty, children: empty })) : (_jsx("ul", { className: c.list, children: coupons.map((coupon) => renderCoupon ? (_jsx("li", { className: c.row, children: renderCoupon(coupon, () => void forget(coupon)) }, coupon.coupon_id)) : (_jsx(CouponRow, { coupon: coupon, c: c, forgetLabel: forgetLabel, onForget: () => void forget(coupon) }, coupon.coupon_id))) }))] }));
+}
+function CouponRow({ coupon, c, forgetLabel, onForget, }) {
+    const active = coupon.status === "active";
+    const expiry = active ? couponExpiryText(coupon.valid_until) : null;
+    return (_jsxs("li", { className: c.row, children: [_jsxs("div", { children: [_jsx("span", { className: c.name, children: coupon.name }), " ", _jsxs("span", { className: c.discount, children: [coupon.discount_percent, "% off"] }), _jsxs("div", { className: c.meta, children: [_jsx("span", { className: active ? c.active : undefined, children: couponStatusLabel(coupon.status) }), " · ", couponUsesText(coupon), expiry && ` · ${expiry}`] })] }), _jsx("button", { type: "button", onClick: onForget, title: "Remove from your list (the code can be redeemed again while its window allows)", className: c.chip, children: forgetLabel })] }));
+}

package/dist/react/ErrorBoundary.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The last guard: a render-time throw shows a calm card instead of a white
+ * screen. Data paths catch their own failures; this catches what they miss.
+ *
+ * The crash is pushed to the package debug log (scrubbed, and persisted when
+ * the site turned that on), so it can still be read after a reload. The
+ * default card shows the error and offers Copy error + log / Try again /
+ * Reload chips. Mechanics only: `classNames` styles it, or `fallback` replaces
+ * it entirely.
+ */
+import { Component, type ErrorInfo, type ReactNode } from "react";
+export interface ErrorFallbackProps {
+    error: Error;
+    componentStack: string;
+    /** The error, its stacks and the recent activity log, ready to copy. */
+    report: () => string;
+    /** Render the children again. */
+    reset: () => void;
+}
+export interface ErrorBoundaryClassNames {
+    root?: string;
+    title?: string;
+    message?: string;
+    /** The <pre> with the error and component stack. */
+    detail?: string;
+    /** The row of chips. */
+    actions?: string;
+    chip?: string;
+}
+export interface ErrorBoundaryProps {
+    children: ReactNode;
+    /** Replace the default card. */
+    fallback?: ReactNode | ((p: ErrorFallbackProps) => ReactNode);
+    title?: ReactNode;
+    message?: ReactNode;
+    /** Show the error text and component stack on the card. Default true. */
+    showDetail?: boolean;
+    onError?: (error: Error, componentStack: string) => void;
+    classNames?: ErrorBoundaryClassNames;
+}
+interface State {
+    error: Error | null;
+    stack: string;
+    copied: boolean;
+}
+export default class ErrorBoundary extends Component<ErrorBoundaryProps, State> {
+    state: State;
+    static getDerivedStateFromError(error: Error): Partial<State>;
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    private report;
+    private reset;
+    private copy;
+    render(): ReactNode;
+}
+export {};

package/dist/react/ErrorBoundary.js

@@ -0,0 +1,49 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The last guard: a render-time throw shows a calm card instead of a white
+ * screen. Data paths catch their own failures; this catches what they miss.
+ *
+ * The crash is pushed to the package debug log (scrubbed, and persisted when
+ * the site turned that on), so it can still be read after a reload. The
+ * default card shows the error and offers Copy error + log / Try again /
+ * Reload chips. Mechanics only: `classNames` styles it, or `fallback` replaces
+ * it entirely.
+ */
+import { Component } from "react";
+import { debugLogText, debugPush } from "../debugLog.js";
+import { errorReport } from "../errorReport.js";
+export default class ErrorBoundary extends Component {
+    state = { error: null, stack: "", copied: false };
+    static getDerivedStateFromError(error) {
+        return { error };
+    }
+    componentDidCatch(error, info) {
+        const stack = info.componentStack ?? "";
+        this.setState({ stack });
+        debugPush("error", `render crash: ${error.message}`);
+        console.error("Unhandled render error:", error, stack);
+        this.props.onError?.(error, stack);
+    }
+    report = () => errorReport(this.state.error, this.state.stack, debugLogText());
+    reset = () => this.setState({ error: null, stack: "", copied: false });
+    copy = () => {
+        navigator.clipboard?.writeText(this.report()).then(() => {
+            this.setState({ copied: true });
+            setTimeout(() => this.setState({ copied: false }), 1500);
+        }, () => { });
+    };
+    render() {
+        const { error, stack, copied } = this.state;
+        if (!error)
+            return this.props.children;
+        const { fallback, title = "Something went sideways", showDetail = true, classNames: c = {} } = this.props;
+        if (typeof fallback === "function") {
+            return fallback({ error, componentStack: stack, report: this.report, reset: this.reset });
+        }
+        if (fallback !== undefined)
+            return fallback;
+        const message = this.props.message ??
+            "The page hit an unexpected error. It is saved to the debug log — copy it into a bug report. Reloading usually clears it.";
+        return (_jsxs("div", { role: "alert", className: c.root, children: [_jsx("h1", { className: c.title, children: title }), _jsx("p", { className: c.message, children: message }), showDetail && (_jsxs("pre", { className: c.detail, children: [error.message, stack ? `\n${stack}` : ""] })), _jsxs("div", { className: c.actions, children: [_jsx("button", { type: "button", onClick: this.copy, className: c.chip, children: copied ? "Copied" : "Copy error + log" }), _jsx("button", { type: "button", onClick: this.reset, className: c.chip, children: "Try again" }), _jsx("button", { type: "button", onClick: () => window.location.reload(), className: c.chip, children: "Reload" })] })] }));
+    }
+}

package/dist/react/PagedTable.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The parts of a sortable, paged table: a header cell that sorts, the
+ * First / Prev / Page N of M / Next / Last controls, and the frame.
+ *
+ * Mechanics only — the sort toggling and the paging arithmetic (`nextSort`,
+ * `lastPage`, `clampPage` in the framework-free half). How it looks is the
+ * site's, through `classNames`; the controls are chips. Paging can be the
+ * server's (pass its total) or the browser's (`pageRows`).
+ */
+import type { ReactNode } from "react";
+import { type SortDir } from "../table.ts";
+export interface SortHeaderClassNames {
+    /** The <th>. */
+    cell?: string;
+    /** The button inside a sortable header. */
+    button?: string;
+    /** Added to the button of the column being sorted. */
+    active?: string;
+    /** The ▾ / ▴ mark. */
+    arrow?: string;
+}
+export interface SortHeaderProps {
+    label: ReactNode;
+    /** The column's sort key. Omit for a header that does not sort. */
+    col?: string;
+    activeCol: string;
+    dir: SortDir;
+    onSort: (col: string, dir: SortDir) => void;
+    /** The direction a newly chosen column starts in. Default "desc". */
+    initialDir?: SortDir;
+    classNames?: SortHeaderClassNames;
+}
+/** A header cell. Tapping the sorted column flips it; another column starts at `initialDir`. */
+export declare function SortHeader({ label, col, activeCol, dir, onSort, initialDir, classNames: c }: SortHeaderProps): import("react").JSX.Element;
+export interface PageControlsClassNames {
+    root?: string;
+    /** Every control. */
+    chip?: string;
+    /** "Page N of M · K total". */
+    label?: string;
+}
+export interface PageControlsProps {
+    /** Zero-based. */
+    page: number;
+    pageSize: number;
+    total: number;
+    onPage: (page: number) => void;
+    /** Render nothing when everything fits on one page. Default false. */
+    hideSinglePage?: boolean;
+    classNames?: PageControlsClassNames;
+}
+/** First / ← Prev / Page N of M · K total / Next → / Last. */
+export declare function PageControls({ page, pageSize, total, onPage, hideSinglePage, classNames: c }: PageControlsProps): import("react").JSX.Element | null;
+export interface TableShellClassNames {
+    /** The frame. Give it `overflow-x: auto` to scroll a wide table — the
+     *  package does not, since a scrolling box clips popovers inside it. */
+    root?: string;
+    table?: string;
+}
+/** The frame every paged table sits in: a box and the <table>. */
+export declare function TableShell({ children, classNames: c }: {
+    children: ReactNode;
+    classNames?: TableShellClassNames;
+}): import("react").JSX.Element;

package/dist/react/PagedTable.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { clampPage, lastPage, nextSort } from "../table.js";
+function cx(...parts) {
+    const s = parts.filter(Boolean).join(" ");
+    return s || undefined;
+}
+/** A header cell. Tapping the sorted column flips it; another column starts at `initialDir`. */
+export function SortHeader({ label, col, activeCol, dir, onSort, initialDir = "desc", classNames: c = {} }) {
+    if (!col)
+        return _jsx("th", { className: c.cell, children: label });
+    const active = col === activeCol;
+    return (_jsx("th", { className: c.cell, "aria-sort": active ? (dir === "desc" ? "descending" : "ascending") : undefined, children: _jsxs("button", { type: "button", onClick: () => {
+                const next = nextSort(col, activeCol, dir, initialDir);
+                onSort(next.col, next.dir);
+            }, className: cx(c.button, active && c.active), children: [label, active && (_jsx("span", { "aria-hidden": true, className: c.arrow, children: dir === "desc" ? " ▾" : " ▴" }))] }) }));
+}
+/** First / ← Prev / Page N of M · K total / Next → / Last. */
+export function PageControls({ page, pageSize, total, onPage, hideSinglePage = false, classNames: c = {} }) {
+    const last = lastPage(total, pageSize);
+    if (hideSinglePage && last === 0)
+        return null;
+    const p = clampPage(page, total, pageSize);
+    return (_jsxs("nav", { "aria-label": "Pages", className: c.root, children: [_jsx("button", { type: "button", className: c.chip, disabled: p === 0, onClick: () => onPage(0), title: "First page", "aria-label": "First page", children: "\u23EE" }), _jsx("button", { type: "button", className: c.chip, disabled: p === 0, onClick: () => onPage(p - 1), children: "\u2190 Prev" }), _jsxs("span", { className: c.label, children: ["Page ", p + 1, " of ", last + 1, " \u00B7 ", total.toLocaleString("en-US"), " total"] }), _jsx("button", { type: "button", className: c.chip, disabled: p >= last, onClick: () => onPage(p + 1), children: "Next \u2192" }), _jsx("button", { type: "button", className: c.chip, disabled: p >= last, onClick: () => onPage(last), title: "Last page", "aria-label": "Last page", children: "\u23ED" })] }));
+}
+/** The frame every paged table sits in: a box and the <table>. */
+export function TableShell({ children, classNames: c = {} }) {
+    return (_jsx("div", { className: c.root, children: _jsx("table", { className: c.table, children: children }) }));
+}