@oxyhq/services 22.12.4 → 22.13.0

package/src/ui/components/authChooser/SignInRequestView.tsx

@@ -0,0 +1,163 @@
+/**
+ * The ACTIVE REQUEST surface (`qr` view) — the route Oxy chose, plus honest
+ * progress (issue #691, Phase 5).
+ *
+ * The user already performed their one action. From here the surface only
+ * REPORTS: the route-appropriate primary visual (`RequestPrimarySurface`), the
+ * status line derived from the controller's real signals
+ * (`signInProgressLabel`), and nothing else at the same weight. Alternatives
+ * stay behind "Having trouble?" until `signIn.routeFailed` says the chosen route
+ * could not be carried out — the controller never silently cascades, so
+ * revealing them is this view's decision and this view's alone.
+ *
+ * Two surfaces take over when there is no working primary route to report on:
+ *  - a FAILED request, whose reason is toasted by the container (never inline),
+ *    leaves "Try again" as the primary action with the alternatives revealed;
+ *  - a native device with NO Commons installed, where a same-device QR would be
+ *    a dead end. There, "Get Commons" is the genuine primary route — not a
+ *    fallback — so it renders as the one primary action and the QR handoff moves
+ *    behind the disclosure ("I have Commons on another device").
+ */
+
+import type React from 'react';
+import { useState } from 'react';
+import { View } from 'react-native';
+import { Button } from '@oxyhq/bloom/button';
+import { Text } from '@oxyhq/bloom/typography';
+import type { AccountDialogSnapshot } from '@oxyhq/core';
+import TroubleDisclosure, { type TroubleAction } from './TroubleDisclosure';
+import { SubtleLink } from './primitives';
+import { GetCommonsPrompt, RequestPrimarySurface } from './requestSurfaces';
+import { signInProgressLabel } from './signInProgress';
+import { authChooserStyles as styles } from './styles';
+import type { SignInAlternatives, Theme, Translate } from './types';
+
+interface SignInRequestViewProps {
+  snapshot: AccountDialogSnapshot;
+  theme: Theme;
+  t: Translate;
+  /** Restart the request after a failure. */
+  onRetry: () => void;
+  alternatives: SignInAlternatives;
+}
+
+const SignInRequestView: React.FC<SignInRequestViewProps> = ({
+  snapshot,
+  theme,
+  t,
+  onRetry,
+  alternatives,
+}) => {
+  const { signIn, commonsAvailability } = snapshot;
+  // Set only from the disclosure's own "I have Commons on another device" —
+  // an explicit user choice to leave the acquisition surface, never inferred.
+  const [qrRequested, setQrRequested] = useState(false);
+
+  // A ceremony is pointless once the request is already being confirmed, and a
+  // ceremony FAILURE is toasted by the container — this link never renders an
+  // error of its own (owner mandate).
+  const passkeyAction: TroubleAction[] =
+    alternatives.passkeyAvailable && signIn.phase !== 'authorized' && signIn.phase !== 'completed'
+      ? [
+          {
+            key: 'passkey-signin-link',
+            label: alternatives.passkeyPending
+              ? t('accountSwitcher.passkeySigningIn')
+              : t('accountSwitcher.useIdentityOnDevice'),
+            onPress: alternatives.onSignInWithPasskey,
+            disabled: alternatives.passkeyPending,
+          },
+        ]
+      : [];
+
+  const signUpLink = (
+    // Account CREATION is not an authentication method, and on web this surface
+    // is the FIRST one a signed-out user sees (the entry auto-starts straight
+    // through it) — so the way in for someone with no Oxy ID stays visible as a
+    // subordinate link rather than hiding behind a troubleshooting affordance.
+    <SubtleLink
+      label={t('signin.createAccountLink')}
+      theme={theme}
+      onPress={alternatives.onCreateAccount}
+      testID="create-account-link"
+    />
+  );
+
+  if (signIn.phase === 'error') {
+    return (
+      <View style={styles.centeredBlock}>
+        <Button variant="primary" onPress={onRetry} style={styles.primaryButton}>
+          {t('common.actions.tryAgain')}
+        </Button>
+        {signUpLink}
+        <TroubleDisclosure actions={passkeyAction} revealed theme={theme} t={t} />
+      </View>
+    );
+  }
+
+  if (commonsAvailability === 'unavailable' && !qrRequested) {
+    return (
+      <View style={styles.centeredBlock}>
+        <GetCommonsPrompt theme={theme} t={t} onGetCommons={alternatives.onGetCommons} />
+        {signUpLink}
+        <TroubleDisclosure
+          actions={[
+            {
+              key: 'show-qr-anyway-link',
+              label: t('accountSwitcher.showQrAnyway'),
+              onPress: () => setQrRequested(true),
+            },
+            ...passkeyAction,
+          ]}
+          revealed={false}
+          theme={theme}
+          t={t}
+        />
+      </View>
+    );
+  }
+
+  const status = signInProgressLabel(signIn.progress, signIn.route, t);
+  const troubleActions: TroubleAction[] = [
+    // Redundant while the QR already IS the primary surface.
+    ...(signIn.route === 'qr'
+      ? []
+      : [
+          {
+            key: 'scan-qr-link',
+            label: t('accountSwitcher.scanQr'),
+            onPress: alternatives.onShowQr,
+          },
+        ]),
+    ...passkeyAction,
+    {
+      key: 'get-commons-link',
+      label: t('accountSwitcher.getCommons'),
+      onPress: alternatives.onGetCommons,
+    },
+  ];
+
+  return (
+    <View style={styles.centeredBlock}>
+      <RequestPrimarySurface signIn={signIn} theme={theme} t={t} />
+      {status ? (
+        <Text
+          style={[styles.mutedText, { color: theme.colors.textSecondary }]}
+          accessibilityLiveRegion="polite"
+          testID="signin-progress"
+        >
+          {status}
+        </Text>
+      ) : null}
+      {signUpLink}
+      <TroubleDisclosure
+        actions={troubleActions}
+        revealed={signIn.routeFailed}
+        theme={theme}
+        t={t}
+      />
+    </View>
+  );
+};
+
+export default SignInRequestView;

package/src/ui/components/authChooser/SignUpView.tsx

@@ -0,0 +1,174 @@
+/**
+ * Account creation (`signup` view).
+ *
+ * Commons is ALWAYS the priority path (owner mandate) and leads everywhere it
+ * appears: native shows only "Create your identity in Commons" (or "Get Commons"
+ * first, when it is not installed); web on a first-party Oxy origin leads with
+ * the SAME "Get Commons" CTA, with inline passkey creation offered UNDERNEATH as
+ * the de-emphasized "don't want to install anything" alternative — never
+ * co-equal, never a competing button. Anywhere else (a non-Oxy web origin,
+ * before the b2 hub-relay ships) shows an honest "not available here yet"
+ * handoff instead of a broken button.
+ */
+
+import type React from 'react';
+import { useState } from 'react';
+import { TextInput, View } from 'react-native';
+import { Button } from '@oxyhq/bloom/button';
+import { Text } from '@oxyhq/bloom/typography';
+import type { AccountDialogSnapshot, OxyServices } from '@oxyhq/core';
+import { isWebBrowser } from '../../utils/isWebBrowser';
+import { Dividerish, SubtleLink } from './primitives';
+import { authChooserStyles as styles } from './styles';
+import type { PasskeyMode, Theme, Translate } from './types';
+import { useUsernameAvailability, type UsernameStatus } from './useUsernameAvailability';
+
+interface SignUpViewProps {
+  snapshot: AccountDialogSnapshot;
+  theme: Theme;
+  t: Translate;
+  oxyServices: OxyServices;
+  passkeyMode: PasskeyMode;
+  onCreateWithPasskey: (username: string) => void;
+  createPending: boolean;
+  /** Open the auth.oxy.so hub popup (b2) — the 'hub' mode's only path. */
+  onOpenHub: () => void;
+  /** Deep-link into Commons' own identity-creation screen (installed only). */
+  onCreateIdentityInCommons: () => void;
+  /** Open the Commons store listing / landing page for this platform. */
+  onGetCommons: () => void;
+  onBackToSignIn: () => void;
+}
+
+const SignUpView: React.FC<SignUpViewProps> = ({
+  snapshot,
+  theme,
+  t,
+  oxyServices,
+  passkeyMode,
+  onCreateWithPasskey,
+  createPending,
+  onOpenHub,
+  onCreateIdentityInCommons,
+  onGetCommons,
+  onBackToSignIn,
+}) => {
+  const [username, setUsername] = useState('');
+  const { status: usernameStatus, check: checkUsername } = useUsernameAvailability(oxyServices, t);
+  const canSubmit = username.trim().length >= 3 && usernameStatus === 'available' && !createPending;
+
+  // Native — Commons owns identity creation. Deep-link straight in when it is
+  // installed, else lead with the same "Get Commons" acquisition CTA.
+  if (!isWebBrowser()) {
+    const commonsInstalled = snapshot.commonsAvailability === 'available';
+    return (
+      <View style={styles.centeredBlock}>
+        <Button
+          variant="primary"
+          onPress={commonsInstalled ? onCreateIdentityInCommons : onGetCommons}
+          style={styles.primaryButton}
+        >
+          {commonsInstalled ? t('signup.createInCommons') : t('accountSwitcher.getCommons')}
+        </Button>
+        <SubtleLink label={t('signup.backToSignInLink')} theme={theme} onPress={onBackToSignIn} />
+      </View>
+    );
+  }
+
+  // Web, first-party Oxy origin. Commons leads with a "Get Commons" CTA; passkey
+  // creation is the de-emphasized alternative underneath for someone who doesn't
+  // want to install anything — a secondary button introduced by its own "No
+  // Commons?" framing, the same subordination the sign-in surfaces use.
+  if (passkeyMode === 'direct') {
+    return (
+      <View style={styles.signInBlock}>
+        <Text style={[styles.qrHeadline, { color: theme.colors.text }]}>
+          {t('signup.commonsHeadline')}
+        </Text>
+        <Text style={[styles.mutedText, { color: theme.colors.textSecondary }]}>
+          {t('signup.commonsExplainer')}
+        </Text>
+        <Button variant="primary" onPress={onGetCommons} style={styles.primaryButton}>
+          {t('accountSwitcher.getCommons')}
+        </Button>
+
+        <Dividerish theme={theme} label={t('signin.or')} />
+
+        <Text style={[styles.mutedText, { color: theme.colors.textSecondary }]}>
+          {t('signup.passkeyAlternative')}
+        </Text>
+        <TextInput
+          style={[styles.usernameInput, { borderColor: theme.colors.border, color: theme.colors.text }]}
+          placeholder={t('signup.usernamePlaceholder')}
+          placeholderTextColor={theme.colors.textSecondary}
+          value={username}
+          autoCapitalize="none"
+          autoCorrect={false}
+          autoComplete="username"
+          onChangeText={(value) => {
+            setUsername(value);
+            checkUsername(value.trim());
+          }}
+          testID="signup-username-input"
+        />
+        <UsernameStatusText status={usernameStatus} theme={theme} t={t} />
+        <Button
+          variant="secondary"
+          onPress={() => onCreateWithPasskey(username.trim())}
+          disabled={!canSubmit}
+          style={styles.secondaryButton}
+          testID="signup-create-button"
+        >
+          {createPending ? t('signup.creating') : t('signup.createAccount')}
+        </Button>
+        <SubtleLink label={t('signup.backToSignInLink')} theme={theme} onPress={onBackToSignIn} />
+      </View>
+    );
+  }
+
+  // Web, non-Oxy origin (b2): a passkey ceremony cannot run locally here — the
+  // same WebAuthn RP-ID boundary the sign-in surfaces hit — so this opens the
+  // auth.oxy.so hub popup. Completing EITHER a sign-in OR a fresh sign-up there
+  // relays the resulting session back through the SAME poll/socket engine.
+  return (
+    <View style={styles.centeredBlock}>
+      <Text style={[styles.mutedText, { color: theme.colors.textSecondary }]}>
+        {t('signup.hubExplainer')}
+      </Text>
+      <Button variant="primary" onPress={onOpenHub} style={styles.primaryButton}>
+        {t('signup.continueInWindow')}
+      </Button>
+      <SubtleLink label={t('signup.backToSignInLink')} theme={theme} onPress={onBackToSignIn} />
+    </View>
+  );
+};
+
+/** The inline availability verdict. Network FAILURES are toasted, never shown here. */
+const UsernameStatusText: React.FC<{ status: UsernameStatus; theme: Theme; t: Translate }> = ({
+  status,
+  theme,
+  t,
+}) => {
+  if (status === 'idle') return null;
+  if (status === 'checking') {
+    return (
+      <Text style={[styles.mutedText, { color: theme.colors.textSecondary }]}>
+        {t('signup.usernameChecking')}
+      </Text>
+    );
+  }
+  if (status === 'available') {
+    return (
+      <Text style={[styles.mutedText, { color: theme.colors.success }]}>
+        {t('signup.usernameAvailable')}
+      </Text>
+    );
+  }
+  return (
+    <Text style={[styles.mutedText, { color: theme.colors.error }]}>
+      {t('signup.usernameTaken')}
+    </Text>
+  );
+};
+
+export default SignUpView;

package/src/ui/components/authChooser/TroubleDisclosure.tsx

@@ -0,0 +1,81 @@
+/**
+ * The "Having trouble?" progressive disclosure (issue #691, Phase 5).
+ *
+ * The normal sign-in surface presents ONE primary action. Every alternative —
+ * scanning a QR from another device, a passkey on this device, getting Commons,
+ * creating an account — lives here, hidden until the user asks for it or the
+ * chosen primary route fails.
+ *
+ * Two renderings, deliberately not one controlled component:
+ *  - `revealed` (the primary route failed, or there IS no primary route): the
+ *    alternatives ARE the surface's content now, so they render plainly. There
+ *    is nothing left to hide them behind.
+ *  - otherwise: Bloom's own `Collapsible`, whose trigger is the small
+ *    "Having trouble?" affordance.
+ *
+ * Splitting on `revealed` is what keeps the open state where it belongs — inside
+ * Bloom's uncontrolled disclosure — instead of forcing a hand-rolled controlled
+ * copy of it here.
+ */
+
+import type React from 'react';
+import { View } from 'react-native';
+import { Collapsible } from '@oxyhq/bloom/collapsible';
+import { SubtleLink } from './primitives';
+import { authChooserStyles as styles } from './styles';
+import type { Theme, Translate } from './types';
+
+/** One alternative route out of the current surface. Always a subordinate link. */
+export interface TroubleAction {
+  /** Stable identity for the list, and the action's `testID`. */
+  key: string;
+  label: string;
+  onPress: () => void;
+  disabled?: boolean;
+}
+
+interface TroubleDisclosureProps {
+  actions: TroubleAction[];
+  /**
+   * `true` when the primary route could not be carried out (`signIn.routeFailed`)
+   * or the surface has no working primary at all (a failed request). The
+   * alternatives are shown without asking.
+   */
+  revealed: boolean;
+  theme: Theme;
+  t: Translate;
+}
+
+const TroubleDisclosure: React.FC<TroubleDisclosureProps> = ({ actions, revealed, theme, t }) => {
+  if (actions.length === 0) return null;
+
+  const links = (
+    <View style={styles.troubleActions}>
+      {actions.map((action) => (
+        <SubtleLink
+          key={action.key}
+          label={action.label}
+          theme={theme}
+          onPress={action.onPress}
+          disabled={action.disabled}
+          testID={action.key}
+        />
+      ))}
+    </View>
+  );
+
+  if (revealed) return links;
+
+  return (
+    <Collapsible
+      title={t('accountSwitcher.havingTrouble')}
+      style={styles.troubleTrigger}
+      titleStyle={[styles.linkText, { color: theme.colors.textSecondary }]}
+      testID="trouble-disclosure"
+    >
+      {links}
+    </Collapsible>
+  );
+};
+
+export default TroubleDisclosure;

package/src/ui/components/authChooser/primitives.tsx

@@ -0,0 +1,144 @@
+/**
+ * The small presentational building blocks shared across the auth chooser's
+ * views. One responsibility each, no controller access, no side effects — they
+ * take props and render.
+ */
+
+import type React from 'react';
+import { useState } from 'react';
+import { Pressable, View } from 'react-native';
+import { MaterialCommunityIcons } from '@expo/vector-icons';
+import { Avatar } from '@oxyhq/bloom/avatar';
+import { Text } from '@oxyhq/bloom/typography';
+import { BloomColorScope } from '@oxyhq/bloom/theme';
+import type { SwitchableAccount } from '@oxyhq/core';
+import { authChooserStyles as styles } from './styles';
+import { resolveAccentHex, toPreset, type Theme } from './types';
+
+/** Diameter of a row avatar (the sign-in view's account rows). */
+const ROW_AVATAR_SIZE = 40;
+
+type HoverPressableProps = Omit<React.ComponentProps<typeof Pressable>, 'className'> & {
+  baseClassName: string;
+  hoverClassName: string;
+};
+
+/**
+ * A `Pressable` that appends a hover-tint NativeWind token while pointer-hovered.
+ * The Metro web pipeline here does NOT emit NativeWind `hover:` variants, so hover
+ * is driven by RN's cross-platform `onHoverIn`/`onHoverOut` (they fire only on web
+ * via react-native-web; a no-op on native) toggling a plain background token —
+ * the tint stays a NativeWind class, only the trigger is JS.
+ */
+export const HoverPressable: React.FC<HoverPressableProps> = ({
+  baseClassName,
+  hoverClassName,
+  ...rest
+}) => {
+  const [hovered, setHovered] = useState(false);
+  return (
+    <Pressable
+      {...rest}
+      className={hovered ? `${baseClassName} ${hoverClassName}` : baseClassName}
+      onHoverIn={() => setHovered(true)}
+      onHoverOut={() => setHovered(false)}
+    />
+  );
+};
+
+/**
+ * A SUBORDINATE action: a small centred text link, never a button.
+ *
+ * This is the single visual grammar for everything that is not the surface's one
+ * primary action (issue #691) — the sign-up entry, and every alternative revealed
+ * behind "Having trouble?". Keeping them all on one component is what stops an
+ * alternative from quietly growing into a co-equal button again.
+ */
+export const SubtleLink: React.FC<{
+  label: string;
+  theme: Theme;
+  onPress: () => void;
+  disabled?: boolean;
+  testID?: string;
+}> = ({ label, theme, onPress, disabled, testID }) => (
+  <Pressable
+    onPress={onPress}
+    disabled={disabled}
+    accessibilityRole="button"
+    accessibilityLabel={label}
+    style={styles.footerLink}
+    testID={testID}
+  >
+    <Text style={[styles.linkText, { color: theme.colors.textSecondary }]}>{label}</Text>
+  </Pressable>
+);
+
+/** A labelled hairline separating two blocks ("or"). */
+export const Dividerish: React.FC<{ theme: Theme; label: string }> = ({ theme, label }) => (
+  <View style={styles.dividerRow}>
+    <View style={[styles.dividerLine, { backgroundColor: theme.colors.border }]} />
+    <Text style={[styles.dividerText, { color: theme.colors.textSecondary }]}>{label}</Text>
+    <View style={[styles.dividerLine, { backgroundColor: theme.colors.border }]} />
+  </View>
+);
+
+/**
+ * An account row on the sign-in entry — "continue as one of these" rather than a
+ * choice of authentication METHOD, which is why it stays above the primary CTA
+ * instead of behind the trouble disclosure.
+ */
+export const AccountRow: React.FC<{
+  account: SwitchableAccount;
+  theme: Theme;
+  switching: boolean;
+  disabled: boolean;
+  onPress: () => void;
+}> = ({ account, theme, switching, disabled, onPress }) => {
+  const accent = resolveAccentHex(account.color, theme.colors.primary);
+
+  return (
+    <BloomColorScope colorPreset={toPreset(account.color)} asChild>
+      <Pressable
+        style={[
+          styles.accountRow,
+          {
+            borderColor: account.isCurrent ? accent : theme.colors.border,
+            backgroundColor: theme.colors.card,
+          },
+          disabled && !switching ? styles.rowDisabled : null,
+        ]}
+        onPress={onPress}
+        disabled={disabled}
+        accessibilityRole="button"
+        accessibilityState={{ selected: account.isCurrent, disabled }}
+        accessibilityLabel={account.displayName}
+      >
+        <View style={[styles.avatarRing, { borderColor: account.isCurrent ? accent : 'transparent' }]}>
+          <Avatar
+            source={account.avatarUrl ?? undefined}
+            variant="thumb"
+            name={account.displayName}
+            size={ROW_AVATAR_SIZE}
+          />
+        </View>
+        <View style={styles.rowMeta}>
+          <Text style={[styles.rowName, { color: theme.colors.text }]} numberOfLines={1}>
+            {account.displayName}
+          </Text>
+          {account.email ? (
+            <Text style={[styles.rowHandle, { color: theme.colors.textSecondary }]} numberOfLines={1}>
+              {account.email}
+            </Text>
+          ) : null}
+        </View>
+        {switching ? (
+          <MaterialCommunityIcons name="loading" size={20} color={accent} />
+        ) : account.isCurrent ? (
+          <MaterialCommunityIcons name="check-circle" size={20} color={accent} />
+        ) : (
+          <MaterialCommunityIcons name="chevron-right" size={20} color={theme.colors.textSecondary} />
+        )}
+      </Pressable>
+    </BloomColorScope>
+  );
+};

package/src/ui/components/authChooser/requestSurfaces.tsx

@@ -0,0 +1,116 @@
+/**
+ * The PRIMARY visual of an active "Sign in with Oxy" request — one surface per
+ * route, chosen by {@link RequestPrimarySurface} from the controller's own facts.
+ *
+ * Each is a leading visual and nothing else: the status sentence underneath is
+ * owned by `signInProgressLabel`, and the alternatives by `TroubleDisclosure`.
+ * That separation is what keeps exactly one primary action on screen (issue
+ * #691) — a surface here can never grow a competing button.
+ *
+ * Anti-phishing: the QR plate encodes `signIn.qrPayload` and renders NOTHING
+ * derived from it. Application identity, origin, and scopes are resolved
+ * server-side by the approver (Commons), never read out of the payload here.
+ */
+
+import type React from 'react';
+import { View } from 'react-native';
+import { MaterialCommunityIcons } from '@expo/vector-icons';
+import QRCode from 'react-native-qrcode-svg';
+import { Button } from '@oxyhq/bloom/button';
+import { Loading } from '@oxyhq/bloom/loading';
+import { Text } from '@oxyhq/bloom/typography';
+import type { SignInFlowState } from '@oxyhq/core';
+import { authChooserStyles as styles } from './styles';
+import type { Theme, Translate } from './types';
+
+/** High-contrast QR colors — intentionally fixed (NOT themed) for scan reliability. */
+const QR_PLATE_BG = '#FFFFFF';
+const QR_FOREGROUND = '#000000';
+const QR_SIZE = 196;
+/** The leading route glyph, sized to sit where the QR plate otherwise would. */
+const ROUTE_GLYPH_SIZE = 44;
+
+/** The indeterminate leading visual: the request exists but has nothing to show yet. */
+export const PreparingSurface: React.FC = () => <Loading variant="spinner" size="large" />;
+
+/** The leading glyph for a route whose surface is elsewhere (the phone, Commons). */
+export const RouteGlyph: React.FC<{
+  name: keyof typeof MaterialCommunityIcons.glyphMap;
+  color: string;
+}> = ({ name, color }) => (
+  <MaterialCommunityIcons name={name} size={ROUTE_GLYPH_SIZE} color={color} />
+);
+
+/** The cross-device handoff: a headline over the fixed-contrast QR plate. */
+export const QrPlate: React.FC<{ payload: string; theme: Theme; t: Translate }> = ({
+  payload,
+  theme,
+  t,
+}) => (
+  <>
+    <Text style={[styles.qrHeadline, { color: theme.colors.text }]}>
+      {t('accountSwitcher.qrHeadline')}
+    </Text>
+    <View style={styles.qrPlate}>
+      <QRCode value={payload} size={QR_SIZE} backgroundColor={QR_PLATE_BG} color={QR_FOREGROUND} />
+    </View>
+  </>
+);
+
+/**
+ * The acquisition surface. For someone with no Commons at all this is the
+ * GENUINE primary route, not a fallback — a same-device QR they would have to
+ * scan with the very screen showing it is a dead end — so it renders as the
+ * surface's one primary action.
+ */
+export const GetCommonsPrompt: React.FC<{
+  theme: Theme;
+  t: Translate;
+  onGetCommons: () => void;
+}> = ({ theme, t, onGetCommons }) => (
+  <>
+    <Text style={[styles.mutedText, { color: theme.colors.textSecondary }]}>
+      {t('accountSwitcher.commonsNotInstalled')}
+    </Text>
+    <Button
+      variant="primary"
+      onPress={onGetCommons}
+      style={styles.primaryButton}
+      testID="get-commons-button"
+    >
+      {t('accountSwitcher.getCommons')}
+    </Button>
+  </>
+);
+
+/**
+ * The one primary visual for the request's current state.
+ *
+ * Ordered most-terminal-first, so a late-arriving route can never pull the
+ * surface back from "confirming" to a QR the user has already scanned. Every
+ * branch reads only controller facts — there is no local timeline.
+ */
+export const RequestPrimarySurface: React.FC<{
+  signIn: SignInFlowState;
+  theme: Theme;
+  t: Translate;
+}> = ({ signIn, theme, t }) => {
+  if (signIn.progress === 'identity-confirmed') {
+    return <RouteGlyph name="check-circle" color={theme.colors.success} />;
+  }
+  if (signIn.progress === 'confirming-identity') {
+    return <PreparingSurface />;
+  }
+  if (signIn.route === 'qr' && signIn.qrPayload) {
+    return <QrPlate payload={signIn.qrPayload} theme={theme} t={t} />;
+  }
+  if (signIn.route === 'await-push') {
+    return <RouteGlyph name="cellphone-message" color={theme.colors.primary} />;
+  }
+  if (signIn.route === 'open-commons') {
+    return <RouteGlyph name="open-in-app" color={theme.colors.primary} />;
+  }
+  // No route resolved yet (or a route with no payload to render): the request is
+  // being prepared. Honest, and the only state that is not route-specific.
+  return <PreparingSurface />;
+};