@userflow-tech/react-native 0.4.4 → 0.5.0

package/src/surfaces/bannerWebView/BannerWebViewBar.tsx

@@ -23,14 +23,18 @@ import { getEvalJsWebView, type EvalJsWebViewHandle } from '../../evalJs/getWebV
 import { injectEvalPendingIntoWebView } from '../../evalJs/injectEvalPending';
 import type { EvalJsContext } from '../../evalJs/types';
 import { useEvalJsWebViewInjection } from '../../evalJs/useEvalJsWebViewInjection';
+import { usePushBannerHostInsetRegistration } from '../../runtime/pushBannerLayoutContext';
+import { setBannerFlowSpacerHeight } from '../../runtime/bannerFlowSpacer';
+import { warnBannerOnce } from '../../runtime/bannerPlacement';
 import { getUserflowCore } from '../../runtime/userflowCore';
 import { getCurrentScreenLocation, subscribeScreenLocation } from '../../screenTracker';
 import {
   bannerFrameStyle,
-  bannerInnerStyle,
+  bannerPushLayoutChrome,
   resolveBannerBarBorderRadius,
 } from '../bannerBarLayout';
 import { bannerOverlayShadowStyle } from '../bannerBarTokens';
+import { resolveBannerBackgroundColor } from '../resolveBannerTheme';
 import { useUserflowSafeAreaInsets } from '../safeArea';
 
 import { collectBannerAutoRunEvalCodes } from './bannerAutoRunEvalJs';
@@ -39,6 +43,8 @@ import { buildCustomBannerBodyHtml } from './buildCustomBannerHtml';
 
 export interface BannerWebViewBarProps {
   session: BannerSessionFragment;
+  pushLayoutEdge?: 'top' | 'bottom' | null;
+  overlaySafeEdge?: 'top' | 'bottom' | null;
   onActions: (actions: FlowActionFragment[]) => void | Promise<void>;
   onDismiss: (endReason: EndFlowReasonInput) => void;
 }
@@ -68,14 +74,27 @@ function useEvalJsScreen(): { name?: string; path?: string } {
 
 export function BannerWebViewBar({
   session,
+  pushLayoutEdge = null,
+  overlaySafeEdge = null,
   onActions,
   onDismiss,
 }: BannerWebViewBarProps): React.ReactElement | null {
   const banner = session.version.banner;
+  const overlay = banner?.overlay !== false;
+  const hostInsetEdge = banner && !overlay && pushLayoutEdge ? pushLayoutEdge : null;
+  const pushLayoutRegistrationEdge =
+    hostInsetEdge ?? (!overlay && overlaySafeEdge ? overlaySafeEdge : null);
+  const safeAreaEdge = hostInsetEdge ?? overlaySafeEdge ?? null;
+  const onPushChromeLayout = usePushBannerHostInsetRegistration(
+    pushLayoutRegistrationEdge,
+    session.id,
+    pushLayoutRegistrationEdge != null,
+  );
   const WebView = getEvalJsWebView();
   const webRef = React.useRef<EvalJsWebViewHandle>(null);
   const [pageReady, setPageReady] = React.useState(false);
   const [contentHeight, setContentHeight] = React.useState(56);
+  const [webLayoutHeight, setWebLayoutHeight] = React.useState<number | null>(null);
   const colorScheme = useColorScheme();
   const viewport = useWindowDimensions();
   const insets = useUserflowSafeAreaInsets();
@@ -104,18 +123,18 @@ export function BannerWebViewBar({
   const serverEndpoint = getUserflowCore().getServerEndpoint() ?? DEFAULT_SERVER_ENDPOINT;
 
   const skipAutoRunEval = shouldSkipBannerAutoRunEval(session.id);
-  const initialContext = React.useRef(context);
   const html = React.useMemo(() => {
     const body = buildCustomBannerBodyHtml(session, lookupAttribute, serverEndpoint, {
       skipAutoRunEval,
     });
-    return buildBootstrapHtml(initialContext.current, body);
-  }, [lookupAttribute, serverEndpoint, session, skipAutoRunEval]);
+    return buildBootstrapHtml(context, body);
+  }, [context, lookupAttribute, serverEndpoint, session, skipAutoRunEval]);
 
-  const opacity = React.useRef(new Animated.Value(banner?.animate ? 0 : 1)).current;
+  const fadeIn = banner?.animate === true && hostInsetEdge == null;
+  const opacity = React.useRef(new Animated.Value(fadeIn ? 0 : 1)).current;
 
   React.useEffect(() => {
-    if (!banner?.animate) {
+    if (!fadeIn) {
       opacity.setValue(1);
       return;
     }
@@ -129,13 +148,39 @@ export function BannerWebViewBar({
     return () => {
       animation.stop();
     };
-  }, [banner?.animate, opacity, session.id]);
+  }, [fadeIn, opacity, session.id]);
 
   React.useEffect(() => {
     setPageReady(false);
     setContentHeight(56);
+    setWebLayoutHeight(null);
   }, [session.id, html]);
 
+  const reserveFlowSpace = !overlay && overlaySafeEdge != null;
+  React.useEffect(() => {
+    if (!reserveFlowSpace || !overlaySafeEdge) {
+      return;
+    }
+    return () => {
+      setBannerFlowSpacerHeight(overlaySafeEdge, 0);
+    };
+  }, [overlaySafeEdge, reserveFlowSpace, session.id]);
+
+  React.useEffect(() => {
+    if (pushLayoutRegistrationEdge == null) {
+      return;
+    }
+    const timer = setTimeout(() => {
+      if (webLayoutHeight == null) {
+        warnBannerOnce(
+          `push-webview-layout:${session.id}`,
+          'Userflow: push-layout WebView banner did not report a layout height; check custom CSS / WebView logs',
+        );
+      }
+    }, 4000);
+    return () => clearTimeout(timer);
+  }, [pushLayoutRegistrationEdge, session.id, webLayoutHeight]);
+
   React.useEffect(() => {
     if (!pageReady || skipAutoRunEval || !banner) {
       return;
@@ -177,17 +222,23 @@ export function BannerWebViewBar({
             const maxHeight = Math.floor(viewport.height * 0.92);
             const next = Math.min(Math.ceil(height), maxHeight);
             setContentHeight((prev) => (Math.abs(next - prev) <= 1 ? prev : next));
+            setWebLayoutHeight(next);
           }
           return;
         }
         if (record.__userflow === 1 && record.type === 'bannerButton') {
           const buttonId = record.buttonId;
           if (typeof buttonId === 'string' && banner) {
-            const button = banner.buttons.find((entry) => entry.id === buttonId);
+            const button =
+              banner.buttons.find((entry) => entry.id === buttonId) ??
+              banner.buttons.find((entry) => entry.cvid === buttonId);
             if (button) {
               void Promise.resolve(onActions(button.actions)).then(() => {
                 injectEvalPendingIntoWebView(webRef.current);
               });
+            } else if (__DEV__) {
+              // eslint-disable-next-line no-console -- intentional development diagnostic
+              console.warn('[Userflow] banner button not found for id', buttonId);
             }
           }
           return;
@@ -241,72 +292,113 @@ export function BannerWebViewBar({
           return;
       }
     },
-    [banner, onActions, onDismiss, viewport.height],
+    [
+      banner,
+      insets.bottom,
+      insets.top,
+      onActions,
+      onDismiss,
+      overlaySafeEdge,
+      reserveFlowSpace,
+      viewport.height,
+    ],
   );
 
   if (!banner || !WebView) {
     return null;
   }
 
-  const overlay = banner.overlay !== false;
   const frameStyle = bannerFrameStyle(banner);
-  const innerStyle = bannerInnerStyle(banner);
   const overlayEdge = banner.embedMode === BannerEmbedMode.BODY_LAST ? 'bottom' : 'top';
   const barRadius = resolveBannerBarBorderRadius(banner);
+  const backgroundColor = resolveBannerBackgroundColor(session.version.theme);
   const webStyle: ViewStyle = {
     width: '100%',
     height: contentHeight,
-    backgroundColor: 'transparent',
+    backgroundColor,
   };
   const debugging = typeof __DEV__ !== 'undefined' && __DEV__ ? true : undefined;
+  const insetChrome = safeAreaEdge
+    ? bannerPushLayoutChrome(safeAreaEdge, insets, backgroundColor)
+    : null;
+  const insetChromeOutsideFade = insetChrome != null && fadeIn;
+
+  const webViewBar = (
+    <View
+      testID="userflow-banner-webview"
+      pointerEvents="auto"
+      style={[{ borderRadius: barRadius ?? 0, overflow: 'hidden' as const }]}
+    >
+      <WebView
+        key={session.id}
+        ref={webRef}
+        source={{ html, baseUrl: EVAL_JS_BASE_URL }}
+        style={webStyle}
+        javaScriptEnabled
+        domStorageEnabled
+        scrollEnabled={false}
+        bounces={false}
+        showsHorizontalScrollIndicator={false}
+        showsVerticalScrollIndicator={false}
+        originWhitelist={['*']}
+        setSupportMultipleWindows={false}
+        androidLayerType="hardware"
+        {...(debugging !== undefined ? { webviewDebuggingEnabled: debugging } : {})}
+        onMessage={onMessage}
+        onLoadEnd={() => {
+          setPageReady(true);
+          webRef.current?.injectJavaScript(
+            'window.__userflowBannerLayout&&window.__userflowBannerLayout();true;',
+          );
+        }}
+        onShouldStartLoadWithRequest={(request) => {
+          if (isBootstrapUrl(request.url)) {
+            return true;
+          }
+          openExternal(request.url);
+          return false;
+        }}
+        onOpenWindow={(event) => {
+          const url = event.nativeEvent.targetUrl;
+          if (url) {
+            openExternal(url);
+          }
+        }}
+      />
+    </View>
+  );
+
+  const animatedBar = (
+    <Animated.View
+      style={[
+        { opacity },
+        overlay ? bannerOverlayShadowStyle(overlayEdge) : null,
+        insetChromeOutsideFade ? null : insetChrome,
+      ]}
+    >
+      {webViewBar}
+    </Animated.View>
+  );
 
   return (
-    <View testID="userflow-banner-frame" style={frameStyle}>
-      <Animated.View style={[{ opacity }, overlay ? bannerOverlayShadowStyle(overlayEdge) : null]}>
-        <View
-          testID="userflow-banner-webview"
-          style={[
-            { borderRadius: barRadius ?? 0, overflow: 'hidden' as const },
-            innerStyle.maxWidth != null ? { maxWidth: innerStyle.maxWidth } : null,
-          ]}
-        >
-          <WebView
-            ref={webRef}
-            source={{ html, baseUrl: EVAL_JS_BASE_URL }}
-            style={webStyle}
-            javaScriptEnabled
-            domStorageEnabled
-            scrollEnabled={false}
-            bounces={false}
-            showsHorizontalScrollIndicator={false}
-            showsVerticalScrollIndicator={false}
-            originWhitelist={['*']}
-            setSupportMultipleWindows={false}
-            androidLayerType="hardware"
-            {...(debugging !== undefined ? { webviewDebuggingEnabled: debugging } : {})}
-            onMessage={onMessage}
-            onLoadEnd={() => {
-              setPageReady(true);
-              webRef.current?.injectJavaScript(
-                'window.__userflowBannerLayout&&window.__userflowBannerLayout();true;',
-              );
-            }}
-            onShouldStartLoadWithRequest={(request) => {
-              if (isBootstrapUrl(request.url)) {
-                return true;
+    <View
+      testID="userflow-banner-frame"
+      style={frameStyle}
+      onLayout={
+        reserveFlowSpace && overlaySafeEdge
+          ? (event) => {
+              onPushChromeLayout(event);
+              const h = event.nativeEvent.layout.height;
+              if (h > 0) {
+                setBannerFlowSpacerHeight(overlaySafeEdge, h);
               }
-              openExternal(request.url);
-              return false;
-            }}
-            onOpenWindow={(event) => {
-              const url = event.nativeEvent.targetUrl;
-              if (url) {
-                openExternal(url);
-              }
-            }}
-          />
-        </View>
-      </Animated.View>
+            }
+          : pushLayoutRegistrationEdge
+            ? onPushChromeLayout
+            : undefined
+      }
+    >
+      {insetChromeOutsideFade ? <View style={insetChrome}>{animatedBar}</View> : animatedBar}
     </View>
   );
 }

package/src/surfaces/bannerWebView/buildCustomBannerHtml.ts

@@ -7,6 +7,8 @@ import type { EvalJsContext } from '../../evalJs/types';
 
 import { collectBannerAutoRunEvalCodes } from './bannerAutoRunEvalJs';
 import { bannerThemeStyleAttribute } from './bannerThemeStyles';
+import { resolveBannerInnerMaxWidth } from '../bannerBarLayout';
+
 import { BANNER_WEB_FRAME_CSS } from './bannerWebFrameCss';
 import { buttonClassName } from './buttonClassName';
 import { resolveCustomStylesheetUrl } from './resolveCdnHost';
@@ -58,30 +60,71 @@ function layoutMeasureScript(): string {
 `;
 }
 
-function bannerInteractionScript(): string {
+function bannerInteractionScript(buttonsJson: string): string {
   return `
 (function(){
+  var __userflowBannerButtons=${buttonsJson};
   function post(msg){
     if(window.ReactNativeWebView&&window.ReactNativeWebView.postMessage){
       window.ReactNativeWebView.postMessage(JSON.stringify(Object.assign({__userflow:1},msg)));
     }
   }
-  document.addEventListener('click',function(ev){
+  function resolveButtonId(el){
+    if(!el||!el.closest)return null;
+    var tagged=el.closest('[data-userflow-banner-button]');
+    if(tagged){
+      return tagged.getAttribute('data-userflow-banner-button');
+    }
+    function hasClass(el,token){
+      if(!token)return false;
+      var cls=el.className||'';
+      var parts=cls.split(/\\s+/);
+      for(var p=0;p<parts.length;p++){
+        if(parts[p]===token)return true;
+      }
+      return false;
+    }
+    function appearanceClass(appearance){
+      if(!appearance)return '';
+      var value=appearance;
+      var known=value==='primary'||value==='PRIMARY'||value==='default'||value==='DEFAULT'||value==='banner-primary'||value==='banner-secondary';
+      return known?'userflowjs-bubble-button--'+value.toLowerCase():value;
+    }
+    var bubble=el.closest('.userflowjs-bubble-button,button.userflowjs-bubble-button');
+    if(bubble){
+      var id=bubble.getAttribute('data-userflow-banner-button');
+      if(id)return id;
+      for(var i=0;i<__userflowBannerButtons.length;i++){
+        var meta=__userflowBannerButtons[i];
+        if(meta.appearance&&hasClass(bubble,appearanceClass(meta.appearance)))return meta.id;
+      }
+    }
+    var custom=el.closest('[class*="userflow-custom-button"]');
+    if(custom){
+      for(var j=0;j<__userflowBannerButtons.length;j++){
+        var entry=__userflowBannerButtons[j];
+        if(entry.appearance&&hasClass(custom,appearanceClass(entry.appearance)))return entry.id;
+      }
+    }
+    return null;
+  }
+  function onActivate(ev){
     var t=ev.target;
     if(!t||!t.closest)return;
-    var btn=t.closest('[data-userflow-banner-button]');
-    if(btn){
-      ev.preventDefault();
-      post({type:'bannerButton',buttonId:btn.getAttribute('data-userflow-banner-button')});
-      return;
-    }
     var close=t.closest('[data-userflow-banner-dismiss]');
     if(close){
       ev.preventDefault();
       window.__userflowBannerEvalDismissed=true;
       post({type:'bannerDismiss'});
+      return;
     }
-  });
+    var buttonId=resolveButtonId(t);
+    if(buttonId){
+      ev.preventDefault();
+      post({type:'bannerButton',buttonId:buttonId});
+    }
+  }
+  document.addEventListener('click',onActivate,true);
 })();
 `;
 }
@@ -129,8 +172,9 @@ export function buildCustomBannerBodyHtml(
   const layoutClass = contentLayoutClass(banner.contentLayout);
   const themeStyle = bannerThemeStyleAttribute(theme);
   const customCssUrl = resolveCustomStylesheetUrl(serverEndpoint, theme);
+  const innerMaxWidth = resolveBannerInnerMaxWidth(banner);
   const maxInner =
-    banner.maxContentWidth != null ? ` style="max-width:${banner.maxContentWidth}px"` : '';
+    innerMaxWidth != null && innerMaxWidth > 0 ? ` style="max-width:${innerMaxWidth}px"` : '';
   const contentHtml = richContentDocToHtml(banner.content, lookupAttribute);
   const buttonsHtml = banner.buttons
     .map((button) => {
@@ -143,6 +187,14 @@ export function buildCustomBannerBodyHtml(
     ? '<div class="userflowjs-banner-start-spacer"></div>'
     : '<button type="button" class="userflowjs-banner-close userflowjs-button-reset" data-userflow-banner-dismiss="1" aria-label="Dismiss">×</button>';
 
+  const buttonMetaJson = JSON.stringify(
+    banner.buttons.map((button) => ({
+      id: button.id,
+      cvid: button.cvid,
+      appearance: button.appearance ?? '',
+    })),
+  ).replace(/</g, '\\u003c');
+
   const customLink = customCssUrl
     ? `<link rel="stylesheet" href="${escapeAttr(customCssUrl)}" />`
     : '';
@@ -158,7 +210,7 @@ ${customLink}
   </div>
   ${closeHtml}
 </div>
-<script>${layoutMeasureScript()}${bannerInteractionScript()}${options?.skipAutoRunEval ? '' : bannerAutoRunEvalScript(banner, lookupAttribute)}</script>
+<script>${layoutMeasureScript()}${bannerInteractionScript(buttonMetaJson)}${options?.skipAutoRunEval ? '' : bannerAutoRunEvalScript(banner, lookupAttribute)}</script>
 `;
 }
 

package/src/surfaces/hostAccessibilityTrap.ts

@@ -0,0 +1,25 @@
+import type { FlowStepFragment } from '@userflow-tech/protocol';
+
+/**
+ * Whether a step hides host app content from the accessibility tree.
+ *
+ * Modals always do. A tooltip does only when `tooltipTargetBlocked` seals its
+ * target too — otherwise the target is the control the step asks the user to
+ * press, so a screen reader has to be able to reach it.
+ *
+ * `UserflowOverlay` traps the host with this, and tooltip cards gate
+ * `accessibilityViewIsModal` on it: on iOS that flag alone drops the host app,
+ * target included, out of VoiceOver's reach.
+ */
+export function stepTrapsHostAccessibility(
+  step: Pick<FlowStepFragment, 'appearance' | 'tooltipTargetBlocked'>,
+): boolean {
+  const appearance = String(step.appearance).toUpperCase();
+  if (appearance === 'HIDDEN') {
+    return false;
+  }
+  if (appearance !== 'TOOLTIP') {
+    return true;
+  }
+  return step.tooltipTargetBlocked;
+}

package/src/surfaces/resolveBannerTheme.ts

@@ -1,6 +1,9 @@
 import type { ThemeFragment } from '@userflow-tech/protocol';
 
-/** Default banner chrome when theme banner tokens are unset (matches product / web debugger palette). */
+/**
+ * Last-resort banner chrome when neither banner nor brand tokens are set on the
+ * wire (web `applyThemeDefaults` falls back to brand first).
+ */
 export const DEFAULT_BANNER_BACKGROUND_COLOR = '#0A1A24';
 export const DEFAULT_BANNER_FOREGROUND_COLOR = '#FFFFFF';
 
@@ -10,9 +13,17 @@ function readThemeColor(theme: ThemeFragment, key: string): string | undefined {
 }
 
 export function resolveBannerBackgroundColor(theme: ThemeFragment): string {
-  return readThemeColor(theme, 'bannerBackgroundColor') ?? DEFAULT_BANNER_BACKGROUND_COLOR;
+  return (
+    readThemeColor(theme, 'bannerBackgroundColor') ??
+    readThemeColor(theme, 'brandBackgroundColor') ??
+    DEFAULT_BANNER_BACKGROUND_COLOR
+  );
 }
 
 export function resolveBannerForegroundColor(theme: ThemeFragment): string {
-  return readThemeColor(theme, 'bannerForegroundColor') ?? DEFAULT_BANNER_FOREGROUND_COLOR;
+  return (
+    readThemeColor(theme, 'bannerForegroundColor') ??
+    readThemeColor(theme, 'brandForegroundColor') ??
+    DEFAULT_BANNER_FOREGROUND_COLOR
+  );
 }

package/src/surfaces/tooltip/TooltipBubble.tsx

@@ -28,6 +28,12 @@ export interface TooltipBubbleProps {
    * target. Defaults to true so isolated chrome tests keep the diamond.
    */
   showNotch?: boolean;
+  /**
+   * iOS: confine VoiceOver to this card. VoiceOver then skips the host app,
+   * including the target, so set it only while the host is hidden from
+   * accessibility anyway. Defaults to false.
+   */
+  accessibilityViewIsModal?: boolean;
 }
 
 /**
@@ -56,6 +62,7 @@ export function TooltipBubble({
   children,
   maxHeight,
   showNotch: showNotchProp = true,
+  accessibilityViewIsModal = false,
 }: TooltipBubbleProps): React.ReactElement {
   const showNotch = showNotchProp && chrome.notchSize > 0;
   const bordered = chrome.borderWidth > 0;
@@ -104,7 +111,7 @@ export function TooltipBubble({
   return (
     <CardFade
       testID="userflow-tooltip-card"
-      accessibilityViewIsModal
+      accessibilityViewIsModal={accessibilityViewIsModal}
       pointerEvents="auto"
       onLayout={onLayout}
       style={[styles.shell, style]}

package/src/surfaces/tooltip/targetSearchSchedule.ts

@@ -0,0 +1,140 @@
+/**
+ * When TooltipSurface looks for its target.
+ *
+ * - Anchored: a steady poll, so a covered or remounted host is noticed quickly.
+ *   Each search is a cache hit for the resolved host.
+ * - Missing: exponential backoff. A miss walks the tree and scores registered
+ *   hosts, so a target on another screen must not cost a full search every
+ *   second for as long as the flow stays open.
+ * - Registry churn (list rows mounting while the user scrolls) pulls the next
+ *   missing search forward, never closer than {@link MISSING_TRIGGER_GAP_MS}
+ *   to the previous one.
+ * - A screen change or a return to the foreground starts the backoff over.
+ * - Nothing runs while paused (app not active).
+ */
+
+/** Poll while the target is anchored. */
+export const ANCHORED_POLL_MS = 250;
+/** First retry after a miss; doubles per consecutive miss. */
+export const MISSING_BACKOFF_BASE_MS = 250;
+/** Ceiling for the missing-target backoff. */
+export const MISSING_BACKOFF_MAX_MS = 4000;
+/** Closest a registry change can pull a missing search to the previous one. */
+export const MISSING_TRIGGER_GAP_MS = 500;
+
+export type TargetSearchMode = 'anchored' | 'missing';
+
+export interface TargetSearchClock {
+  now(): number;
+  setTimeout(handler: () => void, ms: number): ReturnType<typeof setTimeout>;
+  clearTimeout(handle: ReturnType<typeof setTimeout>): void;
+}
+
+const defaultClock: TargetSearchClock = {
+  now: () => Date.now(),
+  setTimeout: (handler, ms) => setTimeout(handler, ms),
+  clearTimeout: (handle) => clearTimeout(handle),
+};
+
+/** Delay before the next search after `misses` consecutive missing searches. */
+export function missingBackoffDelay(misses: number): number {
+  const exponent = Math.max(0, misses - 1);
+  return Math.min(MISSING_BACKOFF_MAX_MS, MISSING_BACKOFF_BASE_MS * 2 ** exponent);
+}
+
+export class TargetSearchSchedule {
+  private mode: TargetSearchMode = 'missing';
+  /** Searches run since the target was last anchored (or the backoff restarted). */
+  private misses = 0;
+  private lastRunAt = Number.NEGATIVE_INFINITY;
+  private handle: ReturnType<typeof setTimeout> | null = null;
+  private dueAt = Number.POSITIVE_INFINITY;
+  private paused = false;
+  private disposed = false;
+
+  constructor(
+    private readonly search: () => void,
+    private readonly clock: TargetSearchClock = defaultClock,
+  ) {}
+
+  /** Search now and schedule the next one. No-op while paused. */
+  runNow(): void {
+    if (this.disposed || this.paused) return;
+    this.cancel();
+    this.lastRunAt = this.clock.now();
+    if (this.mode === 'missing') this.misses += 1;
+    try {
+      this.search();
+    } finally {
+      if (!this.disposed && !this.paused && this.handle == null) {
+        this.scheduleIn(this.nextDelay());
+      }
+    }
+  }
+
+  /** The target was found or lost. Starts the matching cadence from now. */
+  setMode(mode: TargetSearchMode): void {
+    if (this.disposed || mode === this.mode) return;
+    this.mode = mode;
+    this.misses = 0;
+    if (this.paused) return;
+    this.scheduleIn(mode === 'anchored' ? ANCHORED_POLL_MS : MISSING_BACKOFF_BASE_MS);
+  }
+
+  /** Something the target may depend on changed (a registry mount / unmount). */
+  trigger(): void {
+    if (this.disposed || this.paused || this.mode !== 'missing') return;
+    const now = this.clock.now();
+    const dueAt = Math.max(now, this.lastRunAt + MISSING_TRIGGER_GAP_MS);
+    if (dueAt >= this.dueAt) return;
+    this.scheduleIn(dueAt - now);
+  }
+
+  /** Restart the backoff and search now (screen change, foreground). */
+  rearm(): void {
+    if (this.disposed) return;
+    this.misses = 0;
+    this.runNow();
+  }
+
+  /** Stop searching until {@link resume}. */
+  pause(): void {
+    if (this.disposed || this.paused) return;
+    this.paused = true;
+    this.cancel();
+  }
+
+  /** Leave the paused state and search right away. */
+  resume(): void {
+    if (this.disposed || !this.paused) return;
+    this.paused = false;
+    this.rearm();
+  }
+
+  dispose(): void {
+    this.cancel();
+    this.disposed = true;
+  }
+
+  private nextDelay(): number {
+    return this.mode === 'anchored' ? ANCHORED_POLL_MS : missingBackoffDelay(this.misses);
+  }
+
+  private scheduleIn(ms: number): void {
+    this.cancel();
+    this.dueAt = this.clock.now() + ms;
+    this.handle = this.clock.setTimeout(() => {
+      this.handle = null;
+      this.dueAt = Number.POSITIVE_INFINITY;
+      this.runNow();
+    }, ms);
+  }
+
+  private cancel(): void {
+    if (this.handle != null) {
+      this.clock.clearTimeout(this.handle);
+      this.handle = null;
+    }
+    this.dueAt = Number.POSITIVE_INFINITY;
+  }
+}

package/src/version.ts

@@ -1,2 +1,2 @@
 /** Generated by scripts/write-version.mjs — do not edit. */
-export const SDK_VERSION = '0.4.4';
+export const SDK_VERSION = '0.5.0';