@wireai/activation 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,572 @@
+# Changelog
+
+All notable changes to `wireai-onboarding`. Consumed from source (unpublished),
+so versions are informational.
+
+## [0.7.0] — Unreleased
+
+### Added: session mapping — know when a user opens the app again
+
+- New `session-analytics/` module. `reportSessionStart(opts)` posts ONE standard
+  `app.session_started` event per app-open to `POST /v1/events`, carrying the host's opaque
+  `userId` (optional; pre-auth opens are device-only), a stable non-PII `deviceKey`, the host's
+  `sessionCount`, a derived `returning` flag (`session_count > 1`), and `appVersion`/`platform`.
+  Fire-and-forget (never throws, never awaits) with a once-per-open guard so a re-render can never
+  double-fire. The event is stored as `event_type='app_event'`, `question_key='app.session_started'`
+  (the app.* namespace the reviews wave shipped), so it needs NO server change: the same event
+  stream the console and decision engines already read now answers "show the questionnaire on this
+  user's Nth session" (`min_sessions:N`, or a trigger `{event:"app.session_started", min_count:N}`)
+  and becomes per-user retention analytics.
+- The per-open `session_id` is a fresh `makeSessionId()` each open, NOT the onboarding A2A
+  contextId (onboarding runs once; session-start fires on every open). Grouping over time is by
+  `deviceKey`/`userId`, never by session_id. `deviceKey` links a device's pre-auth opens to the
+  user once `userId` arrives (here or via `identifyOnboarding`).
+- Convenience hook `useSessionStart(config, {userId, sessionCount, deviceKey})` fires on mount and
+  on foreground-after-30-min-background (a real new open, not a quick app-switch), collecting the
+  device snapshot for you. Optional: a host with its own session counter (Myelino/Morrow) can call
+  the plain `reportSessionStart` directly instead. Both paths are first-class.
+- Exports added to the core barrel: `reportSessionStart`, `useSessionStart`, `SESSION_STARTED_EVENT`,
+  `BACKGROUND_SESSION_MS`, and the `ReportSessionStartOptions` / `SessionStartConfig` /
+  `UseSessionStartOptions` types. New README section "Session mapping".
+
+## [0.6.0] — 2026-07-11
+
+### Fixed: the between-turns loader now centers in the full screen
+
+- The "AI is thinking" loader rendered a little low: the between-turns `LoadingBlock` fills the
+  `OnboardingScaffold` body, which sits below the header progress bar, so it centered in the body
+  rather than the screen (the device finding "the loading between questions animation is not
+  centralized"). The scaffold now publishes its top-chrome height through a new `loaderChrome`
+  context and `LoadingBlock` shifts its centered content up by half that distance, landing at the
+  true screen center. It is a static transform on the loader alone, so the card underneath and the
+  card-to-loader handoff are untouched (no reflow, no jump; opacity/transform, native driver).
+- The standalone loader slots (cold-start, resumed-session restoring, transient error/timeout) used
+  to return a bare `LoadingBlock` whose flex only filled whatever the host gave it (no safe area,
+  top-anchored if unbounded). New exported `LoadingScreen` wraps them in a full-area `SafeAreaView`
+  so every loader slot centers the same way. `WireOnboarding` restoring and `OnboardingFlow`
+  cold-start/error now use it. The Scripted-onboarding playground demo exercises the fixed
+  between-turns layout unchanged (same `OnboardingScaffold` + `CardHandoff` + `LoadingBlock`).
+
+### Added: `CenteredModal`, the shared centered-popup shell (reviews API unchanged)
+
+- The content-agnostic centered-popup shell was extracted, unchanged, out of the reviews module
+  into `components/CenteredModal` (`CenteredModal` / `CenteredModalHandle` / `CenteredModalProps`),
+  exported from the core barrel. It is the same transparent RN `Modal` + dimmed backdrop +
+  centered card + spring/fade entrance on RN `Animated` (native driver, zero new deps), with
+  backdrop-tap / Android-back / imperative `close()` dismissal that animates out then fires
+  `onDismiss`. Its pure entrance spec moved to `motion/centeredModalMotion`.
+- `reviews/ReviewModal` is now a thin back-compat re-export of `CenteredModal`, so `ReviewModal`,
+  `ReviewModalHandle`, and `ReviewModalProps` still import from `wireai-onboarding/reviews` and
+  resolve to the exact same runtime object. `reviews/presentation` re-exports the spec under its
+  original `REVIEW_MODAL_ANIM` / `entranceFrame` names. The reviews public API and its canary are
+  unchanged; a new `centeredModal` canary covers the shared shell. The questionnaire module can
+  now reuse the shell without depending on reviews/.
+
+### Changed: the 1-4 review feedback phase is now TWO optional inputs
+
+- `ReviewGate` feedback phase (the 1-4 star path) now renders two optional inputs instead of
+  one required box: the existing multiline box is relabelled "why this rating" (the opinion),
+  and a smaller "what can you suggest" input is added below it. The rating is the only mandatory
+  action now, so Send is no longer disabled on empty text: it works with the opinion box, the
+  suggestion box, both, or neither. Warm thank-you + Skip are unchanged, and the fire-once
+  `onShown` / `onEvent` ref pattern and every analytics moment are untouched.
+
+### Added: `suggestion` carried to the server
+
+- `ReviewSubmission` gains an optional `suggestion` field and `buildReviewSubmission` accepts a
+  `suggestion` input, trimmed and included in the POST body only when non-empty (mirroring the
+  `feedback_text` / `contact` handling). The server ignores the extra field until its own change
+  lands, so this is additive and safe to ship first.
+- The playground Review Gate demo surfaces both inputs so the two-input feedback phase can be
+  tapped through by hand.
+
+### Added: the `questionnaire` feature switch
+
+- `WireFeatures` gained a `questionnaire: { enabled }` switch, mirroring the server's
+  `features.questionnaire`. It fails open to on (an absent or malformed key resolves to
+  `{ enabled: true }`, like `review`), is carried in the frozen `defaultWireFeatures`, parsed via
+  the shared `readEnabled` tolerant reader, and compared in `featuresEqual`. Dark-by-default for
+  the questionnaire comes from the server not returning an enabled switch, not from this default.
+  The questionnaire module gates on this flag.
+
+### Added: the `questionnaire` module (skippable pre-onboarding popup)
+
+- New subpath `wireai-onboarding/questionnaire` (mirrors `reviews/`): a `QuestionnaireGate`
+  popup over the shared `CenteredModal` shell with three inputs, one MANDATORY "what do you
+  think about the app" box plus two OPTIONAL boxes ("help us improve" + "suggestions"). Send is
+  disabled ONLY until the opinion box has text; the two optional boxes never gate it, and the
+  popup is ALWAYS skippable ("Not now" plays the exit, backdrop tap and Android back dismiss).
+  On send it fire-and-forgets the contract body to `POST /v1/questionnaires/{id}/responses` and
+  shows a warm thank-you.
+- `useQuestionnaireGate` owns WHEN the gate shows, mirroring `useReviewGate` exactly: local
+  firing rules OR a server-provided `decision` (the AI seam, `decideQuestionnaire`), gated by the
+  `questionnaire` master switch (`useResolvedFeatures(...).questionnaire.enabled`, fail-open) and
+  shown at most once per user per questionnaire `id` via the shared coachmark seen-gate, so a
+  server bug can never re-spam the popup. Inline `config`/`decision` props are value-stabilized so
+  a verdict-keyed host effect never loops (frequent_rules #11).
+- `submitQuestionnaireResponse` POSTs the contract body (`{ session_id, answers: { opinion,
+  improve, suggestions }, meta: { user_id, device_key, session_count } }`) fire-and-forget, and a
+  best-effort `fetchQuestionnaireDecision` reads `GET /v1/questionnaires/decision` with hard
+  fail-open (unreachable / non-2xx / 404 resolve to null, so the host simply never shows the
+  gate). Pure helpers `buildQuestionnaireSubmission` (opinion required, empties omitted) and the
+  reused `evaluateGate` / `resolveRules` keep the logic verifiable in isolation.
+- `package.json` gains `exports["./questionnaire"]` (react-native to source, import/require to
+  dist), and tsup builds the new subpath. Zero new runtime deps (RN `Animated` only). A new
+  `test/canary/questionnaire.test.tsx` proves the hook does not loop on inline props and that
+  Send is gated on the opinion box only. A playground "8 Questionnaire" demo screen surfaces the
+  trigger, the skip path, the mandatory-first-field validation, and the real once-gate.
+
+## [0.5.0] — 2026-07-11
+
+### Added: per-module feature controls (dashboard kill switches, hard fail-open)
+
+- New core module `src/features/`: `fetchWireFeatures(config)` reads the per-module switches
+  from `GET /v1/features` (tenant key, `Cache-Control: private, max-age=300`), with a last-known
+  cache persisted through the optional `storage`. THE CONTRACT is fail-open, never fail-dark:
+  unreachable, 401, 5xx, timeout, or malformed JSON all resolve to the last cached value, else the
+  all-on defaults (`defaultWireFeatures` = every module on, onboarding `ai`). No failure path ever
+  throws into the host. A control-plane outage can only be more permissive than the dashboard
+  intends. It can never dark a tenant's activation.
+- New hook `useWireFeatures(config?)` (value-stabilized inputs per frequent_rules #11) and an
+  optional `WireFeaturesProvider` so one fetch serves every module. Zero setup is a valid setup:
+  omit the wiring and every surface stays on (defaults), zero behavior change, zero extra fetches.
+- Gated the three client surfaces with graceful semantics:
+  - `CoachmarkProvider` / the overlay host: `coachmarks.enabled === false` makes tour and overlay
+    `show()` requests silent no-ops. The once-per-tour gates are NOT consumed, so re-enabling
+    replays correctly.
+  - `FeatureShowcase`: `showcase.enabled === false` renders nothing and calls `onDone()` from an
+    effect so the host flow continues (cannot strand a navigation flow); the seen gate is not
+    written, so re-enabling replays.
+  - `useReviewGate` / `ReviewGate`: `review.enabled === false` means the gate never fires,
+    composing as a master switch over the existing local-rules + server-decision seam.
+  - Onboarding needs NO kit gating: the server owns `ai` | `static` | `off` over the same A2A
+    contract (`off` already returns a terminal card the kit reads as completion). See the README.
+- Wiring is OPTIONAL at every surface: an explicit `features` prop, else the `WireFeaturesProvider`
+  context, else a lazy `featuresConfig` fetch, else pure defaults.
+- Tests: 26 added (fetch / cache / fail-open matrix covering 401, 5xx, timeout, malformed JSON,
+  cache hit, stale-while-error, no-creds; parser tolerance; the coachmarks-disabled no-op; a
+  `WireFeaturesProvider` render canary; and gating-semantics for showcase + reviews). Full suite
+  93 to 119, green.
+- New public exports from the core barrel: `fetchWireFeatures`, `useWireFeatures`,
+  `WireFeaturesProvider`, `useWireFeaturesContext`, `useResolvedFeatures`, `defaultWireFeatures`,
+  `parseWireFeatures`, `featuresEqual`, the cache helpers, and the `WireFeatures` / `OnboardingMode`
+  types. Coachmarks barrel adds `setCoachmarksEnabled` / `areCoachmarksEnabled`.
+
+## [0.4.0] — 2026-07-10
+
+### Added: render-canary test harness (runtime coverage for the gates)
+- `npm test` now mounts every publicly exported component headlessly
+  (react-test-renderer, dev-only) under deliberately unstable inline props and
+  fails the suite if any component exceeds its render budget. This closes the
+  structural gap that let the ReviewGate remount loop ship past every static
+  gate: bundling and static analysis green is not runtime safe. 20 canary tests
+  across reviews, cards, showcase, coachmarks, and the flow shell, plus an
+  interaction sanity layer. The tester gate definition and frequent_rules #11
+  now require a canary for every new or changed component.
+
+<!-- Retitled from 0.3.2: this section now also ships the card-interactions motion
+     system (new public exports: CardHandoff, useReducedMotion, motionSpec; new
+     optional InterstitialCard `items` prop) — additive feature work = minor bump. -->
+
+### Added: card-interactions motion system (Wire Activation design)
+- **The whole questionnaire now moves per the locked design canvas** ("Wire
+  Activation - Card Interactions"); the extracted, testable spec lives in
+  `design-refs/EXTRACTED-SPEC.md` and every value is a constant in the new
+  `src/motion/motionSpec.ts` (pure, unit-tested — components import, never inline).
+  - `SelectionCard`: rows tick on press (scale 0.975 spring), the selected
+    `primarySoft` fill + `primary` border crossfade in over 180ms ease-wire on a
+    native-driver overlay, and a 24px check dot pops in with a spring. Rows gain
+    radio/checkbox accessibility roles + states. The selected label now keeps the
+    text color (accent discipline: accent on border/dot/fill only).
+  - `ChipSelectCard`: chips press-tick (scale 0.94), the full-accent selected pill
+    crossfades in over 160ms with an `onPrimary` check pop; deselect reverses.
+  - `InterstitialCard`: art and title fade-up in sequence (500ms ease-wire, 100ms
+    stagger). NEW optional `items: string[]` prop (additive): 2-3 short "work being
+    done" lines that tick on one by one (90ms stagger, check pops 200ms after its
+    row), each meant to reference a real answer. Falls back to `body` unchanged.
+  - `StatusCard`: status glyph springs in (scale 0.4→1), copy fades up 80ms behind.
+  - `CompletionView` (the terminal payoff): badge spring pop + ONE soft accent
+    burst (scale 0.4→1.5, opacity 0.5→0, 500ms, fires once — celebratory without
+    confetti) + copy fade-up staggered 80ms. Settles under a second.
+  - NEW `CardHandoff` (exported): the card-to-card transition — the answered card
+    exits left (180ms) while the next enters from the right (220ms, 80ms overlap),
+    both ease-wire `cubic-bezier(0.16,1,0.3,1)`; loaders hand off with a 120ms
+    fade. Supersedes the internal enter-only `AnimatedCard` (which was never
+    exported). `OnboardingFlow` now routes loader and card states through it, so
+    the "thinking" state fades into the first card instead of hard-cutting.
+  - `LoadingBlock`: the "no spinner" loader — the mark breathes (1600ms), an
+    accent dot orbits a dashed ring (2400ms), and skeleton lines appear only past
+    300ms so a fast (prefetched) turn never flashes placeholder chrome.
+    `AnimatedSparkle` gains a `variant="pulse"` (default "spin" unchanged).
+  - `Button`: press answers the tap — scale 0.975 spring in/out (design row 20).
+  - `StepProgress`: fill now eases with the design curve (400ms ease-wire; was
+    450ms default easing). Still the one sanctioned JS-driver width animation.
+- **Reduce motion is now ENFORCED, closing the documented gap** in
+  `ai_rules/rules/performance.md` §3: new shared hook `useReducedMotion`
+  (exported) reads `AccessibilityInfo.isReduceMotionEnabled` + the
+  `reduceMotionChanged` listener; every animation in the kit gates on it
+  (entrances become a ~120ms fade to the final frame, state changes snap, loops
+  go static, press feedback becomes an opacity dip). `ReviewModal`,
+  `AnimatedSparkle`, `CompletionView` and every card are covered; the rule file
+  is updated from "gap" to enforced with falsifiable greps.
+- Public API: purely additive (`CardHandoff`, `useReducedMotion`, `motionSpec`,
+  InterstitialCard `items`). Existing integrators render correctly with zero
+  changes.
+- Dev/QA: `motionSpec.setMotionDurationScale(x)` — a global duration multiplier
+  (2 = slow-mo) for judging motion; springs don't scale; production defaults to
+  1x. Driven by the playground's Tweak panel.
+
+### Added: playground design-review surface
+- **Design system storybook**: an 11-story "Design system" group on the
+  playground home gallery (Tokens specimen sheet, Buttons, Chips, Option rows,
+  Progress bar, AI-thinking/loading with the sub-300ms vs skeleton comparison,
+  Interstitial processing, Status/Completion replay, the CardHandoff transition
+  flipper, Review modal, Showcase slide) — every story shows its exact
+  props/tokens via the collapsible code block.
+- **Tweak panel**: live global overrides (accent hex + presets, radius scale,
+  spacing scale, animation-speed 0.5x/1x/2x) applied across every story and
+  demo through the shared theme context; one-tap reset.
+- **Scripted onboarding**: a full-screen 5-question run (chips, two selects,
+  interstitial with answer-reflecting `items`, final select, CompletionView)
+  through the REAL shell (OnboardingScaffold + CardHandoff + LoadingBlock) with
+  scripted 700ms thinking beats — the offline stand-in for a tenant flow.
+
+### Fixed: ReviewGate render loop under unstable inline props
+- **`useReviewGate` and `ReviewGate` are now hardened against inline props.** The
+  first on-device run of the centered review popup hit a Maximum-update-depth
+  crash: the host remounted the gate on every analytics event (a `key` derived
+  from an event log), and each fresh mount re-fired `review_prompt_shown`. The
+  kit now tolerates both failure ingredients: `config` and `decision` inputs are
+  value-stabilized (a shallow-equal object no longer recomputes the verdict or
+  remints a decision), the controller and `markShown`/`markResolved` are
+  referentially stable, and the shown event fires exactly once per mount through
+  latest-ref callbacks immune to inline `onEvent`/`onShown` recreation. The
+  once-per-user gate semantics are unchanged.
+- New pure exports from `wireai-onboarding/reviews`: `shallowEqual` and
+  `sameDecision` (the value-equality helpers behind the stabilization), covered
+  by 10 new tests in `equality.test.ts`.
+
+### Fixed: pre-onboarding showcase first slide flooded with the app accent
+- **The showcase's large image/hero panel is now a calm surface, not an accent
+  flood.** 0.3.1 fixed the invisible CTA by mapping `background.primary` to the
+  brand `accent`. But in the underlying `@blazejkustra/react-native-onboarding`,
+  `background.primary` is ONE key that drives THREE surfaces at once: the primary
+  button (`buttons/PrimaryButton.tsx`), the intro highlight word
+  (`OnboardingIntroPanel.tsx`), and the full-bleed image hero panel
+  (`OnboardingImageContainer.tsx`'s `colorBg`). So the button fix also painted the
+  whole hero panel in the accent, which dominated the first slide and "hid" the
+  app (reported in Myelino on 0.3.1). The package exposes no per-surface color key
+  to split them, but it does accept a `background?: () => ReactNode` render prop
+  that REPLACES that panel fill outright. `FeatureShowcase` now passes one: a calm
+  theme `surface` base with a faint accent tint (~10% opacity) on top. Result: the
+  primary button and intro highlight keep the full accent (they read
+  `background.primary` directly), while the hero panel reads as a subtle branded
+  card. No app change needed.
+- New pure export `showcasePanelBackground(theme, accent)` (plus `SHOWCASE_PANEL_TINT_OPACITY`,
+  `ShowcasePanelBackground`) holds the split, unit-tested in
+  `showcaseColors.test.ts` (button = accent, panel base = surface, not accent, tint in
+  the calm 8 to 12% band). The 0.3.1 button-color regression tests are unchanged and
+  still pass.
+
+### Changed: in-app review feedback form (no identity ask, taller box, form CTA)
+- **The 1 to 4 star feedback form no longer asks for identity.** The optional
+  name/email "contact" field was removed. 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 free text. The form never asks the user to type
+  who they are. (`ReviewSubmission.contact` / `buildReviewSubmission`'s `contact`
+  param stay as server-contract plumbing but are no longer populated by the kit.)
+- **The free-text box is now a proper multiline field, ~4 lines tall (capped at
+  ~5).** Height derives from the theme's body line-height via the new pure
+  `feedbackInputHeights(fonts, verticalPadding)` (plus `FEEDBACK_MIN_LINES` /
+  `FEEDBACK_MAX_LINES`), so it scales with the app's font config; `multiline` +
+  `textAlignVertical="top"`, hairline border + `radius.md` + muted placeholder from
+  theme tokens. Unit-tested in `feedbackForm.test.ts`.
+- **The submit button now reads as a form CTA.** It uses the kit's themed `Button`
+  (accent background, `onPrimary` label, `button.radius` / `button.paddingX`: the
+  accent-not-background discipline) and stretches full-width via a new opt-in
+  `fullWidth` prop on `Button` (default false, so no other call site changes).
+- All review events/analytics are unchanged. New `decision.test.ts` documents the
+  no-identity guarantee of the POST body.
+
+## [0.3.1] — Unreleased
+
+### Changed: the in-app review prompt is now a centered popup by default
+- **`ReviewGate` renders as a centered modal** (dimmed backdrop, card in the middle of the
+  screen, spring/fade entrance) instead of the bare host-positioned card, which rendered
+  bottom-anchored and half-hidden on device (reported in Myelino on 0.3.0). The entrance
+  uses RN's built-in `Animated` on the native driver (the same idiom as `CompletionView` /
+  `AnimatedCard`), so the reviews module stays dependency-free (no reanimated). The card
+  surface, radius, spacing, and text all come from the active theme, so it is theme-aware in
+  light and dark. A backdrop tap or Android back dismisses it, counting as the same resolve
+  path `onResolved` already tracks; it never auto-closes on resolve, so the user still sees
+  the thank-you payoff. Adapted from the mobile-launcher boilerplate's `animated-modal`
+  (transparent RN `Modal` + centered container + backdrop-tap dismiss + content
+  stop-propagation + springy zoom-in), reimplemented on RN core primitives.
+- **Additive API, no app change needed.** New optional `presentation?: "modal" | "inline"`
+  prop on `ReviewGate`, defaulting to `"modal"`. Apps like Myelino's `HomeReviewGate` pick up
+  the centered popup automatically when they bump to 0.3.1, with zero code changes. Pass
+  `presentation="inline"` to keep the legacy bare card. New exports: `ReviewModal`,
+  `ReviewModalHandle`, `ReviewModalProps`, `ReviewPresentation`, `resolvePresentation`,
+  `DEFAULT_PRESENTATION`, `REVIEW_MODAL_ANIM`, `entranceFrame`.
+- Extracted the presentation default + entrance math into a pure, unit-tested
+  `src/reviews/presentation.ts` (`resolvePresentation`, `entranceFrame`), with tests
+  asserting the modal is the default and the scale/fade/backdrop interpolation and clamping.
+
+### Fixed — pre-onboarding showcase button rendered in the wrong color
+- **`FeatureShowcase` primary button now uses the brand accent, not the screen
+  background.** The underlying `@blazejkustra/react-native-onboarding` package paints
+  its primary button (plus the intro highlight word and the image hero panel) from
+  `background.primary` — its BRAND/action color, despite the "primary" name. The kit
+  was mapping `background.primary` to the theme's `background`, so every consuming app
+  rendered the "Next/Get Started" CTA in its own screen background color: white-on-white
+  in light mode, dark-on-dark in dark mode (reported in Morrow Self + Myelino, both on
+  0.3.0). The CTA now maps to the theme's `primary` (or the `accentColor` override), and
+  the screen/panel background maps to `background`. No app change is required to pick up
+  the fix — apps already pass their theme/`accentColor` correctly.
+- Extracted the theme→package color mapping into a pure, unit-tested
+  `showcaseColorsFromTheme(theme, accent)` (new `src/showcase/showcaseColors.ts`) with a
+  regression test asserting the primary button is the accent and never the background.
+
+## [0.3.0] — Unreleased
+
+> Pending release. `0.2.1` is already published on npm (coachmarks + showcase, no
+> identity API), so this identity surface — alongside the unpublished `/reviews`
+> module and `selectShowcaseSlides` — ships in `0.3.0`.
+
+### Added — first-class user identity (`userId`) with late binding
+- **`userId` prop** on `<WireOnboarding>`: your own opaque, pseudonymous user id (NOT
+  an email/name/phone) so onboarding sessions reconcile to real users later. Trimmed and
+  capped at 128 chars; old servers ignore the field (backward compatible). Binds at three
+  moments: known at mount (rides the A2A session-start metadata), the user registers
+  mid-session (the kit emits an `identify` client event that attaches the id to the live
+  session), or after the flow (the `identifyOnboarding` helper below).
+- **`identifyOnboarding(opts)`**: post-flow / post-registration binding. Resolves the
+  session from an explicit `contextId` or the persisted `storage`, then posts an `identify`
+  event to `POST /v1/events`. Fire-and-forget, never throws; resolves `true` when it
+  dispatched, `false` when it could not (no user id, no server url, no resolvable session).
+- **`IdentifyOnboardingOptions`** type, **`sanitizeUserId(raw)`** (trim + 128-char cap,
+  returns `undefined` for blank/non-string), and **`USER_ID_MAX_LENGTH`** (128) exported.
+- **`peekPersistedSession(storage, key)`**: read-only accessor that returns the persisted
+  `{ id, ts }` WITHOUT minting a fresh one (backs `identifyOnboarding`'s storage lookup).
+- **`contextId` on the `started` / `resumed` `onEvent`**: the A2A session id is now surfaced
+  on those events so a host can capture it and bind a user AFTER completion (completion
+  clears the persisted session, so the captured id is the reliable post-flow handle).
+  Additive and non-breaking.
+
+## [0.2.0] — 2026-07-09
+
+### Added — coachmarks + feature showcase (two new subpath modules)
+- **`wireai-onboarding/coachmarks`** — a performance-first guided-tour engine lifted
+  from a production app and generalized for the kit. Ships `CoachmarkProvider` (root
+  provider that injects a **synchronous** `CoachmarkStorage` gate + renders the overlay
+  host above the tab bar), `useCoachmarkAnchor` (measure-at-step anchor registry),
+  `useCoachmarkTour` (ordered queue with in-kit gating on `wire_coachmark_<tourId>_seen`,
+  cancellable anchor resolve, ref-held callbacks, one-overlay-at-a-time), the
+  `SpotlightOverlay` (animated `expo-blur` + pulsing ring + tooltip), a dependency-free
+  self-drawn `GestureHint` (UI-thread `react-native-reanimated`, Reduce-Motion fallback),
+  a global `isTestingCoachmark` QA-replay flag (`setCoachmarkTesting`), and the Phase-3
+  `selectTourSteps(catalog, selection?)` AI-selection seam. Ring/tooltip color derives
+  from the onboarding theme with an `accentColor` override.
+- **`wireai-onboarding/showcase`** — `FeatureShowcase`, a themed wrapper over
+  `@blazejkustra/react-native-onboarding` for the pre-onboarding app intro. Maps a
+  declarative `ShowcaseConfig` to the package API, overlays the perf-tuned `GestureHint`
+  per slide, and gates once on `wire_showcase_<id>_seen` (testing flag bypasses).
+
+### Packaging
+- **Subpath exports** keep the main barrel dependency-free — `coachmarks`/`showcase` are
+  NOT re-exported from `src/index.ts`. Their optional peers
+  (`react-native-reanimated >=3`, `expo-blur >=13`, `@blazejkustra/react-native-onboarding >=1`)
+  are declared in `peerDependenciesMeta` as optional and load only when the subpath is used.
+- tsup multi-entry build → `dist/coachmarks` + `dist/showcase` (ESM + CJS + `.d.ts`).
+
+## [0.1.12] — 2026-07-08
+
+### Fixed
+- `withTimeout` now clears its race timer on settle — a won read no longer leaves a
+  ≤1.5 s no-op timer holding the closure alive (`session/persistedSession.ts`).
+
+### Docs
+- Documented the dev-only StrictMode caveat on first-mint hydration: a spurious
+  `resumed: true` can surface in dev builds; production is unaffected and it self-heals
+  (`WireOnboarding.tsx`).
+
+## [0.1.11] — 2026-07-08
+
+### Added — session-id persistence (fixes the phantom-drop funnel inflation)
+- New optional **`storage` prop** (AsyncStorage-compatible `getItem/setItem/removeItem`;
+  pass `@react-native-async-storage/async-storage` as-is or a small MMKV wrapper). When
+  set, the kit persists `{ id, ts }` of its session id — the correlation seed the backend
+  adopts as the A2A `contextId` — so an app **kill** mid-onboarding resumes the SAME
+  backend session on relaunch instead of minting a new one. Previously every relaunch
+  counted a second `session_started` and left the first session as a false "drop",
+  inflating the analytics funnel's `started` denominator. **No new dependency** — the
+  host injects the storage (the kit's first host-supplied-capability port since
+  `illustrations`). Persists the kit's own correlation seed ONLY; answer persistence
+  stays a host concern via `onComplete`.
+- New `sessionTtlMs` prop (default 3 600 000 ms = the backend's session TTL) and
+  `persistKey` prop (default key `wireai:session:<appId>`).
+- Hydration is a **loader-gate**: the provider subtree mounts only after the stored id
+  resolves (one timeout-capped storage read; a hung adapter degrades to a fresh mint,
+  never a stuck screen). New `restoringTitle`/`restoringHint` copy strings.
+- On resume the kickoff sends the existing skip sentinel instead of `startMessage`
+  (whose literal text the server would record as the pending question's ANSWER); the
+  server logs a `screen_skipped` and advances — so a resumed session skips at most the
+  one question that was on screen at kill time. A session the server no longer knows
+  degrades cleanly to a fresh flow under the same id (still one funnel session).
+- The persisted id is **cleared on completion** and deliberately kept on drop/degrade
+  (a dropped session stays resumable within the TTL).
+
+### Changed — `OnboardingEvent` union grew (compile-time visible)
+- New `{ type: "resumed" }` event, fired INSTEAD of `started` when a persisted session
+  was restored — host funnels must not count both as starts. `toAnalyticsEvent` maps it
+  to the new canonical `wire_onboarding_resumed`. Exhaustive `switch`es over
+  `OnboardingEvent` will now fail to compile until they handle `resumed` (intentional).
+- Note for dashboards: resume-kickoffs add `screen_skipped` events, so the skip rate
+  now includes resume-skips.
+
+## [0.1.10] — 2026-07-07
+
+### Fixed — keyboard no longer covers the pinned CTA
+- `CardLayout` now wraps its column in a `KeyboardAvoidingView` (`behavior="padding"`), so
+  the bottom-pinned Continue/Submit button rides above the soft keyboard on text questions
+  (`TextInputCard`). No new dependency — RN core only. On hosts whose window already resizes
+  for the keyboard the computed overlap is ~0, so the padding is a no-op.
+- The card `ScrollView` gets `keyboardDismissMode="on-drag"` (scrolling dismisses the keyboard).
+
+### Added — clearer text questions
+- `TextInputCard` gains an optional `hint` prop, rendered as the subtitle line under the
+  question (one sentence of context: what the answer personalizes). The `placeholder` schema
+  description now demands a concrete "e.g. ..." example answer so the model reliably sends one.
+  Pairs with the backend prompt update (server `app/wire.py` + `app/prompt.py`, same date).
+
+### Fixed — package.json cleanup
+- Removed the stray `dependencies` block that self-depended on `wireai-onboarding@0.1.8` and
+  duplicated the `wireai-rn` peer as a hard dependency.
+
+## [0.1.3] — 2026-06-27
+
+### Changed — kit is the single fallback reporter
+- The whole-flow degrade self-report now posts **`client_fallback`** (was `llm_fallback`),
+  so it lands on the backend's idempotent `client_fallback` ingest, which back-fills a
+  `session_started` for a session it never saw. Result: a device that drops straight to its
+  static manifest still shows as a counted fallback session, correlated to the real funnel
+  session when the SDK forwards `metadata.sessionId` (wireai-rn ≥ 0.2.1). `ClientEventType`
+  is now `screen_skipped | dropped | client_fallback`. **Hosts must NOT also report their own
+  fallback** — the kit owns this signal (previously apps direct-fetched it; remove that on upgrade).
+
+## [0.1.8] — 2026-07-06
+
+### Added — full-screen card layout redesign
+- New `CardLayout` / `AnimatedCard` / `OnboardingScaffold`: every card gets a full-screen
+  layout with a pinned CTA, safe-area handling, and a per-step enter transition (all six
+  cards + the completion view route through it).
+- `TextInputCard` renders a tall multi-line box by default for open-ended answers (new
+  optional `multiline`/`lines` props; set `multiline:false` for a single-line field like a name).
+
+### Changed — new required peer dependency
+- Adds **`react-native-safe-area-context` (>=4.0.0)** as a required peer (used by
+  `OnboardingScaffold` for insets). The kit is no longer strictly pure-JS; the host must wrap
+  its root in a `SafeAreaProvider` (standard in every Expo/RN app, and both current consumers
+  already do).
+
+### Security
+- `InterstitialCard.imageUrl` is now validated as an `https://` URL (previously any string
+  was passed to `<Image>`); a non-https or malformed value is rejected and degrades to the
+  named-illustration fallback.
+
+### Added — prefetch on select (fixes "the first AI question is always the slowest") (2026-07-05)
+- **Choice cards now warm the next turn while the user is still picking.** Q1 is a deterministic
+  base card (instant); Q2 is the first LLM turn and neither backend cache protects it (the
+  flow-cache misses a novel answer combo, the provider prompt-cache is cold on the first call),
+  so it was always the perceptibly-slowest screen. `SelectionCard` and `ChipSelectCard` now emit
+  their live selection via a new optional `onSelectionChange` prop; `<WireOnboarding>` injects a
+  handler that fires a trailing-edge debounced (300ms) `message/preview` keyed on the EXACT text
+  the Continue tap will send (`I selected: ${JSON.stringify(value)}`). The backend (with
+  `WIREAI_PREFETCH_ENABLED`) generates Q2 during the pick→Continue window, so the real tap hits a
+  warm cache and returns instantly. Fire-and-forget: if the user changes the selection after the
+  last preview, the real turn just generates normally (never worse than before). Requires the
+  backend prefetch endpoint (already shipped) enabled.
+
+### Added — reusable integration substrate (2026-06-27)
+- **`isOnboardingEnabled({ remote })`** — one standard gate (transport present + env flag + optional remote-config boolean the app passes in). Replaces per-app `isWireBackendConfigured`.
+- **`WIRE_ONBOARDING_EVENTS` + `toAnalyticsEvent(event)`** — canonical `wire_onboarding_*` funnel names so every app logs the same events through its own logger.
+- **`attributionMetadata(a)`** — shape install/ad attribution into `config.metadata` (forwarded into every A2A request).
+- **`reportClientEvent` / `reportClientEvents` / `makeSessionId`** — fire-and-forget client reporting of device-only funnel events (`dropped`) to `POST /v1/events`; `<WireOnboarding>` emits `dropped` on unmount-without-complete. (`screen_skipped` is server-derived; not double-sent.) NOTE: full session correlation requires `wireai-rn@>=0.2.1`, which forwards `metadata.sessionId` so the server adopts it as the A2A `contextId` (0.2.0 dropped metadata at runtime; fixed in 0.2.1).
+
+### Changed — licensing & distribution (2026-06-27)
+- **Open-sourced**: `license` → MIT (was UNLICENSED), `private` → false, added `repository`/`homepage`/`bugs`/`keywords`/`publishConfig`. Primary install channel is now **npm** (`npm install wireai-onboarding`). README/AGENTS install steps updated off `git+ssh`.
+
+### Added — distribution & glue
+- **Build output** — `tsup` now compiles `src/index.ts` → `dist/` (ESM `index.mjs`
+  + CJS `index.js` + `.d.ts`/`.d.mts`), es2019, peers
+  (`react`/`react-native`/`wireai-rn`/`zod`) externalized. `package.json` gains an
+  `"exports"` map; top-level `main`/`module`/`types` point at `dist` for tooling,
+  while a `"react-native"` export condition keeps RN/Metro consumers resolving to
+  `src/index.ts`. External apps can now `npm install` a tarball / `git+ssh` build;
+  the monorepo apps still consume from source. Scripts: `build`, `prepack`,
+  `pack:tarball`. (Still `"private": true` — closed-source.)
+- **`wireai-onboarding/metro` helper** — `withWireOnboarding(config, options)`
+  folds the per-app ~25-line Metro block (pin single-instance deps + map the
+  specifier + watch source) into one non-destructive call. `options.source` switches
+  to source consumption; `options.appRoot` defaults to `process.cwd()`.
+- **`themeFromBrand({ primary, … })`** — derives a full `Partial<OnboardingTheme>`
+  (tinted soft wash + on-primary + optional background/font) from a brand color over
+  the neutral default, via `mergeTheme`.
+- **`wireConfigFromEnv(overrides?)`** — builds a `WireOnboardingConfig` from
+  `EXPO_PUBLIC_WIREAI_API_KEY` / `EXPO_PUBLIC_WIREAI_SERVER_URL` (+ appId), returning
+  `null` when keys are missing so apps stop re-authoring env gating.
+- **`defaultIllustrations`** — a dependency-free fallback registry (`momentum`,
+  `before-after`) of themed `<View>`/`<Text>` glyphs (no SVG/Lottie), so an app can
+  render `InterstitialCard` with zero illustration code. Spread under your own art to
+  override by name.
+
+### Added
+- **`InterstitialCard`** — a mid-flow momentum/value screen (Duolingo/Cal-AI):
+  illustration + a line that reflects the user's answers back + a Continue tap.
+  Registered in `onboardingComponents`. (Requires the matching server-side entry
+  in `KNOWN_COMPONENTS` + the tenant's `allowed_components`.) The backend can now
+  carry **multiple** images per app (managed in the dashboard); the AI picks one by
+  name and the server resolves it to `imageUrl`, so the card renders it with no
+  app-side registry node needed.
+- **`approxScreens`** prop on `<WireOnboarding>` — when the host knows roughly how
+  many screens the flow runs, the progress bar paces as `step / approxScreens`
+  (capped, still no visible number) instead of the asymptotic default. A
+  backend-supplied `progress.total` (the screen budget, returned on every turn
+  incl. init) takes precedence, so apps usually don't need to pass this at all.
+- **Illustration registry** — `IllustrationProvider` / `useIllustration` + the
+  `illustrations` prop on `<WireOnboarding>` (`name → ReactNode`). Apps bring brand
+  SVG/Lottie/Image; the kit stays dependency-free. Falls back to a backend
+  `imageUrl` via RN `<Image>` when no registry match.
+- **`onError`** prop — fires on backend error/timeout so the host can own recovery
+  (e.g. fall back to a static onboarding). Without it, the kit shows an inline retry.
+- **`onEvent`** prop — `started` / `turn` / `error` lifecycle events for host-side
+  analytics (the kit owns the thread loop).
+- **`copy`** prop — localize the kit's built-in English loader/completion strings.
+- `README.md` documenting the architecture, props, illustrations, and the
+  consume-from-source (Metro + tsconfig) setup.
+
+### Notes
+- `DoneBlock` is no longer used internally (the terminal screen is `CompletionView`);
+  the export is kept for back-compat and marked `@deprecated`.
+- The countless asymptotic `StepProgress`, the sparkle `LoadingBlock`, and the
+  animated-checkmark `CompletionView` (CTA-gated `onComplete`) are unchanged.
+
+## [0.1.2]
+
+- **Static env reads** — `wireConfigFromEnv` / `isOnboardingEnabled` read each `EXPO_PUBLIC_*` via STATIC member access. Expo`s inline-env-vars only inlines static `process.env.EXPO_PUBLIC_*`; aliased/computed access was `undefined` on device (fine in Jest). This was the root cause onboarding did not show on a real device.
+- **Gate on transport presence** — removed the `EXPO_PUBLIC_AI_ONBOARDING_ENABLED` flag. `isOnboardingEnabled` keys off apiKey+serverUrl presence, with an optional `remote` kill-switch. The `envFlagVar` option is gone.
+- **Fallback reported to backend** — on degrade to the static fallback, the kit posts `llm_fallback` to `/v1/events` (tagged via `meta`), so the dashboard fallback-rate counts whole-flow degrades, not just single-turn ones.
+
+## [0.1.1]
+
+- **exports**: the `"."` `react-native` condition now resolves TYPES to the shipped
+  `dist/index.d.ts` (consumers drop the tsconfig workaround that pointed
+  `wireai-onboarding` at `dist`), while Metro still loads `./src/index.ts` at runtime.
+- **zod** moved from `devDependencies` to `peerDependencies` (`>=3`) — the consuming app
+  provides zod; the kit only references it for types.
+
+## [0.1.0]
+
+- Initial kit: `<WireOnboarding>` host over `wireai-rn`, theme system, themed cards
+  (`TextInputCard`, `SelectionCard`, `ChipSelectCard`, `NumberStepperCard`,
+  `StatusCard`), per-step validators, scaffold + progress + loading/error/completion.

package/INTEGRATION_PROMPT.md

@@ -0,0 +1,55 @@
+# Claude integration prompt — wireai-onboarding
+
+Copy everything in the block below and paste it into Claude Code (or any coding agent) **from the
+root of your React Native / Expo app**. Fill in the two values at the top first.
+
+> Fastest path instead of this prompt: run the **`wire-rn-integration`** Claude skill — same job,
+> fully automated. Use this prompt when you don't have that skill installed.
+
+---
+
+```
+You are integrating the `wireai-onboarding` package into THIS React Native / Expo app — a drop-in
+AI onboarding flow. Do it end to end, match my app's existing conventions, and leave it
+type-checking green. Read the package's README.md, llms.txt, and AGENTS.md (in node_modules/wireai-onboarding
+after install) before writing code.
+
+MY VALUES:
+- WIREAI_SERVER_URL: <paste the backend URL, e.g. https://...fly.dev>
+- WIREAI_API_KEY:    <paste the wai_… app key from the getwireai console / register_<app>.py>
+- APP_ID:           <paste my app id, e.g. my-app>
+
+STEPS (do them in order, stop and ask if a convention is ambiguous):
+1. Detect my conventions: navigation lib + where the signup/first-run flow lives, my env-var
+   typing, my profile-update / persistence path, my theme tokens (colors/fonts), my path aliases.
+2. Install: `wireai-onboarding` and `wireai-rn` (react + react-native are already peers). Use my
+   package manager (yarn/npm/pnpm — detect it).
+3. Metro: set `module.exports = withWireOnboarding(getDefaultConfig(__dirname))` from
+   `wireai-onboarding/metro` in metro.config.js (preserve my existing config). This pins one copy
+   of react/react-native/wireai-rn/zod — do NOT skip it.
+4. Env: add EXPO_PUBLIC_WIREAI_API_KEY, EXPO_PUBLIC_WIREAI_SERVER_URL, EXPO_PUBLIC_WIREAI_APP_ID
+ to my env files and my env typing.
+5. Theme: build a theme from my brand with `themeFromBrand({ primary: "<my brand color>" })` or a
+   Partial<OnboardingTheme>; match my dark/light.
+6. Screen: scaffold an onboarding screen that renders
+   `<WireOnboarding config={wireConfigFromEnv({ appId: APP_ID })} theme={...} illustrations={...}
+     onComplete={persist} fallbackFlow={<MyExistingStaticOnboarding/>} onEvent={logEvent} />`.
+   - Gate entry with `isOnboardingEnabled({ remote })` (wire my remote-config boolean if I have one).
+   - `persist`: write ALL of `result.answers` (use `deriveAnswers(result.raw)` to fill gaps) through
+     my normal profile-update path. Do NOT re-ask anything a dedicated screen already owns.
+   - `fallbackFlow` MUST be my existing static onboarding so a backend error/timeout degrades, never
+     dead-ends.
+   - Forward install attribution if I have it: `wireConfigFromEnv({ appId, metadata: attributionMetadata({...}) })`.
+   - Analytics: log via `toAnalyticsEvent(e)` → my logger, using the canonical `wire_onboarding_*` names.
+7. Navigation: mount the screen in my first-run/signup flow; branch to the static flow when the gate
+   is off or config is missing.
+8. Verify: type-check (and lint the changed files); test the flag-off + backend-error paths.
+
+Report back: the files you changed (path:line), the typecheck result, and anything you couldn't
+infer about my conventions.
+```
+
+---
+
+After it runs: set the two secrets in your env, run `expo start -c` once (clears the Metro cache
+after the config change), and you're live.