@userflow-tech/react-native 0.6.0 → 0.7.0

package/src/authoring/hitTest.ts

@@ -17,11 +17,16 @@ import {
 } from '../anchors/fiber/fiberInternals';
 import { createLazyHostFiberIndex, lookupHostFiber } from '../anchors/fiber/indexHostFibers';
 import { measureHostFiber } from '../anchors/fiber/measureHostFiber';
+import {
+  isOutsideModal,
+  locatePresentedModal,
+  rectInWindow,
+  type PresentedModal,
+} from '../anchors/fiber/presentedModal';
 import { readHostText } from '../anchors/fiber/readHostContent';
 import {
   clipToScrollViewports,
   fiberIsUnder,
-  topmostVisibleModalHost,
   type VisibleRect,
 } from '../anchors/fiber/visibleRect';
 import { isFiberOnVisibleScreen } from '../anchors/fiber/visibleScreens';
@@ -61,7 +66,17 @@ export interface HitCandidate {
 
 export type MeasureInstance = (inst: AutoAnchorInstance) => Promise<HitRect | null>;
 export type InstanceFilter = (inst: AutoAnchorInstance) => boolean;
-export type HostAtPoint = (x: number, y: number) => Promise<AnyFiber | null>;
+/**
+ * Why a tap on a presented modal found nothing: the modal cannot be placed in
+ * the window, or the tap was outside it.
+ */
+export type ModalMiss = 'unplaceable' | 'outside';
+
+export type HostAtPoint = (
+  x: number,
+  y: number,
+  presented?: PresentedModal | null,
+) => Promise<AnyFiber | null>;
 
 const MEASURE_TIMEOUT_MS = 400;
 
@@ -259,10 +274,14 @@ function targetForHost(
  * {@link FiberScanRoot}. Hosts above it (the provider's own wrappers) are never
  * resolvable at play time. Empty when `host` is on a covered screen: its
  * ancestors above the navigator are not what was tapped.
+ *
+ * The walk also stops at `boundary`, a presented modal: hosts above it are
+ * drawn beneath the modal, not around what was tapped.
  */
 export function candidateChain(
   host: AnyFiber,
   byFiber: Map<AnyFiber, AutoAnchorInstance>,
+  boundary?: AnyFiber | null,
 ): PickTarget[] {
   const chain: PickTarget[] = [];
   if (!isFiberOnVisibleScreen(host)) return chain;
@@ -281,6 +300,7 @@ export function candidateChain(
       seenFibers.add(target.fiber);
       chain.push(target);
     }
+    if (boundary && (current === boundary || current === getAlternate(boundary))) break;
     current = getReturn(current);
   }
   return chain;
@@ -335,16 +355,30 @@ export function defaultCandidateIndex(candidates: HitCandidate[]): number {
   return index >= 0 ? index : 0;
 }
 
+function targetFiber(target: PickTarget): AnyFiber | null {
+  return target.source === 'fiber'
+    ? target.fiber
+    : fiberFromPublicInstanceSafe(target.instance.ref.current);
+}
+
 async function clipCandidate(candidate: HitCandidate): Promise<HitCandidate | null> {
-  const fiber =
-    candidate.target.source === 'fiber'
-      ? candidate.target.fiber
-      : fiberFromPublicInstanceSafe(candidate.target.instance.ref.current);
+  const fiber = targetFiber(candidate.target);
   const clipped = await clipToScrollViewports(fiber, candidate.rect as VisibleRect);
   if (!clipped) return null;
   return { ...candidate, rect: clipped, area: areaOf(clipped) };
 }
 
+/** `candidate` in window coordinates. A presented modal's content is measured in the modal's space. */
+function candidateInWindow(
+  candidate: HitCandidate,
+  presented: PresentedModal | null,
+): HitCandidate {
+  if (!presented) return candidate;
+  const fiber = targetFiber(candidate.target);
+  if (fiber && !fiberIsUnder(fiber, presented.host)) return candidate;
+  return { ...candidate, rect: rectInWindow(candidate.rect, presented) };
+}
+
 /**
  * Hit-test window coordinates.
  *
@@ -353,6 +387,12 @@ async function clipCandidate(candidate: HitCandidate): Promise<HitCandidate | nu
  * lands on a covered screen. A visible native hit with no identifiable
  * ancestor returns no candidates: geometry ignores stacking order and would
  * offer whatever lies underneath the tap.
+ *
+ * While a modal is presented, only its content is a candidate, and candidate
+ * rects come back in window coordinates. A modal that cannot be placed in the
+ * window yields no candidates rather than a guess, and so does a tap outside
+ * the modal, on the screen it covers. Both call `onModalMiss` so the caller
+ * can say why.
  */
 export async function hitTestAt(
   x: number,
@@ -362,6 +402,7 @@ export async function hitTestAt(
     measure?: MeasureInstance;
     instances?: AutoAnchorInstance[];
     hostAtPoint?: HostAtPoint;
+    onModalMiss?: (miss: ModalMiss) => void;
   },
 ): Promise<HitCandidate[]> {
   const filter = opts?.instanceFilter ?? createVisibleInstanceFilter();
@@ -369,21 +410,33 @@ export async function hitTestAt(
   const pool = (opts?.instances ?? autoAnchorRegistry.allInstances()).filter(filter);
   autoAnchorRegistry.refreshLiveContent(pool);
 
+  const presented = await locatePresentedModal(fiberScanRoot.getFiber());
+  if (presented && !presented.origin) {
+    opts?.onModalMiss?.('unplaceable');
+    return [];
+  }
+  if (presented && isOutsideModal(x, y, presented)) {
+    opts?.onModalMiss?.('outside');
+    return [];
+  }
+
   const injected = opts?.hostAtPoint;
   const locate = injected ?? (opts?.measure === undefined ? hostAtPoint : null);
   if (locate) {
     try {
-      const host = await locate(x, y);
+      const host = await locate(x, y, presented);
       if (host && isFiberOnVisibleScreen(host)) {
-        const chain = candidateChain(host, registryMap(pool));
-        return chain.length > 0 ? candidatesFromChain(chain, measure) : [];
+        const chain = candidateChain(host, registryMap(pool), presented?.host);
+        if (chain.length === 0) return [];
+        const candidates = await candidatesFromChain(chain, measure);
+        return candidates.map((candidate) => candidateInWindow(candidate, presented));
       }
     } catch {
       // Native hit-testing is optional; geometry still runs.
     }
   }
 
-  return geometryHits(x, y, pool, measure);
+  return geometryHits(x, y, pool, measure, presented);
 }
 
 async function geometryHits(
@@ -391,9 +444,10 @@ async function geometryHits(
   y: number,
   pool: AutoAnchorInstance[],
   measure: MeasureInstance,
+  presented: PresentedModal | null,
 ): Promise<HitCandidate[]> {
   const root = fiberScanRoot.getFiber();
-  const modal = root ? topmostVisibleModalHost(root) : null;
+  const modal = presented?.host ?? null;
   const byFiber = registryMap(pool);
 
   const scoped = modal
@@ -426,14 +480,35 @@ async function geometryHits(
       if (!raw) return null;
       const clipped = await clipCandidate({ target, rect: raw, area: areaOf(raw) });
       if (!clipped) return null;
-      if (!pointInRect(x, y, clipped.rect)) return null;
-      return clipped;
+      const placed = candidateInWindow(clipped, presented);
+      if (!pointInRect(x, y, placed.rect)) return null;
+      return placed;
     }),
   );
 
   return measured.filter((c): c is HitCandidate => c != null).sort((a, b) => a.area - b.area);
 }
 
+/**
+ * `candidates` measured again, for when the screen may have moved under a
+ * selection: the keyboard opening or closing resizes or moves a sheet. Null
+ * when one can no longer be measured, or its modal can no longer be placed,
+ * so the caller drops the selection rather than keep a stale rect.
+ */
+export async function remeasureCandidates(
+  candidates: HitCandidate[],
+  measure: MeasureInstance = measureInstanceRect,
+): Promise<HitCandidate[] | null> {
+  const presented = await locatePresentedModal(fiberScanRoot.getFiber());
+  if (presented && !presented.origin) return null;
+  const measured = await candidatesFromChain(
+    candidates.map((candidate) => candidate.target),
+    measure,
+  );
+  if (measured.length !== candidates.length) return null;
+  return measured.map((candidate) => candidateInWindow(candidate, presented));
+}
+
 /** Cycle to the next-larger containing candidate (wraps). */
 export function nextContainingIndex(candidates: HitCandidate[], currentIndex: number): number {
   if (candidates.length === 0) return -1;

package/src/authoring/hostAtPoint.ts

@@ -11,9 +11,10 @@
  *   (see `FindNodeAtPointTest.overlappingViewsWithParentPointerEventsNone`).
  * - Scroll views subtract `contentOffset` in `getContentOriginOffset`, so
  *   content scrolled out of the viewport is not a hit.
- * - Modal content lives under `ModalHostView` in the same shadow tree, but
- *   its frame is relative to the modal window. If the root hit misses the
- *   visible modal's subtree, retry rooted at that modal.
+ * - Content of a presented modal (`RNSModalScreen`, `ModalHostView`) lives in
+ *   the same shadow tree, but Fabric lays it out relative to the modal. While
+ *   one is presented, everything else is drawn beneath it, so only the modal is
+ *   hit, with the point moved into its space (see `presentedModal.ts`).
  * - Screens a navigator covers stay laid out in the shadow tree, on top of the
  *   visible one, and react-native-screens clears their zIndex, so the
  *   last-mounted sibling wins. After visiting a later tab, a tap on an earlier
@@ -33,7 +34,11 @@ import {
 import { nearestHostDescendant } from '../anchors/fiber/findAnchorFiber';
 import { createHostFiberIndex } from '../anchors/fiber/indexHostFibers';
 import { measureHostFiber } from '../anchors/fiber/measureHostFiber';
-import { fiberIsUnder, topmostVisibleModalHost } from '../anchors/fiber/visibleRect';
+import {
+  locatePresentedModal,
+  type Point,
+  type PresentedModal,
+} from '../anchors/fiber/presentedModal';
 import { isFiberOnVisibleScreen, screensCoveringFiber } from '../anchors/fiber/visibleScreens';
 
 const HIT_TIMEOUT_MS = 400;
@@ -167,11 +172,20 @@ function originInParent(
   }, none);
 }
 
-async function hitFabric(rootHost: AnyFiber, x: number, y: number): Promise<AnyFiber | null> {
+/**
+ * `rootOrigin` is where `rootHost` sits in the point's space, for a root that
+ * `measureInWindow` cannot place: a presented modal, whose space is its own.
+ */
+async function hitFabric(
+  rootHost: AnyFiber,
+  x: number,
+  y: number,
+  rootOrigin?: Point,
+): Promise<AnyFiber | null> {
   const manager = fabricManager();
   const node = shadowNodeFromHost(rootHost);
   if (!manager || node == null) return null;
-  const origin = await measureOrigin(rootHost);
+  const origin = rootOrigin ?? (await measureOrigin(rootHost));
   if (!origin) return null;
   const inParent = await originInParent(manager, node);
   const handle = await withTimeout<unknown>((settle) => {
@@ -199,25 +213,43 @@ async function hitPaper(rootHost: AnyFiber, x: number, y: number): Promise<AnyFi
   return index.byNativeTag.get(nativeTag) ?? null;
 }
 
-async function hitUnder(rootHost: AnyFiber, x: number, y: number): Promise<AnyFiber | null> {
-  const fabric = await hitFabric(rootHost, x, y);
+/**
+ * `inModalSpace`: the point is in a presented modal's own space. Paper's
+ * lookup takes window points, so it would land elsewhere there (and
+ * bridgeless logs an error when it finds nothing).
+ */
+async function hitUnder(
+  rootHost: AnyFiber,
+  x: number,
+  y: number,
+  rootOrigin: Point | undefined,
+  inModalSpace: boolean,
+): Promise<AnyFiber | null> {
+  const fabric = await hitFabric(rootHost, x, y, rootOrigin);
   if (fabric) return fabric;
+  if (inModalSpace) return null;
   return hitPaper(rootHost, x, y);
 }
 
-/** {@link hitUnder}, re-hit from the visible screen while the hit lands on a covered one. */
+/**
+ * {@link hitUnder}, re-hit from the visible screen while the hit lands on a
+ * covered one. A `rootOrigin` means the point is in a presented modal's space;
+ * screens inside the modal measure in that space too.
+ */
 async function hitOnVisibleScreen(
   rootHost: AnyFiber,
   x: number,
   y: number,
+  rootOrigin?: Point,
 ): Promise<AnyFiber | null> {
-  let hit = await hitUnder(rootHost, x, y);
+  const inModalSpace = rootOrigin !== undefined;
+  let hit = await hitUnder(rootHost, x, y, rootOrigin, inModalSpace);
   for (let attempt = 0; hit && attempt < MAX_COVERED_SCREEN_RETRIES; attempt += 1) {
     const screens = screensCoveringFiber(hit);
     if (screens.length === 0) return hit;
     let next: AnyFiber | null = null;
     for (const screen of screens) {
-      next = await hitUnder(screen, x, y);
+      next = await hitUnder(screen, x, y, undefined, inModalSpace);
       if (next) break;
     }
     hit = next;
@@ -226,22 +258,36 @@ async function hitOnVisibleScreen(
   return hit && isFiberOnVisibleScreen(hit) ? hit : null;
 }
 
+const MODAL_SPACE_ORIGIN: Point = { x: 0, y: 0 };
+
 /**
  * Host fiber drawn on top at window coordinates, or null when neither Fabric
  * nor Paper hit-testing is available.
+ *
+ * While a modal is presented, only its content can be hit, and nothing is
+ * when the modal cannot be placed in the window. Pass `presented` when the
+ * caller has already looked it up.
  */
-export async function hostAtPoint(x: number, y: number): Promise<AnyFiber | null> {
+export async function hostAtPoint(
+  x: number,
+  y: number,
+  presented?: PresentedModal | null,
+): Promise<AnyFiber | null> {
   const root = fiberScanRoot.getFiber();
   if (!root) return null;
-  const rootHost = nearestHostDescendant(root);
-  if (!rootHost) return null;
 
-  let hit = await hitOnVisibleScreen(rootHost, x, y);
-  const modal = topmostVisibleModalHost(root);
-  const modalHost = modal ? nearestHostDescendant(modal) : null;
-  if (modalHost && (!hit || !fiberIsUnder(hit, modal))) {
-    const modalHit = await hitOnVisibleScreen(modalHost, x, y);
-    if (modalHit) hit = modalHit;
+  const modal = presented === undefined ? await locatePresentedModal(root) : presented;
+  if (modal) {
+    if (!modal.origin) return null;
+    return hitOnVisibleScreen(
+      modal.host,
+      x - modal.origin.x,
+      y - modal.origin.y,
+      modal.modalSpace ? MODAL_SPACE_ORIGIN : undefined,
+    );
   }
-  return hit;
+
+  const rootHost = nearestHostDescendant(root);
+  if (!rootHost) return null;
+  return hitOnVisibleScreen(rootHost, x, y);
 }

package/src/content/RichContentRenderer.tsx

@@ -293,7 +293,8 @@ function TextBlock({
     | Heading1Element
     | Heading2Element
     | { align?: TextAlign | null; children: RichContentInlineNode[] };
-  style: TextStyle;
+  // React Native 0.88's StyleSheet.flatten can return null or undefined.
+  style: TextStyle | null | undefined;
   accessibilityRole?: 'header' | 'text';
 }): React.ReactElement {
   return (
@@ -576,15 +577,16 @@ function baseText(theme: ThemeFragment): TextStyle {
 }
 
 function markStyle(node: AbstractRichContentTextFormatting): TextStyle {
-  const style: TextStyle = {};
-  if (node.bold) style.fontWeight = '700';
-  if (node.italic) style.fontStyle = 'italic';
   const decoration = textDecoration(node);
-  if (decoration) style.textDecorationLine = decoration;
-  if (node.small) style.fontSize = 12;
-  else if (node.sup) style.fontSize = 10;
-  if (node.color) style.color = node.color;
-  return style;
+  const fontSize = node.small ? 12 : node.sup ? 10 : undefined;
+  // Built in one literal: React Native 0.88 types TextStyle as readonly.
+  return {
+    ...(node.bold ? { fontWeight: '700' as const } : null),
+    ...(node.italic ? { fontStyle: 'italic' as const } : null),
+    ...(decoration ? { textDecorationLine: decoration } : null),
+    ...(fontSize != null ? { fontSize } : null),
+    ...(node.color ? { color: node.color } : null),
+  };
 }
 
 /** View wrapper so inline code padding/radius work reliably on Android. */

package/src/deepLinking.ts

@@ -27,7 +27,8 @@ export interface DeepLinkingDeps {
   startFlowWithToken: DeepLinkStartFlowWithToken;
   /** Optional Linking overrides for tests. */
   linking?: {
-    getInitialURL: () => Promise<string | null>;
+    // React Native 0.88 adds undefined to the result.
+    getInitialURL: () => Promise<string | null | undefined>;
     addEventListener: (
       type: 'url',
       handler: (event: { url: string }) => void,

package/src/deviceContext.ts

@@ -1,16 +1,24 @@
 /**
- * Resolve mobile platform metadata for Userflow user attributes.
+ * Resolve mobile platform metadata and the running SDK version for Userflow
+ * user attributes.
  *
  * Cached once during {@link Userflow.init} and merged into identify attributes
  * (same lifecycle as {@link hostAppVersion.ts}).
  */
 
+import { SDK_VERSION } from './version';
+
 export type SdkPlatform = 'react_native';
 export type DeviceOs = 'ios' | 'android';
 export type DeviceType = 'phone' | 'tablet';
 
 export interface DeviceContext {
   sdk: SdkPlatform;
+  /**
+   * Published `@userflow-tech/react-native` version, e.g. `0.4.6`. Always set by
+   * the SDK; optional so context objects built by host code (mocks) stay valid.
+   */
+  sdkVersion?: string;
   deviceOs?: DeviceOs;
   deviceType?: DeviceType;
 }
@@ -19,6 +27,7 @@ export interface DeviceContext {
 export const ANDROID_TABLET_SMALLEST_WIDTH_DP = 600;
 
 export const SDK_USER_ATTRIBUTE = 'sdk';
+export const SDK_VERSION_USER_ATTRIBUTE = 'sdk_version';
 export const DEVICE_OS_USER_ATTRIBUTE = 'device_os';
 export const DEVICE_TYPE_USER_ATTRIBUTE = 'device_type';
 
@@ -70,6 +79,7 @@ export function resolveDeviceContextFromSources(sources: {
   const deviceType = resolveDeviceTypeFromSources(sources);
   return {
     sdk: 'react_native',
+    sdkVersion: SDK_VERSION,
     ...(deviceOs ? { deviceOs } : {}),
     ...(deviceType ? { deviceType } : {}),
   };
@@ -103,6 +113,7 @@ export function resolveDeviceContext(): DeviceContext {
 
 /** `undefined` until the first {@link cacheDeviceContextAtInit}; then resolved. */
 let cachedDeviceContext: DeviceContext | undefined;
+let didWarnSdkVersionOverride = false;
 
 /**
  * Resolve and cache device metadata during {@link Userflow.init}.
@@ -118,33 +129,57 @@ export function getCachedDeviceContext(): DeviceContext | null {
   return cachedDeviceContext ?? null;
 }
 
-/** Returns cached device fields for UpsertUser, or `{}` before init. */
-export function deviceContextUserAttributes(): Record<string, string> {
-  const cached = getCachedDeviceContext();
-  if (!cached) return {};
+/** Device fields for UpsertUser that identify attributes may override. */
+function overridableDeviceAttributes(context: DeviceContext): Record<string, string> {
   return {
-    [SDK_USER_ATTRIBUTE]: cached.sdk,
-    ...(cached.deviceOs ? { [DEVICE_OS_USER_ATTRIBUTE]: cached.deviceOs } : {}),
-    ...(cached.deviceType ? { [DEVICE_TYPE_USER_ATTRIBUTE]: cached.deviceType } : {}),
+    [SDK_USER_ATTRIBUTE]: context.sdk,
+    ...(context.deviceOs ? { [DEVICE_OS_USER_ATTRIBUTE]: context.deviceOs } : {}),
+    ...(context.deviceType ? { [DEVICE_TYPE_USER_ATTRIBUTE]: context.deviceType } : {}),
   };
 }
 
 /** Optional user-attribute keys added by {@link mergeDeviceContextUserAttributes}. */
 export type DeviceContextUserAttributeMap = Partial<{
   [SDK_USER_ATTRIBUTE]: SdkPlatform;
+  [SDK_VERSION_USER_ATTRIBUTE]: string;
   [DEVICE_OS_USER_ATTRIBUTE]: DeviceOs;
   [DEVICE_TYPE_USER_ATTRIBUTE]: DeviceType;
 }>;
 
-/** Merges cached device attrs into identify attributes; caller values win on key conflicts. */
+/** One development warning when identify attributes try to set `sdk_version`. */
+function warnIfSdkVersionOverridden(attributes: Record<string, unknown> | undefined): void {
+  if (!__DEV__ || didWarnSdkVersionOverride) return;
+  const passed = attributes?.[SDK_VERSION_USER_ATTRIBUTE];
+  // `{ set: value }` is the long form of a bare literal.
+  const value =
+    typeof passed === 'object' && passed !== null && 'set' in passed
+      ? (passed as { set: unknown }).set
+      : passed;
+  if (value === undefined || value === SDK_VERSION) return;
+  didWarnSdkVersionOverride = true;
+  // eslint-disable-next-line no-console -- intentional development diagnostic
+  console.warn(
+    `[Userflow] "${SDK_VERSION_USER_ATTRIBUTE}" is set by the SDK (${SDK_VERSION}); the value passed to identify / identifyAnonymous was ignored.`,
+  );
+}
+
+/**
+ * Merges cached device attrs into identify attributes. Caller values win on key
+ * conflicts, except `sdk_version`, which always reports the running SDK.
+ */
 export function mergeDeviceContextUserAttributes<T extends Record<string, unknown>>(
   attributes?: T,
 ): (T & DeviceContextUserAttributeMap) | undefined {
-  const system = deviceContextUserAttributes();
-  if (Object.keys(system).length === 0) {
+  const cached = getCachedDeviceContext();
+  if (!cached) {
     return attributes as (T & DeviceContextUserAttributeMap) | undefined;
   }
-  return { ...system, ...(attributes ?? {}) } as T & DeviceContextUserAttributeMap;
+  warnIfSdkVersionOverridden(attributes);
+  return {
+    ...overridableDeviceAttributes(cached),
+    ...(attributes ?? {}),
+    [SDK_VERSION_USER_ATTRIBUTE]: SDK_VERSION,
+  } as T & DeviceContextUserAttributeMap;
 }
 
 export function formatDeviceContextLog(resolved: DeviceContext | null): string {
@@ -153,7 +188,7 @@ export function formatDeviceContextLog(resolved: DeviceContext | null): string {
   }
   const os = resolved.deviceOs ?? 'unknown';
   const type = resolved.deviceType ?? 'unknown';
-  return `[Userflow] device context sdk=${resolved.sdk} device_os=${os} device_type=${type}`;
+  return `[Userflow] device context sdk=${resolved.sdk} sdk_version=${resolved.sdkVersion ?? 'unknown'} device_os=${os} device_type=${type}`;
 }
 
 /** Log cached user-attribute values. Requires {@link cacheDeviceContextAtInit}. */
@@ -162,7 +197,8 @@ export function logDeviceContext(): void {
   console.log(formatDeviceContextLog(getCachedDeviceContext()));
 }
 
-/** @internal Resets init cache between tests. */
+/** @internal Resets init cache and the one-time override warning between tests. */
 export function resetCachedDeviceContextForTests(): void {
   cachedDeviceContext = undefined;
+  didWarnSdkVersionOverride = false;
 }

package/src/index.ts

@@ -368,7 +368,10 @@ export const Userflow = {
   setOnNavigate(handler: FlowNavigateHandler | null | undefined): void {
     setHostOnNavigate(handler);
   },
-  /** Identify the current user and upsert their attributes. */
+  /**
+   * Identify the current user and upsert their attributes. The SDK adds `sdk_version`
+   * itself; a value passed for it here is ignored.
+   */
   async identify(
     userId: string,
     attributes?: UserflowAttributes,
@@ -391,7 +394,10 @@ export const Userflow = {
     await core.identify(userId, mergeSystemUserAttributes(attributes), options);
     await afterIdentify();
   },
-  /** Identify an anonymous user with a stable auto-generated id stored on device. */
+  /**
+   * Identify an anonymous user with a stable auto-generated id stored on device. Like
+   * {@link identify}, the SDK sets `sdk_version` itself.
+   */
   async identifyAnonymous(
     attributes?: UserflowAttributes,
     options?: UserflowIdentifyOptions,
@@ -478,8 +484,8 @@ export const Userflow = {
     return getCachedHostAppVersion();
   },
   /**
-   * Platform metadata cached during {@link init} (`sdk`, `deviceOs`, `deviceType`),
-   * or `null` before init.
+   * Platform metadata cached during {@link init} (`sdk`, `sdkVersion`, `deviceOs`,
+   * `deviceType`), or `null` before init.
    */
   getDeviceContext(): DeviceContext | null {
     return getCachedDeviceContext();
@@ -576,7 +582,7 @@ export const Userflow = {
     logHostAppVersionToConsole();
   },
   /**
-   * Log cached user-attribute values (`sdk`, `device_os`, `device_type`).
+   * Log cached user-attribute values (`sdk`, `sdk_version`, `device_os`, `device_type`).
    * Requires {@link init}; before init, logs that init is required.
    */
   logDeviceContext(): void {

package/src/installCheck.ts

@@ -10,7 +10,7 @@ export const INSTALL_ASYNC_STORAGE_LINE =
   '- @react-native-async-storage/async-storage is not linked. Anonymous users and Builder pairing will not persist. Add it to the app package.json (npx expo install @react-native-async-storage/async-storage), run pod install on iOS, and rebuild.';
 
 export const INSTALL_VIEW_SHOT_LINE =
-  '- react-native-view-shot is not linked, so Builder element selection gets no screenshot. Install it and rebuild. On Expo SDK 56 and 57, run npx expo install react-native-view-shot unpinned, with no expo.install.exclude entry for it. Otherwise install react-native-view-shot@^5.0.0; on Expo SDK 55 and older, an unpinned npx expo install resolves 4.0.3.';
+  '- react-native-view-shot is not linked, so Builder element selection gets no screenshot. Install it and rebuild. On Expo SDK 56 to 58, run npx expo install react-native-view-shot unpinned, with no expo.install.exclude entry for it. Otherwise install react-native-view-shot@^5.0.0; on Expo SDK 55 and older, an unpinned npx expo install resolves 4.0.3.';
 
 export const INSTALL_WEBVIEW_LINE =
   '- react-native-webview is not linked. Evaluate JavaScript and WebView banners will not run. Install it (npx expo install react-native-webview) and rebuild.';
@@ -36,7 +36,7 @@ export const INSTALL_SAFE_AREA_WARNING =
 export function formatViewShotVersionWarning(version: string): string {
   return (
     `[Userflow] react-native-view-shot@${version} is older than 5.0.0, so Builder element selection may not get a screenshot. ` +
-    'On Expo SDK 56 and 57, run npx expo install react-native-view-shot unpinned, with no expo.install.exclude entry for it, and rebuild. ' +
+    'On Expo SDK 56 to 58, run npx expo install react-native-view-shot unpinned, with no expo.install.exclude entry for it, and rebuild. ' +
     'Otherwise install react-native-view-shot@^5.0.0 in the same command as the SDK and rebuild; on Expo SDK 55 and older, also add "react-native-view-shot" to expo.install.exclude. ' +
     'Do not retry the install with --force or --legacy-peer-deps; that leaves this version in place.\n' +
     INSTALL_CHECK_FOOTER
@@ -89,7 +89,7 @@ function readViewShotVersion(): string | null {
   }
 }
 
-/** Dev warning when view-shot 4.x is installed. Null on 5.x or when it is absent. */
+/** Dev warning when view-shot 4.x is installed. Null on 5.x and later, or when it is absent. */
 export function viewShotVersionWarning(): string | null {
   const version = readViewShotVersion();
   if (!version) return null;

package/src/lifecycle.ts

@@ -94,7 +94,8 @@ export class LifecycleController {
   private readonly scheduler: LifecycleScheduler;
   private readonly now: () => number;
   private readonly suspendGraceMs: number;
-  private readonly getCurrentAppState: () => AppStateStatus;
+  /** Wider than AppStateStatus: React Native 0.88 types currentState as `string | null | undefined`. */
+  private readonly getCurrentAppState: () => string | null | undefined;
   private readonly subscribeAppState: (handler: (status: AppStateStatus) => void) => () => void;
 
   private unsubscribeAppState: (() => void) | null = null;

package/src/pairing/PairingController.ts

@@ -59,7 +59,8 @@ export interface PairingControllerOptions {
    */
   cancelPendingDraftEnd?: () => void;
   LinkingModule?: {
-    getInitialURL(): Promise<string | null>;
+    // React Native 0.88 adds undefined to the result.
+    getInitialURL(): Promise<string | null | undefined>;
     addEventListener(type: 'url', handler: (event: { url: string }) => void): { remove(): void };
   };
   AppStateModule?: {