@gatedpath/frontend-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gatedpath and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,162 @@
+# @gatedpath/frontend-kit
+
+```
+For agents
+- One hook: `useEligibility(address, verifier, requestId, options?)`. It reads the network gate
+  (`permission.isAllowed`) and the dApp's gate (`verifier.isEligible`), caches both, refetches on
+  a new block or every 30 s, and exposes `refresh()`. Don't poll the RPC yourself around it.
+- Five states, one component each, or `<EligibilityGate>` to pick for you: `disconnected`,
+  `unverified`, `ineligible`, `eligible`, `expiring` (plus `checking` and `error`). The gate is the
+  contract; these components decide what a button says, never whether a transaction may run.
+- `expiring` only shows when the verifier can tell. `ReceptorMock` can (`receptorMockExpiry`);
+  real verifiers can't, so leave `expiry` unset on mainnet.
+- Never suggest anvil's default accounts anywhere: they pass `isAllowed` on the real networks
+  (RESEARCH.md question 30). `test/hygiene.test.ts` fails the build if one appears.
+- Show `<GasWarning>` near the first transaction; docs/wallet-gas-warning.md says why.
+- `explainError(error)` turns a viem or wagmi error into the plain words from the shared failure
+  table (`@gatedpath/agent-rules/failures`): NotEligible (with the credential state when you pass
+  one), a wallet rejection, a wrong chain, not enough RBNT. Show `plainWords` and `fix.link`, never
+  `error.message` alone; `kind: "unknown"` carries the error's own words in `raw`.
+- Build: `npm run build`. Tests: `npm test` (Vitest, jsdom, a mocked transport; no network).
+```
+
+The frontend kit from `PLAN.md` section 5.6: React components for the states every Redbelly dApp
+has and most will get wrong, and a hook that reads eligibility once and caches it so the UI does
+not hammer the RPC. wagmi 3 and viem 2 as peers, headless with a small default style that takes
+its colours, radii and type from the site's design tokens.
+
+## The hook
+
+```tsx
+import { useEligibility } from '@gatedpath/frontend-kit';
+
+const eligibility = useEligibility(address, verifier, requestId, {
+  refreshInterval: 30_000, // floor; every new block also refetches
+  watchBlocks: true,       // eth_blockNumber polled by wagmi, reads refetched only when it changes
+  expiry: receptorMockExpiry(publicClient, verifier), // testnet and forks only
+  expiringWindowSeconds: 7 * 86_400,
+});
+// eligibility.state, .isAllowed, .isEligible, .expiresAt, .secondsToExpiry,
+// .lastCheckedAt, .blockNumber, .isFetching, .error, .refresh()
+```
+
+Two reads, both `view`: the network's permission contract (address from
+`@gatedpath/chains` for the current chain, or `options.permission`) and the dApp's verifier
+behind `IRedbellyVerifier.isEligible(wallet, requestId)` from receptor-mock. wagmi batches them
+through Multicall3, which is deployed on both networks, so one `eth_call` per refetch. Results are
+cached by wagmi's query client under the wallet, verifier, request id and chain, so every
+component asking the same question shares one read.
+
+Why block-or-30-seconds: blocks on Redbelly are produced on demand (RESEARCH.md question 4). A
+busy chain gives you a block every few seconds and the reads follow it; a quiet chain gives you
+none, and then a credential that was revoked off-chain would never show until the next block, so
+the interval is the floor. `refresh()` is for the moment after the user comes back from
+access.redbelly.network.
+
+State derivation, in order: no address is `disconnected`; nothing cached and an RPC error is
+`error`; nothing cached yet is `checking`; `isAllowed` false is `unverified` whatever the verifier
+says; `isEligible` false is `ineligible`; `isEligible` true with an expiry inside the window is
+`expiring`; otherwise `eligible`.
+
+## The components
+
+| Component | State | Says |
+|---|---|---|
+| `NotConnected` | `disconnected` | Connect a wallet; identity is per wallet here |
+| `NotVerified` | `unverified` | The wallet is not allowed to transact; link to access.redbelly.network, the faucet on testnet, don't switch wallets |
+| `Ineligible` | `ineligible` | Verified on the network but no accepted proof for this action; the answer is a plain yes or no |
+| `Eligible` | `eligible` | Wraps your action |
+| `ExpiringSoon` | `expiring` | Wraps your action and says when the credential expires |
+| `Checking`, `EligibilityError` | `checking`, `error` | In flight; the RPC failed and nothing is cached, with a retry |
+| `EligibilityGate` | any | Picks one of the above from the hook result; `render` overrides any state |
+| `LastChecked` | | "Last checked at block N" with a refresh button |
+| `GasWarning` | | Vine's wallet gas warning, with a live USD figure if you pass one |
+
+Each renders plain elements with `rb-elig-*` class names. Import
+`@gatedpath/frontend-kit/styles.css` for the default look, which reads the site's
+`--rb-*` and `--sl-*` tokens with their light values as fallbacks, so it follows the site's dark
+theme when `tokens.css` is loaded and looks the same on its own. Or skip the stylesheet and style
+the class names.
+
+## A page
+
+```tsx
+const { address } = useConnection();
+const eligibility = useEligibility(address, verifier, requestId);
+return (
+  <>
+    <EligibilityGate eligibility={eligibility} address={address} chainName={chain.name} testnet={chain.testnet}>
+      <button onClick={subscribe}>Subscribe</button>
+    </EligibilityGate>
+    <LastChecked eligibility={eligibility} />
+    <GasWarning transferUsd={usd} />
+  </>
+);
+```
+
+The scaffolder's `web/` app has this as a working page at `/eligibility`
+(`templates/web/src/app/eligibility/page.tsx`): it reads the template contract's `verifier()` and
+`requestId()`, uses `receptorMockExpiry` on testnet, and prices the gas figure from the on-chain
+feed with `gasCostUsd` from `@gatedpath/chains`.
+
+## The dev entry: `@gatedpath/frontend-kit/dev`
+
+The local loop from PLAN.md 18.1. `DevStatePanel` lists the five wallets `npm run dev` seeded
+in a scaffold, marks the connected one, and flips the connected wallet through NeverIssued,
+Valid, Expired, Revoked and WrongJurisdiction by calling `setStatus` on the `ReceptorMock` as the
+deployer through Anvil's impersonation RPC (`anvil_impersonateAccount`, then stop). It fires
+`notifyEligibilityChanged(wallet)`, which every mounted `useEligibility` for that wallet listens
+to, so the page moves into the new state without a reload or a new block. `anvilAccountConnector`
+is a wagmi connector for one of Anvil's unlocked accounts: the node signs, the browser never holds
+a key. Its style is `@gatedpath/frontend-kit/dev.css`, kept apart from `styles.css` so a
+production bundle that loads the main stylesheet carries nothing of the panel. `parseLocalDeployment` reads `deployments/local.json` as `scripts/dev.mjs` writes it and
+refuses anything that isn't chain 31337 with five wallets on accounts 2 or later.
+
+The panel renders only on chain 31337. On 151 or 153 it renders nothing whatever it is given,
+and the scaffold imports it only in the dev server behind a build-time constant, so a production
+bundle carries none of it; the scaffolder's integration test builds one and checks.
+
+## Tests
+
+`npm test`: 80 Vitest tests in jsdom. `test/mock-chain.tsx` is a wagmi config over a `custom`
+transport that answers `eth_chainId`, `eth_blockNumber`, `eth_call` and Multicall3 `aggregate3`
+from an in-memory state the tests mutate; nothing leaves the process and no address in it exists
+anywhere. The hook tests cover every state, that reads happen once and then only on a new block,
+manual refresh without a block, shared reads, the expiry window, errors and `enabled: false`. The
+component tests render every state, the gate's selection and override, the links (Access dApp,
+faucet, Vine) and the retry and refresh buttons. `test/dev-panel.test.tsx` runs the dev panel
+against a fake chain 31337 (and proves it renders nothing on 153 or 151), including the
+impersonate, send, stop sequence and the refetch without a new block. `test/hygiene.test.ts` walks every file in the
+package and fails on any of anvil's ten default accounts or any 64-hex value.
+
+Not tested: a real wallet. Nothing here signs; the kit reads and renders.
+
+## Not in v1
+
+Storybook (optional in the brief, skipped). A connect button (wagmi's own connectors and the
+scaffolder's `Connect` component do that). Anything that calls the Eligibility SDK: the kit tells
+the user they are ineligible, and the SDK is the thing that can tell them why; the scaffolder's
+`web/src/eligibility/` has the steps for adding it.
+
+## explainError
+
+```tsx
+import { explainError } from '@gatedpath/frontend-kit';
+
+const write = useWriteContract();
+// …
+{write.error && <p>{explainError(write.error).plainWords}</p>}
+```
+
+`explainError(error, { eligibilityStatus? })` walks the error's `cause` chain and answers
+`{ kind, plainWords, cause, fix: { command?, link? }, title?, docsPage?, notEligible?, selector?, raw }`
+from the failure table in `@gatedpath/agent-rules/failures`, the same table the MCP server's
+`explain_failure` and the site's `/errors` page read. It decodes a `ContractFunctionRevertedError`
+by its revert data (a `NotEligible(wallet, requestId)` selector, `ZeroVerifier`, or an
+`Error(string)` reason from the deploy script) or by the error name viem decoded, and recognises
+`UserRejectedRequestError` (or an EIP-1193 code 4001), `ChainMismatchError`, `SwitchChainError` and
+`InsufficientFundsError` by class wherever they sit in the chain. Pass `eligibilityStatus` when the
+page already knows the state behind a `NotEligible` (a `ReceptorMock` can say; a real verifier
+can't) and the entry for that state comes back. Anything else is `kind: "unknown"` with the
+error's own message in `raw`, never a guess. Pure: no network, no React. The scaffold's web app
+renders it in `web/src/components/FailureWords.tsx` under the gated button and the eligibility page.

package/dist/abi.d.ts

@@ -0,0 +1,98 @@
+/** `IRedbellyVerifier.isEligible(address, uint64)` from @gatedpath/receptor-mock. */
+export declare const verifierAbi: readonly [{
+    readonly type: "function";
+    readonly name: "isEligible";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "wallet";
+        readonly type: "address";
+    }, {
+        readonly name: "requestId";
+        readonly type: "uint64";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+}];
+/** The network's permission contract: `isAllowed(address)` (RESEARCH.md question 7). */
+export declare const permissionAbi: readonly [{
+    readonly type: "function";
+    readonly name: "isAllowed";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "wallet";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+}];
+/**
+ * `ReceptorMock.recordFor(address, uint64)` from @gatedpath/receptor-mock. The mock is the
+ * only verifier in the kit that can say when a credential expires; real verifiers answer a plain
+ * boolean. Used by `receptorMockExpiry` for testnet and fork demos only.
+ */
+export declare const receptorMockAbi: readonly [{
+    readonly type: "function";
+    readonly name: "recordFor";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "wallet";
+        readonly type: "address";
+    }, {
+        readonly name: "requestId";
+        readonly type: "uint64";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "isSet";
+            readonly type: "bool";
+        }, {
+            readonly name: "status";
+            readonly type: "uint8";
+        }, {
+            readonly name: "expiresAt";
+            readonly type: "uint64";
+        }];
+    }];
+}];
+/**
+ * The two `ReceptorMock` functions the dev state panel uses on a local Anvil (chain 31337):
+ * `setStatus(wallet, requestId, status)` writes a state, `eligibilityStatus(wallet, requestId)`
+ * reads it back. Never called against 151 or 153; the panel refuses to render there.
+ */
+export declare const receptorMockStatusAbi: readonly [{
+    readonly type: "function";
+    readonly name: "setStatus";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "wallet";
+        readonly type: "address";
+    }, {
+        readonly name: "requestId";
+        readonly type: "uint64";
+    }, {
+        readonly name: "status";
+        readonly type: "uint8";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "eligibilityStatus";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "wallet";
+        readonly type: "address";
+    }, {
+        readonly name: "requestId";
+        readonly type: "uint64";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint8";
+    }];
+}];

package/dist/abi.js

@@ -0,0 +1,79 @@
+// The two reads the kit makes. Nothing else is called.
+/** `IRedbellyVerifier.isEligible(address, uint64)` from @gatedpath/receptor-mock. */
+export const verifierAbi = [
+    {
+        type: 'function',
+        name: 'isEligible',
+        stateMutability: 'view',
+        inputs: [
+            { name: 'wallet', type: 'address' },
+            { name: 'requestId', type: 'uint64' },
+        ],
+        outputs: [{ name: '', type: 'bool' }],
+    },
+];
+/** The network's permission contract: `isAllowed(address)` (RESEARCH.md question 7). */
+export const permissionAbi = [
+    {
+        type: 'function',
+        name: 'isAllowed',
+        stateMutability: 'view',
+        inputs: [{ name: 'wallet', type: 'address' }],
+        outputs: [{ name: '', type: 'bool' }],
+    },
+];
+/**
+ * `ReceptorMock.recordFor(address, uint64)` from @gatedpath/receptor-mock. The mock is the
+ * only verifier in the kit that can say when a credential expires; real verifiers answer a plain
+ * boolean. Used by `receptorMockExpiry` for testnet and fork demos only.
+ */
+export const receptorMockAbi = [
+    {
+        type: 'function',
+        name: 'recordFor',
+        stateMutability: 'view',
+        inputs: [
+            { name: 'wallet', type: 'address' },
+            { name: 'requestId', type: 'uint64' },
+        ],
+        outputs: [
+            {
+                name: '',
+                type: 'tuple',
+                components: [
+                    { name: 'isSet', type: 'bool' },
+                    { name: 'status', type: 'uint8' },
+                    { name: 'expiresAt', type: 'uint64' },
+                ],
+            },
+        ],
+    },
+];
+/**
+ * The two `ReceptorMock` functions the dev state panel uses on a local Anvil (chain 31337):
+ * `setStatus(wallet, requestId, status)` writes a state, `eligibilityStatus(wallet, requestId)`
+ * reads it back. Never called against 151 or 153; the panel refuses to render there.
+ */
+export const receptorMockStatusAbi = [
+    {
+        type: 'function',
+        name: 'setStatus',
+        stateMutability: 'nonpayable',
+        inputs: [
+            { name: 'wallet', type: 'address' },
+            { name: 'requestId', type: 'uint64' },
+            { name: 'status', type: 'uint8' },
+        ],
+        outputs: [],
+    },
+    {
+        type: 'function',
+        name: 'eligibilityStatus',
+        stateMutability: 'view',
+        inputs: [
+            { name: 'wallet', type: 'address' },
+            { name: 'requestId', type: 'uint64' },
+        ],
+        outputs: [{ name: '', type: 'uint8' }],
+    },
+];

package/dist/components.d.ts

@@ -0,0 +1,70 @@
+import type { ReactNode } from 'react';
+import type { Address, EligibilityResult, EligibilityState } from './useEligibility.js';
+export interface StateProps {
+    className?: string;
+    children?: ReactNode;
+}
+/** State 1: nothing is connected. */
+export declare function NotConnected({ className, children }: StateProps): import("react/jsx-runtime").JSX.Element;
+export interface NotVerifiedProps extends StateProps {
+    address: Address;
+    /** Human name of the chain, for the sentence. */
+    chainName?: string;
+    /** True on chain 153: shows the faucet link. */
+    testnet?: boolean;
+}
+/** State 2: connected, but `permission.isAllowed` is false. The wallet cannot transact at all. */
+export declare function NotVerified({ address, chainName, testnet, className, children }: NotVerifiedProps): import("react/jsx-runtime").JSX.Element;
+export interface IneligibleProps extends StateProps {
+    /** What the action needs, in plain words: "an Australian proof of address", "an over-18 credential". */
+    requirement?: string;
+}
+/** State 3: verified on the network, but the verifier says no for this action. */
+export declare function Ineligible({ requirement, className, children }: IneligibleProps): import("react/jsx-runtime").JSX.Element;
+/** State 4: eligible. Usually wraps the action button. */
+export declare function Eligible({ className, children }: StateProps): import("react/jsx-runtime").JSX.Element;
+export interface ExpiringSoonProps extends StateProps {
+    expiresAt: number;
+    secondsToExpiry: number;
+}
+/** State 5: eligible, and the verifier says the credential expires soon. Wraps the action too. */
+export declare function ExpiringSoon({ expiresAt, secondsToExpiry, className, children }: ExpiringSoonProps): import("react/jsx-runtime").JSX.Element;
+/** Shown while both reads are in flight for the first time. */
+export declare function Checking({ className, children }: StateProps): import("react/jsx-runtime").JSX.Element;
+export interface EligibilityErrorProps extends StateProps {
+    error: Error | null;
+    onRetry?: () => void;
+}
+/** An RPC or contract read failed and nothing is cached. Says so; does not guess. */
+export declare function EligibilityError({ error, onRetry, className, children }: EligibilityErrorProps): import("react/jsx-runtime").JSX.Element;
+export interface EligibilityGateProps {
+    /** The result of `useEligibility`. */
+    eligibility: EligibilityResult;
+    address: Address | undefined;
+    chainName?: string;
+    testnet?: boolean;
+    requirement?: string;
+    className?: string;
+    /** Rendered inside the eligible and expiring states: the action itself. */
+    children?: ReactNode;
+    /** Override any state with your own markup. A function receives the hook result. */
+    render?: Partial<Record<EligibilityState, ReactNode | ((r: EligibilityResult) => ReactNode)>>;
+}
+/** One component that picks the state component for you. Bring your own action as `children`. */
+export declare function EligibilityGate({ eligibility, address, chainName, testnet, requirement, className, children, render }: EligibilityGateProps): import("react/jsx-runtime").JSX.Element;
+export interface LastCheckedProps {
+    eligibility: EligibilityResult;
+    className?: string;
+}
+/** "Last checked" line with a refresh button. Put it under any gate. */
+export declare function LastChecked({ eligibility, className }: LastCheckedProps): import("react/jsx-runtime").JSX.Element;
+export interface GasWarningProps {
+    /** A live USD figure for a plain transfer, from `gasCostUsd` in @gatedpath/chains, if you have one. */
+    transferUsd?: string | null;
+    className?: string;
+}
+/**
+ * The wallet gas warning from Vine, which every Redbelly dApp should show near its first
+ * transaction. See docs/wallet-gas-warning.md for the source and the reasoning.
+ */
+export declare function GasWarning({ transferUsd, className }: GasWarningProps): import("react/jsx-runtime").JSX.Element;

package/dist/components.js

@@ -0,0 +1,85 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { ACCESS_URL, FAUCET_URL, VINE_FEES_URL, VINE_INTERACTION_URL } from './urls.js';
+function cx(...parts) {
+    return parts.filter(Boolean).join(' ');
+}
+function short(address) {
+    return `${address.slice(0, 6)}…${address.slice(-4)}`;
+}
+/** State 1: nothing is connected. */
+export function NotConnected({ className, children }) {
+    return (_jsxs("div", { className: cx('rb-elig', 'rb-elig-disconnected', className), role: "status", children: [_jsx("p", { className: "rb-elig-title", children: "Connect a wallet" }), _jsx("p", { className: "rb-elig-body", children: children ?? 'Redbelly checks identity per wallet, so the app needs a wallet before it can tell you anything.' })] }));
+}
+/** State 2: connected, but `permission.isAllowed` is false. The wallet cannot transact at all. */
+export function NotVerified({ address, chainName = 'this network', testnet = false, className, children }) {
+    return (_jsxs("div", { className: cx('rb-elig', 'rb-elig-unverified', className), role: "status", children: [_jsx("p", { className: "rb-elig-title", children: "Verify your wallet" }), _jsxs("p", { className: "rb-elig-body", children: [_jsx("code", { children: short(address) }), " is not yet allowed to transact on ", chainName, ". Redbelly gates every wallet behind a one-time identity check; this app never sees your documents, only a true or false from the network."] }), _jsxs("ol", { className: "rb-elig-steps", children: [_jsxs("li", { children: ["Open", ' ', _jsx("a", { href: ACCESS_URL, target: "_blank", rel: "noreferrer", children: ACCESS_URL }), ' ', "with this same wallet and complete verification."] }), testnet && (_jsxs("li", { children: ["Get testnet RBNT from", ' ', _jsx("a", { href: FAUCET_URL, target: "_blank", rel: "noreferrer", children: "FAUCETME" }), ' ', "so you can pay gas."] })), _jsx("li", { children: "Come back here. This page re-checks on every new block and moves on by itself." })] }), _jsx("p", { className: "rb-elig-muted", children: children ?? "Don't switch to another wallet to get past this: the credential belongs to the wallet that was verified." })] }));
+}
+/** State 3: verified on the network, but the verifier says no for this action. */
+export function Ineligible({ requirement, className, children }) {
+    return (_jsxs("div", { className: cx('rb-elig', 'rb-elig-ineligible', className), role: "status", children: [_jsx("p", { className: "rb-elig-title", children: "Not eligible for this action" }), _jsx("p", { className: "rb-elig-body", children: children ??
+                    `Your wallet is verified on the network, but it does not hold an accepted proof for this action${requirement ? ` (${requirement})` : ''}. The contract would refuse the transaction, so the button stays off.` }), _jsx("p", { className: "rb-elig-muted", children: "The check is on-chain and the answer is a plain yes or no; the app cannot tell whether a credential is missing, expired or revoked. Your identity wallet can." })] }));
+}
+/** State 4: eligible. Usually wraps the action button. */
+export function Eligible({ className, children }) {
+    return (_jsxs("div", { className: cx('rb-elig', 'rb-elig-eligible', className), role: "status", children: [_jsx("p", { className: "rb-elig-title", children: "Eligible" }), children] }));
+}
+function humanDuration(seconds) {
+    if (seconds <= 0)
+        return 'now';
+    const days = Math.floor(seconds / 86_400);
+    if (days >= 2)
+        return `${days} days`;
+    const hours = Math.floor(seconds / 3600);
+    if (hours >= 2)
+        return `${hours} hours`;
+    const minutes = Math.max(1, Math.floor(seconds / 60));
+    return `${minutes} minutes`;
+}
+/** State 5: eligible, and the verifier says the credential expires soon. Wraps the action too. */
+export function ExpiringSoon({ expiresAt, secondsToExpiry, className, children }) {
+    const when = new Date(expiresAt * 1000);
+    return (_jsxs("div", { className: cx('rb-elig', 'rb-elig-expiring', className), role: "status", children: [_jsxs("p", { className: "rb-elig-title", children: ["Eligible, credential expires in ", humanDuration(secondsToExpiry)] }), _jsxs("p", { className: "rb-elig-body", children: ["After ", _jsx("time", { dateTime: when.toISOString(), children: when.toUTCString() }), " this wallet will be refused until the credential is renewed. Renew it in your identity wallet before then; a transaction sent after expiry reverts."] }), children] }));
+}
+/** Shown while both reads are in flight for the first time. */
+export function Checking({ className, children }) {
+    return (_jsx("div", { className: cx('rb-elig', 'rb-elig-checking', className), role: "status", "aria-busy": "true", children: _jsx("p", { className: "rb-elig-body", children: children ?? 'Checking the network and the verifier…' }) }));
+}
+/** An RPC or contract read failed and nothing is cached. Says so; does not guess. */
+export function EligibilityError({ error, onRetry, className, children }) {
+    return (_jsxs("div", { className: cx('rb-elig', 'rb-elig-error', className), role: "alert", children: [_jsx("p", { className: "rb-elig-title", children: "Could not check eligibility" }), _jsx("p", { className: "rb-elig-body", children: children ?? (error?.message ?? 'The RPC did not answer.') }), onRetry && (_jsx("button", { type: "button", className: "rb-elig-button", onClick: onRetry, children: "Try again" }))] }));
+}
+/** One component that picks the state component for you. Bring your own action as `children`. */
+export function EligibilityGate({ eligibility, address, chainName, testnet, requirement, className, children, render }) {
+    const custom = render?.[eligibility.state];
+    if (custom !== undefined)
+        return _jsx(_Fragment, { children: typeof custom === 'function' ? custom(eligibility) : custom });
+    switch (eligibility.state) {
+        case 'disconnected':
+            return _jsx(NotConnected, { className: className });
+        case 'checking':
+            return _jsx(Checking, { className: className });
+        case 'unverified':
+            return _jsx(NotVerified, { address: address, chainName: chainName, testnet: testnet, className: className });
+        case 'ineligible':
+            return _jsx(Ineligible, { requirement: requirement, className: className });
+        case 'expiring':
+            return (_jsx(ExpiringSoon, { expiresAt: eligibility.expiresAt, secondsToExpiry: eligibility.secondsToExpiry, className: className, children: children }));
+        case 'eligible':
+            return _jsx(Eligible, { className: className, children: children });
+        case 'error':
+            return _jsx(EligibilityError, { error: eligibility.error, onRetry: () => void eligibility.refresh(), className: className });
+    }
+}
+/** "Last checked" line with a refresh button. Put it under any gate. */
+export function LastChecked({ eligibility, className }) {
+    const at = eligibility.lastCheckedAt;
+    return (_jsxs("p", { className: cx('rb-elig-last-checked', className), children: [at ? (_jsxs(_Fragment, { children: ["Last checked ", _jsx("time", { dateTime: new Date(at).toISOString(), children: new Date(at).toLocaleTimeString() }), eligibility.blockNumber !== undefined ? ` at block ${eligibility.blockNumber.toString()}` : ''] })) : ('Not checked yet'), _jsx("button", { type: "button", className: "rb-elig-button rb-elig-button-small", onClick: () => void eligibility.refresh(), disabled: eligibility.isFetching, children: eligibility.isFetching ? 'Checking…' : 'Refresh' })] }));
+}
+/**
+ * The wallet gas warning from Vine, which every Redbelly dApp should show near its first
+ * transaction. See docs/wallet-gas-warning.md for the source and the reasoning.
+ */
+export function GasWarning({ transferUsd, className }) {
+    return (_jsxs("p", { className: cx('rb-elig-gas', className), children: ["Gas on Redbelly is priced in US dollars and paid in RBNT", transferUsd ? `; a plain transfer costs about US$${transferUsd} right now` : '', ". Redbelly warns that most wallets show gas information wrongly on this network, so trust the figure here over the wallet's, and read", ' ', _jsx("a", { href: VINE_INTERACTION_URL, target: "_blank", rel: "noreferrer", children: "Vine's note" }), ' ', "and", ' ', _jsx("a", { href: VINE_FEES_URL, target: "_blank", rel: "noreferrer", children: "how fees work" }), "."] }));
+}

package/dist/dev/DevStatePanel.d.ts

@@ -0,0 +1,19 @@
+import { type LocalDeployment } from './localDeployment.js';
+export interface DevStatePanelProps {
+    /** The parsed `deployments/local.json`; see `parseLocalDeployment`. */
+    deployment: LocalDeployment;
+    className?: string;
+}
+/**
+ * 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 declare function DevStatePanel({ deployment, className }: DevStatePanelProps): import("react/jsx-runtime").JSX.Element | null;