@userflow-tech/react-native 0.1.1 → 0.2.0

package/lib/module/surfaces/TooltipSurface.js

@@ -3,35 +3,49 @@
 import * as React from 'react';
 import { ActivityIndicator, Dimensions, Keyboard, ScrollView, StyleSheet, Text, View } from 'react-native';
 import { anchorRegistry } from "../anchors/AnchorRegistry.js";
+import { autoAnchorRegistry } from "../anchors/AutoAnchorRegistry.js";
 import { addAnimationFrameCallback, removeAnimationFrameCallback } from "../anchors/animationFrame.js";
 import { fiberScanRoot } from "../anchors/fiber/FiberScanRoot.js";
-import { invalidateFiberAnchor, resolveAnchorHost } from "../anchors/resolveAnchorHost.js";
+import { clearFiberAnchorCache, invalidateFiberAnchor, resolveAnchorHost } from "../anchors/resolveAnchorHost.js";
+import { resolveAutoAnchorHost } from "../anchors/resolveAutoAnchorHost.js";
 import { resolveManualAnchorId } from "../anchors/resolveManualAnchorId.js";
 import { scrollAnchorIntoView } from "../anchors/scrollAnchorIntoView.js";
 import { getScrollPadding } from "../anchors/scrollConfig.js";
 import { targetPressMonitor } from "../anchors/targetPressMonitor.js";
 import { RichContentRenderer } from "../content/RichContentRenderer.js";
+import { CardFade } from "./CardFade.js";
 import { CloseButton } from "./CloseButton.js";
-import { resolveCloseButtonColor } from "./resolveCloseButtonColor.js";
 import { MADE_WITH_USERFLOW_GAP, MadeWithUserflow } from "./MadeWithUserflow.js";
 import { ProgressBar } from "./ProgressBar.js";
 import { ABSOLUTE_FILL } from "./absoluteFill.js";
+import { useCardTransitionPhase } from "./cardTransition.js";
 import { parseBackdropOpacity } from "./parseBackdropOpacity.js";
 import { resolveStepProgress } from "./progress.js";
-import { useUserflowSafeAreaInsets } from "./safeArea.js";
+import { resolveCloseButtonColor } from "./resolveCloseButtonColor.js";
+import { outsideHighlightOutset, resolveHighlightChrome } from "./resolveHighlightChrome.js";
+import { resolveModalCardMaxHeight } from "./resolveModalLayout.js";
+import { resolveTooltipButtonsAlign, resolveTooltipCardLayout, resolveTooltipCardMaxWidth } from "./resolveTooltipLayout.js";
+import { paddingAsEdgeInsets, useSurfaceLayoutInsets } from "./surfaceLayoutInsets.js";
 import { resolveBubbleChrome } from "./themeChrome.js";
 import { TooltipBubble } from "./tooltip/TooltipBubble.js";
 import { TooltipCutout } from "./tooltip/TooltipCutout.js";
+import { TooltipHighlight } from "./tooltip/TooltipHighlight.js";
 import { computeTooltipPosition } from "./tooltip/computeTooltipPosition.js";
-import { inferTooltipPlacement } from "./tooltip/inferTooltipPlacement.js";
+import { inferTooltipPlacement, tooltipPlacementFits } from "./tooltip/inferTooltipPlacement.js";
 import { parseBackdropPadding } from "./tooltip/parseBackdropPadding.js";
-import { buildEffectiveViewport, isRectFullyVisible, rectsEqual } from "./tooltip/rect.js";
-import { resolveTooltipButtonsAlign, resolveTooltipCardLayout, resolveTooltipCardMaxWidth, resolveTooltipCenterPadding } from "./resolveTooltipLayout.js";
+import { warnTooltipPlacementUnanchored, warnTooltipSidePlacementDropped } from "./tooltip/placementDiagnostics.js";
+import { buildEffectiveViewport, expandRect, isRectFullyVisible, rectsEqual } from "./tooltip/rect.js";
+import { resolveTooltipSideCardWidth, tooltipMinCardHeight, tooltipMinSideCardWidth, tooltipSideGap, tooltipVerticalGap } from "./tooltip/resolveSideCardWidth.js";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 /** Interval for re-resolving a missing / remounted anchor (not for live measure). */
 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 —
@@ -55,6 +69,19 @@ function missingBehavior(theme) {
   return String(theme.tooltipMissingBehavior ?? 'FLAG').toUpperCase();
 }
 
+/** Dim with no card yet, for the frames between mount and the first measure. */
+function backdropOnly(blocker) {
+  if (blocker == null) {
+    return null;
+  }
+  return /*#__PURE__*/_jsx(View, {
+    style: styles.root,
+    testID: "userflow-tooltip-surface",
+    pointerEvents: "box-none",
+    children: blocker
+  });
+}
+
 /**
  * Anchored tooltip chrome: measure manual / fiber anchor, place with web flip/shift,
  * optional cutout backdrop, missing-target report + theme fallbacks.
@@ -64,7 +91,8 @@ export function TooltipSurface({
   session,
   currentStep,
   theme,
-  lookupAttribute
+  lookupAttribute,
+  resetNonce = 0
 }) {
   const version = session.version;
   const chrome = resolveBubbleChrome(theme, 'tooltip');
@@ -72,13 +100,32 @@ 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 === '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(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
@@ -88,9 +135,21 @@ 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(null);
   /** Bounded scroll-into-view attempts for the current step. */
@@ -103,14 +162,33 @@ 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(null);
   const hostMeasureRef = React.useRef(null);
   const hostScrollIntoViewRef = React.useRef(undefined);
+  /** Fiber-cache key for the current host; AUTO exact-id path sets this even when `anchorId` is null. */
+  const fiberCacheIdRef = React.useRef(null);
+  /** Step id we already warned about for a dropped LEFT/RIGHT placement. */
+  const warnedSidePlacementStepRef = React.useRef(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(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);
@@ -129,9 +207,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();
     };
   }, []);
@@ -140,16 +220,49 @@ 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 => {
     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
@@ -165,20 +278,40 @@ export function TooltipSurface({
     if (!mountedRef.current) return;
     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 => {
+    // 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;
@@ -211,40 +344,32 @@ 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;
       }
       const rect = {
@@ -256,7 +381,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
@@ -267,16 +392,19 @@ export function TooltipSurface({
     if (measureInFlightRef.current) return;
     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;
       }
       const rect = {
@@ -288,13 +416,17 @@ 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;
     if (pauseAfterReport) {
@@ -320,7 +452,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(() => {
@@ -354,7 +486,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);
@@ -381,7 +513,31 @@ export function TooltipSurface({
     height: Math.max(0, windowDims.height - keyboardBottomInset)
   }), [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,
@@ -398,102 +554,220 @@ export function TooltipSurface({
   const showWaitingUi = isMissing && missingMode === 'waiting' && measureAttempted;
   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
+      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
+        bubbleBorderWidth: chrome.borderWidth,
+        viewportInsets
       })
     };
-  }, [target, bubbleSize, chrome.notchSize, chrome.borderRadius, chrome.borderWidth, windowSize, desiredPlacement, backdropPadding]);
+  }, [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) {
       setPlacement(layout.placement);
     }
   }, [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;
     }
     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);
       }
     });
     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 = /*#__PURE__*/_jsx(TooltipCutout, {
+    targetRect: layout?.targetHighlightRect ?? null,
+    backdropColor: theme.backdropColor,
+    backdropOpacity: currentStep.backdrop ? backdropOpacity : 0,
+    targetBlocked: currentStep.tooltipTargetBlocked
+  });
   if (hideAfterEnd) {
     return null;
   }
+  const showBranding = session.flow.company.flowBranding;
+  const contentPadding = chrome.contentPadding;
 
-  // Still pending the first measure attempt — stay invisible briefly.
+  // Still pending the first measure attempt — only the blocker shows.
   if (isMissing && missingMode === 'waiting' && !measureAttempted) {
-    return null;
+    return backdropOnly(interactionBlocker);
   }
   if (showWaitingUi) {
-    return /*#__PURE__*/_jsx(View, {
+    return /*#__PURE__*/_jsxs(View, {
       style: styles.root,
       testID: "userflow-tooltip-surface",
       pointerEvents: "box-none",
-      children: /*#__PURE__*/_jsx(View, {
+      children: [interactionBlocker, /*#__PURE__*/_jsx(View, {
         style: [styles.center, centerPaddingStyle],
         pointerEvents: "box-none",
-        children: /*#__PURE__*/_jsx(View, {
+        children: /*#__PURE__*/_jsx(CardFade, {
           testID: "userflow-tooltip-waiting",
           accessibilityViewIsModal: true,
           pointerEvents: "auto",
           style: [chrome.shadowStyle, styles.waitingCard, cardLayoutStyle, {
             borderRadius: chrome.borderRadius,
-            backgroundColor: chrome.backgroundColor
+            backgroundColor: chrome.backgroundColor,
+            maxHeight: viewportMaxHeight
           }],
           children: /*#__PURE__*/_jsxs(View, {
             style: [chrome.fillStyle, {
-              padding: chrome.contentPadding,
-              alignItems: 'center'
+              maxHeight: viewportMaxHeight,
+              minHeight: 0
             }],
-            children: [/*#__PURE__*/_jsx(ActivityIndicator, {
-              color: theme.fontColor
-            }), /*#__PURE__*/_jsx(Text, {
+            children: [/*#__PURE__*/_jsxs(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'
               },
-              children: "Looking for target\u2026"
+              children: [/*#__PURE__*/_jsx(ActivityIndicator, {
+                color: theme.fontColor
+              }), /*#__PURE__*/_jsx(Text, {
+                style: {
+                  color: theme.fontColor,
+                  fontSize: theme.fontSize,
+                  marginTop: 12,
+                  textAlign: 'center'
+                },
+                children: "Looking for target\u2026"
+              })]
+            }), /*#__PURE__*/_jsx(MadeWithUserflow, {
+              company: session.flow.company,
+              color: theme.fontColor,
+              contentPadding: contentPadding
             })]
           })
         })
-      })
+      })]
     });
   }
   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 = /*#__PURE__*/_jsxs(_Fragment, {
     children: [showClose ? /*#__PURE__*/_jsx(CloseButton, {
       onPress: endAsUserClosed,
@@ -549,46 +823,49 @@ export function TooltipSurface({
     })]
   });
   if (showAsBubbleFallback || showMissingUi) {
-    return /*#__PURE__*/_jsx(View, {
+    return /*#__PURE__*/_jsxs(View, {
       style: styles.root,
       testID: "userflow-tooltip-surface",
       pointerEvents: "box-none",
-      children: /*#__PURE__*/_jsx(View, {
+      children: [interactionBlocker, /*#__PURE__*/_jsx(View, {
         style: [styles.center, centerPaddingStyle],
         pointerEvents: "box-none",
-        children: /*#__PURE__*/_jsx(View, {
+        children: /*#__PURE__*/_jsx(CardFade, {
           testID: "userflow-tooltip-card",
           accessibilityViewIsModal: true,
           pointerEvents: "auto",
           onLayout: onCardLayout,
           style: [chrome.shadowStyle, styles.fallbackCard, cardLayoutStyle, {
             borderRadius: chrome.borderRadius,
-            backgroundColor: chrome.backgroundColor
+            backgroundColor: chrome.backgroundColor,
+            maxHeight: viewportMaxHeight
           }],
           children: /*#__PURE__*/_jsx(View, {
-            style: [chrome.fillStyle, styles.fallbackFill],
+            style: [chrome.fillStyle, styles.fallbackFill, {
+              maxHeight: viewportMaxHeight
+            }],
             children: cardBody
           })
         })
-      })
+      })]
     });
   }
   if (!layout || !target) {
-    return null;
+    return backdropOnly(interactionBlocker);
   }
   return /*#__PURE__*/_jsxs(View, {
     style: styles.root,
     testID: "userflow-tooltip-surface",
     pointerEvents: "box-none",
-    children: [currentStep.backdrop ? /*#__PURE__*/_jsx(TooltipCutout, {
+    children: [interactionBlocker, highlight ? /*#__PURE__*/_jsx(TooltipHighlight, {
       targetRect: layout.targetHighlightRect,
-      backdropColor: theme.backdropColor,
-      backdropOpacity: backdropOpacity,
-      targetBlocked: currentStep.tooltipTargetBlocked
+      chrome: highlight
     }) : null, /*#__PURE__*/_jsx(TooltipBubble, {
       chrome: chrome,
       notchPosition: layout.notchPosition,
       onLayout: onCardLayout,
+      maxHeight: layout.maxCardHeight,
+      showNotch: layout.showNotch,
       style: {
         position: 'absolute',
         left: layout.cardPosition.x,
@@ -609,18 +886,19 @@ const styles = StyleSheet.create({
     alignItems: 'center'
   },
   fallbackCard: {
-    maxHeight: '80%',
     flexShrink: 1
   },
   fallbackFill: {
-    flexShrink: 1
+    flexShrink: 1,
+    minHeight: 0
   },
   waitingCard: {
     width: '100%'
   },
   scroll: {
-    flexGrow: 0,
-    flexShrink: 1
+    flexGrow: 1,
+    flexShrink: 1,
+    minHeight: 0
   },
   scrollContent: {
     flexGrow: 1