@wireai/activation 0.14.2 → 0.15.0

package/src/coachmarks/reanimated.ts

@@ -0,0 +1,342 @@
+/**
+ * reanimated — resolve `react-native-reanimated`, lazily and optionally.
+ *
+ * ── WHY THIS DOES NOT BREAK THE NO-NATIVE-DEPENDENCY POLICY ──────────────────────────────
+ *
+ * `react-native-reanimated` is an OPTIONAL peer of the coachmarks subpath. `SpotlightOverlay` and
+ * `GestureHint` animate with it WHEN it is installed, and fall back to a STATIC render of the same
+ * visual when it is not — same ring, same tooltip, same glyph, same copy, same gestures, just
+ * without motion. So a host that never installs it can still run the guided tour and the feature
+ * showcase, and an Expo Go / Lite build is not forced into a native module it cannot take.
+ *
+ * Before this file, both components did `import Animated, { … } from "react-native-reanimated"` at
+ * module scope, and `coachmarks/index.ts` re-exports them with no wildcard escape — so importing
+ * ANYTHING from `@wireai/activation/coachmarks` (even `setCoachmarkStorage`) dragged the peer in,
+ * and a host without it hit a Metro resolution failure. `@wireai/activation/showcase` inherited the
+ * same edge through `GestureHint`. This resolver removes it. Same class as the 0.14.2 `expo-blur`
+ * fix (`expoBlur.ts`), same shape, one size up.
+ *
+ * ── THE SPECIFIER MUST BE A STRING LITERAL, INSIDE A TRY/CATCH ───────────────────────────
+ *
+ * This follows `icons/expoIcons.ts` and `coachmarks/expoBlur.ts` exactly, and expoIcons' header
+ * carries the full autopsy. In short: Metro collects dependencies STATICALLY, matching a call whose
+ * callee is literally the identifier `require` and whose argument is literally a string — an
+ * aliased callee (`const req = require; req(name)`) or a variable specifier is collected NOWHERE,
+ * so the module never enters the bundle (that shape shipped broken in 0.8.0). And the call sitting
+ * inside a TRY/CATCH is literally how Metro marks the dependency `isOptional`, which is what lets
+ * an absent peer degrade instead of failing the build. Do NOT "simplify" either half away.
+ *
+ * ── WHY THE EXPORTS ARE BARE FUNCTIONS WITH THE PEER'S OWN NAMES ─────────────────────────
+ *
+ * The call sites import `useAnimatedStyle` / `useAnimatedProps` / `withTiming` … from HERE instead
+ * of from the peer, and call them unqualified, exactly as before. That is load-bearing, not style:
+ * reanimated's Babel plugin decides what to workletize by the CALLEE NAME (`react-native-worklets`
+ * `plugin/index.js` → `reanimatedFunctionHooks` / `reanimatedFunctionArgsToWorkletize`; it reads
+ * `callee.name`, or `callee.property.name` for a member call, and never checks which module the
+ * name came from). Keeping the names identical keeps every worklet in `SpotlightOverlay` and
+ * `GestureHint` workletized byte-for-byte on a host that HAS the peer. Rename them and the
+ * animations silently stop running on the UI thread.
+ *
+ * ── THE DEGRADE: THE FINAL FRAME, NOT A DEAD ONE ─────────────────────────────────────────
+ *
+ * The shim resolves every animation to its RESTING value — `withTiming(to)` is `to`,
+ * `withSequence(a, b)` is `b`, `withRepeat(x)` is `x` — so a component lands on the pose it would
+ * have settled into anyway (ring at scale 1, glyph at full opacity, blur at BLUR_INTENSITY) rather
+ * than on frame zero, which for the blur would have meant a fully transparent overlay. Shared
+ * values are state-backed so a write from an effect actually reaches the next render; reanimated's
+ * own values do not need this because they drive the UI thread directly. The kit's own
+ * AccessibilityInfo-backed `useReducedMotion` stands in for the peer's, so the reduce-motion
+ * contract in ai_rules/rules/performance.md §3 holds with or without the peer.
+ *
+ * This is also what `ai_rules/rules/frequent_rules.md` #1 prescribes: when the kit needs motion
+ * without the optional peer, it uses core React Native, never Reanimated.
+ */
+import {
+  createElement,
+  forwardRef,
+  useReducer,
+  useRef,
+  type ComponentType,
+  type ReactNode,
+} from "react";
+import { View, type ViewProps, type ViewStyle } from "react-native";
+
+import { useReducedMotion as useOsReducedMotion } from "../motion/useReducedMotion";
+
+// Metro injects a module-scoped `require`; it is ABSENT in a pure-ESM runtime (the kit's own tests
+// run under `node --test` as ESM). Declared locally so this type-checks without ambient Node types;
+// the `typeof` guard keeps the reference ESM-safe.
+declare const require: ((id: string) => unknown) | undefined;
+
+/** A `require`-like resolver. Injectable in tests; production uses the guarded literal require. */
+export type OptionalRequire = (moduleName: string) => unknown;
+
+/** A reanimated shared value, narrowed to the one member the kit uses. */
+export interface SharedValue<T> {
+  value: T;
+}
+
+/** Props `Animated.View` accepts on top of a plain View (layout-animation descriptors). */
+export interface AnimatedViewProps extends ViewProps {
+  entering?: unknown;
+  exiting?: unknown;
+  children?: ReactNode;
+}
+
+/** A component built by `createAnimatedComponent`: its own props plus reanimated's driven props. */
+export type AnimatedComponent<P> = ComponentType<P & { animatedProps?: object }>;
+
+/** The slice of reanimated the coachmark surfaces actually use. */
+export interface ReanimatedApi {
+  /** True when the real peer resolved; false when this is the static fallback. */
+  present: boolean;
+  View: ComponentType<AnimatedViewProps>;
+  createAnimatedComponent: <P extends object>(component: ComponentType<P>) => AnimatedComponent<P>;
+  useSharedValue: <T>(initial: T) => SharedValue<T>;
+  useAnimatedStyle: (factory: () => ViewStyle) => ViewStyle;
+  useAnimatedProps: <P extends object>(factory: () => P) => P;
+  useReducedMotion: () => boolean;
+  withTiming: (toValue: number, config?: object) => number;
+  withRepeat: (animation: number, count?: number, reverse?: boolean) => number;
+  withSequence: (...animations: number[]) => number;
+  withDelay: (ms: number, animation: number) => number;
+  /** The `entering` / `exiting` descriptors, or undefined when the peer is absent. */
+  fadeIn: (durationMs: number) => unknown;
+  fadeOut: (durationMs: number) => unknown;
+}
+
+/**
+ * The production resolver. The specifier is a LITERAL so Metro collects it (see the header); the
+ * `moduleName` parameter exists only to keep the `OptionalRequire` seam shape, so anything other
+ * than the one module this file owns resolves to undefined.
+ */
+const runtimeRequire: OptionalRequire = (moduleName) => {
+  if (moduleName !== "react-native-reanimated") return undefined;
+  if (typeof require !== "function") return undefined;
+  try {
+    return require("react-native-reanimated");
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * TEST-ONLY seam. `SpotlightOverlay` / `GestureHint` have frozen public props, so neither can take
+ * a `requireModule` the way `WireIcon` does — this lets a component render exercise the PRESENT
+ * path. Production never sets it; `runtimeRequire` is the only resolver.
+ */
+let testRequire: OptionalRequire | undefined;
+export const __setReanimatedRequireForTests = (fn: OptionalRequire | undefined): void => {
+  testRequire = fn;
+  cached = undefined;
+};
+
+// ── the static fallback ───────────────────────────────────────────────────────
+
+/**
+ * A shared value that re-renders its owner on write. Reanimated's own value drives the UI thread
+ * and deliberately does NOT re-render; here the render IS the only output, so a value written from
+ * an effect (`intensity.value = withTiming(26)`) has to reach it or the overlay would sit on frame
+ * zero forever — a fully transparent blur. The box identity is stable for the component's lifetime,
+ * exactly like the real one, so it stays safe in a dependency list.
+ */
+const useStaticSharedValue = <T,>(initial: T): SharedValue<T> => {
+  const [, bump] = useReducer((n: number): number => n + 1, 0);
+  const box = useRef<SharedValue<T> | null>(null);
+  if (box.current === null) {
+    let current = initial;
+    box.current = {
+      get value(): T {
+        return current;
+      },
+      set value(next: T) {
+        if (Object.is(next, current)) return;
+        current = next;
+        bump();
+      },
+    };
+  }
+  return box.current;
+};
+
+/** Run a worklet body on the JS side. It must never throw into the render — degrade, don't crash. */
+const runWorklet = <R extends object>(factory: () => R, fallback: R): R => {
+  try {
+    return factory() ?? fallback;
+  } catch {
+    return fallback;
+  }
+};
+
+/** `Animated.View` without the peer: a plain View, with the layout-animation props dropped. */
+const StaticAnimatedView = forwardRef<View, AnimatedViewProps>(function StaticAnimatedView(
+  { entering: _entering, exiting: _exiting, children, ...rest },
+  ref,
+) {
+  return createElement(View, { ...rest, ref }, children);
+});
+
+/**
+ * `createAnimatedComponent` without the peer. The wrapper MERGES `animatedProps` into the real
+ * props, because that object is the only carrier for values the worklet would have driven (the
+ * spotlight's blur `intensity`). Built once per wrapped component at the call site's `useMemo`, so
+ * the returned type identity is stable and React never remounts the subtree.
+ */
+const staticCreateAnimatedComponent = <P extends object>(
+  component: ComponentType<P>,
+): AnimatedComponent<P> =>
+  function StaticAnimatedComponent({ animatedProps, ...rest }) {
+    return createElement(component, { ...(rest as P), ...(animatedProps as object) });
+  };
+
+/**
+ * The peer-absent API. Every animation resolves to its RESTING value, so components render the
+ * frame they would have settled on. Nothing here schedules work, allocates a native module, or
+ * throws.
+ */
+const staticApi: ReanimatedApi = {
+  present: false,
+  View: StaticAnimatedView,
+  createAnimatedComponent: staticCreateAnimatedComponent,
+  useSharedValue: useStaticSharedValue,
+  useAnimatedStyle: (factory) => runWorklet(factory, {}),
+  useAnimatedProps: (factory) => runWorklet(factory, {} as never),
+  useReducedMotion: useOsReducedMotion,
+  withTiming: (toValue) => toValue,
+  withRepeat: (animation) => animation,
+  withSequence: (...animations) => animations[animations.length - 1] ?? 0,
+  withDelay: (_ms, animation) => animation,
+  fadeIn: () => undefined,
+  fadeOut: () => undefined,
+};
+
+// ── the real peer ─────────────────────────────────────────────────────────────
+
+const isFunction = (value: unknown): boolean => typeof value === "function";
+
+/** A React component is a function, or an object carrying `$$typeof` (memo / forwardRef). */
+const isComponent = (value: unknown): boolean =>
+  typeof value === "function" || (!!value && typeof value === "object" && "$$typeof" in value);
+
+/**
+ * Build the API from a resolved module namespace, or undefined when it is not the module we expect.
+ *
+ * The hooks are NAMED exports; `View` and `createAnimatedComponent` live on the DEFAULT export (the
+ * `Animated` object). A CJS interop wrapper puts everything one level down under `default`, so both
+ * are looked up on the namespace first and the default second. EVERY member is verified before the
+ * namespace is accepted: a partial module must degrade to the static fallback, never crash halfway
+ * through a render.
+ */
+const fromModule = (mod: unknown): ReanimatedApi | undefined => {
+  if (!mod || typeof mod !== "object") return undefined;
+  const ns = mod as Record<string, unknown>;
+  const def =
+    ns.default && typeof ns.default === "object"
+      ? (ns.default as Record<string, unknown>)
+      : undefined;
+  const pick = (name: string): unknown => ns[name] ?? def?.[name];
+
+  const view = def?.View ?? ns.View;
+  const createAnimated = def?.createAnimatedComponent ?? ns.createAnimatedComponent;
+  const hooks = {
+    useSharedValue: pick("useSharedValue"),
+    useAnimatedStyle: pick("useAnimatedStyle"),
+    useAnimatedProps: pick("useAnimatedProps"),
+    useReducedMotion: pick("useReducedMotion"),
+    withTiming: pick("withTiming"),
+    withRepeat: pick("withRepeat"),
+    withSequence: pick("withSequence"),
+    withDelay: pick("withDelay"),
+  };
+  const fadeIn = pick("FadeIn");
+  const fadeOut = pick("FadeOut");
+
+  if (!isComponent(view) || !isFunction(createAnimated)) return undefined;
+  if (Object.values(hooks).some((member) => !isFunction(member))) return undefined;
+  if (!fadeIn || !fadeOut) return undefined;
+
+  // The single narrowing seam. Everything above proved the members exist and are callable; the peer
+  // is untyped here (it is resolved through `unknown`), so the cast happens once, at the boundary,
+  // and the exported signatures above are the contract from here on.
+  const api = {
+    present: true,
+    View: view,
+    createAnimatedComponent: createAnimated,
+    ...hooks,
+    fadeIn: (durationMs: number) => (fadeIn as { duration: (ms: number) => unknown }).duration(durationMs),
+    fadeOut: (durationMs: number) => (fadeOut as { duration: (ms: number) => unknown }).duration(durationMs),
+  } as unknown as ReanimatedApi;
+  return api;
+};
+
+/**
+ * Module-level memo. Holds the RESOLVED api (real or static), so an absent peer costs exactly one
+ * failed require per process, not one per mount — and, more importantly, so the implementation can
+ * never change between two renders of the same component, which would break the rules of hooks.
+ */
+let cached: ReanimatedApi | undefined;
+
+/** Reset the memo. TEST-ONLY seam — production never calls it. */
+export const resetReanimatedModuleCache = (): void => {
+  cached = undefined;
+};
+
+/**
+ * Resolve the reanimated API, or the static fallback when the peer is absent/unresolvable.
+ * Never throws and never returns undefined: an absent animation library must degrade to a still
+ * frame, never break the tour.
+ */
+export const resolveReanimated = (
+  requireModule: OptionalRequire = testRequire ?? runtimeRequire,
+): ReanimatedApi => {
+  try {
+    if (cached === undefined || requireModule !== runtimeRequire) {
+      const resolved = fromModule(requireModule("react-native-reanimated")) ?? staticApi;
+      // Don't poison the module memo from an injected test require.
+      if (requireModule === runtimeRequire) cached = resolved;
+      return resolved;
+    }
+    return cached;
+  } catch {
+    return staticApi;
+  }
+};
+
+// ── the call-site surface: the peer's own names, resolved lazily ──────────────
+//
+// Each one delegates on every call, so nothing is resolved at import time. `api()` is memoized, so
+// the delegation is a property read.
+
+const api = (): ReanimatedApi => resolveReanimated();
+
+/**
+ * The `Animated` namespace, with `View` behind a getter so merely importing this module never
+ * touches the peer. The component identity it returns is stable (the peer's own `Animated.View`, or
+ * the module-level `StaticAnimatedView`), so React never remounts the tree under it.
+ */
+export const Animated: {
+  readonly View: ComponentType<AnimatedViewProps>;
+  createAnimatedComponent: <P extends object>(component: ComponentType<P>) => AnimatedComponent<P>;
+} = {
+  get View() {
+    return api().View;
+  },
+  createAnimatedComponent: (component) => api().createAnimatedComponent(component),
+};
+
+/** Layout-animation descriptors. `.duration()` is the only builder the kit uses. */
+export const FadeIn = { duration: (durationMs: number): unknown => api().fadeIn(durationMs) };
+export const FadeOut = { duration: (durationMs: number): unknown => api().fadeOut(durationMs) };
+
+export const useSharedValue = <T,>(initial: T): SharedValue<T> => api().useSharedValue(initial);
+export const useAnimatedStyle = (factory: () => ViewStyle): ViewStyle =>
+  api().useAnimatedStyle(factory);
+export const useAnimatedProps = <P extends object>(factory: () => P): P =>
+  api().useAnimatedProps(factory);
+export const useReducedMotion = (): boolean => api().useReducedMotion();
+export const withTiming = (toValue: number, config?: object): number =>
+  api().withTiming(toValue, config);
+export const withRepeat = (animation: number, count?: number, reverse?: boolean): number =>
+  api().withRepeat(animation, count, reverse);
+export const withSequence = (...animations: number[]): number => api().withSequence(...animations);
+export const withDelay = (ms: number, animation: number): number => api().withDelay(ms, animation);

package/src/coachmarks/runtime.ts

@@ -27,6 +27,9 @@
  */
 import type { CoachmarkStorage } from "./types";
 
+/** RN sets this global; absent under node/SSR. Read defensively via the async-adapter warn below. */
+declare const __DEV__: boolean | undefined;
+
 /**
  * Well-known key into the runtime-global symbol registry — one coachmark runtime across bundles.
  *
@@ -166,6 +169,104 @@ export const showcaseGateKey = (showcaseId: string): string =>
 /** Marker value written for a seen gate. */
 const SEEN_VALUE = "1";
 
+/** Key used only by the one-off synchronicity probe below. Never carries a meaningful value. */
+const GATE_PROBE_KEY = "wire_gate_probe";
+
+/** Once-per-process latch on its own `Symbol.for` slot, mirroring `gateStorageWarned` next door
+ *  in reviews/runtime: a plain `let` would warn once per inlined bundle copy, and the gates live
+ *  in three of them.
+ *
+ *  @globalSlot LATCH — written `true` by the first probe that caught an ASYNC gate adapter, and
+ *  never again. A second differing write re-arms a warning the process already spent, so a host
+ *  whose broken adapter reaches three gates gets the same paragraph three times and stops reading. */
+const ASYNC_GATE_STORAGE_WARNED_SLOT: unique symbol = Symbol.for(
+  "@wireai/activation:asyncGateStorageWarned",
+);
+
+type GlobalWithAsyncGateWarn = typeof globalThis & {
+  [ASYNC_GATE_STORAGE_WARNED_SLOT]?: boolean;
+};
+
+const asyncGateWarnGlobal = globalThis as GlobalWithAsyncGateWarn;
+
+/**
+ * The substitute for an adapter whose `getItem` returned a thenable (an ASYNC adapter, e.g.
+ * AsyncStorage handed straight in). Every seen-gate reads SEEN and every write is dropped, so
+ * nothing shows and nothing fires — FAIL CLOSED, deliberately in both directions the async bug
+ * could err: a Promise is never `=== "1"`, so a raw async adapter reports every gate UNSEEN
+ * forever — tours and showcases replay on every open, and a review gate with `minSessions` 0/1
+ * RE-FIRES its prompt each open (the 2026-07-16 one-star incident class). Never-fire is the only
+ * direction a once-per-user gate may err in.
+ */
+const closedGateStorage: CoachmarkStorage = Object.freeze({
+  getItem: (): string => SEEN_VALUE,
+  setItem: (): void => {},
+});
+
+/** Adapters probed sync (or throwing, which every reader already tolerates): pass through. */
+const syncGateAdapters = new WeakSet<CoachmarkStorage>();
+/** Adapters caught returning a thenable: substituted, and never probed again. */
+const asyncGateAdapters = new WeakSet<CoachmarkStorage>();
+
+/** Warn once, in dev builds only, when a gate adapter turned out to be async. */
+const warnAsyncGateStorage = (): void => {
+  if (asyncGateWarnGlobal[ASYNC_GATE_STORAGE_WARNED_SLOT]) return;
+  if (typeof __DEV__ === "undefined" || !__DEV__) return;
+  if (typeof console === "undefined" || !console.warn) return;
+  asyncGateWarnGlobal[ASYNC_GATE_STORAGE_WARNED_SLOT] = true;
+  console.warn(
+    "[wireai] the gate storage's getItem returned a Promise — an async adapter (e.g. AsyncStorage) " +
+      "cannot drive the once-per-user gates, so coachmark tours, showcases and the review/questionnaire " +
+      "gates are all DISABLED (fail closed: nothing shows, nothing fires) until a synchronous adapter " +
+      "is provided. Pass a sync adapter (e.g. MMKV: `{ getItem: (k) => mmkv.getString(k) ?? null, " +
+      "setItem: (k, v) => mmkv.set(k, v) }`) to CoachmarkProvider or the gate's `storage` prop.",
+  );
+};
+
+/** Test-only: forget the once-per-process async-adapter warn latch. */
+export const resetAsyncGateStorageWarning = (): void => {
+  asyncGateWarnGlobal[ASYNC_GATE_STORAGE_WARNED_SLOT] = undefined;
+};
+
+/**
+ * The thenable probe (fail closed): resolve an adapter to itself when its `getItem` is
+ * synchronous, and to `closedGateStorage` when it returns a thenable. Called on every gate READ
+ * rather than at injection, so (a) a host handing storage straight to a gate's `storage` prop is
+ * probed too, and (b) `CoachmarkProvider`'s unmount cleanup — which compares the singleton to its
+ * own prop by IDENTITY — keeps seeing the object the host passed. Verdicts are WeakSet-cached, so
+ * each adapter pays for exactly one probe read.
+ */
+export const validateGateStorage = (
+  storage: CoachmarkStorage | null,
+): CoachmarkStorage | null => {
+  if (!storage) return null;
+  if (syncGateAdapters.has(storage)) return storage;
+  if (asyncGateAdapters.has(storage)) return closedGateStorage;
+  let probed: unknown;
+  try {
+    probed = storage.getItem(GATE_PROBE_KEY);
+  } catch {
+    // A throwing adapter is synchronous, which is all the probe rules on; every reader already
+    // tolerates the throw itself.
+    syncGateAdapters.add(storage);
+    return storage;
+  }
+  if (probed != null && typeof (probed as { then?: unknown }).then === "function") {
+    asyncGateAdapters.add(storage);
+    try {
+      // Detach the probe's promise so an adapter that REJECTS (e.g. a broken native store) cannot
+      // surface as an unhandled rejection the host never scheduled.
+      (probed as PromiseLike<unknown>).then(undefined, () => {});
+    } catch {
+      // A hostile thenable whose `then` throws is still async; the verdict stands.
+    }
+    warnAsyncGateStorage();
+    return closedGateStorage;
+  }
+  syncGateAdapters.add(storage);
+  return storage;
+};
+
 /**
  * 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
@@ -179,7 +280,7 @@ export const hasSeenGate = (
   testingOverride?: boolean,
 ): boolean => {
   if (testingOverride ?? isCoachmarkTesting()) return false;
-  const storage = storageOverride ?? getCoachmarkStorage();
+  const storage = validateGateStorage(storageOverride ?? getCoachmarkStorage());
   if (!storage) return false;
   try {
     return storage.getItem(key) === SEEN_VALUE;
@@ -198,7 +299,7 @@ export const markSeenGate = (
   testingOverride?: boolean,
 ): void => {
   if (testingOverride ?? isCoachmarkTesting()) return;
-  const storage = storageOverride ?? getCoachmarkStorage();
+  const storage = validateGateStorage(storageOverride ?? getCoachmarkStorage());
   if (!storage) return;
   try {
     storage.setItem(key, SEEN_VALUE);

package/src/coachmarks/types.ts

@@ -31,8 +31,13 @@ export interface TargetRect {
 
 /**
  * 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
+ * "seen?" gate must resolve during render. This is ENFORCED, fail closed: a
+ * probe on first read catches an adapter whose `getItem` returns a thenable
+ * (AsyncStorage handed straight in) and substitutes a closed adapter — every
+ * gate reads "seen", nothing shows, nothing fires, one dev warning names the
+ * fix (see `validateGateStorage` in ./runtime). A raw async adapter would
+ * otherwise report every gate unseen forever: tours replay each open, and a
+ * review gate with `minSessions` 0/1 re-fires each open. 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.

package/src/context/deviceId.ts

@@ -291,3 +291,35 @@ export const resetAutoDeviceKeys = (): void => {
   registry.hydrating.clear();
   registry.pending?.clear();
 };
+
+/**
+ * The auto `device_key` a surface with NO `appId` and NO `storage` of its own may stamp onto a
+ * payload — the review gate being the one that exists (`ReviewGate` takes neither prop).
+ *
+ * WHY IT IS NOT JUST `resolveAutoDeviceKey()`. That function is keyed by `appId`, and `appId` is a
+ * REQUIRED field on `WireOnboardingConfig` that real hosts set to a real value. A propless caller
+ * can only pass `undefined`, which addresses the `"default"` slot — so on any host that names its
+ * app, a bare call would MINT a second id beside the one every other surface already shares. That is
+ * the halved-counter defect this registry exists to close (see the registry note above), arrived at
+ * from the other direction.
+ *
+ * So this READS and does not address:
+ *   • exactly one id space in the process → that id, whoever registered it. This is every
+ *     single-tenant app, i.e. every real app, and it is how the gate joins the analytics surfaces.
+ *   • none at all → mint one through {@link resolveAutoDeviceKey}. Nothing exists to collide with,
+ *     so `"default"` is not a second space, it is the first. PROCESS-scoped (there is no storage to
+ *     persist through), which is honest and still resolvable: a review row is written once per user,
+ *     so a per-launch value here cannot corrupt a counter the way it corrupts `min_sessions`.
+ *   • two or more → `undefined`. Two tenants in one process must never share an id, and a caller
+ *     with no `appId` cannot say which one it belongs to. Refusing is the only safe answer;
+ *     guessing would stamp one tenant's device onto the other's row.
+ *
+ * Never throws, never mints a SECOND id, and never overrides anything a host supplied — the caller
+ * checks for a host value first.
+ */
+export const ambientAutoDeviceKey = (): string | undefined => {
+  const registry = autoDeviceKeyRegistry();
+  if (registry.keys.size === 0) return resolveAutoDeviceKey();
+  if (registry.keys.size > 1) return undefined;
+  return [...registry.keys.values()][0];
+};