@onboarding-yak/react-native 0.0.0-stage → 0.6.1

package/src/index.tsx

@@ -0,0 +1,1087 @@
+import React, { createContext, useContext, useEffect, useRef, useState } from 'react';
+import { AccessibilityInfo, ActivityIndicator, Animated, Easing, Image, Keyboard, KeyboardAvoidingView, Linking, Platform, Pressable, ScrollView, StyleSheet, Text, TextInput, View, useColorScheme, type ImageStyle, type StyleProp, type ViewStyle } from 'react-native';
+import { darkColors, type DarkColors } from './appearance';
+import { CountryPicker, DateWheels, LoaderBlock, NumberEntry, NumberWheel, ProofBlock } from './pickers';
+import type { UnitOption } from './units';
+import { fillTokens, nextVisibleIndex, type MultipleChoice, type ScreenCondition } from './logic';
+import { builtInValues, variableValue, type VariableFormat, type VariableValue } from './variables';
+import { applyVariant, pickFlowVersion, pickVariant, type FlowTest, type ScreenExperiment } from './experiment';
+
+export type { VariableValue } from './variables';
+import { SafeAreaView } from 'react-native-safe-area-context';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+export type EdgeInsets = { top?: number; right?: number; bottom?: number; left?: number };
+export type AxisInsets = { vertical?: number; horizontal?: number };
+export type ScreenTheme = {
+  background?: string;
+  showImage?: boolean;
+  showProgress?: boolean;
+  showTitle?: boolean;
+  showSubtitle?: boolean;
+  showButton?: boolean;
+  showSkip?: boolean;
+  showBack?: boolean;
+  showTerms?: boolean;
+  showLoader?: boolean;
+  showChecklist?: boolean;
+  showCharts?: boolean;
+  showProof?: boolean;
+  gap?: number;
+  margin?: number | AxisInsets;
+  headerPadding?: number | EdgeInsets;
+  bodyPadding?: number | EdgeInsets;
+  footerPadding?: number | EdgeInsets;
+  headerMargin?: AxisInsets;
+  bodyMargin?: AxisInsets;
+  footerMargin?: AxisInsets;
+  align?: 'left' | 'center' | 'right';
+  text?: string;
+  muted?: string;
+  primary?: string;
+  buttonPadding?: number | EdgeInsets;
+  buttonRadius?: number;
+  cardPadding?: number | EdgeInsets;
+  cardRadius?: number;
+  cardBackground?: string;
+  imageFit?: 'cover' | 'contain' | 'fill';
+  imageWidthMode?: 'fill' | 'fixed';
+  imageHeightMode?: 'fill' | 'fixed';
+  imageWidth?: number;
+  imageHeight?: number;
+  imageRadius?: number;
+  imagePadding?: number | EdgeInsets;
+  imageMargin?: AxisInsets;
+  imageBorderWidth?: number;
+  imageBorderColor?: string;
+  /** 'background' fills the screen behind the content, under a tinted overlay. */
+  imagePlacement?: 'inline' | 'background';
+  imageMotion?: 'none' | 'float' | 'rock' | 'pulse' | 'drift';
+  /** Shows an inline image or video inside a phone mockup. */
+  imageFrame?: 'none' | 'iphone' | 'android';
+  overlayColor?: string;
+  overlayOpacity?: number;
+  overlayStyle?: 'solid' | 'gradient';
+  /** Dark-mode color overrides; anything left out is derived from the light colors. */
+  dark?: DarkColors;
+  /** Order of parts in the header and body. Missing parts fall back to their default section. */
+  arrangement?: { header: LayoutPart[]; body: LayoutPart[] };
+  /** Which zone each section sits in. Defaults: header top, footer bottom, body bottom on full-photo screens and top otherwise. */
+  headerAlign?: SectionAlign;
+  bodyAlign?: SectionAlign;
+  footerAlign?: SectionAlign;
+  progress?: 'above' | 'below';
+  progressStyle?: 'segments' | 'bar' | 'dots';
+  skipLabel?: string;
+  backLabel?: string;
+  termsLabel?: string;
+  termsUrl?: string;
+  font?: string;
+  bodyFont?: string;
+  titleSize?: number;
+  bodySize?: number;
+  titleWeight?: 400 | 500 | 700;
+  motion?: Partial<Record<MotionPart, PartMotion>>;
+};
+export type MotionPart = 'image' | 'progress' | 'title' | 'subtitle' | 'answers' | 'cards' | 'button' | 'skip' | 'back' | 'terms';
+export type PartMotion = { enter: 'fade' | 'rise' | 'slide' | 'pop'; duration?: number; delay?: number };
+export type ScreenChart = { id: string; kind: 'bar' | 'line' | 'donut'; title: string; points: { label: string; value: number }[]; hidden?: boolean; motion?: PartMotion };
+export type LayoutPart = 'back' | 'progress' | 'image' | 'loader' | 'title' | 'subtitle' | 'answers' | 'proof' | 'checklist' | 'charts';
+/** Every action except next and complete reaches onAction so the app can make the native request. */
+export type ScreenAction = 'next' | 'complete' | 'requestNotifications' | 'showPaywall' | 'requestTracking' | 'requestLocation' | 'requestCamera' | 'requestPhotos' | 'requestMicrophone' | 'requestContacts' | 'requestHealth' | 'requestBiometrics' | 'requestReview' | 'signUp' | `custom:${string}`;
+/** What onAction returns: nothing or true moves on, false keeps the person on the screen. A Promise makes the flow wait for it. */
+export type ActionResult = void | boolean;
+export type Testimonial = { quote: string; author: string; detail?: string; stars?: number };
+export type Appearance = 'light' | 'dark' | 'system';
+export type SectionAlign = 'top' | 'center' | 'bottom';
+export type FlowScreen = {
+  id: string;
+  kind: 'Welcome' | 'Question' | 'Feature' | 'Permission' | 'Paywall';
+  title: string;
+  subtitle: string;
+  button: string;
+  accent: string;
+  answerType?: 'text' | 'singleChoice';
+  options?: string[];
+  /** Choice questions: allow several picks. The answer joins them with ", ". */
+  multiple?: MultipleChoice;
+  /** Saves this answer under a name later copy can use as {name} or {name|fallback}. */
+  variable?: string;
+  /** How the saved answer is shown when recalled: a currency for money, a style for dates. */
+  variableFormat?: VariableFormat;
+  /** Show this screen only when an earlier choice question's answer matches. */
+  showIf?: ScreenCondition;
+  /** Optional emoji aligned with `options`. Missing or blank means that choice is text only. */
+  optionIcons?: string[];
+  /** Entry hints for written answers, e.g. a number with a unit. */
+  /** Entry for written answers. Wheel: min/max/step/initial. Date: min/max are years; the answer is YYYY-MM-DD. Country: the answer is the English name. */
+  input?: { format: 'text' | 'number' | 'wheel' | 'date' | 'country'; unit?: string; placeholder?: string; min?: number; max?: number; step?: number; initial?: number; /** Other units people can switch to; answers stay in the base unit. */ units?: UnitOption[] };
+  /** A "preparing your plan" moment: a ring fills while each step is checked off. */
+  loader?: { steps: string[]; duration?: number; autoAdvance?: boolean; color?: string; trackColor?: string; textColor?: string };
+  /** Benefits shown with check marks. */
+  checklist?: { items: string[]; color?: string; textColor?: string };
+  /** Two or more images shown as an auto-advancing carousel; `illustration` mirrors the first. */
+  carousel?: { images: string[]; interval?: number; autoplay?: boolean };
+  illustration?: string;
+  action?: ScreenAction;
+  /** Social proof: a star rating, short testimonials, and a stat line. */
+  proof?: { rating?: { score: number; count?: string; label?: string }; testimonials?: Testimonial[]; stat?: string };
+  /** A/B test: other versions of this screen's copy or image. Each session sees one version for the whole flow. */
+  experiment?: ScreenExperiment;
+  buttonStyle?: 'filled' | 'outline' | 'text';
+  theme?: ScreenTheme;
+  translations?: Record<string, ScreenCopy>;
+  charts?: ScreenChart[];
+};
+export type ScreenCopy = {
+  title?: string;
+  subtitle?: string;
+  button?: string;
+  options?: string[];
+  skipLabel?: string;
+  backLabel?: string;
+  termsLabel?: string;
+};
+export type OnboardingFlow = { schemaVersion: 1; id: string; version: number; updatedAt: string; appearance?: Appearance; /** For the {app_name} variable. */ appName?: string; screens: FlowScreen[]; /** A whole-onboarding A/B test; `screens` is version A. */ experiment?: FlowTest<FlowScreen> };
+type Props = {
+  flowId: string;
+  /** The app's publishable key (`oy_pub_…`) from the studio. It's meant to ship inside the app, so it can live in source code. */
+  apiKey: string;
+  baseUrl: string;
+  fallbackFlow: OnboardingFlow;
+  /** TestFlight and other release builds should pass `testing` explicitly; development builds default to `development`. */
+  analyticsEnvironment?: 'development' | 'testing' | 'production';
+  /** Locale key for translated screen copy, e.g. `fr-CA` or `es`. */
+  locale?: string;
+  /** `details.variables` holds every saved answer as a typed value (raw value, unit or currency, and the text shown), keyed by variable name. */
+  onComplete?: (answers: Record<string, string>, details: { variables: Record<string, VariableValue> }) => void;
+  /** `values` lists every pick for multiple-choice questions, or the single answer otherwise. */
+  onAnswer?: (screen: FlowScreen, answer: string, values: string[], variable?: VariableValue) => void;
+  /**
+   * Runs for every action except next and complete. Return a Promise to make the flow wait (the button shows a spinner):
+   * resolving to false, or rejecting, keeps the person on the screen. `details` holds the answers so far, e.g. to save them to a new account.
+   */
+  onAction?: (action: NonNullable<FlowScreen['action']>, screen: FlowScreen, details: { answers: Record<string, string>; variables: Record<string, VariableValue> }) => ActionResult | Promise<ActionResult>;
+  /** Overrides the flow's appearance. 'system' follows the device setting. */
+  appearance?: Appearance;
+  /** Saves progress on the device so a person who leaves the app (e.g. to sign up in a browser) comes back to the same screen. Defaults to true. */
+  resume?: boolean;
+  /**
+   * Draws the videos a flow can use in place of images, e.g. with expo-video. It should fill `style`, loop, and stay muted.
+   * Without it, a video slot shows the screen's illustration color.
+   */
+  renderVideo?: (video: OnboardingVideo) => React.ReactNode;
+};
+export type OnboardingVideo = { uri: string; resizeMode: 'cover' | 'contain' | 'stretch'; style: StyleProp<ViewStyle> };
+type Progress = { version: number; step: number; screenId: string; sessionId: string; history: number[]; answers: Record<string, string>; picked: Record<string, string[]>; displays: Record<string, string> };
+const cacheKey = (id: string) => `@onboardingyak/flow/${id}`;
+const INSTALL_KEY = '@onboardingyak/install';
+const KEY_HEADER = 'X-OnboardingYak-Key';
+const progressKey = (id: string) => `@onboardingyak/progress/${id}`;
+const HEX = /^#[\da-f]{6}$/i;
+
+function colorOf(value: unknown, fallback: string) {
+  return typeof value === 'string' && HEX.test(value) ? value : fallback;
+}
+function rangeOf(value: unknown, fallback: number, min: number, max: number) {
+  return typeof value === 'number' && Number.isFinite(value) ? Math.min(max, Math.max(min, value)) : fallback;
+}
+function lightBackground(hex: string) {
+  const value = Number.parseInt(hex.slice(1), 16);
+  if (!Number.isFinite(value)) return true;
+  const channel = (part: number) => {
+    const scaled = part / 255;
+    return scaled <= 0.03928 ? scaled / 12.92 : ((scaled + 0.055) / 1.055) ** 2.4;
+  };
+  const luma = 0.2126 * channel((value >> 16) & 255) + 0.7152 * channel((value >> 8) & 255) + 0.0722 * channel(value & 255);
+  return luma > 0.45;
+}
+const FONT_NAMES: Record<string, string> = {
+  manrope: 'Manrope',
+  'dm-sans': 'DM Sans',
+  outfit: 'Outfit',
+  nunito: 'Nunito',
+  fraunces: 'Fraunces',
+  newsreader: 'Newsreader',
+  lora: 'Lora',
+  'libre-baskerville': 'Libre Baskerville',
+};
+function fontName(value: unknown, fallback: string) {
+  return typeof value === 'string' && FONT_NAMES[value] ? FONT_NAMES[value] : fallback;
+}
+function fontWeight(value: unknown): '400' | '500' | '700' {
+  return value === 400 || value === 500 || value === 700 ? String(value) as '400' | '500' | '700' : '700';
+}
+function termsHref(url: unknown) {
+  if (typeof url !== 'string') return null;
+  const trimmed = url.trim();
+  if (!trimmed) return null;
+  return /^https?:\/\//i.test(trimmed) ? trimmed.slice(0, 500) : `https://${trimmed.slice(0, 500)}`;
+}
+type EdgeBox = { top: number; right: number; bottom: number; left: number };
+type AxisBox = { vertical: number; horizontal: number };
+function resolveEdges(value: number | EdgeInsets | undefined, fallback: EdgeBox, legacy: 'top' | 'bottom' | 'uniform' | 'inline' = 'top'): EdgeBox {
+  if (typeof value === 'number') {
+    if (legacy === 'bottom') {
+      const amount = rangeOf(value, fallback.bottom, 0, 64);
+      return { top: 0, right: 0, bottom: amount, left: 0 };
+    }
+    if (legacy === 'uniform') {
+      const amount = rangeOf(value, fallback.top, 0, 64);
+      return { top: amount, right: amount, bottom: amount, left: amount };
+    }
+    if (legacy === 'inline') {
+      const amount = rangeOf(value, fallback.right, 0, 64);
+      return { top: fallback.top, right: amount, bottom: fallback.bottom, left: amount };
+    }
+    const amount = rangeOf(value, fallback.top, 0, 64);
+    return { top: amount, right: 0, bottom: 0, left: 0 };
+  }
+  return {
+    top: rangeOf(value?.top, fallback.top, 0, 64),
+    right: rangeOf(value?.right, fallback.right, 0, 64),
+    bottom: rangeOf(value?.bottom, fallback.bottom, 0, 64),
+    left: rangeOf(value?.left, fallback.left, 0, 64),
+  };
+}
+function resolveAxes(value: number | AxisInsets | undefined, fallback: AxisBox): AxisBox {
+  if (typeof value === 'number') {
+    return { vertical: fallback.vertical, horizontal: rangeOf(value, fallback.horizontal, 0, 64) };
+  }
+  return {
+    vertical: rangeOf(value?.vertical, fallback.vertical, 0, 64),
+    horizontal: rangeOf(value?.horizontal, fallback.horizontal, 0, 64),
+  };
+}
+function boxStyle(padding: EdgeBox, margin: AxisBox) {
+  return {
+    paddingTop: padding.top,
+    paddingRight: padding.right,
+    paddingBottom: padding.bottom,
+    paddingLeft: padding.left,
+    marginTop: margin.vertical,
+    marginBottom: margin.vertical,
+    marginLeft: margin.horizontal,
+    marginRight: margin.horizontal,
+  };
+}
+// Same curve as the studio: a light tint at the top that deepens toward the bottom, where the copy sits.
+function overlayAlphaAt(position: number, opacity: number, style: 'solid' | 'gradient') {
+  const full = Math.min(90, Math.max(0, opacity)) / 100;
+  if (style !== 'gradient') return full;
+  const start = full * 0.25;
+  if (position <= 0.3) return start;
+  return start + (full - start) * ((position - 0.3) / 0.7) ** 1.3;
+}
+
+// Mirrors lib/flow-schema.ts.
+const ALIGN_RANK = { top: 0, center: 1, bottom: 2 } as const;
+/** Each section sits in a top, middle, or bottom zone, keeping header → body → footer order: a later section is never placed above an earlier one. */
+function sectionAligns(theme: { headerAlign?: SectionAlign; bodyAlign?: SectionAlign; footerAlign?: SectionAlign } | undefined, backdrop: boolean) {
+  const header: SectionAlign = theme?.headerAlign ?? 'top';
+  let body: SectionAlign = theme?.bodyAlign ?? (backdrop ? 'bottom' : 'top');
+  let footer: SectionAlign = theme?.footerAlign ?? 'bottom';
+  if (ALIGN_RANK[body] < ALIGN_RANK[header]) body = header;
+  if (ALIGN_RANK[footer] < ALIGN_RANK[body]) footer = body;
+  return { header, body, footer };
+}
+
+const OVERLAY_BANDS = 48;
+const LAYOUT_PARTS: LayoutPart[] = ['back', 'progress', 'image', 'loader', 'title', 'subtitle', 'answers', 'proof', 'checklist', 'charts'];
+
+// Same rules as the studio: saved order first, then any missing parts in their default section.
+function resolveArrangement(arrangement: { header?: unknown; body?: unknown } | undefined, progress: 'above' | 'below') {
+  const header: LayoutPart[] = [];
+  const body: LayoutPart[] = [];
+  const seen = new Set<LayoutPart>();
+  const take = (list: unknown, into: LayoutPart[]) => { if (Array.isArray(list)) for (const part of list) if (LAYOUT_PARTS.includes(part) && !seen.has(part)) { seen.add(part); into.push(part); } };
+  take(arrangement?.header, header);
+  take(arrangement?.body, body);
+  for (const part of (progress === 'above' ? ['back', 'progress', 'image'] : ['back', 'image', 'progress']) as LayoutPart[]) if (!seen.has(part)) header.push(part);
+  for (const part of ['loader', 'title', 'subtitle', 'answers', 'proof', 'checklist', 'charts'] as LayoutPart[]) if (!seen.has(part)) body.push(part);
+  return { header, body };
+}
+
+function carouselImages(screen: FlowScreen) {
+  const images = (Array.isArray(screen.carousel?.images) ? screen.carousel.images : []).filter((image) => typeof image === 'string' && image.length > 0).slice(0, 8);
+  return images.length >= 2 ? images : screen.illustration ? [screen.illustration] : [];
+}
+
+/** Media fields hold images or videos; a video is a data URL or a link to a common video file. */
+function isVideoUri(uri: string) {
+  return uri.startsWith('data:video/') || /\.(mp4|m4v|mov|webm)(?:[?#]|$)/i.test(uri);
+}
+
+function phoneImageUri(uri: string) {
+  if (!uri.includes('images.pexels.com')) return uri;
+  try {
+    const url = new URL(uri);
+    const width = Number(url.searchParams.get('w'));
+    if (width > 0 && width < 1800) url.searchParams.set('w', '1800');
+    return url.toString();
+  } catch { return uri; }
+}
+
+const VideoRenderer = createContext<Props['renderVideo']>(undefined);
+
+// An image, or a video drawn by the app's renderVideo.
+function Media({ uri, resize, style, label }: { uri: string; resize: 'cover' | 'contain' | 'stretch'; style: StyleProp<ViewStyle>; label?: string }) {
+  const renderVideo = useContext(VideoRenderer);
+  if (!isVideoUri(uri)) return <Image source={{ uri: phoneImageUri(uri) }} resizeMode={resize} accessibilityLabel={label} accessibilityIgnoresInvertColors style={style as StyleProp<ImageStyle>} />;
+  return <View style={style} accessibilityLabel={label}>{renderVideo?.({ uri, resizeMode: resize, style: StyleSheet.absoluteFill })}</View>;
+}
+
+// A phone shell around the image, sized by height. Proportions match the studio's CSS mockup.
+function DeviceFrame({ device, children }: { device: 'iphone' | 'android'; children: React.ReactNode }) {
+  const [width, setWidth] = useState(0);
+  const iphone = device === 'iphone';
+  const bezel = width * (iphone ? 0.052 : 0.044);
+  const radius = width * (iphone ? 0.15 : 0.1);
+  return <View onLayout={(event) => setWidth(event.nativeEvent.layout.width)} style={[styles.deviceFrame, { borderRadius: radius, padding: bezel, backgroundColor: iphone ? '#141416' : '#1d1e22' }]}>
+    <View style={[styles.deviceButton, { right: -width * 0.014, top: iphone ? '26%' : '21%', height: iphone ? '11%' : '7%', width: width * 0.016 }]} />
+    <View style={[styles.deviceButton, iphone ? { left: -width * 0.014 } : { right: -width * 0.014 }, { top: iphone ? '20%' : '32%', height: iphone ? '13%' : '14%', width: width * 0.016 }]} />
+    <View style={[styles.deviceScreen, { borderRadius: Math.max(0, radius - bezel) }]}>
+      {children}
+      {iphone
+        ? <View style={[styles.deviceIsland, { top: width * 0.03, width: width * 0.3, height: width * 0.075, marginLeft: -width * 0.15 }]} />
+        : <View style={[styles.deviceIsland, { top: width * 0.03, width: width * 0.045, height: width * 0.045, marginLeft: -width * 0.0225 }]} />}
+    </View>
+  </View>;
+}
+
+type CarouselProps = { images: string[]; resize: 'cover' | 'contain' | 'stretch'; interval: number; autoplay: boolean };
+
+// Swipeable slides with dots; advances on a timer unless the person is dragging or prefers reduced motion.
+function InlineCarousel({ images, resize, interval, autoplay }: CarouselProps) {
+  const [width, setWidth] = useState(0);
+  const [index, setIndex] = useState(0);
+  const scroller = useRef<React.ComponentRef<typeof ScrollView>>(null);
+  const dragging = useRef(false);
+  useEffect(() => {
+    if (!autoplay || images.length < 2) return;
+    const timer = setInterval(() => { if (!dragging.current) setIndex((current) => (current + 1) % images.length); }, interval);
+    return () => clearInterval(timer);
+  }, [autoplay, images.length, interval]);
+  useEffect(() => { if (width) scroller.current?.scrollTo({ x: index * width, animated: true }); }, [index, width]);
+  return <View style={StyleSheet.absoluteFill} onLayout={(event) => setWidth(event.nativeEvent.layout.width)}>
+    <ScrollView ref={scroller} horizontal pagingEnabled showsHorizontalScrollIndicator={false} onScrollBeginDrag={() => { dragging.current = true; }} onMomentumScrollEnd={(event) => { dragging.current = false; if (width) setIndex(Math.round(event.nativeEvent.contentOffset.x / width)); }}>
+      {images.map((uri, imageIndex) => <Media key={imageIndex} uri={uri} resize={resize} label={`Image ${imageIndex + 1} of ${images.length}`} style={{ width, height: '100%' }} />)}
+    </ScrollView>
+    <View pointerEvents="none" style={styles.carouselDots}>{images.map((_, dotIndex) => <View key={dotIndex} style={[styles.carouselDot, dotIndex === index && styles.carouselDotActive]} />)}</View>
+  </View>;
+}
+
+// Full-screen photos crossfade behind the content.
+function BackdropCarousel({ images, resize, interval, autoplay }: CarouselProps) {
+  const [index, setIndex] = useState(0);
+  const fades = useRef(images.map((_, imageIndex) => new Animated.Value(imageIndex === 0 ? 1 : 0))).current;
+  useEffect(() => {
+    if (!autoplay || images.length < 2) return;
+    const timer = setInterval(() => setIndex((current) => (current + 1) % images.length), interval);
+    return () => clearInterval(timer);
+  }, [autoplay, images.length, interval]);
+  useEffect(() => {
+    Animated.parallel(fades.map((fade, imageIndex) => Animated.timing(fade, { toValue: imageIndex === index ? 1 : 0, duration: 900, useNativeDriver: true }))).start();
+  }, [fades, index]);
+  return <>{images.map((uri, imageIndex) => <Animated.View key={imageIndex} pointerEvents="none" style={[StyleSheet.absoluteFill, { opacity: fades[imageIndex] }]}><Media uri={uri} resize={resize} style={StyleSheet.absoluteFill} /></Animated.View>)}</>;
+}
+
+// Drawn from thin stacked bands so the SDK needs no native gradient dependency.
+function Overlay({ color, opacity, style }: { color: string; opacity: number; style: 'solid' | 'gradient' }) {
+  if (style !== 'gradient') return <View pointerEvents="none" style={[StyleSheet.absoluteFill, { backgroundColor: color, opacity: opacity / 100 }]} />;
+  return <View pointerEvents="none" style={StyleSheet.absoluteFill}>{Array.from({ length: OVERLAY_BANDS }, (_, index) => <View key={index} style={{ flex: 1, backgroundColor: color, opacity: overlayAlphaAt((index + 0.5) / OVERLAY_BANDS, opacity, style) }} />)}</View>;
+}
+
+function resolveTheme(screen: FlowScreen, dark = false) {
+  const light = resolveLightTheme(screen);
+  return dark ? { ...light, ...darkColors(light, screen.theme?.dark) } : light;
+}
+
+function resolveLightTheme(screen: FlowScreen) {
+  const theme = screen.theme ?? {};
+  const align = theme.align === 'left' || theme.align === 'right' ? theme.align : 'center' as const;
+  const label = (value: unknown, fallback: string, max = 32) => typeof value === 'string' && value.trim() ? value.trim().slice(0, max) : fallback;
+  return {
+    background: colorOf(theme.background, '#ffffff'),
+    showImage: theme.showImage !== false,
+    showProgress: theme.showProgress !== false,
+    showTitle: theme.showTitle !== false,
+    showSubtitle: theme.showSubtitle !== false,
+    showButton: theme.showButton !== false,
+    showSkip: theme.showSkip !== false,
+    showBack: theme.showBack === true,
+    showTerms: theme.showTerms === true,
+    showLoader: theme.showLoader !== false,
+    showChecklist: theme.showChecklist !== false,
+    showCharts: theme.showCharts !== false,
+    showProof: theme.showProof !== false,
+    gap: rangeOf(theme.gap, 14, 0, 48),
+    margin: resolveAxes(theme.margin, { vertical: 0, horizontal: 18 }),
+    headerPadding: resolveEdges(theme.headerPadding, { top: 0, right: 0, bottom: 0, left: 0 }, 'top'),
+    bodyPadding: resolveEdges(theme.bodyPadding, { top: 0, right: 0, bottom: 0, left: 0 }, 'top'),
+    footerPadding: resolveEdges(theme.footerPadding, { top: 0, right: 0, bottom: 24, left: 0 }, 'bottom'),
+    headerMargin: resolveAxes(theme.headerMargin, { vertical: 0, horizontal: 0 }),
+    bodyMargin: resolveAxes(theme.bodyMargin, { vertical: 0, horizontal: 0 }),
+    footerMargin: resolveAxes(theme.footerMargin, { vertical: 0, horizontal: 0 }),
+    align,
+    text: colorOf(theme.text, '#252b26'),
+    muted: colorOf(theme.muted, '#818a82'),
+    primary: colorOf(theme.primary, '#8b1e24'),
+    buttonPadding: resolveEdges(theme.buttonPadding, { top: 10, right: 14, bottom: 10, left: 14 }, 'inline'),
+    buttonRadius: rangeOf(theme.buttonRadius, 8, 0, 40),
+    cardPadding: resolveEdges(theme.cardPadding, { top: 8, right: 8, bottom: 8, left: 8 }, 'uniform'),
+    cardRadius: rangeOf(theme.cardRadius, 7, 0, 40),
+    cardBackground: colorOf(theme.cardBackground, '#ffffff'),
+    imageFit: theme.imageFit === 'contain' || theme.imageFit === 'fill' ? theme.imageFit : 'cover' as const,
+    imageWidthMode: theme.imageWidthMode === 'fill' ? 'fill' as const : 'fixed' as const,
+    imageHeightMode: theme.imageHeightMode === 'fill' ? 'fill' as const : 'fixed' as const,
+    imageWidth: rangeOf(theme.imageWidth, 180, 40, 360),
+    imageHeight: rangeOf(theme.imageHeight, 160, 40, 360),
+    imageRadius: rangeOf(theme.imageRadius, 24, 0, 80),
+    imagePadding: resolveEdges(theme.imagePadding, { top: 0, right: 0, bottom: 0, left: 0 }, 'uniform'),
+    imageMargin: resolveAxes(theme.imageMargin, { vertical: 0, horizontal: 0 }),
+    imageBorderWidth: rangeOf(theme.imageBorderWidth, 0, 0, 12),
+    imageBorderColor: colorOf(theme.imageBorderColor, '#E5E7EB'),
+    imagePlacement: theme.imagePlacement === 'background' ? 'background' as const : 'inline' as const,
+    imageMotion: theme.imageMotion === 'float' || theme.imageMotion === 'rock' || theme.imageMotion === 'pulse' || theme.imageMotion === 'drift' ? theme.imageMotion : 'none' as const,
+    imageFrame: theme.imageFrame === 'iphone' || theme.imageFrame === 'android' ? theme.imageFrame : 'none' as const,
+    overlayColor: colorOf(theme.overlayColor, '#000000'),
+    overlayOpacity: rangeOf(theme.overlayOpacity, 45, 0, 90),
+    overlayStyle: theme.overlayStyle === 'gradient' ? 'gradient' as const : 'solid' as const,
+    progress: theme.progress === 'above' ? 'above' as const : 'below' as const,
+    progressStyle: theme.progressStyle === 'bar' || theme.progressStyle === 'dots' ? theme.progressStyle : 'segments' as const,
+    skipLabel: label(theme.skipLabel, 'Skip'),
+    backLabel: label(theme.backLabel, 'Back'),
+    termsLabel: label(theme.termsLabel, 'By continuing, you agree to our Terms', 160),
+    termsUrl: termsHref(theme.termsUrl),
+    font: fontName(theme.font, 'Manrope'),
+    bodyFont: fontName(theme.bodyFont, 'DM Sans'),
+    titleSize: rangeOf(theme.titleSize, 18, 16, 48),
+    bodySize: rangeOf(theme.bodySize, 12, 11, 32),
+    titleWeight: fontWeight(theme.titleWeight),
+  };
+}
+
+function validFlow(value: unknown, expectedId: string): value is OnboardingFlow {
+  if (!value || typeof value !== 'object') return false;
+  const flow = value as Partial<OnboardingFlow>;
+  return flow.schemaVersion === 1 && flow.id === expectedId && Number.isInteger(flow.version) &&
+    Array.isArray(flow.screens) && flow.screens.length > 0 && flow.screens.every(validScreen);
+}
+
+function validScreen(s: FlowScreen) {
+  return !!s && typeof s.id === 'string' && ['Welcome', 'Question', 'Feature', 'Permission', 'Paywall'].includes(s.kind) &&
+      typeof s.title === 'string' && typeof s.subtitle === 'string' && typeof s.button === 'string' &&
+      /^#[\da-f]{6}$/i.test(s.accent) && (s.answerType === undefined || s.answerType === 'text' || s.answerType === 'singleChoice') &&
+      (s.options === undefined || (Array.isArray(s.options) && s.options.every((option) => typeof option === 'string'))) &&
+      (s.optionIcons === undefined || (Array.isArray(s.optionIcons) && s.optionIcons.length <= 24 && s.optionIcons.every((icon) => typeof icon === 'string' && icon.length <= 32))) &&
+      (s.translations === undefined || (typeof s.translations === 'object' && s.translations !== null && !Array.isArray(s.translations) && Object.values(s.translations).every((copy) =>
+        typeof copy === 'object' && copy !== null && !Array.isArray(copy) && Object.entries(copy).every(([key, text]) =>
+          ['title', 'subtitle', 'button', 'skipLabel', 'backLabel', 'termsLabel'].includes(key) ? typeof text === 'string' : key === 'options' && Array.isArray(text) && text.every((option) => typeof option === 'string'))))) &&
+      (s.illustration === undefined || typeof s.illustration === 'string') &&
+      !(s.kind === 'Question' && s.answerType === 'singleChoice' && !(Array.isArray(s.options) && s.options.length > 0));
+}
+
+/** A flow test is used only when every version's screens pass the same checks; otherwise the original runs. */
+function usableTest(flow: OnboardingFlow) {
+  const test = flow.experiment;
+  if (!test || !Array.isArray(test.variants) || !test.variants.length) return undefined;
+  return test.variants.every((variant) => Array.isArray(variant.screens) && variant.screens.length > 0 && variant.screens.every(validScreen)) ? test : undefined;
+}
+
+/** The screens this install runs: the original, or its flow test version. */
+function screensFor(flow: OnboardingFlow, assignId: string) {
+  const test = usableTest(flow);
+  const version = test ? pickFlowVersion(test, assignId) : undefined;
+  return test && version && version !== 'a' ? test.variants.find((variant) => variant.id === version)?.screens ?? flow.screens : flow.screens;
+}
+
+const stringRecord = (value: unknown): value is Record<string, string> =>
+  !!value && typeof value === 'object' && !Array.isArray(value) && Object.values(value).every((item) => typeof item === 'string');
+
+/** Saved progress is used only for the same flow version, and only when its screen is still at the saved position. */
+function usableProgress(value: unknown, flow: OnboardingFlow, assignId: string): Progress | undefined {
+  if (!value || typeof value !== 'object') return undefined;
+  const saved = value as Partial<Progress>;
+  const screens = screensFor(flow, assignId);
+  const valid = saved.version === flow.version && Number.isInteger(saved.step) && typeof saved.screenId === 'string' && typeof saved.sessionId === 'string' &&
+    Array.isArray(saved.history) && saved.history.every((index) => Number.isInteger(index) && index >= 0 && index < screens.length) &&
+    stringRecord(saved.answers) && stringRecord(saved.displays) &&
+    !!saved.picked && typeof saved.picked === 'object' && Object.values(saved.picked).every((list) => Array.isArray(list) && list.every((item) => typeof item === 'string'));
+  return valid && screens[saved.step as number]?.id === saved.screenId ? saved as Progress : undefined;
+}
+
+function localeCopy(screen: FlowScreen, locale?: string): ScreenCopy | undefined {
+  if (!locale || !screen.translations) return undefined;
+  const translations = screen.translations;
+  const normalized = locale.trim().replace(/_/g, '-').toLowerCase();
+  const exact = Object.keys(translations).find((key) => key.toLowerCase() === normalized);
+  const language = normalized.split('-')[0];
+  const fallback = exact ?? Object.keys(translations).find((key) => key.toLowerCase() === language);
+  return fallback ? translations[fallback] : undefined;
+}
+
+function optionIconAt(icons: unknown, index: number) {
+  if (!Array.isArray(icons)) return '';
+  const icon = icons[index];
+  if (typeof icon !== 'string') return '';
+  const text = icon.trim();
+  return text && text.length <= 32 ? text : '';
+}
+
+function deviceLocale() {
+  try {
+    if (typeof Intl !== 'undefined' && typeof Intl.DateTimeFormat === 'function') {
+      return Intl.DateTimeFormat().resolvedOptions().locale;
+    }
+  } catch { /* Use the default locale when the runtime cannot report one. */ }
+  return 'en';
+}
+
+// {name} tokens in copy become saved answers.
+function fillScreen(screen: FlowScreen, values: Record<string, string>): FlowScreen {
+  const fill = (text: string) => fillTokens(text, values);
+  return {
+    ...screen,
+    proof: screen.proof ? { ...screen.proof, stat: screen.proof.stat ? fill(screen.proof.stat) : undefined } : undefined,
+    title: fill(screen.title),
+    subtitle: fill(screen.subtitle),
+    button: fill(screen.button),
+    loader: screen.loader ? { ...screen.loader, steps: screen.loader.steps.map(fill) } : undefined,
+    checklist: screen.checklist ? { ...screen.checklist, items: screen.checklist.items.map(fill) } : undefined,
+  };
+}
+
+function localizeScreen(screen: FlowScreen, locale?: string): FlowScreen {
+  const copy = localeCopy(screen, locale);
+  if (!copy) return screen;
+  const theme = screen.theme ?? {};
+  return {
+    ...screen,
+    title: copy.title ?? screen.title,
+    subtitle: copy.subtitle ?? screen.subtitle,
+    button: copy.button ?? screen.button,
+    options: copy.options ?? screen.options,
+    theme: {
+      ...theme,
+      skipLabel: copy.skipLabel ?? theme.skipLabel,
+      backLabel: copy.backLabel ?? theme.backLabel,
+      termsLabel: copy.termsLabel ?? theme.termsLabel,
+    },
+  };
+}
+
+const ENTERS = ['fade', 'rise', 'slide', 'pop'] as const;
+
+function readMotion(value: unknown, duration = 480, delay = 0): PartMotion | undefined {
+  if (!value || typeof value !== 'object') return undefined;
+  const item = value as Partial<PartMotion>;
+  if (typeof item.enter !== 'string' || !(ENTERS as readonly string[]).includes(item.enter)) return undefined;
+  const span = typeof item.duration === 'number' && Number.isFinite(item.duration) ? Math.min(1600, Math.max(160, Math.round(item.duration))) : duration;
+  const wait = typeof item.delay === 'number' && Number.isFinite(item.delay) ? Math.min(2000, Math.max(0, Math.round(item.delay))) : delay;
+  return { enter: item.enter as PartMotion['enter'], duration: span, delay: wait };
+}
+
+function readCharts(value: unknown): ScreenChart[] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((chart) => {
+    if (!chart || typeof chart !== 'object') return [];
+    const item = chart as Partial<ScreenChart>;
+    if (typeof item.id !== 'string' || (item.kind !== 'bar' && item.kind !== 'line' && item.kind !== 'donut')) return [];
+    if (item.hidden) return [];
+    if (!Array.isArray(item.points)) return [];
+    const points = item.points.flatMap((point) => {
+      if (!point || typeof point.label !== 'string' || typeof point.value !== 'number' || !Number.isFinite(point.value)) return [];
+      return [{ label: point.label.slice(0, 16), value: Math.min(100, Math.max(0, point.value)) }];
+    }).slice(0, 8);
+    if (!points.length) return [];
+    return [{ id: item.id, kind: item.kind, title: typeof item.title === 'string' ? item.title.slice(0, 48) : '', points, motion: readMotion(item.motion, 520, 300) }];
+  }).slice(0, 4);
+}
+
+function shade(hex: string, index: number) {
+  if (index === 0 || !HEX.test(hex)) return hex;
+  const amount = [0.28, 0.46, 0.62, 0.22, 0.4, 0.7, 0.54][(index - 1) % 7];
+  const toward = index % 2 === 0 ? 'ffffff' : '1f2937';
+  const mix = (start: number) => {
+    const from = Number.parseInt(hex.slice(start, start + 2), 16);
+    const to = Number.parseInt(toward.slice(start - 1, start + 1), 16);
+    return Math.round(from + (to - from) * amount).toString(16).padStart(2, '0');
+  };
+  return `#${mix(1)}${mix(3)}${mix(5)}`;
+}
+
+function Entrance({ motion, children }: { motion: PartMotion; children: React.ReactNode }) {
+  const opacity = useRef(new Animated.Value(0)).current;
+  const drift = useRef(new Animated.Value(motion.enter === 'rise' ? 16 : motion.enter === 'slide' ? 22 : 0)).current;
+  const scale = useRef(new Animated.Value(motion.enter === 'pop' ? 0.92 : 1)).current;
+  useEffect(() => {
+    opacity.setValue(0);
+    drift.setValue(motion.enter === 'rise' ? 16 : motion.enter === 'slide' ? 22 : 0);
+    scale.setValue(motion.enter === 'pop' ? 0.92 : 1);
+    const duration = motion.duration ?? 480;
+    const delay = motion.delay ?? 0;
+    Animated.parallel([
+      Animated.timing(opacity, { toValue: 1, duration, delay, useNativeDriver: true }),
+      Animated.timing(drift, { toValue: 0, duration, delay, useNativeDriver: true }),
+      Animated.timing(scale, { toValue: 1, duration, delay, useNativeDriver: true }),
+    ]).start();
+  }, [delayOf(motion), drift, motion.enter, opacity, scale]);
+  const shift = motion.enter === 'slide' ? { translateX: drift } : { translateY: drift };
+  return <Animated.View style={{ alignSelf: 'stretch', opacity, transform: [shift, { scale }] }}>{children}</Animated.View>;
+}
+
+function delayOf(motion: PartMotion) {
+  return `${motion.enter}:${motion.duration ?? 0}:${motion.delay ?? 0}`;
+}
+
+// Graphs draw in from zero: bars grow, lines reveal left to right, and donut segments sweep around.
+function NativeChart({ chart, color, ink, muted, surface, animate = true, delay = 300 }: { chart: ScreenChart; color: string; ink: string; muted: string; surface: string; animate?: boolean; delay?: number }) {
+  const [width, setWidth] = useState(0);
+  const draw = useRef(new Animated.Value(animate ? 0 : 1)).current;
+  useEffect(() => {
+    if (!animate) return;
+    Animated.timing(draw, { toValue: 1, duration: 1000, delay, easing: Easing.out(Easing.cubic), useNativeDriver: false }).start();
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+  const max = Math.max(...chart.points.map((point) => point.value), 1);
+  const total = chart.points.reduce((sum, point) => sum + point.value, 0) || 1;
+  const height = 92;
+  return (
+    <View style={styles.chart} onLayout={(event) => setWidth(event.nativeEvent.layout.width)}>
+      {!!chart.title.trim() && <Text style={[styles.chartTitle, { color: ink }]}>{chart.title}</Text>}
+      {chart.kind === 'donut' ? (
+        <View style={styles.donutRow}>
+          <View style={styles.donut}>
+            {Array.from({ length: 42 }, (_, index) => {
+              const at = (index + 0.5) / 42;
+              let cursor = 0;
+              let tone = color;
+              for (let pointIndex = 0; pointIndex < chart.points.length; pointIndex += 1) {
+                cursor += chart.points[pointIndex].value / total;
+                tone = shade(color, pointIndex);
+                if (at <= cursor) break;
+              }
+              return <Animated.View key={index} style={[styles.donutTickWrap, { opacity: draw.interpolate({ inputRange: [Math.max(0, at - 0.05), at], outputRange: [0, 1], extrapolate: 'clamp' }), transform: [{ rotate: `${(index / 42) * 360}deg` }] }]}><View style={[styles.donutTick, { backgroundColor: tone }]} /></Animated.View>;
+            })}
+            <View style={[styles.donutHole, { backgroundColor: surface }]}><Text style={[styles.donutTotal, { color: ink }]}>{Math.round(total)}</Text></View>
+          </View>
+          <View style={styles.legend}>{chart.points.map((point, index) => <Text key={`${point.label}-${index}`} style={[styles.legendItem, { color: muted }]}>{point.label}  {point.value}</Text>)}</View>
+        </View>
+      ) : chart.kind === 'line' ? (
+        <View style={{ height: height + 18 }}>
+          <Animated.View style={{ position: 'absolute', left: 0, top: 0, bottom: 0, overflow: 'hidden', width: draw.interpolate({ inputRange: [0, 1], outputRange: [0, width + 4] }) }}><View style={{ width, height: height + 16 }}>
+          {/* Soft fill under the line, drawn as thin columns because React Native has no SVG paths. */}
+          {width > 0 && chart.points.length > 1 && Array.from({ length: Math.ceil((width - 8) / 2) }, (_, column) => {
+            const x = 4 + column * 2 + 1;
+            const position = ((x - 4) / (width - 8)) * (chart.points.length - 1);
+            const at = Math.min(chart.points.length - 2, Math.floor(position));
+            const value = chart.points[at].value + (chart.points[at + 1].value - chart.points[at].value) * (position - at);
+            const top = height - 8 - (value / max) * (height - 16);
+            return <View key={`fill-${column}`} style={{ position: 'absolute', left: x - 1, top, width: 2, height: height - top, backgroundColor: color, opacity: 0.14 }} />;
+          })}
+          {width > 0 && chart.points.slice(0, -1).map((point, index) => {
+            const next = chart.points[index + 1];
+            const x1 = (index / (chart.points.length - 1)) * (width - 8) + 4;
+            const x2 = ((index + 1) / (chart.points.length - 1)) * (width - 8) + 4;
+            const y1 = height - 8 - (point.value / max) * (height - 16);
+            const y2 = height - 8 - (next.value / max) * (height - 16);
+            const length = Math.max(1, Math.hypot(x2 - x1, y2 - y1));
+            return <View key={index} style={{ position: 'absolute', left: (x1 + x2) / 2 - length / 2, top: (y1 + y2) / 2 - 1, width: length, height: 2, borderRadius: 1, backgroundColor: color, transform: [{ rotate: `${Math.atan2(y2 - y1, x2 - x1)}rad` }] }} />;
+          })}
+          {chart.points.map((point, index) => {
+            const x = chart.points.length === 1 ? width / 2 : (index / (chart.points.length - 1)) * (width - 8) + 4;
+            const y = height - 8 - (point.value / max) * (height - 16);
+            return <View key={`${point.label}-${index}`} style={[styles.lineDot, { left: x - 3, top: y - 3, backgroundColor: color }]} />;
+          })}
+          </View></Animated.View>
+          {width > 0 && chart.points.map((point, index) => {
+            const x = chart.points.length === 1 ? width / 2 : (index / (chart.points.length - 1)) * (width - 8) + 4;
+            return <Text key={`label-${index}`} numberOfLines={1} style={[styles.lineLabel, { color: muted, left: Math.max(0, Math.min(width - 56, x - 28)), textAlign: index === 0 && x - 28 < 0 ? 'left' : index === chart.points.length - 1 && x + 28 > width ? 'right' : 'center' }]}>{point.label}</Text>;
+          })}
+        </View>
+      ) : (
+        <View style={styles.bars}>
+          {chart.points.map((point, index) => <View key={`${point.label}-${index}`} style={styles.barCol}><Animated.View style={[styles.bar, { height: draw.interpolate({ inputRange: [0, 1], outputRange: [0, Math.max(4, (point.value / max) * 72)] }), backgroundColor: color, opacity: 0.45 + (point.value / max) * 0.55 }]} /><Text style={[styles.barLabel, { color: muted }]} numberOfLines={1}>{point.label}</Text></View>)}
+        </View>
+      )}
+    </View>
+  );
+}
+
+function withEntrance(motion: PartMotion | undefined, key: string, node: React.ReactNode) {
+  if (!motion || node == null || node === false) return node;
+  return <Entrance key={key} motion={motion}>{node}</Entrance>;
+}
+
+function ImageMotion({ motion, reduceMotion, children, style }: { motion?: ScreenTheme['imageMotion']; reduceMotion: boolean; children: React.ReactNode; style?: StyleProp<ViewStyle> }) {
+  const progress = useRef(new Animated.Value(0)).current;
+  useEffect(() => {
+    progress.stopAnimation();
+    progress.setValue(0);
+    if (reduceMotion || !motion || motion === 'none') return;
+    const floating = motion === 'float';
+    const rocking = motion === 'rock';
+    const pulse = motion === 'pulse';
+    const from = Animated.timing(progress, { toValue: 1, duration: floating || rocking ? 1900 : 2400, easing: Easing.inOut(Easing.sin), useNativeDriver: true });
+    const back = Animated.timing(progress, { toValue: 0, duration: floating || rocking ? 1900 : 2400, easing: Easing.inOut(Easing.sin), useNativeDriver: true });
+    const loop = Animated.loop(Animated.sequence([from, back]));
+    loop.start();
+    return () => loop.stop();
+  }, [motion, progress, reduceMotion]);
+  const transform = motion === 'float' ? [{ translateY: progress.interpolate({ inputRange: [0, 1], outputRange: [0, -8] }) }] : motion === 'rock' ? [{ rotate: progress.interpolate({ inputRange: [0, 0.5, 1], outputRange: ['-2deg', '2deg', '-2deg'] }) }] : motion === 'pulse' ? [{ scale: progress.interpolate({ inputRange: [0, 1], outputRange: [1, 1.035] }) }] : motion === 'drift' ? [{ scale: progress.interpolate({ inputRange: [0, 1], outputRange: [1, 1.08] }) }] : [];
+  return <Animated.View style={[style, !reduceMotion && motion !== 'none' && { transform }]}>{children}</Animated.View>;
+}
+
+export function Onboarding({ flowId, apiKey, baseUrl, fallbackFlow, locale, onComplete, onAction, onAnswer, appearance, analyticsEnvironment: configuredAnalyticsEnvironment, resume = true, renderVideo }: Props) {
+  const scheme = useColorScheme();
+  const [flow, setFlow] = useState<OnboardingFlow>(fallbackFlow);
+  const [step, setStep] = useState(0);
+  const [ready, setReady] = useState(false);
+  const [answer, setAnswer] = useState('');
+  // The answer as the person saw it (e.g. "154 lb"), kept per screen for recalled variables.
+  const [shown, setShown] = useState('');
+  const [displays, setDisplays] = useState<Record<string, string>>({});
+  const [answers, setAnswers] = useState<Record<string, string>>({});
+  // Picks per screen drive conditions; history lets Back return to the screens that were actually shown.
+  const [picks, setPicks] = useState<string[]>([]);
+  const [picked, setPicked] = useState<Record<string, string[]>>({});
+  const [history, setHistory] = useState<number[]>([]);
+  // A resumed onboarding keeps its session id, so analytics count it as one run.
+  const [sessionId, setSessionId] = useState(() => `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 14)}`);
+  const [resumed, setResumed] = useState(false);
+  // True while the app handles an action that returned a Promise, such as sign-up.
+  const [busy, setBusy] = useState(false);
+  const [done, setDone] = useState(false);
+  // A per-install id keeps A/B assignments the same across app launches.
+  const [installId, setInstallId] = useState('');
+  // The version of the onboarding this install runs: the original, or a flow test version. Screen tests pause during a flow test.
+  const assignId = installId || sessionId;
+  const flowTest = usableTest(flow);
+  const flowVersion = flowTest ? pickFlowVersion(flowTest, assignId) : undefined;
+  const playFlow: OnboardingFlow = { ...flow, screens: screensFor(flow, assignId) };
+  const analyticsEnvironment = configuredAnalyticsEnvironment ?? (__DEV__ ? 'development' : 'production');
+  const track = (event_name: 'flow_started' | 'screen_viewed' | 'screen_completed' | 'flow_completed', screen_id?: string, version = flow.version) => {
+    // Screens under an A/B test tag their events with the version this session sees, so results can be compared.
+    const tested = !flowTest && screen_id && event_name !== 'flow_started' && event_name !== 'flow_completed' ? playFlow.screens.find((item) => item.id === screen_id) : undefined;
+    const variant = flowVersion ? `flow-${flowVersion}` : tested?.experiment?.variants?.length ? pickVariant(tested, assignId) : undefined;
+    void fetch(`${baseUrl.replace(/\/$/, '')}/api/events`, { method: 'POST', headers: { 'Content-Type': 'application/json', [KEY_HEADER]: apiKey }, body: JSON.stringify({ app_id: flowId, event_name, screen_id, session_id: sessionId, flow_version: version, environment: analyticsEnvironment, ...(variant ? { variant } : {}) }) }).catch(() => {});
+  };
+  useEffect(() => {
+    let mounted = true;
+    async function load() {
+      let install = '';
+      try {
+        install = (await AsyncStorage.getItem(INSTALL_KEY)) ?? '';
+        if (!install) { install = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 14)}`; await AsyncStorage.setItem(INSTALL_KEY, install); }
+        if (mounted) setInstallId(install);
+      } catch { /* Without storage, assignments fall back to this session. */ }
+      let loaded = fallbackFlow;
+      try {
+        const response = await fetch(`${baseUrl.replace(/\/$/, '')}/api/flows/${encodeURIComponent(flowId)}`, { headers: { [KEY_HEADER]: apiKey } });
+        if (response.status === 401 && __DEV__) console.warn(`OnboardingYak: the apiKey for "${flowId}" is missing or doesn't belong to this app. Copy the publishable key from the studio. Showing the cached or fallback flow.`);
+        if (!response.ok) throw new Error('No published flow');
+        const data: unknown = await response.json();
+        if (!validFlow(data, flowId)) throw new Error('Unsupported flow format');
+        loaded = data;
+        await AsyncStorage.setItem(cacheKey(flowId), JSON.stringify(data));
+      } catch {
+        try {
+          const cached: unknown = JSON.parse((await AsyncStorage.getItem(cacheKey(flowId))) ?? 'null');
+          if (validFlow(cached, flowId)) loaded = cached;
+        } catch { /* Keep the bundled fallback flow. */ }
+      }
+      // Pick up where the person left off, e.g. after leaving the app to sign up.
+      let saved: Progress | undefined;
+      if (resume) {
+        try { saved = usableProgress(JSON.parse((await AsyncStorage.getItem(progressKey(flowId))) ?? 'null'), loaded, install || sessionId); }
+        catch { /* Start from the first screen. */ }
+      }
+      if (!mounted) return;
+      setFlow(loaded);
+      setStep(saved?.step ?? 0);
+      if (saved) {
+        setSessionId(saved.sessionId);
+        setHistory(saved.history);
+        setAnswers(saved.answers);
+        setPicked(saved.picked);
+        setDisplays(saved.displays);
+        setResumed(true);
+      }
+      setReady(true);
+    }
+    load();
+    return () => { mounted = false; };
+  }, [apiKey, baseUrl, flowId]);
+  useEffect(() => {
+    if (ready) {
+      // A resumed onboarding already counted its start; the step effect below counts the screen it resumes on.
+      if (!resumed) track('flow_started');
+      if (step === 0) track('screen_viewed', playFlow.screens[0]?.id);
+    }
+  // Count once when the initial remote or fallback flow has loaded.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [ready, flowId]);
+  // Saved answers become typed variables; copy uses their display text, and the app gets all of them when the flow ends.
+  const collectVariables = (source: Record<string, string>, sourcePicks: Record<string, string[]>, sourceDisplays: Record<string, string>) => {
+    const variables: Record<string, VariableValue> = {};
+    for (const item of playFlow.screens) {
+      if (!item.variable || source[item.id] === undefined) continue;
+      const value = variableValue(item, source[item.id], sourcePicks[item.id] ?? [], sourceDisplays[item.id]);
+      if (value) variables[item.variable.toLowerCase()] = value;
+    }
+    return variables;
+  };
+  const tokenValues: Record<string, string> = {};
+  for (const [name, value] of Object.entries(collectVariables(answers, picked, displays))) tokenValues[name] = value.display;
+  Object.assign(tokenValues, builtInValues(flow.appName, tokenValues));
+  const raw = playFlow.screens[step];
+  const screen = raw ? fillScreen(applyVariant(localizeScreen(raw, locale?.trim() || deviceLocale()), flowTest ? 'a' : pickVariant(raw, assignId)), tokenValues) : undefined;
+  useEffect(() => {
+    if (ready && step > 0) track('screen_viewed', playFlow.screens[step]?.id);
+  // Track a single view each time the step changes.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [step, ready]);
+  useEffect(() => {
+    const screenId = playFlow.screens[step]?.id;
+    if (!resume || !ready || done || !screenId) return;
+    const progress: Progress = { version: flow.version, step, screenId, sessionId, history, answers, picked, displays };
+    AsyncStorage.setItem(progressKey(flowId), JSON.stringify(progress)).catch(() => {});
+  // Saved on each move; the screens follow from flow and step.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [resume, ready, done, step, history, answers, picked, displays, sessionId, flowId, flow.version]);
+  const [reduceMotion, setReduceMotion] = useState(false);
+  const [loaderDoneStep, setLoaderDoneStep] = useState(-1);
+  useEffect(() => {
+    let mounted = true;
+    AccessibilityInfo.isReduceMotionEnabled().then((value) => { if (mounted) setReduceMotion(value); }).catch(() => {});
+    const subscription = AccessibilityInfo.addEventListener('reduceMotionChanged', setReduceMotion);
+    return () => { mounted = false; subscription.remove(); };
+  }, []);
+  if (!ready || !screen) return <SafeAreaView style={styles.loading}><ActivityIndicator color="#8b1e24" /></SafeAreaView>;
+  const mode = appearance ?? flow.appearance ?? 'light';
+  const dark = mode === 'dark' || (mode === 'system' && scheme === 'dark');
+  const theme = resolveTheme(screen, dark);
+  const line = dark ? '#ffffff26' : '#dfe5df';
+  // Wheel screens lock the page scroll so vertical drags always reach the wheel instead of the surrounding scroll view.
+  const hasWheel = screen.kind === 'Question' && screen.answerType !== 'singleChoice' && (screen.input?.format === 'wheel' || screen.input?.format === 'date');
+  const loaderPending = theme.showLoader && !!screen.loader?.steps?.length && loaderDoneStep !== step;
+  // Custom accent colors apply in both modes; custom text and track colors are light-mode only so dark screens stay readable.
+  const checkColor = colorOf(screen.checklist?.color, theme.primary);
+  const checkText = dark ? theme.text : colorOf(screen.checklist?.textColor, theme.text);
+  const pickerColors = { onPrimary: lightBackground(theme.primary) ? '#243028' : '#ffffff', text: theme.text, muted: theme.muted, primary: theme.primary, card: theme.cardBackground, line, font: theme.font, bodyFont: theme.bodyFont };
+  const buttonStyle = screen.buttonStyle ?? 'filled';
+  const onPrimary = lightBackground(theme.primary) ? '#243028' : '#ffffff';
+  const buttonVisual = buttonStyle === 'outline'
+    ? { backgroundColor: 'transparent', borderColor: theme.primary, borderWidth: 1 }
+    : buttonStyle === 'text'
+      ? { backgroundColor: 'transparent' }
+      : { backgroundColor: theme.primary };
+  const labelColor = buttonStyle === 'filled' ? onPrimary : theme.primary;
+  const cross = theme.align === 'right' ? 'flex-end' : theme.align === 'left' ? 'flex-start' : 'center';
+  const multi = screen.kind === 'Question' && screen.answerType === 'singleChoice' && !!screen.multiple;
+  const minPicks = Math.max(1, screen.multiple?.min ?? 1);
+  const needsPicks = multi && picks.length < minPicks;
+  // Ends the onboarding and clears saved progress, so the next launch starts fresh.
+  const finish = (nextAnswers: Record<string, string>, nextPicked: Record<string, string[]>, nextDisplays: Record<string, string>) => {
+    track('flow_completed', screen.id);
+    setDone(true);
+    AsyncStorage.removeItem(progressKey(flowId)).catch(() => {});
+    onComplete?.(nextAnswers, { variables: collectVariables(nextAnswers, nextPicked, nextDisplays) });
+  };
+  // Moves to the next screen whose condition passes, or finishes when none is left.
+  const advance = (nextPicked: Record<string, string[]>, nextAnswers: Record<string, string>, nextDisplays = displays) => {
+    const next = nextVisibleIndex(playFlow.screens, step, nextPicked);
+    if (next < 0) { finish(nextAnswers, nextPicked, nextDisplays); return; }
+    setHistory((list) => [...list, step]);
+    setStep(next);
+  };
+  const goBack = () => {
+    if (busy || !history.length) return;
+    setStep(history[history.length - 1]);
+    setHistory((list) => list.slice(0, -1));
+    setAnswer('');
+    setShown('');
+    setPicks([]);
+  };
+  const continueFlow = async () => {
+    if (loaderPending || busy) return;
+    const values = screen.kind !== 'Question' ? [] : multi ? picks : [answer.trim()].filter(Boolean);
+    const response = values.join(', ');
+    if (screen.kind === 'Question' && (!response || (multi && values.length < minPicks))) return;
+    Keyboard.dismiss();
+    const nextAnswers = screen.kind === 'Question' ? { ...answers, [screen.id]: response } : answers;
+    const nextPicked = screen.kind === 'Question' ? { ...picked, [screen.id]: values } : picked;
+    const nextDisplays = screen.kind === 'Question' && shown ? { ...displays, [screen.id]: shown } : displays;
+    if (screen.kind === 'Question') {
+      setAnswers(nextAnswers);
+      setPicked(nextPicked);
+      setDisplays(nextDisplays);
+      onAnswer?.(screen, response, values, variableValue(screen, response, values, nextDisplays[screen.id]) ?? undefined);
+    }
+    const action = screen.action ?? (nextVisibleIndex(playFlow.screens, step, nextPicked) < 0 ? 'complete' : 'next');
+    if (action !== 'next' && onAction) {
+      // A Promise (e.g. sign-up) holds the flow; false or an error keeps the person here with their answer still selected.
+      let result: ActionResult | Promise<ActionResult>;
+      try { result = onAction(action, screen, { answers: nextAnswers, variables: collectVariables(nextAnswers, nextPicked, nextDisplays) }); }
+      catch { return; }
+      if (result && typeof result === 'object') {
+        setBusy(true);
+        try { result = await result; }
+        catch { result = false; }
+        finally { setBusy(false); }
+      }
+      if (result === false) return;
+    }
+    track('screen_completed', screen.id);
+    if (screen.kind === 'Question') {
+      setAnswer('');
+      setShown('');
+      setPicks([]);
+    }
+    if (action === 'complete') finish(nextAnswers, nextPicked, nextDisplays);
+    else advance(nextPicked, nextAnswers, nextDisplays);
+  };
+  const darkSurface = !lightBackground(theme.showImage && theme.imagePlacement === 'background' && screen.illustration ? theme.overlayColor : theme.background);
+  const progressTrack = darkSurface ? '#ffffff33' : '#eaede9';
+  const progress = !theme.showProgress ? null : theme.progressStyle === 'bar' ? <View style={[styles.progressTrack, { backgroundColor: progressTrack }]}><View style={[styles.progressFill, { width: `${((step + 1) / playFlow.screens.length) * 100}%`, backgroundColor: theme.primary }]} /></View> : <View style={[styles.progress, theme.progressStyle === 'dots' && styles.progressDots]}>{playFlow.screens.map((s, i) => <View key={s.id} style={[theme.progressStyle === 'dots' ? styles.progressDot : styles.progressPart, theme.progressStyle === 'dots' && i === step && styles.progressDotCurrent, { backgroundColor: i <= step ? theme.primary : progressTrack }]} />)}</View>;
+  const imageResize = theme.imageFit === 'contain' ? 'contain' as const : theme.imageFit === 'fill' ? 'stretch' as const : 'cover' as const;
+  const move = (part: MotionPart, delay = 0) => reduceMotion ? undefined : readMotion(screen.theme?.motion?.[part], 480, delay);
+  const enter = (part: MotionPart, key: string, node: React.ReactNode, delay = 0) => withEntrance(move(part, delay), `${screen.id}-${key}-${step}`, node);
+  const charts = readCharts(screen.charts);
+  const images = carouselImages(screen);
+  const carousel = images.length >= 2 ? { images, resize: imageResize, interval: rangeOf(screen.carousel?.interval, 3500, 1500, 10000), autoplay: screen.carousel?.autoplay !== false && !reduceMotion } : null;
+  const backdrop = theme.showImage && theme.imagePlacement === 'background' && images.length > 0;
+  const arrangement = resolveArrangement(screen.theme?.arrangement, theme.progress);
+  const aligns = sectionAligns(screen.theme, backdrop);
+  // A footer moved off the bottom scrolls with the content; a bottom footer stays pinned above the keyboard.
+  const footerInScroll = aligns.footer !== 'bottom';
+  const framed = theme.imageFrame !== 'none';
+  const art = carousel ? <InlineCarousel key={`${screen.id}-${images.length}`} {...carousel} /> : images[0] ? <Media uri={images[0]} resize={imageResize} style={styles.illustration} /> : <><View style={styles.sun}/><Text style={styles.sparkle}>✳</Text></>;
+  const image = theme.showImage && !backdrop ? <ImageMotion motion={theme.imageMotion} reduceMotion={reduceMotion}><View style={[styles.art, boxStyle(theme.imagePadding, theme.imageMargin), framed && styles.artFramed, {
+    backgroundColor: framed ? 'transparent' : screen.accent,
+    width: theme.imageWidthMode === 'fill' ? '100%' : theme.imageWidth,
+    height: theme.imageHeightMode === 'fill' ? undefined : theme.imageHeight,
+    aspectRatio: theme.imageHeightMode === 'fill' ? theme.imageWidth / Math.max(theme.imageHeight, 1) : undefined,
+    borderRadius: framed ? 0 : theme.imageRadius,
+    borderWidth: framed ? 0 : theme.imageBorderWidth,
+    borderColor: theme.imageBorderColor,
+  }]}>{theme.imageFrame !== 'none' ? <DeviceFrame device={theme.imageFrame}>{art}</DeviceFrame> : art}</View></ImageMotion> : null;
+  const partNodes: Record<LayoutPart, React.ReactNode> = {
+    back: theme.showBack && enter('back', 'back', <Pressable accessibilityRole="button" onPress={goBack} style={styles.back}><Text style={[styles.skipText, { color: theme.muted, fontFamily: theme.bodyFont, fontSize: Math.max(12, theme.bodySize - 2) }]}>{`‹ ${theme.backLabel}`}</Text></Pressable>, 0),
+    progress: enter('progress', 'progress', progress, 40),
+    image: enter('image', 'image', image, 90),
+    title: theme.showTitle && enter('title', 'title', <Text style={[styles.title, { color: theme.text, textAlign: theme.align, fontFamily: theme.font, fontSize: theme.titleSize, lineHeight: Math.round(theme.titleSize * 1.2), fontWeight: theme.titleWeight }]}>{screen.title}</Text>, 180),
+    subtitle: theme.showSubtitle && enter('subtitle', 'subtitle', <Text style={[styles.subtitle, { color: theme.muted, textAlign: theme.align, fontFamily: theme.bodyFont, fontSize: theme.bodySize, lineHeight: Math.round(theme.bodySize * 1.45) }]}>{screen.subtitle}</Text>, 260),
+    answers: screen.kind === 'Question' && (screen.answerType === 'singleChoice' ? enter('cards', 'cards', <View style={styles.options}>{(screen.options ?? []).map((option, index) => {
+        const label = option.trim();
+        if (!label) return null;
+        const icon = optionIconAt(screen.optionIcons, index);
+        const picked = multi ? picks.includes(label) : answer === label;
+        const justify = theme.align === 'center' ? 'center' : theme.align === 'right' ? 'flex-end' : 'flex-start';
+        const toggle = () => {
+          if (!multi) { setAnswer(label); return; }
+          setPicks((list) => list.includes(label) ? list.filter((item) => item !== label) : screen.multiple?.max && list.length >= screen.multiple.max ? list : [...list, label]);
+        };
+        return <Pressable key={`${index}-${label}`} accessibilityRole={multi ? 'checkbox' : 'radio'} accessibilityState={{ checked: picked }} onPress={toggle} style={[styles.option, { borderRadius: theme.cardRadius, paddingTop: theme.cardPadding.top, paddingRight: theme.cardPadding.right, paddingBottom: theme.cardPadding.bottom, paddingLeft: theme.cardPadding.left, backgroundColor: picked ? (dark ? `${theme.primary}26` : '#f0f6f0') : theme.cardBackground, borderColor: line, justifyContent: justify }, picked && styles.optionSelected, picked && { borderColor: theme.primary, backgroundColor: dark ? `${theme.primary}26` : '#f0f6f0' }]}>{icon ? <Text style={styles.optionIcon}>{icon}</Text> : null}<Text style={[styles.optionText, { textAlign: theme.align, fontFamily: theme.bodyFont, fontSize: Math.max(12, theme.bodySize - 1) }, dark && { color: theme.text }, picked && styles.optionTextSelected, picked && { color: theme.primary }]}>{label}</Text>{multi ? <View style={[styles.multiCheck, { borderColor: picked ? theme.primary : line, backgroundColor: picked ? theme.primary : 'transparent' }]}>{picked ? <Text style={[styles.multiGlyph, { color: onPrimary }]}>✓</Text> : null}</View> : null}</Pressable>;
+      })}{multi && (minPicks > 1 || screen.multiple?.max) ? <Text style={[styles.multiHint, { color: theme.muted, fontFamily: theme.bodyFont, textAlign: theme.align }]}>{minPicks > 1 && screen.multiple?.max ? `Choose ${minPicks} to ${screen.multiple.max}` : minPicks > 1 ? `Choose at least ${minPicks}` : `Choose up to ${screen.multiple?.max}`}</Text> : null}</View>, 340) : enter('answers', 'answers', screen.input?.format === 'wheel'
+        ? <NumberWheel key={screen.id} input={screen.input} onChange={(value, display) => { setAnswer(value); setShown(display ?? ''); }} colors={pickerColors} />
+        : screen.input?.format === 'date'
+        ? <DateWheels key={screen.id} minYear={screen.input.min} maxYear={screen.input.max} initialYear={screen.input.initial} onChange={setAnswer} colors={pickerColors} />
+        : screen.input?.format === 'country'
+        ? <CountryPicker key={screen.id} value={answer} onChange={setAnswer} placeholder={screen.input.placeholder} colors={pickerColors} />
+        : screen.input?.format === 'number'
+        ? <NumberEntry key={screen.id} input={screen.input} placeholder={screen.input.placeholder} onChange={(value, display) => { setAnswer(value); setShown(display ?? ''); }} colors={pickerColors} size={Math.round(theme.titleSize * 1.5)} />
+        : <TextInput accessibilityLabel="Your answer" multiline value={answer} onChangeText={setAnswer} placeholder={screen.input?.placeholder ?? 'Write your answer…'} placeholderTextColor={dark ? '#7c8480' : '#929b93'} style={[styles.answerInput, { borderColor: line, textAlign: theme.align, color: theme.text, fontFamily: theme.bodyFont, fontSize: theme.bodySize }]} />, 340)),
+    charts: !theme.showCharts ? null : charts.map((chart) => <React.Fragment key={`${chart.id}-${step}`}>{withEntrance(reduceMotion ? undefined : chart.motion, `${screen.id}-${chart.id}-${step}`, <NativeChart chart={chart} color={theme.primary} ink={theme.text} muted={theme.muted} surface={theme.background} animate={!reduceMotion} delay={(chart.motion?.delay ?? 200) + 120} />)}</React.Fragment>),
+    loader: theme.showLoader && screen.loader?.steps?.length ? <LoaderBlock key={`${screen.id}-${step}`} steps={screen.loader.steps.slice(0, 6)} duration={rangeOf(screen.loader.duration, 5000, 2000, 15000)} colors={{ ...pickerColors, primary: colorOf(screen.loader.color, theme.primary), text: dark ? theme.text : colorOf(screen.loader.textColor, theme.text) }} track={dark ? '#ffffff1f' : colorOf(screen.loader.trackColor, '#e6e9e6')} onDone={() => {
+      setLoaderDoneStep(step);
+      if (screen.loader?.autoAdvance !== false) setTimeout(() => { track('screen_completed', screen.id); advance(picked, answers); }, 650);
+    }} /> : null,
+    proof: theme.showProof && screen.proof ? <ProofBlock key={`${screen.id}-proof-${step}`} proof={screen.proof} colors={pickerColors} reduceMotion={reduceMotion} align={theme.align} /> : null,
+    checklist: theme.showChecklist && screen.checklist?.items?.length ? <View style={styles.checklist}>{screen.checklist.items.slice(0, 8).map((item, index) => withEntrance(reduceMotion ? undefined : { enter: 'rise', duration: 420, delay: 220 + index * 110 }, `${screen.id}-check-${index}-${step}`, <View style={styles.checkRow}><View style={[styles.checkMark, { backgroundColor: checkColor }]}><Text style={[styles.checkGlyph, { color: lightBackground(checkColor) ? '#243028' : '#ffffff' }]}>✓</Text></View><Text style={[styles.checkText, { color: checkText, fontFamily: theme.bodyFont, fontSize: theme.bodySize }]}>{item}</Text></View>))}</View> : null,
+  };
+  const placeParts = (parts: LayoutPart[]) => parts.map((part) => <React.Fragment key={part}>{partNodes[part]}</React.Fragment>);
+  const headerView = <View key="header" style={[styles.header, boxStyle(theme.headerPadding, theme.headerMargin), { gap: theme.gap, alignItems: cross }]}>{placeParts(arrangement.header)}</View>;
+  const bodyView = <View key="body" style={[styles.body, boxStyle(theme.bodyPadding, theme.bodyMargin), { flexGrow: 0, gap: theme.gap, alignItems: cross }]}>{placeParts(arrangement.body)}</View>;
+  const footerView = ((theme.showButton || theme.showSkip || theme.showTerms) && <View key="footer" style={[styles.footer, footerInScroll && { marginTop: 0 }, boxStyle(theme.footerPadding, theme.footerMargin), { gap: theme.gap, backgroundColor: backdrop ? 'transparent' : theme.background }]}>
+      {theme.showButton && enter('button', 'button', <Pressable accessibilityRole="button" accessibilityState={{ disabled: loaderPending || needsPicks, busy }} disabled={loaderPending || needsPicks || busy} onPress={() => { void continueFlow(); }} style={[styles.button, buttonVisual, (loaderPending || needsPicks) && { opacity: 0.4 }, { borderRadius: theme.buttonRadius, paddingTop: theme.buttonPadding.top, paddingRight: theme.buttonPadding.right, paddingBottom: theme.buttonPadding.bottom, paddingLeft: theme.buttonPadding.left }]}>{busy ? <ActivityIndicator color={labelColor} /> : <Text style={[styles.buttonText, { color: labelColor, fontFamily: theme.bodyFont, fontSize: theme.bodySize }]}>{screen.button}</Text>}</Pressable>, 420)}
+      {theme.showSkip && enter('skip', 'skip', <Pressable accessibilityRole="button" disabled={busy} onPress={() => { track('screen_completed', screen.id); finish(answers, picked, displays); }} style={styles.skip}><Text style={[styles.skipText, { color: theme.muted, fontFamily: theme.bodyFont, fontSize: Math.max(12, theme.bodySize - 2) }]}>{theme.skipLabel}</Text></Pressable>, 500)}
+      {theme.showTerms && enter('terms', 'terms', <Pressable accessibilityRole={theme.termsUrl ? 'link' : 'text'} onPress={() => { if (theme.termsUrl) void Linking.openURL(theme.termsUrl); }} style={styles.terms}><Text style={[styles.termsText, { color: theme.muted, textAlign: theme.align, fontFamily: theme.bodyFont, fontSize: Math.max(11, theme.bodySize - 3), textDecorationLine: theme.termsUrl ? 'underline' : 'none' }]}>{theme.termsLabel}</Text></Pressable>, 560)}
+    </View>) || null;
+  // Top, middle, and bottom zones with flexible spacers between them. Each spacer cancels one gap so spacing between parts stays as set.
+  const sectionsFor = () => {
+    const zones: Record<SectionAlign, React.ReactNode[]> = { top: [], center: [], bottom: [] };
+    zones[aligns.header].push(headerView);
+    zones[aligns.body].push(bodyView);
+    if (footerInScroll) zones[aligns.footer].push(footerView);
+    const spacer = (key: string) => <View key={key} style={{ flexGrow: 1, marginTop: -theme.gap }} />;
+    return [...zones.top, spacer('space-above'), ...(zones.center.length ? [...zones.center, spacer('space-below')] : []), ...zones.bottom];
+  };
+  // The footer sits outside the scroll area, so the keyboard pushes the button up instead of covering it.
+  // Taps on empty space inside the scroll area close the keyboard (keyboardShouldPersistTaps="handled"). The container is a plain
+  // View, not a Pressable: a Pressable around the screen would claim touches before nested scroll views such as the picker wheels.
+  // A background image covers the whole screen, safe areas included, and its copy settles at the bottom.
+  return <VideoRenderer.Provider value={renderVideo}><View style={[styles.safe, { backgroundColor: theme.background }]}>{backdrop && <ImageMotion motion={theme.imageMotion} reduceMotion={reduceMotion} style={StyleSheet.absoluteFill}>{carousel ? <BackdropCarousel key={`${screen.id}-${images.length}`} {...carousel} /> : <Media uri={images[0]} resize={imageResize} style={StyleSheet.absoluteFill} />}<Overlay color={theme.overlayColor} opacity={theme.overlayOpacity} style={theme.overlayStyle} /></ImageMotion>}<SafeAreaView style={[styles.safe, { backgroundColor: backdrop ? 'transparent' : theme.background }]}><KeyboardAvoidingView style={styles.keyboard} behavior={Platform.OS === 'ios' ? 'padding' : undefined}><View style={[styles.container, { paddingTop: theme.margin.vertical, paddingBottom: theme.margin.vertical, paddingHorizontal: theme.margin.horizontal, gap: theme.gap, alignItems: cross }]}>
+    <ScrollView style={styles.scroll} scrollEnabled={!hasWheel} contentContainerStyle={[styles.scrollContent, { gap: theme.gap }]} keyboardShouldPersistTaps="handled" keyboardDismissMode={Platform.OS === 'ios' ? 'interactive' : 'on-drag'} showsVerticalScrollIndicator={false}>
+    {sectionsFor()}
+    </ScrollView>
+    {!footerInScroll && footerView}
+  </View></KeyboardAvoidingView></SafeAreaView></View></VideoRenderer.Provider>;
+}
+const styles = StyleSheet.create({
+  safe: { flex: 1, backgroundColor: '#fff' }, loading: { flex: 1, alignItems: 'center', justifyContent: 'center' },
+  keyboard: { flex: 1 },
+  container: { flex: 1, alignItems: 'center', paddingTop: 40 },
+  scroll: { flex: 1, alignSelf: 'stretch' }, scrollContent: { flexGrow: 1 },
+  header: { width: '100%', alignSelf: 'stretch' },
+  body: { width: '100%', alignSelf: 'stretch', flexGrow: 1 },
+  art: { width: 180, height: 160, borderRadius: 24, alignItems: 'center', justifyContent: 'center', overflow: 'hidden', alignSelf: 'center' },
+  illustration: { width: '100%', height: '100%' },
+  artFramed: { overflow: 'visible' },
+  deviceFrame: { height: '100%', aspectRatio: 9 / 19.5, maxWidth: '100%', alignSelf: 'center' },
+  deviceScreen: { flex: 1, overflow: 'hidden', backgroundColor: '#000000' },
+  deviceIsland: { position: 'absolute', left: '50%', borderRadius: 999, backgroundColor: '#000000' },
+  deviceButton: { position: 'absolute', borderRadius: 2, backgroundColor: '#2c2c31' },
+  sun: { position: 'absolute', width: 34, height: 34, borderRadius: 17, backgroundColor: '#f0c77f', top: 32 }, sparkle: { color: '#56745f', fontSize: 32 },
+  progress: { flexDirection: 'row', gap: 5, width: '100%', alignSelf: 'stretch' }, progressPart: { flex: 1, height: 4, borderRadius: 4, backgroundColor: '#eaede9' },
+  progressTrack: { width: '100%', height: 4, borderRadius: 4, overflow: 'hidden', alignSelf: 'stretch' }, progressFill: { height: '100%', borderRadius: 4 },
+  progressDots: { justifyContent: 'center', gap: 7 }, progressDot: { width: 8, height: 8, borderRadius: 4 }, progressDotCurrent: { width: 10, height: 10, borderRadius: 5 },
+  title: { color: '#252b26', fontWeight: '700', fontSize: 23, lineHeight: 28, alignSelf: 'stretch' }, subtitle: { color: '#818a82', fontSize: 15, lineHeight: 22, alignSelf: 'stretch' },
+  carouselDots: { position: 'absolute', left: 0, right: 0, bottom: 10, flexDirection: 'row', justifyContent: 'center', gap: 5 },
+  carouselDot: { width: 6, height: 6, borderRadius: 3, backgroundColor: '#ffffff', opacity: 0.55 },
+  carouselDotActive: { width: 16, opacity: 1 },
+  multiCheck: { width: 22, height: 22, marginLeft: 'auto', borderRadius: 6, borderWidth: 2, alignItems: 'center', justifyContent: 'center' },
+  multiGlyph: { fontSize: 13, fontWeight: '800', lineHeight: 16 },
+  multiHint: { fontSize: 12, marginTop: 2 },
+  checklist: { alignSelf: 'stretch', gap: 12 },
+  checkRow: { flexDirection: 'row', alignItems: 'center', gap: 12 },
+  checkMark: { width: 24, height: 24, borderRadius: 12, alignItems: 'center', justifyContent: 'center' },
+  checkGlyph: { fontSize: 13, fontWeight: '800', lineHeight: 16 },
+  checkText: { flex: 1, fontWeight: '500' },
+  numberRow: { alignSelf: 'stretch', flexDirection: 'row', alignItems: 'baseline', justifyContent: 'center', gap: 8, borderBottomWidth: 2, paddingVertical: 10 },
+  numberInput: { minWidth: 72, textAlign: 'center', fontWeight: '700', padding: 0 },
+  numberUnit: { fontWeight: '600' },
+  answerInput: { alignSelf: 'stretch', minHeight: 90, textAlignVertical: 'top', borderColor: '#dfe5df', borderWidth: 1, borderRadius: 12, padding: 12, color: '#39433b' },
+  options: { alignSelf: 'stretch', gap: 9 }, option: { minHeight: 46, flexDirection: 'row', alignItems: 'center', gap: 10, borderWidth: 1, borderColor: '#e0e6e0', borderRadius: 12, paddingHorizontal: 14, backgroundColor: '#fff' }, optionIcon: { fontSize: 20, lineHeight: 24 }, optionSelected: { borderColor: '#8b1e24', backgroundColor: '#f7ecec' }, optionText: { flexShrink: 1, color: '#687269', fontSize: 14 }, optionTextSelected: { color: '#8b1e24', fontWeight: '600' },
+  footer: { marginTop: 'auto', width: '100%', alignSelf: 'stretch' },
+  button: { minHeight: 52, width: '100%', borderRadius: 12, backgroundColor: '#8b1e24', alignItems: 'center', justifyContent: 'center' }, buttonText: { color: '#fff', fontWeight: '600', fontSize: 15 },
+  back: { alignSelf: 'flex-start', paddingVertical: 4 },
+  skip: { padding: 14 }, skipText: { color: '#828a82', fontSize: 13 },
+  terms: { paddingVertical: 4, alignSelf: 'stretch' }, termsText: { color: '#828a82', fontSize: 11, lineHeight: 15 },
+  chart: { alignSelf: 'stretch', width: '100%', gap: 8 },
+  chartTitle: { fontSize: 15, fontWeight: '700' },
+  bars: { flexDirection: 'row', alignItems: 'flex-end', gap: 8, minHeight: 96 },
+  barCol: { flex: 1, alignItems: 'center', gap: 4 },
+  bar: { width: '70%', borderRadius: 5, minHeight: 4 },
+  barLabel: { fontSize: 11 },
+  lineDot: { position: 'absolute', width: 6, height: 6, borderRadius: 3 },
+  lineLabel: { position: 'absolute', top: 94, width: 56, fontSize: 11 },
+  donutRow: { flexDirection: 'row', alignItems: 'center', gap: 12 },
+  donut: { width: 112, height: 112 },
+  donutTickWrap: { position: 'absolute', width: 112, height: 112, alignItems: 'center' },
+  donutTick: { width: 5, height: 12, borderRadius: 3 },
+  donutHole: { position: 'absolute', width: 72, height: 72, borderRadius: 36, top: 20, left: 20, alignItems: 'center', justifyContent: 'center' },
+  donutTotal: { fontSize: 16, fontWeight: '700' },
+  legend: { flex: 1, gap: 4 },
+  legendItem: { fontSize: 12 },
+});