@tollbooth-dpyc/web 1.4.1 → 1.5.0

package/README.md

@@ -9,7 +9,8 @@ features. It is the peer of the `tollbooth-dpyc` Python wheel.
   kind-27235 inline proof when the tab holds a session key
 - **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`,
+- **React components** — `AppShell` / `useAppShell`, `SiteNav`, `AccountPage`,
+  `RefreshButton`, `NpubGate`, `NostrProfilePanel`, `SessionKeyClaim`, `WalletCard`,
   `WalletPage`, `CouponsPanel`, `UsageSummary`, `PatronFundingStatus` /
   `OperatorFundingStatus`, `BuildInfoPanel`, `TimezonePicker`, `TableFilter`,
   `SortHeader` / `PageControls` / `TableShell`, `ThemeToggle`, `ErrorBoundary`,
@@ -174,6 +175,74 @@ import { BuildInfoPanel, OperatorFundingStatus, PatronFundingStatus, UsageSummar
   `service_status`; only https links), the Tollbooth-DPYC™ links, the licence
   and the patent notice. `children` adds rows after the MCP server section.
 
+### App shell, site nav, account page, refresh
+
+The frame a site used to write for itself. `AppShell` holds the session, the
+sign-in gate, `service_status`, the theme and the debug log (mounted last);
+it owns no routes. `useAppShell()` gives any component inside the same npub,
+`signOut` and status, so the site keeps no session context of its own.
+
+```tsx
+import { AccountPage, AppShell, RefreshButton, SiteNav, matchesPath, useAppShell } from "@tollbooth-dpyc/web/react";
+
+<AppShell
+  signedOut={({ gate }) => <><TopBar /><Hero />{gate}</>}
+  footer={({ status }) => <Footer status={status} />}
+  debug={{ children: <SchedulerLogSection /> }}
+  fit="page"                                     // "viewport" for a bottom rail
+>
+  {() => <BrowserRouter><Nav /><Routes>…</Routes></BrowserRouter>}
+</AppShell>
+
+function Nav() {
+  const { session } = useAppShell();
+  const { pathname } = useLocation();
+  return (
+    <SiteNav
+      brand={<Link to="/">eXcalibur</Link>}
+      items={[{ href: "/", label: "Posts", end: true }, { href: "/wallet", label: "Wallet", icon: <Wallet /> }]}
+      isActive={(href, item) => matchesPath(pathname, href, item.end)}
+      renderLink={({ href, ...p }) => <Link to={href} {...p} />}
+      trailing={<BalanceChip />}
+      account={{ npub: session.npub, links: [{ href: "/profile", label: "Profile & theme" }], onSignOut: session.signOut }}
+      classNames={{ root: "flex items-center gap-1.5", list: "flex gap-1", item: "chip", active: "chip-on", end: "ml-auto flex gap-3" }}
+    />
+  );
+}
+
+<AccountPage
+  npub={session.npub}
+  between={{ sessionKey: <XConnectPanel /> }}
+  timezone={{ note: (pref, zone) => (pref === "auto" ? `Currently ${zone}.` : `Using ${zone}.`) }}
+  build={{ status, frontend: { version: __APP_VERSION__, source: "https://github.com/you/site" } }}
+  onSignOut={session.signOut}
+  classNames={{ root: "space-y-5", section: "card p-5", signOut: "chip" }}
+/>
+
+<RefreshButton onRefresh={load} label="Refresh posts" classNames={{ root: "h-12 w-12 rounded-lg" }} />
+```
+
+- `AppShell`: signed in → `children(shell)`; signed out → `signedOut(shell)`,
+  placing `shell.gate` (the `NpubGate`, wired to the operator fingerprint and
+  the lapsed-sign-in note), or the gate alone. The frame is a column: "page"
+  grows with the content; "viewport" pins it to the screen and lets the
+  content shrink, so the debug log's spacer never pushes a bottom rail off.
+- `SiteNav`: brand, pages (icon, label, badge), `trailing`, and an account
+  menu (avatar → identity, links, Log out). Below `collapse` (default
+  `(max-width: 639px)`; `false` never) the pages fold into a menu button.
+  Both popovers set `aria-expanded`, focus their first item, close on Escape
+  (focus back to the button), on a press or focus outside, and move with the
+  arrows, Home and End; tap targets are at least 40 px. Router-agnostic:
+  `isActive` and `renderLink` (plain `<a>` and `location.pathname` by
+  default); `matchesPath(pathname, href, end)` is segment-bounded.
+- `AccountPage`: Nostr profile, session key, usage, time zone, theme, coupons,
+  build — one order. Each section is `false` or its own props; `before`,
+  `after`, and `between[section]` (kept in place when that section is off)
+  hold the site's panels.
+- `RefreshButton`: spins (`motion-safe:animate-spin`, or
+  `classNames.spinning`), is disabled and `aria-busy` while `onRefresh`'s
+  promise runs or `busy` is set; `label` is the tooltip and accessible name.
+
 ### Debug panel
 
 `callTool` logs to a shared, scrubbed ring buffer; `DebugPanel` shows it as a

package/dist/react/AccountPage.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The Profile page every site composed for itself, in one order for all of
+ * them: Nostr profile, session key, usage, time zone, theme, coupons, build.
+ *
+ * Each section is on by default; `false` turns it off and an object passes it
+ * its own props (headings, words, `classNames`). A site's own panels go in
+ * `before`, `after`, or `between` — `between.sessionKey` is drawn right after
+ * the session key, and keeps that place even when the section is off (a site
+ * with its own coupons turns `coupons` off and puts them in `between.coupons`).
+ *
+ * Mechanics only: the time zone and theme controls sit in a `<section>` with a
+ * heading and a line of intro (`classNames.section` …); every other panel draws
+ * itself. Log out is a chip at the end when `onSignOut` is given.
+ */
+import { type ReactNode } from "react";
+import type { Kind0 } from "../standardTools.ts";
+import type { TimezonePref } from "../timezone.ts";
+import { type AccountSection } from "./accountSections.ts";
+import { type BuildInfoPanelProps } from "./BuildInfoPanel.tsx";
+import { type CouponsPanelProps } from "./CouponsPanel.tsx";
+import { type SessionKeyClaimProps } from "./SessionKeyClaim.tsx";
+import { type ThemeToggleProps } from "./ThemeToggle.tsx";
+import { type TimezonePickerProps } from "./TimezonePicker.tsx";
+import { type UsageSummaryProps } from "./UsageSummary.tsx";
+export interface AccountSectionText {
+    heading?: ReactNode;
+    intro?: ReactNode;
+}
+export interface AccountTimezoneProps extends TimezonePickerProps, AccountSectionText {
+    /** A line under the picker, given the stored pick and the zone it resolves to now. */
+    note?: (pref: TimezonePref, zone: string) => ReactNode;
+}
+export interface AccountThemeProps extends ThemeToggleProps, AccountSectionText {
+}
+export interface AccountPageClassNames {
+    root?: string;
+    heading?: string;
+    /** The time-zone and theme sections: box, heading, intro, note. */
+    section?: string;
+    sectionHeading?: string;
+    sectionIntro?: string;
+    sectionNote?: string;
+    /** The row holding Log out, and the chip. */
+    actions?: string;
+    signOut?: string;
+}
+export interface AccountPageProps {
+    npub: string;
+    /** Default "Profile"; null for none. */
+    heading?: ReactNode;
+    profile?: boolean | {
+        onPublished?: (profile: Kind0) => void;
+    };
+    sessionKey?: boolean | Omit<SessionKeyClaimProps, "npub">;
+    usage?: boolean | UsageSummaryProps;
+    timezone?: boolean | AccountTimezoneProps;
+    theme?: boolean | AccountThemeProps;
+    coupons?: boolean | CouponsPanelProps;
+    build?: boolean | BuildInfoPanelProps;
+    before?: ReactNode;
+    /** A site's panel after the named section. */
+    between?: Partial<Record<AccountSection, ReactNode>>;
+    after?: ReactNode;
+    onSignOut?: () => void;
+    /** Default "Log out". */
+    signOutLabel?: ReactNode;
+    classNames?: AccountPageClassNames;
+}
+export default function AccountPage({ npub, heading, profile, sessionKey, usage, timezone, theme, coupons, build, before, between, after, onSignOut, signOutLabel, classNames: c, }: AccountPageProps): import("react").JSX.Element;

package/dist/react/AccountPage.js

@@ -0,0 +1,65 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The Profile page every site composed for itself, in one order for all of
+ * them: Nostr profile, session key, usage, time zone, theme, coupons, build.
+ *
+ * Each section is on by default; `false` turns it off and an object passes it
+ * its own props (headings, words, `classNames`). A site's own panels go in
+ * `before`, `after`, or `between` — `between.sessionKey` is drawn right after
+ * the session key, and keeps that place even when the section is off (a site
+ * with its own coupons turns `coupons` off and puts them in `between.coupons`).
+ *
+ * Mechanics only: the time zone and theme controls sit in a `<section>` with a
+ * heading and a line of intro (`classNames.section` …); every other panel draws
+ * itself. Log out is a chip at the end when `onSignOut` is given.
+ */
+import { Fragment } from "react";
+import { accountSteps } from "./accountSections.js";
+import BuildInfoPanel, {} from "./BuildInfoPanel.js";
+import CouponsPanel, {} from "./CouponsPanel.js";
+import NostrProfilePanel from "./NostrProfilePanel.js";
+import SessionKeyClaim, {} from "./SessionKeyClaim.js";
+import ThemeToggle, {} from "./ThemeToggle.js";
+import TimezonePicker, {} from "./TimezonePicker.js";
+import UsageSummary, {} from "./UsageSummary.js";
+import { useTimezone } from "./useTimezone.js";
+const opts = (v) => (typeof v === "object" ? v : {});
+export default function AccountPage({ npub, heading = "Profile", profile, sessionKey, usage, timezone, theme, coupons, build, before, between = {}, after, onSignOut, signOutLabel = "Log out", classNames: c = {}, }) {
+    const [tzPref, tzZone] = useTimezone();
+    const shown = {
+        profile: profile !== false,
+        sessionKey: sessionKey !== false,
+        usage: usage !== false,
+        timezone: timezone !== false,
+        theme: theme !== false,
+        coupons: coupons !== false,
+        build: build !== false,
+    };
+    const section = (key) => {
+        switch (key) {
+            case "profile":
+                return _jsx(NostrProfilePanel, { npub: npub, ...opts(profile) });
+            case "sessionKey":
+                // Keyed by npub so a revealed key never carries across a sign-in.
+                return _jsx(SessionKeyClaim, { npub: npub, ...opts(sessionKey) }, npub);
+            case "usage":
+                return _jsx(UsageSummary, { ...opts(usage) });
+            case "timezone": {
+                const { heading: h = "Display time zone", intro, note, ...picker } = opts(timezone);
+                return (_jsxs(Section, { heading: h, intro: intro, c: c, children: [_jsx(TimezonePicker, { ...picker }), note && _jsx("p", { className: c.sectionNote, children: note(tzPref, tzZone) })] }));
+            }
+            case "theme": {
+                const { heading: h = "Appearance", intro, ...toggle } = opts(theme);
+                return (_jsx(Section, { heading: h, intro: intro, c: c, children: _jsx(ThemeToggle, { ...toggle }) }));
+            }
+            case "coupons":
+                return _jsx(CouponsPanel, { ...opts(coupons) });
+            case "build":
+                return _jsx(BuildInfoPanel, { ...opts(build) });
+        }
+    };
+    return (_jsxs("div", { className: c.root, children: [heading != null && _jsx("h1", { className: c.heading, children: heading }), before, accountSteps(shown, between).map((step) => (_jsx(Fragment, { children: step.kind === "section" ? section(step.section) : between[step.section] }, `${step.kind}:${step.section}`))), after, onSignOut && (_jsx("div", { className: c.actions, children: _jsx("button", { type: "button", onClick: onSignOut, className: c.signOut, children: signOutLabel }) }))] }));
+}
+function Section({ heading, intro, c, children, }) {
+    return (_jsxs("section", { className: c.section, children: [heading != null && _jsx("h2", { className: c.sectionHeading, children: heading }), intro != null && _jsx("p", { className: c.sectionIntro, children: intro }), children] }));
+}

package/dist/react/AppShell.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The frame every operator site had written for itself: who is signed in, the
+ * sign-in gate when nobody is, the service's status, the theme, the footer and
+ * the debug log — laid out so the log's room never pushes a bottom rail off
+ * the screen.
+ *
+ * It owns no routes. `children(shell)` draws the signed-in site (its nav and
+ * its router); `signedOut(shell)` draws the signed-out one, with
+ * `shell.gate` — the package `NpubGate`, already wired to sign in, to the
+ * operator's fingerprint and to the "your sign-in lapsed" note — wherever it
+ * belongs (under a hero, or on one route of a public site). Without
+ * `signedOut` the gate is the page.
+ *
+ * Inside, `useAppShell()` gives any component the same `shell` — the npub,
+ * `signOut`, the `service_status` answer — so a site keeps no session context
+ * of its own.
+ *
+ * Also done here, once: the stored theme applied before paint and followed
+ * across tabs; the npub's kind-0 picture seeded as its avatar; `DebugPanel`
+ * mounted last, so its spacer is the page's last thing (see `shellLayout`).
+ */
+import { type ReactNode } from "react";
+import { type ServiceStatus } from "../standardTools.ts";
+import { type Theme } from "../theme.ts";
+import { type DebugPanelProps } from "./DebugPanel.tsx";
+import { type ShellFit } from "./shellLayout.ts";
+import { type Session } from "./useSession.ts";
+export interface AppShellContext {
+    session: Session;
+    /** The `service_status` answer, or null until (or unless) it comes. */
+    status: ServiceStatus | null;
+    /** The sign-in gate, ready to place. */
+    gate: ReactNode;
+}
+export interface AppShellClassNames {
+    root?: string;
+    /** The region the site draws in, between the top of the page and the footer. */
+    body?: string;
+}
+export interface AppShellProps {
+    /** The signed-in site: its nav, its routes. */
+    children: (shell: AppShellContext) => ReactNode;
+    /** The signed-out site, placing `shell.gate`. Default: the gate alone. */
+    signedOut?: (shell: AppShellContext) => ReactNode;
+    footer?: ReactNode | ((shell: AppShellContext) => ReactNode);
+    /** The debug log's props (its children are the site's own section), or false for none. */
+    debug?: DebugPanelProps | false;
+    /** The theme when none is stored. Default "dark". */
+    theme?: Theme;
+    /** "page" grows with the content; "viewport" pins to the screen for a bottom rail. Default "page". */
+    fit?: ShellFit;
+    /** Arrive at the gate with a new key already made. */
+    startFresh?: boolean;
+    classNames?: AppShellClassNames;
+}
+/** The shell's session, status and gate, for any component inside `AppShell`. */
+export declare function useAppShell(): AppShellContext;
+export default function AppShell({ children, signedOut, footer, debug, theme, fit, startFresh, classNames: c, }: AppShellProps): import("react").JSX.Element;

package/dist/react/AppShell.js

@@ -0,0 +1,65 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The frame every operator site had written for itself: who is signed in, the
+ * sign-in gate when nobody is, the service's status, the theme, the footer and
+ * the debug log — laid out so the log's room never pushes a bottom rail off
+ * the screen.
+ *
+ * It owns no routes. `children(shell)` draws the signed-in site (its nav and
+ * its router); `signedOut(shell)` draws the signed-out one, with
+ * `shell.gate` — the package `NpubGate`, already wired to sign in, to the
+ * operator's fingerprint and to the "your sign-in lapsed" note — wherever it
+ * belongs (under a hero, or on one route of a public site). Without
+ * `signedOut` the gate is the page.
+ *
+ * Inside, `useAppShell()` gives any component the same `shell` — the npub,
+ * `signOut`, the `service_status` answer — so a site keeps no session context
+ * of its own.
+ *
+ * Also done here, once: the stored theme applied before paint and followed
+ * across tabs; the npub's kind-0 picture seeded as its avatar; `DebugPanel`
+ * mounted last, so its spacer is the page's last thing (see `shellLayout`).
+ */
+import { createContext, useContext, useEffect, useLayoutEffect, useState } from "react";
+import { hydrateAvatarFromNostr } from "../avatar.js";
+import { serviceStatus } from "../standardTools.js";
+import { bootstrapTheme } from "../theme.js";
+import DebugPanel, {} from "./DebugPanel.js";
+import NpubGate from "./NpubGate.js";
+import { shellLayout } from "./shellLayout.js";
+import { useSession } from "./useSession.js";
+import { useTheme } from "./useTheme.js";
+const Ctx = createContext(null);
+/** The shell's session, status and gate, for any component inside `AppShell`. */
+export function useAppShell() {
+    const shell = useContext(Ctx);
+    if (!shell)
+        throw new Error("useAppShell must be used inside <AppShell>");
+    return shell;
+}
+export default function AppShell({ children, signedOut, footer, debug = {}, theme = "dark", fit = "page", startFresh, classNames: c = {}, }) {
+    const session = useSession();
+    const [status, setStatus] = useState(null);
+    useTheme(theme);
+    useLayoutEffect(() => {
+        bootstrapTheme(theme);
+    }, [theme]);
+    useEffect(() => {
+        let live = true;
+        serviceStatus({ bestEffort: true })
+            .then((s) => live && setStatus(s))
+            .catch(() => live && setStatus(null));
+        return () => {
+            live = false;
+        };
+    }, []);
+    const { npub, signedIn, notice, refresh } = session;
+    useEffect(() => {
+        if (signedIn && npub)
+            void hydrateAvatarFromNostr(npub);
+    }, [signedIn, npub]);
+    const gate = (_jsx(NpubGate, { onLogin: refresh, operatorHash: status?.operator_npub_hash, notice: notice, startFresh: startFresh }));
+    const shell = { session, status, gate };
+    const layout = shellLayout(fit);
+    return (_jsx(Ctx.Provider, { value: shell, children: _jsxs("div", { className: c.root, style: layout.root, children: [_jsx("div", { className: c.body, style: layout.body, children: signedIn ? children(shell) : signedOut ? signedOut(shell) : gate }), typeof footer === "function" ? footer(shell) : footer, debug !== false && _jsx(DebugPanel, { ...debug })] }) }));
+}

package/dist/react/RefreshButton.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The one refresh control: an icon button that spins while the re-read runs.
+ *
+ * Give it `onRefresh`; if that returns a promise the button is busy — spinning,
+ * disabled, `aria-busy` — until it settles, so a second press cannot start a
+ * second read. `busy` adds a busy state the site already holds (a page's
+ * first load). A rejected refresh is not swallowed: it still rejects, and the
+ * debug log's unhandled-rejection capture records it.
+ *
+ * Mechanics only: the size, colour and shape are the site's (`classNames`);
+ * the spin is `motion-safe:animate-spin` unless `classNames.spinning` names
+ * another. The label is both the tooltip and the accessible name — override it
+ * only to say WHAT refreshes.
+ */
+import { type ReactNode } from "react";
+export interface RefreshButtonClassNames {
+    root?: string;
+    /** Around the glyph. */
+    icon?: string;
+    /** Added around the glyph while busy. Default "motion-safe:animate-spin". */
+    spinning?: string;
+}
+export interface RefreshButtonProps {
+    onRefresh: () => unknown;
+    /** Busy for a reason the button did not start. */
+    busy?: boolean;
+    /** Tooltip and accessible name. Default "Refresh". */
+    label?: string;
+    /** Replaces the refresh glyph. */
+    icon?: ReactNode;
+    /** The default glyph's size in px. Default 20. */
+    iconSize?: number;
+    classNames?: RefreshButtonClassNames;
+}
+export default function RefreshButton({ onRefresh, busy, label, icon, iconSize, classNames: c, }: RefreshButtonProps): import("react").JSX.Element;

package/dist/react/RefreshButton.js

@@ -0,0 +1,44 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The one refresh control: an icon button that spins while the re-read runs.
+ *
+ * Give it `onRefresh`; if that returns a promise the button is busy — spinning,
+ * disabled, `aria-busy` — until it settles, so a second press cannot start a
+ * second read. `busy` adds a busy state the site already holds (a page's
+ * first load). A rejected refresh is not swallowed: it still rejects, and the
+ * debug log's unhandled-rejection capture records it.
+ *
+ * Mechanics only: the size, colour and shape are the site's (`classNames`);
+ * the spin is `motion-safe:animate-spin` unless `classNames.spinning` names
+ * another. The label is both the tooltip and the accessible name — override it
+ * only to say WHAT refreshes.
+ */
+import { useEffect, useRef, useState } from "react";
+import { RefreshCw } from "lucide-react";
+import { cx } from "./cx.js";
+const TAP = { minWidth: 40, minHeight: 40 };
+const GLYPH = { display: "inline-flex" };
+export default function RefreshButton({ onRefresh, busy = false, label = "Refresh", icon, iconSize = 20, classNames: c = {}, }) {
+    const [running, setRunning] = useState(false);
+    const live = useRef(true);
+    useEffect(() => {
+        live.current = true;
+        return () => {
+            live.current = false;
+        };
+    }, []);
+    const spinning = busy || running;
+    function press() {
+        if (spinning)
+            return;
+        const result = onRefresh();
+        if (!(result instanceof Promise))
+            return;
+        setRunning(true);
+        void result.finally(() => {
+            if (live.current)
+                setRunning(false);
+        });
+    }
+    return (_jsx("button", { type: "button", onClick: press, disabled: spinning, "aria-busy": spinning, "aria-label": label, title: label, className: c.root, style: TAP, children: _jsx("span", { "aria-hidden": true, className: cx(c.icon, spinning && (c.spinning ?? "motion-safe:animate-spin")), style: GLYPH, children: icon ?? _jsx(RefreshCw, { size: iconSize }) }) }));
+}

package/dist/react/SessionKeyClaim.d.ts

@@ -4,13 +4,19 @@
  * Renders ONLY when this browser holds the session nsec for the signed-in
  * npub. NIP-07 and courier-proof sign-ins see nothing: no disabled control,
  * no placeholder, no mention. Painting the key takes two deliberate taps —
- * "Claim your session key", then the Reveal chip — so an account page opened
+ * "Claim your session key", then the Reveal (eye) button — so an account page opened
  * in front of other people does not show it.
  *
  * Destinations: copy, download .env, password-manager prompt, and an
  * encrypted DM to another npub the patron names. The nsec never reaches a
  * log, error text, analytics call, or MCP tool argument.
  */
-export default function SessionKeyClaim({ npub }: {
+export interface SessionKeyClaimClassNames {
+    /** Each round icon action (Reveal, Copy, .env, password manager, DM) when not active. Default: the package's outlined chip. */
+    action?: string;
+}
+export interface SessionKeyClaimProps {
     npub: string;
-}): import("react").JSX.Element | null;
+    classNames?: SessionKeyClaimClassNames;
+}
+export default function SessionKeyClaim({ npub, classNames }: SessionKeyClaimProps): import("react").JSX.Element | null;

package/dist/react/SessionKeyClaim.js

@@ -5,7 +5,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * Renders ONLY when this browser holds the session nsec for the signed-in
  * npub. NIP-07 and courier-proof sign-ins see nothing: no disabled control,
  * no placeholder, no mention. Painting the key takes two deliberate taps —
- * "Claim your session key", then the Reveal chip — so an account page opened
+ * "Claim your session key", then the Reveal (eye) button — so an account page opened
  * in front of other people does not show it.
  *
  * Destinations: copy, download .env, password-manager prompt, and an
@@ -13,13 +13,14 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * log, error text, analytics call, or MCP tool argument.
  */
 import { useRef, useState } from "react";
+import { Check, Copy, Download, Eye, EyeOff, KeyRound, Send } from "lucide-react";
 import { tollboothConfig } from "../config.js";
 import { passwordManagerOutcomeLabel, sessionKeyClaimVisible, sessionKeyEnvContents, sessionKeyEnvFilename, } from "../sessionKeyClaim.js";
 import { sendSessionKeyDm } from "../sessionKeyDm.js";
 import { getSessionNsec, getSessionNsecBytes, hasSessionNsec, sessionNsecNpub, } from "../sessionNsec.js";
 import { shareOrDownload } from "../shareFile.js";
 import { card, input, muted } from "./ui.js";
-export default function SessionKeyClaim({ npub }) {
+export default function SessionKeyClaim({ npub, classNames = {} }) {
     const visible = sessionKeyClaimVisible({
         hasSessionNsec: hasSessionNsec(),
         sessionNsecNpub: sessionNsecNpub(),
@@ -28,9 +29,9 @@ export default function SessionKeyClaim({ npub }) {
     // Hard requirement: silence when the browser does not hold the key.
     if (!visible)
         return null;
-    return _jsx(SessionKeyClaimInner, {});
+    return _jsx(SessionKeyClaimInner, { actionClass: classNames.action });
 }
-function SessionKeyClaimInner() {
+function SessionKeyClaimInner({ actionClass }) {
     const { slug, appName } = tollboothConfig();
     const envFilename = sessionKeyEnvFilename(slug);
     const [revealed, setRevealed] = useState(false);
@@ -162,17 +163,19 @@ function SessionKeyClaimInner() {
                             setDmOpen(false);
                             setFlash(null);
                             setRecipient("");
-                        }, className: `text-[12px] ${muted} hover:text-[var(--tb-ink)]`, children: "Hide" })] }), _jsxs("p", { className: `mb-3 text-[12.5px] leading-relaxed ${muted}`, children: ["Anyone who holds this key is you. It leaves this page only when you choose a destination below \u2014 never logged, never sent to ", appName, "."] }), _jsxs("div", { className: "flex flex-wrap gap-2", children: [_jsx(DestButton, { onClick: () => setShowKey((v) => !v), active: showKey, children: showKey ? "Conceal" : "Reveal" }), _jsx(DestButton, { onClick: () => void copyKey(), disabled: busy, children: copied ? "Copied" : "Copy" }), _jsx(DestButton, { onClick: () => void downloadEnv(), disabled: busy, children: "Download .env" }), _jsx(DestButton, { onClick: () => void passwordManagerSave(), disabled: busy, children: "Password manager" }), _jsx(DestButton, { onClick: () => {
+                        }, className: `text-[12px] ${muted} hover:text-[var(--tb-ink)]`, children: "Hide" })] }), _jsxs("p", { className: `mb-3 text-[12.5px] leading-relaxed ${muted}`, children: ["Anyone who holds this key is you. It leaves this page only when you choose a destination below \u2014 never logged, never sent to ", appName, "."] }), _jsxs("div", { className: "flex flex-wrap gap-2", children: [_jsx(DestButton, { label: showKey ? "Conceal the key" : "Reveal the key", onClick: () => setShowKey((v) => !v), active: showKey, className: actionClass, children: showKey ? _jsx(EyeOff, { size: 20, "aria-hidden": "true" }) : _jsx(Eye, { size: 20, "aria-hidden": "true" }) }), _jsx(DestButton, { label: copied ? "Copied" : "Copy the key", onClick: () => void copyKey(), disabled: busy, className: actionClass, children: copied ? _jsx(Check, { size: 20, "aria-hidden": "true" }) : _jsx(Copy, { size: 20, "aria-hidden": "true" }) }), _jsx(DestButton, { label: "Download a .env file", onClick: () => void downloadEnv(), disabled: busy, className: actionClass, children: _jsx(Download, { size: 20, "aria-hidden": "true" }) }), _jsx(DestButton, { label: "Save to your password manager", onClick: () => void passwordManagerSave(), disabled: busy, className: actionClass, children: _jsx(KeyRound, { size: 20, "aria-hidden": "true" }) }), _jsx(DestButton, { label: "Send by encrypted DM", onClick: () => {
                             setDmOpen((v) => !v);
                             setFlash(null);
-                        }, disabled: busy, active: dmOpen, children: "Send by DM" })] }), showKey && (_jsx("div", { className: "mt-3 break-all rounded-lg border border-[var(--tb-line)] bg-[var(--tb-surface-2)] px-3 py-2 font-mono text-[12px] text-[var(--tb-ink)]", children: getSessionNsec() })), dmOpen && (_jsxs("div", { className: "mt-3 space-y-2 rounded-lg border border-[var(--tb-line)] bg-[var(--tb-surface-2)] p-3", children: [_jsx("p", { className: `text-[12px] leading-relaxed ${muted}`, children: "Encrypts the key to an npub you own and publishes the sealed message to public relays. Only that npub can open it." }), _jsxs("div", { className: "flex flex-wrap items-end gap-2", children: [_jsxs("label", { className: `block min-w-[16rem] flex-1 text-[12px] ${muted}`, children: ["Recipient npub", _jsx("input", { value: recipient, onChange: (e) => setRecipient(e.target.value), spellCheck: false, autoCapitalize: "off", autoCorrect: "off", placeholder: "npub1\u2026", className: `mt-1 h-11 ${input}` })] }), _jsx("button", { type: "button", onClick: () => void sendDm(), disabled: busy || recipient.trim().length < 60, className: "min-h-11 shrink-0 rounded-full border border-[var(--tb-accent)] bg-[var(--tb-accent)] px-4 text-[13px] font-semibold text-[var(--tb-on-accent)] disabled:opacity-40", children: busy ? "Sending…" : "Send encrypted DM" })] })] })), _jsxs("form", { ref: formRef, className: "absolute h-px w-px overflow-hidden opacity-0", "aria-hidden": "true", autoComplete: "on", onSubmit: (e) => {
+                        }, disabled: busy, active: dmOpen, className: actionClass, children: _jsx(Send, { size: 20, "aria-hidden": "true" }) })] }), showKey && (_jsx("div", { className: "mt-3 break-all rounded-lg border border-[var(--tb-line)] bg-[var(--tb-surface-2)] px-3 py-2 font-mono text-[12px] text-[var(--tb-ink)]", children: getSessionNsec() })), dmOpen && (_jsxs("div", { className: "mt-3 space-y-2 rounded-lg border border-[var(--tb-line)] bg-[var(--tb-surface-2)] p-3", children: [_jsx("p", { className: `text-[12px] leading-relaxed ${muted}`, children: "Encrypts the key to an npub you own and publishes the sealed message to public relays. Only that npub can open it." }), _jsxs("div", { className: "flex flex-wrap items-end gap-2", children: [_jsxs("label", { className: `block min-w-[16rem] flex-1 text-[12px] ${muted}`, children: ["Recipient npub", _jsx("input", { value: recipient, onChange: (e) => setRecipient(e.target.value), spellCheck: false, autoCapitalize: "off", autoCorrect: "off", placeholder: "npub1\u2026", className: `mt-1 h-11 ${input}` })] }), _jsx("button", { type: "button", onClick: () => void sendDm(), disabled: busy || recipient.trim().length < 60, className: "min-h-11 shrink-0 rounded-full border border-[var(--tb-accent)] bg-[var(--tb-accent)] px-4 text-[13px] font-semibold text-[var(--tb-on-accent)] disabled:opacity-40", children: busy ? "Sending…" : "Send encrypted DM" })] })] })), _jsxs("form", { ref: formRef, className: "absolute h-px w-px overflow-hidden opacity-0", "aria-hidden": "true", autoComplete: "on", onSubmit: (e) => {
                     e.preventDefault();
                 }, children: [_jsx("input", { ref: userRef, name: "username", autoComplete: "username", defaultValue: "", readOnly: true, tabIndex: -1 }), _jsx("input", { ref: passRef, name: "password", type: "password", autoComplete: "new-password", defaultValue: "", readOnly: true, tabIndex: -1 })] }), flash && (_jsx("p", { className: `mt-3 text-[12.5px] leading-relaxed ${flash.tone === "ok" ? "text-[var(--tb-ink)]" : "text-[var(--tb-err-ink)]"}`, role: "status", children: flash.text }))] }));
 }
-function DestButton({ onClick, disabled, active, children, }) {
-    return (_jsx("button", { type: "button", onClick: onClick, disabled: disabled, className: `min-h-11 shrink-0 rounded-full border px-3.5 text-[12.5px] font-medium disabled:opacity-40 ${active
+/** An icon-only round action. `label` is its aria-label and tooltip. */
+function DestButton({ label, onClick, disabled, active, className, children, }) {
+    const idle = className ?? `border-[var(--tb-line)] ${muted} active:bg-[var(--tb-surface-2)]`;
+    return (_jsx("button", { type: "button", onClick: onClick, disabled: disabled, "aria-label": label, title: label, className: `inline-flex h-11 w-11 shrink-0 items-center justify-center rounded-full border focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--tb-accent)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--tb-surface)] disabled:opacity-40 ${active
             ? "border-[var(--tb-accent)] bg-[var(--tb-accent)] text-[var(--tb-on-accent)]"
-            : `border-[var(--tb-line)] ${muted} active:bg-[var(--tb-surface-2)]`}`, children: children }));
+            : idle}`, children: children }));
 }
 /**
  * Offer the key to a browser password manager. Never claims an OS keychain.

package/dist/react/SiteNav.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The top bar: the site's brand, its pages, and on the right whatever the site
+ * keeps there (a balance chip) and the account menu (avatar → identity, links,
+ * log out). On a phone the pages fold into a menu button.
+ *
+ * Mechanics only. The package owns which page is current, the phone fold, the
+ * two popovers (aria-expanded, focus into the menu and back to its button,
+ * Escape, a press outside, the arrow keys) and 40 px tap targets; every class
+ * is the site's, through `classNames` — with none it is plain markup.
+ *
+ * Router-agnostic: `isActive(href, item)` says which page is current and
+ * `renderLink` draws each link (a react-router `<Link to>`); by default the
+ * links are plain `<a href>` and the current page is read from
+ * `location.pathname`. `matchesPath` is the matching a site's `isActive`
+ * usually wants.
+ */
+import { type CSSProperties, type ReactNode } from "react";
+export interface SiteNavItem {
+    href: string;
+    label: ReactNode;
+    icon?: ReactNode;
+    /** A count or mark after the label; nothing when null or undefined. */
+    badge?: ReactNode;
+    /** Current only on this exact path, not the pages beneath it (the home item). */
+    end?: boolean;
+    title?: string;
+}
+export interface SiteNavLinkProps {
+    href: string;
+    className?: string;
+    style?: CSSProperties;
+    title?: string;
+    "aria-current"?: "page";
+    onClick?: () => void;
+    children: ReactNode;
+}
+export interface SiteNavAccount {
+    npub: string;
+    /** Over the npub in the menu. Default "Nostr identity". */
+    heading?: ReactNode;
+    /** The menu's links (Profile, Wallet). */
+    links?: readonly SiteNavItem[];
+    onSignOut?: () => void;
+    /** Default "Log out". */
+    signOutLabel?: ReactNode;
+    /** Default 32. */
+    avatarSize?: number;
+    /** The avatar button's accessible name. Default "Account". */
+    label?: string;
+}
+export interface SiteNavClassNames {
+    root?: string;
+    /** The `<nav>` holding the pages (or, folded, the menu button and menu). */
+    nav?: string;
+    /** The pages in a row. */
+    list?: string;
+    item?: string;
+    /** Added to the current page's link, in the row and (unless `menuItemActive`) the menu. */
+    active?: string;
+    icon?: string;
+    label?: string;
+    badge?: string;
+    /** The right side: `trailing` and the account menu. */
+    end?: string;
+    /** The phone menu's button, and the menu. */
+    toggle?: string;
+    menu?: string;
+    menuItem?: string;
+    menuItemActive?: string;
+    /** The account menu's wrapper, avatar button and popover. */
+    account?: string;
+    accountButton?: string;
+    accountMenu?: string;
+    accountHeader?: string;
+    accountHeading?: string;
+    accountNpub?: string;
+    accountLink?: string;
+    signOut?: string;
+}
+export interface SiteNavProps {
+    brand?: ReactNode;
+    items: readonly SiteNavItem[];
+    isActive?: (href: string, item: SiteNavItem) => boolean;
+    renderLink?: (props: SiteNavLinkProps) => ReactNode;
+    /** Drawn on the right, before the account menu: a balance chip, a Sign-in link. */
+    trailing?: ReactNode;
+    account?: SiteNavAccount;
+    /** When the pages fold into a menu; false never folds. Default "(max-width: 639px)". */
+    collapse?: string | false;
+    /** The `<nav>`'s accessible name. Default "Main". */
+    label?: string;
+    /** The menu button's accessible name. Default "Menu". */
+    menuLabel?: string;
+    menuIcon?: ReactNode;
+    closeIcon?: ReactNode;
+    classNames?: SiteNavClassNames;
+}
+export default function SiteNav({ brand, items, isActive, renderLink, trailing, account, collapse, label, menuLabel, menuIcon, closeIcon, classNames: c, }: SiteNavProps): import("react").JSX.Element;

package/dist/react/SiteNav.js

@@ -0,0 +1,80 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The top bar: the site's brand, its pages, and on the right whatever the site
+ * keeps there (a balance chip) and the account menu (avatar → identity, links,
+ * log out). On a phone the pages fold into a menu button.
+ *
+ * Mechanics only. The package owns which page is current, the phone fold, the
+ * two popovers (aria-expanded, focus into the menu and back to its button,
+ * Escape, a press outside, the arrow keys) and 40 px tap targets; every class
+ * is the site's, through `classNames` — with none it is plain markup.
+ *
+ * Router-agnostic: `isActive(href, item)` says which page is current and
+ * `renderLink` draws each link (a react-router `<Link to>`); by default the
+ * links are plain `<a href>` and the current page is read from
+ * `location.pathname`. `matchesPath` is the matching a site's `isActive`
+ * usually wants.
+ */
+import { useEffect, useId } from "react";
+import { Menu, X } from "lucide-react";
+import Avatar from "./Avatar.js";
+import { cx } from "./cx.js";
+import { matchesPath } from "./navState.js";
+import { useAvatar } from "./useAvatar.js";
+import { useDisclosure } from "./useDisclosure.js";
+import { useMediaQuery } from "./useMediaQuery.js";
+const TAP = { minWidth: 40, minHeight: 40 };
+const TAP_ROW = { display: "flex", alignItems: "center", minHeight: 40 };
+const plainLink = ({ children, ...p }) => _jsx("a", { ...p, children: children });
+const pathActive = (href, item) => typeof location !== "undefined" && matchesPath(location.pathname, href, item.end);
+export default function SiteNav({ brand, items, isActive = pathActive, renderLink = plainLink, trailing, account, collapse = "(max-width: 639px)", label = "Main", menuLabel = "Menu", menuIcon = _jsx(Menu, { "aria-hidden": true, size: 20 }), closeIcon = _jsx(X, { "aria-hidden": true, size: 20 }), classNames: c = {}, }) {
+    const folded = useMediaQuery(collapse);
+    const menu = useDisclosure();
+    const menuId = useId();
+    const { setOpen } = menu;
+    // Widened past the fold with the menu open: nothing to close later.
+    useEffect(() => {
+        if (!folded)
+            setOpen(false);
+    }, [folded, setOpen]);
+    const content = (item) => (_jsxs(_Fragment, { children: [item.icon && (_jsx("span", { "aria-hidden": true, className: c.icon, children: item.icon })), _jsx("span", { className: c.label, children: item.label }), item.badge != null && _jsx("span", { className: c.badge, children: item.badge })] }));
+    return (_jsxs("header", { className: c.root, children: [brand, _jsx("nav", { "aria-label": label, className: c.nav, ref: menu.rootRef, children: folded ? (_jsxs(_Fragment, { children: [_jsx("button", { ref: menu.buttonRef, type: "button", "aria-expanded": menu.open, "aria-controls": menuId, "aria-label": menuLabel, title: menuLabel, onClick: menu.toggle, className: c.toggle, style: TAP, children: menu.open ? closeIcon : menuIcon }), menu.open && (_jsx("ul", { id: menuId, ref: menu.panelRef, onKeyDown: menu.onPanelKeyDown, className: c.menu, children: items.map((item) => {
+                                const on = isActive(item.href, item);
+                                return (_jsx("li", { children: renderLink({
+                                        href: item.href,
+                                        title: item.title,
+                                        "aria-current": on ? "page" : undefined,
+                                        onClick: () => menu.close(),
+                                        className: cx(c.menuItem, on && (c.menuItemActive ?? c.active)),
+                                        style: TAP_ROW,
+                                        children: content(item),
+                                    }) }, item.href));
+                            }) }))] })) : (_jsx("ul", { className: c.list, children: items.map((item) => {
+                        const on = isActive(item.href, item);
+                        return (_jsx("li", { children: renderLink({
+                                href: item.href,
+                                title: item.title,
+                                "aria-current": on ? "page" : undefined,
+                                className: cx(c.item, on && c.active),
+                                children: content(item),
+                            }) }, item.href));
+                    }) })) }), (trailing != null || account) && (_jsxs("div", { className: c.end, children: [trailing, account && _jsx(AccountMenu, { account: account, isActive: isActive, renderLink: renderLink, c: c })] }))] }));
+}
+function AccountMenu({ account, isActive, renderLink, c, }) {
+    const { npub, heading = "Nostr identity", links = [], onSignOut, signOutLabel = "Log out", avatarSize = 32, label = "Account", } = account;
+    const avatar = useAvatar(npub);
+    const menu = useDisclosure();
+    const menuId = useId();
+    return (_jsxs("div", { ref: menu.rootRef, className: c.account, children: [_jsx("button", { ref: menu.buttonRef, type: "button", "aria-expanded": menu.open, "aria-controls": menuId, "aria-label": label, title: npub, onClick: menu.toggle, className: c.accountButton, style: TAP, children: _jsx(Avatar, { value: avatar, size: avatarSize }) }), menu.open && (_jsxs("div", { id: menuId, ref: menu.panelRef, onKeyDown: menu.onPanelKeyDown, className: c.accountMenu, children: [_jsxs("div", { className: c.accountHeader, children: [_jsx("div", { className: c.accountHeading, children: heading }), _jsx("div", { className: c.accountNpub, title: npub, children: npub })] }), links.map((item) => (_jsx("div", { children: renderLink({
+                            href: item.href,
+                            title: item.title,
+                            "aria-current": isActive(item.href, item) ? "page" : undefined,
+                            onClick: () => menu.close(),
+                            className: c.accountLink,
+                            style: TAP_ROW,
+                            children: item.label,
+                        }) }, item.href))), onSignOut && (_jsx("button", { type: "button", onClick: () => {
+                            menu.close();
+                            onSignOut();
+                        }, className: c.signOut, style: TAP_ROW, children: signOutLabel }))] }))] }));
+}

package/dist/react/accountSections.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The order `AccountPage` draws its sections in, one order for every site, and
+ * where a site's own panels go between them.
+ */
+export type AccountSection = "profile" | "sessionKey" | "usage" | "timezone" | "theme" | "coupons" | "build";
+export declare const ACCOUNT_SECTIONS: readonly AccountSection[];
+export type AccountStep = {
+    kind: "section";
+    section: AccountSection;
+} | {
+    kind: "between";
+    section: AccountSection;
+};
+/**
+ * Each shown section in order, each followed by the site's panel placed after
+ * it. A site panel keeps its place when the section before it is hidden — a
+ * site that brings its own coupons turns the package's off and puts its own
+ * `between.theme`, and it lands where the coupons would have been.
+ */
+export declare function accountSteps(shown: Partial<Record<AccountSection, boolean>>, between: Partial<Record<AccountSection, unknown>>): AccountStep[];

package/dist/react/accountSections.js

@@ -0,0 +1,29 @@
+/**
+ * The order `AccountPage` draws its sections in, one order for every site, and
+ * where a site's own panels go between them.
+ */
+export const ACCOUNT_SECTIONS = [
+    "profile",
+    "sessionKey",
+    "usage",
+    "timezone",
+    "theme",
+    "coupons",
+    "build",
+];
+/**
+ * Each shown section in order, each followed by the site's panel placed after
+ * it. A site panel keeps its place when the section before it is hidden — a
+ * site that brings its own coupons turns the package's off and puts its own
+ * `between.theme`, and it lands where the coupons would have been.
+ */
+export function accountSteps(shown, between) {
+    const steps = [];
+    for (const section of ACCOUNT_SECTIONS) {
+        if (shown[section] !== false)
+            steps.push({ kind: "section", section });
+        if (between[section] != null && between[section] !== false)
+            steps.push({ kind: "between", section });
+    }
+    return steps;
+}

package/dist/react/index.d.ts

@@ -1,3 +1,7 @@
+export { default as AccountPage, type AccountPageClassNames, type AccountPageProps, type AccountSectionText, type AccountThemeProps, type AccountTimezoneProps, } from "./AccountPage.tsx";
+export { ACCOUNT_SECTIONS, type AccountSection } from "./accountSections.ts";
+export { default as AppShell, useAppShell, type AppShellClassNames, type AppShellContext, type AppShellProps, } from "./AppShell.tsx";
+export type { ShellFit } from "./shellLayout.ts";
 export { default as Avatar } from "./Avatar.tsx";
 export { default as AvatarPicker } from "./AvatarPicker.tsx";
 export { default as BuildInfoPanel, type BuildInfoFrontend, type BuildInfoLicence, type BuildInfoPanelClassNames, type BuildInfoPanelProps, } from "./BuildInfoPanel.tsx";
@@ -8,8 +12,11 @@ export { OperatorFundingStatus, PatronFundingStatus, type FundingStatusClassName
 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 RefreshButton, type RefreshButtonClassNames, type RefreshButtonProps, } from "./RefreshButton.tsx";
 export { default as QuoteScroller, type QuoteScrollerProps, type QuoteScrollerClassNames } from "./QuoteScroller.tsx";
-export { default as SessionKeyClaim } from "./SessionKeyClaim.tsx";
+export { default as SessionKeyClaim, type SessionKeyClaimProps, type SessionKeyClaimClassNames, } from "./SessionKeyClaim.tsx";
+export { default as SiteNav, type SiteNavAccount, type SiteNavClassNames, type SiteNavItem, type SiteNavLinkProps, type SiteNavProps, } from "./SiteNav.tsx";
+export { matchesPath } from "./navState.ts";
 export { default as TableFilter, type DateFieldOption, type FilterQuestion, type TableFilterProps, type TableFilterClassNames, type TableFilterDates, type TableFilterQuestions, type TableFilterSearch, } from "./TableFilter.tsx";
 export { default as ThemeToggle, type ThemeToggleProps, type ThemeToggleClassNames } from "./ThemeToggle.tsx";
 export { default as TimezonePicker, type TimezoneOption, type TimezonePickerClassNames, type TimezonePickerProps, } from "./TimezonePicker.tsx";

package/dist/react/index.js

@@ -1,3 +1,6 @@
+export { default as AccountPage, } from "./AccountPage.js";
+export { ACCOUNT_SECTIONS } from "./accountSections.js";
+export { default as AppShell, useAppShell, } from "./AppShell.js";
 export { default as Avatar } from "./Avatar.js";
 export { default as AvatarPicker } from "./AvatarPicker.js";
 export { default as BuildInfoPanel, } from "./BuildInfoPanel.js";
@@ -8,8 +11,11 @@ export { OperatorFundingStatus, PatronFundingStatus, } from "./FundingStatus.js"
 export { default as NpubGate } from "./NpubGate.js";
 export { default as NostrProfilePanel } from "./NostrProfilePanel.js";
 export { PageControls, SortHeader, TableShell, } from "./PagedTable.js";
+export { default as RefreshButton, } from "./RefreshButton.js";
 export { default as QuoteScroller } from "./QuoteScroller.js";
-export { default as SessionKeyClaim } from "./SessionKeyClaim.js";
+export { default as SessionKeyClaim, } from "./SessionKeyClaim.js";
+export { default as SiteNav, } from "./SiteNav.js";
+export { matchesPath } from "./navState.js";
 export { default as TableFilter, } from "./TableFilter.js";
 export { default as ThemeToggle } from "./ThemeToggle.js";
 export { default as TimezonePicker, } from "./TimezonePicker.js";

package/dist/react/navState.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The pure half of `SiteNav`: which item is the current page, and where focus
+ * goes when a key is pressed inside an open menu. No DOM, no router.
+ */
+/** The path part of an href: no query, no hash, no trailing slash (but "/" stays "/"). */
+export declare function pathOf(href: string): string;
+/**
+ * True when `href` is the page at `pathname`.
+ *
+ * `end` asks for the exact path; without it an href also owns everything
+ * beneath it, on a segment boundary — "/posts" is active on "/posts/42" but
+ * never on "/postscript". "/" without `end` is active everywhere, as a
+ * router's NavLink is; give the home item `end`.
+ */
+export declare function matchesPath(pathname: string, href: string, end?: boolean): boolean;
+/**
+ * The index to focus after `key` in an open menu of `count` items, with focus
+ * now on `current` (-1 when it is on none of them). `null` when the key is not
+ * one the menu moves on. Arrows wrap; Home and End go to the ends.
+ */
+export declare function menuFocusIndex(key: string, current: number, count: number): number | null;

package/dist/react/navState.js

@@ -0,0 +1,49 @@
+/**
+ * The pure half of `SiteNav`: which item is the current page, and where focus
+ * goes when a key is pressed inside an open menu. No DOM, no router.
+ */
+/** The path part of an href: no query, no hash, no trailing slash (but "/" stays "/"). */
+export function pathOf(href) {
+    const cut = href.split(/[?#]/, 1)[0] || "/";
+    return cut.length > 1 ? cut.replace(/\/+$/, "") || "/" : cut;
+}
+/**
+ * True when `href` is the page at `pathname`.
+ *
+ * `end` asks for the exact path; without it an href also owns everything
+ * beneath it, on a segment boundary — "/posts" is active on "/posts/42" but
+ * never on "/postscript". "/" without `end` is active everywhere, as a
+ * router's NavLink is; give the home item `end`.
+ */
+export function matchesPath(pathname, href, end = false) {
+    const here = pathOf(pathname);
+    const target = pathOf(href);
+    if (here === target)
+        return true;
+    if (end)
+        return false;
+    if (target === "/")
+        return true;
+    return here.startsWith(`${target}/`);
+}
+/**
+ * The index to focus after `key` in an open menu of `count` items, with focus
+ * now on `current` (-1 when it is on none of them). `null` when the key is not
+ * one the menu moves on. Arrows wrap; Home and End go to the ends.
+ */
+export function menuFocusIndex(key, current, count) {
+    if (count <= 0)
+        return null;
+    switch (key) {
+        case "ArrowDown":
+            return current < 0 ? 0 : (current + 1) % count;
+        case "ArrowUp":
+            return current < 0 ? count - 1 : (current - 1 + count) % count;
+        case "Home":
+            return 0;
+        case "End":
+            return count - 1;
+        default:
+            return null;
+    }
+}

package/dist/react/shellLayout.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The frame `AppShell` lays out: a column as tall as the viewport, the site's
+ * content growing to fill it, then the footer, then the debug log's spacer.
+ *
+ * "page" (the default) lets a long page grow past the viewport and scroll the
+ * window. "viewport" pins the frame to the viewport's height, for a site with
+ * a bottom rail that must stay on screen: the content region may shrink
+ * (min-height 0) and scrolls inside, so the debug log's spacer takes its room
+ * out of the content rather than pushing the rail off the bottom.
+ */
+import type { CSSProperties } from "react";
+export type ShellFit = "page" | "viewport";
+export interface ShellLayout {
+    root: CSSProperties;
+    body: CSSProperties;
+}
+export declare function shellLayout(fit?: ShellFit): ShellLayout;

package/dist/react/shellLayout.js

@@ -0,0 +1,23 @@
+/**
+ * The frame `AppShell` lays out: a column as tall as the viewport, the site's
+ * content growing to fill it, then the footer, then the debug log's spacer.
+ *
+ * "page" (the default) lets a long page grow past the viewport and scroll the
+ * window. "viewport" pins the frame to the viewport's height, for a site with
+ * a bottom rail that must stay on screen: the content region may shrink
+ * (min-height 0) and scrolls inside, so the debug log's spacer takes its room
+ * out of the content rather than pushing the rail off the bottom.
+ */
+export function shellLayout(fit = "page") {
+    const column = { display: "flex", flexDirection: "column" };
+    if (fit === "viewport") {
+        return {
+            root: { ...column, height: "100dvh", overflow: "hidden" },
+            body: { ...column, flex: "1 1 0%", minHeight: 0, overflow: "auto" },
+        };
+    }
+    return {
+        root: { ...column, minHeight: "100dvh" },
+        body: { ...column, flex: "1 0 auto" },
+    };
+}

package/dist/react/useAvatar.d.ts

@@ -0,0 +1,2 @@
+/** The npub's avatar, following the picker (same-tab event) and the npub. */
+export declare function useAvatar(npub: string): string;

package/dist/react/useAvatar.js

@@ -0,0 +1,13 @@
+/** The npub's avatar, following the picker (same-tab event) and the npub. */
+import { useEffect, useState } from "react";
+import { AVATAR_EVENT, avatarFor } from "../avatar.js";
+export function useAvatar(npub) {
+    const [avatar, setAvatar] = useState(() => avatarFor(npub));
+    useEffect(() => {
+        setAvatar(avatarFor(npub));
+        const changed = () => setAvatar(avatarFor(npub));
+        window.addEventListener(AVATAR_EVENT, changed);
+        return () => window.removeEventListener(AVATAR_EVENT, changed);
+    }, [npub]);
+    return avatar;
+}

package/dist/react/useDisclosure.d.ts

@@ -0,0 +1,17 @@
+/**
+ * An open/closed popover done once: the site nav's phone menu and its account
+ * menu. The button carries `aria-expanded`; opening focuses the first item;
+ * Escape closes and hands focus back to the button; a press or focus outside
+ * closes; the arrows, Home and End move between the items.
+ */
+import { type KeyboardEvent } from "react";
+export declare function useDisclosure<Root extends HTMLElement, Panel extends HTMLElement>(): {
+    open: boolean;
+    setOpen: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    toggle: () => void;
+    close: (returnFocus?: boolean) => void;
+    rootRef: import("react").RefObject<Root | null>;
+    buttonRef: import("react").RefObject<HTMLButtonElement | null>;
+    panelRef: import("react").RefObject<Panel | null>;
+    onPanelKeyDown: (e: KeyboardEvent) => void;
+};

package/dist/react/useDisclosure.js

@@ -0,0 +1,58 @@
+/**
+ * An open/closed popover done once: the site nav's phone menu and its account
+ * menu. The button carries `aria-expanded`; opening focuses the first item;
+ * Escape closes and hands focus back to the button; a press or focus outside
+ * closes; the arrows, Home and End move between the items.
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+import { menuFocusIndex } from "./navState.js";
+const FOCUSABLE = "a[href], button:not([disabled]), [tabindex]:not([tabindex='-1'])";
+function items(panel) {
+    return panel ? Array.from(panel.querySelectorAll(FOCUSABLE)) : [];
+}
+export function useDisclosure() {
+    const [open, setOpen] = useState(false);
+    const rootRef = useRef(null);
+    const buttonRef = useRef(null);
+    const panelRef = useRef(null);
+    const close = useCallback((returnFocus = false) => {
+        setOpen(false);
+        if (returnFocus)
+            buttonRef.current?.focus();
+    }, []);
+    const toggle = useCallback(() => setOpen((o) => !o), []);
+    useEffect(() => {
+        if (!open)
+            return;
+        items(panelRef.current)[0]?.focus();
+        const outside = (e) => {
+            const root = rootRef.current;
+            if (root && e.target instanceof Node && !root.contains(e.target))
+                setOpen(false);
+        };
+        const onKey = (e) => {
+            if (e.key !== "Escape")
+                return;
+            e.preventDefault();
+            setOpen(false);
+            buttonRef.current?.focus();
+        };
+        document.addEventListener("pointerdown", outside);
+        document.addEventListener("focusin", outside);
+        document.addEventListener("keydown", onKey);
+        return () => {
+            document.removeEventListener("pointerdown", outside);
+            document.removeEventListener("focusin", outside);
+            document.removeEventListener("keydown", onKey);
+        };
+    }, [open]);
+    const onPanelKeyDown = useCallback((e) => {
+        const list = items(panelRef.current);
+        const next = menuFocusIndex(e.key, list.indexOf(document.activeElement), list.length);
+        if (next === null)
+            return;
+        e.preventDefault();
+        list[next]?.focus();
+    }, []);
+    return { open, setOpen, toggle, close, rootRef, buttonRef, panelRef, onPanelKeyDown };
+}

package/dist/react/useMediaQuery.d.ts

@@ -0,0 +1,2 @@
+/** True while `query` matches; false on the server, and when `query` is false. */
+export declare function useMediaQuery(query: string | false): boolean;

package/dist/react/useMediaQuery.js

@@ -0,0 +1,13 @@
+/** True while `query` matches; false on the server, and when `query` is false. */
+import { useCallback, useSyncExternalStore } from "react";
+export function useMediaQuery(query) {
+    const subscribe = useCallback((changed) => {
+        if (!query || typeof globalThis.matchMedia !== "function")
+            return () => { };
+        const mq = globalThis.matchMedia(query);
+        mq.addEventListener("change", changed);
+        return () => mq.removeEventListener("change", changed);
+    }, [query]);
+    const read = useCallback(() => Boolean(query) && typeof globalThis.matchMedia === "function" && globalThis.matchMedia(query).matches, [query]);
+    return useSyncExternalStore(subscribe, read, () => false);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tollbooth-dpyc/web",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "Shared browser SDK for Tollbooth DPYC operator front ends: npub sign-in, proofs, MCP client, profile and wallet",
   "license": "Apache-2.0",
   "author": "Lonnie VanZandt",