@volter/twin-stripe 0.1.0

package/client/stripe-mirror.tsx

@@ -0,0 +1,691 @@
+// Stripe UI mirror — React/TSX client (Bun-bundled). A Stripe-dashboard-style view
+// in the shared world UI-mirror design language: top bar + left nav + list/detail
+// split. Renders by consuming the twin's own REST API (/v1/<collection>).
+//
+// The pure format/resolution helpers live in ../src/stripe-mirror-ui.ts so they can
+// be unit-tested AND shared here (Bun tree-shakes the server-only exports out of
+// this browser bundle).
+import React, { useEffect, useMemo, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import {
+  formatStripeAmount, formatRecurring, statusTone, flattenStripeValue,
+  resolveCrossRefs, referenceCollection, formatPaymentMethod, productImageUrls,
+  formatPaymentError, formatBalanceSummary, formatAccountFlags, accountCurrentlyDue,
+  type StripeRow, type FlatLine, type CrossRefs,
+} from '../src/stripe-mirror-ui.ts';
+
+export type Section = { key: string; label: string; title: (r: StripeRow) => string; subtitle: (r: StripeRow) => string };
+
+export const SECTIONS: Section[] = [
+  { key: 'customers', label: 'Customers', title: (r) => r.name || r.email || r.id, subtitle: (r) => r.email || r.id },
+  { key: 'payment_intents', label: 'Payments', title: (r) => formatStripeAmount(r.amount, r.currency), subtitle: (r) => `${r.status} · ${r.id}` },
+  { key: 'setup_intents', label: 'Setup Intents', title: (r) => r.id, subtitle: (r) => `${r.status ?? ''} · ${r.usage ?? ''}` },
+  { key: 'subscriptions', label: 'Subscriptions', title: (r) => r.id, subtitle: (r) => `${r.status} · ${r.customer ?? ''}` },
+  { key: 'invoices', label: 'Invoices', title: (r) => `${formatStripeAmount(r.total ?? r.amount_due, r.currency)}`, subtitle: (r) => `${r.status} · ${r.id}` },
+  { key: 'invoiceitems', label: 'Invoice Items', title: (r) => formatStripeAmount(r.amount, r.currency), subtitle: (r) => `${r.customer ?? ''} · ${r.id}` },
+  { key: 'credit_notes', label: 'Credit Notes', title: (r) => formatStripeAmount(r.amount, r.currency), subtitle: (r) => `${r.status ?? ''} · ${r.invoice ?? r.id}` },
+  { key: 'products', label: 'Products', title: (r) => r.name || r.id, subtitle: (r) => r.id },
+  { key: 'prices', label: 'Prices', title: (r) => `${formatStripeAmount(r.unit_amount, r.currency)}${formatRecurring(r.recurring) ? ` ${formatRecurring(r.recurring)}` : ''}`, subtitle: (r) => r.product ?? r.id },
+  // --- billing & commerce (coupons, promotion codes, payment links, quotes) ---
+  { key: 'coupons', label: 'Coupons', title: (r) => r.name || (r.percent_off != null ? `${r.percent_off}% off` : `${formatStripeAmount(r.amount_off, r.currency)} off`), subtitle: (r) => `${r.duration ?? ''} · ${r.id}` },
+  { key: 'promotion_codes', label: 'Promotion Codes', title: (r) => r.code || r.id, subtitle: (r) => `${r.active ? 'active' : 'inactive'} · ${r.coupon ?? ''}` },
+  { key: 'payment_links', label: 'Payment Links', title: (r) => r.url || r.id, subtitle: (r) => `${r.active ? 'active' : 'inactive'} · ${r.id}` },
+  { key: 'quotes', label: 'Quotes', title: (r) => formatStripeAmount(r.amount_total, r.currency), subtitle: (r) => `${r.status ?? ''} · ${r.customer ?? r.id}` },
+  { key: 'charges', label: 'Charges', title: (r) => formatStripeAmount(r.amount, r.currency), subtitle: (r) => `${r.status} · ${r.id}` },
+  { key: 'refunds', label: 'Refunds', title: (r) => formatStripeAmount(r.amount, r.currency), subtitle: (r) => `${r.status ?? ''} · ${r.charge ?? r.id}` },
+  { key: 'payment_methods', label: 'Payment Methods', title: (r) => formatPaymentMethod(r), subtitle: (r) => `${r.type ?? ''} · ${r.id}` },
+  { key: 'disputes', label: 'Disputes', title: (r) => formatStripeAmount(r.amount, r.currency), subtitle: (r) => `${r.reason ?? ''} · ${r.status ?? ''}` },
+  { key: 'payouts', label: 'Payouts', title: (r) => formatStripeAmount(r.amount, r.currency), subtitle: (r) => `${r.status ?? ''} · ${r.id}` },
+  { key: 'balance_transactions', label: 'Balance Transactions', title: (r) => formatStripeAmount(r.amount, r.currency), subtitle: (r) => `${r.type ?? ''} · ${r.id}` },
+  { key: 'balance', label: 'Balance', title: (r) => r.id, subtitle: (r) => 'account balance summary' },
+  // --- Connect (connected accounts + transfers) ---
+  { key: 'accounts', label: 'Connected Accounts', title: (r) => r.email || r.id, subtitle: (r) => `${r.type ?? 'account'} · ${r.country ?? ''}` },
+  { key: 'transfers', label: 'Transfers', title: (r) => formatStripeAmount(r.amount, r.currency), subtitle: (r) => `→ ${r.destination ?? '?'}` },
+  // --- customer billing (tax IDs + credit-balance ledger) ---
+  { key: 'tax_ids', label: 'Customer Tax IDs', title: (r) => `${r.value ?? r.id}`, subtitle: (r) => `${r.type ?? ''} · ${r.customer ?? ''}` },
+  { key: 'customer_balance_transactions', label: 'Customer Balance', title: (r) => formatStripeAmount(r.amount, r.currency), subtitle: (r) => `bal ${formatStripeAmount(r.ending_balance, r.currency)} · ${r.customer ?? ''}` },
+  // --- Stripe Tax (tax rates + calculations) ---
+  { key: 'tax_rates', label: 'Tax Rates', title: (r) => `${r.display_name ?? 'Tax'} · ${r.percentage ?? 0}%`, subtitle: (r) => `${r.inclusive ? 'inclusive' : 'exclusive'} · ${r.jurisdiction ?? r.id}` },
+  { key: 'tax/calculations', label: 'Tax Calculations', title: (r) => formatStripeAmount(r.amount_total, r.currency), subtitle: (r) => `tax ${formatStripeAmount(r.tax_amount_exclusive, r.currency)} · ${r.id}` },
+  { key: 'events', label: 'Events', title: (r) => r.type || r.id, subtitle: (r) => r.id },
+  { key: 'webhook_endpoints', label: 'Webhook Endpoints', title: (r) => r.url || r.id, subtitle: (r) => `${r.status ?? ''} · ${r.id}` },
+  // --- Radar (fraud prevention): reviews, value lists, custom rules ---
+  { key: 'reviews', label: 'Radar Reviews', title: (r) => r.charge || r.payment_intent || r.id, subtitle: (r) => `${r.open ? 'open' : (r.closed_reason ?? 'closed')} · ${r.id}` },
+  { key: 'radar/value_lists', label: 'Radar Value Lists', title: (r) => r.name || r.alias || r.id, subtitle: (r) => `${r.item_type ?? ''} · ${r.alias ?? r.id}` },
+  { key: 'radar/rules', label: 'Radar Rules', title: (r) => r.predicate || r.id, subtitle: (r) => `${r.action ?? ''} · ${r.id}` },
+  // --- Terminal (in-person) + Issuing (card issuing) screens ---
+  { key: 'terminal/readers', label: 'Terminal Readers', title: (r) => r.label || r.id, subtitle: (r) => `${r.status ?? ''} · ${r.device_type ?? ''}` },
+  { key: 'terminal/locations', label: 'Terminal Locations', title: (r) => r.display_name || r.id, subtitle: (r) => `${(r.address as any)?.city ?? ''} · ${r.id}` },
+  { key: 'issuing/cards', label: 'Issuing Cards', title: (r) => `•••• ${r.last4 ?? ''}`, subtitle: (r) => `${r.status ?? ''} · ${r.type ?? ''}` },
+  { key: 'issuing/cardholders', label: 'Issuing Cardholders', title: (r) => r.name || r.id, subtitle: (r) => `${r.type ?? ''} · ${r.status ?? ''}` },
+  // --- Reporting (financial reports / Sigma report runs) ---
+  { key: 'reporting/report_runs', label: 'Reports', title: (r) => r.report_type || r.id, subtitle: (r) => `${r.status ?? ''} · ${r.id}` },
+];
+
+// `balance` is the one section backed by a synthesized summary (GET /v1/balance), not a
+// list collection; the fetch loop special-cases it (no `data` array).
+export const BALANCE_KEY = 'balance';
+const SECTION_BY_KEY: Record<string, Section> = Object.fromEntries(SECTIONS.map((s) => [s.key, s]));
+
+export function StatusPill({ value }: { value: any }) {
+  const v = String(value ?? '');
+  return <span className={`pill ${statusTone(v)}`}>{v.replace(/_/g, ' ') || '—'}</span>;
+}
+
+/** A clickable id reference that jumps to its collection + selects the row. */
+export function RefChip({ collection, id, label, onJump }: { collection: string; id: string; label: string; onJump: (c: string, id: string) => void }) {
+  return (
+    <button className="ref-chip" title={id} onClick={() => onJump(collection, id)}>
+      <span className="ref-label">{label}</span>
+      <span className="ref-id mono">{id}</span>
+    </button>
+  );
+}
+
+/** Render the flattened nested-field lines (replaces the old "[object Object]"). */
+export function NestedLines({ lines, onJump }: { lines: FlatLine[]; onJump: (c: string, id: string) => void }) {
+  return (
+    <div className="nested">
+      {lines.map((ln, i) => (
+        <div className="nested-line" key={i} style={{ paddingLeft: `${ln.depth * 14}px` }}>
+          {ln.label ? <span className="nested-label">{ln.label}</span> : null}
+          {ln.ref ? (
+            <button className="ref-inline mono" title={ln.value} onClick={() => onJump(referenceCollection(ln.label) ?? '', ln.value)}>{ln.value}</button>
+          ) : ln.value ? (
+            <span className="nested-value">{ln.value}</span>
+          ) : null}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * The test-card decline state (payment_intent / charge `last_payment_error`) rendered as
+ * a prominent error banner — this is the vendor-faithful decline reason, not just another
+ * nested field, so the mirror surfaces it like a real Stripe payment-failed screen.
+ */
+export function PaymentErrorBanner({ error }: { error: any }) {
+  const text = formatPaymentError(error);
+  if (!text) return null;
+  return (
+    <div className="pay-error" role="alert">
+      <span className="pay-error-label">Payment error</span>
+      <span className="pay-error-text">{text}</span>
+    </div>
+  );
+}
+
+/** The synthesized account balance summary (available / pending per currency). */
+export function BalanceSummary({ row }: { row: StripeRow }) {
+  const buckets = formatBalanceSummary(row);
+  if (buckets.length === 0) return null;
+  return (
+    <div className="balance-summary">
+      {buckets.map((b) => (
+        <div className={`balance-bucket ${b.bucket}`} key={b.bucket}>
+          <span className="balance-bucket-label">{b.bucket}</span>
+          <span className="balance-bucket-amount">{b.text}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * Connect connected-account panel: the three enablement flags (charges/payouts/details)
+ * a real Stripe Connect dashboard shows up front, plus the outstanding onboarding
+ * requirements (`currently_due`). Surfaces the account's readiness like Stripe does,
+ * instead of leaving these buried in the generic field grid.
+ */
+export function ConnectAccountPanel({ row }: { row: StripeRow }) {
+  const flags = formatAccountFlags(row);
+  const due = accountCurrentlyDue(row);
+  if (flags.length === 0) return null;
+  return (
+    <div className="connect-panel">
+      <div className="connect-flags">
+        {flags.map((f) => (
+          <div className={`connect-flag ${f.enabled ? 'ok' : 'warn'}`} key={f.key}>
+            <span className="connect-flag-label">{f.label}</span>
+            <span className="connect-flag-state">{f.enabled ? 'enabled' : 'disabled'}</span>
+          </div>
+        ))}
+      </div>
+      {due.length > 0 && (
+        <div className="connect-requirements" role="status">
+          <span className="connect-req-label">Requirements currently due</span>
+          <ul className="connect-req-list">
+            {due.map((d) => <li className="connect-req-item mono" key={d}>{d}</li>)}
+          </ul>
+        </div>
+      )}
+    </div>
+  );
+}
+
+/**
+ * Resource action bar — the lifecycle verbs a real Stripe dashboard exposes on a detail
+ * (Capture / Cancel an authorized PaymentIntent, etc.). Each button POSTs the real twin
+ * sub-action endpoint (e.g. /v1/payment_intents/:id/capture); the polling loop then
+ * reflects the new status. Kept faithful: a Capture only shows for a requires_capture PI,
+ * a Cancel only for a still-cancelable one — matching when Stripe actually allows them.
+ */
+export function detailActions(collection: string, row: StripeRow): Array<{ verb: string; label: string }> {
+  const actions: Array<{ verb: string; label: string }> = [];
+  if (collection === 'payment_intents') {
+    if (row.status === 'requires_capture') actions.push({ verb: 'capture', label: 'Capture' });
+    if (row.status && !['succeeded', 'canceled'].includes(String(row.status))) actions.push({ verb: 'cancel', label: 'Cancel' });
+  }
+  return actions;
+}
+
+export function DetailActions({ collection, row, onDone }: { collection: string; row: StripeRow; onDone: () => void }) {
+  const [busy, setBusy] = useState<string | null>(null);
+  const [err, setErr] = useState<string | null>(null);
+  const actions = detailActions(collection, row);
+  if (actions.length === 0) return null;
+  const run = async (verb: string) => {
+    setBusy(verb); setErr(null);
+    try {
+      const res = await fetch(`/v1/${collection}/${row.id}/${verb}`, { method: 'POST' }).then((r) => r.json());
+      if (res.error) throw new Error(res.error.message);
+      onDone();
+    } catch (e: any) {
+      setErr(String(e.message ?? e));
+    } finally {
+      setBusy(null);
+    }
+  };
+  return (
+    <div className="detail-actions">
+      {actions.map((a) => (
+        <button key={a.verb} className={`action-btn action-${a.verb}`} disabled={busy !== null} onClick={() => run(a.verb)}>
+          {busy === a.verb ? `${a.label}…` : a.label}
+        </button>
+      ))}
+      {err && <span className="action-error" role="alert">{err}</span>}
+    </div>
+  );
+}
+
+export function Detail({ collection, row, refs, onJump, onAction }: { collection: string; row?: StripeRow; refs: CrossRefs; onJump: (c: string, id: string) => void; onAction?: () => void }) {
+  if (!row) return <aside className="detail empty">Select a row to inspect it.</aside>;
+  const ccy = typeof row.currency === 'string' ? row.currency : undefined;
+  // Split scalar fields (a plain key/value grid) from nested objects/arrays (recursive).
+  // `last_payment_error` is lifted out into a prominent banner (below) rather than buried
+  // in the generic nested list, so the decline reason reads like a real payment screen.
+  const scalars: Array<[string, any]> = [];
+  const nested: Array<[string, any]> = [];
+  for (const [k, v] of Object.entries(row)) {
+    if (v === null || v === undefined || k === 'object' || k === 'last_payment_error') continue;
+    (typeof v === 'object' ? nested : scalars).push([k, v]);
+  }
+  return (
+    <aside className="detail">
+      <div className="detail-head">
+        <span className="mono">{row.id}</span>
+        {row.status ? <StatusPill value={row.status} /> : row.active !== undefined ? <StatusPill value={String(row.active)} /> : null}
+      </div>
+
+      <DetailActions collection={collection} row={row} onDone={() => onAction?.()} />
+      <PaymentErrorBanner error={row.last_payment_error} />
+      {collection === BALANCE_KEY ? <BalanceSummary row={row} /> : null}
+      {collection === 'accounts' ? <ConnectAccountPanel row={row} /> : null}
+
+      <dl>
+        {scalars.map(([k, v]) => {
+          const ref = typeof v === 'string' && referenceCollection(k);
+          const isMoney = k === 'amount' || k === 'unit_amount' || /amount|total|subtotal|balance/.test(k);
+          return (
+            <div className="kv" key={k}>
+              <dt>{k}</dt>
+              <dd className={k === 'id' || String(k).endsWith('_id') ? 'mono' : ''}>
+                {ref ? (
+                  <button className="ref-inline mono" onClick={() => onJump(ref, v)}>{v}</button>
+                ) : isMoney && typeof v === 'number' ? formatStripeAmount(v, ccy) : String(v)}
+              </dd>
+            </div>
+          );
+        })}
+      </dl>
+
+      {nested.map(([k, v]) => {
+        const thumbs = collection === 'products' && k === 'images' ? productImageUrls(v) : [];
+        return (
+          <div className="detail-block" key={k}>
+            <h4>{k}</h4>
+            {thumbs.length > 0 ? (
+              <div className="thumbs">
+                {thumbs.map((src, i) => (
+                  <a className="thumb" key={i} href={src} target="_blank" rel="noreferrer" title={src}>
+                    <img src={src} alt={`${row.name ?? row.id} image ${i + 1}`} loading="lazy" />
+                  </a>
+                ))}
+              </div>
+            ) : (
+              <NestedLines lines={flattenStripeValue(v, { currency: ccy })} onJump={onJump} />
+            )}
+          </div>
+        );
+      })}
+
+      {(refs.outgoing.length > 0 || refs.incoming.length > 0) && (
+        <div className="detail-block refs">
+          <h4>Related</h4>
+          {refs.outgoing.length > 0 && (
+            <div className="ref-group">
+              <span className="ref-group-label">References</span>
+              {refs.outgoing.map((r, i) => <RefChip key={`o${i}`} {...r} onJump={onJump} />)}
+            </div>
+          )}
+          {refs.incoming.length > 0 && (
+            <div className="ref-group">
+              <span className="ref-group-label">Referenced by</span>
+              {refs.incoming.map((r, i) => <RefChip key={`i${i}`} {...r} onJump={onJump} />)}
+            </div>
+          )}
+        </div>
+      )}
+    </aside>
+  );
+}
+
+/** The left navigation: one item per collection (section), each with a live count. */
+export function SideNav({ sections, counts, activeKey, onSelect, onHome, onSettings }: {
+  sections: Section[];
+  counts: Record<string, number>;
+  activeKey: string;
+  onSelect: (key: string) => void;
+  onHome?: () => void;
+  onSettings?: () => void;
+}) {
+  return (
+    <nav className="side">
+      <button className={`nav-home ${activeKey === '__home' ? 'active' : ''}`} onClick={onHome}>
+        <span>Home</span>
+      </button>
+      {sections.map((s) => (
+        <button key={s.key} className={s.key === activeKey ? 'active' : ''} onClick={() => onSelect(s.key)}>
+          <span>{s.label}</span>
+          <span className="nav-count">{counts[s.key] ?? 0}</span>
+        </button>
+      ))}
+      <button className={`nav-settings ${activeKey === '__settings' ? 'active' : ''}`} onClick={onSettings}>
+        <span>Settings</span>
+      </button>
+    </nav>
+  );
+}
+
+// ── Home / overview screen ──────────────────────────────────────────────────
+// The real Stripe Dashboard Home leads with top-line metrics. We compute them from the
+// SAME twin state the rest of the dashboard renders (no separate data source): gross
+// volume from succeeded payments, the available balance, and live counts. Data-coupled:
+// every number here is derived from the fetched /v1/<collection> projections.
+export function computeHomeMetrics(data: Record<string, StripeRow[]>): {
+  grossVolume: number; currency: string; succeededPayments: number;
+  activeSubscriptions: number; customers: number; openInvoices: number; availableText: string;
+} {
+  const pis = data.payment_intents ?? [];
+  const succeeded = pis.filter((p) => p.status === 'succeeded');
+  const currency = (succeeded[0]?.currency as string) || (pis[0]?.currency as string) || 'usd';
+  const grossVolume = succeeded.reduce((s, p) => s + (Number(p.amount_received ?? p.amount) || 0), 0);
+  const subs = data.subscriptions ?? [];
+  const invoices = data.invoices ?? [];
+  const balanceRow = (data.balance ?? [])[0];
+  const buckets = formatBalanceSummary(balanceRow);
+  const availableText = buckets.find((b) => b.bucket === 'available')?.text ?? formatStripeAmount(0, currency);
+  return {
+    grossVolume, currency,
+    succeededPayments: succeeded.length,
+    activeSubscriptions: subs.filter((s) => s.status === 'active' || s.status === 'trialing').length,
+    customers: (data.customers ?? []).length,
+    openInvoices: invoices.filter((i) => i.status === 'open').length,
+    availableText,
+  };
+}
+
+export function HomeScreen({ data, onJump }: { data: Record<string, StripeRow[]>; onJump: (c: string, id: string) => void }) {
+  const m = computeHomeMetrics(data);
+  const cards = [
+    { key: 'gross', label: 'Gross volume', value: formatStripeAmount(m.grossVolume, m.currency) },
+    { key: 'available', label: 'Available balance', value: m.availableText },
+    { key: 'payments', label: 'Successful payments', value: String(m.succeededPayments) },
+    { key: 'subs', label: 'Active subscriptions', value: String(m.activeSubscriptions) },
+    { key: 'customers', label: 'Customers', value: String(m.customers) },
+    { key: 'open_invoices', label: 'Open invoices', value: String(m.openInvoices) },
+  ];
+  const recent = (data.payment_intents ?? []).slice(0, 5);
+  return (
+    <div className="home-screen">
+      <div className="home-metrics">
+        {cards.map((c) => (
+          <div className="metric-card" key={c.key} data-metric={c.key}>
+            <span className="metric-label">{c.label}</span>
+            <span className="metric-value">{c.value}</span>
+          </div>
+        ))}
+      </div>
+      <div className="home-recent">
+        <h3>Recent payments</h3>
+        {recent.length === 0 && <div className="empty">No payments yet.</div>}
+        {recent.map((p) => (
+          <button className="home-recent-row" key={p.id} onClick={() => onJump('payment_intents', p.id)}>
+            <span className="row-title">{formatStripeAmount(p.amount, p.currency)}</span>
+            <StatusPill value={p.status} />
+            <span className="row-sub mono">{p.id}</span>
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+// ── Global search / command bar ─────────────────────────────────────────────
+// Stripe's Cmd-K command bar searches ACROSS every object type. We search the SAME cached
+// collection data (id / email / name / status / amount substring) and return ranked,
+// cross-collection hits — data-coupled to the twin's real state.
+export type SearchHit = { collection: string; id: string; label: string; sub: string };
+export function globalSearch(data: Record<string, StripeRow[]>, query: string, limit = 20): SearchHit[] {
+  const q = query.trim().toLowerCase();
+  if (!q) return [];
+  const hits: SearchHit[] = [];
+  for (const section of SECTIONS) {
+    for (const row of data[section.key] ?? []) {
+      const haystack = [row.id, row.email, row.name, row.status, section.title(row), section.subtitle(row)]
+        .map((f) => String(f ?? '').toLowerCase());
+      if (haystack.some((f) => f.includes(q))) {
+        hits.push({ collection: section.key, id: row.id, label: section.title(row), sub: `${section.label} · ${row.id}` });
+        if (hits.length >= limit) return hits;
+      }
+    }
+  }
+  return hits;
+}
+
+export function CommandBar({ data, onJump, onClose }: { data: Record<string, StripeRow[]>; onJump: (c: string, id: string) => void; onClose: () => void }) {
+  const [q, setQ] = useState('');
+  const hits = useMemo(() => globalSearch(data, q), [data, q]);
+  return (
+    <div className="cmdk-overlay" role="dialog" aria-label="Search" onClick={onClose}>
+      <div className="cmdk" onClick={(e) => e.stopPropagation()}>
+        <input className="cmdk-input" autoFocus placeholder="Search customers, payments, invoices…" value={q} onChange={(e) => setQ(e.target.value)} />
+        <div className="cmdk-results">
+          {q && hits.length === 0 && <div className="cmdk-empty">No results for “{q}”.</div>}
+          {hits.map((h) => (
+            <button className="cmdk-hit" key={`${h.collection}:${h.id}`} onClick={() => { onJump(h.collection, h.id); onClose(); }}>
+              <span className="cmdk-hit-label">{h.label}</span>
+              <span className="cmdk-hit-sub mono">{h.sub}</span>
+            </button>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+// ── Settings screen (account / API keys / webhooks) ─────────────────────────
+// Backed by real twin state: the account (GET /v1/account, incl. the payout schedule) and
+// the registered webhook endpoints (GET /v1/webhook_endpoints). The API keys block shows
+// the twin's test-mode keys (it is a test-mode twin) — labeled as such, not fabricated live keys.
+export function payoutScheduleText(account: StripeRow | undefined): string {
+  const sched = (account?.settings as any)?.payouts?.schedule;
+  if (!sched || typeof sched !== 'object') return 'default';
+  const interval = String(sched.interval ?? 'daily');
+  if (interval === 'weekly' && sched.weekly_anchor) return `weekly (on ${sched.weekly_anchor})`;
+  if (interval === 'monthly' && sched.monthly_anchor != null) return `monthly (on day ${sched.monthly_anchor})`;
+  return interval;
+}
+
+export function SettingsScreen({ account, webhooks }: { account?: StripeRow; webhooks: StripeRow[] }) {
+  return (
+    <div className="settings-screen">
+      <section className="settings-block" data-settings="account">
+        <h3>Account</h3>
+        <dl>
+          <div className="kv"><dt>Account ID</dt><dd className="mono">{account?.id ?? '—'}</dd></div>
+          <div className="kv"><dt>Country</dt><dd>{(account?.country as string) ?? '—'}</dd></div>
+          <div className="kv"><dt>Default currency</dt><dd>{String((account?.default_currency as string) ?? '—').toUpperCase()}</dd></div>
+          <div className="kv"><dt>Payout schedule</dt><dd className="settings-payout-schedule">{payoutScheduleText(account)}</dd></div>
+          <div className="kv"><dt>Charges enabled</dt><dd>{String(account?.charges_enabled ?? false)}</dd></div>
+        </dl>
+      </section>
+      <section className="settings-block" data-settings="api-keys">
+        <h3>API keys</h3>
+        <div className="api-key-row">
+          <span className="api-key-label">Publishable key (test)</span>
+          <span className="api-key-value mono">pk_test_twin</span>
+        </div>
+        <div className="api-key-row">
+          <span className="api-key-label">Secret key (test)</span>
+          <span className="api-key-value mono">sk_test_twin••••</span>
+        </div>
+      </section>
+      <section className="settings-block" data-settings="webhooks">
+        <h3>Webhooks</h3>
+        {webhooks.length === 0 && <div className="empty">No webhook endpoints registered.</div>}
+        {webhooks.map((w) => (
+          <div className="webhook-row" key={w.id}>
+            <span className="webhook-url mono">{w.url ?? w.id}</span>
+            <StatusPill value={w.status ?? 'enabled'} />
+          </div>
+        ))}
+      </section>
+    </div>
+  );
+}
+
+// ── Create / edit modal (write forms) ───────────────────────────────────────
+// The real Dashboard creates objects via a modal write form that POSTs the create endpoint.
+// We model a faithful create form per collection (the few required fields), POSTing the SAME
+// /v1/<collection> the SDK uses; on success the polling loop reflects the new row.
+export const CREATE_FORMS: Record<string, { label: string; fields: Array<{ name: string; label: string; placeholder?: string; required?: boolean }> }> = {
+  customers: { label: 'customer', fields: [{ name: 'email', label: 'Email', placeholder: 'jenny@example.com' }, { name: 'name', label: 'Name' }] },
+  products: { label: 'product', fields: [{ name: 'name', label: 'Name', required: true }, { name: 'description', label: 'Description' }] },
+  coupons: { label: 'coupon', fields: [{ name: 'percent_off', label: 'Percent off', placeholder: '20' }, { name: 'duration', label: 'Duration', placeholder: 'once' }] },
+  payment_intents: { label: 'payment', fields: [{ name: 'amount', label: 'Amount (cents)', required: true, placeholder: '1000' }, { name: 'currency', label: 'Currency', required: true, placeholder: 'usd' }] },
+};
+
+export function CreateModal({ collection, onClose, onCreated }: { collection: string; onClose: () => void; onCreated: () => void }) {
+  const form = CREATE_FORMS[collection];
+  const [values, setValues] = useState<Record<string, string>>({});
+  const [busy, setBusy] = useState(false);
+  const [err, setErr] = useState<string | null>(null);
+  if (!form) return null;
+  const submit = async () => {
+    setBusy(true); setErr(null);
+    try {
+      const body = Object.entries(values).filter(([, v]) => v !== '').map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join('&');
+      const res = await fetch(`/v1/${collection}`, { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body }).then((r) => r.json());
+      if (res.error) throw new Error(res.error.message);
+      onCreated(); onClose();
+    } catch (e: any) {
+      setErr(String(e.message ?? e));
+    } finally {
+      setBusy(false);
+    }
+  };
+  return (
+    <div className="create-overlay" role="dialog" aria-label={`Create ${form.label}`} onClick={onClose}>
+      <div className="create-modal" onClick={(e) => e.stopPropagation()}>
+        <h3 className="create-title">New {form.label}</h3>
+        {form.fields.map((f) => (
+          <label className="create-field" key={f.name}>
+            <span className="create-field-label">{f.label}{f.required ? ' *' : ''}</span>
+            <input className="create-field-input" placeholder={f.placeholder ?? ''} value={values[f.name] ?? ''} onChange={(e) => setValues((v) => ({ ...v, [f.name]: e.target.value }))} />
+          </label>
+        ))}
+        {err && <div className="create-error" role="alert">{err}</div>}
+        <div className="create-actions">
+          <button className="create-cancel" onClick={onClose}>Cancel</button>
+          <button className="create-submit" disabled={busy} onClick={submit}>{busy ? 'Creating…' : 'Create'}</button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/** The list pane: one row per object in the active section (or an empty state). */
+export function ListPane({ section, rows, query, currentId, onSelect }: {
+  section: Section;
+  rows: StripeRow[];
+  query?: string;
+  currentId?: string;
+  onSelect: (id: string) => void;
+}) {
+  return (
+    <section className="list">
+      {rows.length === 0 && <div className="empty">{query ? 'No matches.' : `No ${section.label.toLowerCase()} in the twin yet.`}</div>}
+      {rows.map((row, i) => (
+        <button key={row.id ?? i} className={`list-row ${currentId === row.id ? 'active' : ''}`} onClick={() => onSelect(row.id)}>
+          <span className="row-main">
+            <span className="row-title">{section.title(row)}</span>
+            <span className="row-sub mono">{section.subtitle(row)}</span>
+          </span>
+          {row.status ? <StatusPill value={row.status} /> : row.active !== undefined ? <StatusPill value={String(row.active)} /> : null}
+        </button>
+      ))}
+    </section>
+  );
+}
+
+export function App() {
+  const [activeKey, setActiveKey] = useState<string>('__home');
+  // All collections cached so cross-references resolve without extra round-trips.
+  const [data, setData] = useState<Record<string, StripeRow[]>>({});
+  const [account, setAccount] = useState<StripeRow | undefined>(undefined);
+  const [error, setError] = useState<string | null>(null);
+  const [selected, setSelected] = useState<string | null>(null);
+  const [query, setQuery] = useState('');
+  const [cmdOpen, setCmdOpen] = useState(false);
+  const [createFor, setCreateFor] = useState<string | null>(null);
+  // Bumped after a detail action (capture/cancel) to re-fetch immediately rather than
+  // waiting for the next poll tick.
+  const [refreshKey, setRefreshKey] = useState(0);
+
+  const active = SECTION_BY_KEY[activeKey];
+
+  useEffect(() => {
+    let live = true;
+    const tick = async () => {
+      try {
+        const results = await Promise.all(SECTIONS.map((s) =>
+          fetch(`/v1/${s.key}`).then((r) => r.json()).then((j) => {
+            if (j.error) throw new Error(j.error.message);
+            // `balance` returns a single summary object (no `data` array); present it as a
+            // one-row list so it flows through the same list/detail machinery. Give it a
+            // stable id so selection/cross-ref code (keyed on `id`) works.
+            if (s.key === BALANCE_KEY) return [s.key, [{ id: 'balance', ...j } as StripeRow]] as const;
+            return [s.key, (j.data ?? []) as StripeRow[]] as const;
+          }),
+        ));
+        // the platform account (GET /v1/account) backs the Settings screen.
+        const acct = await fetch('/v1/account').then((r) => r.json()).catch(() => undefined);
+        if (!live) return;
+        setData(Object.fromEntries(results));
+        if (acct && !acct.error) setAccount(acct as StripeRow);
+        setError(null);
+      } catch (e: any) {
+        if (live) setError(String(e.message ?? e));
+      }
+    };
+    void tick();
+    const timer = window.setInterval(tick, 2000);
+    return () => { live = false; window.clearInterval(timer); };
+  }, [refreshKey]);
+
+  // Cmd/Ctrl-K opens the global command bar (Stripe's search shortcut).
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'k') { e.preventDefault(); setCmdOpen((o) => !o); }
+      if (e.key === 'Escape') { setCmdOpen(false); setCreateFor(null); }
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, []);
+
+  const rows = data[activeKey];
+  const filtered = useMemo(() => {
+    const q = query.trim().toLowerCase();
+    if (!active) return [];
+    if (!q) return rows ?? [];
+    return (rows ?? []).filter((r) =>
+      [active.title(r), active.subtitle(r), r.id, r.email, r.name].some((f) => String(f ?? '').toLowerCase().includes(q)),
+    );
+  }, [rows, query, active]);
+
+  const current = useMemo(() => (rows ?? []).find((r) => r.id === selected) ?? filtered[0], [rows, selected, filtered]);
+  const refs = useMemo(() => current ? resolveCrossRefs(activeKey, current, data) : { outgoing: [], incoming: [] }, [current, activeKey, data]);
+
+  const jump = (collection: string, id: string) => {
+    if (!collection) return;
+    setActiveKey(collection);
+    setSelected(id);
+    setQuery('');
+  };
+
+  const canCreate = active && CREATE_FORMS[activeKey] !== undefined;
+
+  return (
+    <div className="dash">
+      <header className="topbar">
+        <div className="brand"><span className="dot" /> Stripe <span className="tag">twin</span></div>
+        <button className="search search-trigger" onClick={() => setCmdOpen(true)}>Search… <span className="kbd">⌘K</span></button>
+        {active ? <input className="search section-filter" placeholder="Filter this section…" value={query} onChange={(e) => setQuery(e.target.value)} /> : null}
+        <span className="mode">Test mode</span>
+      </header>
+      <div className="body">
+        <SideNav
+          sections={SECTIONS}
+          counts={Object.fromEntries(SECTIONS.map((s) => [s.key, data[s.key]?.length ?? 0]))}
+          activeKey={activeKey}
+          onSelect={(key) => { setActiveKey(key); setSelected(null); setQuery(''); }}
+          onHome={() => { setActiveKey('__home'); setSelected(null); setQuery(''); }}
+          onSettings={() => { setActiveKey('__settings'); setSelected(null); setQuery(''); }}
+        />
+        <main className="content">
+          {activeKey === '__home' ? (
+            <>
+              <div className="content-head"><h2>Home</h2></div>
+              <HomeScreen data={data} onJump={jump} />
+            </>
+          ) : activeKey === '__settings' ? (
+            <>
+              <div className="content-head"><h2>Settings</h2></div>
+              <SettingsScreen account={account} webhooks={data.webhook_endpoints ?? []} />
+            </>
+          ) : active ? (
+            <>
+              <div className="content-head">
+                <h2>{active.label}</h2>
+                <span className="count">{filtered.length}{query ? ` of ${rows?.length ?? 0}` : ''}</span>
+                {canCreate ? <button className="create-trigger" onClick={() => setCreateFor(activeKey)}>+ New</button> : null}
+              </div>
+              {error && <div className="error">Failed to load /v1/{activeKey}: {error}</div>}
+              <div className="split">
+                <ListPane
+                  section={active}
+                  rows={rows ? filtered : []}
+                  query={query}
+                  currentId={current?.id}
+                  onSelect={(id) => setSelected(id)}
+                />
+                <Detail collection={activeKey} row={current} refs={refs} onJump={jump} onAction={() => setRefreshKey((k) => k + 1)} />
+              </div>
+            </>
+          ) : null}
+        </main>
+      </div>
+      {cmdOpen ? <CommandBar data={data} onJump={jump} onClose={() => setCmdOpen(false)} /> : null}
+      {createFor ? <CreateModal collection={createFor} onClose={() => setCreateFor(null)} onCreated={() => setRefreshKey((k) => k + 1)} /> : null}
+    </div>
+  );
+}
+
+// Browser-only mount. Guarded so the presentational components above can be imported
+// (and renderToStaticMarkup'd) in a DOM-less test/SSR environment without this top-level
+// `document` access throwing. The browser bundle still mounts exactly as before.
+if (typeof document !== 'undefined') {
+  createRoot(document.getElementById('root')!).render(<App />);
+}