@userflow-tech/react-native 0.1.1 → 0.2.0

package/src/surfaces/TooltipSurface.tsx

@@ -18,10 +18,16 @@ import {
 } from 'react-native';
 
 import { anchorRegistry } from '../anchors/AnchorRegistry';
+import { autoAnchorRegistry } from '../anchors/AutoAnchorRegistry';
 import { addAnimationFrameCallback, removeAnimationFrameCallback } from '../anchors/animationFrame';
 import { fiberScanRoot } from '../anchors/fiber/FiberScanRoot';
 import type { AnyFiber } from '../anchors/fiber/fiberInternals';
-import { invalidateFiberAnchor, resolveAnchorHost } from '../anchors/resolveAnchorHost';
+import {
+  clearFiberAnchorCache,
+  invalidateFiberAnchor,
+  resolveAnchorHost,
+} from '../anchors/resolveAnchorHost';
+import { resolveAutoAnchorHost } from '../anchors/resolveAutoAnchorHost';
 import { resolveManualAnchorId } from '../anchors/resolveManualAnchorId';
 import { scrollAnchorIntoView } from '../anchors/scrollAnchorIntoView';
 import { getScrollPadding } from '../anchors/scrollConfig';
@@ -29,31 +35,47 @@ import { targetPressMonitor } from '../anchors/targetPressMonitor';
 import { RichContentRenderer } from '../content/RichContentRenderer';
 import type { LookupAttribute } from '../content/types';
 
+import { CardFade } from './CardFade';
 import { CloseButton } from './CloseButton';
-import { resolveCloseButtonColor } from './resolveCloseButtonColor';
 import { MADE_WITH_USERFLOW_GAP, MadeWithUserflow } from './MadeWithUserflow';
 import { ProgressBar } from './ProgressBar';
 import { ABSOLUTE_FILL } from './absoluteFill';
+import { useCardTransitionPhase } from './cardTransition';
 import { parseBackdropOpacity } from './parseBackdropOpacity';
 import { resolveStepProgress } from './progress';
-import { useUserflowSafeAreaInsets } from './safeArea';
+import { resolveCloseButtonColor } from './resolveCloseButtonColor';
+import { outsideHighlightOutset, resolveHighlightChrome } from './resolveHighlightChrome';
+import { resolveModalCardMaxHeight } from './resolveModalLayout';
+import {
+  resolveTooltipButtonsAlign,
+  resolveTooltipCardLayout,
+  resolveTooltipCardMaxWidth,
+} from './resolveTooltipLayout';
+import { paddingAsEdgeInsets, useSurfaceLayoutInsets } from './surfaceLayoutInsets';
 import { resolveBubbleChrome } from './themeChrome';
 import { TooltipBubble } from './tooltip/TooltipBubble';
 import { TooltipCutout } from './tooltip/TooltipCutout';
+import { TooltipHighlight } from './tooltip/TooltipHighlight';
 import { computeTooltipPosition } from './tooltip/computeTooltipPosition';
 import {
   inferTooltipPlacement,
+  tooltipPlacementFits,
   type Rect,
   type TooltipPlacementSide,
 } from './tooltip/inferTooltipPlacement';
 import { parseBackdropPadding } from './tooltip/parseBackdropPadding';
-import { buildEffectiveViewport, isRectFullyVisible, rectsEqual } from './tooltip/rect';
 import {
-  resolveTooltipButtonsAlign,
-  resolveTooltipCardLayout,
-  resolveTooltipCardMaxWidth,
-  resolveTooltipCenterPadding,
-} from './resolveTooltipLayout';
+  warnTooltipPlacementUnanchored,
+  warnTooltipSidePlacementDropped,
+} from './tooltip/placementDiagnostics';
+import { buildEffectiveViewport, expandRect, isRectFullyVisible, rectsEqual } from './tooltip/rect';
+import {
+  resolveTooltipSideCardWidth,
+  tooltipMinCardHeight,
+  tooltipMinSideCardWidth,
+  tooltipSideGap,
+  tooltipVerticalGap,
+} from './tooltip/resolveSideCardWidth';
 
 export interface TooltipSurfaceProps {
   engine: FlowSessionEngine;
@@ -61,6 +83,12 @@ export interface TooltipSurfaceProps {
   currentStep: FlowStepFragment;
   theme: ThemeFragment;
   lookupAttribute: LookupAttribute;
+  /**
+   * Bumped on preview restart and every goToStep, including a ForceGoToStep
+   * back to the current step, so targeting re-bootstraps when session/step
+   * identity is unchanged.
+   */
+  resetNonce?: number;
 }
 
 type MissingMode = 'waiting' | 'reported';
@@ -69,6 +97,11 @@ type MissingMode = 'waiting' | 'reported';
 const RESOLVE_MS = 250;
 /** Slower resolve poll after FLAG/ERROR report so a late-mounting target can recover. */
 const RESOLVE_SLOW_MS = 1000;
+/**
+ * One-frame delay before the first resolve after a step/reset so dialog
+ * teardown cannot arm the missing-target timer with a 0-size measure.
+ */
+export const FIRST_RESOLVE_DELAY_MS = 16;
 /**
  * Max scroll-into-view attempts per step while the target stays partially
  * clipped. Only a safety net for targets that can never become fully visible —
@@ -95,6 +128,18 @@ function missingBehavior(theme: ThemeFragment): string {
   return String(theme.tooltipMissingBehavior ?? 'FLAG').toUpperCase();
 }
 
+/** Dim with no card yet, for the frames between mount and the first measure. */
+function backdropOnly(blocker: React.ReactNode): React.ReactElement | null {
+  if (blocker == null) {
+    return null;
+  }
+  return (
+    <View style={styles.root} testID="userflow-tooltip-surface" pointerEvents="box-none">
+      {blocker}
+    </View>
+  );
+}
+
 /**
  * Anchored tooltip chrome: measure manual / fiber anchor, place with web flip/shift,
  * optional cutout backdrop, missing-target report + theme fallbacks.
@@ -105,6 +150,7 @@ export function TooltipSurface({
   currentStep,
   theme,
   lookupAttribute,
+  resetNonce = 0,
 }: TooltipSurfaceProps): React.ReactElement | null {
   const version = session.version;
   const chrome = resolveBubbleChrome(theme, 'tooltip');
@@ -112,14 +158,33 @@ export function TooltipSurface({
   const showClose = !version.closeDisabled;
   const backdropOpacity = parseBackdropOpacity(theme.backdropOpacity);
   const backdropPadding = parseBackdropPadding(currentStep.backdropPadding);
-  const anchorId = resolveManualAnchorId(currentStep.selector?.css);
+  const selector = currentStep.selector;
+  const isAuto = (selector?.type as string | null) === 'AUTO';
+  const autoData = selector?.autoData ?? null;
+  const anchorId = isAuto ? null : resolveManualAnchorId(selector?.css);
+  const targetKey = isAuto ? `auto:${autoData ?? ''}` : (anchorId ?? '');
+  const highlight = currentStep.backdrop ? resolveHighlightChrome(theme, backdropPadding) : null;
+  const outsideHighlightSpread = highlight ? outsideHighlightOutset(highlight) : 0;
   const desiredPlacement = normalizePlacement(currentStep.tooltipPlacement);
   const behavior = missingBehavior(theme);
-  const insets = useUserflowSafeAreaInsets();
-  const centerPaddingStyle = resolveTooltipCenterPadding(insets);
+  /**
+   * An exiting card stays mounted for the fade, so anything it fires belongs to
+   * a step the user already left. Mirrored into a ref for the callbacks that run
+   * outside render (native touches, measure callbacks, timers).
+   */
+  const isExiting = useCardTransitionPhase() === 'exiting';
+  const exitingRef = React.useRef(isExiting);
+  exitingRef.current = isExiting;
+  const layoutInsets = useSurfaceLayoutInsets();
+  const centerPaddingStyle = layoutInsets;
 
   const [keyboardBottomInset, setKeyboardBottomInset] = React.useState(0);
   const [target, setTarget] = React.useState<Rect | null>(null);
+  /**
+   * Placeholder until the card's first `onLayout`. A narrowed LEFT/RIGHT can
+   * leave a 2–3× smaller/taller measurement here; that must not leak into the
+   * next step's `fits()` (see the reset on `currentStep.id`).
+   */
   const [bubbleSize, setBubbleSize] = React.useState({ width: 280, height: 160 });
   const [placement, setPlacement] = React.useState<TooltipPlacementSide>(
     desiredPlacement ?? 'BELOW',
@@ -128,10 +193,22 @@ export function TooltipSurface({
   const [registryTick, setRegistryTick] = React.useState(0);
   /** True after at least one *failed* measure for the current step/anchor. */
   const [measureAttempted, setMeasureAttempted] = React.useState(false);
+  /**
+   * False only after a same-step `resetNonce` bump (preview restart) until one
+   * frame has passed, so dialog teardown cannot 0-size FLAG.
+   */
+  const [resolveArmed, setResolveArmed] = React.useState(true);
+  const targetingIdentityRef = React.useRef({
+    stepId: currentStep.id,
+    targetKey,
+    resetNonce,
+  });
 
   const reportedRef = React.useRef(false);
   const placementRef = React.useRef(placement);
   placementRef.current = placement;
+  const desiredPlacementRef = React.useRef(desiredPlacement);
+  desiredPlacementRef.current = desiredPlacement;
   const mountedRef = React.useRef(true);
   const targetRef = React.useRef<Rect | null>(null);
   /** Bounded scroll-into-view attempts for the current step. */
@@ -144,16 +221,35 @@ export function TooltipSurface({
   const scrollSettledRef = React.useRef(false);
   /** In-flight measureInWindow guard for the rAF loop. */
   const measureInFlightRef = React.useRef(false);
+  /**
+   * Bumped whenever the resolved host is dropped. `measureInWindow` is async, so
+   * a measurement dispatched before the drop can still land after it — without
+   * this guard it re-anchors a target the resolver has already rejected, and the
+   * tooltip flip-flops between anchored and "looking for target".
+   */
+  const resolveEpochRef = React.useRef(0);
   /** Latest resolved host fiber (for scroll-ancestor walk + rAF remeasure). */
   const hostFiberRef = React.useRef<AnyFiber | null>(null);
   const hostMeasureRef = React.useRef<
     ((callback: (x: number, y: number, width: number, height: number) => void) => void) | null
   >(null);
   const hostScrollIntoViewRef = React.useRef<(() => void) | undefined>(undefined);
+  /** Fiber-cache key for the current host; AUTO exact-id path sets this even when `anchorId` is null. */
+  const fiberCacheIdRef = React.useRef<string | null>(null);
+  /** Step id we already warned about for a dropped LEFT/RIGHT placement. */
+  const warnedSidePlacementStepRef = React.useRef<string | null>(null);
+  const currentStepIdRef = React.useRef(currentStep.id);
+  currentStepIdRef.current = currentStep.id;
+  /**
+   * Step the current `target` rect was measured for. A step advance re-renders
+   * with the new step before the reset effect clears `target`, so for one commit
+   * the new step's placement is evaluated against the previous target.
+   */
+  const targetStepIdRef = React.useRef<string | null>(null);
   const keyboardBottomInsetRef = React.useRef(keyboardBottomInset);
   keyboardBottomInsetRef.current = keyboardBottomInset;
-  const insetsRef = React.useRef(insets);
-  insetsRef.current = insets;
+  const insetsRef = React.useRef(layoutInsets);
+  insetsRef.current = layoutInsets;
   const missingModeRef = React.useRef(missingMode);
   missingModeRef.current = missingMode;
   const behaviorRef = React.useRef(behavior);
@@ -175,9 +271,11 @@ export function TooltipSurface({
   React.useEffect(() => {
     const bump = () => setRegistryTick((n) => n + 1);
     const unsubRegistry = anchorRegistry.subscribe(bump);
+    const unsubAuto = autoAnchorRegistry.subscribe(bump);
     const unsubScan = fiberScanRoot.subscribe(bump);
     return () => {
       unsubRegistry();
+      unsubAuto();
       unsubScan();
     };
   }, []);
@@ -187,17 +285,44 @@ export function TooltipSurface({
     scrollAttemptsRef.current = 0;
     scrollSettledRef.current = false;
     measureInFlightRef.current = false;
+    resolveEpochRef.current += 1;
     hostFiberRef.current = null;
     hostMeasureRef.current = null;
     hostScrollIntoViewRef.current = undefined;
+    fiberCacheIdRef.current = null;
+    warnedSidePlacementStepRef.current = null;
+    targetStepIdRef.current = null;
     targetRef.current = null;
+    // Drop the previous card's measured size and side so the next step does not
+    // inherit a wrapped 115×400 LEFT into `fits(currentPlacement)`.
+    const nextPlacement = desiredPlacementRef.current ?? 'BELOW';
+    placementRef.current = nextPlacement;
+    setPlacement(nextPlacement);
+    setBubbleSize({ width: 280, height: 160 });
     setMissingMode('waiting');
     setMeasureAttempted(false);
     setTarget(null);
-  }, [currentStep.id, anchorId]);
+    const prev = targetingIdentityRef.current;
+    const sameIdentity = prev.stepId === currentStep.id && prev.targetKey === targetKey;
+    const nonceBumped = prev.resetNonce !== resetNonce;
+    targetingIdentityRef.current = { stepId: currentStep.id, targetKey, resetNonce };
+    // Defer only a same-step restart bootstrap. A real step/target change
+    // should resolve on the first paint.
+    setResolveArmed(!(sameIdentity && nonceBumped));
+    clearFiberAnchorCache();
+  }, [currentStep.id, targetKey, resetNonce]);
+
+  React.useEffect(() => {
+    if (resolveArmed) return;
+    const handle = setTimeout(() => {
+      if (mountedRef.current) setResolveArmed(true);
+    }, FIRST_RESOLVE_DELAY_MS);
+    return () => clearTimeout(handle);
+  }, [resolveArmed]);
 
   const applyTarget = React.useCallback((next: Rect | null) => {
     if (!mountedRef.current) return;
+    targetStepIdRef.current = next == null ? null : currentStepIdRef.current;
     if (rectsEqual(targetRef.current, next)) return;
     if (next == null) {
       // The anchor went away (unmount / navigation), so whatever scroll position
@@ -215,25 +340,45 @@ export function TooltipSurface({
     setMeasureAttempted((prev) => (prev ? prev : true));
   }, []);
 
+  /**
+   * Forget the resolved host and report the target as gone. Bumping the epoch
+   * voids any measurement still in flight for it, and releasing the in-flight
+   * guard lets the next resolve measure immediately instead of waiting on a
+   * callback that no longer means anything.
+   */
+  const dropHost = React.useCallback(() => {
+    resolveEpochRef.current += 1;
+    measureInFlightRef.current = false;
+    hostFiberRef.current = null;
+    hostMeasureRef.current = null;
+    hostScrollIntoViewRef.current = undefined;
+    fiberCacheIdRef.current = null;
+    markMeasureAttempted();
+    applyTarget(null);
+  }, [applyTarget, markMeasureAttempted]);
+
   const effectiveViewport = React.useCallback(() => {
     const windowSize = Dimensions.get('window');
     const scrollPadding = getScrollPadding();
+    const layoutPad = paddingAsEdgeInsets(insetsRef.current);
     return buildEffectiveViewport(
       {
         width: windowSize.width,
         height: Math.max(0, windowSize.height - keyboardBottomInsetRef.current),
       },
       {
-        top: (insetsRef.current.top ?? 0) + (scrollPadding?.top ?? 0),
-        right: (insetsRef.current.right ?? 0) + (scrollPadding?.right ?? 0),
-        bottom: (insetsRef.current.bottom ?? 0) + (scrollPadding?.bottom ?? 0),
-        left: (insetsRef.current.left ?? 0) + (scrollPadding?.left ?? 0),
+        top: layoutPad.top + (scrollPadding?.top ?? 0),
+        right: layoutPad.right + (scrollPadding?.right ?? 0),
+        bottom: layoutPad.bottom + (scrollPadding?.bottom ?? 0),
+        left: layoutPad.left + (scrollPadding?.left ?? 0),
       },
     );
   }, []);
 
   const maybeScrollIntoView = React.useCallback(
     (rect: Rect) => {
+      // Scrolling the app to reveal a target we are fading away from is visible.
+      if (exitingRef.current) return;
       if (scrollSettledRef.current) return;
       if (isRectFullyVisible(rect, effectiveViewport())) {
         scrollSettledRef.current = true;
@@ -271,43 +416,41 @@ export function TooltipSurface({
   const resolveTarget = React.useCallback(() => {
     if (!mountedRef.current) return;
 
-    if (!anchorId) {
-      hostFiberRef.current = null;
-      hostMeasureRef.current = null;
-      hostScrollIntoViewRef.current = undefined;
-      markMeasureAttempted();
-      applyTarget(null);
-      return;
-    }
-
-    const resolution = resolveAnchorHost(anchorId);
-    if (resolution.status !== 'found') {
-      hostFiberRef.current = null;
-      hostMeasureRef.current = null;
-      hostScrollIntoViewRef.current = undefined;
-      markMeasureAttempted();
-      applyTarget(null);
+    const resolution = isAuto
+      ? resolveAutoAnchorHost(autoData)
+      : anchorId
+        ? resolveAnchorHost(anchorId)
+        : null;
+    if (!resolution || resolution.status !== 'found') {
+      dropHost();
       return;
     }
 
     hostFiberRef.current = resolution.fiber ?? null;
     hostMeasureRef.current = resolution.host.measureInWindow;
     hostScrollIntoViewRef.current = resolution.host.scrollIntoView;
+    fiberCacheIdRef.current =
+      'fiberCacheId' in resolution && typeof resolution.fiberCacheId === 'string'
+        ? resolution.fiberCacheId
+        : (anchorId ?? null);
 
     // Kick an immediate measure after resolve so the first paint isn't waiting
     // on the next rAF (and so missing targets still mark attempted).
     if (measureInFlightRef.current) return;
+    const epoch = resolveEpochRef.current;
     measureInFlightRef.current = true;
     resolution.host.measureInWindow((x, y, width, height) => {
+      if (resolveEpochRef.current !== epoch) {
+        measureInFlightRef.current = false;
+        return;
+      }
       measureInFlightRef.current = false;
       if (!mountedRef.current) return;
 
       if (width <= 0 || height <= 0) {
-        invalidateFiberAnchor(anchorId);
-        hostFiberRef.current = null;
-        hostMeasureRef.current = null;
-        markMeasureAttempted();
-        applyTarget(null);
+        const cacheId = fiberCacheIdRef.current;
+        if (cacheId) invalidateFiberAnchor(cacheId);
+        dropHost();
         return;
       }
 
@@ -315,7 +458,7 @@ export function TooltipSurface({
       maybeScrollIntoView(rect);
       applyTarget(rect);
     });
-  }, [anchorId, applyTarget, markMeasureAttempted, maybeScrollIntoView]);
+  }, [anchorId, applyTarget, autoData, dropHost, isAuto, maybeScrollIntoView]);
 
   /**
    * Live re-measure of an already-resolved host. Driven by the shared rAF hub
@@ -327,17 +470,20 @@ export function TooltipSurface({
     const measure = hostMeasureRef.current;
     if (!measure) return;
 
+    const epoch = resolveEpochRef.current;
     measureInFlightRef.current = true;
     measure((x, y, width, height) => {
+      if (resolveEpochRef.current !== epoch) {
+        measureInFlightRef.current = false;
+        return;
+      }
       measureInFlightRef.current = false;
       if (!mountedRef.current) return;
 
       if (width <= 0 || height <= 0) {
-        if (anchorId) invalidateFiberAnchor(anchorId);
-        hostFiberRef.current = null;
-        hostMeasureRef.current = null;
-        markMeasureAttempted();
-        applyTarget(null);
+        const cacheId = fiberCacheIdRef.current;
+        if (cacheId) invalidateFiberAnchor(cacheId);
+        dropHost();
         return;
       }
 
@@ -345,14 +491,18 @@ export function TooltipSurface({
       maybeScrollIntoView(rect);
       applyTarget(rect);
     });
-  }, [anchorId, applyTarget, markMeasureAttempted, maybeScrollIntoView]);
+  }, [applyTarget, dropHost, maybeScrollIntoView]);
 
   React.useEffect(() => {
+    if (!resolveArmed) return;
     resolveTarget();
-  }, [resolveTarget, registryTick]);
+  }, [resolveTarget, registryTick, resolveArmed]);
 
   // Resolve poll: recover missing / remounted anchors. Live measurement is on rAF.
   React.useEffect(() => {
+    if (!resolveArmed) {
+      return;
+    }
     const allowsRecovery =
       behavior === 'FLAG' || behavior === 'ERROR' || (behavior === 'END' && session.draftMode);
     const pauseAfterReport = missingMode === 'reported' && !allowsRecovery;
@@ -381,7 +531,7 @@ export function TooltipSurface({
       kbShow.remove();
       kbHide.remove();
     };
-  }, [resolveTarget, missingMode, behavior, session.draftMode]);
+  }, [resolveTarget, missingMode, behavior, session.draftMode, resolveArmed]);
 
   // rAF tracking while a host is resolved (and we are not paused after report).
   React.useEffect(() => {
@@ -422,7 +572,7 @@ export function TooltipSurface({
 
     const ms = parseToleranceMs(theme.tooltipMissingToleranceSeconds);
     const timer = setTimeout(() => {
-      if (!mountedRef.current || reportedRef.current) return;
+      if (!mountedRef.current || exitingRef.current || reportedRef.current) return;
       reportedRef.current = true;
       setMissingMode('reported');
       void engine.reportTooltipTargetMissing(currentStep.id);
@@ -458,7 +608,40 @@ export function TooltipSurface({
     [windowDims.width, windowDims.height, keyboardBottomInset],
   );
   const cardMaxWidth = resolveTooltipCardMaxWidth(theme, currentStep.width, windowSize.width);
-  const cardLayoutStyle = resolveTooltipCardLayout(cardMaxWidth, windowSize.width);
+  const viewportMaxHeight = resolveModalCardMaxHeight(windowSize.height, layoutInsets);
+  const minCardHeight = tooltipMinCardHeight({
+    contentPadding: chrome.contentPadding,
+    borderWidth: chrome.borderWidth,
+    cardMaxHeight: viewportMaxHeight,
+  });
+  const minSideCardWidth = tooltipMinSideCardWidth({
+    contentPadding: chrome.contentPadding,
+    borderWidth: chrome.borderWidth,
+    cardMaxWidth,
+  });
+  const sideCardWidth = React.useMemo(() => {
+    if (!target) return null;
+    if (desiredPlacement !== 'LEFT' && desiredPlacement !== 'RIGHT') return null;
+    const placementTarget = expandRect(target, backdropPadding + outsideHighlightSpread);
+    return resolveTooltipSideCardWidth({
+      placement: desiredPlacement,
+      target: placementTarget,
+      windowWidth: windowSize.width,
+      notchSize: chrome.notchSize,
+      cardMaxWidth,
+      minWidth: minSideCardWidth,
+    });
+  }, [
+    target,
+    desiredPlacement,
+    backdropPadding,
+    outsideHighlightSpread,
+    windowSize.width,
+    chrome.notchSize,
+    cardMaxWidth,
+    minSideCardWidth,
+  ]);
+  const defaultCardLayoutStyle = resolveTooltipCardLayout(cardMaxWidth, windowSize.width);
   const buttonsAlign = resolveTooltipButtonsAlign(theme);
   const progressBarProps = {
     enabled: theme.progressBarEnabled,
@@ -480,37 +663,94 @@ export function TooltipSurface({
 
   const layout = React.useMemo(() => {
     if (!target) return null;
+    // A target left over from the previous step belongs to that step's
+    // measurement; placing against it would also reuse that step's card size.
+    if (targetStepIdRef.current !== currentStep.id) return null;
+    const placementTarget = expandRect(target, backdropPadding + outsideHighlightSpread);
+    const viewportInsets = paddingAsEdgeInsets(layoutInsets);
+    const height = Math.min(bubbleSize.height, viewportMaxHeight);
+    const inferSize =
+      sideCardWidth != null ? { width: sideCardWidth, height } : { width: cardMaxWidth, height };
     const nextPlacement = inferTooltipPlacement({
-      target,
-      bubbleSize,
+      target: placementTarget,
+      bubbleSize: inferSize,
       notchSize: chrome.notchSize,
       windowSize,
       currentPlacement: placementRef.current,
       desiredPlacement,
+      viewportInsets,
+      minHeight: minCardHeight,
     });
+    const honorSide =
+      sideCardWidth != null &&
+      nextPlacement === desiredPlacement &&
+      (nextPlacement === 'LEFT' || nextPlacement === 'RIGHT');
+    const fitted = tooltipPlacementFits({
+      target: placementTarget,
+      bubbleSize: inferSize,
+      notchSize: chrome.notchSize,
+      windowSize,
+      placement: nextPlacement,
+      viewportInsets,
+      minHeight: minCardHeight,
+    });
+    let maxCardHeight = viewportMaxHeight;
+    if (nextPlacement === 'ABOVE' || nextPlacement === 'BELOW') {
+      const gap = tooltipVerticalGap({
+        placement: nextPlacement,
+        target: placementTarget,
+        windowHeight: windowSize.height,
+        notchSize: chrome.notchSize,
+        viewportInsets,
+      });
+      const budget = Math.floor(gap);
+      if (Number.isFinite(budget) && budget > 0) {
+        maxCardHeight = Math.max(minCardHeight, Math.min(viewportMaxHeight, budget));
+      }
+    }
+    const positionHeight = Math.min(height, maxCardHeight);
+    const positionSize = honorSide
+      ? { width: sideCardWidth, height: positionHeight }
+      : { width: cardMaxWidth, height: positionHeight };
     return {
       placement: nextPlacement,
+      honorSide,
+      fitted,
+      maxCardHeight,
       ...computeTooltipPosition({
         target,
-        bubbleSize,
+        bubbleSize: positionSize,
         placement: nextPlacement,
         notchSize: chrome.notchSize,
         backdropPadding,
+        outsideHighlightSpread,
         windowSize,
         bubbleBorderRadius: chrome.borderRadius,
         bubbleBorderWidth: chrome.borderWidth,
+        viewportInsets,
       }),
     };
   }, [
     target,
     bubbleSize,
+    sideCardWidth,
+    cardMaxWidth,
+    viewportMaxHeight,
+    minCardHeight,
+    currentStep.id,
     chrome.notchSize,
     chrome.borderRadius,
     chrome.borderWidth,
     windowSize,
     desiredPlacement,
     backdropPadding,
+    outsideHighlightSpread,
+    layoutInsets,
   ]);
+  const cardLayoutStyle =
+    layout?.honorSide && sideCardWidth != null
+      ? { width: sideCardWidth, maxWidth: sideCardWidth }
+      : defaultCardLayoutStyle;
 
   React.useEffect(() => {
     if (layout && layout.placement !== placement) {
@@ -518,12 +758,58 @@ export function TooltipSurface({
     }
   }, [layout, placement]);
 
+  React.useEffect(() => {
+    if (!layout || !target) return;
+    if (desiredPlacement !== 'LEFT' && desiredPlacement !== 'RIGHT') return;
+    // A target left over from the previous step says nothing about this one.
+    if (targetStepIdRef.current !== currentStep.id) return;
+    if (!(session.draftMode || __DEV__)) return;
+    if (warnedSidePlacementStepRef.current === currentStep.id) return;
+    if (layout.placement === desiredPlacement) {
+      // Last-resort return of the authored side: nothing actually fit.
+      if (layout.fitted) return;
+      warnedSidePlacementStepRef.current = currentStep.id;
+      warnTooltipPlacementUnanchored({ requested: desiredPlacement });
+      return;
+    }
+    // Only the structural floor — not keyboard / off-screen flips. A resolved
+    // width means the room was there and something else moved the card.
+    if (sideCardWidth != null) return;
+    warnedSidePlacementStepRef.current = currentStep.id;
+    const placementTarget = expandRect(target, backdropPadding + outsideHighlightSpread);
+    warnTooltipSidePlacementDropped({
+      requested: desiredPlacement,
+      used: layout.placement,
+      availableGap: tooltipSideGap({
+        placement: desiredPlacement,
+        target: placementTarget,
+        windowWidth: windowSize.width,
+        notchSize: chrome.notchSize,
+      }),
+      minWidth: minSideCardWidth,
+    });
+  }, [
+    layout,
+    target,
+    desiredPlacement,
+    sideCardWidth,
+    session.draftMode,
+    currentStep.id,
+    backdropPadding,
+    outsideHighlightSpread,
+    windowSize.width,
+    chrome.notchSize,
+    minSideCardWidth,
+  ]);
+
   // Web parity: "When target element is clicked" → step.actions.
   // Observe taps via TargetPressBridge (pass-through); do not steal the press.
   const hasTarget = target != null;
   const targetActions = currentStep.actions;
   React.useEffect(() => {
-    if (!hasTarget || currentStep.tooltipTargetBlocked || targetActions.length === 0) {
+    // Release the monitor while exiting: it is a singleton, and a tap landing on
+    // the old target would run the departing step's actions.
+    if (isExiting || !hasTarget || currentStep.tooltipTargetBlocked || targetActions.length === 0) {
       targetPressMonitor.clear();
       return;
     }
@@ -531,6 +817,8 @@ export function TooltipSurface({
     targetPressMonitor.set({
       getRect: () => targetRef.current,
       onPress: () => {
+        // Native touches are async relative to commits, so re-check the phase.
+        if (exitingRef.current) return;
         void engine.handleActions(targetActions);
       },
     });
@@ -538,22 +826,40 @@ export function TooltipSurface({
     return () => {
       targetPressMonitor.clear();
     };
-  }, [hasTarget, currentStep.tooltipTargetBlocked, targetActions, engine]);
+  }, [hasTarget, currentStep.tooltipTargetBlocked, targetActions, engine, isExiting]);
+
+  // Painted from mount rather than once the target lands, so a modal → tooltip
+  // swap keeps the dim continuous instead of blinking it off for the frames the
+  // anchor takes to measure. The hole opens when `layout` arrives.
+  // Always mount the cutout: when `backdrop` is off the dim opacity is 0 but
+  // the bands still block host taps (unless interaction blocking is disabled).
+  const interactionBlocker = (
+    <TooltipCutout
+      targetRect={layout?.targetHighlightRect ?? null}
+      backdropColor={theme.backdropColor}
+      backdropOpacity={currentStep.backdrop ? backdropOpacity : 0}
+      targetBlocked={currentStep.tooltipTargetBlocked}
+    />
+  );
 
   if (hideAfterEnd) {
     return null;
   }
 
-  // Still pending the first measure attempt — stay invisible briefly.
+  const showBranding = session.flow.company.flowBranding;
+  const contentPadding = chrome.contentPadding;
+
+  // Still pending the first measure attempt — only the blocker shows.
   if (isMissing && missingMode === 'waiting' && !measureAttempted) {
-    return null;
+    return backdropOnly(interactionBlocker);
   }
 
   if (showWaitingUi) {
     return (
       <View style={styles.root} testID="userflow-tooltip-surface" pointerEvents="box-none">
+        {interactionBlocker}
         <View style={[styles.center, centerPaddingStyle]} pointerEvents="box-none">
-          <View
+          <CardFade
             testID="userflow-tooltip-waiting"
             accessibilityViewIsModal
             pointerEvents="auto"
@@ -564,26 +870,39 @@ export function TooltipSurface({
               {
                 borderRadius: chrome.borderRadius,
                 backgroundColor: chrome.backgroundColor,
+                maxHeight: viewportMaxHeight,
               },
             ]}
           >
             {/* Shadow on the outer shell — fill clips and iOS would clip the shadow. */}
-            <View
-              style={[chrome.fillStyle, { padding: chrome.contentPadding, alignItems: 'center' }]}
-            >
-              <ActivityIndicator color={theme.fontColor} />
-              <Text
+            <View style={[chrome.fillStyle, { maxHeight: viewportMaxHeight, minHeight: 0 }]}>
+              <View
                 style={{
-                  color: theme.fontColor,
-                  fontSize: theme.fontSize,
-                  marginTop: 12,
-                  textAlign: 'center',
+                  paddingHorizontal: contentPadding,
+                  paddingTop: contentPadding,
+                  paddingBottom: showBranding ? MADE_WITH_USERFLOW_GAP : contentPadding,
+                  alignItems: 'center',
                 }}
               >
-                Looking for target…
-              </Text>
+                <ActivityIndicator color={theme.fontColor} />
+                <Text
+                  style={{
+                    color: theme.fontColor,
+                    fontSize: theme.fontSize,
+                    marginTop: 12,
+                    textAlign: 'center',
+                  }}
+                >
+                  Looking for target…
+                </Text>
+              </View>
+              <MadeWithUserflow
+                company={session.flow.company}
+                color={theme.fontColor}
+                contentPadding={contentPadding}
+              />
             </View>
-          </View>
+          </CardFade>
         </View>
       </View>
     );
@@ -591,8 +910,6 @@ export function TooltipSurface({
 
   const progressTop = theme.progressBarEnabled && theme.progressBarPosition === 'TOP';
   const progressBottom = theme.progressBarEnabled && theme.progressBarPosition === 'BOTTOM';
-  const showBranding = session.flow.company.flowBranding;
-  const contentPadding = chrome.contentPadding;
 
   const cardBody = (
     <>
@@ -653,8 +970,9 @@ export function TooltipSurface({
   if (showAsBubbleFallback || showMissingUi) {
     return (
       <View style={styles.root} testID="userflow-tooltip-surface" pointerEvents="box-none">
+        {interactionBlocker}
         <View style={[styles.center, centerPaddingStyle]} pointerEvents="box-none">
-          <View
+          <CardFade
             testID="userflow-tooltip-card"
             accessibilityViewIsModal
             pointerEvents="auto"
@@ -666,37 +984,38 @@ export function TooltipSurface({
               {
                 borderRadius: chrome.borderRadius,
                 backgroundColor: chrome.backgroundColor,
+                maxHeight: viewportMaxHeight,
               },
             ]}
           >
             {/* Shadow lives on the outer layer: the fill clips its content and
                 iOS clips the shadow with it. */}
-            <View style={[chrome.fillStyle, styles.fallbackFill]}>{cardBody}</View>
-          </View>
+            <View style={[chrome.fillStyle, styles.fallbackFill, { maxHeight: viewportMaxHeight }]}>
+              {cardBody}
+            </View>
+          </CardFade>
         </View>
       </View>
     );
   }
 
   if (!layout || !target) {
-    return null;
+    return backdropOnly(interactionBlocker);
   }
 
   return (
     <View style={styles.root} testID="userflow-tooltip-surface" pointerEvents="box-none">
-      {currentStep.backdrop ? (
-        <TooltipCutout
-          targetRect={layout.targetHighlightRect}
-          backdropColor={theme.backdropColor}
-          backdropOpacity={backdropOpacity}
-          targetBlocked={currentStep.tooltipTargetBlocked}
-        />
+      {interactionBlocker}
+      {highlight ? (
+        <TooltipHighlight targetRect={layout.targetHighlightRect} chrome={highlight} />
       ) : null}
 
       <TooltipBubble
         chrome={chrome}
         notchPosition={layout.notchPosition}
         onLayout={onCardLayout}
+        maxHeight={layout.maxCardHeight}
+        showNotch={layout.showNotch}
         style={{
           position: 'absolute',
           left: layout.cardPosition.x,
@@ -720,18 +1039,19 @@ const styles = StyleSheet.create({
     alignItems: 'center',
   },
   fallbackCard: {
-    maxHeight: '80%',
     flexShrink: 1,
   },
   fallbackFill: {
     flexShrink: 1,
+    minHeight: 0,
   },
   waitingCard: {
     width: '100%',
   },
   scroll: {
-    flexGrow: 0,
+    flexGrow: 1,
     flexShrink: 1,
+    minHeight: 0,
   },
   scrollContent: {
     flexGrow: 1,