@userflow-tech/react-native 0.1.0 → 0.2.0

package/src/pairing/resolvePreviewChrome.ts

@@ -0,0 +1,57 @@
+import type { PairingEngineState } from '@userflow-tech/core';
+
+import type { ChromeTopBarTone } from '../authoring/chrome/ChromeTopBar';
+
+export type PreviewChrome =
+  | { visible: false }
+  | { visible: true; tone: ChromeTopBarTone; label: string; numberOfLines: number };
+
+function isBannerVisible(state: PairingEngineState): boolean {
+  if (!state.previewActive && state.status === 'idle') return false;
+  if (
+    !state.previewActive &&
+    state.status !== 'token_expired' &&
+    state.status !== 'device_already_paired' &&
+    state.status !== 'error'
+  ) {
+    return false;
+  }
+  return true;
+}
+
+function shown(
+  tone: ChromeTopBarTone,
+  label: string,
+  numberOfLines = 1,
+): Extract<PreviewChrome, { visible: true }> {
+  return { visible: true, tone, label, numberOfLines };
+}
+
+/**
+ * Maps pairing-engine state onto the preview top-bar chrome.
+ * Pure: no React, so the nine-case table can be asserted without a renderer.
+ */
+export function resolvePreviewChrome(state: PairingEngineState): PreviewChrome {
+  if (!isBannerVisible(state)) return { visible: false };
+
+  switch (state.status) {
+    case 'connecting':
+      return shown('default', 'Connecting to Builder…');
+    case 'reconnecting':
+      return shown('default', 'Reconnecting…');
+    case 'token_expired':
+      return shown('error', 'Pairing ended - rescan to continue', 2);
+    case 'device_already_paired':
+      return shown('error', 'Another device is already paired', 2);
+    case 'error':
+      if (state.pairingId === null) {
+        return shown('error', 'Preview unavailable');
+      }
+      return shown('error', 'Pairing ended - rescan to continue', 2);
+    default:
+      if (state.awaitingStartCondition) {
+        return shown('default', 'Waiting for auto-start condition…');
+      }
+      return shown('default', 'Preview mode');
+  }
+}

package/src/pairing/tokenStorage.ts

@@ -17,14 +17,38 @@ type SecureStoreModule = {
   deleteItemAsync(key: string): Promise<void>;
 };
 
+let cachedSecureStore: SecureStoreModule | null | undefined;
+
+/** Expo modules must be installed natively — not just the JS package. */
+function isExpoModulesRuntimeAvailable(): boolean {
+  const expo = (globalThis as { expo?: { EventEmitter?: unknown } }).expo;
+  return typeof expo?.EventEmitter === 'function';
+}
+
 function tryLoadExpoSecureStore(): SecureStoreModule | null {
+  if (cachedSecureStore !== undefined) return cachedSecureStore;
+
+  if (typeof require !== 'function' || !isExpoModulesRuntimeAvailable()) {
+    cachedSecureStore = null;
+    return cachedSecureStore;
+  }
+
   try {
     // Optional peer — absent in bare RN without expo-secure-store.
     // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires -- optional peer at import time
-    return require('expo-secure-store') as SecureStoreModule;
+    cachedSecureStore = require('expo-secure-store') as SecureStoreModule;
   } catch {
-    return null;
+    cachedSecureStore = null;
+    if (__DEV__) {
+      // eslint-disable-next-line no-console -- intentional missing-optional-peer diagnostic
+      console.warn(
+        '[Userflow] Optional peer expo-secure-store is unavailable; ' +
+          'pairing JWT persistence falls back to in-memory storage.',
+      );
+    }
   }
+
+  return cachedSecureStore;
 }
 
 /** In-memory store used when SecureStore is unavailable (and in tests). */
@@ -74,3 +98,8 @@ export function createPairingTokenStore(): PairingTokenStore {
     },
   };
 }
+
+/** @internal Resets module cache between tests. */
+export function resetPairingTokenStoreCacheForTests(): void {
+  cachedSecureStore = undefined;
+}

package/src/pairing/usePairingState.ts

@@ -12,6 +12,8 @@ const IDLE: PairingEngineState = {
   lastError: null,
   needsRescan: false,
   awaitingStartCondition: false,
+  canRestartPreview: false,
+  previewRestartGeneration: 0,
 };
 
 /** Subscribe to Builder pairing / preview-mode state (dev builds only). */

package/src/runtime/FlowRenderer.tsx

@@ -10,20 +10,42 @@ import { useFlowSessionState } from './useFlowSessionState';
 
 export interface FlowRendererProps {
   engine: FlowSessionEngine;
+  /** Pairing preview restart counter; combined with stepShowNonce as resetNonce. */
+  previewRestartGeneration?: number;
 }
 
+type SurfaceProps = React.ComponentProps<typeof ModalSurface>;
+
+/** Everything a surface needs for one step, so the fade can hold it during an exit. */
+type StepRender = Omit<SurfaceProps, 'engine'> & { appearance: string; resetNonce: number };
+
 function appearanceOf(step: { appearance: unknown }): string {
   return String(step.appearance).toUpperCase();
 }
 
+function renderSurface(
+  engine: FlowSessionEngine,
+  { appearance, resetNonce, ...surfaceProps }: StepRender,
+): React.ReactElement {
+  return appearance === 'TOOLTIP' ? (
+    <TooltipSurface engine={engine} resetNonce={resetNonce} {...surfaceProps} />
+  ) : (
+    <ModalSurface engine={engine} {...surfaceProps} />
+  );
+}
+
 /**
  * Renders the active flow step.
  *
- * TOOLTIP → {@link TooltipSurface}; everything else → {@link ModalSurface}
- * (BUBBLE/HIDDEN remain centered-card fallbacks until dedicated surfaces).
+ * TOOLTIP → {@link TooltipSurface}; HIDDEN → nothing (session and triggers
+ * stay active); everything else → {@link ModalSurface} (BUBBLE remains a
+ * centered-card fallback until a dedicated surface).
  */
-export function FlowRenderer({ engine }: FlowRendererProps): React.ReactElement | null {
-  const { session, currentStep } = useFlowSessionState(engine);
+export function FlowRenderer({
+  engine,
+  previewRestartGeneration = 0,
+}: FlowRendererProps): React.ReactElement | null {
+  const { session, currentStep, stepShowNonce } = useFlowSessionState(engine);
   const lookupAttribute = React.useMemo(
     () => genSessionDataLookup(session?.data ?? []),
     [session?.data],
@@ -33,28 +55,34 @@ export function FlowRenderer({ engine }: FlowRendererProps): React.ReactElement
     return null;
   }
 
-  const theme = currentStep.theme ?? session.version.theme;
   const appearance = appearanceOf(currentStep);
-  const animationKey = `${session.id}:${currentStep.id}:${appearance}`;
-
-  const surface =
-    appearance === 'TOOLTIP' ? (
-      <TooltipSurface
-        engine={engine}
-        session={session}
-        currentStep={currentStep}
-        theme={theme}
-        lookupAttribute={lookupAttribute}
-      />
-    ) : (
-      <ModalSurface
-        engine={engine}
-        session={session}
-        currentStep={currentStep}
-        theme={theme}
-        lookupAttribute={lookupAttribute}
-      />
-    );
-
-  return <FlowSurfaceFade animationKey={animationKey}>{surface}</FlowSurfaceFade>;
+  // No chrome, and no FlowSurfaceFade: its exit blocker would intercept the
+  // in-app tap a hidden step is waiting for.
+  if (appearance === 'HIDDEN') {
+    return null;
+  }
+  // Step+appearance only: session identity is the React key below so a new
+  // flow remounts the fade instead of holding the outgoing flow for CARD_EXIT_MS
+  // (that hold is what made a START_FLOW replacement look like two flows).
+  // `resetNonce` is frozen with the shown step so an exiting card does not
+  // re-resolve; it is not part of animationKey (that would fade the same step).
+  const animationKey = `${currentStep.id}:${appearance}`;
+  const resetNonce = previewRestartGeneration + stepShowNonce;
+
+  return (
+    <FlowSurfaceFade
+      key={session.id}
+      animationKey={animationKey}
+      step={{
+        appearance,
+        session,
+        currentStep,
+        theme: currentStep.theme ?? session.version.theme,
+        lookupAttribute,
+        resetNonce,
+      }}
+    >
+      {(shown) => renderSurface(engine, shown)}
+    </FlowSurfaceFade>
+  );
 }

package/src/runtime/FlowSurfaceFade.tsx

@@ -1,50 +1,71 @@
 import * as React from 'react';
-import { Animated, StyleSheet, View } from 'react-native';
+import { StyleSheet, View } from 'react-native';
 
 import { ABSOLUTE_FILL } from '../surfaces/absoluteFill';
+import { CARD_EXIT_MS, CardTransitionProvider } from '../surfaces/cardTransition';
+import { getSurfaceInteractionBlocking } from '../surfaces/surfaceInteractionConfig';
 
-const FADE_MS = 180;
-
-export interface FlowSurfaceFadeProps {
-  children: React.ReactNode;
-  /** Bumps when the active step changes so we fade in again. */
+export interface FlowSurfaceFadeProps<TStep> {
+  /** Bumps when the active step changes, driving the crossfade. */
   animationKey: string;
+  /** Render data for `animationKey`. */
+  step: TStep;
+  children: (step: TStep) => React.ReactNode;
 }
 
 /**
- * Short opacity fade for flow surface entry (FLOW_RENDERING_SPEC minimum).
- * Exit fades when the keyed surface unmounts via a brief hold are deferred —
- * step swaps remount with a fresh fade-in.
+ * Crossfades flow surfaces on step changes: the outgoing card fades out, then
+ * the incoming step mounts and fades in — no cut, no flash at full opacity.
+ * Cards animate themselves off the phase published here (see `useCardOpacity`),
+ * which keeps backdrops and cutouts steady across the swap.
+ *
+ * The outgoing step keeps rendering from `step` captured at the last swap, so
+ * the surface is not remounted mid-exit (a remount would re-resolve anchors and
+ * flash the tooltip's waiting state).
+ *
+ * A new flow remounts this component (`key={session.id}` in FlowRenderer) so
+ * the outgoing flow is not held across a START_FLOW replacement.
+ *
+ * Exit on flow end unmounts immediately: the surface is gone as soon as the
+ * session is cleared.
  */
-export function FlowSurfaceFade({
-  children,
+export function FlowSurfaceFade<TStep>({
   animationKey,
-}: FlowSurfaceFadeProps): React.ReactElement {
-  const opacity = React.useRef(new Animated.Value(0)).current;
+  step,
+  children,
+}: FlowSurfaceFadeProps<TStep>): React.ReactElement {
+  const [shownKey, setShownKey] = React.useState(animationKey);
+  const exiting = shownKey !== animationKey;
+  const shownStep = React.useRef(step);
+  if (!exiting) {
+    shownStep.current = step;
+  }
 
   React.useEffect(() => {
-    opacity.setValue(0);
-    const animation = Animated.timing(opacity, {
-      toValue: 1,
-      duration: FADE_MS,
-      useNativeDriver: true,
-    });
-    animation.start();
+    if (!exiting) {
+      return;
+    }
+    const timer = setTimeout(() => {
+      setShownKey(animationKey);
+    }, CARD_EXIT_MS);
     return () => {
-      animation.stop();
+      clearTimeout(timer);
     };
-  }, [animationKey, opacity]);
+  }, [animationKey, exiting]);
+
+  const blockInteraction = getSurfaceInteractionBlocking();
 
   return (
-    <Animated.View
-      testID="userflow-surface-fade"
-      style={[styles.fill, { opacity }]}
-      pointerEvents="box-none"
-    >
-      <View style={styles.fill} pointerEvents="box-none">
-        {children}
+    <View testID="userflow-surface-fade" style={styles.fill} pointerEvents="box-none">
+      {exiting && blockInteraction ? (
+        <View testID="userflow-surface-exit-blocker" style={styles.fill} pointerEvents="auto" />
+      ) : null}
+      <View style={styles.fill} pointerEvents={exiting ? 'none' : 'box-none'}>
+        <CardTransitionProvider value={exiting ? 'exiting' : 'entering'}>
+          {children(shownStep.current)}
+        </CardTransitionProvider>
       </View>
-    </Animated.View>
+    </View>
   );
 }
 

package/src/runtime/TargetPressBridge.tsx

@@ -1,57 +1,39 @@
 import * as React from 'react';
-import { StyleSheet, View, type GestureResponderEvent, type NativeTouchEvent } from 'react-native';
+import { StyleSheet, View, type GestureResponderEvent } from 'react-native';
 
 import { targetPressMonitor } from '../anchors/targetPressMonitor';
 
+import { changedTouchPoints, forEachChangedTouch } from './changedTouchPoints';
+
 export interface TargetPressBridgeProps {
   children: React.ReactNode;
 }
 
-/**
- * Touches that just started/ended/cancelled for this event. Prefer
- * `changedTouches` so multi-touch uses the finger(s) that actually changed —
- * `touches[0]` may be an already-active finger. Each touch carries `identifier`
- * so the monitor can pair start/end per finger.
- */
-function changedTouchPoints(
-  event: GestureResponderEvent,
-): Array<Pick<NativeTouchEvent, 'identifier' | 'pageX' | 'pageY'>> {
-  const { changedTouches, touches, identifier, pageX, pageY } = event.nativeEvent;
-  if (changedTouches && changedTouches.length > 0) {
-    return changedTouches.map((touch) => ({
-      identifier: touch.identifier,
-      pageX: touch.pageX,
-      pageY: touch.pageY,
-    }));
-  }
-  if (touches && touches.length > 0) {
-    const touch = touches[touches.length - 1]!;
-    return [{ identifier: touch.identifier, pageX: touch.pageX, pageY: touch.pageY }];
-  }
-  return [{ identifier: identifier ?? 0, pageX, pageY }];
-}
-
 /**
  * Wraps app content so tooltip target taps can be observed without stealing
- * them from the underlying control (web parity: click listener, no preventDefault).
+ * them from the underlying control (web parity: click listener, no
+ * preventDefault).
  *
  * The Userflow overlay is a sibling above the app, so hole Pressables would
  * intercept presses. Instead we hit-test bubbled `onTouchStart` / `onTouchEnd`
  * against the rect registered by {@link TooltipSurface}.
  *
+ * Preview-chrome double taps are observed by `DoubleTapBridge` around the
+ * whole provider tree — this bridge never sees overlay touches.
+ *
  * Does not claim the gesture responder.
  */
 export function TargetPressBridge({ children }: TargetPressBridgeProps): React.ReactElement {
   const onTouchStart = React.useCallback((event: GestureResponderEvent) => {
-    for (const touch of changedTouchPoints(event)) {
-      targetPressMonitor.handleTouchStart(touch.identifier, touch.pageX, touch.pageY);
-    }
+    forEachChangedTouch(event, (identifier, pageX, pageY) => {
+      targetPressMonitor.handleTouchStart(identifier, pageX, pageY);
+    });
   }, []);
 
   const onTouchEnd = React.useCallback((event: GestureResponderEvent) => {
-    for (const touch of changedTouchPoints(event)) {
-      targetPressMonitor.handleTouchEnd(touch.identifier, touch.pageX, touch.pageY);
-    }
+    forEachChangedTouch(event, (identifier, pageX, pageY) => {
+      targetPressMonitor.handleTouchEnd(identifier, pageX, pageY);
+    });
   }, []);
 
   const onTouchCancel = React.useCallback((event: GestureResponderEvent) => {

package/src/runtime/UserflowProvider.tsx

@@ -3,14 +3,19 @@ import * as React from 'react';
 import { StyleSheet, View } from 'react-native';
 
 import { FiberScanRoot } from '../anchors/fiber/FiberScanRoot';
+import { ElementPickerOverlay } from '../authoring/ElementPickerOverlay';
+import { DoubleTapBridge } from '../authoring/chrome/DoubleTapBridge';
+import { elementPickerController } from '../authoring/elementPickerController';
 import { PreviewModeBanner } from '../pairing/PreviewModeBanner';
 import { getPairingController } from '../pairing/pairingRuntime';
 import { usePairingState } from '../pairing/usePairingState';
 import { ABSOLUTE_FILL } from '../surfaces/absoluteFill';
+import { SurfaceLayoutInsetsProvider } from '../surfaces/surfaceLayoutInsets';
 
 import { FlowRenderer } from './FlowRenderer';
 import { TargetPressBridge } from './TargetPressBridge';
 import { getFlowSessionEngine } from './flowEngine';
+import { useFlowSessionState } from './useFlowSessionState';
 import { getUserflowCore } from './userflowCore';
 
 export interface UserflowContextValue {
@@ -31,14 +36,16 @@ export interface UserflowProviderProps {
  * calling {@link Userflow.init}.
  *
  * Children render normally. An absolute overlay sits above them with
- * `pointerEvents="box-none"` so taps pass through except where flow UI sits.
+ * `pointerEvents="box-none"` so taps pass through except where flow UI blocks
+ * them (modals always; tooltips when interaction blocking is enabled).
  * We deliberately do not use RN `<Modal>` — it is the wrong primitive for
  * non-modal tooltips (WS6).
  *
  * **Expo Router:** also mount `UserflowExpoRouterScreenTracker` from
- * `@userflow-tech/react-native/expo-router` under this provider so pathname changes
- * and path-like NAVIGATE actions are wired. The tracker is a separate entry so
- * apps without `expo-router` are not forced to install that peer.
+ * `@userflow-tech/react-native/expo-router` under this provider so pathname and
+ * navigation-state changes and path-like NAVIGATE actions are wired. The tracker
+ * is a separate entry so apps without `expo-router` are not forced to install
+ * that peer.
  *
  * **React Navigation:** wrap `NavigationContainer` with
  * {@link WithUserflowReactNavigation} from `@userflow-tech/react-native/navigation`.
@@ -50,22 +57,75 @@ export function UserflowProvider({
   const engine = engineProp ?? getFlowSessionEngine(getUserflowCore());
   const contextValue = React.useMemo<UserflowContextValue>(() => ({ engine }), [engine]);
   const pairingState = usePairingState();
+  const { session, currentStep } = useFlowSessionState(engine);
+  const [previewConfirming, setPreviewConfirming] = React.useState(false);
+  const [pickerActive, setPickerActive] = React.useState(
+    () => elementPickerController.getState().active,
+  );
+
+  React.useEffect(() => {
+    return elementPickerController.subscribe((next) => {
+      setPickerActive(next.active);
+    });
+  }, []);
+
+  const trapHostAccessibility = React.useMemo(() => {
+    if (previewConfirming) {
+      return true;
+    }
+    if (!session || !currentStep) {
+      return false;
+    }
+    const appearance = String(currentStep.appearance).toUpperCase();
+    if (appearance === 'HIDDEN') {
+      return false;
+    }
+    if (appearance !== 'TOOLTIP') {
+      return true;
+    }
+    return currentStep.tooltipTargetBlocked;
+  }, [previewConfirming, session, currentStep]);
 
   const onExitPreview = React.useCallback(() => {
     void getPairingController(getUserflowCore()).exitPreview();
   }, []);
 
+  const onRestartPreview = React.useCallback(() => {
+    void getPairingController(getUserflowCore()).restartPreview();
+  }, []);
+
   return (
     <UserflowContext.Provider value={contextValue}>
-      <View style={styles.root} collapsable={false}>
-        <TargetPressBridge>
-          <FiberScanRoot>{children}</FiberScanRoot>
-        </TargetPressBridge>
-        <View style={styles.overlay} pointerEvents="box-none">
-          <PreviewModeBanner state={pairingState} onExit={onExitPreview} />
-          <FlowRenderer engine={engine} />
-        </View>
-      </View>
+      <SurfaceLayoutInsetsProvider>
+        <DoubleTapBridge>
+          <View style={styles.root} collapsable={false}>
+            <View
+              style={styles.appContent}
+              testID="userflow-app-content"
+              importantForAccessibility={trapHostAccessibility ? 'no-hide-descendants' : undefined}
+              accessibilityElementsHidden={trapHostAccessibility ? true : undefined}
+            >
+              <TargetPressBridge>
+                <FiberScanRoot>{children}</FiberScanRoot>
+              </TargetPressBridge>
+            </View>
+            <View style={styles.overlay} pointerEvents="box-none">
+              <PreviewModeBanner
+                onConfirmingChange={setPreviewConfirming}
+                onExit={onExitPreview}
+                onRestart={onRestartPreview}
+                state={pairingState}
+                suppressed={pickerActive}
+              />
+              <FlowRenderer
+                engine={engine}
+                previewRestartGeneration={pairingState.previewRestartGeneration}
+              />
+              <ElementPickerOverlay />
+            </View>
+          </View>
+        </DoubleTapBridge>
+      </SurfaceLayoutInsetsProvider>
     </UserflowContext.Provider>
   );
 }
@@ -83,6 +143,9 @@ const styles = StyleSheet.create({
   root: {
     flex: 1,
   },
+  appContent: {
+    flex: 1,
+  },
   overlay: {
     ...ABSOLUTE_FILL,
   },

package/src/runtime/changedTouchPoints.ts

@@ -0,0 +1,34 @@
+import type { GestureResponderEvent, NativeTouchEvent } from 'react-native';
+
+/**
+ * Touches that just started/ended/cancelled for this event. Prefer
+ * `changedTouches` so multi-touch uses the finger(s) that actually changed —
+ * `touches[0]` may be an already-active finger. Each touch carries `identifier`
+ * so monitors can pair start/end per finger.
+ */
+export function changedTouchPoints(
+  event: GestureResponderEvent,
+): Array<Pick<NativeTouchEvent, 'identifier' | 'pageX' | 'pageY'>> {
+  const { changedTouches, touches, identifier, pageX, pageY } = event.nativeEvent;
+  if (changedTouches && changedTouches.length > 0) {
+    return changedTouches.map((touch) => ({
+      identifier: touch.identifier,
+      pageX: touch.pageX,
+      pageY: touch.pageY,
+    }));
+  }
+  if (touches && touches.length > 0) {
+    const touch = touches[touches.length - 1]!;
+    return [{ identifier: touch.identifier, pageX: touch.pageX, pageY: touch.pageY }];
+  }
+  return [{ identifier: identifier ?? 0, pageX, pageY }];
+}
+
+export function forEachChangedTouch(
+  event: GestureResponderEvent,
+  fn: (identifier: NativeTouchEvent['identifier'], pageX: number, pageY: number) => void,
+): void {
+  for (const touch of changedTouchPoints(event)) {
+    fn(touch.identifier, touch.pageX, touch.pageY);
+  }
+}

package/src/runtime/flowEngine.ts

@@ -16,6 +16,8 @@ export function getFlowSessionEngine(core: UserflowCore): FlowSessionEngine {
       onOpenExternalUrl: (url) => {
         void openFlowNavigateUrl(url);
       },
+      updateUser: (attributes) => core.updateUser(attributes),
+      updateGroup: (attributes, options) => core.updateGroup(attributes, options),
     });
   }
   return flowEngine;

package/src/runtime/flowSessionViewState.ts

@@ -5,6 +5,12 @@ import type { FlowSessionFragment, FlowStepFragment } from '@userflow-tech/proto
 export interface FlowSessionViewState {
   session: FlowSessionFragment | null;
   currentStepId: string | null;
+  /**
+   * Bumped on every `goToStep`, including a ForceGoToStep back to the current
+   * step, so tooltip targeting can re-bootstrap when session/step identity
+   * would otherwise be unchanged (draft preview restart).
+   */
+  stepShowNonce: number;
 }
 
 export function initialFlowSessionViewState(
@@ -13,15 +19,19 @@ export function initialFlowSessionViewState(
   return {
     session,
     currentStepId: session?.currentStep?.id ?? null,
+    stepShowNonce: 0,
   };
 }
 
 /**
  * Reduces engine events into view state.
  *
- * Important: `goToStep` updates `currentStepId` without requiring a new
- * `sessionChange` — the engine mutates `session.currentStep` in place and
- * `ForceGoToStep` does not update it at all.
+ * `goToStep` updates `currentStepId` without a new `sessionChange`. A later
+ * same-session SetFlowSession must not snap back to `session.currentStep` —
+ * tracking a button event enqueues `check_sessions`, which can push a stale
+ * current step. Web `FlowApp` `updateSession` keeps the local step for the
+ * same session id (and only falls back if that step was deleted from the
+ * version).
  */
 export function reduceFlowSessionViewState(
   state: FlowSessionViewState,
@@ -31,21 +41,49 @@ export function reduceFlowSessionViewState(
     case 'sessionChange':
       return {
         session: event.session,
-        currentStepId: event.session?.currentStep?.id ?? null,
+        currentStepId: resolveSessionChangeStepId(state, event.session),
+        stepShowNonce: state.session?.id === event.session?.id ? state.stepShowNonce : 0,
       };
     case 'goToStep':
       return {
         ...state,
         currentStepId: event.stepId,
+        stepShowNonce: state.stepShowNonce + 1,
       };
     case 'flowEnded':
       return {
         session: null,
         currentStepId: null,
+        stepShowNonce: 0,
       };
   }
 }
 
+function resolveSessionChangeStepId(
+  state: FlowSessionViewState,
+  session: FlowSessionFragment | null,
+): string | null {
+  if (session == null) {
+    return null;
+  }
+  if (state.session?.id !== session.id || state.currentStepId == null) {
+    return session.currentStep?.id ?? null;
+  }
+  const previousStep = state.session.version.steps.find((step) => step.id === state.currentStepId);
+  const byCrossVersionId =
+    previousStep == null
+      ? undefined
+      : session.version.steps.find((step) => step.crossVersionId === previousStep.crossVersionId);
+  if (byCrossVersionId) {
+    return byCrossVersionId.id;
+  }
+  const byId = session.version.steps.find((step) => step.id === state.currentStepId);
+  if (byId) {
+    return byId.id;
+  }
+  return session.currentStep?.id ?? null;
+}
+
 export function resolveCurrentStep(
   session: FlowSessionFragment | null,
   currentStepId: string | null,