@wireai/activation 0.1.0

package/src/index.ts

@@ -0,0 +1,159 @@
+/**
+ * wireai-onboarding — premium, themable drop-in onboarding kit on top of the
+ * open-source wireai-rn SDK. Public surface.
+ */
+
+// ─── Host ────────────────────────────────────────────────────────────────────
+export { WireOnboarding } from "./WireOnboarding";
+/** Dev/QA: an on-demand modal trigger to run the flow without a new account. */
+export { DemoOnboarding } from "./DemoOnboarding";
+export type { DemoOnboardingProps } from "./DemoOnboarding";
+
+// ─── Theme ───────────────────────────────────────────────────────────────────
+export { OnboardingThemeProvider, useOnboardingTheme } from "./theme/ThemeContext";
+export { defaultOnboardingTheme, mergeTheme } from "./theme/defaultTheme";
+export { themeFromBrand } from "./theme/themeFromBrand";
+export type { ThemeFromBrandInput } from "./theme/themeFromBrand";
+export type {
+  OnboardingTheme,
+  OnboardingColors,
+  OnboardingFonts,
+  OnboardingRadius,
+  OnboardingSpacing,
+  OnboardingButtonStyle,
+} from "./theme/types";
+
+// ─── Shell components (compose your own flow if needed) ───────────────────────
+export { OnboardingScaffold } from "./components/OnboardingScaffold";
+export { StepProgress } from "./components/StepProgress";
+export { LoadingBlock } from "./components/LoadingBlock";
+export { LoadingScreen } from "./components/LoadingScreen";
+export { AnimatedSparkle } from "./components/AnimatedSparkle";
+export { ErrorBlock } from "./components/ErrorBlock";
+/** @deprecated No longer used internally — the terminal screen is CompletionView. */
+export { DoneBlock } from "./components/DoneBlock";
+export { CompletionView } from "./components/CompletionView";
+export { IllustrationProvider, useIllustration } from "./components/Illustration";
+export type { IllustrationRegistry } from "./components/Illustration";
+export { defaultIllustrations } from "./illustrations/defaultIllustrations";
+export { Button as OnboardingButton } from "./components/Button";
+export { CardHandoff } from "./components/CardHandoff";
+export type { CardHandoffProps, CardHandoffVariant } from "./components/CardHandoff";
+/** Content-agnostic centered-popup shell (the reviews `ReviewModal` re-exports this). */
+export { CenteredModal } from "./components/CenteredModal";
+export type { CenteredModalHandle, CenteredModalProps } from "./components/CenteredModal";
+
+// ─── Motion (the design-spec constants + the reduce-motion gate) ──────────────
+export { useReducedMotion } from "./motion/useReducedMotion";
+export * as motionSpec from "./motion/motionSpec";
+
+// ─── Themed cards + the registered set ────────────────────────────────────────
+export {
+  ChipSelectCard,
+  TextInputCard,
+  SelectionCard,
+  StatusCard,
+  NumberStepperCard,
+  InterstitialCard,
+  onboardingComponents,
+} from "./cards";
+
+// ─── Flow internals (advanced) ────────────────────────────────────────────────
+export { OnboardingFlow } from "./OnboardingFlow";
+export { deriveAnswers } from "./utils/deriveAnswers";
+export { readProgress } from "./utils/readProgress";
+
+// ─── Feature controls (per-module dashboard kill switches; hard fail-open) ────
+export {
+  fetchWireFeatures,
+  useWireFeatures,
+  WireFeaturesProvider,
+  useWireFeaturesContext,
+  useResolvedFeatures,
+  defaultWireFeatures,
+  parseWireFeatures,
+  featuresEqual,
+  featuresCacheKey,
+  readCachedFeatures,
+  writeCachedFeatures,
+  isFeaturesFresh,
+  DEFAULT_FEATURES_TTL_MS,
+} from "./features";
+export type {
+  WireFeatures,
+  WireFeaturesConfig,
+  OnboardingMode,
+  WireFeaturesProviderProps,
+  ResolveFeaturesOptions,
+  CachedFeatures,
+} from "./features";
+
+// ─── Config + env helpers ─────────────────────────────────────────────────────
+export { wireConfigFromEnv } from "./config/wireConfigFromEnv";
+export type { WireConfigOverrides } from "./config/wireConfigFromEnv";
+export { isOnboardingEnabled } from "./config/onboardingFlag";
+export type { OnboardingFlagOptions } from "./config/onboardingFlag";
+
+// ─── Analytics (canonical funnel names) ───────────────────────────────────────
+export { WIRE_ONBOARDING_EVENTS, toAnalyticsEvent } from "./analytics/analyticsEvent";
+export type { WireOnboardingEventName, AnalyticsEvent } from "./analytics/analyticsEvent";
+
+// ─── Client event reporting (device-only funnel events → /v1/events) ──────────
+export {
+  reportClientEvent,
+  reportClientEvents,
+  makeSessionId,
+} from "./analytics/reportClientEvent";
+export type {
+  ClientEvent,
+  ClientEventType,
+  ClientEventTarget,
+} from "./analytics/reportClientEvent";
+
+// ─── Attribution forwarding (→ config.metadata) ───────────────────────────────
+export { attributionMetadata } from "./attribution/attribution";
+export type { OnboardingAttribution } from "./attribution/attribution";
+
+// ─── Device context (privacy-label-neutral, dependency-free) ──────────────────
+export { collectDeviceContext } from "./device/deviceContext";
+export type { DeviceContext, DeviceFormFactor } from "./device/deviceContext";
+
+// ─── User identity (opaque pseudonymous id; late binding, dependency-free) ────
+export { identifyOnboarding, sanitizeUserId, USER_ID_MAX_LENGTH } from "./identity/userIdentity";
+export type { IdentifyOnboardingOptions } from "./identity/userIdentity";
+
+// ─── Session mapping (one `app.session_started` per app-open → /v1/events) ─────
+export {
+  reportSessionStart,
+  resetSessionStartGuard,
+  SESSION_STARTED_EVENT,
+  useSessionStart,
+  BACKGROUND_SESSION_MS,
+} from "./session-analytics";
+export type {
+  ReportSessionStartOptions,
+  SessionStartConfig,
+  UseSessionStartOptions,
+} from "./session-analytics";
+
+// ─── Session persistence (host-injected storage; see the `storage` prop) ──────
+export {
+  loadPersistedSession,
+  peekPersistedSession,
+  savePersistedSession,
+  clearPersistedSession,
+  sessionStorageKey,
+  DEFAULT_SESSION_TTL_MS,
+} from "./session/persistedSession";
+export type { WireOnboardingStorage, LoadedSession } from "./session/persistedSession";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+export type {
+  WireOnboardingProps,
+  WireOnboardingConfig,
+  OnboardingResult,
+  OnboardingEvent,
+  OnboardingCopy,
+  StepValidator,
+  OnboardingProgress,
+} from "./types";

package/src/motion/centeredModalMotion.ts

@@ -0,0 +1,45 @@
+/**
+ * centeredModalMotion - the pure entrance spec for the content-agnostic CenteredModal shell.
+ *
+ * WHY split out: the shell UI (CenteredModal) is RN and cannot run under the kit's node:test
+ * runner, but the entrance math is pure and worth pinning. Keep the animation spec here so both
+ * the component and the tests read one source, and so any module (reviews, questionnaire) can
+ * reuse the shell without depending on another feature module.
+ *
+ * The centered popup uses RN's built-in `Animated` (native driver), the same idiom as
+ * CompletionView/CardHandoff, so the shell stays dependency-free (no reanimated).
+ *
+ * NOTE: `reviews/presentation.ts` re-exports these under their original names
+ * (`REVIEW_MODAL_ANIM`, `entranceFrame`) for back-compat with the reviews public API.
+ */
+
+/**
+ * The entrance spec for the centered popup. Values chosen to match the boilerplate's
+ * `animated-modal` feel (a springy zoom-in) with the kit's own native-driver idiom:
+ *   • backdrop fades 0 -> `backdropOpacity`
+ *   • card springs from `scaleFrom` -> 1 and fades 0 -> 1
+ */
+export const CENTERED_MODAL_ANIM = {
+  /** Spring config for the card scale/opacity entrance (mirrors CompletionView's pop). */
+  enterSpring: { friction: 7, tension: 80 },
+  /** Exit timing in ms (fade + shrink back out before unmount). */
+  exitMs: 160,
+  /** Card scale at rest (progress 0); grows to 1 at progress 1. */
+  scaleFrom: 0.9,
+  /** Peak dim of the backdrop at progress 1. */
+  backdropOpacity: 0.55,
+} as const;
+
+/** A single frame of the entrance, for a progress value in [0..1] (clamped). Pure, testable. */
+export const centeredModalFrame = (
+  progress: number,
+  backdropMax: number = CENTERED_MODAL_ANIM.backdropOpacity,
+): { cardOpacity: number; cardScale: number; backdropOpacity: number } => {
+  const p = progress < 0 ? 0 : progress > 1 ? 1 : progress;
+  const { scaleFrom } = CENTERED_MODAL_ANIM;
+  return {
+    cardOpacity: p,
+    cardScale: scaleFrom + (1 - scaleFrom) * p,
+    backdropOpacity: backdropMax * p,
+  };
+};

package/src/motion/motionSpec.ts

@@ -0,0 +1,133 @@
+/**
+ * motionSpec — the single source of truth for every animation value in the kit,
+ * extracted 1:1 from the Wire Activation card-interactions design canvas
+ * (see design-refs/EXTRACTED-SPEC.md for the row-by-row mapping).
+ *
+ * Pure constants + pure helpers only — NO react-native import — so the spec is
+ * unit-testable under node:test and components can't drift from the design
+ * without a red test.
+ */
+
+/** The design system's "ease-wire" curve: cubic-bezier(0.16, 1, 0.3, 1). */
+export const WIRE_BEZIER = [0.16, 1, 0.3, 1] as const;
+
+/** Design-system duration tokens (colors_and_type.css --duration-*). */
+export const DURATION_FAST_MS = 150;
+export const DURATION_BASE_MS = 300;
+export const DURATION_SLOW_MS = 500;
+
+/** Reduce-motion fallback: a short fade to the final frame, never a frozen mid-state. */
+export const REDUCED_FADE_MS = 120;
+
+// ── Press feedback (spec rows 1, 4, 20) ─────────────────────────────────────
+export const ROW_PRESS_SCALE = 0.975;
+export const CHIP_PRESS_SCALE = 0.94;
+export const BUTTON_PRESS_SCALE = 0.975;
+/** Reduce-motion press feedback: opacity dip instead of scale. */
+export const REDUCED_PRESS_OPACITY = 0.85;
+export const PRESS_SPRING = { friction: 8, tension: 220 } as const;
+export const BUTTON_PRESS_SPRING = { friction: 8, tension: 240 } as const;
+
+// ── Selection state changes (spec rows 2, 3, 5, 6) ──────────────────────────
+export const SELECT_FILL_MS = 180;
+export const CHIP_FILL_MS = 160;
+export const CHECK_SPRING = { friction: 6, tension: 180 } as const;
+export const CHECK_SCALE_FROM = 0.6;
+
+// ── Card-to-card handoff (spec rows 7-10) ───────────────────────────────────
+export const CARD_ENTER_MS = 220;
+export const CARD_EXIT_MS = 180;
+/** The exit starts this long BEFORE the enter (enter is delayed by this). */
+export const CARD_EXIT_LEAD_MS = 80;
+export const CARD_SLIDE_PX = 26;
+export const CARD_ENTER_SCALE_FROM = 0.96;
+/** The interstitial keeps the shell's springier value-beat (AnimatedCard idiom). */
+export const CARD_SPRING = { damping: 14, stiffness: 180, mass: 1 } as const;
+/** Loader-to-card handoff: the loader just fades out. */
+export const LOADER_HANDOFF_FADE_MS = 120;
+
+// ── InterstitialCard reveal (spec rows 11-13) ───────────────────────────────
+export const INTERSTITIAL_HEAD_MS = 500;
+export const INTERSTITIAL_HEAD_STAGGER_MS = 100;
+export const INTERSTITIAL_ITEM_MS = 300;
+export const INTERSTITIAL_ITEM_STAGGER_MS = 90;
+export const INTERSTITIAL_ITEM_BASE_DELAY_MS = 200;
+export const INTERSTITIAL_CHECK_DELAY_MS = 200;
+export const INTERSTITIAL_CHECK_SCALE_FROM = 0.4;
+
+/** Delay before work item `index` begins its reveal (row lands after the head). */
+export const interstitialItemDelay = (index: number): number =>
+  INTERSTITIAL_ITEM_BASE_DELAY_MS + index * INTERSTITIAL_ITEM_STAGGER_MS;
+
+/** Delay before work item `index`'s check pops (200ms after its row starts). */
+export const interstitialCheckDelay = (index: number): number =>
+  interstitialItemDelay(index) + INTERSTITIAL_CHECK_DELAY_MS;
+
+// ── Status / completion payoff (spec rows 14-16) ────────────────────────────
+export const STATUS_POP_SPRING = { friction: 6, tension: 200 } as const;
+export const STATUS_POP_SCALE_FROM = 0.4;
+export const STATUS_BURST_MS = 500;
+export const STATUS_BURST_SCALE_FROM = 0.4;
+export const STATUS_BURST_SCALE_TO = 1.5;
+export const STATUS_BURST_OPACITY_FROM = 0.5;
+export const STATUS_COPY_MS = 300;
+export const STATUS_COPY_STAGGER_MS = 80;
+/** Copy starts settling once the badge pop is visibly underway. */
+export const STATUS_COPY_BASE_DELAY_MS = 200;
+
+/** Delay before payoff copy line `index` fades up. */
+export const statusCopyDelay = (index: number): number =>
+  STATUS_COPY_BASE_DELAY_MS + index * STATUS_COPY_STAGGER_MS;
+
+// ── Loading treatment (spec rows 17-19) ─────────────────────────────────────
+export const LOADER_PULSE_MS = 1600;
+export const LOADER_PULSE_MIN_OPACITY = 0.35;
+export const LOADER_ORBIT_MS = 2400;
+/** Skeleton lines appear only when the fetch runs past this. */
+export const SKELETON_DELAY_MS = 300;
+export const SKELETON_PULSE_MS = 1500;
+export const SKELETON_MIN_OPACITY = 0.45;
+
+// ── Progress bar (spec row 21) ──────────────────────────────────────────────
+export const PROGRESS_MS = 400;
+
+// ── Dev/QA duration scale (slow-mo for judging motion) ──────────────────────
+// A module-level multiplier applied to every timing DURATION (and stagger
+// delay) at animation start. 1 = design speed; 2 = half-speed slow-mo. Springs
+// are physics-based (friction/tension) and do NOT scale. This is a dev/QA tool
+// (the playground's tweak panel drives it) — production code never calls the
+// setter, so the default 1 keeps shipped motion exactly on spec.
+
+let durationScale = 1;
+
+/** Set the global duration multiplier (clamped to 0.1-10; invalid resets to 1). */
+export const setMotionDurationScale = (scale: number): void => {
+  durationScale = Number.isFinite(scale) && scale > 0 ? Math.min(10, Math.max(0.1, scale)) : 1;
+};
+
+export const getMotionDurationScale = (): number => durationScale;
+
+/** Apply the current duration scale to a spec duration/delay (rounded ms). */
+export const scaledMs = (ms: number): number => Math.round(ms * durationScale);
+
+// ── Reduce-motion helpers (pure, shared by every animated component) ────────
+
+export type EntranceSpec = {
+  /** Duration to animate with (falls back to the short fade under reduce motion). */
+  duration: number;
+  /** Whether transforms (translate/scale) may move; false = opacity-only fade. */
+  useTransform: boolean;
+};
+
+/** Entrances: full motion normally; a 120ms opacity-only fade under reduce motion. */
+export const entranceSpec = (reduced: boolean, durationMs: number): EntranceSpec =>
+  reduced
+    ? { duration: REDUCED_FADE_MS, useTransform: false }
+    : { duration: durationMs, useTransform: true };
+
+/** State changes (select fills etc.): snap instantly under reduce motion. */
+export const stateChangeDuration = (reduced: boolean, durationMs: number): number =>
+  reduced ? 0 : durationMs;
+
+/** Looping/ambient animations run only when motion is allowed. */
+export const loopEnabled = (reduced: boolean): boolean => !reduced;

package/src/motion/useReducedMotion.ts

@@ -0,0 +1,43 @@
+/**
+ * useReducedMotion — the kit's ONE reduce-motion gate. Reads the OS setting via
+ * AccessibilityInfo and stays subscribed to `reduceMotionChanged`, so every
+ * animated component lands on its final frame (or a ~120ms fade) the moment the
+ * user flips the setting — no restart needed.
+ *
+ * This closes the gap documented in ai_rules/rules/performance.md §3: every
+ * animation in the kit must consume this hook (usually through the pure helpers
+ * in motionSpec.ts: `entranceSpec` / `stateChangeDuration` / `loopEnabled`).
+ */
+import { useEffect, useState } from "react";
+import { AccessibilityInfo } from "react-native";
+
+// Last-known value, module-level: cards remount every turn (keyed on message id),
+// and a `useState(false)` default would flash one animated frame per turn for a
+// reduce-motion user before the async read resolves.
+let lastKnown = false;
+
+export const useReducedMotion = (): boolean => {
+  const [reduced, setReduced] = useState(lastKnown);
+
+  useEffect(() => {
+    let mounted = true;
+    AccessibilityInfo.isReduceMotionEnabled()
+      .then((value) => {
+        lastKnown = value;
+        if (mounted) setReduced(value);
+      })
+      .catch(() => {
+        // Unavailable (e.g. some test envs): keep the last-known value.
+      });
+    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", (value) => {
+      lastKnown = value;
+      setReduced(value);
+    });
+    return () => {
+      mounted = false;
+      sub?.remove();
+    };
+  }, []);
+
+  return reduced;
+};

package/src/questionnaire/QuestionnaireGate.tsx

@@ -0,0 +1,235 @@
+/**
+ * QuestionnaireGate - the skippable pre-onboarding questionnaire popup.
+ *
+ * A centered popup (over the shared `CenteredModal` shell) with three inputs:
+ *   • a MANDATORY multiline "what do you think about the app" box (~4 lines), and
+ *   • two OPTIONAL smaller boxes ("help us improve" + "suggestions").
+ * Send is disabled ONLY until the opinion box has text; the two optional boxes never gate it.
+ * The gate is ALWAYS skippable (a "Not now"/"Skip" link plays the popup exit), so it is never
+ * a dead end. On send it builds the contract body and fire-and-forgets it to the Wire server,
+ * then shows a warm thank-you until the user taps the backdrop to close.
+ *
+ * The form NEVER asks for identity (no name / email / contact field): the host already
+ * identifies the user via `sessionId` + `meta` (user_id, device_key, session_count), which is
+ * all the POST body carries alongside the answers. Every visual value comes from the
+ * OnboardingTheme; analytics are callback-based (no PII - answers go ONLY in the POST body).
+ */
+import React, { useCallback, useMemo, useState } from "react";
+import { Pressable, StyleSheet, Text, TextInput, View } from "react-native";
+
+import { Button } from "../components/Button";
+import { CenteredModal, type CenteredModalHandle } from "../components/CenteredModal";
+import { feedbackInputHeights } from "../reviews/feedbackForm";
+import { useOnboardingTheme } from "../theme/ThemeContext";
+import type { OnboardingTheme } from "../theme/types";
+import { bodyStyle, captionStyle, headingStyle } from "../theme/typography";
+import { buildQuestionnaireSubmission } from "./decision";
+import { submitQuestionnaireResponse } from "./transport";
+import type { QuestionnaireGateProps } 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 = "form" | "thanks";
+
+export const QuestionnaireGate: React.FC<QuestionnaireGateProps> = ({
+  questionnaire,
+  target,
+  sessionId,
+  meta,
+  onEvent,
+  onResolved,
+  onShown,
+  theme: themeOverride,
+  dismissible = true,
+}) => {
+  const active = useOnboardingTheme();
+  const t = useMemo(() => mergeThemeOver(active, themeOverride), [active, themeOverride]);
+  const modalRef = React.useRef<CenteredModalHandle>(null);
+
+  const id = questionnaire.id;
+  const [phase, setPhase] = useState<Phase>("form");
+  const [opinion, setOpinion] = useState("");
+  const [improve, setImprove] = useState("");
+  const [suggestions, setSuggestions] = useState("");
+
+  // Fire questionnaire_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: "questionnaire_prompt_shown", id });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const resolve = useCallback(() => {
+    onResolved?.();
+  }, [onResolved]);
+
+  // The opinion box is the ONLY gate on Send. The two optional boxes never disable it.
+  const canSend = opinion.trim().length > 0;
+
+  const send = useCallback(() => {
+    if (!canSend) return;
+    // Identity is NEVER collected here - the host already sends user_id / device_key / session
+    // via `sessionId` + `meta`. We POST only the three answers.
+    const submission = buildQuestionnaireSubmission({
+      answers: { opinion, improve, suggestions },
+      sessionId,
+      meta,
+    });
+    submitQuestionnaireResponse(target, id, submission);
+    onEvent?.({ name: "questionnaire_submitted", id });
+    setPhase("thanks");
+    resolve();
+  }, [canSend, opinion, improve, suggestions, sessionId, meta, target, id, onEvent, resolve]);
+
+  // The in-card "Not now"/"Skip" link plays the popup's exit animation (which resolves on
+  // completion, the same path a backdrop tap takes). Emit the dismissed moment first.
+  const handleDismissTap = useCallback(() => {
+    onEvent?.({ name: "questionnaire_dismissed", id });
+    modalRef.current?.close();
+  }, [onEvent, id]);
+
+  const title = questionnaire.title ?? "How's it going so far?";
+  const opinionLabel = questionnaire.opinion_label ?? "What do you think about the app?";
+  const improveLabel = questionnaire.improve_label ?? "How can we improve? (optional)";
+  const suggestionsLabel = questionnaire.suggestions_label ?? "Any suggestions? (optional)";
+
+  // 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; padding is folded in so the lines are visible.
+  const opinionBox = feedbackInputHeights(t.fonts, t.spacing.md);
+
+  const content = (
+    <>
+      <Text style={[headingStyle(t.fonts), { color: t.colors.text }]}>{title}</Text>
+
+      {phase === "form" && (
+        <>
+          <Text style={[captionStyle(t.fonts), { color: t.colors.textMuted }]}>
+            A few words is plenty. Only the first box is required.
+          </Text>
+
+          {/* MANDATORY opinion box - the only gate on Send. */}
+          <Text style={[captionStyle(t.fonts), { color: t.colors.textMuted }]}>{opinionLabel}</Text>
+          <TextInput
+            value={opinion}
+            onChangeText={setOpinion}
+            placeholder="e.g. it feels fast and clear"
+            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: opinionBox.minHeight,
+                maxHeight: opinionBox.maxHeight,
+              },
+            ]}
+          />
+
+          {/* OPTIONAL "help us improve" box - never gates Send. */}
+          <Text style={[captionStyle(t.fonts), { color: t.colors.textMuted }]}>{improveLabel}</Text>
+          <TextInput
+            value={improve}
+            onChangeText={setImprove}
+            placeholder="e.g. fewer steps to start"
+            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,
+              },
+            ]}
+          />
+
+          {/* OPTIONAL "suggestions" box - never gates Send. */}
+          <Text style={[captionStyle(t.fonts), { color: t.colors.textMuted }]}>
+            {suggestionsLabel}
+          </Text>
+          <TextInput
+            value={suggestions}
+            onChangeText={setSuggestions}
+            placeholder="e.g. a dark theme"
+            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" onPress={send} variant="primary" fullWidth disabled={!canSend} />
+          {dismissible && (
+            <Pressable onPress={handleDismissTap} hitSlop={8}>
+              <Text style={[captionStyle(t.fonts), styles.link, { color: t.colors.textMuted }]}>
+                Not now
+              </Text>
+            </Pressable>
+          )}
+        </>
+      )}
+
+      {phase === "thanks" && (
+        <Text style={[bodyStyle(t.fonts), { color: t.colors.textMuted }]}>
+          Thank you. This helps us make it better.
+        </Text>
+      )}
+    </>
+  );
+
+  return (
+    <CenteredModal ref={modalRef} theme={t} dismissible={dismissible} onDismiss={resolve}>
+      {content}
+    </CenteredModal>
+  );
+};
+
+QuestionnaireGate.displayName = "QuestionnaireGate";
+
+const styles = StyleSheet.create({
+  input: { borderWidth: 1 },
+  link: { textAlign: "center", textDecorationLine: "underline" },
+});
+
+export default QuestionnaireGate;

package/src/questionnaire/decision.ts

@@ -0,0 +1,63 @@
+/**
+ * decision.ts - pure decision logic for the questionnaire gate.
+ *
+ * `decideQuestionnaire` is the AI seam, mirroring `decideReview` 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. The local firing
+ * rules (`evaluateGate` / `resolveRules`) and their signals are the SAME generic, pure
+ * helpers the review gate uses - reused here rather than duplicated, since a questionnaire
+ * verdict is structurally the same `{fire, reason}` contract.
+ *
+ * `buildQuestionnaireSubmission` is pure too, so the "opinion required, empties omitted"
+ * shaping of the POST body is verifiable in isolation (the kit has no runtime test runner).
+ */
+import { decideReview, evaluateGate, resolveRules } from "../reviews/decision";
+import type {
+  QuestionnaireAnswers,
+  QuestionnaireDecision,
+  QuestionnaireMeta,
+  QuestionnaireSubmission,
+} from "./types";
+
+// Re-export the generic local-rule helpers under the questionnaire's own namespace so a
+// host wires the fallback without reaching into the reviews module.
+export { evaluateGate, resolveRules } from "../reviews/decision";
+export type { GateSignals, GateRules } from "../reviews/decision";
+
+/**
+ * The seam. `decision` absent → the local verdict stands; present → it overrides. Same
+ * contract philosophy as `decideReview(local, decision?)`.
+ */
+export const decideQuestionnaire = (
+  local: QuestionnaireDecision,
+  decision?: QuestionnaireDecision,
+): QuestionnaireDecision => decideReview(local, decision);
+
+/**
+ * Build the `POST /v1/questionnaires/{id}/responses` body. `opinion` is the only mandatory
+ * answer (trimmed); `improve`/`suggestions` are trimmed and sent as `null` when empty. The
+ * `meta` bucket carries the non-PII correlation fields (user_id / device_key / session_count),
+ * each defaulting to null. Free text lives ONLY here, never in analytics events.
+ */
+export const buildQuestionnaireSubmission = (input: {
+  answers: QuestionnaireAnswers;
+  sessionId?: string | null;
+  meta?: QuestionnaireMeta;
+}): QuestionnaireSubmission => {
+  const opinion = input.answers.opinion.trim();
+  const improve = input.answers.improve?.trim();
+  const suggestions = input.answers.suggestions?.trim();
+  return {
+    session_id: input.sessionId ?? null,
+    answers: {
+      opinion,
+      improve: improve ? improve : null,
+      suggestions: suggestions ? suggestions : null,
+    },
+    meta: {
+      user_id: input.meta?.user_id ?? null,
+      device_key: input.meta?.device_key ?? null,
+      session_count: input.meta?.session_count ?? null,
+    },
+  };
+};