@volter/twin-stripe 0.1.2 → 2.0.1

package/src/stripe-js.ts

@@ -0,0 +1,70 @@
+// STRIPE.JS — the client library an application's page loads from js.stripe.com (docs/contributing/architecture.md,
+// "Screens": a widget the vendor ships into the application's own page "is not a screen: it is a client library,
+// twinned from its published types as an SDK surface is"). Written from @stripe/stripe-js's published loader and types
+// (7.x: dist/index.mjs, dist/stripe-js/stripe.d.ts, dist/stripe-js/hosted-checkout.d.ts), nothing of Stripe's script
+// copied:
+//   - the loader injects https://js.stripe.com/<release train>/stripe.js (or /v3/), and accepts a script already on the
+//     page whose src matches `/^https:\/\/js\.stripe\.com\/(v3|[a-z]+)\/stripe\.js(\?.*)?$/` (so /v3/stripe.js too);
+//     it resolves `window.Stripe`, reads `Stripe.version` (3 is the v3 URL, otherwise the train's name) and calls the
+//     instance's `_registerWrapper` when it has one;
+//   - `stripe.redirectToCheckout({ sessionId })` sends the customer to that Checkout Session's page (hosted-checkout.d.ts,
+//     RedirectToCheckoutServerOptions), which this twin serves at checkout.stripe.com/c/pay/{id} (screens/checkout.tsx),
+//     and its promise settles only on failure (`Promise<never | {error}>`);
+//   - `stripe.collectFinancialConnectionsAccounts({ clientSecret })` loads the Financial Connections authentication
+//     flow for the session whose client_secret it is (stripe.d.ts; docs.stripe.com/js/financial_connections/
+//     collect_financial_connections_accounts: "it will load the Authentication Flow, an on-page modal UI"). Where the
+//     twin decides: it navigates to the flow's page, js.stripe.com/v3/financial-connections/{client_secret}
+//     (screens/financial-connections.tsx), instead of a modal, so its promise does not settle; the flow returns the
+//     holder to the session's return_url, where the application reads the session's accounts.
+// Demand: Dub's upgrade button (apps/web/ui/workspaces/upgrade-plan-button.tsx) creates a session on its server and
+// calls redirectToCheckout. Every other member of the library throws, naming itself, when called: an application
+// reaching one finds the gap instead of a silent no-op.
+
+/** The release train a script path names: `/v3`, `/v3/` or `/v3/stripe.js` → 3, `/<train>/stripe.js` → the train. */
+export function stripeJsTrain(pathname: string): 3 | string | undefined {
+  if (/^\/v3(\/|\/stripe\.js)?$/.test(pathname)) return 3;
+  return /^\/([a-z]+)\/stripe\.js$/.exec(pathname)?.[1];
+}
+
+function script(version: 3 | string): string {
+  return `(function () {
+  var version = ${JSON.stringify(version)};
+  function gap(name) {
+    return function () { throw new Error("Stripe.js (Volter twin): stripe." + name + " is not modelled by this twin yet"); };
+  }
+  function Stripe(publishableKey) {
+    if (typeof publishableKey !== "string" || !publishableKey) throw new Error("Stripe.js (Volter twin): Stripe() needs a publishable key");
+    var known = {
+      _registerWrapper: function () {},
+      redirectToCheckout: function (options) {
+        if (!options || typeof options.sessionId !== "string" || !options.sessionId) return gap("redirectToCheckout without a sessionId")();
+        window.location.assign("https://checkout.stripe.com/c/pay/" + encodeURIComponent(options.sessionId));
+        return new Promise(function () {});
+      },
+      collectFinancialConnectionsAccounts: function (options) {
+        if (!options || typeof options.clientSecret !== "string" || !options.clientSecret) return gap("collectFinancialConnectionsAccounts without a clientSecret")();
+        window.location.assign("https://js.stripe.com/v3/financial-connections/" + encodeURIComponent(options.clientSecret));
+        return new Promise(function () {});
+      }
+    };
+    return new Proxy(known, {
+      get: function (target, name) {
+        if (name in target) return target[name];
+        if (typeof name === "symbol" || name === "then") return undefined;
+        return gap(String(name));
+      }
+    });
+  }
+  Stripe.version = version;
+  window.Stripe = Stripe;
+})();
+`;
+}
+
+/** js.stripe.com's script for a GET of its path, or undefined for any other request. */
+export function stripeJs(request: Request): Response | undefined {
+  if (request.method !== 'GET') return undefined;
+  const train = stripeJsTrain(new URL(request.url).pathname);
+  if (train === undefined) return undefined;
+  return new Response(script(train), { headers: { 'content-type': 'application/javascript; charset=utf-8', 'access-control-allow-origin': '*' } });
+}

package/src/stripe-mirror-ui.ts

@@ -1,9 +1,11 @@
-// Stripe MIRROR UI (scorecard R13) — a Stripe-dashboard-like view served as a
-// React/TSX app (bundled by Bun, the repo convention; cf. tracker-visualizer).
-// It renders by consuming the twin's OWN REST API on the same origin
-// (/v1/<collection>) — the same endpoints the app uses. Per-vendor + concrete.
-// PURE FRONTEND (R3): the mirror imports no handler and no twin internals — it MOUNTS the pack's
-// own fetch adapter as its API backend and reads every byte of state back over the wire.
+// The Stripe Dashboard (manifest screen `dashboard`, dashboard.stripe.com/test/{section}): a React app
+// (Bun-bundled) served beside the twin. A PURE FRONTEND (runtime contract R3): this module is the shell, its
+// assets and one listener that mounts the pack's OWN fetch adapter beside them. It imports no handler and no
+// twin internals; the client reads and writes only through Stripe's API (`/v1/...`, client/dashboard-api.ts),
+// so it renders a twin or a real account's test data unchanged, pointed at any origin by configuration.
+import { readFile } from 'node:fs/promises';
+import { bundleClient, fileResponse } from '@volter/world-core';
+import { serveHttp } from '@volter/world-core';
 import { createStripeTwinFetch } from './stripe-server.ts';
 
 const CLIENT_ENTRY = () => new URL('../client/stripe-mirror.tsx', import.meta.url).pathname;  // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
@@ -15,310 +17,32 @@ const CLIENT_CSS = () => new URL('../client/stripe-mirror.css', import.meta.url)
 // These are intentionally framework-agnostic (plain data in → plain data out) so
 // they can be unit-tested in isolation AND imported by the React/TSX client
 // (Bun tree-shakes the server-only exports below out of the browser bundle).
-// Keep them free of any `@volter/twin`/`Bun`/twin-adapter usage.
+// Keep them free of any `@volter/world-core`/`Bun`/twin-adapter usage.
 // ---------------------------------------------------------------------------
 
-export type StripeRow = Record<string, any>;
-
-/** Zero-decimal currencies (Stripe stores these in whole units, not cents). */
-const ZERO_DECIMAL = new Set(['bif', 'clp', 'djf', 'gnf', 'jpy', 'kmf', 'krw', 'mga', 'pyg', 'rwf', 'ugx', 'vnd', 'vuv', 'xaf', 'xof', 'xpf']);
-
-/**
- * Format a Stripe minor-unit amount (cents) as a localized currency string.
- * Honors zero-decimal currencies (¥4200 not ¥42.00). Non-numbers → an em dash.
- */
-export function formatStripeAmount(value: unknown, currency?: string): string {
-  if (typeof value !== 'number' || !Number.isFinite(value)) return '—';
-  const ccy = String(currency ?? 'usd').toLowerCase();
-  const zero = ZERO_DECIMAL.has(ccy);
-  const major = zero ? value : value / 100;
-  try {
-    return new Intl.NumberFormat('en-US', {
-      style: 'currency', currency: ccy.toUpperCase(),
-      minimumFractionDigits: zero ? 0 : 2, maximumFractionDigits: zero ? 0 : 2,
-    }).format(major);
-  } catch {
-    // Unknown/invalid currency code → a stable, readable fallback.
-    return `${zero ? major : major.toFixed(2)} ${ccy.toUpperCase()}`;
-  }
-}
-
-/**
- * Render a Stripe price's `recurring` block as a short interval label, e.g.
- * "every month", "every 3 months". Returns '' when it isn't a recurring price.
- */
-export function formatRecurring(recurring: unknown): string {
-  if (!recurring || typeof recurring !== 'object') return '';
-  const r = recurring as Record<string, unknown>;
-  const interval = typeof r.interval === 'string' ? r.interval : '';
-  if (!interval) return '';
-  const count = Number(r.interval_count);
-  return count > 1 ? `every ${count} ${interval}s` : `every ${interval}`;
-}
-
-/**
- * Render a saved payment method as a short human label, e.g. "Visa •••• 4242"
- * for a card, or the bare `type` ("us_bank_account") for non-card methods.
- */
-export function formatPaymentMethod(pm: unknown): string {
-  if (!pm || typeof pm !== 'object') return '—';
-  const m = pm as Record<string, any>;
-  const card = m.card && typeof m.card === 'object' ? (m.card as Record<string, any>) : undefined;
-  if (card && (card.brand || card.last4)) {
-    const brand = card.brand ? String(card.brand).replace(/\b\w/g, (c) => c.toUpperCase()) : 'Card';
-    return card.last4 ? `${brand} •••• ${card.last4}` : brand;
-  }
-  return typeof m.type === 'string' && m.type ? m.type : (m.id ?? '—');
-}
-
-/**
- * Extract the HTTP(S) image URLs from a product's `images` field (Stripe stores an
- * array of URL strings) so the mirror can render them as <img> thumbnails instead
- * of plain text. Non-arrays / non-URL entries are dropped. Order is preserved.
- */
-export function productImageUrls(images: unknown): string[] {
-  if (!Array.isArray(images)) return [];
-  return images.filter((u): u is string => typeof u === 'string' && /^https?:\/\//i.test(u));
-}
-
-/**
- * Render a payment_intent / charge `last_payment_error` (the test-card decline state)
- * as a single human-readable line, e.g. "card_declined (insufficient_funds): Your card
- * has insufficient funds." Returns '' when there is no error object. This is the
- * vendor-faithful decline reason the twin populates on a declined confirm.
- */
-export function formatPaymentError(error: unknown): string {
-  if (!error || typeof error !== 'object') return '';
-  const e = error as Record<string, any>;
-  const code = typeof e.code === 'string' ? e.code : '';
-  const declineCode = typeof e.decline_code === 'string' ? e.decline_code : '';
-  const message = typeof e.message === 'string' ? e.message : '';
-  const head = code ? (declineCode ? `${code} (${declineCode})` : code) : declineCode;
-  if (head && message) return `${head}: ${message}`;
-  return head || message;
-}
-
-/**
- * Summarize a synthesized Stripe `balance` object (available/pending arrays, one entry
- * per currency) into short per-bucket lines, e.g. ["available: $42.00", "pending: $0.00"].
- * The balance is not a list collection, so the mirror renders this summary directly.
- */
-export function formatBalanceSummary(balance: unknown): Array<{ bucket: string; text: string }> {
-  if (!balance || typeof balance !== 'object') return [];
-  const b = balance as Record<string, any>;
-  const sum = (arr: unknown): string => {
-    if (!Array.isArray(arr) || arr.length === 0) return formatStripeAmount(0, 'usd');
-    return arr
-      .map((e) => formatStripeAmount((e as Record<string, any>)?.amount, (e as Record<string, any>)?.currency))
-      .join(', ');
-  };
-  const out: Array<{ bucket: string; text: string }> = [];
-  if (Array.isArray(b.available)) out.push({ bucket: 'available', text: sum(b.available) });
-  if (Array.isArray(b.pending)) out.push({ bucket: 'pending', text: sum(b.pending) });
-  return out;
-}
-
-/**
- * Summarize a Connect connected `account` object's enablement state into the three
- * boolean capability flags a real Stripe Connect dashboard shows up front:
- * charges_enabled, payouts_enabled, details_submitted. Each is rendered as a tone-
- * carrying flag (true → ok, false → warn) so an un-onboarded account reads as such.
- */
-export type AccountFlag = { key: string; label: string; enabled: boolean };
-export function formatAccountFlags(account: unknown): AccountFlag[] {
-  if (!account || typeof account !== 'object') return [];
-  const a = account as Record<string, any>;
-  return [
-    { key: 'charges_enabled', label: 'Charges', enabled: a.charges_enabled === true },
-    { key: 'payouts_enabled', label: 'Payouts', enabled: a.payouts_enabled === true },
-    { key: 'details_submitted', label: 'Details submitted', enabled: a.details_submitted === true },
-  ];
-}
-
-/**
- * Extract a Connect account's outstanding onboarding requirements (the
- * `requirements.currently_due` list real Stripe shows as "needs attention"). Returns
- * an ordered list of the still-due field paths; empty when nothing is due.
- */
-export function accountCurrentlyDue(account: unknown): string[] {
-  if (!account || typeof account !== 'object') return [];
-  const req = (account as Record<string, any>).requirements;
-  if (!req || typeof req !== 'object') return [];
-  const due = (req as Record<string, any>).currently_due;
-  return Array.isArray(due) ? due.filter((d): d is string => typeof d === 'string') : [];
-}
-
-/** Tone for a status pill: 'ok' (green), 'warn' (amber), 'bad' (red), '' (neutral). */
-export type PillTone = 'ok' | 'warn' | 'bad' | '';
-const PILL_OK = new Set(['active', 'succeeded', 'paid', 'true', 'enabled', 'available', 'won']);
-const PILL_WARN = new Set(['open', 'draft', 'pending', 'processing', 'incomplete', 'trialing', 'requires_confirmation', 'requires_action', 'requires_capture', 'requires_payment_method', 'past_due', 'unpaid', 'in_transit', 'warning_needs_response', 'needs_response', 'under_review', 'warning_under_review']);
-const PILL_BAD = new Set(['canceled', 'cancelled', 'void', 'uncollectible', 'failed', 'incomplete_expired', 'false', 'disabled', 'lost', 'charge_refunded']);
-export function statusTone(value: unknown): PillTone {
-  const v = String(value ?? '').toLowerCase();
-  if (PILL_OK.has(v)) return 'ok';
-  if (PILL_BAD.has(v)) return 'bad';
-  if (PILL_WARN.has(v)) return 'warn';
-  return '';
-}
-
-/** True when a key names a field whose value is a Stripe object id we can link. */
-export function isReferenceKey(key: string): boolean {
-  return REFERENCE_FIELDS.has(key);
-}
-// field name → the COLLECTION it points at (so the UI can jump sections + select).
-const REFERENCE_FIELD_MAP: Record<string, string> = {
-  customer: 'customers', product: 'products', price: 'prices',
-  subscription: 'subscriptions', latest_invoice: 'invoices', invoice: 'invoices',
-  payment_intent: 'payment_intents', latest_charge: 'charges', charge: 'charges',
-  payment_method: 'payment_methods', default_payment_method: 'payment_methods',
-  dispute: 'disputes', payout: 'payouts', balance_transaction: 'balance_transactions',
-  source_transaction: 'charges', setup_intent: 'setup_intents',
-  // Connect: a transfer's `destination` points at a connected account.
-  account: 'accounts', destination: 'accounts',
-  // Billing: a customer_balance_transaction may reference the credit_note that created it.
-  credit_note: 'credit_notes',
-};
-const REFERENCE_FIELDS = new Set(Object.keys(REFERENCE_FIELD_MAP));
-/** The collection a reference field points at, or undefined if not a reference. */
-export function referenceCollection(key: string): string | undefined {
-  return REFERENCE_FIELD_MAP[key];
-}
-
-/** A single line in the flattened, human-readable view of a nested value. */
-export type FlatLine = { depth: number; label: string; value: string; ref?: string };
-
-/**
- * Flatten an arbitrary nested Stripe value (object / array / scalar) into ordered,
- * indented label/value lines suitable for a readable detail view — instead of the
- * old "[object Object]". Stripe "list" wrappers ({object:'list',data:[...]}) are
- * unwrapped to their `data`. Amount-ish fields are currency-formatted.
- */
-export function flattenStripeValue(value: unknown, opts: { label?: string; depth?: number; currency?: string } = {}): FlatLine[] {
-  const depth = opts.depth ?? 0;
-  const label = opts.label ?? '';
-  const currency = opts.currency;
-  if (value === null || value === undefined) return [{ depth, label, value: '—' }];
-
-  if (Array.isArray(value)) {
-    if (value.length === 0) return [{ depth, label, value: '(none)' }];
-    const out: FlatLine[] = label ? [{ depth, label, value: '' }] : [];
-    value.forEach((item, i) => {
-      const childDepth = label ? depth + 1 : depth;
-      out.push(...flattenStripeValue(item, { label: `#${i + 1}`, depth: childDepth, currency }));
-    });
-    return out;
-  }
-
-  if (typeof value === 'object') {
-    const obj = value as Record<string, unknown>;
-    // Unwrap Stripe list objects to their data array.
-    if (obj.object === 'list' && Array.isArray(obj.data)) {
-      return flattenStripeValue(obj.data, { label, depth, currency });
-    }
-    const childCurrency = typeof obj.currency === 'string' ? obj.currency : currency;
-    const keys = Object.keys(obj).filter((k) => obj[k] !== null && obj[k] !== undefined && k !== 'object');
-    if (keys.length === 0) return [{ depth, label, value: '(empty)' }];
-    const out: FlatLine[] = label ? [{ depth, label, value: '' }] : [];
-    const childDepth = label ? depth + 1 : depth;
-    for (const k of keys) out.push(...flattenStripeValue(obj[k], { label: k, depth: childDepth, currency: childCurrency }));
-    return out;
-  }
-
-  // scalar
-  const ref = typeof value === 'string' && isReferenceKey(label) ? value : undefined;
-  const isMoney = typeof value === 'number' && (label === 'unit_amount' || /amount|total|subtotal|balance/.test(label));
-  const rendered = isMoney ? formatStripeAmount(value, currency) : String(value);
-  return [{ depth, label, value: rendered, ...(ref ? { ref } : {}) }];
-}
-
-/**
- * Resolve the cross-references for a row: the rows in other collections that this
- * row points AT (outgoing, e.g. invoice→customer) and the rows that point BACK at
- * it (incoming, e.g. customer←subscriptions). Resolved purely from already-fetched
- * collection data, so the UI can render clickable links without extra requests.
- */
-export type RefLink = { collection: string; id: string; label: string };
-export type CrossRefs = { outgoing: RefLink[]; incoming: RefLink[] };
-
-const LABELERS: Record<string, (r: StripeRow) => string> = {
-  customers: (r) => r.name || r.email || r.id,
-  products: (r) => r.name || r.id,
-  prices: (r) => `${formatStripeAmount(r.unit_amount, r.currency)}${formatRecurring(r.recurring) ? ` ${formatRecurring(r.recurring)}` : ''}`,
-  subscriptions: (r) => `${r.status ?? 'subscription'} · ${r.id}`,
-  invoices: (r) => `${r.status ?? 'invoice'} · ${formatStripeAmount(r.total ?? r.amount_due, r.currency)}`,
-  payment_intents: (r) => `${formatStripeAmount(r.amount, r.currency)} · ${r.status ?? ''}`,
-  charges: (r) => `${formatStripeAmount(r.amount, r.currency)} · ${r.status ?? ''}`,
-  refunds: (r) => `${formatStripeAmount(r.amount, r.currency)} · ${r.status ?? 'refund'}`,
-  payment_methods: (r) => `${formatPaymentMethod(r)} · ${r.id}`,
-  disputes: (r) => `${formatStripeAmount(r.amount, r.currency)} · ${r.status ?? 'dispute'}`,
-  payouts: (r) => `${formatStripeAmount(r.amount, r.currency)} · ${r.status ?? 'payout'}`,
-  balance_transactions: (r) => `${formatStripeAmount(r.amount, r.currency)} · ${r.type ?? 'txn'}`,
-  events: (r) => `${r.type ?? 'event'} · ${r.id}`,
-  setup_intents: (r) => `${r.status ?? 'setup_intent'} · ${r.id}`,
-  invoiceitems: (r) => `${formatStripeAmount(r.amount, r.currency)} · ${r.id}`,
-  accounts: (r) => `${r.email || r.id} · ${r.type ?? 'account'}`,
-  transfers: (r) => `${formatStripeAmount(r.amount, r.currency)} → ${r.destination ?? '?'}`,
-  credit_notes: (r) => `${formatStripeAmount(r.amount, r.currency)} · ${r.status ?? 'credit_note'}`,
-  tax_ids: (r) => `${r.value ?? r.id} · ${r.type ?? ''}`,
-  customer_balance_transactions: (r) => `${formatStripeAmount(r.amount, r.currency)} · ${r.id}`,
-};
-function labelFor(collection: string, row: StripeRow): string {
-  return (LABELERS[collection] ?? ((r: StripeRow) => r.id))(row);
-}
-
-export function resolveCrossRefs(
-  collection: string,
-  row: StripeRow,
-  data: Record<string, StripeRow[]>,
-): CrossRefs {
-  const outgoing: RefLink[] = [];
-  const incoming: RefLink[] = [];
-  if (!row) return { outgoing, incoming };
-
-  // Outgoing: every reference field on this row that we can resolve to a row.
-  for (const [key, value] of Object.entries(row)) {
-    if (typeof value !== 'string' || !isReferenceKey(key)) continue;
-    const target = referenceCollection(key)!;
-    const found = (data[target] ?? []).find((r) => r.id === value);
-    outgoing.push({ collection: target, id: value, label: `${key}: ${found ? labelFor(target, found) : value}` });
-  }
-
-  // Incoming: rows in other collections whose reference field points at this row.
-  for (const [other, rows] of Object.entries(data)) {
-    if (other === collection) continue;
-    for (const r of rows) {
-      for (const [key, value] of Object.entries(r)) {
-        if (value !== row.id || !isReferenceKey(key)) continue;
-        incoming.push({ collection: other, id: r.id, label: `${labelFor(other, r)}` });
-      }
-    }
-  }
-  return { outgoing, incoming };
-}
+export * from './stripe-shared.ts';
+import { flattenStripeValue, resolveCrossRefs, type CrossRefs, type FlatLine, type StripeRow } from './stripe-shared.ts';
+void flattenStripeValue; void resolveCrossRefs;
 
 const APP_SHELL = `<!doctype html>
 <html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
-<title>Stripe UI mirror (twin)</title><link rel="stylesheet" href="/assets/styles.css"></head>
-<body><div id="root"></div><script type="module" src="/assets/app.js"></script></body></html>`;
-
+<base href="/"><title>Dashboard – Stripe</title><link rel="stylesheet" href="assets/styles.css"></head>
+<body><div id="root"></div><script type="module" src="assets/app.js"></script></body></html>`;
 let clientBundle: Promise<string> | null = null;
+
 /** Build the React/TSX dashboard client to browser JS (Bun bundles TSX); cached. */
 export function buildStripeMirrorClient(): Promise<string> {
   if (!clientBundle) {
-    clientBundle = Bun.build({ entrypoints: [CLIENT_ENTRY()], target: 'browser', minify: true })
-      .then(async (result) => {
-        if (!result.success) throw new Error(result.logs.map((l) => l.message).join('\n') || 'stripe mirror client build failed');
-        return result.outputs[0]!.text();
-      })
+    clientBundle = bundleClient(CLIENT_ENTRY())
       .catch((error) => { clientBundle = null; throw error; });
   }
   return clientBundle;
 }
 
-/** Serve the Stripe dashboard mirror UI (React app) + its backing REST API. */
-export function createStripeMirrorServer(options: { root?: string; port?: number }): { port: number; stop: () => void } {
+/** Serve the Stripe Dashboard (React app) with the twin's own fetch adapter mounted beside it. */
+export async function createStripeMirrorServer(options: { root?: string; port?: number }): Promise<{ port: number; stop: () => void }> {
   const twin = createStripeTwinFetch(options);
-  const server = Bun.serve({
+  const server = await serveHttp({
     // LOOPBACK-SPECIFIC bind (2026-08-20, the roving ui-verify flake): with the default
     // wildcard hostname, `port: 0` can be handed a port some long-running app already LISTENS
     // on at 127.0.0.1 (SO_REUSEADDR allows the overlapping non-identical bind), and the more
@@ -336,9 +60,10 @@ export function createStripeMirrorServer(options: { root?: string; port?: number
         catch (error) { return new Response(String(error), { status: 500 }); }
       }
       if (request.method === 'GET' && url.pathname === '/assets/styles.css') {
-        return new Response(Bun.file(CLIENT_CSS()), { headers: { 'content-type': 'text/css; charset=utf-8' } });
+        return fileResponse(CLIENT_CSS(), { headers: { 'content-type': 'text/css; charset=utf-8' } });
       }
-      if (request.method === 'GET' && (url.pathname === '/' || url.pathname === '')) {
+      // the Dashboard's own paths (/test/payments, /test/customers/cus_…) are the app; `/` opens Home
+      if (request.method === 'GET' && (url.pathname === '/' || url.pathname === '' || url.pathname === '/test' || url.pathname.startsWith('/test/'))) {
         return new Response(APP_SHELL, { headers: { 'content-type': 'text/html; charset=utf-8' } });
       }
       // everything else → the twin's OWN FETCH ADAPTER (composition, R2): the React client fetches
@@ -354,7 +79,12 @@ export function createStripeMirrorServer(options: { root?: string; port?: number
   return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
 }
 
-/** The app-shell HTML (pure, for tests). The dashboard itself is the React client. */
+/** The app-shell HTML (pure, for tests). The Dashboard itself is the React client. */
 export function stripeMirrorHtml(): string {
   return APP_SHELL;
 }
+
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export function stripeMirrorStyles(): Promise<string> {
+  return readFile(CLIENT_CSS(), 'utf8');
+}

package/src/stripe-params.ts

@@ -0,0 +1,44 @@
+// STRIPE'S PARAMETER CHECK — every API request's top-level parameters against the operation's own in the vendored
+// spec, before any handler reads them. Stripe refuses a parameter the operation does not take with
+// `400 parameter_unknown` ("Received unknown parameter: …", docs.stripe.com/error-codes#parameter-unknown) and a
+// required one left out with `400 parameter_missing` ("Missing required param: …",
+// docs.stripe.com/error-codes#parameter-missing). Without this check a handler read whatever it was sent, so a
+// parameter Stripe had removed (a promotion code's top-level `coupon`, replaced by `promotion[coupon]` in
+// 2025-09-30.clover) was accepted.
+//
+// Where the evidence stops: the check knows only the served version's parameters (the spec's, surface.version). A
+// request pinning an earlier version with Stripe-Version is not checked, since the pack holds no earlier spec;
+// nested parameters are not checked.
+import { readParams, vendorError, type DerivedCall } from '@volter/world-core';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { manifest } from './manifest.ts';
+import { SERVED_VERSION } from './stripe-version.ts';
+
+type Param = { name: string; required?: boolean };
+type Op = { id: string; method: string; query?: Param[]; body?: Param[] };
+const OPS = new Map((surface.operations as Op[]).map((o) => [o.id, o]));
+
+/** Parameters Stripe documents outside its published spec, each with the page that documents it. */
+const DOCUMENTED: Record<string, string[]> = {
+  // a top-up into the Issuing balance (docs.stripe.com/issuing/funding/balance: "destination_balance=issuing")
+  PostTopups: ['destination_balance'],
+};
+
+/** Stripe's refusal of a request whose top-level parameters the operation does not take, or undefined. */
+export async function refuseParameters(call: DerivedCall): Promise<Response | undefined> {
+  const op = OPS.get(call.operation.id);
+  if (!op) return undefined;
+  const pinned = call.request.headers.get('stripe-version');
+  if (pinned && pinned < SERVED_VERSION) return undefined;
+  const method = call.request.method.toUpperCase();
+  const known = new Set([...(op.query ?? []), ...(op.body ?? [])].map((p) => p.name).concat(DOCUMENTED[op.id] ?? []));
+  const params = await readParams(manifest, call.request.clone(), call.operation);
+  for (const name of Object.keys(params)) {
+    if (!known.has(name)) return vendorError(manifest, { status: 400, code: 'parameter_unknown', param: name, message: `Received unknown parameter: ${name}` });
+  }
+  const required = method === 'GET' || method === 'DELETE' ? (op.query ?? []) : (op.body ?? []);
+  for (const p of required) {
+    if (p.required && params[p.name] === undefined) return vendorError(manifest, { status: 400, code: 'parameter_missing', param: p.name, message: `Missing required param: ${p.name}.` });
+  }
+  return undefined;
+}

package/src/stripe-perform-harness.ts

@@ -0,0 +1,29 @@
+// A MINIATURE OF THE HEAD, for this pack's own claims and suites (protocol 2). The kernel's loop
+// (`performEntries`) needs a bound root and a sealed credential a unit test does not have; this is the same
+// shape without one — the same `deployableEntries`, the pack's own push, the same `confirmAction`. Not on
+// the serve path, not exported from the pack.
+import { confirmAction, deployableEntries, worldNow } from '@volter/world-core';
+import { INTERNAL_SUBJECT_TYPES, isPushable, pushStripeAction, type StripeExecute } from './stripe-connector.ts';
+
+export async function performPending(
+  execute: StripeExecute,
+  opts: { root?: string; occurredAt: string },
+): Promise<{ pushed: number; confirmed: string[]; externalIds: Record<string, string> }> {
+  const confirmed: string[] = [];
+  const externalIds: Record<string, string> = {};
+  for (const entry of deployableEntries('stripe', opts.root)) {
+    const op = entry.operation ?? `${entry.subject.type}.update`;
+    // the twin's own records — the recorded event envelopes and the idempotency bookkeeping — are local
+    // state and are never sent
+    if (INTERNAL_SUBJECT_TYPES.has(entry.subject.type) || !isPushable(op)) continue;
+    const { externalId } = await pushStripeAction(execute, { operation: op, subject: entry.subject, fields: entry.fields ?? {} });
+    confirmAction({
+      service: 'stripe', actionId: entry.id, subject: entry.subject, fields: entry.fields ?? {},
+      occurredAt: opts.occurredAt ?? worldNow(), vendorSubjectId: externalId, receipt: { status: 'deployed' },
+      ...(opts.root !== undefined ? { root: opts.root } : {}),
+    });
+    confirmed.push(entry.id);
+    externalIds[entry.id] = externalId;
+  }
+  return { pushed: confirmed.length, confirmed, externalIds };
+}