@userflow-tech/react-native 0.1.1 → 0.3.0

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/SdkErrorBoundary.tsx

@@ -0,0 +1,77 @@
+import * as React from 'react';
+
+import { reportSdkError } from './reportSdkError';
+
+export interface SdkErrorBoundaryProps {
+  /** Label included in the isolated-error log (for example `overlay`). */
+  scope: string;
+  /**
+   * When this value changes after a caught error, the boundary retries its
+   * children — but only if that identity has not already failed. A reconnect
+   * that restores the same session/step stays blank. Does not remount children
+   * while they are healthy.
+   */
+  resetKey?: string;
+  /** Called after a render error is isolated (for example to clear an a11y trap). */
+  onError?: (error: Error) => void;
+  children: React.ReactNode;
+}
+
+interface SdkErrorBoundaryState {
+  hasError: boolean;
+  resetKey: string | undefined;
+  failedKeys: string[];
+}
+
+/**
+ * Contains React render/lifecycle errors in SDK UI so they cannot unmount the
+ * host app tree. Event handlers and async work are not covered — those use
+ * {@link isolateSync} / {@link isolateAsync}.
+ */
+export class SdkErrorBoundary extends React.Component<
+  SdkErrorBoundaryProps,
+  SdkErrorBoundaryState
+> {
+  override state: SdkErrorBoundaryState = {
+    hasError: false,
+    resetKey: this.props.resetKey,
+    failedKeys: [],
+  };
+
+  static getDerivedStateFromError(): Partial<SdkErrorBoundaryState> {
+    return { hasError: true };
+  }
+
+  static getDerivedStateFromProps(
+    props: SdkErrorBoundaryProps,
+    state: SdkErrorBoundaryState,
+  ): Partial<SdkErrorBoundaryState> | null {
+    if (props.resetKey === state.resetKey) {
+      return null;
+    }
+    const nextKey = props.resetKey ?? '';
+    if (nextKey !== '' && state.failedKeys.includes(nextKey)) {
+      return { hasError: true, resetKey: props.resetKey };
+    }
+    return { hasError: false, resetKey: props.resetKey };
+  }
+
+  override componentDidCatch(error: Error, info: React.ErrorInfo): void {
+    reportSdkError(this.props.scope, error, info.componentStack);
+    this.props.onError?.(error);
+    const key = this.props.resetKey;
+    if (!key) {
+      return;
+    }
+    this.setState((prev) =>
+      prev.failedKeys.includes(key) ? null : { failedKeys: [...prev.failedKeys, key] },
+    );
+  }
+
+  override render(): React.ReactNode {
+    if (this.state.hasError) {
+      return null;
+    }
+    return this.props.children;
+  }
+}

package/src/runtime/TargetPressBridge.tsx

@@ -1,68 +1,57 @@
 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';
+import { isolateSync } from './isolateCall';
+
 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);
-    }
+    isolateSync('target-press', () => {
+      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);
-    }
+    isolateSync('target-press', () => {
+      forEachChangedTouch(event, (identifier, pageX, pageY) => {
+        targetPressMonitor.handleTouchEnd(identifier, pageX, pageY);
+      });
+    });
   }, []);
 
   const onTouchCancel = React.useCallback((event: GestureResponderEvent) => {
-    const points = changedTouchPoints(event);
-    if (points.length === 0) {
-      targetPressMonitor.cancelTouch();
-      return;
-    }
-    for (const touch of points) {
-      targetPressMonitor.cancelTouch(touch.identifier);
-    }
+    isolateSync('target-press', () => {
+      const points = changedTouchPoints(event);
+      if (points.length === 0) {
+        targetPressMonitor.cancelTouch();
+        return;
+      }
+      for (const touch of points) {
+        targetPressMonitor.cancelTouch(touch.identifier);
+      }
+    });
   }, []);
 
   return (

package/src/runtime/UserflowOverlay.tsx

@@ -0,0 +1,118 @@
+import type { BannerSessionEngine, FlowSessionEngine } from '@userflow-tech/core';
+import * as React from 'react';
+
+import { ElementPickerOverlay } from '../authoring/ElementPickerOverlay';
+import { elementPickerController } from '../authoring/elementPickerController';
+import { EvalJsHost } from '../evalJs/EvalJsHost';
+import { PreviewModeBanner } from '../pairing/PreviewModeBanner';
+import { getPairingController } from '../pairing/pairingRuntime';
+import { usePairingState } from '../pairing/usePairingState';
+import { usePreviewBarHold } from '../pairing/usePreviewBarHold';
+
+import { BannerHost } from './BannerHost';
+import { FlowRenderer } from './FlowRenderer';
+import { useFlowSessionState } from './useFlowSessionState';
+import { getUserflowCore } from './userflowCore';
+
+export interface UserflowOverlayProps {
+  engine: FlowSessionEngine;
+  bannerEngine: BannerSessionEngine;
+  /** Keep the host a11y trap in the provider (outside this error boundary). */
+  onTrapChange: (trap: boolean) => void;
+}
+
+/**
+ * SDK overlay chrome: preview banner, active flow surface, element picker.
+ * Mounted inside {@link SdkErrorBoundary} so a render throw here cannot
+ * unmount host children of {@link UserflowProvider}.
+ */
+export function UserflowOverlay({
+  engine,
+  bannerEngine,
+  onTrapChange,
+}: UserflowOverlayProps): React.ReactElement {
+  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 previewHeld = usePreviewBarHold(pairingState, pickerActive);
+
+  const trapHostAccessibility = React.useMemo(() => {
+    // Picking hides flow chrome, so the host must stay in the accessibility tree.
+    if (pickerActive) {
+      return false;
+    }
+    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;
+  }, [pickerActive, previewConfirming, session, currentStep]);
+
+  React.useLayoutEffect(() => {
+    onTrapChange(trapHostAccessibility);
+    return () => {
+      // Release whenever this overlay unmounts — including when
+      // SdkErrorBoundary replaces it with null and onError never runs.
+      onTrapChange(false);
+    };
+  }, [onTrapChange, trapHostAccessibility]);
+
+  const onExitPreview = React.useCallback(() => {
+    void getPairingController(getUserflowCore()).exitPreview();
+  }, []);
+
+  const onRestartPreview = React.useCallback(() => {
+    void getPairingController(getUserflowCore()).restartPreview();
+  }, []);
+
+  return (
+    <>
+      {/*
+       * Under the preview banner and flow chrome (later siblings paint on top).
+       * Outside FlowRenderer so picking, which unmounts flow chrome, does not
+       * destroy a running script. `suppressed` hides it for the pick.
+       */}
+      <EvalJsHost suppressed={pickerActive} />
+      <PreviewModeBanner
+        onConfirmingChange={setPreviewConfirming}
+        onExit={onExitPreview}
+        held={previewHeld}
+        onRestart={onRestartPreview}
+        state={pairingState}
+        suppressed={pickerActive}
+      />
+      {/*
+       * Unmount flow chrome for the whole pick. The session stays alive;
+       * captureScreen would otherwise include the modal or tooltip.
+       * Remounting reads the same session back.
+       */}
+      <BannerHost engine={bannerEngine} hidden={pickerActive} />
+      {pickerActive ? null : (
+        <FlowRenderer
+          engine={engine}
+          previewRestartGeneration={pairingState.previewRestartGeneration}
+        />
+      )}
+      <ElementPickerOverlay />
+    </>
+  );
+}