@gatedpath/frontend-kit 0.1.0

package/dist/dev/DevStatePanel.js

@@ -0,0 +1,123 @@
+'use client';
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useChainId, useClient, useConnect, useConnection, useDisconnect } from 'wagmi';
+import { encodeFunctionData } from 'viem';
+import { readContract, waitForTransactionReceipt } from 'viem/actions';
+import { receptorMockStatusAbi } from '../abi.js';
+import { notifyEligibilityChanged } from '../events.js';
+import { anvilAccountConnector } from './anvilConnector.js';
+import { ELIGIBILITY_STATES, LOCAL_CHAIN_ID } from './localDeployment.js';
+const STATE_HINT = {
+    NeverIssued: 'no credential',
+    Valid: 'passes the gate',
+    Expired: 'credential past its window',
+    Revoked: 'issuer revoked it',
+    WrongJurisdiction: 'credential does not satisfy the query',
+};
+function short(address) {
+    return `${address.slice(0, 6)}…${address.slice(-4)}`;
+}
+/** Sends one JSON-RPC request through wagmi's client for the local chain, methods Anvil adds included. */
+function rpc(client, method, params = []) {
+    return client.request({ method, params });
+}
+/**
+ * The dev-only state switcher (PLAN.md 18.1). Lists the five wallets `npm run dev` seeded, marks
+ * the connected one, and flips the connected wallet through the five credential states by calling
+ * `setStatus` on the `ReceptorMock` as the deployer, through Anvil's impersonation RPC. Every
+ * mounted `useEligibility` for that wallet refetches on the resulting signal, so the page moves
+ * into the new state without a reload.
+ *
+ * It renders only when the wallet (or, unconnected, the app) is on chain 31337 and the deployment
+ * it was given says 31337 too. On 151 or 153 it renders nothing, whatever it was given. In a
+ * scaffold it is imported only by the dev server and is absent from production bundles; the
+ * scaffolder's test asserts both.
+ */
+export function DevStatePanel({ deployment, className }) {
+    const configChainId = useChainId();
+    const connection = useConnection();
+    const chainId = connection.chainId ?? configChainId;
+    const onLocal = chainId === LOCAL_CHAIN_ID && deployment.chainId === LOCAL_CHAIN_ID;
+    const client = useClient({ chainId: LOCAL_CHAIN_ID });
+    const connect = useConnect();
+    const disconnect = useDisconnect();
+    const [states, setStates] = useState(() => Object.fromEntries(deployment.wallets.map((w) => [w.address.toLowerCase(), w.state])));
+    const [busy, setBusy] = useState(null);
+    const [message, setMessage] = useState(null);
+    const requestId = BigInt(deployment.requestId);
+    const connected = connection.address?.toLowerCase();
+    const readStates = useCallback(async () => {
+        if (!client || !onLocal)
+            return;
+        const next = {};
+        const targets = [...deployment.wallets.map((w) => w.address), ...(connection.address ? [connection.address] : [])];
+        for (const address of targets) {
+            const status = await readContract(client, {
+                address: deployment.verifier,
+                abi: receptorMockStatusAbi,
+                functionName: 'eligibilityStatus',
+                args: [address, requestId],
+            });
+            next[address.toLowerCase()] = ELIGIBILITY_STATES[Number(status)] ?? 'NeverIssued';
+        }
+        setStates((prev) => ({ ...prev, ...next }));
+    }, [client, onLocal, deployment.wallets, deployment.verifier, requestId, connection.address]);
+    useEffect(() => {
+        void readStates().catch((e) => setMessage(e instanceof Error ? e.message : String(e)));
+    }, [readStates]);
+    const setState = useCallback(async (state) => {
+        if (!client || !connection.address)
+            return;
+        const wallet = connection.address;
+        const deployer = deployment.deployer.address;
+        setBusy(state);
+        setMessage(null);
+        try {
+            // The mock has no owner: any sender may call setStatus. The deployer is used because it is the
+            // account npm run dev funded and deployed from, and impersonation keeps that true whatever
+            // wallet is connected. Nothing here signs; Anvil does.
+            await rpc(client, 'anvil_impersonateAccount', [deployer]);
+            let hash;
+            try {
+                const data = encodeFunctionData({
+                    abi: receptorMockStatusAbi,
+                    functionName: 'setStatus',
+                    args: [wallet, requestId, ELIGIBILITY_STATES.indexOf(state)],
+                });
+                hash = (await rpc(client, 'eth_sendTransaction', [{ from: deployer, to: deployment.verifier, data }]));
+            }
+            finally {
+                await rpc(client, 'anvil_stopImpersonatingAccount', [deployer]);
+            }
+            const receipt = await waitForTransactionReceipt(client, { hash });
+            setStates((prev) => ({ ...prev, [wallet.toLowerCase()]: state }));
+            setMessage(`${short(wallet)} is now ${state} (block ${receipt.blockNumber.toString()})`);
+            notifyEligibilityChanged(wallet);
+        }
+        catch (e) {
+            setMessage(e instanceof Error ? e.message : String(e));
+        }
+        finally {
+            setBusy(null);
+        }
+    }, [client, connection.address, deployment.deployer.address, deployment.verifier, requestId]);
+    // One connector per seeded wallet, created here and handed to wagmi on click, so the app's own
+    // wagmi config needs no dev wiring: nothing about Anvil accounts exists outside this panel.
+    const connectorFor = useMemo(() => {
+        const byIndex = new Map(deployment.wallets.map((w) => [w.index, anvilAccountConnector({ address: w.address, index: w.index, label: `Wallet ${w.index} (${w.state})` })]));
+        return (index) => byIndex.get(index);
+    }, [deployment.wallets]);
+    if (!onLocal)
+        return null;
+    const connectedRow = connected && deployment.wallets.find((w) => w.address.toLowerCase() === connected);
+    const connectedState = connected ? states[connected] : undefined;
+    return (_jsxs("section", { className: ['rb-devstate', className].filter(Boolean).join(' '), "aria-label": "Local dev state", children: [_jsxs("p", { className: "rb-devstate-title", children: ["Dev state", _jsxs("span", { className: "rb-devstate-muted", children: [' ', "Anvil chain ", LOCAL_CHAIN_ID, deployment.forkOf ? `, fork of ${deployment.forkOf}` : ', no fork', ", request id ", deployment.requestId, ". Dev server only; never on 151 or 153."] })] }), _jsxs("table", { className: "rb-devstate-table", children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { children: "Wallet" }), _jsx("th", { children: "State" }), _jsx("th", { children: "Address" }), _jsx("th", {})] }) }), _jsx("tbody", { children: deployment.wallets.map((w) => {
+                            const isConnected = connected === w.address.toLowerCase();
+                            const connector = connectorFor(w.index);
+                            const state = states[w.address.toLowerCase()] ?? w.state;
+                            return (_jsxs("tr", { className: isConnected ? 'rb-devstate-connected' : undefined, "aria-current": isConnected ? 'true' : undefined, children: [_jsxs("td", { children: [w.index, isConnected ? _jsx("span", { className: "rb-devstate-mark", children: " connected" }) : null] }), _jsxs("td", { children: [state, " ", _jsxs("span", { className: "rb-devstate-muted", children: ["(", STATE_HINT[state], ")"] })] }), _jsx("td", { children: _jsx("code", { title: w.address, children: short(w.address) }) }), _jsx("td", { children: isConnected ? (_jsx("button", { type: "button", className: "rb-devstate-button", onClick: () => disconnect.mutate({}), children: "Disconnect" })) : connector ? (_jsx("button", { type: "button", className: "rb-devstate-button", disabled: connect.isPending, onClick: () => connect.mutate({ connector }), children: "Connect" })) : null })] }, w.address));
+                        }) })] }), _jsxs("div", { className: "rb-devstate-actions", role: "group", "aria-label": "Set the connected wallet's state", children: [_jsx("span", { className: "rb-devstate-muted", children: connection.address
+                            ? `Set ${connectedRow ? `wallet ${connectedRow.index}` : short(connection.address)} to:`
+                            : 'Connect a wallet above to change its state.' }), ELIGIBILITY_STATES.map((s) => (_jsx("button", { type: "button", className: "rb-devstate-button", disabled: !connection.address || busy !== null || connectedState === s, "aria-pressed": connectedState === s, onClick: () => void setState(s), children: busy === s ? `${s}…` : s }, s)))] }), message ? _jsx("p", { className: "rb-devstate-muted rb-devstate-message", children: message }) : null] }));
+}

package/dist/dev/anvilConnector.d.ts

@@ -0,0 +1,25 @@
+import { type EIP1193RequestFn } from 'viem';
+import type { Address } from '../useEligibility.js';
+import type { LocalDeployment } from './localDeployment.js';
+export interface AnvilAccountConnectorOptions {
+    /** The Anvil account to act as. Must be one the node has unlocked (its own ten, or an impersonated one). */
+    address: Address;
+    /** The account's index, for the connector's name. */
+    index: number;
+    /** A label for the button; defaults to `Wallet <index>`. */
+    label?: string;
+}
+/**
+ * A wagmi connector for one of Anvil's unlocked accounts. Every request goes straight to the
+ * chain's RPC: `eth_sendTransaction` is signed by the node, so the browser never holds a key
+ * and nothing is imported into a wallet extension. It only makes sense against a local Anvil
+ * (chain 31337); `npm run dev` in a scaffold adds one per seeded wallet in the dev server and
+ * none in a production build.
+ */
+export declare function anvilAccountConnector({ address, index, label }: AnvilAccountConnectorOptions): import("wagmi").CreateConnectorFn<{
+    request: EIP1193RequestFn;
+}, Record<string, unknown>, Record<string, unknown>>;
+/** One connector per seeded wallet, in the file's order (NeverIssued first, Valid second). */
+export declare function anvilAccountConnectors(deployment: LocalDeployment): import("wagmi").CreateConnectorFn<{
+    request: EIP1193RequestFn;
+}, Record<string, unknown>, Record<string, unknown>>[];

package/dist/dev/anvilConnector.js

@@ -0,0 +1,78 @@
+import { createConnector } from 'wagmi';
+import { getAddress, numberToHex } from 'viem';
+/**
+ * A wagmi connector for one of Anvil's unlocked accounts. Every request goes straight to the
+ * chain's RPC: `eth_sendTransaction` is signed by the node, so the browser never holds a key
+ * and nothing is imported into a wallet extension. It only makes sense against a local Anvil
+ * (chain 31337); `npm run dev` in a scaffold adds one per seeded wallet in the dev server and
+ * none in a production build.
+ */
+export function anvilAccountConnector({ address, index, label }) {
+    const account = getAddress(address);
+    let connected = false;
+    return createConnector((config) => ({
+        id: `anvil-account-${index}`,
+        name: label ?? `Wallet ${index}`,
+        type: 'anvilAccount',
+        async connect() {
+            connected = true;
+            // wagmi types the accounts by a `withCapabilities` generic; this connector has no capabilities to report.
+            return { accounts: [account], chainId: await this.getChainId() };
+        },
+        async disconnect() {
+            connected = false;
+        },
+        async getAccounts() {
+            return connected ? [account] : [];
+        },
+        async getChainId() {
+            const chain = config.chains[0];
+            if (!chain)
+                throw new Error('no chain configured');
+            return chain.id;
+        },
+        async isAuthorized() {
+            return connected;
+        },
+        async switchChain({ chainId }) {
+            const chain = config.chains.find((c) => c.id === chainId);
+            if (!chain)
+                throw new Error(`chain ${chainId} is not configured`);
+            return chain;
+        },
+        onAccountsChanged() { },
+        onChainChanged() { },
+        onDisconnect() {
+            connected = false;
+            config.emitter.emit('disconnect');
+        },
+        async getProvider() {
+            const chain = config.chains[0];
+            if (!chain)
+                throw new Error('no chain configured');
+            const url = chain.rpcUrls.default.http[0];
+            if (!url)
+                throw new Error('the chain has no HTTP RPC URL');
+            const request = (async ({ method, params }) => {
+                if (method === 'eth_accounts' || method === 'eth_requestAccounts')
+                    return [account];
+                if (method === 'eth_chainId')
+                    return numberToHex(chain.id);
+                const response = await fetch(url, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json' },
+                    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params: params ?? [] }),
+                });
+                const body = (await response.json());
+                if (body.error)
+                    throw new Error(body.error.message ?? 'RPC error');
+                return body.result;
+            });
+            return { request };
+        },
+    }));
+}
+/** One connector per seeded wallet, in the file's order (NeverIssued first, Valid second). */
+export function anvilAccountConnectors(deployment) {
+    return deployment.wallets.map((w) => anvilAccountConnector({ address: w.address, index: w.index, label: `Wallet ${w.index} (${w.state})` }));
+}

package/dist/dev/index.d.ts

@@ -0,0 +1,6 @@
+export { DevStatePanel } from './DevStatePanel.js';
+export type { DevStatePanelProps } from './DevStatePanel.js';
+export { anvilAccountConnector, anvilAccountConnectors } from './anvilConnector.js';
+export type { AnvilAccountConnectorOptions } from './anvilConnector.js';
+export { parseLocalDeployment, ELIGIBILITY_STATES, LOCAL_CHAIN_ID } from './localDeployment.js';
+export type { LocalDeployment, LocalWallet, EligibilityStateName } from './localDeployment.js';

package/dist/dev/index.js

@@ -0,0 +1,6 @@
+// `@gatedpath/frontend-kit/dev`: the local-loop pieces (PLAN.md 18.1). Import this path only from
+// code a dev server runs; the scaffold's `web/src/components/DevState.tsx` does, behind a build-time
+// check that leaves nothing of it in a production bundle.
+export { DevStatePanel } from './DevStatePanel.js';
+export { anvilAccountConnector, anvilAccountConnectors } from './anvilConnector.js';
+export { parseLocalDeployment, ELIGIBILITY_STATES, LOCAL_CHAIN_ID } from './localDeployment.js';

package/dist/dev/localDeployment.d.ts

@@ -0,0 +1,37 @@
+import type { Address } from '../useEligibility.js';
+/** The chain id `npm run dev` gives its Anvil. The panel renders on this chain and no other. */
+export declare const LOCAL_CHAIN_ID = 31337;
+/** The five credential states, in `EligibilityStatus` enum order from @gatedpath/receptor-mock. */
+export declare const ELIGIBILITY_STATES: readonly ["NeverIssued", "Valid", "Expired", "Revoked", "WrongJurisdiction"];
+export type EligibilityStateName = (typeof ELIGIBILITY_STATES)[number];
+/** One seeded wallet. `index` is the Anvil account index; the file never carries a key. */
+export interface LocalWallet {
+    index: number;
+    state: EligibilityStateName;
+    address: Address;
+    note: string;
+}
+/**
+ * `deployments/local.json` as `scripts/dev.mjs` writes it in a scaffold (PLAN.md 18.1). `deployer`
+ * is Anvil account 7, the account that deployed the mock and holds the contract's admin roles; the
+ * panel impersonates it to call `setStatus`. Accounts 0 and 1 are never used (RESEARCH.md 30).
+ */
+export interface LocalDeployment {
+    chainId: number;
+    forkOf: 151 | 153 | null;
+    verifier: Address;
+    contract: Address;
+    requestId: number;
+    deployer: {
+        index: number;
+        address: Address;
+    };
+    wallets: LocalWallet[];
+    startedAt: string;
+}
+/**
+ * Parses the JSON `next.config.ts` inlines as `NEXT_PUBLIC_LOCAL_DEPLOYMENT` in the dev server.
+ * Returns null for anything that is not a well-formed local deployment on chain 31337, so a
+ * stray value can never make the panel appear against a real network.
+ */
+export declare function parseLocalDeployment(json: string | undefined | null): LocalDeployment | null;

package/dist/dev/localDeployment.js

@@ -0,0 +1,41 @@
+/** The chain id `npm run dev` gives its Anvil. The panel renders on this chain and no other. */
+export const LOCAL_CHAIN_ID = 31337;
+/** The five credential states, in `EligibilityStatus` enum order from @gatedpath/receptor-mock. */
+export const ELIGIBILITY_STATES = ['NeverIssued', 'Valid', 'Expired', 'Revoked', 'WrongJurisdiction'];
+/**
+ * Parses the JSON `next.config.ts` inlines as `NEXT_PUBLIC_LOCAL_DEPLOYMENT` in the dev server.
+ * Returns null for anything that is not a well-formed local deployment on chain 31337, so a
+ * stray value can never make the panel appear against a real network.
+ */
+export function parseLocalDeployment(json) {
+    if (!json)
+        return null;
+    let value;
+    try {
+        value = JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+    if (!value || typeof value !== 'object')
+        return null;
+    const d = value;
+    const isAddress = (a) => typeof a === 'string' && /^0x[0-9a-fA-F]{40}$/.test(a);
+    if (d.chainId !== LOCAL_CHAIN_ID)
+        return null;
+    if (!isAddress(d.verifier) || !isAddress(d.contract))
+        return null;
+    if (typeof d.requestId !== 'number')
+        return null;
+    if (!d.deployer || !isAddress(d.deployer.address) || typeof d.deployer.index !== 'number')
+        return null;
+    if (!Array.isArray(d.wallets) || d.wallets.length !== ELIGIBILITY_STATES.length)
+        return null;
+    for (const [i, w] of d.wallets.entries()) {
+        if (!w || !isAddress(w.address) || w.state !== ELIGIBILITY_STATES[i] || typeof w.index !== 'number')
+            return null;
+        if (w.index < 2)
+            return null; // accounts 0 and 1 are never used
+    }
+    return d;
+}

package/dist/dev.css

@@ -0,0 +1,37 @@
+/* @gatedpath/frontend-kit/dev.css: the dev state panel's default style, on the same tokens as
+   styles.css. A separate file so a production build that loads styles.css carries nothing of the
+   panel; the scaffold's dev-only loader is the one place that imports it. */
+.rb-devstate {
+  font-family: var(--sl-font, 'Readex Pro', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif);
+  color: var(--rb-color-text, #283A46);
+  background: var(--rb-color-surface, #EFF3F6);
+  border: 1px dashed var(--rb-color-hairline-strong, #848B91);
+  border-radius: var(--rb-radius-lg, 10px);
+  padding: var(--rb-space-4, 1rem) var(--rb-space-5, 1.25rem);
+  margin: var(--rb-space-4, 1rem) 0;
+  font-size: var(--sl-text-sm, 0.875rem);
+  line-height: var(--sl-line-height, 1.6);
+}
+.rb-devstate-title { margin: 0 0 var(--rb-space-2, 0.5rem); font-weight: var(--rb-weight-strong, 600); }
+.rb-devstate-muted { color: var(--rb-color-text-muted, #4C6B80); font-weight: 400; }
+.rb-devstate-message { margin: var(--rb-space-2, 0.5rem) 0 0; }
+.rb-devstate-table { border-collapse: collapse; width: 100%; margin: 0 0 var(--rb-space-3, 0.75rem); }
+.rb-devstate-table th, .rb-devstate-table td { text-align: left; padding: 0.25rem 0.5rem 0.25rem 0; border-bottom: 1px solid var(--rb-color-hairline, #DFE7EC); vertical-align: top; }
+.rb-devstate-connected td { font-weight: var(--rb-weight-strong, 600); }
+.rb-devstate-mark { color: var(--rb-color-accent, #0F766E); font-weight: var(--rb-weight-strong, 600); }
+.rb-devstate-actions { display: flex; flex-wrap: wrap; gap: 0.5rem; align-items: center; }
+.rb-devstate-button {
+  font: inherit;
+  padding: 0.25rem 0.6rem;
+  border-radius: var(--rb-radius-md, 6px);
+  border: 1px solid var(--rb-color-hairline-strong, #848B91);
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+}
+.rb-devstate-button[aria-pressed='true'] { border-color: var(--rb-color-accent, #0F766E); color: var(--rb-color-accent, #0F766E); }
+.rb-devstate-button:disabled { opacity: 0.5; cursor: default; }
+.rb-devstate code {
+  font-family: var(--sl-font-mono, 'JetBrains Mono', ui-monospace, Menlo, monospace);
+  font-size: var(--sl-text-code, 0.875rem);
+}

package/dist/events.d.ts

@@ -0,0 +1,7 @@
+import type { Address } from './useEligibility.js';
+type Listener = (address: Address | undefined) => void;
+/** Tells every mounted `useEligibility` for `address` (or every one, when omitted) to refetch. */
+export declare function notifyEligibilityChanged(address?: Address): void;
+/** Subscribes; returns the unsubscribe function. Used by `useEligibility`. */
+export declare function onEligibilityChanged(listener: Listener): () => void;
+export {};

package/dist/events.js

@@ -0,0 +1,13 @@
+const listeners = new Set();
+/** Tells every mounted `useEligibility` for `address` (or every one, when omitted) to refetch. */
+export function notifyEligibilityChanged(address) {
+    for (const listener of listeners)
+        listener(address);
+}
+/** Subscribes; returns the unsubscribe function. Used by `useEligibility`. */
+export function onEligibilityChanged(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}

package/dist/expiry.d.ts

@@ -0,0 +1,12 @@
+import type { PublicClient } from 'viem';
+import type { Address } from './useEligibility.js';
+/**
+ * An `expiry` reader for `useEligibility` that works when the verifier is a `ReceptorMock`
+ * (testnet and forks). It reads `recordFor(wallet, requestId).expiresAt`; zero means no expiry.
+ * Real verifiers (an Iden3 `ZKPVerifier` child, a `VCVerifierBaseContract` child) do not expose
+ * an expiry, so on mainnet leave `expiry` unset and the `expiring` state never shows.
+ */
+export declare function receptorMockExpiry(client: PublicClient, verifier: Address): ({ address, requestId }: {
+    address: Address;
+    requestId: bigint;
+}) => Promise<number | null>;

package/dist/expiry.js

@@ -0,0 +1,19 @@
+import { receptorMockAbi } from './abi.js';
+/**
+ * An `expiry` reader for `useEligibility` that works when the verifier is a `ReceptorMock`
+ * (testnet and forks). It reads `recordFor(wallet, requestId).expiresAt`; zero means no expiry.
+ * Real verifiers (an Iden3 `ZKPVerifier` child, a `VCVerifierBaseContract` child) do not expose
+ * an expiry, so on mainnet leave `expiry` unset and the `expiring` state never shows.
+ */
+export function receptorMockExpiry(client, verifier) {
+    return async ({ address, requestId }) => {
+        const record = await client.readContract({
+            address: verifier,
+            abi: receptorMockAbi,
+            functionName: 'recordFor',
+            args: [address, requestId],
+        });
+        const expiresAt = Number(record.expiresAt);
+        return record.isSet && expiresAt > 0 ? expiresAt : null;
+    };
+}

package/dist/explainError.d.ts

@@ -0,0 +1,34 @@
+import type { EligibilityStatusName } from '@gatedpath/agent-rules/failures';
+export interface ExplainedError {
+    /** A kind from the failure table, or "unknown". */
+    kind: string;
+    plainWords: string;
+    cause: string;
+    fix: {
+        command?: string;
+        link?: string;
+    };
+    /** The table entry's heading, when known. */
+    title?: string;
+    /** The site page for this kind, when known. */
+    docsPage?: string;
+    /** `NotEligible(wallet, requestId)` arguments when they could be read from the revert. */
+    notEligible?: {
+        wallet: string;
+        requestId: string;
+    };
+    /** The revert selector when the error carried revert data. */
+    selector?: string;
+    /** The error's own words, shortened, for a details line. */
+    raw: string;
+}
+export interface ExplainErrorOptions {
+    /**
+     * The credential state behind a NotEligible revert, when the page already knows it (from
+     * `receptorMockStatus` on a ReceptorMock, or the dev state panel). Picks the entry for that
+     * state; a real verifier cannot tell, so leave it unset there.
+     */
+    eligibilityStatus?: EligibilityStatusName | number | null;
+}
+/** Explains an error from wagmi's `useWriteContract`, viem's clients, or anything with a `cause` chain. */
+export declare function explainError(error: unknown, options?: ExplainErrorOptions): ExplainedError;

package/dist/explainError.js

@@ -0,0 +1,113 @@
+// explainError: a viem or wagmi error in, the plain words from the shared failure table out. The
+// same table the MCP server's explain_failure reads (@gatedpath/agent-rules/failures), so a page
+// shows the words an agent would see instead of a hex revert. Pure: no network, no React.
+//
+// What it decodes: a ContractFunctionRevertedError (NotEligible by selector or by the decoded
+// error name, the deploy script's Error(string) reasons, ZeroVerifier), a user rejection in the
+// wallet, a wrong or unswitchable chain, and not enough RBNT for gas. Anything else comes back as
+// kind "unknown" with the error's own message, never a guess.
+import { decodeRevertData, failureByKind, matchErrorName, matchText, notEligibleEntry, revertHexIn, ELIGIBILITY_STATUS_NAMES, } from '@gatedpath/agent-rules/failures';
+function chain(error) {
+    const out = [];
+    let e = error;
+    for (let i = 0; i < 12 && e && typeof e === 'object'; i++) {
+        out.push(e);
+        e = e.cause;
+    }
+    return out;
+}
+function words(error) {
+    if (typeof error === 'string')
+        return error;
+    const parts = chain(error).flatMap((e) => [e.shortMessage, e.details, e.message]).filter((s) => typeof s === 'string' && s.length > 0);
+    return parts.join('\n');
+}
+function fromEntry(entry, raw, extra = {}) {
+    return {
+        kind: entry.kind,
+        plainWords: entry.plainWords,
+        cause: entry.cause,
+        fix: { ...(entry.fix.command ? { command: entry.fix.command } : {}), ...(entry.fix.link ? { link: entry.fix.link } : {}) },
+        title: entry.title,
+        docsPage: entry.docsPage,
+        raw: raw.slice(0, 600),
+        ...extra,
+    };
+}
+function statusName(status) {
+    if (status === null || status === undefined)
+        return null;
+    if (typeof status === 'number')
+        return ELIGIBILITY_STATUS_NAMES[status] ?? null;
+    return status;
+}
+/** Explains an error from wagmi's `useWriteContract`, viem's clients, or anything with a `cause` chain. */
+export function explainError(error, options = {}) {
+    const raw = words(error);
+    const links = chain(error);
+    // 1. Revert data on a ContractFunctionRevertedError (or anything carrying `raw`/`data` hex).
+    for (const e of links) {
+        const hex = typeof e.raw === 'string' && /^0x[0-9a-fA-F]{8,}$/.test(e.raw) ? e.raw : typeof e.data === 'string' && /^0x[0-9a-fA-F]{8,}$/.test(e.data) ? e.data : null;
+        const decodedByViem = e.data && typeof e.data === 'object' && typeof e.data.errorName === 'string' ? e.data : null;
+        if (decodedByViem?.errorName === 'NotEligible') {
+            const [wallet, requestId] = decodedByViem.args ?? [];
+            const entry = notEligibleEntry(statusName(options.eligibilityStatus));
+            return fromEntry(entry, raw, {
+                selector: hex ? hex.slice(0, 10).toLowerCase() : undefined,
+                notEligible: { wallet: String(wallet ?? '').toLowerCase(), requestId: String(requestId ?? '') },
+            });
+        }
+        if (hex) {
+            const decoded = decodeRevertData(hex);
+            if (decoded?.kind === 'not-eligible') {
+                const entry = notEligibleEntry(statusName(options.eligibilityStatus));
+                return fromEntry(entry, raw, { selector: decoded.selector, ...(decoded.notEligible ? { notEligible: decoded.notEligible } : {}) });
+            }
+            if (decoded?.kind)
+                return fromEntry(failureByKind(decoded.kind), raw, { selector: decoded.selector });
+            if (decoded) {
+                const byText = matchText(raw);
+                if (byText)
+                    return fromEntry(byText, raw, { selector: decoded.selector });
+                return { kind: 'unknown', plainWords: "This failure isn't in the table, so there are no plain words for it yet.", cause: `The contract reverted with selector ${decoded.selector}, which the table doesn't know.`, fix: {}, selector: decoded.selector, raw: raw.slice(0, 600) };
+            }
+        }
+        if (decodedByViem && decodedByViem.errorName === 'ZeroVerifier')
+            return fromEntry(failureByKind('zero-verifier'), raw);
+        if (typeof e.reason === 'string') {
+            const byReason = matchText(e.reason);
+            if (byReason)
+                return fromEntry(byReason, raw);
+        }
+    }
+    // 2. viem's own classes, by name along the cause chain (the wallet's 4001 arrives as UserRejectedRequestError).
+    for (const e of links) {
+        const byName = typeof e.name === 'string' ? matchErrorName(e.name) : undefined;
+        if (byName)
+            return fromEntry(byName, raw);
+        if (e.code === 4001)
+            return fromEntry(failureByKind('user-rejected'), raw);
+    }
+    // 3. Revert data quoted inside a message (a node's `execution reverted: custom error 0x…` text).
+    const quoted = revertHexIn(raw);
+    if (quoted) {
+        const decoded = decodeRevertData(quoted);
+        if (decoded?.kind === 'not-eligible') {
+            const entry = notEligibleEntry(statusName(options.eligibilityStatus));
+            return fromEntry(entry, raw, { selector: decoded.selector, ...(decoded.notEligible ? { notEligible: decoded.notEligible } : {}) });
+        }
+        if (decoded?.kind)
+            return fromEntry(failureByKind(decoded.kind), raw, { selector: decoded.selector });
+    }
+    // 4. The words themselves.
+    const byText = matchText(raw);
+    if (byText)
+        return fromEntry(byText, raw);
+    return {
+        kind: 'unknown',
+        plainWords: "This failure isn't in the table, so there are no plain words for it yet.",
+        cause: 'Nothing in the failure table matched the error. Its own message is in raw.',
+        fix: {},
+        raw: raw.slice(0, 600) || String(error),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { useEligibility } from './useEligibility.js';
+export type { Address, EligibilityState, EligibilityResult, UseEligibilityOptions } from './useEligibility.js';
+export { receptorMockExpiry } from './expiry.js';
+export { notifyEligibilityChanged, onEligibilityChanged } from './events.js';
+export { EligibilityGate, NotConnected, NotVerified, Ineligible, Eligible, ExpiringSoon, Checking, EligibilityError, LastChecked, GasWarning, } from './components.js';
+export type { EligibilityGateProps, StateProps, NotVerifiedProps, IneligibleProps, ExpiringSoonProps, EligibilityErrorProps, LastCheckedProps, GasWarningProps, } from './components.js';
+export { verifierAbi, permissionAbi, receptorMockAbi, receptorMockStatusAbi } from './abi.js';
+export { ACCESS_URL, FAUCET_URL, VINE_INTERACTION_URL, VINE_FEES_URL } from './urls.js';
+export { explainError } from './explainError.js';
+export type { ExplainedError, ExplainErrorOptions } from './explainError.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+export { useEligibility } from './useEligibility.js';
+export { receptorMockExpiry } from './expiry.js';
+export { notifyEligibilityChanged, onEligibilityChanged } from './events.js';
+export { EligibilityGate, NotConnected, NotVerified, Ineligible, Eligible, ExpiringSoon, Checking, EligibilityError, LastChecked, GasWarning, } from './components.js';
+export { verifierAbi, permissionAbi, receptorMockAbi, receptorMockStatusAbi } from './abi.js';
+export { ACCESS_URL, FAUCET_URL, VINE_INTERACTION_URL, VINE_FEES_URL } from './urls.js';
+export { explainError } from './explainError.js';