@wireai/activation 0.1.0

package/src/reviews/ReviewGate.tsx

@@ -0,0 +1,316 @@
+/**
+ * ReviewGate — the in-app review sentiment gate UI.
+ *
+ * A NEUTRAL prompt ("Enjoying <app>?") over five tappable stars. The honest split:
+ *   • 5 stars → the native store review (expo-store-review when available, else the
+ *     configured store URL). Fires `store_review_requested`.
+ *   • 1-4 stars → a feather-light feedback form: TWO optional inputs, the "why this
+ *     rating" opinion box (~4 lines) and a smaller "what can you suggest" box, POSTed
+ *     to the Wire server (`feedback_text` + `suggestion`). The rating is the only
+ *     mandatory action, so Send works with either box, both, or neither. Warm
+ *     thank-you state, never a dead end.
+ *
+ * The form NEVER asks for identity (no name / email / contact field): the host already
+ * identifies the user via `sessionId` + `meta` (e.g. user_id, device_key), which is all
+ * the POST body carries alongside the rating and the free text.
+ *
+ * Every visual value comes from the OnboardingTheme (useOnboardingTheme). Analytics are
+ * callback-based (mirroring the coachmark convention): the host wires `onEvent` to its own
+ * analytics. No PII in events — feedback text goes ONLY in the POST body.
+ *
+ * Store-policy: `requestReview` is quota'd and never guaranteed to show; it is called ONLY
+ * on the 5-star path, never from a "rate us 5 stars" button. See the README notes.
+ */
+import React, { useCallback, useMemo, useState } from "react";
+import { Pressable, StyleSheet, Text, TextInput, View } from "react-native";
+
+import { Button } from "../components/Button";
+import { useOnboardingTheme } from "../theme/ThemeContext";
+import type { OnboardingTheme } from "../theme/types";
+import { bodyStyle, captionStyle, headingStyle } from "../theme/typography";
+import { buildReviewSubmission, routeRating } from "./decision";
+import { feedbackInputHeights } from "./feedbackForm";
+import { resolvePresentation } from "./presentation";
+import { ReviewModal, type ReviewModalHandle } from "./ReviewModal";
+import { requestStoreReview } from "./storeReview";
+import { submitReview } from "./transport";
+import type { ReviewGateProps } from "./types";
+
+const mergeThemeOver = (
+  base: OnboardingTheme,
+  override?: Partial<OnboardingTheme>,
+): OnboardingTheme => {
+  if (!override) return base;
+  return {
+    colors: { ...base.colors, ...override.colors },
+    fonts: { ...base.fonts, ...override.fonts },
+    radius: { ...base.radius, ...override.radius },
+    spacing: { ...base.spacing, ...override.spacing },
+    button: { ...base.button, ...override.button },
+  };
+};
+
+type Phase = "rating" | "feedback" | "thanks";
+
+export const ReviewGate: React.FC<ReviewGateProps> = ({
+  appName,
+  store,
+  target,
+  sessionId,
+  meta,
+  onEvent,
+  onResolved,
+  onShown,
+  theme: themeOverride,
+  dismissible = true,
+  presentation,
+  id = "default",
+}) => {
+  const active = useOnboardingTheme();
+  const t = useMemo(() => mergeThemeOver(active, themeOverride), [active, themeOverride]);
+  const mode = resolvePresentation(presentation);
+  const modalRef = React.useRef<ReviewModalHandle>(null);
+
+  const [phase, setPhase] = useState<Phase>("rating");
+  const [stars, setStars] = useState(0);
+  const [hovered, setHovered] = useState(0);
+  const [feedback, setFeedback] = useState("");
+  const [suggestion, setSuggestion] = useState("");
+
+  // Fire review_prompt_shown exactly ONCE per mount. The callbacks are read through
+  // refs (not effect deps) so an inline `onShown`/`onEvent` — recreated every render,
+  // as real hosts idiomatically pass — never re-runs the effect. Empty deps + the
+  // shownRef guard make this a true fire-once, immune to prop-identity churn.
+  const shownRef = React.useRef(false);
+  const onShownRef = React.useRef(onShown);
+  const onEventRef = React.useRef(onEvent);
+  onShownRef.current = onShown;
+  onEventRef.current = onEvent;
+  React.useEffect(() => {
+    if (shownRef.current) return;
+    shownRef.current = true;
+    onShownRef.current?.();
+    onEventRef.current?.({ name: "review_prompt_shown", id });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const resolve = useCallback(() => {
+    onResolved?.();
+  }, [onResolved]);
+
+  const pickRating = useCallback(
+    async (value: number) => {
+      setStars(value);
+      onEvent?.({ name: "review_rating_selected", id, stars: value });
+      if (routeRating(value) === "store") {
+        onEvent?.({ name: "store_review_requested", id, stars: value });
+        await requestStoreReview(store);
+        setPhase("thanks");
+        resolve();
+      } else {
+        setPhase("feedback");
+      }
+    },
+    [onEvent, id, store, resolve],
+  );
+
+  const sendFeedback = useCallback(() => {
+    // Identity is NEVER collected here — the host already sends user_id / device /
+    // session via `sessionId` + `meta`. We POST only the rating + the free text.
+    const body = buildReviewSubmission({
+      stars,
+      feedbackText: feedback,
+      suggestion,
+      sessionId,
+      meta,
+    });
+    submitReview(target, body);
+    onEvent?.({ name: "review_feedback_submitted", id, stars });
+    setPhase("thanks");
+    resolve();
+  }, [stars, feedback, suggestion, sessionId, meta, target, onEvent, id, resolve]);
+
+  const dismiss = useCallback(() => {
+    setPhase("thanks");
+    resolve();
+  }, [resolve]);
+
+  // The in-card "Not now"/"Skip" link. In modal mode it plays the popup's exit animation
+  // (which resolves on completion, the same path a backdrop tap takes); inline keeps the
+  // legacy behavior of swapping to the thank-you in place.
+  const handleDismissTap = useCallback(() => {
+    if (mode === "modal") modalRef.current?.close();
+    else dismiss();
+  }, [mode, dismiss]);
+
+  const title =
+    phase === "feedback"
+      ? "What should we improve?"
+      : phase === "thanks"
+        ? "Thank you"
+        : appName
+          ? `Enjoying ${appName}?`
+          : "How's your experience?";
+
+  const surface = {
+    backgroundColor: t.colors.surface,
+    borderRadius: t.radius.lg,
+    padding: t.spacing.lg,
+    gap: t.spacing.md,
+  } as const;
+
+  // A multiline box ~4 lines tall (capped at ~5), derived from the theme's body
+  // line-height so it scales with the app's font config. The field's own vertical
+  // padding is folded in so the requested lines are visible inside the padding.
+  const feedbackBox = feedbackInputHeights(t.fonts, t.spacing.md);
+
+  // The phase content, shared by both presentations. In "modal" mode ReviewModal supplies
+  // the centered, dimmed, animated card surface; in "inline" mode the bare card below does.
+  const content = (
+    <>
+      <Text style={[headingStyle(t.fonts), { color: t.colors.text }]}>{title}</Text>
+
+      {phase === "rating" && (
+        <>
+          <Text style={[captionStyle(t.fonts), { color: t.colors.textMuted }]}>
+            Tap a star to let us know.
+          </Text>
+          <View style={styles.stars}>
+            {[1, 2, 3, 4, 5].map((n) => {
+              const filled = n <= (hovered || stars);
+              return (
+                <Pressable
+                  key={n}
+                  onPressIn={() => setHovered(n)}
+                  onPressOut={() => setHovered(0)}
+                  onPress={() => void pickRating(n)}
+                  accessibilityRole="button"
+                  accessibilityLabel={`${n} star${n > 1 ? "s" : ""}`}
+                  hitSlop={8}
+                >
+                  <Text
+                    style={[
+                      styles.star,
+                      { color: filled ? t.colors.primary : t.colors.border },
+                    ]}
+                  >
+                    {filled ? "★" : "☆"}
+                  </Text>
+                </Pressable>
+              );
+            })}
+          </View>
+          {dismissible && (
+            <Pressable onPress={handleDismissTap} hitSlop={8}>
+              <Text style={[captionStyle(t.fonts), styles.link, { color: t.colors.textMuted }]}>
+                Not now
+              </Text>
+            </Pressable>
+          )}
+        </>
+      )}
+
+      {phase === "feedback" && (
+        <>
+          <Text style={[captionStyle(t.fonts), { color: t.colors.textMuted }]}>
+            A few words is plenty. Both boxes are optional, so send whatever you like.
+          </Text>
+          {/* Two OPTIONAL inputs. No name / email / contact field: the host already
+              identifies the user via sessionId + meta, so we never ask for identity
+              here. Send stays enabled whether the user fills one box, both, or neither
+              (the rating is the only mandatory action). */}
+          <Text style={[captionStyle(t.fonts), { color: t.colors.textMuted }]}>
+            Why this rating? (optional)
+          </Text>
+          <TextInput
+            value={feedback}
+            onChangeText={setFeedback}
+            placeholder="e.g. too many steps"
+            placeholderTextColor={t.colors.textMuted}
+            multiline
+            textAlignVertical="top"
+            style={[
+              bodyStyle(t.fonts),
+              styles.input,
+              {
+                color: t.colors.text,
+                backgroundColor: t.colors.background,
+                borderRadius: t.radius.md,
+                borderColor: t.colors.border,
+                padding: t.spacing.md,
+                minHeight: feedbackBox.minHeight,
+                maxHeight: feedbackBox.maxHeight,
+              },
+            ]}
+          />
+          <Text style={[captionStyle(t.fonts), { color: t.colors.textMuted }]}>
+            What can we do better? (optional)
+          </Text>
+          <TextInput
+            value={suggestion}
+            onChangeText={setSuggestion}
+            placeholder="e.g. save my place between steps"
+            placeholderTextColor={t.colors.textMuted}
+            style={[
+              bodyStyle(t.fonts),
+              styles.input,
+              {
+                color: t.colors.text,
+                backgroundColor: t.colors.background,
+                borderRadius: t.radius.md,
+                borderColor: t.colors.border,
+                paddingHorizontal: t.spacing.md,
+                paddingVertical: t.spacing.sm,
+                minHeight: t.button.height,
+              },
+            ]}
+          />
+          <Button
+            title="Send feedback"
+            onPress={sendFeedback}
+            variant="primary"
+            fullWidth
+          />
+          {dismissible && (
+            <Pressable onPress={handleDismissTap} hitSlop={8}>
+              <Text style={[captionStyle(t.fonts), styles.link, { color: t.colors.textMuted }]}>
+                Skip
+              </Text>
+            </Pressable>
+          )}
+        </>
+      )}
+
+      {phase === "thanks" && (
+        <Text style={[bodyStyle(t.fonts), { color: t.colors.textMuted }]}>
+          We appreciate you. This helps us make it better.
+        </Text>
+      )}
+    </>
+  );
+
+  // Default: a centered popup over a dimmed backdrop with a spring/fade entrance. A backdrop
+  // tap (or Android back) resolves via the same path onResolved already tracks.
+  if (mode === "modal") {
+    return (
+      <ReviewModal ref={modalRef} theme={t} dismissible={dismissible} onDismiss={resolve}>
+        {content}
+      </ReviewModal>
+    );
+  }
+
+  // Legacy: the bare card, positioned by wherever the host mounts it.
+  return <View style={[styles.card, surface]}>{content}</View>;
+};
+
+ReviewGate.displayName = "ReviewGate";
+
+const styles = StyleSheet.create({
+  card: { width: "100%" },
+  stars: { flexDirection: "row", justifyContent: "center", gap: 8 },
+  star: { fontSize: 40, lineHeight: 46 },
+  input: { borderWidth: 1 },
+  link: { textAlign: "center", textDecorationLine: "underline" },
+});
+
+export default ReviewGate;

package/src/reviews/ReviewModal.tsx

@@ -0,0 +1,13 @@
+/**
+ * ReviewModal - back-compat re-export of the shared CenteredModal shell.
+ *
+ * The centered-popup presentation was extracted, unchanged, to `components/CenteredModal` so the
+ * questionnaire module can reuse the same shell without importing reviews/. This file keeps the
+ * reviews public API (`ReviewModal`, `ReviewModalHandle`, `ReviewModalProps`) pointing at the
+ * exact same runtime object, so the reviews canary and every existing import stay valid.
+ */
+export { CenteredModal as ReviewModal, default } from "../components/CenteredModal";
+export type {
+  CenteredModalHandle as ReviewModalHandle,
+  CenteredModalProps as ReviewModalProps,
+} from "../components/CenteredModal";

package/src/reviews/decision.ts

@@ -0,0 +1,120 @@
+/**
+ * decision.ts — the pure decision logic for the review gate.
+ *
+ * `decideReview` is the AI seam, mirroring `selectTourSteps` exactly: ONE function that
+ * turns an optional injected decision into the live verdict. No injected decision → the
+ * local rules stand; a server decision present → it OVERRIDES them. Building the seam now
+ * is the whole cost of being AI-ready: today the host passes local rules only; later the
+ * Wire server computes `{fire, reason}` from the onboarding learnings and the host passes
+ * it straight in — zero app changes.
+ *
+ *   // v1 (local rules only)
+ *   const verdict = decideReview(evaluateGate(rules, signals));
+ *
+ *   // AI on (server-provided decision wins)
+ *   const verdict = decideReview(evaluateGate(rules, signals), serverDecision);
+ *
+ * `evaluateGate`, `routeRating`, and `buildReviewSubmission` are pure so the gate logic
+ * is verifiable in isolation (the kit has no test runner; correctness lives in these).
+ */
+import type {
+  RatingRoute,
+  ReviewDecision,
+  ReviewSubmission,
+} from "./types";
+
+/**
+ * The seam. `decision` absent → the local verdict stands; present → it overrides.
+ * Same contract philosophy as `selectTourSteps(catalog, selection?)`.
+ */
+export const decideReview = (
+  local: ReviewDecision,
+  decision?: ReviewDecision,
+): ReviewDecision => decision ?? local;
+
+/** The signals the local rules evaluate against (read from injected sync storage + host). */
+export interface GateSignals {
+  /** Sessions observed on this device (incl. the current one). */
+  sessions: number;
+  /** Tracked app events observed (host-owned). */
+  events: number;
+  /** Epoch ms of the last time the gate was shown, or null if never. */
+  lastShownAt: number | null;
+  /** Whether the once-per-version gate is already satisfied. */
+  seen: boolean;
+  /** Current epoch ms (injected so the function stays pure). */
+  now: number;
+}
+
+/** The resolved local rules (defaults applied). */
+export interface GateRules {
+  enabled: boolean;
+  minSessions: number;
+  minEvents: number;
+  cooldownDays: number;
+  oncePerVersion: boolean;
+}
+
+/** Fill a partial `ReviewConfig` with the rule defaults. */
+export const resolveRules = (config: {
+  enabled?: boolean;
+  minSessions?: number;
+  minEvents?: number;
+  cooldownDays?: number;
+  oncePerVersion?: boolean;
+}): GateRules => ({
+  enabled: config.enabled ?? true,
+  minSessions: config.minSessions ?? 0,
+  minEvents: config.minEvents ?? 0,
+  cooldownDays: config.cooldownDays ?? 0,
+  oncePerVersion: config.oncePerVersion ?? true,
+});
+
+const MS_PER_DAY = 86_400_000;
+
+/**
+ * Deterministic v1 local decision. Order: disabled → once-gate → min-sessions →
+ * min-events → cooldown → fire. Reasons mirror the server evaluator's vocabulary.
+ */
+export const evaluateGate = (rules: GateRules, s: GateSignals): ReviewDecision => {
+  if (!rules.enabled) return { fire: false, reason: "disabled" };
+  if (rules.oncePerVersion && s.seen) return { fire: false, reason: "already_shown" };
+  if (s.sessions < rules.minSessions) return { fire: false, reason: "min_sessions" };
+  if (s.events < rules.minEvents) return { fire: false, reason: "min_events" };
+  if (rules.cooldownDays > 0 && s.lastShownAt != null) {
+    const elapsedDays = (s.now - s.lastShownAt) / MS_PER_DAY;
+    if (elapsedDays < rules.cooldownDays) return { fire: false, reason: "cooldown" };
+  }
+  return { fire: true, reason: "local_rules_met" };
+};
+
+/**
+ * Route a rating. 5 stars → the native store review; 1-4 → the feedback form. The
+ * sentiment question itself is neutral — this is the ONLY place 5 is treated specially,
+ * never a button labeled "rate us 5 stars" (see the store-policy notes in the README).
+ */
+export const routeRating = (stars: number): RatingRoute =>
+  stars >= 5 ? "store" : "feedback";
+
+/** Build the `POST /v1/reviews` body. Feedback text/contact belong ONLY here, never in events. */
+export const buildReviewSubmission = (input: {
+  stars: number;
+  feedbackText?: string;
+  suggestion?: string;
+  contact?: string;
+  sessionId?: string;
+  source?: string;
+  meta?: Record<string, unknown>;
+}): ReviewSubmission => {
+  const body: ReviewSubmission = { stars: input.stars };
+  const text = input.feedbackText?.trim();
+  if (text) body.feedback_text = text;
+  const suggestion = input.suggestion?.trim();
+  if (suggestion) body.suggestion = suggestion;
+  const contact = input.contact?.trim();
+  if (contact) body.contact = contact;
+  if (input.sessionId) body.session_id = input.sessionId;
+  if (input.source) body.source = input.source;
+  if (input.meta && Object.keys(input.meta).length > 0) body.meta = input.meta;
+  return body;
+};

package/src/reviews/equality.ts

@@ -0,0 +1,54 @@
+/**
+ * equality.ts — tiny, dependency-free value-equality helpers used to STABILIZE
+ * references across renders.
+ *
+ * WHY this exists: real integrators pass inline objects — `config={{ id: 'x' }}`,
+ * `decision={{ fire: true }}` — whose IDENTITY changes every render even though
+ * their VALUES do not. If the review hook let those unstable references flow into
+ * a `useMemo`/`useEffect` dependency list (or handed a fresh verdict object back
+ * every render), a host that depends on the returned value would re-run its own
+ * effect forever → "Maximum update depth exceeded". A library must tolerate inline
+ * props without looping; these helpers are how the hook holds a stable reference
+ * whenever the underlying values are unchanged.
+ *
+ * Pure (no React import) so it runs under the kit's node:test runner.
+ */
+import type { ReviewDecision } from "./types";
+
+/**
+ * One-level value-equality of two plain objects (or primitives). Same-reference is
+ * equal; two objects are equal when they have the same keys and each value is
+ * `Object.is`-equal. Good enough for the flat `config` / `decision` shapes the gate
+ * accepts (all leaf values are primitives).
+ */
+export const shallowEqual = (a: unknown, b: unknown): boolean => {
+  if (Object.is(a, b)) return true;
+  if (
+    a == null ||
+    b == null ||
+    typeof a !== "object" ||
+    typeof b !== "object"
+  ) {
+    return false;
+  }
+  const ak = Object.keys(a as Record<string, unknown>);
+  const bk = Object.keys(b as Record<string, unknown>);
+  if (ak.length !== bk.length) return false;
+  for (const k of ak) {
+    if (!Object.is((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k])) {
+      return false;
+    }
+  }
+  return true;
+};
+
+/**
+ * Structural equality of two review verdicts by their contract fields (`fire`,
+ * `reason`). A `null`/`undefined` verdict equals only another absent one. Used to
+ * decide whether the hook can keep returning the SAME verdict object (so a host
+ * that lists `controller.decision` in an effect dep array never loops).
+ */
+export const sameDecision = (a?: ReviewDecision | null, b?: ReviewDecision | null): boolean => {
+  if (a == null || b == null) return a == b;
+  return a.fire === b.fire && a.reason === b.reason;
+};

package/src/reviews/expo-store-review.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Ambient type for the OPTIONAL peer `expo-store-review`.
+ *
+ * The reviews module never hard-depends on it: it is loaded lazily via a guarded
+ * dynamic import and externalized from the build, so the core kit installs nothing.
+ * This declaration lets the module typecheck whether or not the host has the package
+ * installed. When the host does install it, Metro/the bundler resolves the real module
+ * at runtime; when it doesn't, the guarded import rejects and the kit falls back to
+ * opening the configured store URLs.
+ */
+declare module "expo-store-review" {
+  /** Whether the native in-app review dialog can be requested on this device. */
+  export function isAvailableAsync(): Promise<boolean>;
+  /** Ask the OS to show its native in-app review prompt (quota'd, never guaranteed). */
+  export function requestReview(): Promise<void>;
+}

package/src/reviews/feedbackForm.ts

@@ -0,0 +1,41 @@
+/**
+ * feedbackForm — pure sizing helpers for the 1–4★ feedback form, kept out of the
+ * React component so the "≈4 lines tall, capped at 5" rule is verifiable in
+ * isolation (the reviews module's correctness lives in these pure functions, the
+ * same convention as `decision.ts` / `presentation.ts`).
+ *
+ * Malik's ask: the feedback field should be a multiline box "around 3 to 5 lines"
+ * tall, not a single-line input. We size it from the theme's body line-height so
+ * it scales with the app's font config.
+ */
+import type { OnboardingFonts } from "../theme/types";
+import { bodyStyle } from "../theme/typography";
+
+/** Lines the box shows at rest, and the cap it can grow to. */
+export const FEEDBACK_MIN_LINES = 4;
+export const FEEDBACK_MAX_LINES = 5;
+
+export interface FeedbackInputHeights {
+  /** Resting height — the box opens at ~4 lines so it reads as "write a few words". */
+  minHeight: number;
+  /** Growth cap — it never balloons past ~5 lines; scroll takes over beyond that. */
+  maxHeight: number;
+}
+
+/**
+ * Derive the multiline feedback box's min/max height from the theme's body
+ * line-height. `minHeight = MIN_LINES × lineHeight`, capped at
+ * `MAX_LINES × lineHeight`, plus the field's vertical padding (top + bottom) so
+ * the requested number of text lines is actually visible inside the padding.
+ */
+export const feedbackInputHeights = (
+  fonts: OnboardingFonts,
+  verticalPadding = 0,
+): FeedbackInputHeights => {
+  const lineHeight = bodyStyle(fonts).lineHeight ?? Math.round(fonts.baseSize * fonts.scale * 1.5);
+  const pad = verticalPadding * 2;
+  return {
+    minHeight: lineHeight * FEEDBACK_MIN_LINES + pad,
+    maxHeight: lineHeight * FEEDBACK_MAX_LINES + pad,
+  };
+};

package/src/reviews/index.ts

@@ -0,0 +1,78 @@
+/**
+ * wireai-onboarding/reviews — the in-app review sentiment gate.
+ *
+ * Subpath entry, kept OUT of the main barrel so the core kit stays dependency-free:
+ * importing this pulls in the OPTIONAL peer `expo-store-review` (loaded lazily and only on
+ * the 5-star path). The gate asks a neutral question, routes 5 stars to the native store
+ * review and 1-4 to a feather-light feedback form POSTed to the Wire server, and decides
+ * WHEN to show via local rules OR a server-provided decision (the AI seam).
+ *
+ *   import { ReviewGate, useReviewGate } from "wireai-onboarding/reviews";
+ */
+
+// ─── The gate UI ──────────────────────────────────────────────────────────────
+export { ReviewGate } from "./ReviewGate";
+
+// ─── The centered-popup presentation (default) + its pure spec ─────────────────
+export { ReviewModal } from "./ReviewModal";
+export type { ReviewModalHandle, ReviewModalProps } from "./ReviewModal";
+export {
+  resolvePresentation,
+  DEFAULT_PRESENTATION,
+  REVIEW_MODAL_ANIM,
+  entranceFrame,
+} from "./presentation";
+
+// ─── The WHEN decision (local rules + the server-decision override) ───────────
+export { useReviewGate } from "./useReviewGate";
+
+// ─── The AI seam + pure gate logic (verifiable in isolation) ──────────────────
+export {
+  decideReview,
+  evaluateGate,
+  resolveRules,
+  routeRating,
+  buildReviewSubmission,
+} from "./decision";
+export type { GateSignals, GateRules } from "./decision";
+
+// ─── Value-equality helpers (stabilize inline-identity props → no render loop) ─
+export { shallowEqual, sameDecision } from "./equality";
+
+// ─── Feedback-form sizing (the ~4-line multiline box) ─────────────────────────
+export {
+  feedbackInputHeights,
+  FEEDBACK_MIN_LINES,
+  FEEDBACK_MAX_LINES,
+} from "./feedbackForm";
+export type { FeedbackInputHeights } from "./feedbackForm";
+
+// ─── The 5-star store path (optional peer + URL fallback) ─────────────────────
+export { requestStoreReview, openStoreListing, storeUrl } from "./storeReview";
+
+// ─── Server transport: submit a review + report generic app.* events ──────────
+export { submitReview, reportAppEvent } from "./transport";
+export type { ReportAppEventOptions } from "./transport";
+
+// ─── Gate-key + storage helpers (shared coachmark storage singleton) ──────────
+export {
+  reviewSeenKey,
+  reviewLastShownKey,
+  reviewSessionsKey,
+} from "./runtime";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+export type {
+  ReviewDecision,
+  RatingRoute,
+  ReviewConfig,
+  ReviewStoreConfig,
+  ReviewTarget,
+  ReviewSubmission,
+  ReviewGateProps,
+  ReviewPresentation,
+  ReviewGateEvent,
+  ReviewGateEventName,
+  UseReviewGateOptions,
+  ReviewGateController,
+} from "./types";

package/src/reviews/presentation.ts

@@ -0,0 +1,29 @@
+/**
+ * presentation.ts — the pure presentation + entrance-animation logic for the review gate.
+ *
+ * WHY split out: the gate UI (ReviewGate/ReviewModal) is RN and can't run under the kit's
+ * node:test runner, but the presentation DEFAULT and the entrance math are pure and worth
+ * pinning. Keep the animation spec here so both the component and the tests read one source.
+ *
+ * The centered popup uses RN's built-in `Animated` (native driver) — the same idiom as
+ * CompletionView/CardHandoff — so the reviews module stays dependency-free (no reanimated).
+ */
+import type { ReviewPresentation } from "./types";
+
+/** Centered popup by default (Malik's ruling: the bottom-anchored inline card read as wrong). */
+export const DEFAULT_PRESENTATION: ReviewPresentation = "modal";
+
+/** Resolve the presentation prop → the effective mode. Absent → the centered modal. */
+export const resolvePresentation = (p?: ReviewPresentation): ReviewPresentation =>
+  p ?? DEFAULT_PRESENTATION;
+
+/**
+ * The centered-popup entrance spec + pure entrance-frame math now live in the neutral
+ * `../motion/centeredModalMotion` (the shell was extracted to `components/CenteredModal` so the
+ * questionnaire module can reuse it without importing reviews/). Re-exported here under their
+ * original names so the reviews public API (reviews/index.ts) and presentation.test.ts stay valid.
+ */
+export {
+  CENTERED_MODAL_ANIM as REVIEW_MODAL_ANIM,
+  centeredModalFrame as entranceFrame,
+} from "../motion/centeredModalMotion";