@solvapay/react 1.1.4 → 1.2.0-preview-4931d1e51e774cede74a33b7f5349c6cf0ff0e95

package/CHANGELOG.md

@@ -1,12 +1,262 @@
 # @solvapay/react changelog
 
-## 1.1.4
+## 1.2.0-preview-4931d1e51e774cede74a33b7f5349c6cf0ff0e95
+
+### Minor Changes
+
+- b53abcb: Add step-aware heading + subheading primitives to `<CheckoutSteps>`. `<CheckoutSteps.StepHeading>` and `<CheckoutSteps.StepMessage>` resolve copy from the active `flow.step` and `flow.branch` (and the selected plan's `billingCycle`), so the chrome at the top of the embedded checkout updates as the customer progresses through plan -> amount -> payment. New `checkout.stepHeading.{plan,amount,payment}` and `checkout.stepMessage.{plan,amount,paymentRecurring,paymentOneTime,paymentPayg}` keys ship with sensible English defaults; the `paymentRecurring` key interpolates `{planName}` from the selected plan.
+
+  ```tsx
+  <CheckoutSteps.Root productRef={productRef} returnUrl={url}>
+    <CheckoutSteps.StepHeading className="my-heading" />
+    <CheckoutSteps.StepMessage className="my-subheading" />
+    <CheckoutSteps.IfStep step="plan">{/* … */}</CheckoutSteps.IfStep>
+    {/* … */}
+  </CheckoutSteps.Root>
+  ```
+
+  When nested inside `<PaywallNotice.Root>`, the `plan` step heading + message defer to the existing `paywall.{paymentRequired,activationRequired,topupRequired}Heading` / `resolvePaywallMessage` so the gate-reason framing the customer saw on entry stays intact. Outside paywall context the fallback `checkout.stepHeading.plan` ("Choose your plan") is used.
+
+  `<PaywallNotice.EmbeddedCheckout>` now renders `<CheckoutSteps.StepHeading>` + `<CheckoutSteps.StepMessage>` at the top of its internal stepped composition by default, passing through the consumer's `classNames.heading` / `classNames.message` overrides. Integrators who already render `<PaywallNotice.Heading>` + `<PaywallNotice.Message>` as siblings of `<EmbeddedCheckout>` (the previous documented pattern) will see duplicated text — drop the outer parts and rely on the in-flow defaults, or stop using `<PaywallNotice.EmbeddedCheckout>` and compose `<CheckoutSteps.*>` directly to keep full layout control.
+
+  Resolves the stale "Pick a plan below to keep chatting." subheading shown on the lifetime-access checkout once the user had progressed past the plan step, and the equivalent staleness on the proactive upgrade path in the chat-checkout demo.
+
+- f0ee414: Add first-class chatbot / streaming primitives across `@solvapay/server` and `@solvapay/react`.
+
+  ### `@solvapay/server`
+  - **New `solvaPay.payable({ productRef }).gate(req, opts)` primitive.** Decision-shaped paywall surface for streaming, SSE, and multi-step agent flows that don't fit the one-shot `.http()` / `.next()` / `.mcp()` adapter contract. Returns a discriminated union — `{ kind: 'paywall', response, content }` (pre-built 402) or `{ kind: 'allow', decision, customerRef, trackSuccess, trackFail }` with bound usage closures. `trackSuccess` / `trackFail` pre-fill `productRef`, `customerRef`, `requestId` and route through `ctx.waitUntil` when an `ExecutionContext`-shaped `ctx` is provided so Workers keep `trackUsage` alive past the response close. Multiple `trackSuccess` calls per allow decision are supported (per-step metering for AI SDK `onStepFinish`, LangChain `handleLLMEnd`, OpenAI `response.completed`).
+  - **New `solvaPay.paywall.decide()` factory exposure.** The kernel `paywall.decide()` routine — already used internally by adapters — is now reachable on the public factory return so streaming handlers can consume the verdict directly without re-implementing limit checks + gate construction.
+  - **New `buildPaywallGate(productRef, limits)` export.** Pure helper that converts a `LimitResponseWithPlan` (or any subset compatible with `apiClient.checkLimits`) into a `PaywallStructuredContent`. Extracted from `paywall.decide()`; both paths share the helper so wire shapes stay in lockstep. Exported from both `./` and `./edge` entrypoints.
+  - **New types:** `PayableGateOptions`, `PayableGateResult`, `PayablePaywallResult`, `PayableAllowResult`.
+  - The handler-shaped adapters (`.http`, `.next`, `.mcp`, `.function`) and `paywall.protect()` are unchanged.
+
+  ### `@solvapay/react`
+  - **`usePlans({ productRef })` `fetcher` is now optional.** When omitted, the hook reads `_config` via `SolvaPayContext` and routes through `defaultListPlans` — preferring `config.transport.listPlans` when available, falling back to `GET ${config.api.listPlans ?? '/api/list-plans'}`. Matches the existing fallback in `<PlanSelector>` / `<CheckoutLayout>` so consumers no longer need to hand-roll `useTransport()` + a fetcher just to call `usePlans`. Explicit `fetcher` overrides remain supported for advanced cases.
+  - **New anonymous-auth helpers (`./adapters/auth`):**
+    - `getOrCreateAnonymousCustomerRef(storageKey?)` — mints / persists an `anon_<uuid>` customer ref under `localStorage`. Falls back to the deterministic `'anon_ssr'` placeholder server-side.
+    - `createAnonymousAuthAdapter(customerRef)` — returns an `AuthAdapter` whose `getToken()` and `getUserId()` both yield the supplied ref. Used to keep the SDK's auth-poll heuristic happy in apps without real authentication.
+    - `resetAnonymousCustomerRef(storageKey?)` — clears the persisted ref plus the SDK's cached customer-ref entries so the next call mints a fresh identity.
+
+  These are additive — no existing exports change. `chat-checkout-demo` is now built on `payable.gate()` + `<PaywallNotice>` and demonstrates the JWT real-auth migration in its README.
+
+- b53abcb: Make every checkout entry require a deliberate plan click + Continue, and ship baseline CSS for the `solvapay-checkout-*` namespace so the recommended-default paywall and `<CheckoutSteps.*>` surfaces look correct out of the box.
+
+  ### Behavioural changes
+  - **`usePlans` no longer pre-selects the first plan when auto-selection is opted out.** When `autoSelectFirstPaid: false` and no `initialPlanRef` is supplied (the configuration `<CheckoutSteps.Root>` uses), `selectedPlanIndex` is `-1` and `selectedPlan` is `null` until the user picks a card. Previously the hook fell through to `0`, which silently highlighted the first card and enabled `<CheckoutSteps.PlanContinueButton>` — defeating the explicit-consent intent of `autoSelectFirstPaid: false`. `<PlanSelector.Root>` direct consumers default to `autoSelectFirstPaid: true` and are unaffected.
+  - **`<PaywallNotice.EmbeddedCheckout>` and `<CheckoutSteps.*>` always render the plan step.** The user clicks a card and presses Continue; nothing auto-advances. This applies even when only one plan is selectable — the plan step is where the rate / commitment is disclosed, and consenting to a paid action shouldn't be silent.
+  - **`@solvapay/react/styles.css` ships baseline rules for `solvapay-checkout-*` parts** — continue button, back link, order summary, amount picker, success receipt. Apps overriding the per-part `className` are unaffected; apps relying on no styling will see new defaults. The pay button (`.solvapay-checkout-pay-button`) and form errors (`.solvapay-checkout-error`) are deliberately not styled here — the underlying `<PaymentForm>` / `<TopupForm>` primitives already cover them via `[data-solvapay-*-submit]` and `[data-solvapay-*-error]`.
+
+  ### Additions
+  - **`UseCheckoutFlowReturn.canGoBack`** — derived boolean read by `<CheckoutSteps.BackLink>`. With every progression user-driven, `canGoBack` is `true` whenever `step` is `'amount'` or `'payment'`, and `false` on `'plan'`.
+
+- e83cae5: Allow customers on an active usage-based (PAYG) plan to top up without bouncing off the plan step.
+
+  ### Behavioural changes
+  - **`<PlanSelector.Grid>` keeps PAYG `currentPlanRef` cards selectable.** Previously every "Current" card was disabled (`disabled = isCurrent || isFree`), which on topup products — where `buildDefaultCheckoutPlanFilter` collapses the catalogue down to a single PAYG card — left the customer staring at an inert grid with no way forward. Recurring/one-time current cards stay disabled because re-selecting them would re-charge the customer; the PAYG branch is the topup conduit and re-entering it is the expected next action. The "Current" badge still renders so the customer sees their active plan.
+  - **`<PlanSelector.Root>` auto-selects the customer's PAYG `currentPlanRef`** when it lands in the visible plan list. Topup checkout (`<CheckoutSteps.Root>` → `autoSelectFirstPaid: false`) now opens with `<CheckoutSteps.PlanContinueButton>` enabled instead of greyed-out. One-shot per `productRef` so a deliberate `clearSelection` doesn't immediately re-snap. Recurring/one-time current plans are not auto-selected — staying with `autoSelectFirstPaid: false`'s explicit-consent contract.
+  - **`useCheckoutFlow.advance()` skips `transport.activatePlan` when the selected plan is already the customer's current plan.** PAYG re-activation is a no-op on the backend and the round-trip just adds latency plus a transient `status: 'activating'` flicker. The flow steps straight to the amount picker.
+
+- cca77fb: Align `<CheckoutSteps>` PAYG topup flow with the hosted topup page and `<McpTopupView>` — drive amount + payment off the merchant's base currency, optimistically bump credits on success, and add the `topupCurrency` prop as a forward-compat hook for multi-currency topups.
+
+  ### Currency invariant
+
+  Credits are merchant-wide, not plan-specific. The PAYG topup branch (`<CheckoutSteps.AmountPicker>`, `<CheckoutSteps.AmountContinueButton>`, `<CheckoutSteps.Payment>` PAYG variant) now resolves currency strictly from:
+
+  ```
+  topupCurrency prop  →  merchant.defaultCurrency  →  null (UI gates)
+  ```
+
+  `plan.currency` is **never** consulted for the topup branch — using it would mismatch what the wallet actually settles in. Recurring/one-time plan purchases keep using `plan.currency` (correct for those, since they settle in the plan's denominated currency).
+
+  ### Additions
+  - **`topupCurrency?: string`** prop on `<CheckoutSteps.Root>` and `<PaywallNotice.EmbeddedCheckout>`. Defaults to `merchant.defaultCurrency`. Pass an explicit value when integrators surface a per-customer currency picker (multi-currency topup support, future).
+  - **`flow.topupCurrency: string | null`** and **`flow.topupCurrencyReady: boolean`** on the `useCheckoutFlow` return value. Step components consume both via `useCheckoutContext`; while `!topupCurrencyReady`, the AmountPicker and Continue button render skeleton/disabled state instead of a misleading default.
+
+  ### Behavioural changes
+  - **Optimistic balance bump on PAYG success.** `useCheckoutFlow.recordPaygSuccess` now calls `balance.adjustBalance(creditsAdded)` so the header pill / `<BalanceBadge>` reflect the topup before the Stripe webhook lands. The `SolvaPayProvider`'s 8s grace window auto-reconciles via the deferred fetch — no race against the real webhook. Mirrors `<McpTopupView>`.
+  - **`<RecurringPayment>` distinguishes recurring vs one-time** plans in submit-button + order-summary copy. Plans with `billingCycle` render `Subscribe — $X/cycle`; plans without (e.g. lifetime / one-time) render `Pay $X` with no `/cycle` suffix. Fixes a regression where lifetime plans rendered as `Subscribe — $X/mo`.
+  - **`<CheckoutSteps.AmountPicker>` renders a skeleton row** while `useMerchant` is in flight and no explicit `topupCurrency` prop is passed. Ensures the picker never paints a misleading USD preset on a non-USD merchant during initial load. The merchant fetch is fast in practice (5-minute cache, often seeded), so this is rarely visible.
+
+  ### Migration
+
+  No breaking changes for existing single-currency integrators. Custom transports without a `getMerchant` adapter must pass `topupCurrency` explicitly (the only currency source available without merchant data) — same shape future multi-currency pickers will use.
+
+- ae1f0aa: Add headless `useCheckoutFlow` hook + opt-in `<CheckoutSteps.*>` parts so MCP, paywall, and chatbot/web checkouts share one state engine while each owns its own layout. Also fix MCP-flavored copy bleed in `<PaywallNotice.Message>` for web integrators.
+
+  ### Additions
+  - **`useCheckoutFlow({ productRef, … })`** — headless state engine for the four-step activation flow (plan → amount [PAYG only] → payment → success). Owns step state, transitions, lifecycle callbacks (`onPlanSelect`, `onAmountSelect`, `onPurchaseSuccess`, `onError`), and the `transport.activatePlan` side-effect on the PAYG plan→amount edge. Must be called inside `<PlanSelector.Root>`. Exported from `@solvapay/react` and `@solvapay/react/primitives`.
+  - **`<CheckoutSteps.*>`** — opt-in pre-styled parts (`Root`, `IfStep`, `PlanGrid`, `PlanContinueButton`, `AmountPicker`, `AmountContinueButton`, `Payment`, `BackLink`, `Success`) that compose on `useCheckoutFlow`. Class names follow the `solvapay-checkout-*` namespace. MCP and paywall surfaces add their own ancestor selectors (`.solvapay-mcp-shell .solvapay-checkout-card`) rather than remapping `classNames` per call site. Exported from `@solvapay/react` and `@solvapay/react/primitives`.
+  - **i18n keys** — new `paywall.activationRequiredMessage`, `paywall.paymentRequiredMessageNoBalance`, `paywall.topupRequiredMessage` for web-friendly paywall copy that doesn't leak MCP tool names ("Call the `upgrade` tool…") into web UIs.
+
+  ### Behavioural changes
+  - **`<PaywallNotice.EmbeddedCheckout>` is now a stepped composition** of `<CheckoutSteps.*>` (plan → amount → payment → success with an explicit Continue between plan and the form). This is the SDK's recommended default for paywall surfaces. Apps wanting a different layout compose `<CheckoutSteps.*>` directly. Removes the previous one-shot composition where the PAYG amount picker and payment form coexisted on the same surface.
+  - **`<PaywallNotice.Message>` resolves a kind-specific i18n string first**, falling back to `content.message` only when no kind-specific copy exists. Strict improvement: web UIs no longer surface MCP-flavored "Call the `upgrade` tool…" copy that was authored for CLI / MCP hosts. The MCP layer routes `content.message` through `content[0].text` (its actual consumer), so MCP behaviour is unchanged.
+  - **`<PaywallNotice.EmbeddedCheckout>` and `<CheckoutSteps.Root>` ship a smart default plan filter.** Aligns the SDK with the hosted-checkout topup pattern (one usage-based plan + `<AmountPicker>` with currency presets — no separate "100 Credits" / "250 Credits" pack plans). The new `buildDefaultCheckoutPlanFilter(plans)` always hides Free plans, and hides PAYG when the product also exposes a non-PAYG paid plan so legacy / mixed configs render only the packs. PAYG-only products surface a single PAYG card on the plan step that the user clicks before continuing into the AmountPicker. Consumers passing an explicit `filter` prop keep their existing behaviour.
+
+  ### MCP
+  - `<McpCheckoutView>` and `mcp/views/checkout/EmbeddedCheckout` are now thin layout wrappers around `useCheckoutFlow`. The state machine moved to the hook; the MCP wrapper owns the bridge wiring (`notifyModelContext` on plan commit, `notifySuccess` on success, `sendMessage` on Stay-on-Free) and the MCP-specific chrome (banner, Stay-on-Free button). All existing `<McpCheckoutView>` tests pass unchanged.
+
+- b53abcb: Add `useLimits` — a backend-authoritative hook for rendering "X left" pills against any (product, meter) pair.
+
+  The runtime portion of the backend's `LimitResponse` (the same data `paywall.decide()` consults internally on every gated request) is now exposed read-only so consumers can render an honest counter without reinventing the math client-side. Replaces two common patterns:
+  - `floor(useBalance().credits / plan.creditsPerUnit)` for prepaid usage-based products.
+  - `messageLimit - userMessageCount` local refs for free-tier products.
+
+  Both collapse onto one source of truth.
+
+  ### `@solvapay/react`
+
+  ```tsx
+  import { useLimits } from '@solvapay/react'
+
+  const { remaining, withinLimits, refetch, adjustRemaining } = useLimits({
+    productRef: 'prd_api',
+    meterName: 'requests', // optional; defaults to 'requests'
+  })
+  ```
+
+  The minimal projection (`remaining`, `withinLimits`, `meterName`, `activationRequired`) is intentional — `plans` / `balance` / `productDetails` are already surfaced by `usePlans` / `useBalance` / paywall structured content.
+
+  `activationRequired: true` distinguishes "free tier waiting to be claimed" from "exhausted" — both look like `remaining: 0` on the wire, but only the latter should drive an "Upgrade" CTA. Pair with `useActivation` to flip the customer onto the free tier when the backend's default plan needs explicit activation:
+
+  ```tsx
+  const { activationRequired } = useLimits({ productRef })
+  const { activate } = useActivation()
+  const freePlan = plans.find(p => !p.requiresPayment && (p.freeUnits ?? 0) > 0)
+
+  useEffect(() => {
+    if (activationRequired === true && freePlan?.reference) {
+      activate({ productRef, planRef: freePlan.reference })
+    }
+  }, [activationRequired, freePlan?.reference, productRef, activate])
+  ```
+
+  `adjustRemaining(delta)` mirrors `useBalance().adjustBalance` — applies an 8 s optimistic grace window then auto-refetches. Use after a successful gated action so the pill snaps before the trailing refetch lands. Module-level cache keyed by `customerRef:productRef:meterName` with a 10 s TTL that mirrors the backend paywall's `limitsCacheTTL`. When the transport doesn't implement `getLimits` (e.g. an MCP adapter without the route), the hook returns `null` for `remaining` / `withinLimits` with `loading: false` — graceful fallback matching `useUsage`'s behaviour when `getUsage` is absent.
+
+  ### `@solvapay/server`
+
+  New `checkLimitsCore(request, options)` route helper mirrors `listPlansCore` — reads `productRef` (required) and `meterName` (optional) from query string, authenticates via `getAuthenticatedUserCore`, returns the full `LimitResponseWithPlan`. Reachable from both `@solvapay/server` and `@solvapay/server/edge`.
+
+  ### Transport layer
+
+  `SolvaPayTransport` gains an optional `getLimits({ productRef, meterName? })` method (parallel to `getBalance` / `getUsage`). The default HTTP transport routes to `GET /api/limits` (configurable via `SolvaPayConfig.api.getLimits`).
+
+  ### `useAutoActivateFreePlan`
+
+  New hook that encapsulates the "silently activate the free plan when the backend reports `activationRequired: true`" pattern from the demo. Pairs `useLimits`, `usePlans`, and `useActivation` behind a one-shot guard keyed by `${customerRef}:${productRef}` so failed activations don't retry on every render. Returns `{ pending, activated, error }` — use `pending` as a skeleton gate so the UI doesn't flash "0 left" between the limits fetch and the post-activation refetch.
+
+  ```tsx
+  import { useAutoActivateFreePlan } from '@solvapay/react'
+
+  const { pending: autoActivating } = useAutoActivateFreePlan({ productRef })
+
+  <UsagePill loading={autoActivating || limitsLoading} remaining={limitRemaining} />
+  ```
+
+  When the product has no free plan to activate (e.g. a PAYG-only product whose default plan needs activation but is paid), `pending` stays `false` so the consumer commits to the backend's actual `remaining` instead of stalling on a skeleton.
+
+  ### `usePlans` in-flight cache fix
+
+  Reordered the cache check so the in-flight branch wins over the fresh-cache branch. Previously two sibling `usePlans` calls against the same `productRef` could race: the second caller hit the fresh-cache branch (the in-flight slot carries `plans: []` + a fresh timestamp) and locked itself into "loading=false, plans=[]" until the TTL expired. The in-flight branch now coalesces correctly, and the fresh-cache branch only matches when `plans.length > 0`. Behaviour is unchanged for single-mount use; concurrent callers no longer need a workaround.
+
+  ### Non-breaking
+
+  All additions are additive: `useBalance` / `useUsage` are unchanged, `getLimits` is optional on the transport interface so existing custom transports keep working without modification, and the `usePlans` cache reorder is a strict bugfix (no API change).
 
 ### Patch Changes
 
+- b53abcb: Soften amount-picker quick-pick chips from fully-rounded capsules (`border-radius: 999px`) to subtly rounded rectangles (`border-radius: 8px`) in both the SDK base stylesheet (`.solvapay-amount-picker-pill` / `[data-solvapay-amount-picker-option]`) and the MCP variant (`.solvapay-mcp-amount-option`). Keeps `<CheckoutSteps.AmountPicker>`, `<AmountPicker>`, the hosted topup page, and every `<Mcp*View>` topup/checkout surface visually consistent — the previous capsule shape read inconsistently between narrow MCP iframes (~520px) and wider web containers (~672px+).
+
+  Consumers who prefer the previous capsule shape can restore it with a single override:
+
+  ```css
+  .solvapay-amount-picker-pill,
+  [data-solvapay-amount-picker-option],
+  .solvapay-mcp-amount-option {
+    border-radius: 999px;
+  }
+  ```
+
+  Quick-pick chips inside `.solvapay-amount-picker-pills` (the SDK's default amount-picker row used by `<AmountPicker>`, `<ActivationFlow.AmountPicker>`, and `<CheckoutSteps.AmountPicker>`) now stretch evenly across the row via `flex: 1; min-width: 0` instead of hugging their text content. Matches the dense, even-row look that hosted MCP surfaces already render via host CSS. The container's `flex-wrap: wrap` is preserved so chips wrap to a new line when the row is too narrow to fit them. Consumers who want the previous content-width behaviour can opt out with:
+
+  ```css
+  .solvapay-amount-picker-pills > [data-solvapay-amount-picker-option],
+  .solvapay-amount-picker-pills > .solvapay-amount-picker-pill {
+    flex: 0 0 auto;
+  }
+  ```
+
+  The default amount-picker tree (`<AmountPicker>` shim and `<CheckoutSteps.AmountPicker>` `DefaultAmountTree`) now reserves vertical space for the credit-estimate line at all times instead of mounting it conditionally on first valid amount entry. Previously the form would jump downward by ~1 line the moment a user typed a custom amount or selected a quick-pick chip; the line is now always present, rendered with a non-breaking-space placeholder and `aria-hidden="true"` until an estimate is available. Behaviour is unchanged for hosts that pass `showCreditEstimate={false}` to the standalone `<AmountPicker>` shim — the line is omitted entirely there as before.
+
+- 0240670: Fix `<McpApp>` shell content width on wide-iframe hosts. The previous CSS-only "fill iframe width" change removed the `max-width: 520px` cap from `.solvapay-mcp-main` so unbounded-iframe hosts (MCP Inspector, MCP Jam, full-browser previews) could use the column they hand us, but it overshot — at iframe widths beyond ~700px the AppHeader, body card, and LegalFooter all stretched to the iframe edges, splaying receipt rows with hundreds of pixels of dead air, blowing up the `width: 100%` button to ~800px, and producing >95-character body-copy line lengths.
+
+  Re-introduce a single `max-inline-size: 520px` on `.solvapay-mcp-main` so the whole shell renders as one visually unified block centred in the iframe. The earlier `@media (min-width: 900px) { max-width: 960px }` sidebar-mode override is intentionally not carried forward — it was the cause of the felt-cramped problem on 1200px+ iframes.
+
+  Also convert the wide-shell sidebar `@media (min-width: 900px)` query (`.solvapay-mcp-shell-sidebar` + `.solvapay-mcp-shell-layout` grid switch) to a `@container (min-width: 900px)` query, with `container-type: inline-size` on `.solvapay-mcp-main`. Without this, the sidebar grid would still fire on iframe viewport width — meaning at iframe widths ≥900px the `1fr + 320px` grid would activate inside the 520px capped shell, squeezing the body column to ~184px and breaking payment forms. Container queries fire on the shell's own width.
+
+  When the shell renders the sidebar (authenticated customers — `isShellSidebarEligible` in `McpAppShell.tsx`), lift the cap to 900px via `.solvapay-mcp-main:has(.solvapay-mcp-shell-sidebar)`. Without this lift, `McpAppShell` would suppress the inline customer/seller detail cards in the body (assuming the sidebar takes them) while the sidebar would stay `display: none` (because the container threshold is never reached inside the 520 cap) — both copies hidden, customer details invisible for every authenticated user. With the lift, the 1fr + 320 sidebar grid has room and the container query fires correctly. Unauthenticated flows keep the tighter 520 cap.
+
+  Below 520px (Claude Desktop ~400-500px, ChatGPT inline ~400px, Mobile Claude ~300-360px) the cap is a no-op and content fills the host's container, matching Anthropic's "apps fill the container width" guidance for the primary use cases. Above 520px the cap activates.
+
+  Source-grounded basis for 520:
+  - SEP-1865 §"Container Dimensions" — when the host omits `containerDimensions.width`/`maxWidth` (Unbounded mode) the spec delegates the size choice to the View.
+  - OpenAI Apps SDK guidelines mandate "set a max width and design layouts that collapse gracefully on small screens".
+  - OpenAI's `apps-sdk-ui` reservation card uses `max-w-sm` (384px); `openai-apps-sdk-examples` cluster sits at 220-360px.
+  - Anthropic's PRIMARY use case is Desktop Claude at 400-500px. 520 is a small composite-flow buffer above that range — our `PlanStep → AmountStep → PaymentStep → SuccessStep` is slightly larger than a single-tool inline card.
+  - At our 14px body, 520px ≈ 62ch — inside the 65-75ch optimal reading line length.
+
 - 8dd8638: Fix `McpAppFull.addEventListener`/`removeEventListener` types to accept the tighter `K extends keyof AppEventMap` shape introduced in `@modelcontextprotocol/ext-apps@^1.7`. Previously the loose `(evt: string, …)` signature on the interface didn't match what ext-apps exposes from 1.7+, so consumers seeing types from both `@solvapay/react` and `ext-apps@^1.7` would hit `TS2322: Type 'App' is not assignable to type 'McpAppFull'` at every `<McpApp app={...} />` mount site.
 
   The interface now declares `(evt: any, …)` for both event-listener fields, which is permissive enough to satisfy the new tightened generic without giving up the legacy `ontoolresult` setter fallback. Fixes [PR #169](https://github.com/solvapay/solvapay-sdk/pull/169).
+
+- b53abcb: `<MandateText>` now explicitly calls out that one-time charges are one-time. The `oneTime` mandate template (rendered by `<MandateText>`, `<PaywallNotice.EmbeddedCheckout>`, and `<CheckoutSteps.PaymentForm>` whenever the resolved plan is a one-time / lifetime plan) was previously indistinguishable from the recurring template at a glance: _"By confirming, you authorize Acme Inc to charge $99 for Widget API. Payments are processed by SolvaPay."_ — no signal that this is a single charge versus a subscription. Inserts "a one-time" before the amount so the sentence now reads _"...to charge a one-time $99 for Widget API..."_. Mirrors the disambiguation the `recurring` template gets via `every {period} until you cancel`.
+
+  Integrators with snapshot tests pinned to the previous wording will need to update their fixtures. Integrators using a custom `copy.mandate.oneTime` override are unaffected.
+
+- b53abcb: Fix `<PaywallNotice.EmbeddedCheckout>` so it dismisses synchronously on successful payment instead of waiting for `usePaywallResolver` to flip. Pre-fix, the checkout's `onPurchaseSuccess` only triggered a refetch and the parent's `onResolved` was fired by an effect that watched the resolver — backend / webhook lag (sandbox or local dev) could leave the success card stuck for 10s+ even after Stripe had confirmed the payment.
+
+  `<PaywallNotice.Root>` now dedupes `onResolved` per-mount and exposes the deduped trigger via context, so `<EmbeddedCheckout>` can signal completion immediately on payment success while the resolver-driven path keeps working as a backstop. Inline `onResolved` arrows on the parent no longer re-trigger the effect either.
+
+- cca77fb: `<PaywallNotice>` copy is now host-neutral and topup-aware.
+
+  The default i18n strings used to leak MCP framing ("This tool needs an active plan…") into web surfaces. They've been rewritten in second person and split so the heading/message track whether the gate calls for a real plan or just more credits.
+
+  ### Copy changes
+
+  | Key                                  | Before                                                                      | After                                                              |
+  | ------------------------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+  | `paywall.activationRequiredHeading`  | `Add credits to continue`                                                   | `Activate a plan to continue`                                      |
+  | `paywall.activationRequiredMessage`  | `This tool needs an active plan{forProduct}. Pick one below to keep going.` | `You need an active plan{forProduct} to continue. Pick one below.` |
+  | `paywall.topupRequiredHeading` (new) | —                                                                           | `Add credits to continue`                                          |
+
+  `paywall.topupRequiredMessage` (`You're out of credits{forProduct}. Add more below to keep going.`) is unchanged — it now actually gets used.
+
+  ### Routing
+
+  `<PaywallNotice.Heading>` and `<PaywallNotice.Message>` distinguish the topup variant of an `activation_required` gate from a subscription/lifetime activation. When every plan on `content.plans` has `type: 'usage-based' | 'hybrid'` (PAYG-only), they resolve to the topup heading + message; otherwise they resolve to the activation heading + message. `payment_required` is unchanged.
+
+  ### Migration
+
+  Integrators relying on the default `activationRequiredHeading` text get the corrected copy automatically. Integrators overriding `paywall.*` strings via the i18n bundle keep working — only one new optional key (`topupRequiredHeading`) was added; the runtime falls back to it for PAYG-only gates and `activationRequiredHeading` everywhere else.
+
+- b53abcb: Topup-only paywalls now emit `kind: 'activation_required'` (with the PAYG plans attached) instead of `kind: 'payment_required'`. Fixes the React SDK rendering "Upgrade to continue" / "Pick a plan below to keep chatting" on a surface that only shows an amount picker — the existing `<PaywallNotice.Heading>` / `<PaywallNotice.Message>` resolvers now pick the topup-flavored copy automatically ("Add credits to continue" / "You're out of credits. Add more below to keep going.").
+
+  The swap is conservative — `buildPaywallGate` only re-discriminates when:
+  1. `activationRequired` is not set (the customer already has an active plan), AND
+  2. `classifyPaywallState` returns `topup_required` (active usage-based plan, out of credits), AND
+  3. `limits.plans` contains at least one paid plan AND every paid plan is PAYG (`type: 'usage-based' | 'hybrid'`). Free plans are filtered out before the check, so a typical Free + PAYG product still counts as topup-only.
+
+  When any of those conditions doesn't hold (no plans on the response, mixed PAYG + recurring product, etc.) the gate stays on `payment_required` so the heading / message stay accurate. The internal `paywall-state` classifier and the MCP narration text generated by `buildGateMessage` were already producing topup copy for this case via the `topup_required` state — only the structured `kind` discriminant on the wire changes.
+
+  ### Backward compat
+
+  HTTP / Next adapter consumers branching on `gate.kind === 'payment_required'` for the topup case will now see `gate.kind === 'activation_required'`. The shape is otherwise identical (with `plans`, `balance`, `productDetails` all populated when available). MCP `<McpCheckoutView>` / `PlanStep` `paywallKind` branching is unaffected because the MCP topup flow routes through `<McpTopupView>` (a separate view discriminator) rather than the upgrade plan-step UI.
+
+  Consumers who relied on `kind === 'payment_required'` to mean "this customer is over their free quota and needs to choose a plan" should switch to checking `kind === 'payment_required'` OR (`kind === 'activation_required'` AND not every paid plan is PAYG) for the same intent.
+
+- cca77fb: Fix `usePaywallResolver` so `payment_required` gates carrying a `balance.creditsPerUnit` block resolve once the customer's wallet covers the next unit. This makes topup-shaped 402s (where the customer already has an active usage-based plan) dismiss automatically after a successful topup, instead of leaving consumers stuck on a static success surface.
+
+  A topup creates a balance transaction, not a paid plan purchase, so `hasPaidPurchase` would never flip on subsequent topups. Treating the attached `balance` block the same way the `activation_required` branch does fixes the post-topup auto-dismiss for `<PaywallNotice.Root onResolved>` consumers.
   - @solvapay/mcp-core@0.2.4
 
 ## 1.1.3

package/dist/adapters/auth.cjs

@@ -20,7 +20,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/adapters/auth.ts
 var auth_exports = {};
 __export(auth_exports, {
-  defaultAuthAdapter: () => defaultAuthAdapter
+  createAnonymousAuthAdapter: () => createAnonymousAuthAdapter,
+  defaultAuthAdapter: () => defaultAuthAdapter,
+  getOrCreateAnonymousCustomerRef: () => getOrCreateAnonymousCustomerRef,
+  resetAnonymousCustomerRef: () => resetAnonymousCustomerRef
 });
 module.exports = __toCommonJS(auth_exports);
 var defaultAuthAdapter = {
@@ -43,7 +46,37 @@ var defaultAuthAdapter = {
     return null;
   }
 };
+var DEFAULT_ANON_STORAGE_KEY = "solvapay:anonymousCustomerRef";
+var SSR_PLACEHOLDER_REF = "anon_ssr";
+function getOrCreateAnonymousCustomerRef(storageKey = DEFAULT_ANON_STORAGE_KEY) {
+  if (typeof window === "undefined") return SSR_PLACEHOLDER_REF;
+  const stored = window.localStorage.getItem(storageKey);
+  if (stored) return stored;
+  const next = `anon_${crypto.randomUUID()}`;
+  window.localStorage.setItem(storageKey, next);
+  return next;
+}
+function resetAnonymousCustomerRef(storageKey = DEFAULT_ANON_STORAGE_KEY) {
+  if (typeof window === "undefined") return;
+  window.localStorage.removeItem(storageKey);
+  window.localStorage.removeItem("solvapay_customerRef");
+  window.localStorage.removeItem("solvapay_customerRef_expiry");
+  window.localStorage.removeItem("solvapay_customerRef_userId");
+}
+function createAnonymousAuthAdapter(customerRef) {
+  return {
+    async getToken() {
+      return customerRef;
+    },
+    async getUserId() {
+      return customerRef;
+    }
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  defaultAuthAdapter
+  createAnonymousAuthAdapter,
+  defaultAuthAdapter,
+  getOrCreateAnonymousCustomerRef,
+  resetAnonymousCustomerRef
 });

package/dist/adapters/auth.d.cts

@@ -53,5 +53,67 @@ interface AuthAdapter {
  * It checks for a token in localStorage under the 'auth_token' key.
  */
 declare const defaultAuthAdapter: AuthAdapter;
+/**
+ * Generate (and persist) a stable per-browser customer reference.
+ *
+ * Backed by `window.localStorage` under `storageKey` (default
+ * `solvapay:anonymousCustomerRef`). Calling this from a non-browser
+ * context returns the deterministic SSR placeholder `anon_ssr` —
+ * useful for keeping server-rendered output stable but never used as
+ * an actual customer identifier.
+ *
+ * Pair with `createAnonymousAuthAdapter(ref)` to wire an SDK-friendly
+ * `AuthAdapter` for apps without real authentication. When you migrate
+ * to a real identity provider, swap in your own `AuthAdapter` and
+ * leave this helper behind — the SolvaPay backend deduplicates on
+ * `externalRef`, so the move is non-destructive.
+ *
+ * @param storageKey Optional override for the persistence key.
+ * @returns The persisted (or freshly minted) anonymous customer ref.
+ *
+ * @since 1.2.0
+ */
+declare function getOrCreateAnonymousCustomerRef(storageKey?: string): string;
+/**
+ * Clear the persisted anonymous customer ref. The next call to
+ * `getOrCreateAnonymousCustomerRef()` mints a fresh one — useful for
+ * "switch demo identity" affordances and for end-to-end tests that
+ * need a clean slate per run.
+ *
+ * Also wipes the SDK's customer-ref cache (`solvapay_customerRef`,
+ * `solvapay_customerRef_expiry`, `solvapay_customerRef_userId`) so a
+ * post-reset `checkPurchase` doesn't send the stale
+ * `x-solvapay-customer-ref` header before the SDK's userId-mismatch
+ * invalidation has had a chance to run.
+ *
+ * @param storageKey Optional override matching the key passed to
+ *   `getOrCreateAnonymousCustomerRef`.
+ *
+ * @since 1.2.0
+ */
+declare function resetAnonymousCustomerRef(storageKey?: string): void;
+/**
+ * Build an `AuthAdapter` that pretends every browser is a logged-in
+ * user identified by the supplied anonymous customer ref. Both
+ * `getToken()` and `getUserId()` return the ref — the userId doubles
+ * as the SolvaPay `externalRef` so visiting customers are
+ * deduplicated across reloads.
+ *
+ * `getToken` returns the ref instead of `null` because the SDK polls
+ * auth every 30s; a `null` token causes it to wipe the cached
+ * customer ref, which in turn nulls out local balance state and the
+ * UI snaps back to a "0 credits" view between polls. The synthetic
+ * token only keeps the SDK's session-alive heuristic happy — the
+ * server reads `x-customer-ref` (or your own `x-user-id`-style
+ * header), so an `Authorization: Bearer anon_<uuid>` is harmless on
+ * the wire.
+ *
+ * Once you wire real auth, replace this with the JWT adapter your
+ * identity provider gives you (Clerk, Supabase, Auth0, …) — see
+ * `defaultAuthAdapter` for the JWT-token convention.
+ *
+ * @since 1.2.0
+ */
+declare function createAnonymousAuthAdapter(customerRef: string): AuthAdapter;
 
-export { type AuthAdapter, defaultAuthAdapter };
+export { type AuthAdapter, createAnonymousAuthAdapter, defaultAuthAdapter, getOrCreateAnonymousCustomerRef, resetAnonymousCustomerRef };

package/dist/adapters/auth.d.ts

@@ -53,5 +53,67 @@ interface AuthAdapter {
  * It checks for a token in localStorage under the 'auth_token' key.
  */
 declare const defaultAuthAdapter: AuthAdapter;
+/**
+ * Generate (and persist) a stable per-browser customer reference.
+ *
+ * Backed by `window.localStorage` under `storageKey` (default
+ * `solvapay:anonymousCustomerRef`). Calling this from a non-browser
+ * context returns the deterministic SSR placeholder `anon_ssr` —
+ * useful for keeping server-rendered output stable but never used as
+ * an actual customer identifier.
+ *
+ * Pair with `createAnonymousAuthAdapter(ref)` to wire an SDK-friendly
+ * `AuthAdapter` for apps without real authentication. When you migrate
+ * to a real identity provider, swap in your own `AuthAdapter` and
+ * leave this helper behind — the SolvaPay backend deduplicates on
+ * `externalRef`, so the move is non-destructive.
+ *
+ * @param storageKey Optional override for the persistence key.
+ * @returns The persisted (or freshly minted) anonymous customer ref.
+ *
+ * @since 1.2.0
+ */
+declare function getOrCreateAnonymousCustomerRef(storageKey?: string): string;
+/**
+ * Clear the persisted anonymous customer ref. The next call to
+ * `getOrCreateAnonymousCustomerRef()` mints a fresh one — useful for
+ * "switch demo identity" affordances and for end-to-end tests that
+ * need a clean slate per run.
+ *
+ * Also wipes the SDK's customer-ref cache (`solvapay_customerRef`,
+ * `solvapay_customerRef_expiry`, `solvapay_customerRef_userId`) so a
+ * post-reset `checkPurchase` doesn't send the stale
+ * `x-solvapay-customer-ref` header before the SDK's userId-mismatch
+ * invalidation has had a chance to run.
+ *
+ * @param storageKey Optional override matching the key passed to
+ *   `getOrCreateAnonymousCustomerRef`.
+ *
+ * @since 1.2.0
+ */
+declare function resetAnonymousCustomerRef(storageKey?: string): void;
+/**
+ * Build an `AuthAdapter` that pretends every browser is a logged-in
+ * user identified by the supplied anonymous customer ref. Both
+ * `getToken()` and `getUserId()` return the ref — the userId doubles
+ * as the SolvaPay `externalRef` so visiting customers are
+ * deduplicated across reloads.
+ *
+ * `getToken` returns the ref instead of `null` because the SDK polls
+ * auth every 30s; a `null` token causes it to wipe the cached
+ * customer ref, which in turn nulls out local balance state and the
+ * UI snaps back to a "0 credits" view between polls. The synthetic
+ * token only keeps the SDK's session-alive heuristic happy — the
+ * server reads `x-customer-ref` (or your own `x-user-id`-style
+ * header), so an `Authorization: Bearer anon_<uuid>` is harmless on
+ * the wire.
+ *
+ * Once you wire real auth, replace this with the JWT adapter your
+ * identity provider gives you (Clerk, Supabase, Auth0, …) — see
+ * `defaultAuthAdapter` for the JWT-token convention.
+ *
+ * @since 1.2.0
+ */
+declare function createAnonymousAuthAdapter(customerRef: string): AuthAdapter;
 
-export { type AuthAdapter, defaultAuthAdapter };
+export { type AuthAdapter, createAnonymousAuthAdapter, defaultAuthAdapter, getOrCreateAnonymousCustomerRef, resetAnonymousCustomerRef };

package/dist/adapters/auth.js

@@ -1,6 +1,12 @@
 import {
-  defaultAuthAdapter
-} from "../chunk-OUSEQRCT.js";
+  createAnonymousAuthAdapter,
+  defaultAuthAdapter,
+  getOrCreateAnonymousCustomerRef,
+  resetAnonymousCustomerRef
+} from "../chunk-UMXOAUW7.js";
 export {
-  defaultAuthAdapter
+  createAnonymousAuthAdapter,
+  defaultAuthAdapter,
+  getOrCreateAnonymousCustomerRef,
+  resetAnonymousCustomerRef
 };

package/dist/{chunk-OMQXXYD4.js → chunk-7LUMHCWV.js}

@@ -13,7 +13,7 @@ import {
   usePurchaseStatus,
   useSolvaPay,
   useTransport
-} from "./chunk-WQ3P3PK7.js";
+} from "./chunk-WAJBPTYG.js";
 
 // src/hooks/usePaymentMethod.ts
 import { useCallback, useEffect, useState } from "react";