@robertlinde/react-tour-kit 0.8.9 → 1.0.1

package/src/react-native-platform/layer/tour-host.tsx

@@ -0,0 +1,105 @@
+import {type ComponentRef, type ReactNode, useContext, useRef, useState, useSyncExternalStore} from 'react';
+import {Dimensions, type LayoutChangeEvent, StyleSheet, View} from 'react-native';
+import {devWarn, isDevelopment} from '../../shared/engine/report.util.js';
+import {useIsomorphicLayoutEffect} from '../../shared/react/use-isomorphic-layout-effect.hook.js';
+import {NativeTourContext} from '../native-context.js';
+import {TourOverlay} from '../../shared/renderer/tour-overlay.js';
+import {LayerSizeContext} from './native-renderer.js';
+
+let hostCounter = 0;
+
+/**
+ * Where the tour is drawn. `TourProvider` already renders one around your app; add another
+ * `<TourHost />` as the last child of a screen presented as a native modal (react-native-screens
+ * `presentation: 'modal'`, or inside your own `<Modal>`), so tours can highlight elements there.
+ * The most recently mounted host is used.
+ */
+export function TourHost(): ReactNode {
+  return <HostView isRoot={false} />;
+}
+
+/** @internal Also used by `TourProvider` for its root host. */
+export function HostView({isRoot}: {readonly isRoot: boolean}): ReactNode {
+  const context = useContext(NativeTourContext);
+  const viewRef = useRef<ComponentRef<typeof View> | null>(null);
+  const [key] = useState(() => ++hostCounter);
+  const [size, setSize] = useState({width: 0, height: 0});
+  const hosts = context?.hosts;
+  const activeKey = useSyncExternalStore(
+    hosts?.subscribe ?? subscribeNothing,
+    () => hosts?.activeKey(),
+    () => hosts?.activeKey(),
+  );
+  const engine = context?.overlay.engine;
+  const isTourActive = useSyncExternalStore(
+    engine?.subscribe ?? subscribeNothing,
+    () => engine?.getPublicState().isActive ?? false,
+    () => engine?.getPublicState().isActive ?? false,
+  );
+
+  useIsomorphicLayoutEffect(() => hosts?.register(key, () => viewRef.current, isRoot), [hosts, key, isRoot]);
+
+  if (!context) {
+    if (!isRoot) {
+      devWarn('<TourHost /> must be rendered inside <TourProvider>.');
+    }
+
+    return null;
+  }
+
+  const onLayout = (event: LayoutChangeEvent): void => {
+    const {width, height} = event.nativeEvent.layout;
+    const next = {width, height};
+    setSize(next);
+    context.hosts.setSize(key, next);
+    if (isRoot && isDevelopment) {
+      warnIfNotFullWindow(viewRef.current);
+    }
+  };
+
+  const isActive = activeKey === key;
+  const isModal = !isRoot && isActive && isTourActive;
+  return (
+    <View
+      ref={viewRef}
+      collapsable={false}
+      pointerEvents="box-none"
+      style={StyleSheet.absoluteFill}
+      // A TourHost drawing the tour hides the screen it is in from VoiceOver (its siblings).
+      accessibilityViewIsModal={isModal}
+      onLayout={onLayout}
+    >
+      {/* Drawn in the active host only, once it has been laid out. */}
+      {isActive && size.width > 0 && size.height > 0 ? (
+        <LayerSizeContext.Provider value={size}>
+          <TourOverlay {...context.overlay} />
+        </LayerSizeContext.Provider>
+      ) : null}
+    </View>
+  );
+}
+
+function subscribeNothing(): () => void {
+  return () => {
+    // Nothing to unsubscribe.
+  };
+}
+
+let warnedNotFullWindow = false;
+
+function warnIfNotFullWindow(view: ComponentRef<typeof View> | null): void {
+  if (!view || warnedNotFullWindow) {
+    return;
+  }
+
+  view.measureInWindow((x: number, y: number, width: number, height: number) => {
+    const window = Dimensions.get('window');
+    if (x > 1 || y > 1 || width + 1 < window.width || height + 1 < window.height) {
+      warnedNotFullWindow = true;
+      devWarn(
+        'TourProvider does not fill the window, so the overlay will not cover the whole screen. ' +
+          'Place it at the root of your app, outside SafeAreaView or padded containers, and pass `insets` instead.',
+      );
+    }
+  });
+}

package/src/react-native-platform/measure.util.ts

@@ -0,0 +1,140 @@
+import type {Box} from '../shared/geometry/geometry.type.js';
+
+/** React Native's `measure` callback signature. */
+// eslint-disable-next-line max-params -- signature defined by React Native
+type MeasureCallback = (x: number, y: number, width: number, height: number, pageX: number, pageY: number) => void;
+
+type MeasurableInstance = {
+  getBoundingClientRect?: () => {x: number; y: number; width: number; height: number};
+  measure?: (callback: MeasureCallback) => void;
+  measureLayout?: (
+    relativeTo: unknown,
+    onSuccess: (left: number, top: number, width: number, height: number) => void,
+    onFail?: () => void,
+  ) => void;
+  contains?: (other: unknown) => boolean;
+};
+
+function isMeasurable(value: unknown): value is MeasurableInstance {
+  return typeof value === 'object' && value !== null;
+}
+
+/**
+ * Measures a native view relative to the root view. Uses the synchronous `getBoundingClientRect`
+ * (New Architecture, includes transforms) and falls back to `measure`. Resolves `undefined` for
+ * views that are not rendered (unmounted, zero size, or flattened away on the old architecture).
+ *
+ * Positions are only compared with other positions from this function, so whichever origin the
+ * platform uses (status bar, edge-to-edge) cancels out.
+ */
+export async function measureView(instance: unknown): Promise<Box | undefined> {
+  if (!isMeasurable(instance)) {
+    return undefined;
+  }
+
+  if (typeof instance.getBoundingClientRect === 'function') {
+    const rect = instance.getBoundingClientRect();
+    return valid({x: rect.x, y: rect.y, width: rect.width, height: rect.height});
+  }
+
+  const {measure} = instance;
+  if (typeof measure !== 'function') {
+    return undefined;
+  }
+
+  return new Promise((resolve) => {
+    try {
+      // eslint-disable-next-line max-params -- signature defined by React Native
+      measure.call(instance, (_x, _y, width, height, pageX, pageY) => {
+        resolve(valid({x: pageX, y: pageY, width, height}));
+      });
+    } catch {
+      resolve(undefined);
+    }
+  });
+}
+
+function valid(box: Box): Box | undefined {
+  const finite = [box.x, box.y, box.width, box.height].every(
+    (value) => typeof value === 'number' && Number.isFinite(value),
+  );
+  if (!finite || (box.width <= 0 && box.height <= 0)) {
+    return undefined;
+  }
+
+  return box;
+}
+
+export function relativeTo(box: Box, origin: Box): Box {
+  return {x: box.x - origin.x, y: box.y - origin.y, width: box.width, height: box.height};
+}
+
+/** Longest wait for `measureLayout` (on the Old Architecture a round trip to native). */
+const measureLayoutTimeoutMs = 500;
+
+/**
+ * Where `instance` is inside `ancestor` (from the layout, so also for views that cannot be
+ * measured on screen; possibly zero-sized), `false` when it is not inside it, or `undefined` when
+ * React Native cannot tell.
+ */
+export async function measureLayoutIn(instance: unknown, ancestor: unknown): Promise<Box | false | undefined> {
+  if (!isMeasurable(instance) || !isMeasurable(ancestor) || typeof instance.measureLayout !== 'function') {
+    return undefined;
+  }
+
+  const {measureLayout} = instance;
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      resolve(undefined);
+    }, measureLayoutTimeoutMs);
+    const settle = (result: Box | false | undefined): void => {
+      clearTimeout(timer);
+      resolve(result);
+    };
+
+    try {
+      measureLayout.call(
+        instance,
+        ancestor,
+        (left, top, width, height) => {
+          const box = {x: left, y: top, width, height};
+          settle(Object.values(box).every((value) => Number.isFinite(value)) ? box : undefined);
+        },
+        () => {
+          settle(false);
+        },
+      );
+    } catch {
+      settle(undefined);
+    }
+  });
+}
+
+/** Ancestry does not change for a mounted view (React Native never moves views to another parent). */
+const ancestry = new WeakMap<object, WeakMap<object, boolean>>();
+
+/** Whether `instance` is a descendant of `ancestor`, or `undefined` when React Native cannot tell. */
+export async function isDescendant(instance: unknown, ancestor: unknown): Promise<boolean | undefined> {
+  if (!isMeasurable(instance) || !isMeasurable(ancestor)) {
+    return undefined;
+  }
+
+  const known = ancestry.get(instance)?.get(ancestor);
+  if (known !== undefined) {
+    return known;
+  }
+
+  const result =
+    typeof ancestor.contains === 'function'
+      ? ancestor.contains(instance)
+      : await measureLayoutIn(instance, ancestor).then((position) =>
+          position === undefined ? undefined : position !== false,
+        );
+  if (result !== undefined) {
+    const forInstance = ancestry.get(instance) ?? new WeakMap<object, boolean>();
+    forInstance.set(ancestor, result);
+    ancestry.set(instance, forInstance);
+  }
+
+  return result;
+}

package/src/react-native-platform/native-context.ts

@@ -0,0 +1,15 @@
+import {createContext} from 'react';
+import type {TourOverlayProps} from '../shared/renderer/tour-overlay.js';
+import type {HostStore} from './host-store.js';
+import type {TourRegistry} from './registry.js';
+
+/** Everything the native hooks and hosts need from the provider. Internal. */
+export type NativeTourContextValue = {
+  readonly registry: TourRegistry;
+  readonly hosts: HostStore;
+  /** Rendered by the active host. */
+  readonly overlay: TourOverlayProps;
+};
+
+export const NativeTourContext = createContext<NativeTourContextValue | undefined>(undefined);
+NativeTourContext.displayName = 'NativeTourContext';

package/src/react-native-platform/native-environment.ts

@@ -0,0 +1,33 @@
+import type {Insets, Size} from '../shared/geometry/geometry.type.js';
+import {resolveInsets, type TourInsets} from './insets.util.js';
+
+/**
+ * Values the native platform reads at measuring time (outside React rendering): safe-area insets
+ * and the on-screen keyboard. Updated by the provider in effects.
+ */
+export type NativeEnvironment = {
+  readonly setInsets: (insets: TourInsets | undefined) => void;
+  /** How much of the layer the keyboard covers. Returns whether that changed. */
+  readonly setKeyboardOverlap: (overlap: number) => boolean;
+  readonly getInsets: (layer: Size) => Insets;
+};
+
+export function createNativeEnvironment(): NativeEnvironment {
+  let insets: TourInsets | undefined;
+  let keyboardOverlap = 0;
+  return {
+    setInsets(value): void {
+      insets = value;
+    },
+    setKeyboardOverlap(overlap): boolean {
+      const next = Number.isFinite(overlap) ? Math.max(0, overlap) : 0;
+      if (Math.abs(next - keyboardOverlap) < 0.5) {
+        return false;
+      }
+
+      keyboardOverlap = next;
+      return true;
+    },
+    getInsets: (layer) => resolveInsets(insets, layer, keyboardOverlap),
+  };
+}

package/src/react-native-platform/native-platform.ts

@@ -0,0 +1,368 @@
+import {nextFrame} from '../shared/engine/abort.util.js';
+import type {TargetMeasurement} from '../shared/engine/tour-adapter.type.js';
+import {containsBox, intersect, narrowClip} from '../shared/geometry/box.util.js';
+import type {Box, Insets, Size, Viewport} from '../shared/geometry/geometry.type.js';
+import type {
+  ExternalValue,
+  PlatformAdapter,
+  ScrollContainer,
+  ScrollContainerMetrics,
+} from '../shared/platform/platform.type.js';
+import type {TourTarget} from '../shared/types/tour-step.type.js';
+import {isDescendant, measureLayoutIn, measureView, relativeTo} from './measure.util.js';
+import type {TourRegistry} from './registry.js';
+
+export type NativePlatformOptions = {
+  readonly registry: TourRegistry;
+  /** The view the tour is drawn in (the provider's root layer, or the newest `TourHost`). */
+  readonly getHost: () => {readonly instance: unknown; readonly size: Size} | undefined;
+  readonly getInsets: () => Insets;
+  /** Subscribes to anything that can move targets: layer size, keyboard, safe-area changes. */
+  readonly subscribeLayout: (listener: () => void) => () => void;
+  readonly reducedMotion: ExternalValue<boolean>;
+  readonly getPixelRatio: () => number;
+};
+
+/** What the tour uses of a `ScrollView` instance. */
+type ScrollViewInstance = {
+  getNativeScrollRef?: () => unknown;
+  getInnerViewRef?: () => unknown;
+  getScrollResponder?: () => unknown;
+  scrollTo?: (params: {x?: number; y?: number; animated?: boolean}) => void;
+};
+
+type ScrollViewGeometry = {
+  readonly scrollView: ScrollViewInstance;
+  /** The visible area of the scroll view, in layer coordinates. */
+  readonly viewport: Box;
+  /** The scrollable content, in layer coordinates. */
+  readonly content: Box;
+};
+
+/** A target found on screen: the view, and where it is in layer coordinates. */
+type LocatedTarget = {
+  readonly instance: unknown;
+  readonly rect: Box;
+  /** The registered scroll views, when they were already measured to find the target. */
+  readonly geometries: readonly ScrollViewGeometry[] | undefined;
+};
+
+const area = (box: Box): number => box.width * box.height;
+
+function isObject(value: unknown): value is ScrollViewInstance {
+  return typeof value === 'object' && value !== null;
+}
+
+/**
+ * The `ScrollView` behind a registered ref. Lists (`FlatList`, `SectionList`, `VirtualizedList`)
+ * expose theirs as the scroll responder; a `ScrollView` is its own.
+ */
+function scrollViewOf(registered: unknown): ScrollViewInstance | undefined {
+  if (!isObject(registered)) {
+    return undefined;
+  }
+
+  if (typeof registered.scrollTo === 'function') {
+    return registered;
+  }
+
+  const responder = registered.getScrollResponder?.();
+  return isObject(responder) && typeof responder.scrollTo === 'function' ? responder : undefined;
+}
+
+/** Scroll offsets are rounded to physical pixels: up to one point off still counts as arrived. */
+const arrivalTolerance = 1;
+/** Frames without movement after which a scroll that moved but stopped short counts as finished. */
+const stillFramesAfterMoving = 3;
+
+/** Which axes a scroll view can scroll: those where its content is bigger than the view. */
+function scrollAxes(geometry: ScrollViewGeometry): {readonly x: boolean; readonly y: boolean} {
+  return {
+    x: geometry.content.width > geometry.viewport.width + arrivalTolerance,
+    y: geometry.content.height > geometry.viewport.height + arrivalTolerance,
+  };
+}
+
+/**
+ * Orders scroll views that all contain the target innermost first: a scroll view inside another
+ * one lies within that one's content.
+ */
+function innermostFirst(geometries: readonly ScrollViewGeometry[]): ScrollViewGeometry[] {
+  const depth = (geometry: ScrollViewGeometry): number =>
+    geometries.filter((other) => other !== geometry && containsBox(other.content, geometry.viewport, 1)).length;
+  // Not `toSorted`: ES2023 is not available on every supported React Native version.
+  // eslint-disable-next-line unicorn/no-array-sort
+  return [...geometries].sort((a, b) => depth(b) - depth(a) || area(a.content) - area(b.content));
+}
+
+/** React Native's raw facts for the tour: measuring views, registered targets and scroll views, the host layer. */
+export function createNativePlatform(env: NativePlatformOptions): PlatformAdapter {
+  async function hostOrigin(): Promise<Box | undefined> {
+    const host = env.getHost();
+    return host ? measureView(host.instance) : undefined;
+  }
+
+  function candidates(target: TourTarget): unknown[] {
+    if (typeof target === 'string') {
+      return env.registry.targets(target).map((ref) => ref.current);
+    }
+
+    return [target.current];
+  }
+
+  async function registeredScrollViews(origin: Box): Promise<ScrollViewGeometry[]> {
+    const geometries = await Promise.all(
+      env.registry.scrollViews().map(async (ref) => scrollViewGeometry(ref.current, origin)),
+    );
+    return geometries.filter((geometry): geometry is ScrollViewGeometry => geometry !== undefined);
+  }
+
+  async function scrollViewGeometry(registered: unknown, origin: Box): Promise<ScrollViewGeometry | undefined> {
+    const scrollView = scrollViewOf(registered);
+    if (!scrollView) {
+      return undefined;
+    }
+
+    const [viewport, content] = await Promise.all([
+      measureView(scrollView.getNativeScrollRef?.() ?? scrollView),
+      measureView(scrollView.getInnerViewRef?.()),
+    ]);
+    if (!viewport || !content) {
+      return undefined;
+    }
+
+    return {scrollView, viewport: relativeTo(viewport, origin), content: relativeTo(content, origin)};
+  }
+
+  /**
+   * The scroll views around the target, innermost first. A scroll view counts when the target is
+   * one of its descendants, where React Native can tell: a header button above a page that has
+   * been scrolled is not inside the page, even though the page's content reaches behind it.
+   * Otherwise it counts when its content contains the target, or another scroll view around it (a
+   * target at the end of a horizontal list below the fold is inside the list, the list inside the page).
+   */
+  async function containingScrollViews(
+    located: LocatedTarget,
+    geometries: readonly ScrollViewGeometry[],
+  ): Promise<ScrollViewGeometry[]> {
+    const ancestry = await Promise.all(
+      geometries.map(async (geometry) => isDescendant(located.instance, geometry.scrollView.getInnerViewRef?.())),
+    );
+    const around = new Set(geometries.filter((_geometry, index) => ancestry[index] === true));
+    const unknown = geometries.filter((_geometry, index) => ancestry[index] === undefined);
+    let isGrowing = true;
+    while (isGrowing) {
+      isGrowing = false;
+      for (const geometry of unknown) {
+        const contains =
+          !around.has(geometry) &&
+          (containsBox(geometry.content, located.rect, 1) ||
+            [...around].some((inner) => containsBox(geometry.content, inner.viewport, 1)));
+        if (contains) {
+          around.add(geometry);
+          isGrowing = true;
+        }
+      }
+    }
+
+    return innermostFirst([...around]);
+  }
+
+  /** The part of `box` not covered by insets (system bars, the keyboard); all of it when nothing of it is uncovered. */
+  function unobstructedPart(box: Box): Box {
+    const size = env.getHost()?.size ?? {width: 0, height: 0};
+    const insets = env.getInsets();
+    const screen = {
+      x: insets.left,
+      y: insets.top,
+      width: size.width - insets.left - insets.right,
+      height: size.height - insets.top - insets.bottom,
+    };
+    const visible = intersect(box, screen);
+    return visible && visible.width > 0 && visible.height > 0 ? visible : box;
+  }
+
+  async function scrollViewMetrics(scrollView: ScrollViewInstance): Promise<ScrollContainerMetrics | undefined> {
+    const origin = await hostOrigin();
+    const current = origin ? await scrollViewGeometry(scrollView, origin) : undefined;
+    if (!current) {
+      return undefined;
+    }
+
+    const offset = {x: current.viewport.x - current.content.x, y: current.viewport.y - current.content.y};
+    const axes = scrollAxes(current);
+    const end = {
+      x: current.content.width - current.viewport.width,
+      y: current.content.height - current.viewport.height,
+    };
+    return {
+      // The part the user can see: scroll views of edge-to-edge apps reach behind the keyboard and
+      // the system bars, and a target scrolled there would still be hidden.
+      area: unobstructedPart(current.viewport),
+      offset,
+      // Content can rest away from offset 0 (content insets under a translucent header, margins,
+      // content centred on a tablet), so the offset can be negative. An axis the scroll view does
+      // not scroll stays where it is.
+      minOffset: {x: axes.x ? Math.min(0, offset.x) : offset.x, y: axes.y ? Math.min(0, offset.y) : offset.y},
+      maxOffset: {x: axes.x ? Math.max(offset.x, end.x) : offset.x, y: axes.y ? Math.max(offset.y, end.y) : offset.y},
+    };
+  }
+
+  function scrollContainer(scrollView: ScrollViewInstance): ScrollContainer {
+    return {
+      measure: async () => scrollViewMetrics(scrollView),
+      async scrollTo(offset, {animated, signal}): Promise<void> {
+        const start = await scrollViewMetrics(scrollView);
+        scrollView.scrollTo?.({x: offset.x, y: offset.y, animated});
+        if (!start) {
+          return;
+        }
+
+        // Scroll views report no "scroll end" for programmatic scrolls, and measurements cannot be
+        // trusted to move either: on the New Architecture they come from the shadow tree, which iOS
+        // only updates when a scroll animation has finished. So wait until the scroll view measures
+        // at the offset it was sent to, on the axes it was asked to move. Content that rests away
+        // from offset 0 can stop a little short: then it counts as done once it moved and stopped.
+        const moves = {
+          x: Math.abs(offset.x - start.offset.x) > arrivalTolerance,
+          y: Math.abs(offset.y - start.offset.y) > arrivalTolerance,
+        };
+        let previous = start.offset;
+        let stillFrames = 0;
+        let hasMoved = false;
+        while (!signal.aborted) {
+          // eslint-disable-next-line no-await-in-loop -- frame by frame
+          await nextFrame(signal);
+          // eslint-disable-next-line no-await-in-loop -- see above
+          const current = await scrollViewMetrics(scrollView);
+          if (signal.aborted || !current) {
+            return;
+          }
+
+          const hasArrived =
+            (!moves.x || Math.abs(current.offset.x - offset.x) <= arrivalTolerance) &&
+            (!moves.y || Math.abs(current.offset.y - offset.y) <= arrivalTolerance);
+          const isStill =
+            Math.abs(current.offset.x - previous.x) < 0.5 && Math.abs(current.offset.y - previous.y) < 0.5;
+          hasMoved ||= !isStill;
+          stillFrames = isStill ? stillFrames + 1 : 0;
+          previous = current.offset;
+          if (hasArrived || (hasMoved && stillFrames >= stillFramesAfterMoving)) {
+            return;
+          }
+        }
+      },
+    };
+  }
+
+  /**
+   * Measures a target that cannot be measured directly through a scroll view's content: on the
+   * Old Architecture, views the layout flattened away and list items scrolled out of the visible
+   * window cannot be measured on screen, but their position in the content is known.
+   */
+  async function measureThroughScrollViews(
+    instance: unknown,
+    geometries: readonly ScrollViewGeometry[],
+  ): Promise<Box | undefined> {
+    for (const geometry of geometries) {
+      // eslint-disable-next-line no-await-in-loop -- the first scroll view that knows the target is enough
+      const position = await measureLayoutIn(instance, geometry.scrollView.getInnerViewRef?.());
+      if (position && (position.width > 0 || position.height > 0)) {
+        return {...position, x: geometry.content.x + position.x, y: geometry.content.y + position.y};
+      }
+    }
+
+    return undefined;
+  }
+
+  async function locateTarget(target: TourTarget, origin: Box): Promise<LocatedTarget | undefined> {
+    const screen = {x: 0, y: 0, width: origin.width, height: origin.height};
+    let geometries: ScrollViewGeometry[] | undefined;
+    // Several components can register the same id (tabs that stay mounted, two screens during a
+    // transition): prefer the newest one that is actually on screen.
+    let fallback: LocatedTarget | undefined;
+    for (const instance of candidates(target)) {
+      // eslint-disable-next-line no-await-in-loop -- candidates are checked in priority order
+      const measured = await measureView(instance);
+      let rect = measured ? relativeTo(measured, origin) : undefined;
+      if (!rect) {
+        // eslint-disable-next-line no-await-in-loop -- only when measuring directly failed
+        geometries ??= await registeredScrollViews(origin);
+        // eslint-disable-next-line no-await-in-loop -- see above
+        rect = await measureThroughScrollViews(instance, geometries);
+      }
+
+      if (!rect) {
+        continue;
+      }
+
+      if (intersect(rect, screen)) {
+        return {instance, rect, geometries};
+      }
+
+      fallback ??= {instance, rect, geometries};
+    }
+
+    return fallback;
+  }
+
+  async function measureTarget(target: TourTarget): Promise<TargetMeasurement | undefined> {
+    const origin = await hostOrigin();
+    const located = origin ? await locateTarget(target, origin) : undefined;
+    if (!origin || !located) {
+      return undefined;
+    }
+
+    const containers = await containingScrollViews(
+      located,
+      located.geometries ?? (await registeredScrollViews(origin)),
+    );
+    let clip: Box | undefined;
+    for (const container of containers) {
+      clip = narrowClip(clip, container.viewport);
+    }
+
+    return {rect: located.rect, clip};
+  }
+
+  return {
+    measure: measureTarget,
+
+    subscribe(_target, onChange): () => void {
+      // Views report no layout events to the outside; registrations, the host layer, the keyboard
+      // and safe-area changes do.
+      const unsubscribeLayout = env.subscribeLayout(onChange);
+      const unsubscribeRegistry = env.registry.subscribe(onChange);
+      return () => {
+        unsubscribeLayout();
+        unsubscribeRegistry();
+      };
+    },
+
+    // A registered view (or a ref) that cannot be measured yet has not been laid out: nothing
+    // announces when it is, so the tour checks every frame.
+    isAwaitingLayout: (target) => typeof target !== 'string' || env.registry.targets(target).length > 0,
+
+    async scrollContainers(target): Promise<readonly ScrollContainer[]> {
+      const origin = await hostOrigin();
+      const located = origin ? await locateTarget(target, origin) : undefined;
+      if (!origin || !located) {
+        return [];
+      }
+
+      const chain = await containingScrollViews(located, located.geometries ?? (await registeredScrollViews(origin)));
+      return chain.map(({scrollView}) => scrollContainer(scrollView));
+    },
+
+    getViewport(): Viewport {
+      const size = env.getHost()?.size ?? {width: 0, height: 0};
+      return {rect: {x: 0, y: 0, width: size.width, height: size.height}, insets: env.getInsets()};
+    },
+
+    reducedMotion: env.reducedMotion,
+
+    measuresWhileScrolling: false,
+
+    getPixelRatio: env.getPixelRatio,
+  };
+}