@tollbooth-dpyc/web 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,69 @@
+# @tollbooth-dpyc/web
+
+The browser half of [Tollbooth DPYC](https://github.com/lonniev/tollbooth-dpyc):
+the shared code every operator front end needs, so a site holds only its own
+features. It is the peer of the `tollbooth-dpyc` Python wheel.
+
+- **npub sign-in** — a Nostr DM challenge, or an in-browser session key
+- **proofs** — the npub/`dpop_token` envelope on every paid call, a fresh
+  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`, `WalletCard`,
+  `AvatarPicker`, `useSession`
+- **Pages proxy** — the `/mcp` Cloudflare Pages Function
+
+## Use
+
+```ts
+// main.tsx — once, before rendering
+import { configureTollbooth } from "@tollbooth-dpyc/web";
+
+configureTollbooth({ slug: "chart", appName: "ChartRemotely", mcpUrl: "/mcp" });
+```
+
+```tsx
+import { callTool, callToolWithContent } from "@tollbooth-dpyc/web";
+import { NpubGate, WalletCard, useSession } from "@tollbooth-dpyc/web/react";
+
+const displays = await callTool("agent_status");               // chart_agent_status
+const { data, images } = await callToolWithContent("snapshot_display", { display: "Desk" });
+```
+
+Short tool names are used throughout; the slug is added for you, and the proof
+is bound to the full runtime name.
+
+```js
+// functions/mcp.js
+import { makeMcpProxy } from "@tollbooth-dpyc/web/pages-proxy";
+export const onRequest = makeMcpProxy("https://chartremotely-mcp.fastmcp.app/mcp");
+```
+
+### Styling
+
+Components use Tailwind classes coloured only through CSS variables. Tell
+Tailwind to scan the package, import the default tokens, and override any of
+them after:
+
+```css
+@import "tailwindcss";
+@import "@tollbooth-dpyc/web/theme.css";
+@source "../node_modules/@tollbooth-dpyc/web/dist";
+
+:root { --tb-accent: #4cc38a; }
+```
+
+## Develop
+
+```sh
+npm install
+npm test       # node --test, no browser needed
+npm run build  # tsc → dist/
+```
+
+Releases publish from a `v*` tag through npm trusted publishing; see
+`.github/workflows/release.yml`.
+
+## Licence
+
+Apache-2.0

package/dist/avatar.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The patron's avatar, cached per npub.
+ *
+ * kind-0 `picture` is the source of truth, but it is a URL and an emoji glyph
+ * is not, so a glyph pick stays local. A change dispatches a window event so
+ * every avatar on the page updates without a reload.
+ */
+export declare const AVATAR_CHOICES: string[];
+export declare const AVATAR_EVENT = "tollbooth:avatar-changed";
+/** http(s) or data:image renders as an image; anything else as a glyph. */
+export declare function isAvatarUrl(value: string): boolean;
+/** First 8 and last 4 characters. */
+export declare function shortNpub(npub?: string | null): string;
+export declare function getStoredAvatar(npub: string): string;
+export declare function setStoredAvatar(npub: string, value: string): void;
+/** A stable glyph from the npub, so a new patron still has a distinct avatar. */
+export declare function defaultAvatar(npub: string): string;
+export declare function avatarFor(npub: string): string;
+/** Seed the cache from kind-0, unless the patron already picked one here. */
+export declare function hydrateAvatarFromNostr(npub: string): Promise<void>;

package/dist/avatar.js

@@ -0,0 +1,54 @@
+/**
+ * The patron's avatar, cached per npub.
+ *
+ * kind-0 `picture` is the source of truth, but it is a URL and an emoji glyph
+ * is not, so a glyph pick stays local. A change dispatches a window event so
+ * every avatar on the page updates without a reload.
+ */
+import { fetchProfile } from "./nostrProfile.js";
+import { readStored, writeStored } from "./storage.js";
+export const AVATAR_CHOICES = [
+    "🐂", "🐻", "🦂", "🦅", "🐺", "🦉",
+    "🦊", "🐉", "🦄", "🐢", "🦈", "🦀",
+    "🎩", "🎭", "🃏", "🎯", "🪙", "💎",
+    "⚡", "🔥", "🌪️", "🌊", "🏔️", "🌋",
+    "♟️", "♛", "🛡️", "⚔️", "🗝️", "📜",
+];
+export const AVATAR_EVENT = "tollbooth:avatar-changed";
+/** http(s) or data:image renders as an image; anything else as a glyph. */
+export function isAvatarUrl(value) {
+    return /^(https?:\/\/|data:image\/)/i.test(value);
+}
+/** First 8 and last 4 characters. */
+export function shortNpub(npub) {
+    if (!npub)
+        return "";
+    return npub.length <= 16 ? npub : `${npub.slice(0, 8)}…${npub.slice(-4)}`;
+}
+export function getStoredAvatar(npub) {
+    return npub ? readStored(`avatar:${npub}`) : "";
+}
+export function setStoredAvatar(npub, value) {
+    if (!npub)
+        return;
+    writeStored(`avatar:${npub}`, value);
+    globalThis.dispatchEvent?.(new CustomEvent(AVATAR_EVENT, { detail: { npub, value } }));
+}
+/** A stable glyph from the npub, so a new patron still has a distinct avatar. */
+export function defaultAvatar(npub) {
+    let h = 0;
+    for (const c of npub)
+        h = (h * 31 + c.charCodeAt(0)) >>> 0;
+    return AVATAR_CHOICES[h % AVATAR_CHOICES.length];
+}
+export function avatarFor(npub) {
+    return getStoredAvatar(npub) || defaultAvatar(npub);
+}
+/** Seed the cache from kind-0, unless the patron already picked one here. */
+export async function hydrateAvatarFromNostr(npub) {
+    if (!npub || getStoredAvatar(npub))
+        return;
+    const p = await fetchProfile(npub);
+    if (p?.picture)
+        setStoredAvatar(npub, p.picture);
+}

package/dist/client.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The operator MCP, as a page calls it.
+ *
+ * 1. One @modelcontextprotocol/sdk Client over StreamableHTTP, shared by the
+ *    whole page. The SDK handles the initialize handshake and the session.
+ * 2. Auth is the uniform npub proof, by one of two tactics, invisible to
+ *    callers: a session nsec signs a fresh kind-27235 proof per call, bound to
+ *    the runtime tool name; otherwise the DM proof token cached at
+ *    `receive_npub_proof` is sent as is.
+ * 3. Bootstrap tools take no envelope and are safe before sign-in.
+ */
+import { type ImageBlock } from "./toolResult.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);
+}
+type ProofExpiredListener = (message: string) => void;
+/**
+ * Subscribe to proof bounces from anywhere in the app. Without this the tree
+ * never learns the token was cleared, and the patron is stranded on a page
+ * whose data will not load. Returns an unsubscribe function.
+ */
+export declare function onProofExpired(cb: ProofExpiredListener): () => void;
+export interface CallOptions {
+    /**
+     * A non-essential call — diagnostics, personalization. It never logs the
+     * patron out, whatever it gets back.
+     */
+    bestEffort?: boolean;
+    timeoutMs?: number;
+}
+export interface ToolAnswer<T> {
+    data: T;
+    images: ImageBlock[];
+}
+/**
+ * Call a tool by its short name ("snapshot_display", not
+ * "chart_snapshot_display") and get both its answer and any images it sent.
+ */
+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

@@ -0,0 +1,169 @@
+/**
+ * The operator MCP, as a page calls it.
+ *
+ * 1. One @modelcontextprotocol/sdk Client over StreamableHTTP, shared by the
+ *    whole page. The SDK handles the initialize handshake and the session.
+ * 2. Auth is the uniform npub proof, by one of two tactics, invisible to
+ *    callers: a session nsec signs a fresh kind-27235 proof per call, bound to
+ *    the runtime tool name; otherwise the DM proof token cached at
+ *    `receive_npub_proof` is sent as is.
+ * 3. Bootstrap tools take no envelope and are safe before sign-in.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+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 { clearSessionNsec, hasSessionNsec, sessionNsecNpub } from "./sessionNsec.js";
+import { errorText, looksFailed, proofBounceMessage, readToolResult, } from "./toolResult.js";
+/**
+ * Standard tools whose wheel signature takes no npub/proof envelope. Pydantic
+ * strict mode rejects unexpected kwargs, so they must not get one.
+ */
+const STANDARD_BOOTSTRAP = [
+    "request_npub_proof",
+    "receive_npub_proof",
+    "service_status",
+    "session_status",
+    "get_nostr_profile",
+    "publish_nostr_profile",
+    "get_operator_onboarding_status",
+    "check_authority_balance",
+    "list_canonical_identities",
+    "check_proof_status",
+    "get_patron_onboarding_status",
+    "request_patron_credentials",
+    "receive_patron_credentials",
+];
+const STANDARD_QUIET = ["service_status", "get_nostr_profile"];
+let client = null;
+let connecting = null;
+function mcpUrl() {
+    const url = tollboothConfig().mcpUrl;
+    if (!url)
+        throw new Error("mcpUrl is not configured (e.g. \"/mcp\").");
+    return url.startsWith("/") ? `${globalThis.location.origin}${url}` : url;
+}
+async function getClient() {
+    if (client)
+        return client;
+    if (!connecting) {
+        // Cleared whether it worked or not. Cleared only on success, one failed
+        // connect — no signal, a cold server — was awaited again by every later
+        // call, and nothing reached the server until the page was reloaded.
+        connecting = (async () => {
+            const c = new Client({ name: `${tollboothConfig().slug}-frontend`, version: "1" });
+            await c.connect(new StreamableHTTPClientTransport(new URL(mcpUrl())));
+            client = c;
+        })().finally(() => {
+            connecting = null;
+        });
+    }
+    await connecting;
+    if (!client)
+        throw new Error("Could not connect to the service.");
+    return client;
+}
+/**
+ * The proof for one call: a fresh inline proof when this tab's session key
+ * derives to the signed-in npub, else the cached DM token. A session key left
+ * from a previous identity is evicted rather than allowed to sign.
+ */
+function proofFor(tool) {
+    try {
+        const npub = getStoredNpub();
+        const sessionNpub = hasSessionNsec() ? sessionNsecNpub() : null;
+        if (sessionNpub && sessionNpub === npub)
+            return signInlineProof(toolName(tool));
+        if (sessionNpub)
+            clearSessionNsec();
+    }
+    catch {
+        /* fall through to the cached token */
+    }
+    return getStoredProof();
+}
+/** A paid call bounced for a lapsed or missing proof. The gate re-arms sign-in. */
+export class ProofRequiredError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ProofRequiredError";
+    }
+}
+const proofExpiredListeners = new Set();
+/**
+ * Subscribe to proof bounces from anywhere in the app. Without this the tree
+ * never learns the token was cleared, and the patron is stranded on a page
+ * whose data will not load. Returns an unsubscribe function.
+ */
+export function onProofExpired(cb) {
+    proofExpiredListeners.add(cb);
+    return () => proofExpiredListeners.delete(cb);
+}
+function emitProofExpired(message) {
+    for (const cb of proofExpiredListeners) {
+        try {
+            cb(message);
+        }
+        catch {
+            /* a listener error must not swallow the throw that follows */
+        }
+    }
+}
+/**
+ * Call a tool by its short name ("snapshot_display", not
+ * "chart_snapshot_display") and get both its answer and any images it sent.
+ */
+export async function callToolWithContent(tool, args = {}, opts = {}) {
+    const cfg = tollboothConfig();
+    const name = toolName(tool);
+    const quiet = STANDARD_QUIET.includes(tool) || cfg.quietTools.includes(tool);
+    // `args` holds only the caller's own parameters — the envelope is added
+    // below — so it is safe to log.
+    if (!quiet)
+        debugPush("call", `${name}(${JSON.stringify(args).slice(0, 140)})`);
+    const bootstrap = STANDARD_BOOTSTRAP.includes(tool) || cfg.extraBootstrapTools.includes(tool);
+    const merged = bootstrap
+        ? { ...args }
+        : { npub: getStoredNpub(), dpop_token: proofFor(tool), ...args };
+    let result;
+    try {
+        const c = await getClient();
+        result = (await c.callTool({ name, arguments: merged }, undefined, { timeout: opts.timeoutMs ?? 120_000 }));
+    }
+    catch (e) {
+        if (!quiet)
+            debugPush("error", `${name}: ${e.message}`);
+        throw new Error(`${name}: ${e.message}`);
+    }
+    if (result.isError) {
+        const text = errorText(result);
+        if (!quiet)
+            debugPush("error", `${name}: ${text.slice(0, 200)}`);
+        throw new Error(text);
+    }
+    const { payload, images } = readToolResult(result);
+    if (!quiet) {
+        const preview = typeof payload === "string" ? payload : JSON.stringify(payload);
+        const tail = images.length ? ` +${images.length} image` : "";
+        debugPush(looksFailed(payload) ? "error" : "result", `${name} → ${String(preview).slice(0, 220)}${tail}`);
+    }
+    if (!opts.bestEffort) {
+        const bounced = proofBounceMessage(payload);
+        if (bounced !== null) {
+            // The token just refused is the same one the recent-login shortcut
+            // would replay, so it goes too, or a returning patron re-bounces.
+            const npub = getStoredNpub();
+            clearStoredProof();
+            if (npub)
+                forgetRecentLogin(npub);
+            emitProofExpired(bounced);
+            throw new ProofRequiredError(bounced);
+        }
+    }
+    return { data: payload, images };
+}
+export async function callTool(tool, args = {}, opts = {}) {
+    return (await callToolWithContent(tool, args, opts)).data;
+}

package/dist/config.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The one thing that differs between operator front ends.
+ *
+ * Every copy of this code in the fleet differed from its siblings in the same
+ * few places: the tool-name slug, the brand in a sign-in DM and a heading, and
+ * the prefix on its localStorage keys. Those are configuration, so they live
+ * here and nowhere else. A site calls `configureTollbooth` once, before it
+ * renders, and everything in the package reads from it.
+ */
+export interface TollboothConfig {
+    /** Tool-name prefix the operator registers under, e.g. "chart" or "goodearth". */
+    slug: string;
+    /** The name a patron knows the service by, e.g. "ChartRemotely". */
+    appName: string;
+    /** Prefix for localStorage keys. Defaults to the slug. */
+    storagePrefix?: string;
+    /**
+     * Where the MCP endpoint is. A path ("/mcp") is resolved against the page's
+     * origin, which is how every site reaches its Pages proxy.
+     */
+    mcpUrl: string;
+    /**
+     * Free tools this operator adds that take no npub/proof envelope, on top of
+     * the standard ones. Pydantic rejects unexpected kwargs, so a tool listed
+     * here must truly not accept `npub`.
+     */
+    extraBootstrapTools?: string[];
+    /** Tools too routine to log in the debug panel. */
+    quietTools?: string[];
+}
+interface Resolved extends Required<Omit<TollboothConfig, "extraBootstrapTools" | "quietTools">> {
+    extraBootstrapTools: string[];
+    quietTools: string[];
+}
+export declare function configureTollbooth(config: TollboothConfig): void;
+export declare function tollboothConfig(): Resolved;
+/** The runtime tool name a proof must be bound to, e.g. "chart_snapshot_display". */
+export declare function toolName(tool: string): string;
+export {};

package/dist/config.js

@@ -0,0 +1,33 @@
+/**
+ * The one thing that differs between operator front ends.
+ *
+ * Every copy of this code in the fleet differed from its siblings in the same
+ * few places: the tool-name slug, the brand in a sign-in DM and a heading, and
+ * the prefix on its localStorage keys. Those are configuration, so they live
+ * here and nowhere else. A site calls `configureTollbooth` once, before it
+ * renders, and everything in the package reads from it.
+ */
+let current = null;
+export function configureTollbooth(config) {
+    if (!/^[a-z][a-z0-9_]*$/.test(config.slug)) {
+        throw new Error(`slug must be lowercase letters, digits or underscores: ${config.slug}`);
+    }
+    current = {
+        slug: config.slug,
+        appName: config.appName,
+        storagePrefix: config.storagePrefix ?? config.slug,
+        mcpUrl: config.mcpUrl,
+        extraBootstrapTools: config.extraBootstrapTools ?? [],
+        quietTools: config.quietTools ?? [],
+    };
+}
+export function tollboothConfig() {
+    if (!current) {
+        throw new Error("configureTollbooth() must be called before the app renders.");
+    }
+    return current;
+}
+/** The runtime tool name a proof must be bound to, e.g. "chart_snapshot_display". */
+export function toolName(tool) {
+    return `${tollboothConfig().slug}_${tool}`;
+}

package/dist/debugLog.d.ts

@@ -0,0 +1,18 @@
+/**
+ * An in-memory activity log of MCP calls, for a site's debug panel.
+ *
+ * A ring buffer with subscribers, so the one `callTool` can push and any panel
+ * can listen. It survives route changes and is gone on reload. Arguments are
+ * logged only as the wrapper's own parameters — the npub/proof envelope is
+ * added after logging, so no proof ever lands here.
+ */
+export interface DebugEntry {
+    ts: string;
+    type: "info" | "call" | "result" | "error";
+    message: string;
+}
+export declare function debugPush(type: DebugEntry["type"], message: string): void;
+export declare function clearDebug(): void;
+export declare function debugEntries(): readonly DebugEntry[];
+/** Subscribe to changes. Returns an unsubscribe function. */
+export declare function onDebug(fn: () => void): () => void;