@appinternalleads/ui 0.2.0

package/src/components/onboarding/help-center/HelpCenterView.tsx

@@ -0,0 +1,104 @@
+import { useState } from 'react';
+import { Box, ExternalLink, Icon, Text } from '../../../core';
+import { TypeTile } from '../../../ds';
+import { blockRadii, useDs, type DensityName } from '../../../tokens';
+import { iconFor, resolveConfig, type OnboardingPreset, type OnboardingResult, type PatternStatus } from '../shared/contract';
+import { ONBOARDING_TIMING, type OnboardingOperation } from '../shared/mock';
+import { InvalidConfig } from '../shared/InvalidConfig';
+import { OnboardingCard } from '../shared/OnboardingCard';
+import { Hidden, PlainChip } from '../shared/parts';
+import { runOutcome, useDefaultOperation, usePatternStatus, useSceneReport } from '../shared/runtime';
+import { useOperationRunner } from '../../../runtime/operations';
+import { HELP_PRESETS, validateHelpCenter, type HelpCenterSettings, type HelpScene } from './contract';
+import { guarded } from '../shared/guard';
+
+export type HelpCenterSeed = { support?: 'idle' | 'open' };
+export type HelpCenterOperations = { openSupport: OnboardingOperation<void> };
+
+export type HelpCenterProps = {
+  preset?: OnboardingPreset;
+  config?: Partial<HelpCenterSettings>;
+  density?: DensityName;
+  status?: PatternStatus;
+  result?: OnboardingResult;
+  operations?: HelpCenterOperations;
+  reload?: OnboardingOperation<void>;
+  initial?: HelpCenterSeed;
+  /** A link was followed. */
+  onOpenLink?: (href: string) => void;
+  onScene?: (scene: string) => void;
+  testID?: string;
+};
+
+export function helpSeed(_c: HelpCenterSettings, scene: HelpScene): HelpCenterSeed {
+  return scene === 'support' ? { support: 'open' } : {};
+}
+
+/**
+ * **Help Center** — a stack of link rows: tile, title with an optional plain "New" badge,
+ * description, a visually hidden "(opens in a new tab)" and a trailing external-link glyph. The
+ * footer's only button is the ghost support action: "Contact support" → "Opening…" → "Chat open".
+ */
+function HelpCenterView(props: HelpCenterProps) {
+  const config = resolveConfig(HELP_PRESETS, props.preset, props.config);
+  const issues = validateHelpCenter(config);
+  if (issues.length) return <InvalidConfig title={config.title} issues={issues} testID={props.testID} />;
+  return <Valid {...props} config={config} />;
+}
+
+function Valid({
+  config, density, status, result, operations, reload, initial, onOpenLink, onScene, testID,
+}: Omit<HelpCenterProps, 'config'> & { config: HelpCenterSettings }) {
+  const { colors } = useDs();
+  const pattern = usePatternStatus(status ?? (config.links.length ? 'ready' : 'empty'), reload);
+  const [support, setSupport] = useState<'idle' | 'opening' | 'open'>(initial?.support ?? 'idle');
+  const runner = useOperationRunner();
+  const open = useDefaultOperation(operations?.openSupport, ONBOARDING_TIMING.finish, () => result === 'error');
+  useSceneReport(pattern.status === 'ready' ? (support === 'open' ? 'support' : 'default') : pattern.status, onScene);
+
+  return (
+    <OnboardingCard
+      testID={testID}
+      header={config}
+      copy={config}
+      density={density}
+      status={pattern.status}
+      onRetry={pattern.retry}
+      onEmptyAction={pattern.retry}
+      hint={support === 'open' ? config.supportOpenHint : config.footerNote}
+      secondary={{
+        label: support === 'opening' ? 'Opening…' : support === 'open' ? config.supportOpenLabel : config.supportLabel,
+        disabled: support !== 'idle',
+        onPress: () => {
+          if (support !== 'idle') return;
+          setSupport('opening');
+          runOutcome(runner, 'support', open, undefined, { ok: () => setSupport('open'), fail: () => setSupport('idle') });
+        },
+      }}>
+      <Box role="list" aria-label={config.title} gap="s1" style={{ marginHorizontal: -8 }}>
+        {config.links.map(l => (
+          <Box key={l.href} role="listitem">
+            <ExternalLink
+              href={l.href}
+              onOpen={() => { onOpenLink?.(l.href); onScene?.('opened'); }}
+              style={{ flexDirection: 'row', alignItems: 'center', gap: 12, borderRadius: blockRadii.inset, paddingVertical: 10, paddingHorizontal: 8 }}>
+              <TypeTile icon={iconFor(l.icon)} type={l.type} size={32} />
+              <Box flex={1} style={{ minWidth: 0 }}>
+                <Box row align="center" gap="s2">
+                  <Text variant="caption" color="textPrimary" style={{ fontWeight: '600', fontSize: 13 }}>{l.title}</Text>
+                  {l.badge ? <PlainChip height={20}>{l.badge}</PlainChip> : null}
+                </Box>
+                <Text variant="caption" color="textSecondary" style={{ fontSize: 12 }}>{l.description}</Text>
+                <Hidden>(opens in a new tab)</Hidden>
+              </Box>
+              <Icon name="external" size={16} color={colors.textSecondary} />
+            </ExternalLink>
+          </Box>
+        ))}
+      </Box>
+    </OnboardingCard>
+  );
+}
+
+/** HelpCenter, guarded: a wrong-kind config is refused by name and a render error is caught, never thrown to the page (`shared/guard`). */
+export const HelpCenter = guarded(HelpCenterView, HELP_PRESETS, 'HelpCenter');

package/src/components/onboarding/help-center/contract.ts

@@ -0,0 +1,33 @@
+import type { DataType } from '../../../tokens';
+import type { HeaderConfig, LoadCopy, OnboardingIssue, PresetsFile } from '../shared/contract';
+import presetsJson from './presets.json';
+
+/**
+ * **Help Center (batch 2 §3.5)** — point new users to docs, videos, the community and support.
+ * Every row is a real link that opens in a new tab and says so; there is no coral primary.
+ */
+
+export type HelpLink = { type: DataType; icon: string; title: string; description: string; href: string; badge: string };
+
+export const HELP_SCENES = ['default', 'support', 'loading', 'empty', 'error'] as const;
+export type HelpScene = (typeof HELP_SCENES)[number];
+/** Scenes that are an operation in flight — see `sceneProps`. */
+export const HELP_IN_FLIGHT: readonly string[] = [];
+
+export type HelpCenterSettings = HeaderConfig & LoadCopy & {
+  links: HelpLink[];
+  supportLabel: string;
+  supportOpenLabel: string;
+  supportOpenHint: string;
+  /** "Links open in a new tab". */
+  footerNote: string;
+};
+
+export const HELP_PRESETS = presetsJson as unknown as PresetsFile<HelpCenterSettings>;
+
+export function validateHelpCenter(c: HelpCenterSettings): OnboardingIssue[] {
+  if (!Array.isArray(c.links)) return [{ path: 'links', message: 'links must be a list.' }];
+  const issues: OnboardingIssue[] = [];
+  c.links.forEach((l, i) => { if (!/^https?:\/\//.test(l.href)) issues.push({ path: `links[${i}].href`, message: 'Links must be http(s) URLs.' }); });
+  return issues;
+}

package/src/components/onboarding/help-center/index.ts

@@ -0,0 +1,5 @@
+export {
+  HELP_IN_FLIGHT, HELP_PRESETS, HELP_SCENES, validateHelpCenter,
+  type HelpCenterSettings, type HelpLink, type HelpScene,
+} from './contract';
+export { HelpCenter, helpSeed, type HelpCenterOperations, type HelpCenterProps, type HelpCenterSeed } from './HelpCenterView';

package/src/components/onboarding/help-center/presets.json

@@ -0,0 +1,250 @@
+{
+  "component": "help-center",
+  "baseCopy": {
+    "loadErrorTitle": "Couldn’t load this step",
+    "loadErrorBody": "Nothing was lost. Retry to load it again.",
+    "retryLabel": "Retry",
+    "emptyCta": "Refresh"
+  },
+  "base": {
+    "type": "file",
+    "icon": "lifebuoy",
+    "title": "Get help when you need it",
+    "subtitle": "Guides, videos and people who can answer questions.",
+    "links": [
+      {
+        "type": "file",
+        "icon": "book",
+        "title": "Documentation",
+        "description": "Guides for every feature",
+        "href": "https://example.com/docs",
+        "badge": ""
+      },
+      {
+        "type": "action",
+        "icon": "play",
+        "title": "Video tutorials",
+        "description": "Short walkthroughs, under 5 minutes",
+        "href": "https://example.com/videos",
+        "badge": ""
+      },
+      {
+        "type": "agent",
+        "icon": "users",
+        "title": "Community",
+        "description": "Ask other customers",
+        "href": "https://example.com/community",
+        "badge": ""
+      },
+      {
+        "type": "data",
+        "icon": "pulse",
+        "title": "Status",
+        "description": "Current uptime and incidents",
+        "href": "https://example.com/status",
+        "badge": ""
+      }
+    ],
+    "supportLabel": "Contact support",
+    "supportOpenLabel": "Chat open",
+    "supportOpenHint": "Support chat opened in the corner",
+    "footerNote": "Links open in a new tab",
+    "emptyTitle": "No help resources",
+    "emptyBody": "Your admin hasn’t added any resources yet.",
+    "emptyCta": "Refresh"
+  },
+  "cases": {
+    "case1": {},
+    "case2": {
+      "type": "action",
+      "icon": "code",
+      "title": "Developer resources",
+      "subtitle": "Everything you need to build on the API.",
+      "supportLabel": "Contact developer support",
+      "links": [
+        {
+          "type": "file",
+          "icon": "code",
+          "title": "API reference",
+          "description": "Every endpoint, with examples",
+          "href": "https://example.com/api",
+          "badge": ""
+        },
+        {
+          "type": "action",
+          "icon": "box",
+          "title": "SDKs",
+          "description": "JavaScript, Python and Go",
+          "href": "https://example.com/sdks",
+          "badge": ""
+        },
+        {
+          "type": "data",
+          "icon": "doc",
+          "title": "Changelog",
+          "description": "What changed in each release",
+          "href": "https://example.com/changelog",
+          "badge": "New"
+        },
+        {
+          "type": "schedule",
+          "icon": "pulse",
+          "title": "Status",
+          "description": "API uptime and incidents",
+          "href": "https://example.com/status",
+          "badge": ""
+        }
+      ]
+    },
+    "case3": {
+      "type": "schedule",
+      "icon": "book",
+      "title": "Staff training",
+      "subtitle": "Get your team comfortable in the first week.",
+      "supportLabel": "Call support",
+      "links": [
+        {
+          "type": "file",
+          "icon": "book",
+          "title": "Quick-start guide",
+          "description": "The ten things front desk does daily",
+          "href": "https://example.com/quick-start",
+          "badge": ""
+        },
+        {
+          "type": "action",
+          "icon": "play",
+          "title": "Training videos",
+          "description": "Booking, check-in and billing",
+          "href": "https://example.com/training",
+          "badge": ""
+        },
+        {
+          "type": "data",
+          "icon": "question",
+          "title": "FAQ",
+          "description": "Answers to common questions",
+          "href": "https://example.com/faq",
+          "badge": ""
+        },
+        {
+          "type": "agent",
+          "icon": "phone",
+          "title": "Phone support",
+          "description": "Weekdays, 8am to 6pm",
+          "href": "https://example.com/phone",
+          "badge": ""
+        }
+      ]
+    },
+    "case4": {
+      "type": "agent",
+      "icon": "sparkle",
+      "title": "Get more from your assistant",
+      "subtitle": "Tips from people who use it every day.",
+      "supportLabel": "Talk to a person",
+      "links": [
+        {
+          "type": "agent",
+          "icon": "chat",
+          "title": "Prompting guide",
+          "description": "How to ask for what you want",
+          "href": "https://example.com/prompting",
+          "badge": ""
+        },
+        {
+          "type": "agent",
+          "icon": "sparkle",
+          "title": "Examples",
+          "description": "Real requests that work well",
+          "href": "https://example.com/examples",
+          "badge": ""
+        },
+        {
+          "type": "agent",
+          "icon": "shield",
+          "title": "What it can’t do",
+          "description": "Limits, and why they exist",
+          "href": "https://example.com/limits",
+          "badge": ""
+        },
+        {
+          "type": "action",
+          "icon": "flag",
+          "title": "Report an issue",
+          "description": "Tell us when an answer is wrong",
+          "href": "https://example.com/report",
+          "badge": ""
+        }
+      ]
+    },
+    "case5": {
+      "type": "data",
+      "icon": "cart",
+      "title": "Seller help",
+      "subtitle": "Sell more, with less guesswork.",
+      "supportLabel": "Start live chat",
+      "links": [
+        {
+          "type": "file",
+          "icon": "book",
+          "title": "Seller handbook",
+          "description": "Listings, fees and payouts",
+          "href": "https://example.com/handbook",
+          "badge": ""
+        },
+        {
+          "type": "schedule",
+          "icon": "video",
+          "title": "Webinars",
+          "description": "Live sessions every Thursday",
+          "href": "https://example.com/webinars",
+          "badge": "New"
+        },
+        {
+          "type": "agent",
+          "icon": "chat",
+          "title": "Forum",
+          "description": "Talk to other sellers",
+          "href": "https://example.com/forum",
+          "badge": ""
+        },
+        {
+          "type": "action",
+          "icon": "headset",
+          "title": "Live chat",
+          "description": "Average reply in 4 minutes",
+          "href": "https://example.com/chat",
+          "badge": ""
+        }
+      ]
+    }
+  },
+  "meta": {
+    "case1": {
+      "eyebrow": "Case study 1 · SaaS",
+      "title": "Product help",
+      "scenario": "A new user sees where to go when they get stuck."
+    },
+    "case2": {
+      "eyebrow": "Case study 2 · Platform",
+      "title": "Developer resources",
+      "scenario": "A developer gets the API reference and SDKs. The changelog carries a New badge."
+    },
+    "case3": {
+      "eyebrow": "Case study 3 · Clinic",
+      "title": "Staff training",
+      "scenario": "Clinic staff find training material and a phone line."
+    },
+    "case4": {
+      "eyebrow": "Case study 4 · AI agent",
+      "title": "Assistant tips",
+      "scenario": "A user learns how to get better answers, and where the assistant stops."
+    },
+    "case5": {
+      "eyebrow": "Case study 5 · Marketplace",
+      "title": "Seller help",
+      "scenario": "A new seller gets the handbook, webinars and live chat. Webinars carry a New badge."
+    }
+  }
+}

package/src/components/onboarding/id-verification/IdVerificationView.tsx

@@ -0,0 +1,245 @@
+import { useEffect, useMemo } from 'react';
+import { Box, Icon, Pressable, Text } from '../../../core';
+import { Button, Callout, ProgressBar } from '../../../ds';
+import { blockRadii, useDs, type DensityName } from '../../../tokens';
+import { resolveConfig, type OnboardingPreset, type OnboardingResult, type PatternStatus } from '../shared/contract';
+import { ONBOARDING_TIMING, createMockProgressOperation, type OnboardingOperation, type ProgressOperation } from '../shared/mock';
+import { InvalidConfig } from '../shared/InvalidConfig';
+import { OnboardingCard } from '../shared/OnboardingCard';
+import { Hidden, Slot, Spinner, StatusMark } from '../shared/parts';
+import { runOutcome, useDefaultOperation, usePatternStatus, useSceneReport, useSeededReducer } from '../shared/runtime';
+import { useOperationRunner } from '../../../runtime/operations';
+import { ID_PRESETS, validateIdVerification, type IdVerificationSettings } from './contract';
+import {
+  idSeed, idView, initialIdVerification, placeholderFileName, reduceIdVerification,
+  type CheckMark, type IdSide, type IdVerificationSeed,
+} from './engine';
+import { guarded } from '../shared/guard';
+
+export type IdVerificationOperations = {
+  /**
+   * Take one side — the host's picker or camera, then the upload, reporting progress. The library
+   * never receives or renders the image; a filled slot says "preview hidden".
+   */
+  upload: ProgressOperation<{ side: number; label: string }>;
+  /** Run the quality checks. `{ ok: false }` means a check failed (the config's `failCheck`). */
+  checks?: OnboardingOperation<{ sides: string[] }>;
+  submit: OnboardingOperation<{ docLabel: string }>;
+};
+
+export type IdVerificationProps = {
+  preset?: OnboardingPreset;
+  config?: Partial<IdVerificationSettings>;
+  density?: DensityName;
+  status?: PatternStatus;
+  /** How the default Submit ends. */
+  result?: OnboardingResult;
+  operations?: IdVerificationOperations;
+  reload?: OnboardingOperation<void>;
+  initial?: IdVerificationSeed;
+  onSubmitted?: (docLabel: string) => void;
+  onScene?: (scene: string) => void;
+  testID?: string;
+};
+
+/**
+ * **ID Verification** — one upload slot per side (16:10; three layers that cross-fade, M4: a dashed
+ * button, "Uploading… 40%" over a coral bar, and a neutral placeholder — never the ID itself — with
+ * Replace), the quality checks (a clock, a spinner, a mint check, or an apricot "!" with a bold fix
+ * and "Upload again"), and a status callout (how it works · pending · verified · rejected). Submit
+ * is disabled until every side is up and every check passes.
+ */
+function IDVerificationView(props: IdVerificationProps) {
+  const config = resolveConfig(ID_PRESETS, props.preset, props.config);
+  const issues = validateIdVerification(config);
+  if (issues.length) return <InvalidConfig title={config.title} issues={issues} testID={props.testID} />;
+  return <Valid {...props} config={config} />;
+}
+
+function Valid({
+  config, density, status, result, operations, reload, initial, onSubmitted, onScene, testID,
+}: Omit<IdVerificationProps, 'config'> & { config: IdVerificationSettings }) {
+  const runner = useOperationRunner();
+  const key = JSON.stringify([config, initial ?? null]);
+  const [state, send, ref] = useSeededReducer(
+    reduceIdVerification,
+    () => initialIdVerification(config, initial ?? (config.ship ? idSeed(config, config.ship) : {})),
+    key,
+    () => { config.sides.forEach((_, i) => runner.cancel(`upload-${i}`)); runner.cancel('checks'); runner.cancel('submit'); },
+  );
+  const pattern = usePatternStatus(status ?? 'ready', reload);
+  const v = idView(config, state);
+  useSceneReport(pattern.status === 'ready' ? v.scene : pattern.status, onScene);
+
+  const mockUpload = useMemo(() => createMockProgressOperation<{ side: number; label: string }>({ tickMs: ONBOARDING_TIMING.uploadTick, step: 0.15 }), []);
+  const upload = operations?.upload ?? mockUpload;
+  const checks = useDefaultOperation(operations?.checks, ONBOARDING_TIMING.checks, () => false);
+  const submit = useDefaultOperation(operations?.submit, ONBOARDING_TIMING.claim, () => result === 'error');
+
+  const runChecks = () => runOutcome(runner, 'checks', checks, { sides: config.sides }, {
+    ok: () => send({ type: 'checked', failed: false }),
+    fail: () => send({ type: 'checked', failed: true }),
+  });
+  const runUpload = (side: number) => {
+    runner.run(`upload-${side}`, ctx => upload({ side, label: config.sides[side]! }, {
+      signal: ctx.signal,
+      onProgress: f => send({ type: 'progress', side, pct: Math.round(f * 100) }),
+    }), {
+      onOk: r => {
+        if (!r.ok) { send({ type: 'uploadFailed', side }); return; }
+        send({ type: 'uploaded', side });
+        const next = reduceIdVerification(ref.current, { type: 'uploaded', side });
+        if (next.checks === 'running') runChecks();
+      },
+      onError: () => send({ type: 'uploadFailed', side }),
+    });
+  };
+  const startUpload = (side: number) => {
+    if (v.locked) return;
+    send({ type: 'upload', side });
+    runUpload(side);
+  };
+  const runSubmit = () => runOutcome(runner, 'submit', submit, { docLabel: config.docLabel }, {
+    ok: () => { send({ type: 'submitted' }); onSubmitted?.(config.docLabel); },
+    fail: () => send({ type: 'submitFailed' }),
+  });
+  useEffect(() => {
+    ref.current.sides.forEach((s, i) => { if (s.phase === 'busy') runUpload(i); });
+    if (ref.current.checks === 'running') runChecks();
+    if (ref.current.review === 'submitting') runSubmit();
+  }, [key]);
+
+  const submitting = state.review === 'submitting';
+  return (
+    <OnboardingCard
+      testID={testID}
+      header={config}
+      copy={config}
+      density={density}
+      status={pattern.status}
+      onRetry={pattern.retry}
+      onEmptyAction={pattern.retry}
+      chip={v.chip}
+      hint={v.footerHint}
+      primary={{
+        label: v.primaryLabel,
+        disabled: !v.canSubmit,
+        busy: submitting,
+        onPress: () => { if (!idView(config, ref.current).canSubmit) return; send({ type: 'submit' }); runSubmit(); },
+      }}>
+      <Box gap="s4">
+        <Box row gap="s3">
+          {state.sides.map((s, i) => (
+            <SideSlot key={i} side={s} label={config.sides[i]!} docLabel={config.docLabel} locked={v.locked} onUpload={() => startUpload(i)} />
+          ))}
+          {state.sides.length === 1 ? <Box flex={1} /> : null}
+        </Box>
+        <Box gap="s2">
+          <Text nativeID={`idv-checks-${config.docLabel.replace(/\W/g, '')}`} variant="caption" color="textPrimary" style={{ fontSize: 12, fontWeight: '600' }}>Quality checks</Text>
+          <Box role="list" aria-labelledby={`idv-checks-${config.docLabel.replace(/\W/g, '')}`} gap="s2">
+            {config.checks.map((label, i) => (
+              <CheckRow key={label} label={label} mark={v.checks[i]!} hint={config.failHint} onFix={() => startUpload(config.failSide)} />
+            ))}
+          </Box>
+        </Box>
+        <StatusCallout {...v.callout} onRestart={() => send({ type: 'restart' })} />
+        {state.review === 'failed' ? <Callout alert strong title="Couldn’t submit your document">Nothing was sent. Check your connection, then retry.</Callout> : null}
+        {/* A failed upload is said, not silently emptied — until that side is uploaded again. */}
+        {state.sides.some(x => x.failed) ? (
+          <Callout alert strong title={`Couldn’t upload the ${config.sides.filter((_, i) => state.sides[i]?.failed).join(' and ').toLowerCase()}`}>
+            Nothing was saved. Check your connection, then upload it again.
+          </Callout>
+        ) : null}
+      </Box>
+    </OnboardingCard>
+  );
+}
+
+function SideSlot({ side, label, docLabel, locked, onUpload }: { side: IdSide; label: string; docLabel: string; locked: boolean; onUpload: () => void }) {
+  const { colors } = useDs();
+  /* 16:10, and never shorter than what the slot says — at phone width a half-width slot would
+     otherwise clip its own words. */
+  const frame = { width: '100%' as const, aspectRatio: 16 / 10, minHeight: 116, borderRadius: blockRadii.inset };
+  return (
+    <Box flex={1} gap="s1" style={{ minWidth: 0 }}>
+      <Text variant="caption" color="textPrimary" style={{ fontSize: 12, fontWeight: '600' }}>{label}</Text>
+      <Slot slotKey={side.phase} align="flex-start">
+        {side.phase === 'empty' ? (
+          <Pressable
+            onPress={onUpload}
+            disabled={locked}
+            aria-label={`Upload ${docLabel} · ${label}`}
+            align="center"
+            justify="center"
+            gap="s1"
+            style={{ ...frame, padding: 12, borderWidth: 1, borderStyle: 'dashed', borderColor: colors.hairlineStrong, backgroundColor: colors.surface1 }}>
+            <Icon name="upload" size={18} color={colors.textSecondary} />
+            <Text variant="caption" color="textPrimary" align="center" style={{ fontSize: 12, fontWeight: '600' }}>Drop a file here or click to upload</Text>
+            <Text variant="caption" color="textSecondary" align="center" style={{ fontSize: 12 }}>JPG or PNG · up to 10 MB</Text>
+          </Pressable>
+        ) : null}
+        {side.phase === 'busy' ? (
+          <Box justify="center" gap="s2" aria-busy style={{ ...frame, padding: 16, borderWidth: 1, borderColor: colors.hairlineStrong }}>
+            <Box row justify="space-between">
+              <Text variant="caption" color="textPrimary" style={{ fontSize: 12 }}>Uploading…</Text>
+              <Text variant="caption" color="textPrimary" numeric style={{ fontSize: 12 }}>{`${side.pct}%`}</Text>
+            </Box>
+            <ProgressBar bare tone="accent" label={`Upload ${docLabel} · ${label}`} value={side.pct} max={100} />
+          </Box>
+        ) : null}
+        {side.phase === 'filled' ? (
+          <Box align="center" justify="center" gap="s1" style={{ ...frame, padding: 12, borderWidth: 1, borderColor: colors.hairlineStrong, backgroundColor: colors.surfaceSunken }}>
+            <Box role="img" aria-label={`${label} uploaded · preview hidden`}><Icon name="id-card" size={28} color={colors.textSecondary} /></Box>
+            <Text variant="caption" color="textSecondary" numeric align="center" style={{ fontSize: 12 }}>{placeholderFileName(label)}</Text>
+            <Button variant="secondary" size="xsmall" disabled={locked} aria-label={`Replace ${label}`} onPress={onUpload}>Replace</Button>
+          </Box>
+        ) : null}
+      </Slot>
+    </Box>
+  );
+}
+
+const CHECK_WORD: Record<CheckMark, string> = { pending: ', not checked yet', running: ', checking', pass: ', passed', fail: ', failed' };
+
+function CheckRow({ label, mark, hint, onFix }: { label: string; mark: CheckMark; hint: string; onFix: () => void }) {
+  const { colors } = useDs();
+  return (
+    <Box role="listitem" row align="flex-start" gap="s2">
+      <Box width={18} height={18} align="center" justify="center" style={{ marginTop: 1 }}>
+        <Slot slotKey={mark} align="flex-start">
+          {mark === 'pending' ? <Icon name="clock" size={14} color={colors.textSecondary} /> : null}
+          {mark === 'running' ? <Spinner size={14} /> : null}
+          {mark === 'pass' ? <StatusMark tone="mint" size={18} /> : null}
+          {mark === 'fail' ? <StatusMark tone="apricot" size={18} /> : null}
+        </Slot>
+      </Box>
+      <Box flex={1} gap="s1" style={{ minWidth: 0 }}>
+        <Text variant="caption" style={{ fontSize: 13, color: mark === 'pass' || mark === 'fail' ? colors.textPrimary : colors.textSecondary }}>{label}</Text>
+        <Hidden>{CHECK_WORD[mark]}</Hidden>
+        {mark === 'fail' ? <Text variant="caption" style={{ fontSize: 12, fontWeight: '700', color: colors.status.needsUser }}>{hint}</Text> : null}
+      </Box>
+      {mark === 'fail' ? <Button variant="secondary" size="xsmall" onPress={onFix}>Upload again</Button> : null}
+    </Box>
+  );
+}
+
+/** D9: the review's status — the well (how it works, pending), mint (verified) or apricot (rejected, with Upload again). */
+function StatusCallout({ tone, title, body, onRestart }: { tone: 'plain' | 'mint' | 'apricot'; title: string; body: string; onRestart: () => void }) {
+  const { colors } = useDs();
+  const skin = tone === 'mint' ? { bg: colors.statusBg.executed, ink: colors.status.executed, icon: 'tick' as const }
+    : tone === 'apricot' ? { bg: colors.statusBg.needsUser, ink: colors.status.needsUser, icon: 'alert' as const }
+    : { bg: colors.surfaceSunken, ink: colors.textPrimary, icon: 'clock' as const };
+  return (
+    <Box role="status" row align="flex-start" gap="s2" style={{ paddingVertical: 12, paddingHorizontal: 14, borderRadius: blockRadii.mid, backgroundColor: skin.bg }}>
+      <Box style={{ marginTop: 1 }}><Icon name={skin.icon} size={16} color={skin.ink} /></Box>
+      <Box flex={1} gap="s1" style={{ minWidth: 0 }}>
+        <Text variant="caption" style={{ fontSize: 13, color: skin.ink, fontWeight: tone === 'apricot' ? '700' : '600' }}>{title}</Text>
+        <Text variant="caption" style={{ fontSize: 12, color: skin.ink }}>{body}</Text>
+      </Box>
+      {tone === 'apricot' ? <Button variant="secondary" size="xsmall" onPress={onRestart}>Upload again</Button> : null}
+    </Box>
+  );
+}
+
+/** IDVerification, guarded: a wrong-kind config is refused by name and a render error is caught, never thrown to the page (`shared/guard`). */
+export const IDVerification = guarded(IDVerificationView, ID_PRESETS, 'IDVerification');