@growth-labs/cms 0.1.0

package/src/ui/screens/SubscriptionsScreen.tsx

@@ -0,0 +1,1240 @@
+// src/ui/screens/SubscriptionsScreen.tsx — Subscriptions screen (P5 Task 11).
+//
+// Renders the member list + filters, 4 KPI cards (Active/MRR/Churn/LTV),
+// the plan-mix bar, export, and gift subscription — backed entirely by
+// GET /admin/api/subscriptions?type=* (members / kpis / planMix / export)
+// and POST /admin/api/subscriptions (gift).
+//
+// Honesty conventions (two-level per grounding fact 10):
+//   - result.status === 'empty'  → honest empty state, no mock numbers
+//   - result.status === 'partial' → render value with a partial affordance
+//   - result.status === 'live'   → render the real value
+//   - per-key null (e.g. ltv: null) → "— pending backfill" via formatKpi
+//
+// NO BData / MEMBERS / mock KPI numbers (38,214 / $320k / $186).
+//
+// Presentation: Broadsheet idiom — page-head/page-title, .grid-stats KPI cards
+// with serif .tnum numbers, .seg filter, the .tbl members table with .pill.pdot
+// plan/status chips, the .masthead-rule hairline under card titles, and the
+// gift dialog on a .scrim + .panel.panel-pad with .field-label/.input/.btn.
+
+import { useCallback, useEffect, useReducer, useState } from 'react'
+import type {
+	DuplicateAccountsReport,
+	GiftOrdersPage,
+	LsImportSummary,
+	ProviderResult,
+	SubscriptionMember,
+} from '../../providers/types.js'
+import { Icon } from '../icons.js'
+import {
+	formatKpi,
+	type KpiPending,
+	type PlanMixBucket,
+	planMixToBars,
+	selectKpiState,
+} from './render-state.js'
+
+// ---------------------------------------------------------------------------
+// Filter options
+// ---------------------------------------------------------------------------
+
+type FilterOption = 'all' | 'paid' | 'past_due' | 'canceled'
+
+const FILTER_LABELS: Array<{ value: FilterOption; label: string }> = [
+	{ value: 'all', label: 'All' },
+	{ value: 'paid', label: 'Paid' },
+	{ value: 'past_due', label: 'Past due' },
+	{ value: 'canceled', label: 'Canceled' },
+]
+
+// ---------------------------------------------------------------------------
+// Data shapes
+// ---------------------------------------------------------------------------
+
+interface SubscriptionsData {
+	members: ProviderResult<SubscriptionMember[]>
+	kpis: ProviderResult<Record<string, number | null>>
+	planMix: ProviderResult<PlanMixBucket[]>
+	duplicates: ProviderResult<DuplicateAccountsReport>
+	gifts: ProviderResult<GiftOrdersPage>
+}
+
+// ---------------------------------------------------------------------------
+// Reducer
+// ---------------------------------------------------------------------------
+
+interface SubscriptionsState {
+	loading: boolean
+	error: string | null
+	data: SubscriptionsData | null
+	page: number
+}
+
+type SubscriptionsAction =
+	| { type: 'fetch-start' }
+	| { type: 'fetch-ok'; data: SubscriptionsData }
+	| { type: 'fetch-error'; error: string }
+	| { type: 'set-page'; page: number }
+
+function init(): SubscriptionsState {
+	return { loading: true, error: null, data: null, page: 1 }
+}
+
+function reducer(state: SubscriptionsState, action: SubscriptionsAction): SubscriptionsState {
+	switch (action.type) {
+		case 'fetch-start':
+			return { ...state, loading: true, error: null }
+		case 'fetch-ok':
+			return { ...state, loading: false, error: null, data: action.data }
+		case 'fetch-error':
+			return { ...state, loading: false, error: action.error, data: null }
+		case 'set-page':
+			return { ...state, page: action.page }
+		default:
+			return state
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Gift form state
+// ---------------------------------------------------------------------------
+
+interface GiftState {
+	open: boolean
+	email: string
+	planVariantId: string
+	submitting: boolean
+	result: string | null
+}
+
+// ---------------------------------------------------------------------------
+// SubscriptionsScreen
+// ---------------------------------------------------------------------------
+
+export function SubscriptionsScreen() {
+	const [filter, setFilter] = useState<FilterOption>('all')
+	const [s, dispatch] = useReducer(reducer, undefined, init)
+	const [gift, setGift] = useState<GiftState>({
+		open: false,
+		email: '',
+		planVariantId: '',
+		submitting: false,
+		result: null,
+	})
+	const [exporting, setExporting] = useState(false)
+
+	const fetchData = useCallback(async (f: FilterOption, page: number) => {
+		dispatch({ type: 'fetch-start' })
+		try {
+			const filterParam = f === 'all' ? '' : `&filter=${f}`
+			const [membersRes, kpisRes, planMixRes, duplicatesRes, giftsRes] = await Promise.all([
+				fetch(`/admin/api/subscriptions?type=members${filterParam}&page=${page}`),
+				fetch('/admin/api/subscriptions?type=kpis'),
+				fetch('/admin/api/subscriptions?type=planMix'),
+				fetch('/admin/api/subscriptions?type=duplicates'),
+				fetch('/admin/api/subscriptions?type=gifts'),
+			])
+
+			if (!membersRes.ok || !kpisRes.ok || !planMixRes.ok || !duplicatesRes.ok || !giftsRes.ok) {
+				const bad = [membersRes, kpisRes, planMixRes, duplicatesRes, giftsRes].find((r) => !r.ok)!
+				dispatch({ type: 'fetch-error', error: `${bad.status} ${bad.statusText}` })
+				return
+			}
+
+			const [members, kpis, planMix, duplicates, gifts] = await Promise.all([
+				membersRes.json() as Promise<ProviderResult<SubscriptionMember[]>>,
+				kpisRes.json() as Promise<ProviderResult<Record<string, number | null>>>,
+				planMixRes.json() as Promise<ProviderResult<PlanMixBucket[]>>,
+				duplicatesRes.json() as Promise<ProviderResult<DuplicateAccountsReport>>,
+				giftsRes.json() as Promise<ProviderResult<GiftOrdersPage>>,
+			])
+
+			dispatch({ type: 'fetch-ok', data: { members, kpis, planMix, duplicates, gifts } })
+		} catch (err) {
+			dispatch({ type: 'fetch-error', error: String(err) })
+		}
+	}, [])
+
+	useEffect(() => {
+		void fetchData(filter, s.page)
+	}, [fetchData, filter, s.page])
+
+	const handleFilterChange = (f: FilterOption) => {
+		setFilter(f)
+		dispatch({ type: 'set-page', page: 1 })
+	}
+
+	const handleExport = async () => {
+		setExporting(true)
+		try {
+			const res = await fetch('/admin/api/subscriptions?type=export&fmt=csv')
+			if (!res.ok) return
+			const body = (await res.json()) as ProviderResult<string>
+			if (body.status === 'empty' || !body.data) return
+			const blob = new Blob([body.data], { type: 'text/csv' })
+			const url = URL.createObjectURL(blob)
+			const a = document.createElement('a')
+			a.href = url
+			a.download = 'members.csv'
+			a.click()
+			URL.revokeObjectURL(url)
+		} finally {
+			setExporting(false)
+		}
+	}
+
+	const handleGiftSubmit = async () => {
+		if (!gift.email || !gift.planVariantId) return
+		setGift((g) => ({ ...g, submitting: true, result: null }))
+		try {
+			const res = await fetch('/admin/api/subscriptions', {
+				method: 'POST',
+				headers: { 'Content-Type': 'application/json' },
+				body: JSON.stringify({ email: gift.email, planVariantId: gift.planVariantId }),
+			})
+			const body = (await res.json()) as ProviderResult<{ id: string }>
+			if (body.status === 'empty' || !body.data.id) {
+				setGift((g) => ({ ...g, submitting: false, result: 'Provider not configured.' }))
+			} else {
+				setGift((g) => ({
+					...g,
+					submitting: false,
+					result: `Gift created: ${body.data.id}`,
+					email: '',
+					planVariantId: '',
+				}))
+				void fetchData(filter, s.page)
+			}
+		} catch (err) {
+			setGift((g) => ({ ...g, submitting: false, result: String(err) }))
+		}
+	}
+
+	const isPartial = s.data !== null && s.data.kpis.status === 'partial'
+
+	return (
+		<div className="page page-wide fade-in subscriptions-screen" style={{ maxWidth: 1340 }}>
+			<div className="page-head">
+				<div>
+					<h1 className="page-title">Subscriptions</h1>
+					<div className="page-sub">Members, revenue, and plan distribution.</div>
+				</div>
+				<div style={{ display: 'flex', gap: 8 }}>
+					<button
+						type="button"
+						className="btn"
+						onClick={() => void handleExport()}
+						disabled={exporting}
+					>
+						<Icon name="download" size={16} />
+						{exporting ? 'Exporting…' : 'Export'}
+					</button>
+					<button
+						type="button"
+						className="btn primary"
+						onClick={() => setGift((g) => ({ ...g, open: true }))}
+					>
+						<Icon name="sparkle" size={16} />
+						Gift subscription
+					</button>
+				</div>
+			</div>
+
+			{s.loading && (
+				<div style={{ color: 'var(--ink-muted)', fontSize: 14 }}>Loading subscriptions…</div>
+			)}
+
+			{!s.loading && s.error && (
+				<div style={{ color: 'var(--red)', fontSize: 14, display: 'flex', alignItems: 'center' }}>
+					{s.error}
+					<button
+						type="button"
+						className="btn sm"
+						style={{ marginLeft: 12 }}
+						onClick={() => void fetchData(filter, s.page)}
+					>
+						Retry
+					</button>
+				</div>
+			)}
+
+			{!s.loading && !s.error && s.data && (
+				<SubscriptionsBody
+					data={s.data}
+					isPartial={isPartial}
+					filter={filter}
+					onFilterChange={handleFilterChange}
+					page={s.page}
+					onPageChange={(p) => dispatch({ type: 'set-page', page: p })}
+				/>
+			)}
+
+			{/* Gift modal */}
+			{gift.open && (
+				<GiftModal
+					gift={gift}
+					onChange={(field, value) => setGift((g) => ({ ...g, [field]: value }))}
+					onSubmit={() => void handleGiftSubmit()}
+					onClose={() => setGift((g) => ({ ...g, open: false, result: null }))}
+				/>
+			)}
+		</div>
+	)
+}
+
+// ---------------------------------------------------------------------------
+// SubscriptionsBody
+// ---------------------------------------------------------------------------
+
+function SubscriptionsBody({
+	data,
+	isPartial,
+	filter,
+	onFilterChange,
+	page,
+	onPageChange,
+}: {
+	data: SubscriptionsData
+	isPartial: boolean
+	filter: FilterOption
+	onFilterChange: (f: FilterOption) => void
+	page: number
+	onPageChange: (p: number) => void
+}) {
+	// resolvePlanName: null impl echoes the id — the screen receives plan-mix from the
+	// provider and resolves names via the plan-mix data directly (the provider already
+	// supplies the plan id; a real resolver is injected at cutover).
+	const resolveName = (id: string) => id
+
+	const showPlanMix =
+		data.planMix.status !== 'empty' && data.planMix.data && data.planMix.data.length > 0
+
+	return (
+		<>
+			{isPartial && (
+				<PartialBanner message="Showing partial subscription data — LTV/MRR/churn pending LemonSqueezy backfill." />
+			)}
+
+			{/* KPI cards */}
+			<KpiCards kpis={data.kpis} />
+
+			{/* Members table (1.6fr) + plan mix aside (1fr) */}
+			<div className="grid-split-wide" style={{ marginBottom: 'var(--gap)' }}>
+				<div className="panel" style={{ overflow: 'hidden' }}>
+					<div
+						style={{
+							display: 'flex',
+							alignItems: 'center',
+							justifyContent: 'space-between',
+							padding: '15px 18px 14px',
+						}}
+					>
+						<div className="card-title">Members</div>
+						<FilterSegment value={filter} onChange={onFilterChange} />
+					</div>
+					<hr className="masthead-rule" style={{ margin: '0 18px' }} />
+					<MembersTable
+						result={data.members}
+						resolvePlanName={resolveName}
+						page={page}
+						onPageChange={onPageChange}
+					/>
+				</div>
+
+				{showPlanMix ? (
+					<PlanMixChart planMix={data.planMix} resolvePlanName={resolveName} />
+				) : (
+					<div className="panel panel-pad">
+						<div className="card-title" style={{ marginBottom: 16 }}>
+							Plan mix
+						</div>
+						<EmptyPanel
+							icon="chart"
+							message="Plan distribution will appear once the subscriptions provider is configured."
+						/>
+					</div>
+				)}
+			</div>
+
+			{/* Admin-parity panels: Duplicate Accounts, Gift Orders, LemonSqueezy Sync */}
+			<DuplicateAccountsPanel result={data.duplicates} />
+			<GiftOrdersPanel result={data.gifts} />
+			<LemonSqueezySyncPanel />
+		</>
+	)
+}
+
+// ---------------------------------------------------------------------------
+// DuplicateAccountsPanel — billing-email + canonical-email conflict groups
+// ---------------------------------------------------------------------------
+
+function DuplicateAccountsPanel({ result }: { result: ProviderResult<DuplicateAccountsReport> }) {
+	const report = result.data
+	const billing = report?.billingConflicts ?? []
+	const canonical = report?.canonicalConflicts ?? []
+	const hasAny = billing.length > 0 || canonical.length > 0
+
+	return (
+		<div className="panel panel-pad" style={{ marginBottom: 'var(--gap)' }}>
+			<div className="card-title">Duplicate accounts</div>
+			<div className="page-sub" style={{ margin: '4px 0 0' }}>
+				Accounts sharing a billing email or Gmail-canonical alias.
+			</div>
+			<hr className="masthead-rule" style={{ margin: '12px 0 16px' }} />
+
+			{result.status === 'partial' && (
+				<div className="kicker" style={{ color: 'var(--amber)', marginBottom: 12 }}>
+					Partial data
+				</div>
+			)}
+
+			{result.status === 'empty' || !hasAny ? (
+				<EmptyPanel
+					icon="users"
+					message={
+						result.status === 'empty'
+							? 'Duplicate-account checks run once the subscriptions provider is configured.'
+							: 'No duplicate-account signals found.'
+					}
+				/>
+			) : (
+				<>
+					{report && (
+						<div className="kicker" style={{ marginBottom: 14, color: 'var(--ink-muted)' }}>
+							{report.summary.billingConflictGroups} billing ·{' '}
+							{report.summary.canonicalConflictGroups} canonical · {report.summary.impactedAccounts}{' '}
+							accounts impacted
+						</div>
+					)}
+					{billing.length > 0 && (
+						<div style={{ marginBottom: canonical.length > 0 ? 18 : 0 }}>
+							<div className="kicker" style={{ marginBottom: 8 }}>
+								Shared billing email
+							</div>
+							{billing.map((g) => (
+								<ConflictRow
+									key={`b:${g.billingEmail}`}
+									title={g.billingEmail}
+									count={g.accountCount}
+									emails={g.accountEmails}
+								/>
+							))}
+						</div>
+					)}
+					{canonical.length > 0 && (
+						<div>
+							<div className="kicker" style={{ marginBottom: 8 }}>
+								Canonical email matches
+							</div>
+							{canonical.map((g) => (
+								<ConflictRow
+									key={`c:${g.canonicalEmail}`}
+									title={g.canonicalEmail}
+									count={g.accountCount}
+									emails={g.accountEmails}
+								/>
+							))}
+						</div>
+					)}
+				</>
+			)}
+		</div>
+	)
+}
+
+function ConflictRow({ title, count, emails }: { title: string; count: number; emails: string[] }) {
+	return (
+		<div
+			style={{
+				display: 'flex',
+				alignItems: 'baseline',
+				justifyContent: 'space-between',
+				gap: 12,
+				padding: '9px 0',
+				borderBottom: '1px solid var(--border-soft)',
+			}}
+		>
+			<div style={{ minWidth: 0 }}>
+				<div style={{ fontSize: 13, fontWeight: 600, color: 'var(--ink)' }}>{title}</div>
+				<div
+					style={{
+						fontSize: 12,
+						color: 'var(--ink-muted)',
+						overflow: 'hidden',
+						textOverflow: 'ellipsis',
+						whiteSpace: 'nowrap',
+						maxWidth: 520,
+					}}
+				>
+					{emails.join(', ')}
+				</div>
+			</div>
+			<span className="type-tag" style={{ flexShrink: 0 }}>
+				{count} accounts
+			</span>
+		</div>
+	)
+}
+
+// ---------------------------------------------------------------------------
+// GiftOrdersPanel — gift-order claim/delivery tracking
+// ---------------------------------------------------------------------------
+
+function GiftOrdersPanel({ result }: { result: ProviderResult<GiftOrdersPage> }) {
+	const page = result.data
+	const rows = page?.rows ?? []
+
+	return (
+		<div className="panel panel-pad" style={{ marginBottom: 'var(--gap)' }}>
+			<div className="card-title">Gift orders</div>
+			<div className="page-sub" style={{ margin: '4px 0 0' }}>
+				Gifted subscriptions, claim status, and recipient delivery.
+			</div>
+			<hr className="masthead-rule" style={{ margin: '12px 0 16px' }} />
+
+			{result.status === 'partial' && (
+				<div className="kicker" style={{ color: 'var(--amber)', marginBottom: 12 }}>
+					Partial data
+				</div>
+			)}
+
+			{result.status === 'empty' || rows.length === 0 ? (
+				<EmptyPanel
+					icon="sparkle"
+					message={
+						result.status === 'empty'
+							? 'Gift orders appear once the subscriptions provider is configured.'
+							: 'No gift orders found.'
+					}
+				/>
+			) : (
+				<>
+					{page && (
+						<div className="kicker" style={{ marginBottom: 14, color: 'var(--ink-muted)' }}>
+							{page.summary.redeemed} claimed · {page.summary.pendingClaim} pending · {page.total}{' '}
+							total
+						</div>
+					)}
+					<div style={{ overflowX: 'auto' }}>
+						<table className="tbl" style={{ minWidth: 640 }}>
+							<thead>
+								<tr>
+									<th>Recipient</th>
+									<th>Gifter</th>
+									<th>Plan</th>
+									<th>Status</th>
+								</tr>
+							</thead>
+							<tbody>
+								{rows.map((g) => (
+									<tr key={g.id}>
+										<td>
+											<div style={{ fontSize: 13, fontWeight: 600, color: 'var(--ink)' }}>
+												{g.recipientName || g.recipientEmail}
+											</div>
+											{g.recipientName && (
+												<div style={{ fontSize: 12, color: 'var(--ink-muted)' }}>
+													{g.recipientEmail}
+												</div>
+											)}
+										</td>
+										<td style={{ fontSize: 12.5, color: 'var(--ink-muted)' }}>{g.gifterEmail}</td>
+										<td>
+											<span className="type-tag">
+												{g.planType} · {g.durationDays}d
+											</span>
+										</td>
+										<td>
+											<GiftStatusBadge redeemedAt={g.redeemedAt} status={g.status} />
+										</td>
+									</tr>
+								))}
+							</tbody>
+						</table>
+					</div>
+				</>
+			)}
+		</div>
+	)
+}
+
+function GiftStatusBadge({ redeemedAt, status }: { redeemedAt: number | null; status: string }) {
+	const claimed = redeemedAt !== null
+	return (
+		<span className={`pill ${claimed ? 'published' : 'review'}`}>
+			<span className="pdot" />
+			{claimed ? 'Claimed' : status === 'pending' ? 'Unclaimed' : status}
+		</span>
+	)
+}
+
+// ---------------------------------------------------------------------------
+// LemonSqueezySyncPanel — triggers the privileged import + shows the summary
+// ---------------------------------------------------------------------------
+
+interface SyncState {
+	running: boolean
+	summary: LsImportSummary | null
+	error: string | null
+}
+
+function LemonSqueezySyncPanel() {
+	const [s, setS] = useState<SyncState>({ running: false, summary: null, error: null })
+
+	const runSync = useCallback(async (dryRun: boolean) => {
+		setS({ running: true, summary: null, error: null })
+		try {
+			const res = await fetch(`/admin/api/subscriptions?type=import-ls&dryRun=${dryRun}`, {
+				method: 'POST',
+			})
+			if (!res.ok) {
+				setS({ running: false, summary: null, error: `${res.status} ${res.statusText}` })
+				return
+			}
+			const body = (await res.json()) as ProviderResult<LsImportSummary>
+			setS({ running: false, summary: body.data, error: null })
+		} catch (err) {
+			setS({ running: false, summary: null, error: String(err) })
+		}
+	}, [])
+
+	return (
+		<div className="panel panel-pad" style={{ marginBottom: 'var(--gap)' }}>
+			<div className="card-title">LemonSqueezy sync</div>
+			<div className="page-sub" style={{ margin: '4px 0 0' }}>
+				Pull subscriptions from LemonSqueezy and reconcile users + entitlements. Existing records
+				are updated, new ones created — nothing is deleted.
+			</div>
+			<hr className="masthead-rule" style={{ margin: '12px 0 16px' }} />
+
+			<div style={{ display: 'flex', gap: 8 }}>
+				<button
+					type="button"
+					className="btn"
+					onClick={() => void runSync(true)}
+					disabled={s.running}
+				>
+					Dry run
+				</button>
+				<button
+					type="button"
+					className="btn primary"
+					onClick={() => void runSync(false)}
+					disabled={s.running}
+				>
+					<Icon name="bolt" size={15} />
+					{s.running ? 'Syncing…' : 'Sync all'}
+				</button>
+			</div>
+
+			{s.error && <div style={{ marginTop: 14, fontSize: 13, color: 'var(--red)' }}>{s.error}</div>}
+
+			{s.summary && (
+				<div
+					style={{
+						marginTop: 16,
+						border: '1px solid var(--border)',
+						borderRadius: 'var(--radius)',
+						padding: '14px 16px',
+						background: 'var(--panel-2)',
+					}}
+				>
+					<div className="kicker" style={{ marginBottom: 8 }}>
+						{s.summary.dryRun ? 'Dry run preview' : 'Sync complete'}
+					</div>
+					{s.summary.synced === 0 &&
+					s.summary.usersCreated === 0 &&
+					s.summary.usersUpdated === 0 ? (
+						<div style={{ fontSize: 13, color: 'var(--ink-muted)' }}>
+							Nothing to sync — the subscriptions provider returned no records.
+						</div>
+					) : (
+						<div
+							style={{
+								display: 'flex',
+								flexWrap: 'wrap',
+								gap: '6px 18px',
+								fontSize: 13,
+								color: 'var(--ink-soft)',
+							}}
+						>
+							<span>
+								<strong className="tnum">{s.summary.synced}</strong> synced
+							</span>
+							<span>
+								<strong className="tnum">{s.summary.usersCreated}</strong> users created
+							</span>
+							<span>
+								<strong className="tnum">{s.summary.usersUpdated}</strong> users updated
+							</span>
+							<span>
+								<strong className="tnum">{s.summary.subscriptionsCreated}</strong> subs created
+							</span>
+							<span>
+								<strong className="tnum">{s.summary.subscriptionsUpdated}</strong> subs updated
+							</span>
+						</div>
+					)}
+				</div>
+			)}
+		</div>
+	)
+}
+
+// ---------------------------------------------------------------------------
+// KPI cards — 4 cards: Active / MRR / Churn / LTV
+// ---------------------------------------------------------------------------
+
+const KPI_DEFS: Array<{
+	key: string
+	label: string
+	fmt: 'num' | 'pct' | 'usd'
+}> = [
+	{ key: 'active', label: 'Active subscribers', fmt: 'num' },
+	{ key: 'mrr', label: 'Monthly recurring', fmt: 'usd' },
+	{ key: 'churn', label: 'Churn', fmt: 'pct' },
+	{ key: 'ltv', label: 'Avg. LTV', fmt: 'usd' },
+]
+
+function KpiCards({ kpis }: { kpis: ProviderResult<Record<string, number | null>> }) {
+	const kpiStatus = selectKpiState(kpis)
+
+	if (kpiStatus === 'empty') {
+		return (
+			<div style={{ marginBottom: 'var(--gap)' }}>
+				<EmptyPanel
+					icon="users"
+					message="No subscription data yet — configure the subscriptions provider."
+				/>
+			</div>
+		)
+	}
+
+	return (
+		<div className="grid-stats" style={{ marginBottom: 'var(--gap)' }}>
+			{KPI_DEFS.map((def) => {
+				const raw = kpis.data?.[def.key] ?? null
+				const formatted = formatKpi(raw, def.fmt)
+				const isPending =
+					formatted !== null && typeof formatted === 'object' && (formatted as KpiPending).pending
+
+				const displayValue = isPending ? null : (formatted as string)
+				const displayNote = isPending ? '— pending backfill' : null
+
+				return (
+					<KpiCard
+						key={def.key}
+						label={def.label}
+						status={isPending ? 'partial' : kpiStatus}
+						value={displayValue}
+						note={displayNote}
+					/>
+				)
+			})}
+		</div>
+	)
+}
+
+function KpiCard({
+	label,
+	status,
+	value,
+	note,
+}: {
+	label: string
+	status: 'live' | 'partial' | 'empty'
+	value: string | null
+	note: string | null
+}) {
+	return (
+		<div className="panel panel-pad">
+			<div className="kicker">{label}</div>
+			<div
+				className="serif tnum"
+				style={{
+					fontSize: 30,
+					fontWeight: 600,
+					color: 'var(--ink)',
+					margin: '6px 0 4px',
+					whiteSpace: 'nowrap',
+				}}
+			>
+				{status === 'empty' || value === null ? (
+					<span style={{ fontSize: 18, color: 'var(--ink-muted)' }}>—</span>
+				) : (
+					value
+				)}
+			</div>
+			{note && <span style={{ fontSize: 12, color: 'var(--ink-faint)' }}>{note}</span>}
+			{status === 'partial' && !note && (
+				<span className="kicker" style={{ color: 'var(--amber)' }}>
+					Partial
+				</span>
+			)}
+		</div>
+	)
+}
+
+// ---------------------------------------------------------------------------
+// PlanMixChart — stacked bar + legend rows (aside panel)
+// ---------------------------------------------------------------------------
+
+const PLAN_DOT_COLORS = ['#1f6b4a', '#0c4a6e', '#5b4bc4', '#8c6d14', '#475569']
+
+function PlanMixChart({
+	planMix,
+	resolvePlanName,
+}: {
+	planMix: ProviderResult<PlanMixBucket[]>
+	resolvePlanName: (id: string) => string
+}) {
+	if (!planMix.data || planMix.data.length === 0) return null
+
+	const bars = planMixToBars(planMix.data, resolvePlanName)
+	const colorFor = (i: number) => PLAN_DOT_COLORS[i % PLAN_DOT_COLORS.length]
+
+	return (
+		<div className="panel panel-pad">
+			<div className="card-title" style={{ marginBottom: 16 }}>
+				Plan mix
+			</div>
+			{planMix.status === 'partial' && (
+				<div className="kicker" style={{ color: 'var(--amber)', marginBottom: 12 }}>
+					Partial data
+				</div>
+			)}
+			<div
+				style={{
+					display: 'flex',
+					height: 10,
+					borderRadius: 6,
+					overflow: 'hidden',
+					marginBottom: 18,
+				}}
+			>
+				{bars.map((bar, i) => (
+					<span key={bar.name} style={{ width: `${bar.pct}%`, background: colorFor(i) }} />
+				))}
+			</div>
+			{bars.map((bar, i) => (
+				<div
+					key={bar.name}
+					style={{
+						display: 'flex',
+						alignItems: 'center',
+						gap: 10,
+						padding: '9px 0',
+						borderBottom: '1px solid var(--border-soft)',
+					}}
+				>
+					<span style={{ width: 9, height: 9, borderRadius: 2, background: colorFor(i) }} />
+					<span style={{ flex: 1, fontSize: 13, fontWeight: 600, color: 'var(--ink)' }}>
+						{bar.name}
+					</span>
+					<span className="tnum" style={{ fontSize: 12.5, color: 'var(--ink-muted)' }}>
+						{bar.count.toLocaleString('en-US')}
+					</span>
+					<span
+						className="tnum"
+						style={{
+							fontSize: 12.5,
+							fontWeight: 600,
+							color: 'var(--ink-soft)',
+							width: 54,
+							textAlign: 'right',
+						}}
+					>
+						{bar.pct.toFixed(1)}%
+					</span>
+				</div>
+			))}
+		</div>
+	)
+}
+
+// ---------------------------------------------------------------------------
+// MembersTable
+// ---------------------------------------------------------------------------
+
+function MembersTable({
+	result,
+	resolvePlanName,
+	page,
+	onPageChange,
+}: {
+	result: ProviderResult<SubscriptionMember[]>
+	resolvePlanName: (id: string) => string
+	page: number
+	onPageChange: (p: number) => void
+}) {
+	if (result.status === 'empty') {
+		return (
+			<div style={{ padding: 18 }}>
+				<EmptyPanel
+					icon="users"
+					message="No members yet — configure the subscriptions provider to list members."
+				/>
+			</div>
+		)
+	}
+
+	if (!result.data || result.data.length === 0) {
+		return (
+			<div style={{ padding: 18 }}>
+				<EmptyPanel icon="users" message="No members match this filter." />
+			</div>
+		)
+	}
+
+	const members = result.data
+
+	return (
+		<div>
+			{result.status === 'partial' && (
+				<div
+					className="kicker"
+					style={{
+						padding: '8px 18px',
+						color: 'var(--amber)',
+						background: 'color-mix(in srgb, var(--amber) 7%, transparent)',
+						borderBottom: '1px solid var(--border)',
+					}}
+				>
+					Partial data — some member fields may be incomplete
+				</div>
+			)}
+			<div style={{ overflowX: 'auto' }}>
+				<table className="tbl" style={{ minWidth: 640 }}>
+					<thead>
+						<tr>
+							<th style={{ paddingLeft: 18 }}>Member</th>
+							<th>Plan</th>
+							<th>Status</th>
+							<th>LTV</th>
+						</tr>
+					</thead>
+					<tbody>
+						{members.map((member) => {
+							const planName = member.planVariantId ? resolvePlanName(member.planVariantId) : '—'
+							const email = member.email ?? '(no email)'
+							const initials = initialsFor(email)
+							// LTV: not on SubscriptionMember interface — individual member LTV is per-KPI
+							// (only available via getKpis aggregate); render "—" honestly.
+							return (
+								<tr key={member.id}>
+									<td style={{ paddingLeft: 18 }}>
+										<div style={{ display: 'flex', alignItems: 'center', gap: 11 }}>
+											<div
+												className="avatar"
+												style={{
+													background: avatarColor(email),
+													width: 30,
+													height: 30,
+													fontSize: 11,
+												}}
+											>
+												{initials}
+											</div>
+											<div style={{ minWidth: 0 }}>
+												<div
+													style={{
+														fontSize: 13,
+														fontWeight: 600,
+														color: 'var(--ink)',
+														overflow: 'hidden',
+														textOverflow: 'ellipsis',
+														whiteSpace: 'nowrap',
+														maxWidth: 280,
+													}}
+												>
+													{email}
+												</div>
+											</div>
+										</div>
+									</td>
+									<td>
+										<span className="type-tag">{planName}</span>
+									</td>
+									<td>
+										<StatusBadge status={member.status} />
+									</td>
+									<td className="tnum" style={{ color: 'var(--ink-faint)' }}>
+										—
+									</td>
+								</tr>
+							)
+						})}
+					</tbody>
+				</table>
+			</div>
+
+			{/* Pagination */}
+			<div
+				style={{
+					display: 'flex',
+					justifyContent: 'flex-end',
+					alignItems: 'center',
+					gap: 10,
+					padding: '12px 18px',
+				}}
+			>
+				<button
+					type="button"
+					className="btn sm"
+					disabled={page <= 1}
+					onClick={() => onPageChange(page - 1)}
+					style={{ opacity: page <= 1 ? 0.4 : 1 }}
+				>
+					<Icon name="chevLeft" size={14} />
+					Prev
+				</button>
+				<span className="kicker">Page {page}</span>
+				<button
+					type="button"
+					className="btn sm"
+					disabled={members.length === 0}
+					onClick={() => onPageChange(page + 1)}
+					style={{ opacity: members.length === 0 ? 0.4 : 1 }}
+				>
+					Next
+					<Icon name="chevRight" size={14} />
+				</button>
+			</div>
+		</div>
+	)
+}
+
+// ---------------------------------------------------------------------------
+// StatusBadge — broadsheet .pill with leading .pdot
+// ---------------------------------------------------------------------------
+
+// Map provider status → broadsheet pill variant + display label.
+const STATUS_PILL: Record<string, { cls: string; label: string }> = {
+	active: { cls: 'published', label: 'Active' },
+	past_due: { cls: 'review', label: 'Past due' },
+	canceled: { cls: 'draft', label: 'Canceled' },
+	trialing: { cls: 'scheduled', label: 'Trialing' },
+}
+
+function StatusBadge({ status }: { status: string | null }) {
+	const variant = status ? STATUS_PILL[status] : undefined
+	const cls = variant?.cls ?? 'draft'
+	const label = variant?.label ?? status ?? '—'
+	return (
+		<span className={`pill ${cls}`}>
+			<span className="pdot" />
+			{label}
+		</span>
+	)
+}
+
+// ---------------------------------------------------------------------------
+// FilterSegment — broadsheet .seg segmented control
+// ---------------------------------------------------------------------------
+
+function FilterSegment({
+	value,
+	onChange,
+}: {
+	value: FilterOption
+	onChange: (f: FilterOption) => void
+}) {
+	return (
+		<div className="seg">
+			{FILTER_LABELS.map((opt) => (
+				<button
+					key={opt.value}
+					type="button"
+					className={value === opt.value ? 'on' : ''}
+					onClick={() => onChange(opt.value)}
+				>
+					{opt.label}
+				</button>
+			))}
+		</div>
+	)
+}
+
+// ---------------------------------------------------------------------------
+// GiftModal — .scrim + .panel.panel-pad dialog
+// ---------------------------------------------------------------------------
+
+function GiftModal({
+	gift,
+	onChange,
+	onSubmit,
+	onClose,
+}: {
+	gift: GiftState
+	onChange: (field: 'email' | 'planVariantId', value: string) => void
+	onSubmit: () => void
+	onClose: () => void
+}) {
+	const ok = gift.result?.startsWith('Gift created')
+	return (
+		<div
+			className="scrim"
+			style={{ placeItems: 'center', zIndex: 100 }}
+			role="dialog"
+			aria-modal="true"
+			aria-label="Gift subscription"
+			onClick={onClose}
+			onKeyUp={(e) => {
+				if (e.key === 'Escape') onClose()
+			}}
+		>
+			{/* biome-ignore lint/a11y/useKeyWithClickEvents: onClick only stops the backdrop close from bubbling; it is not a user-facing action and needs no keyboard handler. The dialog scrim above owns click-away + Escape. */}
+			<div
+				className="panel panel-pad fade-only"
+				role="document"
+				style={{ width: 420, boxShadow: 'var(--shadow-lg)' }}
+				onClick={(e) => e.stopPropagation()}
+			>
+				<div style={{ display: 'flex', alignItems: 'center', gap: 8, marginBottom: 4 }}>
+					<Icon name="sparkle" size={18} style={{ color: 'var(--accent)' }} />
+					<div className="card-title">Gift subscription</div>
+					<button
+						type="button"
+						className="icon-btn"
+						style={{ marginLeft: 'auto' }}
+						onClick={onClose}
+					>
+						<Icon name="x" size={16} />
+					</button>
+				</div>
+				<hr className="masthead-rule" style={{ margin: '6px 0 18px' }} />
+
+				<label style={{ display: 'block', marginBottom: 16 }}>
+					<span className="field-label">Recipient email</span>
+					<input
+						className="input"
+						type="email"
+						value={gift.email}
+						onChange={(e) => onChange('email', e.target.value)}
+						placeholder="subscriber@example.com"
+					/>
+				</label>
+
+				<label style={{ display: 'block', marginBottom: 16 }}>
+					<span className="field-label">Plan variant ID</span>
+					<input
+						className="input"
+						type="text"
+						value={gift.planVariantId}
+						onChange={(e) => onChange('planVariantId', e.target.value)}
+						placeholder="e.g. variant_123"
+					/>
+				</label>
+
+				{gift.result && (
+					<div
+						style={{
+							fontSize: 12,
+							color: ok ? 'var(--green)' : 'var(--red)',
+							padding: '6px 10px',
+							background: ok
+								? 'color-mix(in srgb, var(--green) 8%, transparent)'
+								: 'color-mix(in srgb, var(--red) 8%, transparent)',
+							borderRadius: 'var(--radius-sm)',
+							marginBottom: 16,
+						}}
+					>
+						{gift.result}
+					</div>
+				)}
+
+				<div style={{ display: 'flex', justifyContent: 'flex-end', gap: 10 }}>
+					<button type="button" className="btn" onClick={onClose}>
+						Cancel
+					</button>
+					<button
+						type="button"
+						className="btn primary"
+						onClick={onSubmit}
+						disabled={gift.submitting || !gift.email || !gift.planVariantId}
+						style={{
+							opacity: gift.submitting || !gift.email || !gift.planVariantId ? 0.5 : 1,
+						}}
+					>
+						{gift.submitting ? 'Gifting…' : 'Send gift'}
+					</button>
+				</div>
+			</div>
+		</div>
+	)
+}
+
+// ---------------------------------------------------------------------------
+// Shared micro-components
+// ---------------------------------------------------------------------------
+
+function EmptyPanel({
+	icon,
+	message,
+}: {
+	icon: Parameters<typeof Icon>[0]['name']
+	message: string
+}) {
+	return (
+		<div
+			style={{
+				border: '1px solid var(--border)',
+				borderRadius: 'var(--radius)',
+				padding: '28px 20px',
+				textAlign: 'center',
+				fontSize: 13,
+				color: 'var(--ink-muted)',
+				background: 'var(--panel-2)',
+				display: 'flex',
+				flexDirection: 'column',
+				alignItems: 'center',
+				gap: 8,
+			}}
+		>
+			<Icon name={icon} size={22} style={{ color: 'var(--border)', opacity: 0.7 }} />
+			<span>{message}</span>
+		</div>
+	)
+}
+
+function PartialBanner({ message }: { message: string }) {
+	return (
+		<div
+			style={{
+				padding: '8px 14px',
+				marginBottom: 'var(--gap)',
+				background: 'color-mix(in srgb, var(--amber) 8%, transparent)',
+				border: '1px solid color-mix(in srgb, var(--amber) 20%, transparent)',
+				borderRadius: 'var(--radius-sm)',
+				fontSize: 12,
+				color: 'var(--amber)',
+				display: 'flex',
+				alignItems: 'center',
+				gap: 7,
+			}}
+		>
+			<Icon name="bolt" size={13} />
+			{message}
+		</div>
+	)
+}
+
+// ---------------------------------------------------------------------------
+// Avatar helpers — derive initials + a stable tint from the member email
+// ---------------------------------------------------------------------------
+
+function initialsFor(email: string): string {
+	const local = email.split('@')[0] ?? email
+	const parts = local.split(/[.\-_+]/).filter(Boolean)
+	if (parts.length >= 2) return (parts[0]![0]! + parts[1]![0]!).toUpperCase()
+	return local.slice(0, 2).toUpperCase()
+}
+
+const AVATAR_COLORS = ['#0c4a6e', '#1f6b4a', '#5b4bc4', '#8c6d14', '#075985', '#475569']
+
+function avatarColor(seed: string): string {
+	let h = 0
+	for (let i = 0; i < seed.length; i++) h = (h * 31 + seed.charCodeAt(i)) >>> 0
+	return AVATAR_COLORS[h % AVATAR_COLORS.length]!
+}