@smileid/usesmileid 12.0.0-beta01

package/src/presentation/screen/use_smile_id_instructions_screen.tsx

@@ -0,0 +1,194 @@
+import type { ReactNode } from "react";
+import { StyleSheet, Text, View } from "react-native";
+import { SafeAreaView } from "react-native-safe-area-context";
+import type { UseSmileIDTheme } from "../theme/theme";
+import { useUseSmileIDTheme } from "../theme/theme_context";
+import { UseSmileIDAttribution } from "../components/use_smile_id_attribution";
+import { UseSmileIDBackButton } from "../components/use_smile_id_back_button";
+import { UseSmileIDButton } from "../components/use_smile_id_button";
+import { UseSmileIDInstructionsHero } from "../components/use_smile_id_instructions_hero";
+import { UseSmileIDGuidelineThumbnail } from "../components/use_smile_id_guideline_thumbnail";
+import { SiCaptureGuidelinesIcon } from "../components/icons";
+import { useUseSmileIDLocalizations } from "../../l10n/use_smile_id_localizations_provider";
+import type { InstructionGuideline } from "../flow/model/instruction_guideline";
+import {
+  SELFIE_GUIDELINES,
+  SELFIE_HERO_ANIMATION,
+  type HeroAnimationSource,
+} from "../flow/model/instructions_defaults";
+
+export type UseSmileIDInstructionsScreenProps = {
+  /** Leading title text, rendered in the title-text colour. */
+  readonly titlePrefix?: string;
+  /** Emphasized word, rendered in the primary colour on its own line. */
+  readonly titleEmphasis?: string;
+  /** Lottie hero animation; defaults to the bundled selfie hero. */
+  readonly heroSource?: HeroAnimationSource;
+  /** Capture-guidelines section title (rendered uppercase). */
+  readonly guidelinesSectionTitle?: string;
+  /** Guideline tiles; empty/omitted falls back to `SELFIE_GUIDELINES`. */
+  readonly guidelines?: readonly InstructionGuideline[];
+  readonly showAttribution?: boolean;
+  /** Draw the face-oval ring around the hero animation. */
+  readonly showHeroOval?: boolean;
+  /** Animate the ring's rising green progress fill. */
+  readonly showHeroOvalProgress?: boolean;
+  readonly onContinue?: () => void;
+  readonly onBack?: () => void;
+  readonly theme?: UseSmileIDTheme;
+  /**
+   * Render the bottom continue button via a partner-supplied slot.
+   * Receives `onClick` already bound to `onContinue`. When omitted, the
+   * screen renders the canonical primary `<UseSmileIDButton>`.
+   */
+  readonly continueButton?: (props: { onClick: () => void }) => ReactNode;
+};
+
+/**
+ * Instructions screen: a split annotated title, a hero animation with an
+ * optional face-oval progress ring, a "Capture Guidelines" section with a
+ * reflowing row of thumbnails, and a continue button + optional attribution.
+ */
+export function UseSmileIDInstructionsScreen(
+  props: UseSmileIDInstructionsScreenProps,
+) {
+  const themeFromContext = useUseSmileIDTheme();
+  const theme = props.theme ?? themeFromContext;
+  const localizations = useUseSmileIDLocalizations();
+
+  const titlePrefix =
+    props.titlePrefix ?? localizations.siInstructionsTitlePrefix;
+  const titleEmphasis =
+    props.titleEmphasis ?? localizations.siInstructionsEmphasisSelfie;
+  const guidelinesSectionTitle =
+    props.guidelinesSectionTitle ??
+    localizations.siInstructionsCaptureGuidelines;
+  const guidelines =
+    props.guidelines && props.guidelines.length > 0
+      ? props.guidelines
+      : SELFIE_GUIDELINES;
+  const heroSource = props.heroSource ?? SELFIE_HERO_ANIMATION;
+  const showAttribution = props.showAttribution ?? true;
+  const showHeroOval = props.showHeroOval ?? true;
+  const showHeroOvalProgress = props.showHeroOvalProgress ?? true;
+  const onContinue = props.onContinue ?? (() => {});
+
+  return (
+    <SafeAreaView
+      style={[
+        styles.root,
+        {
+          backgroundColor: theme.colors.background,
+          paddingHorizontal: theme.spacing.large, // 24px content margin
+          paddingVertical: theme.spacing.medium,
+        },
+      ]}
+      testID="si_instructions_screen"
+    >
+      {props.onBack ? (
+        <UseSmileIDBackButton
+          onClick={props.onBack}
+          theme={theme}
+          testID="si_back_button"
+        />
+      ) : null}
+
+      <View style={{ height: theme.spacing.medium }} />
+
+      <Text
+        accessibilityRole="header"
+        style={{ ...theme.typography.pageHeading, fontWeight: "800" }}
+        testID="si_instructions_title"
+      >
+        <Text style={{ color: theme.colors.titleText }}>{titlePrefix}</Text>
+        {/* Force the emphasis onto its own line. */}
+        {"\n"}
+        <Text style={{ color: theme.colors.primary }}>{titleEmphasis}</Text>
+      </Text>
+
+      <View style={{ height: theme.spacing.medium }} />
+
+      <UseSmileIDInstructionsHero
+        source={heroSource}
+        showOval={showHeroOval}
+        showOvalProgress={showHeroOvalProgress}
+        theme={theme}
+      />
+
+      <View
+        style={styles.sectionHeader}
+        testID="si_instructions_guidelines_section_header"
+      >
+        <SiCaptureGuidelinesIcon size={16} color={theme.colors.primary} />
+        <View style={{ width: theme.spacing.extraSmall }} />
+        <Text
+          style={{
+            ...theme.typography.sectionHeading,
+            fontSize: 11,
+            lineHeight: 16.5,
+            letterSpacing: 0.55,
+            fontWeight: "700",
+            color: theme.colors.titleText,
+          }}
+        >
+          {guidelinesSectionTitle.toUpperCase()}
+        </Text>
+      </View>
+
+      <View style={{ height: theme.spacing.medium }} />
+
+      <View
+        style={[styles.guidelinesRow, { rowGap: theme.spacing.medium }]}
+        testID="si_instructions_guidelines_row"
+      >
+        {guidelines.map((guideline) => (
+          <UseSmileIDGuidelineThumbnail
+            key={`${guideline.status}-${guideline.label(localizations)}`}
+            guideline={guideline}
+            theme={theme}
+          />
+        ))}
+      </View>
+
+      <View style={{ height: theme.spacing.large }} />
+
+      <View
+        style={[styles.bottom, { paddingHorizontal: theme.spacing.extraSmall }]}
+      >
+        {props.continueButton ? (
+          props.continueButton({ onClick: onContinue })
+        ) : (
+          <UseSmileIDButton
+            label={localizations.siLabelContinue}
+            onClick={onContinue}
+            variant="primary"
+            theme={theme}
+            testID="si_instructions_continue_button"
+          />
+        )}
+        {showAttribution ? (
+          <>
+            <View style={{ height: theme.spacing.small }} />
+            <UseSmileIDAttribution theme={theme} />
+          </>
+        ) : null}
+      </View>
+    </SafeAreaView>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: { flex: 1 },
+  sectionHeader: {
+    flexDirection: "row",
+    alignItems: "center",
+    paddingStart: 4,
+  },
+  guidelinesRow: {
+    flexDirection: "row",
+    flexWrap: "wrap",
+    // Span the full content width, flush to the edges.
+    justifyContent: "space-between",
+  },
+  bottom: { alignItems: "center" },
+});

package/src/presentation/screen/use_smile_id_permission_screen.tsx

@@ -0,0 +1,52 @@
+import { Text, View } from "react-native";
+import type { UseSmileIDTheme } from "../theme/theme";
+import { useUseSmileIDTheme } from "../theme/theme_context";
+
+export type UseSmileIDPermissionScreenProps = {
+  readonly cameraRationale?: string;
+  readonly onGranted?: () => void;
+  readonly onDenied?: () => void;
+  readonly theme?: UseSmileIDTheme;
+};
+
+/**
+ * Permission screen — requests camera (and optionally microphone)
+ * at the OS level.
+ *
+ * **STUB.** Visual implementation pending — see
+ * `react-native-expo/docs/Architecture.md § Rollout`.
+ */
+export function UseSmileIDPermissionScreen(
+  props: UseSmileIDPermissionScreenProps,
+) {
+  const themeFromContext = useUseSmileIDTheme();
+  const theme = props.theme ?? themeFromContext;
+  return (
+    <View
+      style={{
+        flex: 1,
+        alignItems: "center",
+        justifyContent: "center",
+        backgroundColor: theme.colors.background,
+        padding: theme.spacing.large,
+      }}
+    >
+      <Text
+        style={{
+          ...theme.typography.sectionHeading,
+          color: theme.colors.titleText,
+        }}
+      >
+        UseSmileIDPermissionScreen
+      </Text>
+      <Text
+        style={{
+          ...theme.typography.cardSubTitle,
+          color: theme.colors.cardText,
+        }}
+      >
+        {props.cameraRationale ?? "Camera permission required — stub"}
+      </Text>
+    </View>
+  );
+}

package/src/presentation/screen/use_smile_id_preview_screen.tsx

@@ -0,0 +1,159 @@
+import { useState, type ReactNode } from "react";
+import { StyleSheet, Text, View, type LayoutChangeEvent } from "react-native";
+import { SafeAreaView } from "react-native-safe-area-context";
+import type { UseSmileIDTheme } from "../theme/theme";
+import { useUseSmileIDTheme } from "../theme/theme_context";
+import { UseSmileIDAttribution } from "../components/use_smile_id_attribution";
+import { UseSmileIDCapturedImageOval } from "../components/use_smile_id_captured_image_oval";
+import { UseSmileIDCardSurface } from "../components/use_smile_id_card_surface";
+import { UseSmileIDConfirmationButtons } from "../components/use_smile_id_confirmation_buttons";
+import { useUseSmileIDLocalizations } from "../../l10n/use_smile_id_localizations_provider";
+import { resolvePreviewState } from "./helpers/preview_screen_helpers";
+
+export type UseSmileIDPreviewScreenProps = {
+  readonly capturedSelfiePath?: string;
+  readonly allowRetake?: boolean;
+  readonly showAttribution?: boolean;
+  readonly onAccept?: () => void;
+  readonly onReject?: () => void;
+  /**
+   * Render the Accept button via a partner-supplied slot.
+   *
+   * **Slot contract:** providing *any* slot (continue or cancel)
+   * replaces the *entire* default confirmation row. If you supply
+   * `continueButton` and want a Retake control too, supply
+   * `cancelButton` as well — the default Retake tile does not
+   * fall through.
+   */
+  readonly continueButton?: (props: { onClick: () => void }) => ReactNode;
+  /**
+   * Render the Reject (retake) button via a partner-supplied slot.
+   * See the slot contract note on `continueButton`.
+   */
+  readonly cancelButton?: (props: { onClick: () => void }) => ReactNode;
+  readonly theme?: UseSmileIDTheme;
+};
+
+/**
+ * Preview screen — confirms the captured selfie before submission.
+ *
+ *   - Uniform light page with the captured image clipped to the face
+ *     oval. The oval scales to the leftover height above the card so
+ *     the two never overlap; no scrim is painted.
+ *   - Bottom card (white, rounded, soft upward shadow) with the title
+ *     "Confirm image quality", a caption, and the Retake / Confirm
+ *     tiles.
+ *   - Attribution sits centered below the card.
+ */
+export function UseSmileIDPreviewScreen(props: UseSmileIDPreviewScreenProps) {
+  const themeFromContext = useUseSmileIDTheme();
+  const theme = props.theme ?? themeFromContext;
+  const loc = useUseSmileIDLocalizations();
+  const showAttribution = props.showAttribution ?? true;
+  const state = resolvePreviewState(props);
+  const [screen, setScreen] = useState<{ width: number; height: number }>({
+    width: 0,
+    height: 0,
+  });
+
+  const onScreenLayout = (event: LayoutChangeEvent) => {
+    const { width, height } = event.nativeEvent.layout;
+    // Re-measure on rotation / split-screen so the oval geometry
+    // recomputes against the new bounds rather than freezing on the
+    // first measurement.
+    setScreen({ width, height });
+  };
+
+  const handleAccept = () => {
+    // The preview is only reached once a capture exists, so Accept is
+    // always actionable — no per-press capture guard.
+    props.onAccept?.();
+  };
+  const handleReject = () => {
+    if (state.canRetake) props.onReject?.();
+  };
+
+  const customContinue = props.continueButton;
+  const customCancel = props.cancelButton;
+  const hasSlots = Boolean(customContinue || customCancel);
+
+  return (
+    <SafeAreaView
+      style={[
+        styles.root,
+        { backgroundColor: theme.colors.captureReviewBackground },
+      ]}
+      testID="si_preview_screen"
+      onLayout={onScreenLayout}
+    >
+      <UseSmileIDCapturedImageOval
+        screenWidth={screen.width}
+        screenHeight={screen.height}
+        {...(state.hasImage && props.capturedSelfiePath
+          ? { uri: props.capturedSelfiePath }
+          : {})}
+        imageTestID="si_preview_image"
+        imageAccessibilityLabel={loc.siPreviewAccessibilityImage}
+        theme={theme}
+      />
+
+      <UseSmileIDCardSurface theme={theme} style={styles.card}>
+        <Text
+          accessibilityRole="header"
+          style={{
+            ...theme.typography.cardHeading,
+            color: theme.colors.primary,
+            textAlign: "center",
+            letterSpacing: -0.425,
+          }}
+        >
+          {loc.siPreviewTitle}
+        </Text>
+        <Text
+          style={{
+            ...theme.typography.cardCaption,
+            color: theme.colors.cardText,
+            textAlign: "center",
+            marginTop: theme.spacing.extraSmall / 2,
+          }}
+        >
+          {loc.siPreviewSubtitle}
+        </Text>
+        <View style={{ marginTop: theme.spacing.medium }}>
+          {hasSlots ? (
+            <View style={styles.buttonRow}>
+              {customCancel ? customCancel({ onClick: handleReject }) : null}
+              {customContinue
+                ? customContinue({ onClick: handleAccept })
+                : null}
+            </View>
+          ) : (
+            <UseSmileIDConfirmationButtons
+              onAccept={handleAccept}
+              onReject={handleReject}
+              acceptLabel={loc.siPreviewConfirm}
+              rejectLabel={loc.siPreviewRetake}
+              theme={theme}
+              testID="si_preview_confirmation_buttons"
+            />
+          )}
+        </View>
+      </UseSmileIDCardSurface>
+
+      {showAttribution ? (
+        <UseSmileIDAttribution forceLightMode theme={theme} />
+      ) : null}
+    </SafeAreaView>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: { flex: 1, overflow: "hidden" },
+  card: { alignItems: "center" },
+  buttonRow: {
+    flexDirection: "row",
+    alignSelf: "stretch",
+    justifyContent: "space-between",
+    alignItems: "center",
+  },
+});

package/src/presentation/screen/use_smile_id_processing_screen.tsx

@@ -0,0 +1,223 @@
+import { useState, type ReactNode } from "react";
+import { StyleSheet, View, type LayoutChangeEvent } from "react-native";
+import { SafeAreaView } from "react-native-safe-area-context";
+import type { UseSmileIDTheme } from "../theme/theme";
+import { useUseSmileIDTheme } from "../theme/theme_context";
+import type { DocumentOrientation } from "../../core/models/document_type";
+import { UseSmileIDAttribution } from "../components/use_smile_id_attribution";
+import { UseSmileIDCapturedDocumentImage } from "../components/use_smile_id_captured_document_image";
+import { UseSmileIDCapturedImageOval } from "../components/use_smile_id_captured_image_oval";
+import { UseSmileIDCardSurface } from "../components/use_smile_id_card_surface";
+import { UseSmileIDFailedContent } from "../components/use_smile_id_failed_content";
+import { UseSmileIDLoadingContent } from "../components/use_smile_id_loading_content";
+import { UseSmileIDStatusIndicator } from "../components/use_smile_id_status_indicator";
+import { UseSmileIDSuccessContent } from "../components/use_smile_id_success_content";
+import type { StatusIndicatorState } from "../components/status_indicator_state";
+import { useUseSmileIDLocalizations } from "../../l10n/use_smile_id_localizations_provider";
+import type { ProcessingState } from "../state/processing_state";
+
+// Re-export so this file's public API is unchanged; the type moved to
+// state/processing_state.ts to break a component-to-screen cycle.
+export type { ProcessingState } from "../state/processing_state";
+
+export type UseSmileIDProcessingScreenProps = {
+  readonly state: ProcessingState;
+  readonly capturedSelfiePath?: string;
+  /**
+   * Render the captured image inside the face oval (default true).
+   * False (Enhanced KYC, BVN — nothing captured) centres the status
+   * badge in the region instead.
+   */
+  readonly showFaceOval?: boolean;
+  /**
+   * Captured front-document URI. When set it supersedes the selfie oval — the
+   * document renders at its capture aspect with the status badge centered over
+   * it (document-job variant).
+   */
+  readonly documentImageUri?: string;
+  /** Capture orientation for {@link documentImageUri}. Defaults to landscape. */
+  readonly documentOrientation?: DocumentOrientation;
+  readonly showProgressPercentage?: boolean;
+  readonly showAttribution?: boolean;
+  readonly onContinue?: () => void;
+  readonly onRetry?: () => void;
+  readonly onExit?: () => void;
+  /**
+   * Render the Continue button via a partner-supplied slot.
+   * Slot contract: title + message always render; each slot replaces
+   * only its own button (override Retry without losing the default Exit).
+   */
+  readonly continueButton?: (props: { onClick: () => void }) => ReactNode;
+  /** Render the Retry button via a partner-supplied slot. See the
+   * slot contract on `continueButton`. */
+  readonly retryButton?: (props: { onClick: () => void }) => ReactNode;
+  /** Render the Exit button via a partner-supplied slot. See the
+   * slot contract on `continueButton`. */
+  readonly exitButton?: (props: { onClick: () => void }) => ReactNode;
+  readonly theme?: UseSmileIDTheme;
+};
+
+/** Map the lifecycle state to the in-oval badge state. */
+function statusStateFor(kind: ProcessingState["kind"]): StatusIndicatorState {
+  switch (kind) {
+    case "loading":
+      return "loading";
+    case "success":
+      return "success";
+    case "failed":
+      return "failure";
+  }
+}
+
+/**
+ * Processing screen — submission-status surface holding the captured
+ * selfie in the face oval, switching the in-oval status badge and card
+ * body by lifecycle state (loading / success+Continue / failed+Retry-Exit).
+ * The oval scales to the leftover height above the card so the two never overlap.
+ */
+export function UseSmileIDProcessingScreen(
+  props: UseSmileIDProcessingScreenProps,
+) {
+  const themeFromContext = useUseSmileIDTheme();
+  const theme = props.theme ?? themeFromContext;
+  const loc = useUseSmileIDLocalizations();
+  const showAttribution = props.showAttribution ?? true;
+  const showFaceOval = props.showFaceOval ?? true;
+
+  const [screen, setScreen] = useState<{ width: number; height: number }>({
+    width: 0,
+    height: 0,
+  });
+  const onScreenLayout = (event: LayoutChangeEvent) => {
+    setScreen({
+      width: event.nativeEvent.layout.width,
+      height: event.nativeEvent.layout.height,
+    });
+  };
+
+  const hasImage =
+    typeof props.capturedSelfiePath === "string" &&
+    props.capturedSelfiePath.length > 0;
+  const hasDocumentImage =
+    typeof props.documentImageUri === "string" &&
+    props.documentImageUri.length > 0;
+
+  const customContinue = props.continueButton;
+  const customRetry = props.retryButton;
+  const customExit = props.exitButton;
+
+  return (
+    <SafeAreaView
+      style={[
+        styles.root,
+        { backgroundColor: theme.colors.captureReviewBackground },
+      ]}
+      testID="si_processing_screen"
+      onLayout={onScreenLayout}
+    >
+      {hasDocumentImage ? (
+        <UseSmileIDCapturedDocumentImage
+          orientation={props.documentOrientation ?? "Landscape"}
+          {...(props.documentImageUri ? { uri: props.documentImageUri } : {})}
+          imageTestID="si_processing_document_image"
+          imageAccessibilityLabel={loc.siCdCapturedImage}
+          overlayChild={
+            <UseSmileIDStatusIndicator
+              state={statusStateFor(props.state.kind)}
+              theme={theme}
+              testID="si_processing_center_indicator"
+            />
+          }
+          theme={theme}
+        />
+      ) : showFaceOval ? (
+        <UseSmileIDCapturedImageOval
+          screenWidth={screen.width}
+          screenHeight={screen.height}
+          {...(hasImage && props.capturedSelfiePath
+            ? { uri: props.capturedSelfiePath }
+            : {})}
+          imageTestID="si_processing_image"
+          imageAccessibilityLabel={loc.siCdCapturedImage}
+          overlayChild={
+            <UseSmileIDStatusIndicator
+              state={statusStateFor(props.state.kind)}
+              theme={theme}
+              testID="si_processing_center_indicator"
+            />
+          }
+          theme={theme}
+        />
+      ) : (
+        <View style={styles.noOvalRegion} testID="si_processing_no_oval_region">
+          <UseSmileIDStatusIndicator
+            state={statusStateFor(props.state.kind)}
+            theme={theme}
+            testID="si_processing_center_indicator"
+          />
+        </View>
+      )}
+
+      <UseSmileIDCardSurface theme={theme} style={styles.card}>
+        {props.state.kind === "loading" ? (
+          <UseSmileIDLoadingContent
+            theme={theme}
+            testID="si_processing_loading_content"
+          />
+        ) : null}
+        {props.state.kind === "success" ? (
+          <UseSmileIDSuccessContent
+            theme={theme}
+            {...(hasDocumentImage
+              ? { title: loc.siDocumentProcessingComplete }
+              : {})}
+            {...(props.state.message !== undefined
+              ? { message: props.state.message }
+              : {})}
+            {...(props.onContinue && !customContinue
+              ? { onContinue: props.onContinue }
+              : {})}
+            testID="si_processing_success_content"
+          />
+        ) : null}
+        {props.state.kind === "failed" ? (
+          <UseSmileIDFailedContent
+            theme={theme}
+            {...(props.state.errorMessage !== undefined
+              ? { errorMessage: props.state.errorMessage }
+              : {})}
+            {...(props.onRetry && !customRetry
+              ? { onRetry: props.onRetry }
+              : {})}
+            {...(props.onExit && !customExit ? { onExit: props.onExit } : {})}
+            testID="si_processing_failed_content"
+          />
+        ) : null}
+        {props.state.kind === "success" && customContinue && props.onContinue
+          ? customContinue({ onClick: props.onContinue })
+          : null}
+        {props.state.kind === "failed" && (customRetry || customExit) ? (
+          <View style={[styles.actionStack, { gap: theme.spacing.small }]}>
+            {customRetry && props.onRetry
+              ? customRetry({ onClick: props.onRetry })
+              : null}
+            {customExit && props.onExit
+              ? customExit({ onClick: props.onExit })
+              : null}
+          </View>
+        ) : null}
+      </UseSmileIDCardSurface>
+
+      {showAttribution ? (
+        <UseSmileIDAttribution forceLightMode theme={theme} />
+      ) : null}
+    </SafeAreaView>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: { flex: 1, overflow: "hidden" },
+  noOvalRegion: { flex: 1, alignItems: "center", justifyContent: "center" },
+  card: { alignItems: "center" },
+  actionStack: { alignSelf: "stretch" },
+});

package/src/presentation/state/__tests__/use_smile_id_overlay_state.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import {
+  isDirectional,
+  OVERLAY_STATE_COUNT,
+  UseSmileIDOverlayState,
+} from "../use_smile_id_overlay_state";
+
+describe("UseSmileIDOverlayState", () => {
+  it("pins the total state count so additions/drops surface at PR time", () => {
+    expect(Object.keys(UseSmileIDOverlayState).length).toBe(
+      OVERLAY_STATE_COUNT,
+    );
+  });
+});
+
+describe("isDirectional", () => {
+  it("is true exactly for the four MOVE_* hints", () => {
+    const directional = Object.values(UseSmileIDOverlayState).filter((state) =>
+      isDirectional(state),
+    );
+    expect(new Set(directional)).toEqual(
+      new Set([
+        UseSmileIDOverlayState.MOVE_LEFT,
+        UseSmileIDOverlayState.MOVE_RIGHT,
+        UseSmileIDOverlayState.MOVE_UP,
+        UseSmileIDOverlayState.MOVE_DOWN,
+      ]),
+    );
+  });
+});

package/src/presentation/state/processing_state.ts

@@ -0,0 +1,19 @@
+/**
+ * Processing screen lifecycle state.
+ *
+ *   - `loading`  — submission in flight; show spinner + "Submitting…"
+ *   - `success`  — server accepted; show ✓ + title/message + Continue
+ *   - `failed`   — server / network rejected; show ✕ + reason + Retry/Exit
+ *
+ * Discriminated union so the rendering code branches exhaustively
+ * (TypeScript narrows on `state.kind`).
+ *
+ * Lives in its own leaf module — the screen and the in-oval indicator
+ * both depend on this type, and putting it on the screen would create
+ * a cycle (screen → indicator → screen for the type). The leaf
+ * placement is the standard fix.
+ */
+export type ProcessingState =
+  | { readonly kind: "loading" }
+  | { readonly kind: "success"; readonly message?: string }
+  | { readonly kind: "failed"; readonly errorMessage?: string };