@userflow-tech/react-native 0.1.0 → 0.2.0

package/lib/commonjs/surfaces/TooltipSurface.js

@@ -3,40 +3,55 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
+exports.FIRST_RESOLVE_DELAY_MS = void 0;
 exports.TooltipSurface = TooltipSurface;
 var React = _interopRequireWildcard(require("react"));
 var _reactNative = require("react-native");
 var _AnchorRegistry = require("../anchors/AnchorRegistry.js");
+var _AutoAnchorRegistry = require("../anchors/AutoAnchorRegistry.js");
 var _animationFrame = require("../anchors/animationFrame.js");
 var _FiberScanRoot = require("../anchors/fiber/FiberScanRoot.js");
 var _resolveAnchorHost = require("../anchors/resolveAnchorHost.js");
+var _resolveAutoAnchorHost = require("../anchors/resolveAutoAnchorHost.js");
 var _resolveManualAnchorId = require("../anchors/resolveManualAnchorId.js");
 var _scrollAnchorIntoView = require("../anchors/scrollAnchorIntoView.js");
 var _scrollConfig = require("../anchors/scrollConfig.js");
 var _targetPressMonitor = require("../anchors/targetPressMonitor.js");
 var _RichContentRenderer = require("../content/RichContentRenderer.js");
+var _CardFade = require("./CardFade.js");
 var _CloseButton = require("./CloseButton.js");
-var _resolveCloseButtonColor = require("./resolveCloseButtonColor.js");
 var _MadeWithUserflow = require("./MadeWithUserflow.js");
 var _ProgressBar = require("./ProgressBar.js");
 var _absoluteFill = require("./absoluteFill.js");
+var _cardTransition = require("./cardTransition.js");
 var _parseBackdropOpacity = require("./parseBackdropOpacity.js");
 var _progress = require("./progress.js");
-var _safeArea = require("./safeArea.js");
+var _resolveCloseButtonColor = require("./resolveCloseButtonColor.js");
+var _resolveHighlightChrome = require("./resolveHighlightChrome.js");
+var _resolveModalLayout = require("./resolveModalLayout.js");
+var _resolveTooltipLayout = require("./resolveTooltipLayout.js");
+var _surfaceLayoutInsets = require("./surfaceLayoutInsets.js");
 var _themeChrome = require("./themeChrome.js");
 var _TooltipBubble = require("./tooltip/TooltipBubble.js");
 var _TooltipCutout = require("./tooltip/TooltipCutout.js");
+var _TooltipHighlight = require("./tooltip/TooltipHighlight.js");
 var _computeTooltipPosition = require("./tooltip/computeTooltipPosition.js");
 var _inferTooltipPlacement = require("./tooltip/inferTooltipPlacement.js");
 var _parseBackdropPadding = require("./tooltip/parseBackdropPadding.js");
+var _placementDiagnostics = require("./tooltip/placementDiagnostics.js");
 var _rect = require("./tooltip/rect.js");
-var _resolveTooltipLayout = require("./resolveTooltipLayout.js");
+var _resolveSideCardWidth = require("./tooltip/resolveSideCardWidth.js");
 var _jsxRuntime = require("react/jsx-runtime");
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 /** 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.
+ */
+const FIRST_RESOLVE_DELAY_MS = exports.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 —
@@ -60,6 +75,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__*/(0, _jsxRuntime.jsx)(_reactNative.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.
@@ -69,7 +97,8 @@ function TooltipSurface({
   session,
   currentStep,
   theme,
-  lookupAttribute
+  lookupAttribute,
+  resetNonce = 0
 }) {
   const version = session.version;
   const chrome = (0, _themeChrome.resolveBubbleChrome)(theme, 'tooltip');
@@ -77,13 +106,32 @@ function TooltipSurface({
   const showClose = !version.closeDisabled;
   const backdropOpacity = (0, _parseBackdropOpacity.parseBackdropOpacity)(theme.backdropOpacity);
   const backdropPadding = (0, _parseBackdropPadding.parseBackdropPadding)(currentStep.backdropPadding);
-  const anchorId = (0, _resolveManualAnchorId.resolveManualAnchorId)(currentStep.selector?.css);
+  const selector = currentStep.selector;
+  const isAuto = selector?.type === 'AUTO';
+  const autoData = selector?.autoData ?? null;
+  const anchorId = isAuto ? null : (0, _resolveManualAnchorId.resolveManualAnchorId)(selector?.css);
+  const targetKey = isAuto ? `auto:${autoData ?? ''}` : anchorId ?? '';
+  const highlight = currentStep.backdrop ? (0, _resolveHighlightChrome.resolveHighlightChrome)(theme, backdropPadding) : null;
+  const outsideHighlightSpread = highlight ? (0, _resolveHighlightChrome.outsideHighlightOutset)(highlight) : 0;
   const desiredPlacement = normalizePlacement(currentStep.tooltipPlacement);
   const behavior = missingBehavior(theme);
-  const insets = (0, _safeArea.useUserflowSafeAreaInsets)();
-  const centerPaddingStyle = (0, _resolveTooltipLayout.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 = (0, _cardTransition.useCardTransitionPhase)() === 'exiting';
+  const exitingRef = React.useRef(isExiting);
+  exitingRef.current = isExiting;
+  const layoutInsets = (0, _surfaceLayoutInsets.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
@@ -93,9 +141,21 @@ 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. */
@@ -108,14 +168,33 @@ 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);
@@ -134,9 +213,11 @@ function TooltipSurface({
   React.useEffect(() => {
     const bump = () => setRegistryTick(n => n + 1);
     const unsubRegistry = _AnchorRegistry.anchorRegistry.subscribe(bump);
+    const unsubAuto = _AutoAnchorRegistry.autoAnchorRegistry.subscribe(bump);
     const unsubScan = _FiberScanRoot.fiberScanRoot.subscribe(bump);
     return () => {
       unsubRegistry();
+      unsubAuto();
       unsubScan();
     };
   }, []);
@@ -145,16 +226,49 @@ 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));
+    (0, _resolveAnchorHost.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 ((0, _rect.rectsEqual)(targetRef.current, next)) return;
     if (next == null) {
       // The anchor went away (unmount / navigation), so whatever scroll position
@@ -170,20 +284,40 @@ 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 = _reactNative.Dimensions.get('window');
     const scrollPadding = (0, _scrollConfig.getScrollPadding)();
+    const layoutPad = (0, _surfaceLayoutInsets.paddingAsEdgeInsets)(insetsRef.current);
     return (0, _rect.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 ((0, _rect.isRectFullyVisible)(rect, effectiveViewport())) {
       scrollSettledRef.current = true;
@@ -216,40 +350,32 @@ 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 = (0, _resolveAnchorHost.resolveAnchorHost)(anchorId);
-    if (resolution.status !== 'found') {
-      hostFiberRef.current = null;
-      hostMeasureRef.current = null;
-      hostScrollIntoViewRef.current = undefined;
-      markMeasureAttempted();
-      applyTarget(null);
+    const resolution = isAuto ? (0, _resolveAutoAnchorHost.resolveAutoAnchorHost)(autoData) : anchorId ? (0, _resolveAnchorHost.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) {
-        (0, _resolveAnchorHost.invalidateFiberAnchor)(anchorId);
-        hostFiberRef.current = null;
-        hostMeasureRef.current = null;
-        markMeasureAttempted();
-        applyTarget(null);
+        const cacheId = fiberCacheIdRef.current;
+        if (cacheId) (0, _resolveAnchorHost.invalidateFiberAnchor)(cacheId);
+        dropHost();
         return;
       }
       const rect = {
@@ -261,7 +387,7 @@ 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
@@ -272,16 +398,19 @@ 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) (0, _resolveAnchorHost.invalidateFiberAnchor)(anchorId);
-        hostFiberRef.current = null;
-        hostMeasureRef.current = null;
-        markMeasureAttempted();
-        applyTarget(null);
+        const cacheId = fiberCacheIdRef.current;
+        if (cacheId) (0, _resolveAnchorHost.invalidateFiberAnchor)(cacheId);
+        dropHost();
         return;
       }
       const rect = {
@@ -293,13 +422,17 @@ 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) {
@@ -325,7 +458,7 @@ 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(() => {
@@ -359,7 +492,7 @@ 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);
@@ -386,7 +519,31 @@ function TooltipSurface({
     height: Math.max(0, windowDims.height - keyboardBottomInset)
   }), [windowDims.width, windowDims.height, keyboardBottomInset]);
   const cardMaxWidth = (0, _resolveTooltipLayout.resolveTooltipCardMaxWidth)(theme, currentStep.width, windowSize.width);
-  const cardLayoutStyle = (0, _resolveTooltipLayout.resolveTooltipCardLayout)(cardMaxWidth, windowSize.width);
+  const viewportMaxHeight = (0, _resolveModalLayout.resolveModalCardMaxHeight)(windowSize.height, layoutInsets);
+  const minCardHeight = (0, _resolveSideCardWidth.tooltipMinCardHeight)({
+    contentPadding: chrome.contentPadding,
+    borderWidth: chrome.borderWidth,
+    cardMaxHeight: viewportMaxHeight
+  });
+  const minSideCardWidth = (0, _resolveSideCardWidth.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 = (0, _rect.expandRect)(target, backdropPadding + outsideHighlightSpread);
+    return (0, _resolveSideCardWidth.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 = (0, _resolveTooltipLayout.resolveTooltipCardLayout)(cardMaxWidth, windowSize.width);
   const buttonsAlign = (0, _resolveTooltipLayout.resolveTooltipButtonsAlign)(theme);
   const progressBarProps = {
     enabled: theme.progressBarEnabled,
@@ -403,102 +560,220 @@ 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 = (0, _rect.expandRect)(target, backdropPadding + outsideHighlightSpread);
+    const viewportInsets = (0, _surfaceLayoutInsets.paddingAsEdgeInsets)(layoutInsets);
+    const height = Math.min(bubbleSize.height, viewportMaxHeight);
+    const inferSize = sideCardWidth != null ? {
+      width: sideCardWidth,
+      height
+    } : {
+      width: cardMaxWidth,
+      height
+    };
     const nextPlacement = (0, _inferTooltipPlacement.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 = (0, _inferTooltipPlacement.tooltipPlacementFits)({
+      target: placementTarget,
+      bubbleSize: inferSize,
+      notchSize: chrome.notchSize,
+      windowSize,
+      placement: nextPlacement,
+      viewportInsets,
+      minHeight: minCardHeight
     });
+    let maxCardHeight = viewportMaxHeight;
+    if (nextPlacement === 'ABOVE' || nextPlacement === 'BELOW') {
+      const gap = (0, _resolveSideCardWidth.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,
       ...(0, _computeTooltipPosition.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;
+      (0, _placementDiagnostics.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 = (0, _rect.expandRect)(target, backdropPadding + outsideHighlightSpread);
+    (0, _placementDiagnostics.warnTooltipSidePlacementDropped)({
+      requested: desiredPlacement,
+      used: layout.placement,
+      availableGap: (0, _resolveSideCardWidth.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.targetPressMonitor.clear();
       return;
     }
     _targetPressMonitor.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.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__*/(0, _jsxRuntime.jsx)(_TooltipCutout.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__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+    return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
       style: styles.root,
       testID: "userflow-tooltip-surface",
       pointerEvents: "box-none",
-      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+      children: [interactionBlocker, /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
         style: [styles.center, centerPaddingStyle],
         pointerEvents: "box-none",
-        children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+        children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_CardFade.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__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
             style: [chrome.fillStyle, {
-              padding: chrome.contentPadding,
-              alignItems: 'center'
+              maxHeight: viewportMaxHeight,
+              minHeight: 0
             }],
-            children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.ActivityIndicator, {
-              color: theme.fontColor
-            }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+            children: [/*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
               style: {
-                color: theme.fontColor,
-                fontSize: theme.fontSize,
-                marginTop: 12,
-                textAlign: 'center'
+                paddingHorizontal: contentPadding,
+                paddingTop: contentPadding,
+                paddingBottom: showBranding ? _MadeWithUserflow.MADE_WITH_USERFLOW_GAP : contentPadding,
+                alignItems: 'center'
               },
-              children: "Looking for target\u2026"
+              children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.ActivityIndicator, {
+                color: theme.fontColor
+              }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+                style: {
+                  color: theme.fontColor,
+                  fontSize: theme.fontSize,
+                  marginTop: 12,
+                  textAlign: 'center'
+                },
+                children: "Looking for target\u2026"
+              })]
+            }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_MadeWithUserflow.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__*/(0, _jsxRuntime.jsxs)(_jsxRuntime.Fragment, {
     children: [showClose ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_CloseButton.CloseButton, {
       onPress: endAsUserClosed,
@@ -554,46 +829,49 @@ function TooltipSurface({
     })]
   });
   if (showAsBubbleFallback || showMissingUi) {
-    return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+    return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
       style: styles.root,
       testID: "userflow-tooltip-surface",
       pointerEvents: "box-none",
-      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+      children: [interactionBlocker, /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
         style: [styles.center, centerPaddingStyle],
         pointerEvents: "box-none",
-        children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+        children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_CardFade.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__*/(0, _jsxRuntime.jsx)(_reactNative.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__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
     style: styles.root,
     testID: "userflow-tooltip-surface",
     pointerEvents: "box-none",
-    children: [currentStep.backdrop ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_TooltipCutout.TooltipCutout, {
+    children: [interactionBlocker, highlight ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_TooltipHighlight.TooltipHighlight, {
       targetRect: layout.targetHighlightRect,
-      backdropColor: theme.backdropColor,
-      backdropOpacity: backdropOpacity,
-      targetBlocked: currentStep.tooltipTargetBlocked
+      chrome: highlight
     }) : null, /*#__PURE__*/(0, _jsxRuntime.jsx)(_TooltipBubble.TooltipBubble, {
       chrome: chrome,
       notchPosition: layout.notchPosition,
       onLayout: onCardLayout,
+      maxHeight: layout.maxCardHeight,
+      showNotch: layout.showNotch,
       style: {
         position: 'absolute',
         left: layout.cardPosition.x,
@@ -614,18 +892,19 @@ const styles = _reactNative.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