@wireai/activation 0.1.0

package/src/coachmarks/coachmarkAnchorRegistry.ts

@@ -0,0 +1,70 @@
+import type { TargetRect } from "./types";
+
+/**
+ * Maps a coachmark anchor id → a function that measures that element's current
+ * window rect. Elements register themselves on mount (via useCoachmarkAnchor)
+ * and the tour controller resolves an id to a rect at the moment a step fires.
+ *
+ * This is the "app declares WHERE" half of the engine: the kit owns the
+ * measuring/registry mechanics, each app decides which ids exist and pins them
+ * to its own components.
+ */
+export type AnchorMeasurer = () => Promise<TargetRect | null>;
+
+const anchors = new Map<string, AnchorMeasurer>();
+
+/**
+ * NOTE: this registry is last-writer-wins — one measurer per id. An `anchorId`
+ * MUST be unique across screens that can be mounted simultaneously; if two live
+ * screens share an id, the second registration hides the first and unmount order
+ * decides who survives. Scope ids per screen (e.g. `feed.filter_icon`) when a
+ * component can appear in more than one mounted screen at once.
+ */
+export const coachmarkAnchors = {
+  register(id: string, measurer: AnchorMeasurer) {
+    anchors.set(id, measurer);
+  },
+  /**
+   * Only clears the id when `measurer` is still the current registration, so a
+   * screen unmounting after a newer screen registered the same id does not wipe
+   * the live measurer. Omit `measurer` to force-delete regardless.
+   */
+  unregister(id: string, measurer?: AnchorMeasurer) {
+    if (measurer !== undefined && anchors.get(id) !== measurer) return;
+    anchors.delete(id);
+  },
+  get(id: string): AnchorMeasurer | undefined {
+    return anchors.get(id);
+  },
+  /**
+   * Resolve an anchor to a rect, retrying briefly while the target lays out
+   * (e.g. the first feed post, or a screen just navigated to). Cancellable via
+   * `shouldCancel` so a superseded step abandons its retry loop immediately.
+   */
+  async resolve(
+    id: string,
+    {
+      retries = 6,
+      intervalMs = 120,
+      shouldCancel,
+    }: {
+      retries?: number;
+      intervalMs?: number;
+      /** Abort the retry loop early (e.g. the step was superseded). */
+      shouldCancel?: () => boolean;
+    } = {},
+  ): Promise<TargetRect | null> {
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      if (shouldCancel?.()) return null;
+      const measurer = anchors.get(id);
+      if (measurer) {
+        const rect = await measurer();
+        if (rect && rect.width > 0 && rect.height > 0) return rect;
+      }
+      if (attempt < retries) {
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+      }
+    }
+    return null;
+  },
+};

package/src/coachmarks/coachmarkOverlayStore.ts

@@ -0,0 +1,63 @@
+import { useSyncExternalStore } from "react";
+
+import { areCoachmarksEnabled } from "./runtime";
+import type { GestureKind, Placement, TargetRect } from "./types";
+
+/**
+ * A tiny module-level store for the single active coachmark overlay. The host
+ * (CoachmarkOverlayHost, mounted once by CoachmarkProvider at the app root)
+ * subscribes and renders whatever is active; the tour controller drives it
+ * imperatively via show()/hide(). No React context is needed for the overlay
+ * itself — the host reaches the root so the ring can paint above the tab bar.
+ *
+ * Only ONE overlay is ever active (steps never stack), per the engine's
+ * one-overlay-at-a-time rule.
+ */
+export interface CoachmarkOverlayState {
+  message: string;
+  targetRect: TargetRect | null;
+  gesture: GestureKind;
+  placement: Placement;
+  onEngage: () => void;
+  onDismiss: () => void;
+}
+
+let current: CoachmarkOverlayState | null = null;
+const listeners = new Set<() => void>();
+
+const emit = () => {
+  for (const listener of listeners) listener();
+};
+
+export const coachmarkOverlay = {
+  show(state: CoachmarkOverlayState) {
+    // Feature kill switch: when coachmarks are disabled, a show() request is a silent no-op —
+    // no ring paints, and because nothing shows the user can't advance/dismiss a tour, so no
+    // once-gate is ever written and re-enabling replays it. hide() still works (see below).
+    if (!areCoachmarksEnabled()) return;
+    current = state;
+    emit();
+  },
+  hide() {
+    if (current === null) return;
+    current = null;
+    emit();
+  },
+  subscribe(listener: () => void) {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  },
+  getSnapshot(): CoachmarkOverlayState | null {
+    return current;
+  },
+};
+
+/** Subscribe a component to the active overlay (or null). */
+export const useCoachmarkOverlay = (): CoachmarkOverlayState | null =>
+  useSyncExternalStore(
+    coachmarkOverlay.subscribe,
+    coachmarkOverlay.getSnapshot,
+    coachmarkOverlay.getSnapshot,
+  );

package/src/coachmarks/index.ts

@@ -0,0 +1,62 @@
+/**
+ * wireai-onboarding/coachmarks — the performance-first guided-tour engine.
+ *
+ * Subpath entry, kept OUT of the main barrel so the core kit stays dependency-
+ * free: importing this pulls in the optional peers `react-native-reanimated` and
+ * `expo-blur`. The app declares WHERE things anchor (useCoachmarkAnchor) and
+ * WHICH tour plays (useCoachmarkTour); the kit owns the animation, measuring,
+ * blur, ring, gesture hand, and one-overlay-at-a-time queue.
+ *
+ *   import {
+ *     CoachmarkProvider, useCoachmarkAnchor, useCoachmarkTour,
+ *   } from "wireai-onboarding/coachmarks";
+ */
+
+// ─── Root provider (mount once, around the NavigationContainer) ───────────────
+export { CoachmarkProvider } from "./CoachmarkProvider";
+export type { CoachmarkProviderProps } from "./CoachmarkProvider";
+
+// ─── Hooks (the declarative DX surface) ───────────────────────────────────────
+export { useCoachmarkAnchor } from "./useCoachmarkAnchor";
+export { useCoachmarkTour } from "./useCoachmarkTour";
+export type { UseCoachmarkTourOptions } from "./useCoachmarkTour";
+
+// ─── QA replay flag ───────────────────────────────────────────────────────────
+export {
+  setCoachmarkTesting,
+  isCoachmarkTesting,
+  coachmarkGateKey,
+  showcaseGateKey,
+  hasSeenGate,
+  markSeenGate,
+  setCoachmarkStorage,
+  getCoachmarkStorage,
+  setCoachmarksEnabled,
+  areCoachmarksEnabled,
+} from "./runtime";
+
+// ─── Phase-3 (AI selection) seam ──────────────────────────────────────────────
+export { selectTourSteps } from "./selectTourSteps";
+
+// ─── Primitives (compose your own overlay if the tour hook isn't enough) ──────
+export { GestureHint } from "./GestureHint";
+export type { GestureHintProps } from "./GestureHint";
+export { SpotlightOverlay } from "./SpotlightOverlay";
+export type { SpotlightOverlayProps } from "./SpotlightOverlay";
+export { CoachmarkOverlayHost } from "./CoachmarkOverlayHost";
+export type { CoachmarkOverlayHostProps } from "./CoachmarkOverlayHost";
+
+// ─── Imperative overlay store + anchor registry (advanced) ────────────────────
+export { coachmarkOverlay, useCoachmarkOverlay } from "./coachmarkOverlayStore";
+export type { CoachmarkOverlayState } from "./coachmarkOverlayStore";
+export { coachmarkAnchors } from "./coachmarkAnchorRegistry";
+export type { AnchorMeasurer } from "./coachmarkAnchorRegistry";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+export type {
+  GestureKind,
+  Placement,
+  TargetRect,
+  CoachmarkStorage,
+  CoachmarkStep,
+} from "./types";

package/src/coachmarks/runtime.ts

@@ -0,0 +1,103 @@
+/**
+ * Module-level runtime for the coachmark engine: the injected sync storage, the
+ * global `isTestingCoachmark` flag, and the seen-gate helpers built on top.
+ *
+ * WHY module singletons (not just context): the tour hooks and the anchor
+ * registry are driven imperatively from anywhere in the tree (a screen deep
+ * under the navigator), while the storage + testing flag are configured once at
+ * the root by `CoachmarkProvider`. Singletons let a hook read the gate without
+ * every call site threading the storage through props. The provider is still the
+ * single writer — it calls `setCoachmarkStorage` / `setCoachmarkTesting` on mount.
+ */
+import type { CoachmarkStorage } from "./types";
+
+let storageSingleton: CoachmarkStorage | null = null;
+let testing = false;
+// The coachmarks feature kill switch (from GET /v1/features). Default true = fail-open: with no
+// flags fetched, coachmarks behave exactly as before. CoachmarkProvider writes it from the
+// resolved flags. Disabled → the tour never ARMS and the overlay `show()` is a no-op, so nothing
+// paints and — critically — no once-gate is written, so re-enabling replays the tour correctly.
+let coachmarksEnabled = true;
+
+/**
+ * Set the coachmarks master switch (from the resolved feature flags). Default true (fail-open).
+ * Written by CoachmarkProvider; read imperatively by the tour arm + the overlay store.
+ */
+export const setCoachmarksEnabled = (value: boolean): void => {
+  coachmarksEnabled = value;
+};
+
+/** Whether the coachmarks module is enabled. False → tours/overlays are silently skipped. */
+export const areCoachmarksEnabled = (): boolean => coachmarksEnabled;
+
+/** Set (or clear) the injected sync gate storage. Called by CoachmarkProvider. */
+export const setCoachmarkStorage = (storage: CoachmarkStorage | null): void => {
+  storageSingleton = storage;
+};
+
+/** The currently-injected gate storage, or null if no provider is mounted. */
+export const getCoachmarkStorage = (): CoachmarkStorage | null => storageSingleton;
+
+/**
+ * Toggle the global QA replay flag. When true, EVERY seen-gate reads as unseen
+ * and every seen-write is suppressed, so every tour + showcase replays on each
+ * mount. The app flips ONE boolean to QA the whole coachmark surface.
+ */
+export const setCoachmarkTesting = (value: boolean): void => {
+  testing = value;
+};
+
+/** Whether replay-everything QA mode is on. */
+export const isCoachmarkTesting = (): boolean => testing;
+
+/** Gate key for a tour: `wire_coachmark_<tourId>_seen`. */
+export const coachmarkGateKey = (tourId: string): string =>
+  `wire_coachmark_${tourId}_seen`;
+
+/** Gate key for a feature showcase: `wire_showcase_<id>_seen`. */
+export const showcaseGateKey = (showcaseId: string): string =>
+  `wire_showcase_${showcaseId}_seen`;
+
+/** Marker value written for a seen gate. */
+const SEEN_VALUE = "1";
+
+/**
+ * Read a seen gate. Testing mode ALWAYS reports unseen (so everything replays).
+ * A missing storage (no provider) also reports unseen — the safe default is to
+ * show the hint rather than silently swallow it. `storageOverride` /
+ * `testingOverride` let a self-contained component (e.g. FeatureShowcase) pass
+ * its own storage without relying on the provider singleton.
+ */
+export const hasSeenGate = (
+  key: string,
+  storageOverride?: CoachmarkStorage | null,
+  testingOverride?: boolean,
+): boolean => {
+  if (testingOverride ?? testing) return false;
+  const storage = storageOverride ?? storageSingleton;
+  if (!storage) return false;
+  try {
+    return storage.getItem(key) === SEEN_VALUE;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Mark a gate seen. Suppressed in testing mode (so replay never persists) and a
+ * no-op without storage. Best-effort — a throwing adapter never breaks the tour.
+ */
+export const markSeenGate = (
+  key: string,
+  storageOverride?: CoachmarkStorage | null,
+  testingOverride?: boolean,
+): void => {
+  if (testingOverride ?? testing) return;
+  const storage = storageOverride ?? storageSingleton;
+  if (!storage) return;
+  try {
+    storage.setItem(key, SEEN_VALUE);
+  } catch {
+    // Best-effort: a failed write just means the hint may show once more.
+  }
+};

package/src/coachmarks/selectTourSteps.ts

@@ -0,0 +1,45 @@
+/**
+ * selectTourSteps — the Phase-3 (AI intent-mapping) seam, stubbed today.
+ *
+ * The app declares a full catalog of coachmarks (its "feature map"). Near-term,
+ * the whole catalog plays in its declared order. LATER, the Wire server will
+ * emit an ordered `coachmarks: string[]` id list chosen by the user's captured
+ * intent (see the package spec §1e / §5), and the app passes it straight here as
+ * `selection`. This function is the ONE place that turns a selection into the
+ * live ordered step list — so turning AI on is a drop-in with zero app changes:
+ *
+ *   // Phase 1-2 (no AI): full catalog, declared order
+ *   const steps = selectTourSteps(catalog);
+ *
+ *   // Phase 3 (AI on): server-chosen subset, server order
+ *   const steps = selectTourSteps(catalog, plan.coachmarks);
+ *
+ * Contract:
+ *  - `selection` absent → returns the catalog unchanged (identity/declared order).
+ *  - `selection` present → returns only catalog entries whose `id` appears in
+ *    `selection`, ordered by `selection` (unknown ids are skipped; duplicates in
+ *    `selection` are ignored after the first match).
+ *
+ * NOTE: routing steps through a catalog + this selector is NOT required today.
+ * Declaring an inline, static (module-level or memoized) steps array and passing
+ * it straight to `useCoachmarkTour` is a perfectly fine consumer pattern. The
+ * catalog + selection route exists to make the app AI-selection-ready — flip to
+ * server-chosen ordering later with zero app changes — not as the baseline.
+ */
+export const selectTourSteps = <T extends { id: string }>(
+  catalog: T[],
+  selection?: string[],
+): T[] => {
+  if (!selection) return catalog;
+
+  const byId = new Map(catalog.map((item) => [item.id, item]));
+  const seen = new Set<string>();
+  const ordered: T[] = [];
+  for (const id of selection) {
+    if (seen.has(id)) continue;
+    seen.add(id);
+    const item = byId.get(id);
+    if (item) ordered.push(item);
+  }
+  return ordered;
+};

package/src/coachmarks/types.ts

@@ -0,0 +1,58 @@
+/**
+ * Shared types for the coachmark / guided-tour overlay engine.
+ *
+ * Lifted from the Myelino app engine and made kit-generic: the app supplies the
+ * anchors + catalog + copy, the kit owns the animation/measure/queue mechanics.
+ * Dependency-free on purpose so the type surface can be imported anywhere.
+ */
+
+/** The animated hand/gesture shown over or beside a highlighted target. */
+export type GestureKind =
+  | "swipe_up"
+  | "swipe_down"
+  | "swipe_left"
+  | "swipe_right"
+  | "tap"
+  | "double_tap"
+  | "pinch"
+  | "zoom"
+  | "none";
+
+/** Which side of the highlighted target the tooltip pill sits on. */
+export type Placement = "top" | "bottom" | "left" | "right" | "center";
+
+/** A measured on-screen rectangle (window coordinates from measureInWindow). */
+export interface TargetRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * The host-injected gate storage. SYNCHRONOUS on purpose — a coachmark's
+ * "seen?" gate must resolve during render with no async flash (otherwise a ring
+ * momentarily paints before the read resolves and says "already seen"). MMKV's
+ * `getString`/`set` fit as-is; an in-memory `Map` wrapper works for tests. This
+ * is deliberately separate from the async `WireOnboardingStorage` used for
+ * session persistence.
+ */
+export interface CoachmarkStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+}
+
+/**
+ * One step in a guided tour. `anchorId` is looked up in the anchor registry at
+ * fire time; omit it for a centered, target-less hint (e.g. a scroll gesture).
+ * `id` doubles as the analytics name for the step.
+ */
+export interface CoachmarkStep {
+  id: string;
+  message: string;
+  gesture?: GestureKind;
+  placement?: Placement;
+  anchorId?: string;
+  /** Extra action when the step is engaged (e.g. navigate to another tab). */
+  onEngage?: () => void;
+}

package/src/coachmarks/useCoachmarkAnchor.ts

@@ -0,0 +1,49 @@
+import { useEffect, useRef } from "react";
+import type { View } from "react-native";
+
+import { coachmarkAnchors } from "./coachmarkAnchorRegistry";
+import type { TargetRect } from "./types";
+
+/**
+ * Makes any element ringable by a coachmark tour. Attach the returned ref to a
+ * plain RN View wrapping the target (use `collapsable={false}` so the native
+ * node survives for measurement):
+ *
+ *   const filterAnchor = useCoachmarkAnchor("filter_icon");
+ *   <View ref={filterAnchor} collapsable={false}>{button}</View>
+ *
+ * The app decides which ids exist and where they live; the kit measures them at
+ * step time via `measureInWindow` (never continuously). Pass `null` to keep the
+ * hook's position stable while registering nothing (e.g. a list item that is
+ * only an anchor at one index).
+ */
+export const useCoachmarkAnchor = (id: string | null | undefined) => {
+  const ref = useRef<View>(null);
+
+  useEffect(() => {
+    if (!id) return undefined;
+
+    const measure = (): Promise<TargetRect | null> =>
+      new Promise((resolve) => {
+        const node = ref.current;
+        if (!node || typeof node.measureInWindow !== "function") {
+          return resolve(null);
+        }
+        node.measureInWindow((x, y, width, height) => {
+          if (
+            [x, y, width, height].some(
+              (value) => value == null || Number.isNaN(value),
+            )
+          ) {
+            return resolve(null);
+          }
+          resolve({ x, y, width, height });
+        });
+      });
+
+    coachmarkAnchors.register(id, measure);
+    return () => coachmarkAnchors.unregister(id, measure);
+  }, [id]);
+
+  return ref;
+};

package/src/coachmarks/useCoachmarkTour.ts

@@ -0,0 +1,200 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { coachmarkAnchors } from "./coachmarkAnchorRegistry";
+import { coachmarkOverlay } from "./coachmarkOverlayStore";
+import { areCoachmarksEnabled, coachmarkGateKey, hasSeenGate, markSeenGate } from "./runtime";
+import type { CoachmarkStep } from "./types";
+
+export interface UseCoachmarkTourOptions {
+  /**
+   * Gate key for the whole tour. The kit reads/writes
+   * `wire_coachmark_<tourId>_seen` through the injected CoachmarkStorage so the
+   * app never owns the "seen" bookkeeping (the global testing flag bypasses it).
+   */
+  tourId: string;
+  /** Run at most once ever (persisted via the gate). Default true. */
+  showOnce?: boolean;
+  /**
+   * Domain gate — the tour only arms while this is true (e.g. hasPosts), and it
+   * also drives PAUSE/RESUME: if this flips false mid-tour (e.g. the user tab-
+   * switches and the screen loses focus without unmounting) the overlay is
+   * hidden but the tour's position is kept, and it resumes on the CURRENT step
+   * (re-resolving its anchor) when this returns true. See the hook JSDoc.
+   */
+  enabled: boolean;
+  /** Let passive value land before the first hint. */
+  startDelayMs?: number;
+  /** Fires once the tour finishes or is skipped (after the gate is written). */
+  onComplete?: () => void;
+  /**
+   * Fires once when a step first becomes visible. It is NOT re-fired when the
+   * SAME step resumes after a focus-loss pause (the last-shown step id is
+   * tracked in a ref and suppressed), so a tab-switch never inflates
+   * impressions. It fires again only when the tour advances to a new step.
+   */
+  onStepShown?: (id: string) => void;
+  onStepEngaged?: (id: string) => void;
+  onStepDismissed?: (id: string) => void;
+}
+
+const DEFAULT_START_DELAY_MS = 3000;
+
+/**
+ * Plays an ordered queue of coachmark steps on the current screen through the
+ * root SpotlightOverlay (mounted by CoachmarkProvider). Engaging a step (tap the
+ * ring/tooltip) advances and fires onStepEngaged. Tapping the backdrop advances
+ * to the NEXT step and fires onStepDismissed — a stray tap or a "not now" never
+ * kills the tour; only a backdrop tap on the LAST step ends it. Both terminal
+ * paths (engaging past the end, or dismissing the last step) write the seen gate
+ * once and call onComplete, so a finished tour never nags again.
+ *
+ * Gating lives IN the kit: the tour arms only when `enabled` AND (not `showOnce`
+ * OR the `tourId` gate is unseen).
+ *
+ * PAUSE/RESUME on focus loss: `enabled` is a live gate, not just an arm-once
+ * trigger. Once armed, if `enabled` goes false while the tour is in flight
+ * (started, not finished) — the classic case being a tab-switch that keeps the
+ * screen mounted — the drive effect hides the overlay so a stale rect can't
+ * float over the wrong screen, but KEEPS `activeIndex` and does NOT write the
+ * seen gate. When `enabled` returns true the effect re-runs (it's in the deps)
+ * and re-drives the SAME step, re-resolving its anchor so a moved/relaid-out
+ * target is picked up. `onStepShown` is suppressed on that resume (last-shown
+ * step id is tracked in a ref) so a pause/resume never double-counts a step.
+ *
+ * IMPORTANT: `steps` MUST be a stable (memoized) array. If a new array identity
+ * is passed on every render the drive effect re-runs and re-shows the current
+ * step (wasteful anchor re-resolves / overlay churn), and analytics can
+ * double-fire. Memoize it, or pass an inline module-level constant.
+ *
+ * Preserved engine invariants: step callbacks live in a ref (not effect deps),
+ * anchor resolution is cancellable, and finish is idempotent (only one overlay
+ * is ever active, the gate is written once).
+ */
+export const useCoachmarkTour = (
+  /** Ordered coachmark steps. MUST be stable/memoized — see the note above. */
+  steps: CoachmarkStep[],
+  {
+    tourId,
+    showOnce = true,
+    enabled,
+    startDelayMs = DEFAULT_START_DELAY_MS,
+    onComplete,
+    onStepShown,
+    onStepEngaged,
+    onStepDismissed,
+  }: UseCoachmarkTourOptions,
+) => {
+  const [activeIndex, setActiveIndex] = useState<number | null>(null);
+  const startedRef = useRef(false);
+  const finishedRef = useRef(false);
+  // Id of the step onStepShown last fired for. Lets us re-drive the current
+  // step on a focus-loss RESUME without re-firing the impression callback.
+  const lastShownStepIdRef = useRef<string | null>(null);
+
+  // Keep the latest step callbacks in a ref so parent-recreated inline callbacks
+  // don't re-trigger the drive effect (which would re-show the step and
+  // double-fire analytics). The drive effect keys only on the step, not these.
+  const callbacksRef = useRef({ onStepShown, onStepEngaged, onStepDismissed });
+  callbacksRef.current = { onStepShown, onStepEngaged, onStepDismissed };
+
+  const finish = useCallback(() => {
+    if (finishedRef.current) return;
+    finishedRef.current = true;
+    if (showOnce) markSeenGate(coachmarkGateKey(tourId));
+    coachmarkOverlay.hide();
+    setActiveIndex(null);
+    onComplete?.();
+  }, [onComplete, showOnce, tourId]);
+
+  // Arm once, after the delay, when enabled and the gate is unseen.
+  useEffect(() => {
+    if (!enabled || startedRef.current) return undefined;
+    // Feature kill switch: never arm while coachmarks are disabled, so no timer starts, no
+    // overlay shows, and the once-gate is NOT consumed — re-enabling replays the tour.
+    if (!areCoachmarksEnabled()) return undefined;
+    if (showOnce && hasSeenGate(coachmarkGateKey(tourId))) return undefined;
+    const timer = setTimeout(() => {
+      startedRef.current = true;
+      setActiveIndex(0);
+    }, startDelayMs);
+    return () => clearTimeout(timer);
+  }, [enabled, startDelayMs, showOnce, tourId]);
+
+  // Drive the active step. Keyed on `enabled` too, so a mid-tour focus loss
+  // pauses (hide, keep position) and a return to focus resumes the same step.
+  useEffect(() => {
+    if (activeIndex === null) return undefined;
+
+    // PAUSE: armed but the screen lost focus (enabled flipped false while in
+    // flight). Hide the overlay so a stale rect can't float over the wrong
+    // screen, but KEEP activeIndex and DON'T write the gate. When enabled
+    // returns true this effect re-runs and re-drives the current step below.
+    if (!enabled) {
+      if (startedRef.current && !finishedRef.current) coachmarkOverlay.hide();
+      return undefined;
+    }
+
+    if (activeIndex >= steps.length) {
+      finish();
+      return undefined;
+    }
+
+    const step = steps[activeIndex];
+    if (!step) {
+      finish();
+      return undefined;
+    }
+    let cancelled = false;
+
+    (async () => {
+      // Re-resolve the anchor every drive (incl. resume) — rects may have moved
+      // while the screen was backgrounded / relaid out.
+      const rect = step.anchorId
+        ? await coachmarkAnchors.resolve(step.anchorId, {
+            shouldCancel: () => cancelled,
+          })
+        : null;
+      if (cancelled) return;
+
+      // Fire onStepShown only when the shown step actually changes — a resume
+      // of the SAME step (post focus-loss) must not double-count the impression.
+      if (lastShownStepIdRef.current !== step.id) {
+        lastShownStepIdRef.current = step.id;
+        callbacksRef.current.onStepShown?.(step.id);
+      }
+      coachmarkOverlay.show({
+        message: step.message,
+        targetRect: rect,
+        gesture: step.gesture ?? "none",
+        placement: step.placement ?? "bottom",
+        onEngage: () => {
+          callbacksRef.current.onStepEngaged?.(step.id);
+          step.onEngage?.();
+          setActiveIndex((index) => (index ?? 0) + 1);
+        },
+        onDismiss: () => {
+          callbacksRef.current.onStepDismissed?.(step.id);
+          // Backdrop tap advances to the next step; only the LAST step's
+          // backdrop tap ends the whole tour (the gate is written once, there).
+          if (activeIndex >= steps.length - 1) {
+            finish();
+          } else {
+            setActiveIndex((index) => (index ?? 0) + 1);
+          }
+        },
+      });
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [activeIndex, steps, finish, enabled]);
+
+  // Safety: clear the overlay if the screen unmounts mid-tour.
+  useEffect(
+    () => () => {
+      if (!finishedRef.current) coachmarkOverlay.hide();
+    },
+    [],
+  );
+};