@solvapay/react 2.1.1 → 2.2.0-preview-e3e546693c002c32f128d83bf6c5fe76ac182a79

package/dist/mcp/index.d.cts

@@ -1,9 +1,10 @@
-import { v as SolvaPayTransport, _ as SolvaPayProviderInitial, z as SolvaPayConfig, D as BootstrapPlanLike, H as Merchant } from '../shared-D0hmT1qU.cjs';
+import { w as SolvaPayTransport, a1 as SolvaPayProviderInitial, D as SolvaPayConfig, B as BootstrapPlanLike, y as PurchaseInfo, a2 as CreditActivityType, a3 as CreditActivityEntry, H as Merchant } from '../useUsage-CTgRBvFK.cjs';
 import { TOOL_FOR_VIEW, SolvaPayMcpViewKind, BootstrapMerchant, BootstrapProduct, BootstrapPlan, BootstrapCustomer } from '@solvapay/mcp-core';
 export { MCP_TOOL_NAMES, McpToolName } from '@solvapay/mcp-core';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
-import { PricingOptionLike } from '@solvapay/core';
+import { PricingOptionLike, PricedLike, BalancePegLike } from '@solvapay/core';
+import { U as UsageMeterRootProps } from '../UsageMeter-rga6cyfB.cjs';
 import '@stripe/stripe-js';
 import '../adapters/auth.cjs';
 
@@ -64,12 +65,20 @@ declare function createMcpAppAdapter(app: McpAppLike): SolvaPayTransport;
 
 /**
  * Probe whether `@stripe/stripe-js` can mount inside the current MCP host
- * sandbox. Compliant hosts (basic-host, ChatGPT, MCPJam) honour the
- * declared `_meta.ui.csp.frameDomains` and Stripe loads normally;
- * non-compliant hosts (Claude today — see anthropics/claude-ai-mcp#40)
+ * sandbox. Hosts that deliver the declared `_meta.ui.csp.frameDomains` to
+ * the widget document (basic-host, ChatGPT) let Stripe load normally.
+ * Reading `frameDomains` is not the same as the emitted policy surviving
+ * to the guest document — MCPJam currently reports a runtime mismatch
+ * between its effective CSP model and the browser's enforced policy.
+ * Non-compliant hosts (Claude today — see anthropics/claude-ai-mcp#40)
  * hardcode `frame-src 'self' blob: data:` and the nested Stripe iframes
  * are refused even though the parent script loads fine.
  *
+ * A second, harder constraint: sandbox flags are inherited by descendant
+ * frames. A chain missing `allow-same-origin` cannot host Stripe at all
+ * regardless of `frame-src` — Stripe's own inner iframe fails its
+ * `script-src 'self'` when the ancestor omits it.
+ *
  * ## Why `ready` alone is a lie on Claude
  *
  * Stripe's `PaymentElement` fires its `ready` event as soon as the
@@ -178,6 +187,25 @@ interface McpBridgeAppLike {
             text: string;
         }>;
     }) => Promise<unknown> | void;
+    /**
+     * `ui/open-link` — ask the host to open a URL in the user's browser.
+     * On hosts whose iframe sandbox omits `allow-popups` (Claude) this is
+     * the only way out of the frame: `<a target="_blank">` and
+     * `window.open()` are both dropped there without an error.
+     */
+    openLink?: (params: {
+        url: string;
+    }) => Promise<{
+        isError?: boolean;
+    } | undefined>;
+    /**
+     * Host capabilities resolved during `connect()`. `openLinks` gates
+     * `openLink` — a host can expose the method without declaring
+     * support, and calling it blind would swallow the click.
+     */
+    getHostCapabilities?: () => {
+        openLinks?: unknown;
+    } | undefined;
 }
 interface NotifyModelContextParams {
     /** Short, plain-text update ("User selected Pro"). */
@@ -351,11 +379,10 @@ declare function isTransportToolName(name: string): boolean;
  * Classification of the host-invoked tool that opened the widget iframe.
  * Drives `<McpApp>`'s mount branching:
  *
- *  - `intent`  — one of `upgrade` / `manage_account` / `topup`. Call
- *                the corresponding tool via `fetchMcpBootstrap`.
+ *  - `intent`  — the `account` viewer. Call it via `fetchMcpBootstrap`.
  *  - `other`   — no tool info, or a SolvaPay transport tool as the
- *                iframe entry point (rare). Fall back to the `upgrade`
- *                intent tool for a fresh snapshot.
+ *                iframe entry point (rare). Fall back to the `account`
+ *                viewer for a fresh snapshot.
  *
  * The previous `data` kind was removed with the text-only paywall
  * refactor: payable merchant tools no longer advertise
@@ -363,7 +390,7 @@ declare function isTransportToolName(name: string): boolean;
  * silent success or a paywall response. If one of those ever fires
  * anyway (a legacy opt-in server), the classification falls through
  * to `other` and the shell asks `fetchMcpBootstrap` for a clean
- * `upgrade` snapshot.
+ * `account` snapshot.
  */
 type HostEntryClassification = {
     kind: 'intent';
@@ -503,14 +530,15 @@ declare function waitForInitialToolResult(app: McpAppBootstrapLike & AppToolResu
 
 /**
  * Seed the module-level hook caches (`merchantCache`, `productCache`,
- * `plansCache`, `paymentMethodCache`) from a `SolvaPayProviderInitial`
- * snapshot so the MCP App shell never fires a first-mount fetch.
+ * `plansCache`, `paymentMethodCache`, `limitsCache`) from a
+ * `SolvaPayProviderInitial` snapshot so the MCP App shell never fires a
+ * first-mount fetch.
  *
  * Called from `<McpApp>` before rendering `<SolvaPayProvider>`. The
- * seeded entries share the same 5-minute TTL as normal fetches — once
- * expired the caches fall back to their existing behaviour (which, for
- * MCP, returns the seeded value because the hooks' fetchers become
- * no-ops after the read tools are dropped).
+ * seeded entries share the same TTL as normal fetches — once expired
+ * the caches fall back to their existing behaviour (which, for MCP,
+ * returns the seeded value because the hooks' fetchers become no-ops
+ * after the read tools are dropped).
  */
 
 /**
@@ -523,6 +551,131 @@ declare function waitForInitialToolResult(app: McpAppBootstrapLike & AppToolResu
  */
 declare function seedMcpCaches(initial: SolvaPayProviderInitial, config: SolvaPayConfig): void;
 
+/**
+ * Pure derivation helpers that map a plan / active purchase onto the
+ * activation strategy + action-affordance shape the shell renders per
+ * plan type.
+ *
+ * Keeping these in a standalone module lets the hosted manage page
+ * share the same matrix as the MCP shell — "one plan-shape matrix,
+ * two surfaces" — and makes the 4 × 2 × 3 test matrix from the plan a
+ * pure-function target (no RTL needed).
+ *
+ * The shape is derived from the wire's `options[]` through the
+ * `@solvapay/core` readers. These helpers previously keyed off
+ * `planType`, `meterRef`, `meterId`, and `limit`, none of which the
+ * backend sends: every plan fell through to the unknown branch, so a
+ * pay-as-you-go plan (which has no headline `price`) resolved to
+ * `'free'` and metered subscriptions were indistinguishable from
+ * unlimited ones.
+ */
+
+type PlanShape = 'free' | 'trial' | 'usage-based' | 'recurring-unlimited' | 'recurring-metered';
+/**
+ * Strategy the Plan tab uses when the user clicks a plan card:
+ *  - `activate` — free / trial / free-priced recurring: instant activation
+ *    via `ActivationFlow.Summary` + `ActivateButton`.
+ *  - `topup-first` — usage-based: ActivationFlow's `AmountPicker`
+ *    branch.
+ *  - `paid-checkout` — recurring with a non-zero price: mount
+ *    `PaymentFormGate` + `PaymentForm.*` for inline Stripe Elements.
+ */
+type ActivationStrategy = 'activate' | 'topup-first' | 'paid-checkout';
+/**
+ * The subset of a plan — or of the plan snapshot frozen onto a purchase
+ * — that the shape derivation reads. A plan carries `requiresPayment`;
+ * a snapshot may not. Usage-counting and the rest come out of `options[]`.
+ */
+interface PlanLike {
+    /** Catalog / snapshot identifier used to match a purchase back to a live plan. */
+    reference?: string | null;
+    /** Display name. Catalog plans carry it; thin snapshots may not. */
+    name?: string | null;
+    /** Backend-derived pricing label, e.g. `'usage-based'` or `'hybrid'`. */
+    type?: string | null;
+    /** Composable pricing options: charges, billing cycle, limit, trial. */
+    options?: PricingOptionLike[] | null;
+    /** `false` marks a free plan. Only present on a plan, not a snapshot. */
+    requiresPayment?: boolean | null;
+    /** Derived headline amount; only a fallback for snapshots frozen before `options[]`. */
+    price?: number | null;
+    currency?: string | null;
+    /** Frozen on snapshots; usage-based when `options[]` is missing. */
+    isMetered?: boolean | null;
+}
+interface PurchaseSnapshotLike {
+    planSnapshot?: PlanLike | null;
+    /** Whether the customer has a payment method on file. */
+    hasPaymentMethod?: boolean;
+}
+/**
+ * Map a `BootstrapPlan` / `PlanSnapshot` to its concrete shape. The
+ * shapes are distinct in UX: each drives a different summary string, a
+ * different set of CTAs, and a different activity-strip variant.
+ *
+ * A billing cycle is what separates a subscription from a one-off, and
+ * metering is what separates capped from unlimited. A paid plan with
+ * neither is a one-time purchase, which this matrix has no member for
+ * and folds into `'recurring-unlimited'` — the same bucket it landed in
+ * before, and the one that routes it to paid checkout.
+ */
+declare function resolvePlanShape(plan: PlanLike | null | undefined): PlanShape | null;
+/**
+ * Pick the activation strategy for a plan the user just clicked.
+ *
+ * Free and trial plans activate instantly, usage-based always tops up
+ * first, and everything else goes to Stripe checkout. A zero-priced
+ * plan needs no separate branch: it resolves to `'free'`, because
+ * charging nothing is what makes a plan free.
+ */
+declare function resolveActivationStrategy(plan: PlanLike | null | undefined): ActivationStrategy;
+/**
+ * Per-variant action flags for the Plan-active card. Only flags that
+ * are `true` render affordances — this collapses the "should we show
+ * Cancel?" boolean maze into a single resolver call.
+ *
+ * Rules from the plan:
+ *  - `topUp` — only on usage-based purchases.
+ *  - `cancel` — recurring (paid subscription) and free plans. PAYG
+ *    has no renewal to cancel.
+ *  - `changePlan` — always, when the product exposes more than one
+ *    plan.
+ *  - `managePortal` — only when the customer has a payment method on
+ *    file. Free plans that never charged a card skip this.
+ *  - `upgrade` — shown *instead of* `changePlan` when the active plan
+ *    is free AND at least one paid plan exists.
+ */
+interface PlanActions {
+    topUp: boolean;
+    cancel: boolean;
+    changePlan: boolean;
+    managePortal: boolean;
+    upgrade: boolean;
+}
+interface PlanActionsInput {
+    purchase: PurchaseSnapshotLike | null | undefined;
+    /** Total plans exposed on the product. */
+    planCount: number;
+    /** Number of paid plans (price > 0, not free) on the product. */
+    paidPlanCount: number;
+}
+/**
+ * Overlay a live catalog plan onto a (possibly thin) purchase snapshot.
+ * Snapshots frozen without `options[]` collapse PAYG to `{ price: 0 }`,
+ * which `resolvePlanShape` reads as `'free'`. Prefer the snapshot's
+ * `options[]` when present; otherwise take them from the catalog match.
+ */
+declare function mergePlanSnapshot(snapshot: PlanLike | null | undefined, catalog: PlanLike | null | undefined): PlanLike | null;
+declare function findCatalogPlan(plans: readonly PlanLike[] | undefined, snapshot: PlanLike | null | undefined, planRef?: string | null): PlanLike | undefined;
+declare function resolvePlanActions({ purchase, planCount, paidPlanCount, }: PlanActionsInput): PlanActions;
+/**
+ * "Your activity" strip variant shown at the top of a surface when a
+ * returning customer has an active purchase. Hidden when the customer
+ * has no active purchase.
+ */
+type ActivityStripKind = 'none' | 'payg-balance' | 'recurring-unlimited-renew' | 'recurring-metered-usage' | 'free-usage';
+declare function resolveActivityStrip(purchase: PurchaseSnapshotLike | null | undefined): ActivityStripKind;
+
 /**
  * Per-element className overrides for `<Mcp*View>` primitives.
  *
@@ -538,8 +691,16 @@ interface McpViewClassNames {
     muted?: string;
     button?: string;
     linkButton?: string;
+    /**
+     * @deprecated Prefer composing the hosted notice primitives.
+     * Slot retained for integrator overrides that still target it.
+     */
     notice?: string;
     error?: string;
+    /**
+     * @deprecated Awaiting-payment chrome is an internal checkout state.
+     * Slot retained for integrator overrides that still target it.
+     */
     awaitingHeader?: string;
     balanceRow?: string;
     amountPicker?: string;
@@ -553,6 +714,10 @@ interface McpViewClassNames {
     businessToggle?: string;
     businessField?: string;
     taxSummary?: string;
+    /**
+     * @deprecated Activation is no longer a standalone view.
+     * Slot retained for integrator overrides that still target it.
+     */
     activationFlow?: string;
     /** Root wrapper of `<AppHeader>` (icon + merchant name row). */
     appHeader?: string;
@@ -592,31 +757,42 @@ declare function resolveMcpClassNames(overrides: McpViewClassNames | undefined):
 
 interface McpAccountViewProps {
     /**
-     * @deprecated Product context is not rendered in the account surface.
-     * Kept for integrators who pass `bootstrap.product` through custom views.
+     * Invoked product. Used as the identity header on credit and allowance
+     * states.
      */
     product?: Pick<BootstrapProduct, 'name' | 'description'> | null;
+    /** Scopes active products and `useLimits` to this invocation. */
+    productRef?: string;
     classNames?: McpViewClassNames;
     /**
-     * Called when the user clicks the "Top up" link inside the
-     * pay-as-you-go credit card or the Customer details card.
-     * `<McpAppShell>` wires this to a tab switch so nothing re-mounts.
+     * Called when the user clicks "Add funds". `<McpAppShell>`
+     * wires this to a surface swap so nothing re-mounts.
      */
     onTopup?: () => void;
     /**
-     * Called when the user clicks "Pick a plan" from the empty state or
-     * "See plans" on the pay-as-you-go state. Wired by the shell to
-     * switch to the checkout surface.
+     * Called when the user clicks "Turn on" or "Manage" on the
+     * auto-recharge row. Wired by the shell to the dedicated view.
      */
-    onChangePlan?: () => void;
+    onAutoRecharge?: () => void;
     /**
-     * Skip the Customer + Seller detail cards. `<McpAppShell>` sets this
-     * when it mounts the persistent right-hand sidebar (whenever
-     * `bootstrap.customer` is set) so the cards are not duplicated.
+     * Called when the user clicks "Pick a plan" or Change plan.
+     * Wired by the shell to switch to checkout.
      */
-    hideDetailCards?: boolean;
+    onChangePlan?: (planRef?: string) => void;
+    /**
+     * Product catalog used to decide Upgrade vs Change plan. The shell
+     * passes `bootstrap.plans`.
+     */
+    plans?: readonly PlanLike[];
+}
+declare function McpAccountView({ product, productRef, classNames, onTopup, onAutoRecharge, onChangePlan, plans, }: McpAccountViewProps): react_jsx_runtime.JSX.Element;
+
+interface McpAutoRechargeViewProps {
+    classNames?: McpViewClassNames;
+    /** Wired by the shell to return to the account surface. */
+    onBack?: () => void;
 }
-declare function McpAccountView({ classNames, onTopup, onChangePlan, hideDetailCards, }: McpAccountViewProps): react_jsx_runtime.JSX.Element;
+declare function McpAutoRechargeView({ classNames, onBack }: McpAutoRechargeViewProps): react_jsx_runtime.JSX.Element;
 
 interface McpCheckoutViewProps {
     productRef: string;
@@ -658,10 +834,21 @@ interface McpCheckoutViewProps {
      * surface routing.
      */
     onBack?: () => void;
+    /**
+     * Pre-select this plan and, with `autoAdvance`, skip the plan step
+     * by running `flow.advance()` once the selector has that plan.
+     */
+    initialPlanRef?: string;
+    /**
+     * When set with `initialPlanRef`, fire the plan-step Continue path
+     * automatically so a ladder Switch/Activate lands on amount or
+     * payment — not a second plan picker.
+     */
+    autoAdvance?: boolean;
     classNames?: McpViewClassNames;
     children?: React.ReactNode;
 }
-declare function McpCheckoutView({ productRef, publishableKey, returnUrl, onPurchaseSuccess, onRequestTopup: _onRequestTopup, fromPaywall, paywallKind, plans, onClose, onBack, classNames, children, }: McpCheckoutViewProps): react_jsx_runtime.JSX.Element;
+declare function McpCheckoutView({ productRef, publishableKey, returnUrl, onPurchaseSuccess, onRequestTopup: _onRequestTopup, fromPaywall, paywallKind, plans, onClose, onBack, initialPlanRef, autoAdvance, classNames, children, }: McpCheckoutViewProps): react_jsx_runtime.JSX.Element;
 
 interface McpTopupViewProps {
     /** Public SDK contract — null means "no key supplied". Normalized internally. */
@@ -694,9 +881,10 @@ declare function McpTopupView({ publishableKey, returnUrl, onTopupSuccess, onBac
  * The `paywall` / `nudge` kinds were removed as part of the text-only
  * paywall refactor: merchant paywall / nudge responses are plain text
  * narrations now, not widget surfaces. The iframe is only mounted for
- * the three deliberate intent tools.
+ * the `account` viewer (slash prompts remap onto it with a `view`).
  */
-type McpViewKind = 'checkout' | 'account' | 'topup';
+
+type McpViewKind = SolvaPayMcpViewKind;
 /**
  * @deprecated Use `McpViewKind`. This alias exists for one minor
  * version to give internal callers a grace window on the rename; the
@@ -734,15 +922,21 @@ interface McpViewRouterProps {
     bootstrap: McpBootstrap;
     views?: McpAppViewOverrides;
     classNames?: McpViewClassNames;
-    /** Whether the shell already renders the customer/seller cards in a sidebar. */
-    suppressDetailCards?: boolean;
     /**
      * Called when a surface asks to swap to another surface in-session
-     * (account → topup via the details card, account → checkout via
+     * (account → topup via the credits CTA, account → checkout via
      * "Change plan", topup → account via "Back"). The shell wires this
      * to its `overrideView` state.
      */
-    onSurfaceChange?: (next: McpViewKind) => void;
+    onSurfaceChange?: (next: McpViewKind, intent?: {
+        planRef?: string;
+    }) => void;
+    /**
+     * Plan the account ladder asked checkout to open on. The shell
+     * forwards it as `initialPlanRef` + `autoAdvance` so the plan step
+     * is skipped.
+     */
+    overridePlanRef?: string;
     /**
      * Optional bootstrap re-fetcher. The shell triggers it once on mount
      * so a customer who re-opens a backgrounded iframe sees fresh
@@ -761,7 +955,7 @@ interface McpViewRouterProps {
  * Exported so integrators that own their own shell + provider mount
  * can still get view dispatch for free.
  */
-declare function McpViewRouter({ view, bootstrap, views, classNames, suppressDetailCards, onSurfaceChange, onRefreshBootstrap, onClose, }: McpViewRouterProps): React.ReactNode;
+declare function McpViewRouter({ view, bootstrap, views, classNames, onSurfaceChange, overridePlanRef, onRefreshBootstrap, onClose, }: McpViewRouterProps): React.ReactNode;
 
 /**
  * Minimal host-context shape `<McpApp>` reads. Kept loose so the real
@@ -816,6 +1010,7 @@ interface McpAppViewOverrides {
     checkout?: React.ComponentType<McpCheckoutViewProps>;
     account?: React.ComponentType<McpAccountViewProps>;
     topup?: React.ComponentType<McpTopupViewProps>;
+    autoRecharge?: React.ComponentType<McpAutoRechargeViewProps>;
 }
 interface McpAppProps {
     app: McpAppFull;
@@ -865,114 +1060,195 @@ interface McpAppProps {
 }
 declare function McpApp({ app, productRef: productRefOverride, views, classNames, footer, onInitError, applyContext, onClose, messageOnSuccess, }: McpAppProps): react_jsx_runtime.JSX.Element;
 
+interface ActiveProduct {
+    reference: string;
+    productName: string;
+    productRef: string | null;
+    planName: string | null;
+    planRef: string | null;
+    since: string | null;
+    isMetered: boolean;
+    amount: number;
+    currency: string;
+}
+declare function deriveActiveProducts(purchases: readonly PurchaseInfo[] | undefined, productRef?: string | null): ActiveProduct[];
+declare function formatSince(iso: string | null, locale: string): string | null;
+declare function formatProductTerms(product: ActiveProduct, locale: string, extras?: {
+    rate?: string | null;
+}): string;
+declare function formatAllowanceTerms(product: ActiveProduct, locale: string, extras?: {
+    price?: string | null;
+    renewsOn?: string | null;
+    started?: boolean;
+    qualifier?: 'one time' | null;
+}): string;
+
 /**
- * Pure derivation helpers that map a plan / active purchase onto the
- * activation strategy + action-affordance shape the shell renders per
- * plan type.
- *
- * Keeping these in a standalone module lets the hosted manage page
- * share the same matrix as the MCP shell — "one plan-shape matrix,
- * two surfaces" — and makes the 4 × 2 × 3 test matrix from the plan a
- * pure-function target (no RTL needed).
+ * Pure account-widget state machine + field resolvers.
  *
- * The shape is derived from the wire's `options[]` through the
- * `@solvapay/core` readers. These helpers previously keyed off
- * `planType`, `meterRef`, `meterId`, and `limit`, none of which the
- * backend sends: every plan fell through to the unknown branch, so a
- * pay-as-you-go plan (which has no headline `price`) resolved to
- * `'free'` and metered subscriptions were indistinguishable from
- * unlimited ones.
+ * `resolveAccountState()` maps bootstrap + limits onto the ten v3
+ * states (A–J). The six field resolvers pin renderings that would
+ * otherwise be re-decided per component. No React — same pattern as
+ * `plan-actions.ts`.
  */
 
-type PlanShape = 'free' | 'trial' | 'usage-based' | 'recurring-unlimited' | 'recurring-metered';
+declare const ACCOUNT_STATES: readonly ["A", "B", "C", "D", "E", "F", "G", "H", "I", "J"];
+type AccountState = (typeof ACCOUNT_STATES)[number];
+interface AccountLimitsLike {
+    remaining: number | null;
+    withinLimits: boolean | null;
+    activationRequired: boolean | null;
+    overage: boolean | null;
+    needsTopUp: boolean | null;
+    needsUpgrade: boolean | null;
+    throttled: boolean | null;
+}
+interface AccountPurchaseLike {
+    planSnapshot?: PlanLike | null;
+    cancelledAt?: string | null;
+    endDate?: string | null;
+    usage?: {
+        used?: number;
+        periodEnd?: string | null;
+    } | null;
+}
+interface AccountStateInput {
+    /** Bootstrap / limits still in flight — state G. */
+    loading?: boolean;
+    purchase: AccountPurchaseLike | null | undefined;
+    limits: AccountLimitsLike | null | undefined;
+    /**
+     * Pre-resolved shape. When omitted, derived from `purchase.planSnapshot`.
+     * Callers that have the live catalog should pass `resolvePlanShape(mergePlanSnapshot(...))`.
+     */
+    planShape?: PlanShape | null;
+    now?: Date;
+}
 /**
- * Strategy the Plan tab uses when the user clicks a plan card:
- *  - `activate` — free / trial / free-priced recurring: instant activation
- *    via `ActivationFlow.Summary` + `ActivateButton`.
- *  - `topup-first` — usage-based: ActivationFlow's `AmountPicker`
- *    branch.
- *  - `paid-checkout` — recurring with a non-zero price: mount
- *    `PaymentFormGate` + `PaymentForm.*` for inline Stripe Elements.
+ * Precedence (pinned in tests):
+ *   G loading
+ *   H `activationRequired` (outranks zero remaining → not F)
+ *   J `cancelledAt` + future `endDate` (outranks plan shape)
+ *   I `overage` (outranks `withinLimits` → not F)
+ *   D `needsTopUp` or a usage-based plan that is out of limits
+ *   F allowance plan at cap
+ *   B / C / E running plan-shape (`throttled` / `needsUpgrade` land here)
+ *   A no plan
  */
-type ActivationStrategy = 'activate' | 'topup-first' | 'paid-checkout';
+declare function resolveAccountState(input: AccountStateInput): AccountState;
+type RemainingDisplay = {
+    kind: 'unknown';
+    label: 'Not known yet';
+} | {
+    kind: 'unlimited';
+    label: 'Unlimited';
+} | {
+    kind: 'finite';
+    remaining: number;
+};
+declare function resolveRemaining(input: {
+    remaining: number | null | undefined;
+    /** Plan limit cap. `0` means unlimited (backend sentinel). */
+    cap?: number | null;
+    limitsResolved: boolean;
+}): RemainingDisplay;
+type MeterTone = 'ok' | 'warning' | 'critical';
 /**
- * The subset of a plan — or of the plan snapshot frozen onto a purchase
- * — that the shape derivation reads. A plan carries `requiresPayment`;
- * a snapshot may not. Usage-counting and the rest come out of `options[]`.
+ * Warning at 80% used **or** last remaining call (`remaining === 1` on a
+ * finite cap). Critical at 100%. E at 2 of 3 is the last-call case.
  */
-interface PlanLike {
-    /** Composable pricing options: charges, billing cycle, limit, trial. */
-    options?: PricingOptionLike[] | null;
-    /** `false` marks a free plan. Only present on a plan, not a snapshot. */
-    requiresPayment?: boolean | null;
-    /** Derived headline amount; only a fallback for snapshots frozen before `options[]`. */
-    price?: number | null;
-    currency?: string | null;
-}
-interface PurchaseSnapshotLike {
-    planSnapshot?: PlanLike | null;
-    /** Whether the customer has a payment method on file. */
-    hasPaymentMethod?: boolean;
+declare function resolveMeterTone(input: {
+    used: number;
+    remaining: number | null;
+    total: number | null;
+}): MeterTone;
+type RateDisplay = {
+    kind: 'none';
+    label: null;
+    showRunway: false;
+} | {
+    kind: 'unconvertible';
+    label: 'Rate confirmed at checkout';
+    showRunway: false;
+} | {
+    kind: 'flat';
+    creditsPerCall: number;
+    label: string;
+    showRunway: true;
+} | {
+    kind: 'tiered';
+    creditsPerCall: number;
+    label: string;
+    showRunway: true;
+};
+declare function resolveRateDisplay(plan: PricedLike | null | undefined, balance: BalancePegLike | null | undefined, meter?: string): RateDisplay;
+type PeriodDisplay = {
+    kind: 'none';
+    label: 'After your first call';
+} | {
+    kind: 'date';
+    periodEnd: string;
+};
+declare function resolvePeriodDisplay(periodEnd?: string | null): PeriodDisplay;
+interface OneTimeDisplay {
+    showRenews: boolean;
+    planQualifier: 'one time' | null;
 }
+declare function resolveOneTimeDisplay(plan: PricedLike | null | undefined): OneTimeDisplay;
 /**
- * Map a `BootstrapPlan` / `PlanSnapshot` to its concrete shape. The
- * shapes are distinct in UX: each drives a different summary string, a
- * different set of CTAs, and a different activity-strip variant.
- *
- * A billing cycle is what separates a subscription from a one-off, and
- * metering is what separates capped from unlimited. A paid plan with
- * neither is a one-time purchase, which this matrix has no member for
- * and folds into `'recurring-unlimited'` — the same bucket it landed in
- * before, and the one that routes it to paid checkout.
+ * The Sold-by strip is host chrome. No account state depends on it
+ * being visible — provenance rides on the plan line.
  */
-declare function resolvePlanShape(plan: PlanLike | null | undefined): PlanShape | null;
+declare function resolveMerchantStrip(): {
+    required: false;
+};
+declare function remainingCap(plan: PricedLike | null | undefined, meter?: string): number | null;
 /**
- * Pick the activation strategy for a plan the user just clicked.
- *
- * Free and trial plans activate instantly, usage-based always tops up
- * first, and everything else goes to Stripe checkout. A zero-priced
- * plan needs no separate branch: it resolves to `'free'`, because
- * charging nothing is what makes a plan free.
+ * Whole days from `now` until `iso`. Floor at 0 so a past reset never
+ * prints a negative caption. `null` when the date is unparseable.
  */
-declare function resolveActivationStrategy(plan: PlanLike | null | undefined): ActivationStrategy;
+declare function daysUntil(iso: string, now?: Date): number | null;
 /**
- * Per-variant action flags for the Plan-active card. Only flags that
- * are `true` render affordances — this collapses the "should we show
- * Cancel?" boolean maze into a single resolver call.
- *
- * Rules from the plan:
- *  - `topUp` — only on usage-based purchases.
- *  - `cancel` — recurring (paid subscription) and free plans. PAYG
- *    has no renewal to cancel.
- *  - `changePlan` — always, when the product exposes more than one
- *    plan.
- *  - `managePortal` — only when the customer has a payment method on
- *    file. Free plans that never charged a card skip this.
- *  - `upgrade` — shown *instead of* `changePlan` when the active plan
- *    is free AND at least one paid plan exists.
+ * Display noun for an allowance meter. The default `requests` meter
+ * reads as "calls" on this widget; any other meter keeps its name.
  */
-interface PlanActions {
-    topUp: boolean;
-    cancel: boolean;
-    changePlan: boolean;
-    managePortal: boolean;
-    upgrade: boolean;
-}
-interface PlanActionsInput {
-    purchase: PurchaseSnapshotLike | null | undefined;
-    /** Total plans exposed on the product. */
-    planCount: number;
-    /** Number of paid plans (price > 0, not free) on the product. */
-    paidPlanCount: number;
-}
-declare function resolvePlanActions({ purchase, planCount, paidPlanCount, }: PlanActionsInput): PlanActions;
+declare function allowanceMeterUnit(meter: string | null | undefined, count: number): string;
+
 /**
- * "Your activity" strip variant shown at the top of a surface when a
- * returning customer has an active purchase. Hidden when the customer
- * has no active purchase.
+ * A/F ladder copy — what happens at the limit, and whether a card is
+ * needed. Used on every ladder row in both inline and fullscreen.
  */
-type ActivityStripKind = 'none' | 'payg-balance' | 'recurring-unlimited-renew' | 'recurring-metered-usage' | 'free-usage';
-declare function resolveActivityStrip(purchase: PurchaseSnapshotLike | null | undefined): ActivityStripKind;
+
+declare function planConsequence(plan: PlanLike, locale: string, balance: BalancePegLike | null | undefined, extras?: {
+    merchantName?: string | null;
+}): string;
+
+/**
+ * Map `get_history` rows onto the designed fullscreen tables.
+ *
+ * Credit activity is account-wide (seven B2 fields → Event / When /
+ * Credits / Balance). Charges are product-scoped (Charge / Date /
+ * Amount). No receipt column.
+ */
+
+declare const CREDIT_ACTIVITY_TYPE_LABELS: Record<CreditActivityType, string>;
+declare function mapCreditActivityRow(entry: CreditActivityEntry, locale: string): {
+    title: string;
+    subtitle: string | null;
+    when: string;
+    credits: string;
+    balance: string;
+};
+declare function mapChargeRow(purchase: PurchaseInfo, locale: string): {
+    charge: string;
+    date: string;
+    amount: string;
+};
+declare function formatMerchantPlace(merchant: {
+    city?: string | null;
+    stateOrCounty?: string | null;
+}): string | null;
+declare function websiteHostLabel(url: string): string;
 
 interface BackLinkProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
     /** Visible label; typically `"Back to my account"` or `"Change amount"`. */
@@ -1078,39 +1354,242 @@ declare function McpHostInfoProvider({ hostName, children }: McpHostInfoProvider
  */
 declare function useHostName(): string | null;
 
-interface McpCustomerDetailsCardProps {
-    classNames?: McpViewClassNames;
-    /**
-     * When provided, a "Top up" text button is rendered next to the
-     * credit balance row. Typically wired to switch the active surface in
-     * the `<McpAppShell>` so the in-iframe navigation stays shell-local.
-     */
-    onTopup?: () => void;
-    /**
-     * Hides the credit balance row even when a non-zero balance is
-     * present. Useful on an unlimited-plan customer whose `balance` is
-     * populated but semantically meaningless.
-     */
-    hideBalance?: boolean;
+/**
+ * MCP Apps display-mode types and host-context readers.
+ *
+ * Display mode is host state, not routing: the host publishes
+ * `displayMode` / `availableDisplayModes` on `McpUiHostContext`.
+ * The host owns the expand affordance; the SDK reads and reacts.
+ * `@solvapay/react/mcp` does not import
+ * `@modelcontextprotocol/ext-apps` — these types are structural
+ * aliases of that package's `McpUiDisplayMode` /
+ * `McpUiAppCapabilities.availableDisplayModes`.
+ */
+declare const MCP_DISPLAY_MODES: readonly ["inline", "fullscreen", "pip"];
+type McpDisplayMode = (typeof MCP_DISPLAY_MODES)[number];
+interface McpSafeAreaInsets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+interface McpContainerDimensions {
+    width?: number;
+    height?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+}
+interface McpDisplayModeState {
+    displayMode: McpDisplayMode;
+    availableDisplayModes: readonly McpDisplayMode[];
+    containerDimensions?: McpContainerDimensions;
+    safeAreaInsets?: McpSafeAreaInsets;
 }
 /**
- * Customer details — name, email, customer reference (monospaced, the
- * value users paste into support tickets). The credit balance row is
- * only rendered when `balance > 0` to avoid a "0 credits" row on a
- * brand-new account.
+ * Capabilities the view advertises on `ui/initialize`. Pass as the
+ * second argument to `new App(info, capabilities)` so the host only
+ * offers modes this surface can handle. `pip` is excluded — account
+ * and checkout are not live sessions.
  */
-declare function McpCustomerDetailsCard({ classNames, onTopup, hideBalance, }: McpCustomerDetailsCardProps): react_jsx_runtime.JSX.Element;
-interface McpSellerDetailsCardProps {
-    classNames?: McpViewClassNames;
-    /** Render the "Verified seller" trust badge next to the heading. */
-    showVerifiedBadge?: boolean;
+declare const SOLVAPAY_MCP_APP_CAPABILITIES: {
+    availableDisplayModes: readonly ["inline", "fullscreen"];
+};
+declare const DEFAULT_DISPLAY_MODE_STATE: McpDisplayModeState;
+/** Host width at which fullscreen may use the 340px payment split. */
+declare const MCP_HOSTED_MIN_WIDTH = 1000;
+type McpHostedRail = 'hosted' | 'inline' | 'widget';
+/**
+ * Space the host says we have. Prefer the tighter of `width` and
+ * `maxWidth`.
+ */
+declare function hostWidthPx(dimensions: McpContainerDimensions | undefined): number | undefined;
+/**
+ * Which payment geometry to stamp on `data-rail`.
+ *
+ * - `inline` — widget; 260px split only at the 760px mcp query
+ * - `hosted` — fullscreen; 340px split at the 1000px `mcp-hosted` query
+ *
+ * Fullscreen always stamps `hosted`. Host-reported
+ * `containerDimensions` can be stale (MCPJam keeps a 720 template
+ * width on a `fixed inset-0` surface), so the JS width gate is not
+ * trusted. `@container mcp-hosted (min-width: 1000px)` owns the
+ * geometry from the measured width. Chrome (`displayMode`) stays
+ * fullscreen either way.
+ */
+declare function resolveHostedRail(state: Pick<McpDisplayModeState, 'displayMode'>): McpHostedRail;
+declare function isMcpDisplayMode(value: unknown): value is McpDisplayMode;
+/**
+ * Pull display-mode fields out of a host-context object. Unknown or
+ * missing values fall back to {@link DEFAULT_DISPLAY_MODE_STATE} —
+ * never invent a mode the host did not advertise.
+ */
+declare function readDisplayModeState(ctx: unknown): McpDisplayModeState;
+/**
+ * Host composer / device insets as root-container padding.
+ *
+ * Read `hostContext.safeAreaInsets`, not `env(safe-area-inset-*)` —
+ * inside a sandboxed iframe the env() values are the device's, and
+ * the host composer is what actually overlaps us. Zero when the host
+ * reports nothing; adding zero is harmless.
+ */
+declare function hostSafeAreaPadding(insets: McpSafeAreaInsets | undefined): {
+    paddingTop: number;
+    paddingRight: number;
+    paddingBottom: number;
+    paddingLeft: number;
+};
+
+interface McpDisplayModeProviderProps {
+    value: McpDisplayModeState;
+    children: React.ReactNode;
 }
+declare function McpDisplayModeProvider({ value, children }: McpDisplayModeProviderProps): react_jsx_runtime.JSX.Element;
+/** Current host display mode. Never throws; defaults to inline. */
+declare function useDisplayMode(): McpDisplayModeState;
+
+/**
+ * Payment-form identity caption. Renders `Paying as {email}` only —
+ * no merchant name, no middot join. Fullscreen stacks a muted label
+ * over the email; inline is a single muted span.
+ */
+
+interface McpPayingAsProps {
+    /** Override the signed-in customer email. */
+    email?: string | null;
+}
+declare function McpPayingAs({ email }: McpPayingAsProps): React.ReactElement | null;
+
+declare function Section({ title, children, className, }: {
+    title?: string;
+    children: React.ReactNode;
+    className?: string;
+}): React.ReactElement;
+declare function Eyebrow({ children, variant, className, }: {
+    children: React.ReactNode;
+    variant?: 'step' | 'rail';
+    className?: string;
+}): React.ReactElement;
+declare function LineItem({ label, value, muted, className, }: {
+    label: React.ReactNode;
+    value: React.ReactNode;
+    muted?: boolean;
+    className?: string;
+}): React.ReactElement;
+interface AmountLadderRow {
+    label: React.ReactNode;
+    value: React.ReactNode;
+    muted?: boolean;
+}
+declare function AmountLadder({ rows, className, }: {
+    rows: readonly AmountLadderRow[];
+    className?: string;
+}): React.ReactElement;
+declare function PresetTile({ amount, credits, selected, onClick, className, }: {
+    amount: React.ReactNode;
+    credits: React.ReactNode;
+    selected?: boolean;
+    onClick?: () => void;
+    className?: string;
+}): React.ReactElement;
+declare function PlanRow({ name, description, price, selected, current, disabled, state, onClick, className, ...rest }: {
+    name: React.ReactNode;
+    description?: React.ReactNode;
+    price: React.ReactNode;
+    selected?: boolean;
+    current?: boolean;
+    disabled?: boolean;
+    state?: 'idle' | 'selected' | 'current' | 'disabled';
+    onClick?: () => void;
+    className?: string;
+} & Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'onClick' | 'className'>): React.ReactElement;
+declare function StatusDot({ label, empty, className, }: {
+    label?: string;
+    /** Outline-only dot — state A "No plan". */
+    empty?: boolean;
+    className?: string;
+}): React.ReactElement;
+declare function Pill({ children, className, }: {
+    children: React.ReactNode;
+    className?: string;
+}): React.ReactElement;
+type StatusPillTone = 'neutral' | 'accent';
+/** Accent is reserved for the one failing/warning pill: D, F, I. */
+declare function statusPillTone(state: AccountState): StatusPillTone;
+declare function StatusPill({ children, tone, className, }: {
+    children: React.ReactNode;
+    tone?: StatusPillTone;
+    className?: string;
+}): React.ReactElement;
+interface FactBandItem {
+    key: string;
+    label: React.ReactNode;
+    value: React.ReactNode;
+    /** Narrow-row value. Falls back to `value` when omitted. */
+    compactValue?: React.ReactNode;
+    caption?: React.ReactNode;
+}
+/**
+ * Remaining-led fact strip. Columns at the 760px sidebar breakpoint,
+ * key-value rows below it. Callers omit a fact entirely — never pass a
+ * placeholder column. Unmetered subscriptions still render Remaining as
+ * Unlimited; they omit the meter, not the fact.
+ */
+declare function FactBand({ items, className, }: {
+    items: readonly FactBandItem[];
+    className?: string;
+}): React.ReactElement;
+declare function sanitizeDecimalInput(raw: string): string;
+declare function Field({ id, label, value, onChange, prefix, suffix, placeholder, disabled, inputMode, ariaLabel, className, }: {
+    id: string;
+    label: string;
+    value: string;
+    onChange: (value: string) => void;
+    prefix?: string;
+    suffix?: string;
+    placeholder?: string;
+    disabled?: boolean;
+    inputMode?: React.HTMLAttributes<HTMLInputElement>['inputMode'];
+    ariaLabel?: string;
+    className?: string;
+}): React.ReactElement;
+declare function Toggle({ checked, onChange, label, className, }: {
+    checked: boolean;
+    onChange: (checked: boolean) => void;
+    label: string;
+    className?: string;
+}): React.ReactElement;
+declare function LedgerRow({ cells, className, }: {
+    cells: readonly {
+        content: React.ReactNode;
+        align?: 'left' | 'right';
+    }[];
+    className?: string;
+}): React.ReactElement;
+declare function AttributionFooter({ children, className, }: {
+    children: React.ReactNode;
+    className?: string;
+}): React.ReactElement;
+declare function SplitRow({ children, className, }: {
+    children: React.ReactNode;
+    className?: string;
+}): React.ReactElement;
+
+/**
+ * MCP account-widget wrapper around the shared `<UsageMeter>`.
+ *
+ * Pins `warningAt=80` / `criticalAt=100` (shared defaults are 75/90) and
+ * forces a warning when `remaining === 1` on a finite cap — E at 2 of 3
+ * is a last-call warning, not a 67%=80% bug.
+ */
+
+declare const MCP_USAGE_WARNING_AT = 80;
+declare const MCP_USAGE_CRITICAL_AT = 100;
 /**
- * Seller details — company name, legal entity, support email/URL,
- * terms link. Compliance-relevant: a customer paying through the
- * iframe should see who they're actually paying, to the same level of
- * detail as hosted checkout.
+ * `0` when remaining is the last call on a finite cap so the shared
+ * percent gate still flips to warning below 80%. Otherwise 80.
  */
-declare function McpSellerDetailsCard({ classNames, showVerifiedBadge, }: McpSellerDetailsCardProps): react_jsx_runtime.JSX.Element | null;
+declare function mcpUsageWarningAt(remaining: number | null | undefined): number;
+type McpUsageMeterProps = Omit<UsageMeterRootProps, 'warningAt' | 'criticalAt'>;
+declare function McpUsageMeter({ usageOverride, className, children, ...rest }: McpUsageMeterProps): React.ReactElement;
 
-export { type ActivationStrategy, type ActivityStripKind, AppHeader, type AppHeaderMode, type AppHeaderProps, type AppToolResultEvents, BackLink, type BackLinkProps, HOSTS_WITH_MERCHANT_CHROME, type HostEntryClassification, McpAccountView, type McpAccountViewProps, McpApp, type McpAppBootstrapLike, type McpAppFull, type McpAppLike, type McpAppProps, McpAppShell, type McpAppShellProps, type McpAppViewOverrides, type McpBootstrap, type McpBridgeAppLike, McpBridgeProvider, type McpBridgeProviderProps, type McpBridgeValue, McpCheckoutView, type McpCheckoutViewProps, McpCustomerDetailsCard, type McpCustomerDetailsCardProps, McpHostInfoProvider, type McpHostInfoProviderProps, type McpMessageOnSuccess, McpSellerDetailsCard, type McpSellerDetailsCardProps, type McpSuccessEvent, type McpTabKind, type McpToolResult, McpTopupView, type McpTopupViewProps, type McpUiHostContextLike, type McpView, type McpViewClassNames, type McpViewKind, McpViewRouter, type McpViewRouterProps, type NotifyModelContextParams, type PlanActions, type PlanActionsInput, type PlanLike, type PlanShape, type PurchaseSnapshotLike, SOLVAPAY_TRANSPORT_TOOL_NAMES, type SendMessageParams, type StripeProbeState, type WaitForInitialToolResultOptions, type WaitForInitialToolResultResult, classifyHostEntry, createMcpAppAdapter, fetchMcpBootstrap, fetchMcpBootstrapViaResource, isTransportToolName, parseBootstrapFromToolResult, resolveActivationStrategy, resolveActivityStrip, resolveMcpClassNames, resolvePlanActions, resolvePlanShape, seedMcpCaches, useHostLocale, useHostName, useMcpBridge, useMcpToolResult, useStripeProbe, waitForInitialToolResult };
+export { ACCOUNT_STATES, type AccountLimitsLike, type AccountPurchaseLike, type AccountState, type AccountStateInput, type ActivationStrategy, type ActiveProduct, type ActivityStripKind, AmountLadder, type AmountLadderRow, AppHeader, type AppHeaderMode, type AppHeaderProps, type AppToolResultEvents, AttributionFooter, BackLink, type BackLinkProps, CREDIT_ACTIVITY_TYPE_LABELS, DEFAULT_DISPLAY_MODE_STATE, Eyebrow, FactBand, type FactBandItem, Field, HOSTS_WITH_MERCHANT_CHROME, type HostEntryClassification, LedgerRow, LineItem, MCP_DISPLAY_MODES, MCP_HOSTED_MIN_WIDTH, MCP_USAGE_CRITICAL_AT, MCP_USAGE_WARNING_AT, McpAccountView, type McpAccountViewProps, McpApp, type McpAppBootstrapLike, type McpAppFull, type McpAppLike, type McpAppProps, McpAppShell, type McpAppShellProps, type McpAppViewOverrides, McpAutoRechargeView, type McpAutoRechargeViewProps, type McpBootstrap, type McpBridgeAppLike, McpBridgeProvider, type McpBridgeProviderProps, type McpBridgeValue, McpCheckoutView, type McpCheckoutViewProps, type McpContainerDimensions, type McpDisplayMode, McpDisplayModeProvider, type McpDisplayModeProviderProps, type McpDisplayModeState, McpHostInfoProvider, type McpHostInfoProviderProps, type McpHostedRail, type McpMessageOnSuccess, McpPayingAs, type McpPayingAsProps, type McpSafeAreaInsets, type McpSuccessEvent, type McpTabKind, type McpToolResult, McpTopupView, type McpTopupViewProps, type McpUiHostContextLike, McpUsageMeter, type McpUsageMeterProps, type McpView, type McpViewClassNames, type McpViewKind, McpViewRouter, type McpViewRouterProps, type MeterTone, type NotifyModelContextParams, type OneTimeDisplay, type PeriodDisplay, Pill, type PlanActions, type PlanActionsInput, type PlanLike, PlanRow, type PlanShape, PresetTile, type PurchaseSnapshotLike, type RateDisplay, type RemainingDisplay, SOLVAPAY_MCP_APP_CAPABILITIES, SOLVAPAY_TRANSPORT_TOOL_NAMES, Section, type SendMessageParams, SplitRow, StatusDot, StatusPill, type StatusPillTone, type StripeProbeState, Toggle, type WaitForInitialToolResultOptions, type WaitForInitialToolResultResult, allowanceMeterUnit, classifyHostEntry, createMcpAppAdapter, daysUntil, deriveActiveProducts, fetchMcpBootstrap, fetchMcpBootstrapViaResource, findCatalogPlan, formatAllowanceTerms, formatMerchantPlace, formatProductTerms, formatSince, hostSafeAreaPadding, hostWidthPx, isMcpDisplayMode, isTransportToolName, mapChargeRow, mapCreditActivityRow, mcpUsageWarningAt, mergePlanSnapshot, parseBootstrapFromToolResult, planConsequence, readDisplayModeState, remainingCap, resolveAccountState, resolveActivationStrategy, resolveActivityStrip, resolveHostedRail, resolveMcpClassNames, resolveMerchantStrip, resolveMeterTone, resolveOneTimeDisplay, resolvePeriodDisplay, resolvePlanActions, resolvePlanShape, resolveRateDisplay, resolveRemaining, sanitizeDecimalInput, seedMcpCaches, statusPillTone, useDisplayMode, useHostLocale, useHostName, useMcpBridge, useMcpToolResult, useStripeProbe, waitForInitialToolResult, websiteHostLabel };