@tollbooth-dpyc/web 0.5.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,11 +45,74 @@ 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
-bar along the bottom of the page with Copy and Clear. Put it once near the root.
-Anything the site alone needs goes in as children, drawn above the log:
+bar along the bottom of the page with Copy and Clear. Put it once, **last** in
+the app shell. The bar is fixed to the viewport, but it also keeps its own
+room in the page: an in-flow spacer as tall as the bar is right now (collapsed
+or open) plus the iOS safe-area inset, so the page's last line always scrolls
+clear of it. Mounted last, that spacer is the page's last thing; mounted
+earlier, the room opens up there instead. Anything the site alone needs goes
+in as children, drawn above the log:
 
 ```tsx
 import { configureDebugLog, debugPush } from "@tollbooth-dpyc/web";
@@ -115,6 +182,14 @@ them after:
 :root { --tb-accent: #4cc38a; }
 ```
 
+## Stability
+
+From 1.0.0 the public API — everything exported from `@tollbooth-dpyc/web`,
+`/react`, `/pages-proxy` and the `theme.css` tokens — follows semver. Patch and
+minor releases are safe to take unattended (the fleet's Renovate preset
+auto-merges them); a breaking change ships only as a new major, which Renovate
+holds for review.
+
 ## Develop
 
 ```sh

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/DebugPanel.d.ts

@@ -13,6 +13,12 @@
  *
  * Touch-first: every control is a real button at least 40px square, nothing
  * hides behind hover, and the page under the bar stays tappable.
+ *
+ * The panel keeps its own space: beside the fixed bar it renders an in-flow
+ * spacer as tall as the bar is right now (collapsed or open, measured with a
+ * ResizeObserver) plus the iOS safe-area inset, so the page's last line can
+ * always scroll clear of it. Mount it LAST in the app shell so that spacer is
+ * the last thing in the page's flow.
  */
 import { type ReactNode } from "react";
 export interface DebugPanelProps {

package/dist/react/DebugPanel.js

@@ -14,11 +14,18 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
  *
  * Touch-first: every control is a real button at least 40px square, nothing
  * hides behind hover, and the page under the bar stays tappable.
+ *
+ * The panel keeps its own space: beside the fixed bar it renders an in-flow
+ * spacer as tall as the bar is right now (collapsed or open, measured with a
+ * ResizeObserver) plus the iOS safe-area inset, so the page's last line can
+ * always scroll clear of it. Mount it LAST in the app shell so that spacer is
+ * the last thing in the page's flow.
  */
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { onProofExpired } from "../client.js";
 import { captureGlobalErrors, clearDebug, debugLogText, debugPush, debugSeverity, } from "../debugLog.js";
 import { readStored, writeStored } from "../storage.js";
+import { debugSpacerHeight, debugSpacerPx } from "./debugSpacer.js";
 import { useDebugLog } from "./useDebugLog.js";
 const OPEN_KEY = "debug-open";
 const TYPE_INK = {
@@ -40,6 +47,26 @@ export default function DebugPanel({ title = "Debug", defaultOpen = false, captu
         return saved === "" ? defaultOpen : saved === "1";
     });
     const [copied, setCopied] = useState("");
+    const barRef = useRef(null);
+    // Null until measured (and on the server, or with no ResizeObserver): the
+    // spacer then reserves the collapsed bar.
+    const [barHeight, setBarHeight] = useState(null);
+    useEffect(() => {
+        const bar = barRef.current;
+        const RO = globalThis.ResizeObserver;
+        if (!bar || !RO)
+            return;
+        // The observer reports once on observe and after every resize — opening,
+        // closing, a new log line, rotation — batched to the frame, and a state
+        // write only when the whole-pixel height actually changes.
+        const ro = new RO((entries) => {
+            const box = entries[entries.length - 1]?.borderBoxSize?.[0];
+            const next = debugSpacerPx(box ? box.blockSize : bar.getBoundingClientRect().height);
+            setBarHeight((prev) => (prev === next ? prev : next));
+        });
+        ro.observe(bar);
+        return () => ro.disconnect();
+    }, []);
     useEffect(() => {
         if (!captureErrors)
             return;
@@ -73,9 +100,9 @@ export default function DebugPanel({ title = "Debug", defaultOpen = false, captu
         : notices > 0
             ? "bg-[var(--tb-notice-bg)] text-[var(--tb-notice-ink)] border-[var(--tb-notice-line)]"
             : "bg-[var(--tb-surface-2)] text-[var(--tb-ink)] border-[var(--tb-line)]";
-    return (_jsxs("div", { className: "pointer-events-none fixed inset-x-0 bottom-0 z-50 flex flex-col items-end", children: [_jsxs("div", { className: "pointer-events-auto flex flex-wrap justify-end gap-1 pr-3", children: [open && (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", onClick: copy, className: plainTab, "aria-label": "Copy the whole log", children: copied === "ok" ? "Copied" : copied === "failed" ? "Copy failed" : "Copy" }), _jsx("button", { type: "button", onClick: clearDebug, className: plainTab, children: "Clear" })] })), _jsxs("button", { type: "button", onClick: toggle, "aria-expanded": open, className: `${tab} ${toggleTone}`, children: [open ? "Hide" : title, " (", log.length, failures > 0 ? ` · ${failures} err` : "", notices > 0 ? ` · ${notices} notice` : "", ")"] })] }), open && (_jsxs("div", { className: "pointer-events-auto max-h-[40vh] w-full overflow-y-auto border-t border-[var(--tb-line)] bg-[var(--tb-surface)] p-3 font-mono text-xs text-[var(--tb-ink)]", children: [children && _jsx("div", { className: "mb-2 border-b border-[var(--tb-line)] pb-2 font-sans", children: children }), log.length === 0 && _jsx("div", { className: "text-[var(--tb-muted)]", children: "No MCP activity yet." }), log.map((entry, i) => {
-                        const sev = debugSeverity(entry);
-                        const flag = sev === "ok" ? null : FLAGGED[sev];
-                        return (_jsxs("div", { className: `-mx-1 flex gap-2 rounded px-1 py-0.5 ${flag?.row ?? ""}`, children: [_jsx("span", { className: "shrink-0 text-[var(--tb-muted)]", children: entry.ts }), _jsxs("span", { className: `w-14 shrink-0 ${flag?.ink ?? TYPE_INK[entry.type]}`, children: [sev === "notice" ? "notice" : entry.type, sev === "failure" && entry.type !== "error" ? " !" : ""] }), _jsx("span", { className: `min-w-0 break-all ${flag?.ink ?? ""}`, children: entry.message })] }, log.length - i));
-                    })] }))] }));
+    return (_jsxs(_Fragment, { children: [_jsx("div", { "aria-hidden": "true", "data-tb-debug-spacer": "", style: { height: debugSpacerHeight(barHeight), flexShrink: 0 } }), _jsxs("div", { ref: barRef, className: "pointer-events-none fixed inset-x-0 bottom-0 z-50 flex flex-col items-end", children: [_jsxs("div", { className: "pointer-events-auto flex flex-wrap justify-end gap-1 pr-3", children: [open && (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", onClick: copy, className: plainTab, "aria-label": "Copy the whole log", children: copied === "ok" ? "Copied" : copied === "failed" ? "Copy failed" : "Copy" }), _jsx("button", { type: "button", onClick: clearDebug, className: plainTab, children: "Clear" })] })), _jsxs("button", { type: "button", onClick: toggle, "aria-expanded": open, className: `${tab} ${toggleTone}`, children: [open ? "Hide" : title, " (", log.length, failures > 0 ? ` · ${failures} err` : "", notices > 0 ? ` · ${notices} notice` : "", ")"] })] }), open && (_jsxs("div", { className: "pointer-events-auto max-h-[40vh] w-full overflow-y-auto border-t border-[var(--tb-line)] bg-[var(--tb-surface)] p-3 font-mono text-xs text-[var(--tb-ink)]", children: [children && _jsx("div", { className: "mb-2 border-b border-[var(--tb-line)] pb-2 font-sans", children: children }), log.length === 0 && _jsx("div", { className: "text-[var(--tb-muted)]", children: "No MCP activity yet." }), log.map((entry, i) => {
+                                const sev = debugSeverity(entry);
+                                const flag = sev === "ok" ? null : FLAGGED[sev];
+                                return (_jsxs("div", { className: `-mx-1 flex gap-2 rounded px-1 py-0.5 ${flag?.row ?? ""}`, children: [_jsx("span", { className: "shrink-0 text-[var(--tb-muted)]", children: entry.ts }), _jsxs("span", { className: `w-14 shrink-0 ${flag?.ink ?? TYPE_INK[entry.type]}`, children: [sev === "notice" ? "notice" : entry.type, sev === "failure" && entry.type !== "error" ? " !" : ""] }), _jsx("span", { className: `min-w-0 break-all ${flag?.ink ?? ""}`, children: entry.message })] }, log.length - i));
+                            })] }))] })] }));
 }

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 {};