@wireai/activation 0.14.0 → 0.14.2

package/CHANGELOG.md

@@ -3,6 +3,87 @@
 All notable changes to `@wireai/activation` (formerly `wireai-onboarding`).
 Historical entries below the rename keep the old package name on purpose.
 
+## [0.14.2] - 2026-08-18
+
+**PATCH: no public surface gained, lost or renamed a member.** `SpotlightOverlay` keeps its props
+and its export; `expo-blur` stays an OPTIONAL peer.
+
+### Fixed
+
+- **The coachmarks subpath no longer force-imports its optional peer `expo-blur`.**
+  `SpotlightOverlay` did `import { BlurView } from "expo-blur"` at module scope and built its
+  animated blur component at module load, and `coachmarks/index.ts` re-exports the overlay with no
+  wildcard escape — so importing ANYTHING from `@wireai/activation/coachmarks`, even
+  `setCoachmarkStorage`, dragged `expo-blur` in. A host that took the peer's "optional" at its word
+  and skipped installing it hit a Metro resolution failure the moment it touched coachmarks, which
+  is why the AI Mobile Launcher tiers (and any Expo Go build) could not adopt the capability. The
+  peer is now resolved through a guarded lazy require with a string-literal specifier inside a
+  try/catch (the same shape as `icons/expoIcons.ts` / `device/appVersion.ts`), and the animated
+  component is built once on first render, so the subpath carries no static top-level import of the
+  peer.
+  - **Degradation, by design:** when `expo-blur` is absent the spotlight drops the frost to an
+    equivalent dimmed scrim. The ring, tooltip and gestures behave identically — a missing
+    decorative frost never blanks a tour, never crashes, never renders empty.
+  - `metro/index.js` `OPTIONAL_MODULES` and `tsup.config.ts` now treat `expo-blur` as a guarded
+    optional peer (moved off the static-peer list), so the built `dist/` collects it as optional and
+    the metro helper's empty-module safety net covers it for hosts that disable Metro's
+    `allowOptionalDependencies`.
+
+## [0.14.1] - 2026-08-18
+
+Two rulings from the 0.14.0 audit, applied. Both were reproduced there and left for a decision
+rather than guessed at; both decisions came back on 2026-08-18.
+
+**PATCH: no public surface gained, lost or renamed a member.** But read the first entry before you
+upgrade — it is a behaviour change you will see in your funnel, not a silent internal fix.
+
+### Fixed
+
+- **The review/questionnaire gates counted JS PROCESSES, not app-opens, so `minSessions` stalled at
+  1 on iOS.** `useLifecycleEvents` already defines an app-open correctly — a foreground after 30+
+  minutes in the background — and fires a fresh `app.session_started` for it. The device-side
+  counter behind `minSessions` did not follow: it pinned one id for the life of the JS process, and
+  iOS suspends apps rather than killing them. So a user who opened the app every day for a week
+  produced seven server-side opens while `wire_review_<id>_sessions` stayed at 1, and any gate with
+  the fail-closed `minSessions: 2` default could never fire on a phone that is never force-quit —
+  which is most phones. **⚠️ UPGRADE NOTE: gates that have been silently dormant will start firing.**
+  That is the fix, but if you have been reading a flat prompt rate as "users decline", the number
+  will move. The counter still refuses the case it was pinned for in the first place: on a cold
+  start the gate renders (and counts) before the root lifecycle effect registers the session id, and
+  that first registration NAMES the open already counted rather than starting a second one — so the
+  2026-07-16 incident, where `minSessions: 2` became satisfiable inside a user's very first launch,
+  stays closed. One accepted under-count remains, deliberately: if the mount open never registers (a
+  refused non-durable device key over a broken store) and a later foreground is the first
+  registration the launch sees, it is adopted rather than counted. A fail-closed gate may only err
+  toward prompting less.
+
+- **A permission record that could not be READ is no longer read as "nothing settled".** A timed-out
+  or throwing storage read arrived as `[]`, which is indistinguishable from a genuine empty record,
+  and the flow acted on that guess twice: it re-showed a permission screen the user may already have
+  answered — spending the ONE native prompt iOS ever grants — and the answer then persisted a record
+  containing just that one id, OVER whatever the store actually held. A slow adapter could therefore
+  permanently shrink the memory that exists to prevent the re-ask. The read now reports whether the
+  store answered at all; on "it did not", permission screens are suppressed for that session and
+  nothing is written back. A successful read of a corrupt, absent or other-session entry is still a
+  genuine empty and still shows the screen. The trade is stated rather than hidden: on a host whose
+  adapter never answers, configured permission screens silently never show, so it warns in dev
+  naming the adapter.
+
+### Changed
+
+- **`@wireai/activation:processOpenId` is re-declared LIVE (was LATCH).** The governance canary in
+  `test/canary/globalSlotDiscipline.test.tsx` asserted that this slot must NOT follow the session
+  registry, which is what froze the counter above; it now drives the slot through two real opens and
+  requires it to move. The cold-start property it used to guard — the first registration of a launch
+  must not re-pin — is asserted in `src/reviews/sessionCount.test.ts`, alongside the incident it
+  exists for. The slot holds the pinned open id plus the registered id observed when it was pinned,
+  because "is this a new open?" is only answerable against what was last seen.
+
+Tests 808 → 814, all green, and the deferred `todo` reproduction is now a passing assertion.
+Every fix was falsified first: reverting the counter fix reddens exactly the app-open test plus the
+slot canary and leaves the cold-start test green; collapsing the unknown read back to empty reddens
+both unit tests and the end-to-end canary while its positive control stays green.
+
 ## [0.14.0] - 2026-08-17
 
 A durability release, in two rounds. Round 1 stopped the two counted lifecycle events from riding a

package/README.md

@@ -1162,6 +1162,11 @@ const gate = useReviewGate({ config: { id: "home", minSessions: 2 }, decision, s
 await track("journal_done"); // POST stored → revalidation bumps → effect re-fetches → gate can fire
 ```
 
+`minSessions` counts **app-opens**, not mounts and not launches: a foreground after 30+ minutes in
+the background is a new one. That matters on iOS, where an app is suspended rather than killed — a
+user who never force-quits still advances the counter. (Before 0.14.1 it counted JS processes, so
+on those devices it stayed at 1 forever and a `minSessions: 2` gate could never fire.)
+
 The questionnaire gate uses the identical shape: swap `fetchReviewDecision` / `useReviewGate`
 for `fetchQuestionnaireDecision` / `useQuestionnaireGate` from `@wireai/activation/questionnaire`
 (both take a `decision` prop). One `wire.track` call feeds every subscribed gate.