@wireai/activation 0.15.0 → 0.16.0

package/dist/{currentSession-orZy5p1e.d.mts → currentSession-Bz7G6lno.d.mts}

@@ -81,33 +81,6 @@ type DeviceContext = {
  */
 declare const collectDeviceContext: () => DeviceContext;
 
-/**
- * reportClientEvent — forward DEVICE-ONLY onboarding events to the Wire AI analytics
- * backend (`POST {serverUrl}/v1/events`), completing the funnel for events the server
- * can't observe on its own.
- *
- * The backend already records the server-observable funnel during the A2A flow
- * (`session_started`, `screen_shown`, `answer_submitted`, `completed`, `llm_fallback`,
- * and even `screen_skipped` — it derives that from the kit's skip sentinel). The one
- * event no server request can capture is `dropped`: the user closing the app / unmounting
- * the flow without finishing. That's what this reporter is for.
- *
- * Contract (server: routers/onboarding.py → analytics/events.py):
- *   POST {serverUrl}/v1/events
- *   Authorization: Bearer {apiKey}
- *   { "events": [ { event_type, session_id, screen_index?, component?, question_key?,
- *                   latency_ms?, meta?, device?, user_context? } ] }
- * The server fills `app_id` + `environment` from the resolving key (never send app_id),
- * and silently skips malformed events — one bad payload never fails the batch.
- *
- * ⚠️ Correlation: `session_id` MUST equal the A2A `contextId` the server uses to key the
- * server-side events, or the funnel report (which groups by `session_id`) treats this as a
- * phantom session. See `makeSessionId` + WireOnboarding for how the kit seeds it.
- *
- * Fire-and-forget: this never throws into the UI and never awaits — analytics must never
- * be able to break onboarding.
- */
-
 /** Event types a CLIENT may report. The rest of the funnel is server-side; sending those
  *  here would double-count. `screen_skipped` is included for completeness, but the kit does
  *  NOT emit it — the backend already derives it from the skip sentinel (see OnboardingFlow).
@@ -669,10 +642,11 @@ type WireOnboardingProps = {
      * Build the value with the helper so the wire spelling is decided in one place:
      *
      * ```tsx
-     * <WireOnboarding userContext={activationJoinContext(deviceKey)} ... />
-     * // no device id of your own? pass `storage` and leave this prop alone — the kit injects its
-     * // own key, and only after it has confirmed the key actually persists (see `autoJoinKey`).
-     * <WireOnboarding config={{ ...config, storage }} ... />
+     * <WireOnboarding config={config} userContext={activationJoinContext(deviceKey)} ... />
+     * // no device id of your own? pass the `storage` PROP (it is a prop of this component, never a
+     * // field of `WireOnboardingConfig`) and leave this prop alone — the kit injects its own key,
+     * // and only after it has confirmed the key actually persists (see `autoJoinKey`).
+     * <WireOnboarding config={config} storage={storage} ... />
      * ```
      *
      * ⛔ Do NOT hand-build the auto key with `activationJoinContext(resolveAutoDeviceKey({...}))`.
@@ -1402,8 +1376,19 @@ declare const resolveAutoDeviceKey: (opts?: ResolveAutoDeviceKeyOptions) => stri
  * follows it. Only a caller that can afford one storage read should use this; the fire-and-forget
  * event paths must stay on the sync function.
  *
- * Never throws or rejects: a missing, hung, or rejecting adapter resolves to the in-memory id, and
- * with no `storage` it resolves immediately (there is nothing to hydrate from).
+ * Never throws or rejects: a missing or rejecting adapter resolves to the in-memory id, and with no
+ * `storage` it resolves immediately (there is nothing to hydrate from).
+ *
+ * ⛔ A HUNG ADAPTER IS THE ONE CASE IT DOES NOT COVER, and this line used to claim it did. The read
+ * underneath is a bare `storage.getItem` with no ceiling of its own, so an adapter that neither
+ * resolves nor rejects (a locked keychain, a wedged native bridge) leaves THIS PROMISE PENDING
+ * FOREVER — it does not fall back to the in-memory id, it simply never answers. Anything that gates
+ * a user-visible or metric-bearing action on the result must therefore race it against a ceiling of
+ * its own: `<WireOnboarding>` does (`AUTO_JOIN_HYDRATION_TIMEOUT_MS`), and so do the two lifecycle
+ * hooks (`session-analytics/useLifecycleEvents` + `useSessionStart`, through the shared
+ * `withTimeout` + `READ_TIMEOUT_MS` in `session/persistedSession`) — a hung read there had silently
+ * killed `app.session_started` and `app.first_open` for the whole process. Use the SYNC
+ * {@link resolveAutoDeviceKey} when you cannot afford to wait at all.
  *
  * ⚠️ IT RETURNS A BARE STRING, so it CANNOT say whether the id survives the launch — a degraded
  * adapter resolves to the in-memory mint and reads identically to a persisted one. No kit surface
@@ -1425,7 +1410,9 @@ declare const hydrateAutoDeviceKey: (opts?: ResolveAutoDeviceKeyOptions) => Prom
  *
  * Resolves `undefined` only when there is no usable id at all. With no `storage` it resolves
  * immediately with `durable: false` — a process-scoped id is exactly what "no persistence" means.
- * Never throws or rejects.
+ * Never throws or rejects — but, exactly like {@link hydrateAutoDeviceKey} above, it can also never
+ * SETTLE on a hung adapter (the underlying `getItem` carries no ceiling), so every caller races it
+ * against one of its own. See the note there.
  */
 declare const hydrateDeviceIdentity: (opts?: ResolveAutoDeviceKeyOptions) => Promise<IdentityRecord | undefined>;
 /** Test-only: forget every auto id + hydration flag so a unit test starts from a clean registry. */
@@ -1438,7 +1425,10 @@ declare const resetAutoDeviceKeys: () => void;
 declare const setCurrentSessionId: (id: string | undefined) => void;
 /** The current per-open `session_id`, or `undefined` when no app-open has been registered yet. */
 declare const getCurrentSessionId: () => string | undefined;
-/** Test-only: forget the current session id so a unit test starts from a clean registry. */
+/** Test-only: forget the current session id so a unit test starts from a clean registry. Does NOT
+ *  clear the MINTED-id record (see `isMintedSessionId`), for the same reason the warn latch below is
+ *  not cleared: `makeSessionId()` never repeats, so a remembered fallback id can never again equal a
+ *  live one, and the record is overwritten by the next mint anyway. */
 declare const resetCurrentSessionId: () => void;
 /**
  * The current per-open `session_id`, MINTING and registering one when no app-open has been

package/dist/{currentSession-CFSRZ2wg.d.ts → currentSession-z-CZ55ad.d.ts}

@@ -81,33 +81,6 @@ type DeviceContext = {
  */
 declare const collectDeviceContext: () => DeviceContext;
 
-/**
- * reportClientEvent — forward DEVICE-ONLY onboarding events to the Wire AI analytics
- * backend (`POST {serverUrl}/v1/events`), completing the funnel for events the server
- * can't observe on its own.
- *
- * The backend already records the server-observable funnel during the A2A flow
- * (`session_started`, `screen_shown`, `answer_submitted`, `completed`, `llm_fallback`,
- * and even `screen_skipped` — it derives that from the kit's skip sentinel). The one
- * event no server request can capture is `dropped`: the user closing the app / unmounting
- * the flow without finishing. That's what this reporter is for.
- *
- * Contract (server: routers/onboarding.py → analytics/events.py):
- *   POST {serverUrl}/v1/events
- *   Authorization: Bearer {apiKey}
- *   { "events": [ { event_type, session_id, screen_index?, component?, question_key?,
- *                   latency_ms?, meta?, device?, user_context? } ] }
- * The server fills `app_id` + `environment` from the resolving key (never send app_id),
- * and silently skips malformed events — one bad payload never fails the batch.
- *
- * ⚠️ Correlation: `session_id` MUST equal the A2A `contextId` the server uses to key the
- * server-side events, or the funnel report (which groups by `session_id`) treats this as a
- * phantom session. See `makeSessionId` + WireOnboarding for how the kit seeds it.
- *
- * Fire-and-forget: this never throws into the UI and never awaits — analytics must never
- * be able to break onboarding.
- */
-
 /** Event types a CLIENT may report. The rest of the funnel is server-side; sending those
  *  here would double-count. `screen_skipped` is included for completeness, but the kit does
  *  NOT emit it — the backend already derives it from the skip sentinel (see OnboardingFlow).
@@ -669,10 +642,11 @@ type WireOnboardingProps = {
      * Build the value with the helper so the wire spelling is decided in one place:
      *
      * ```tsx
-     * <WireOnboarding userContext={activationJoinContext(deviceKey)} ... />
-     * // no device id of your own? pass `storage` and leave this prop alone — the kit injects its
-     * // own key, and only after it has confirmed the key actually persists (see `autoJoinKey`).
-     * <WireOnboarding config={{ ...config, storage }} ... />
+     * <WireOnboarding config={config} userContext={activationJoinContext(deviceKey)} ... />
+     * // no device id of your own? pass the `storage` PROP (it is a prop of this component, never a
+     * // field of `WireOnboardingConfig`) and leave this prop alone — the kit injects its own key,
+     * // and only after it has confirmed the key actually persists (see `autoJoinKey`).
+     * <WireOnboarding config={config} storage={storage} ... />
      * ```
      *
      * ⛔ Do NOT hand-build the auto key with `activationJoinContext(resolveAutoDeviceKey({...}))`.
@@ -1402,8 +1376,19 @@ declare const resolveAutoDeviceKey: (opts?: ResolveAutoDeviceKeyOptions) => stri
  * follows it. Only a caller that can afford one storage read should use this; the fire-and-forget
  * event paths must stay on the sync function.
  *
- * Never throws or rejects: a missing, hung, or rejecting adapter resolves to the in-memory id, and
- * with no `storage` it resolves immediately (there is nothing to hydrate from).
+ * Never throws or rejects: a missing or rejecting adapter resolves to the in-memory id, and with no
+ * `storage` it resolves immediately (there is nothing to hydrate from).
+ *
+ * ⛔ A HUNG ADAPTER IS THE ONE CASE IT DOES NOT COVER, and this line used to claim it did. The read
+ * underneath is a bare `storage.getItem` with no ceiling of its own, so an adapter that neither
+ * resolves nor rejects (a locked keychain, a wedged native bridge) leaves THIS PROMISE PENDING
+ * FOREVER — it does not fall back to the in-memory id, it simply never answers. Anything that gates
+ * a user-visible or metric-bearing action on the result must therefore race it against a ceiling of
+ * its own: `<WireOnboarding>` does (`AUTO_JOIN_HYDRATION_TIMEOUT_MS`), and so do the two lifecycle
+ * hooks (`session-analytics/useLifecycleEvents` + `useSessionStart`, through the shared
+ * `withTimeout` + `READ_TIMEOUT_MS` in `session/persistedSession`) — a hung read there had silently
+ * killed `app.session_started` and `app.first_open` for the whole process. Use the SYNC
+ * {@link resolveAutoDeviceKey} when you cannot afford to wait at all.
  *
  * ⚠️ IT RETURNS A BARE STRING, so it CANNOT say whether the id survives the launch — a degraded
  * adapter resolves to the in-memory mint and reads identically to a persisted one. No kit surface
@@ -1425,7 +1410,9 @@ declare const hydrateAutoDeviceKey: (opts?: ResolveAutoDeviceKeyOptions) => Prom
  *
  * Resolves `undefined` only when there is no usable id at all. With no `storage` it resolves
  * immediately with `durable: false` — a process-scoped id is exactly what "no persistence" means.
- * Never throws or rejects.
+ * Never throws or rejects — but, exactly like {@link hydrateAutoDeviceKey} above, it can also never
+ * SETTLE on a hung adapter (the underlying `getItem` carries no ceiling), so every caller races it
+ * against one of its own. See the note there.
  */
 declare const hydrateDeviceIdentity: (opts?: ResolveAutoDeviceKeyOptions) => Promise<IdentityRecord | undefined>;
 /** Test-only: forget every auto id + hydration flag so a unit test starts from a clean registry. */
@@ -1438,7 +1425,10 @@ declare const resetAutoDeviceKeys: () => void;
 declare const setCurrentSessionId: (id: string | undefined) => void;
 /** The current per-open `session_id`, or `undefined` when no app-open has been registered yet. */
 declare const getCurrentSessionId: () => string | undefined;
-/** Test-only: forget the current session id so a unit test starts from a clean registry. */
+/** Test-only: forget the current session id so a unit test starts from a clean registry. Does NOT
+ *  clear the MINTED-id record (see `isMintedSessionId`), for the same reason the warn latch below is
+ *  not cleared: `makeSessionId()` never repeats, so a remembered fallback id can never again equal a
+ *  live one, and the record is overwritten by the next mint anyway. */
 declare const resetCurrentSessionId: () => void;
 /**
  * The current per-open `session_id`, MINTING and registering one when no app-open has been

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import React__default, { ReactNode } from 'react';
-import { I as WireOnboardingProps, J as WireOnboardingConfig, O as OnboardingResult, K as WirePermissionStatus, P as PermissionStage, L as WirePermissionOutcome, S as StepValidator, M as OnboardingEvent, N as OnboardingCopy, C as ClientEventTarget, Q as DeviceContext, T as PermissionScreenConfig, W as WireUserContext, c as ClientEvent, U as PermissionPlacement, g as EnvelopeSource } from './currentSession-orZy5p1e.mjs';
-export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, b as ClearUserContextOptions, d as ClientEventType, V as DEFAULT_PERMISSION_COPY, X as DeviceFormFactor, D as DeviceKeyStorage, Y as EXTRA_KEY_PREFIX, Z as GENERIC_PERMISSION_COPY, _ as IdentifyOnboardingBinding, $ as IdentifyOnboardingOptions, a0 as IdentityRecord, a1 as IdentitySource, a2 as IdentitySpace, a3 as NOTIFICATIONS_PERMISSION_COPY, a4 as OnboardingProgress, a5 as PermissionScreenCopy, R as ResolveAutoDeviceKeyOptions, a6 as ResolveUserContextOptions, a7 as ResolvedUserContext, a8 as USER_ID_MAX_LENGTH, i as WIRE_ONBOARDING_EVENTS, a9 as WIRE_PERMISSION_EVENTS, j as WireOnboardingEventName, aa as WirePermissionEventName, ab as WirePermissionKind, ac as activationJoinContext, k as analyticsUserIdStorageKey, m as clearPiiFromContext, n as clearUserContext, ad as collectDeviceContext, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, ae as hashEmailFnv1a, af as hostIdentity, ag as hydrateAutoDeviceKey, ah as hydrateDeviceIdentity, ai as identifyOnboarding, aj as isWireScalar, s as looksLikeEmail, t as makeSessionId, ak as mintDeviceId, al as namespaceExtra, am as normalizePermissionStatus, an as permissionEventName, ao as permissionEventProps, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, ap as resetIdentityProvenance, F as resolveAutoDeviceKey, aq as resolveIdentity, ar as resolvePermissionCopy, as as resolveUserContext, at as sanitizeUserId, G as setCurrentSessionId, H as toAnalyticsEvent } from './currentSession-orZy5p1e.mjs';
+import { I as WireOnboardingProps, J as WireOnboardingConfig, O as OnboardingResult, K as WirePermissionStatus, P as PermissionStage, L as WirePermissionOutcome, S as StepValidator, M as OnboardingEvent, N as OnboardingCopy, C as ClientEventTarget, Q as DeviceContext, T as PermissionScreenConfig, W as WireUserContext, c as ClientEvent, U as PermissionPlacement, g as EnvelopeSource } from './currentSession-Bz7G6lno.mjs';
+export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, b as ClearUserContextOptions, d as ClientEventType, V as DEFAULT_PERMISSION_COPY, X as DeviceFormFactor, D as DeviceKeyStorage, Y as EXTRA_KEY_PREFIX, Z as GENERIC_PERMISSION_COPY, _ as IdentifyOnboardingBinding, $ as IdentifyOnboardingOptions, a0 as IdentityRecord, a1 as IdentitySource, a2 as IdentitySpace, a3 as NOTIFICATIONS_PERMISSION_COPY, a4 as OnboardingProgress, a5 as PermissionScreenCopy, R as ResolveAutoDeviceKeyOptions, a6 as ResolveUserContextOptions, a7 as ResolvedUserContext, a8 as USER_ID_MAX_LENGTH, i as WIRE_ONBOARDING_EVENTS, a9 as WIRE_PERMISSION_EVENTS, j as WireOnboardingEventName, aa as WirePermissionEventName, ab as WirePermissionKind, ac as activationJoinContext, k as analyticsUserIdStorageKey, m as clearPiiFromContext, n as clearUserContext, ad as collectDeviceContext, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, ae as hashEmailFnv1a, af as hostIdentity, ag as hydrateAutoDeviceKey, ah as hydrateDeviceIdentity, ai as identifyOnboarding, aj as isWireScalar, s as looksLikeEmail, t as makeSessionId, ak as mintDeviceId, al as namespaceExtra, am as normalizePermissionStatus, an as permissionEventName, ao as permissionEventProps, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, ap as resetIdentityProvenance, F as resolveAutoDeviceKey, aq as resolveIdentity, ar as resolvePermissionCopy, as as resolveUserContext, at as sanitizeUserId, G as setCurrentSessionId, H as toAnalyticsEvent } from './currentSession-Bz7G6lno.mjs';
 import { O as OnboardingTheme } from './types-BKfpdZzX.mjs';
 export { a as OnboardingButtonStyle, b as OnboardingColors, c as OnboardingFonts, d as OnboardingRadius, e as OnboardingSpacing } from './types-BKfpdZzX.mjs';
 export { C as CenteredModal, a as CenteredModalHandle, b as CenteredModalProps } from './CenteredModal-C3qQBHsA.mjs';
@@ -1301,6 +1301,7 @@ declare const readProgress: (response?: WireAIResponse) => PartialProgress;
  */
 declare const fetchWireFeatures: (config?: WireFeaturesConfig) => Promise<WireFeatures>;
 
+/** The flags alone — the original hook, unchanged for every consumer that cannot act on `settled`. */
 declare const useWireFeatures: (config?: WireFeaturesConfig) => WireFeatures;
 
 /**
@@ -2165,6 +2166,8 @@ interface ReportFirstOpenOptions extends LifecycleEventInput {
  *   • Race guard: an in-memory latch is set SYNCHRONOUSLY before the async read, so two
  *     near-simultaneous calls fire at most once.
  *   • Without `storage`: degraded mode — fires once per PROCESS via the latch only (documented).
+ *   • WITHOUT A TRANSPORT: no-op, and — the point of the check — the once-ever flag is NOT spent.
+ *     See below.
  */
 declare const reportFirstOpen: (opts: ReportFirstOpenOptions) => void;
 /** Options for {@link wireLifecycleEvents}: the shared lifecycle inputs + first-open persistence. */

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import React__default, { ReactNode } from 'react';
-import { I as WireOnboardingProps, J as WireOnboardingConfig, O as OnboardingResult, K as WirePermissionStatus, P as PermissionStage, L as WirePermissionOutcome, S as StepValidator, M as OnboardingEvent, N as OnboardingCopy, C as ClientEventTarget, Q as DeviceContext, T as PermissionScreenConfig, W as WireUserContext, c as ClientEvent, U as PermissionPlacement, g as EnvelopeSource } from './currentSession-CFSRZ2wg.js';
-export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, b as ClearUserContextOptions, d as ClientEventType, V as DEFAULT_PERMISSION_COPY, X as DeviceFormFactor, D as DeviceKeyStorage, Y as EXTRA_KEY_PREFIX, Z as GENERIC_PERMISSION_COPY, _ as IdentifyOnboardingBinding, $ as IdentifyOnboardingOptions, a0 as IdentityRecord, a1 as IdentitySource, a2 as IdentitySpace, a3 as NOTIFICATIONS_PERMISSION_COPY, a4 as OnboardingProgress, a5 as PermissionScreenCopy, R as ResolveAutoDeviceKeyOptions, a6 as ResolveUserContextOptions, a7 as ResolvedUserContext, a8 as USER_ID_MAX_LENGTH, i as WIRE_ONBOARDING_EVENTS, a9 as WIRE_PERMISSION_EVENTS, j as WireOnboardingEventName, aa as WirePermissionEventName, ab as WirePermissionKind, ac as activationJoinContext, k as analyticsUserIdStorageKey, m as clearPiiFromContext, n as clearUserContext, ad as collectDeviceContext, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, ae as hashEmailFnv1a, af as hostIdentity, ag as hydrateAutoDeviceKey, ah as hydrateDeviceIdentity, ai as identifyOnboarding, aj as isWireScalar, s as looksLikeEmail, t as makeSessionId, ak as mintDeviceId, al as namespaceExtra, am as normalizePermissionStatus, an as permissionEventName, ao as permissionEventProps, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, ap as resetIdentityProvenance, F as resolveAutoDeviceKey, aq as resolveIdentity, ar as resolvePermissionCopy, as as resolveUserContext, at as sanitizeUserId, G as setCurrentSessionId, H as toAnalyticsEvent } from './currentSession-CFSRZ2wg.js';
+import { I as WireOnboardingProps, J as WireOnboardingConfig, O as OnboardingResult, K as WirePermissionStatus, P as PermissionStage, L as WirePermissionOutcome, S as StepValidator, M as OnboardingEvent, N as OnboardingCopy, C as ClientEventTarget, Q as DeviceContext, T as PermissionScreenConfig, W as WireUserContext, c as ClientEvent, U as PermissionPlacement, g as EnvelopeSource } from './currentSession-z-CZ55ad.js';
+export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, b as ClearUserContextOptions, d as ClientEventType, V as DEFAULT_PERMISSION_COPY, X as DeviceFormFactor, D as DeviceKeyStorage, Y as EXTRA_KEY_PREFIX, Z as GENERIC_PERMISSION_COPY, _ as IdentifyOnboardingBinding, $ as IdentifyOnboardingOptions, a0 as IdentityRecord, a1 as IdentitySource, a2 as IdentitySpace, a3 as NOTIFICATIONS_PERMISSION_COPY, a4 as OnboardingProgress, a5 as PermissionScreenCopy, R as ResolveAutoDeviceKeyOptions, a6 as ResolveUserContextOptions, a7 as ResolvedUserContext, a8 as USER_ID_MAX_LENGTH, i as WIRE_ONBOARDING_EVENTS, a9 as WIRE_PERMISSION_EVENTS, j as WireOnboardingEventName, aa as WirePermissionEventName, ab as WirePermissionKind, ac as activationJoinContext, k as analyticsUserIdStorageKey, m as clearPiiFromContext, n as clearUserContext, ad as collectDeviceContext, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, ae as hashEmailFnv1a, af as hostIdentity, ag as hydrateAutoDeviceKey, ah as hydrateDeviceIdentity, ai as identifyOnboarding, aj as isWireScalar, s as looksLikeEmail, t as makeSessionId, ak as mintDeviceId, al as namespaceExtra, am as normalizePermissionStatus, an as permissionEventName, ao as permissionEventProps, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, ap as resetIdentityProvenance, F as resolveAutoDeviceKey, aq as resolveIdentity, ar as resolvePermissionCopy, as as resolveUserContext, at as sanitizeUserId, G as setCurrentSessionId, H as toAnalyticsEvent } from './currentSession-z-CZ55ad.js';
 import { O as OnboardingTheme } from './types-BKfpdZzX.js';
 export { a as OnboardingButtonStyle, b as OnboardingColors, c as OnboardingFonts, d as OnboardingRadius, e as OnboardingSpacing } from './types-BKfpdZzX.js';
 export { C as CenteredModal, a as CenteredModalHandle, b as CenteredModalProps } from './CenteredModal-Cdgns6--.js';
@@ -1301,6 +1301,7 @@ declare const readProgress: (response?: WireAIResponse) => PartialProgress;
  */
 declare const fetchWireFeatures: (config?: WireFeaturesConfig) => Promise<WireFeatures>;
 
+/** The flags alone — the original hook, unchanged for every consumer that cannot act on `settled`. */
 declare const useWireFeatures: (config?: WireFeaturesConfig) => WireFeatures;
 
 /**
@@ -2165,6 +2166,8 @@ interface ReportFirstOpenOptions extends LifecycleEventInput {
  *   • Race guard: an in-memory latch is set SYNCHRONOUSLY before the async read, so two
  *     near-simultaneous calls fire at most once.
  *   • Without `storage`: degraded mode — fires once per PROCESS via the latch only (documented).
+ *   • WITHOUT A TRANSPORT: no-op, and — the point of the check — the once-ever flag is NOT spent.
+ *     See below.
  */
 declare const reportFirstOpen: (opts: ReportFirstOpenOptions) => void;
 /** Options for {@link wireLifecycleEvents}: the shared lifecycle inputs + first-open persistence. */

package/dist/index.js

@@ -1168,6 +1168,28 @@ var readProgress = (response) => {
   };
 };
 
+// src/utils/withDeadline.ts
+var DEADLINE_EXPIRED = /* @__PURE__ */ Symbol("wire-deadline-expired");
+var DEFAULT_DEADLINE_MS = 15e3;
+var withDeadline = async (exchange, timeoutMs = DEFAULT_DEADLINE_MS) => {
+  const controller = typeof AbortController !== "undefined" ? new AbortController() : void 0;
+  let timer;
+  const expired = new Promise((resolve) => {
+    timer = setTimeout(() => {
+      controller == null ? void 0 : controller.abort();
+      resolve(DEADLINE_EXPIRED);
+    }, timeoutMs);
+  });
+  const running = exchange(controller == null ? void 0 : controller.signal);
+  try {
+    return await Promise.race([running, expired]);
+  } finally {
+    clearTimeout(timer);
+    void running.catch(() => {
+    });
+  }
+};
+
 // src/analytics/reportClientEvent.ts
 var makeSessionId = () => `wire_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
 var toWireEvents = (events) => events.map((event) => {
@@ -1239,14 +1261,17 @@ var reportClientEventsOutcome = async (target, events) => {
   try {
     const req = buildEventsRequest(target, events);
     if (!req) return "refused";
-    const res = await fetch(req.url, req.init);
-    if (!res || !res.ok) return "unreachable";
-    const ack = await readEventsAck(res);
-    if (!ack || ack.skipped <= 0) return "delivered";
-    if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
-      console.warn(describeDiscarded(ack));
-    }
-    return "refused";
+    const outcome = await withDeadline(async (signal) => {
+      const res = await fetch(req.url, { ...req.init, signal });
+      if (!res || !res.ok) return "unreachable";
+      const ack = await readEventsAck(res);
+      if (!ack || ack.skipped <= 0) return "delivered";
+      if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
+        console.warn(describeDiscarded(ack));
+      }
+      return "refused";
+    });
+    return outcome === DEADLINE_EXPIRED ? "unreachable" : outcome;
   } catch {
     return "unreachable";
   }
@@ -3478,11 +3503,11 @@ var provenanceRegistry = () => {
   return created;
 };
 var provenanceKey = (space, scope) => `${space}:${scope != null ? scope : "default"}`;
+var isUsableIdentityValue = (value) => typeof value === "string" && value.trim().length > 0;
 var resolveIdentity = (input) => {
   var _a;
-  if (typeof input.value !== "string") return void 0;
+  if (!isUsableIdentityValue(input.value)) return void 0;
   const value = input.value.trim();
-  if (!value) return void 0;
   const durable = (_a = input.durable) != null ? _a : input.source === "host";
   if (input.source === "host") {
     provenanceRegistry().host.set(provenanceKey(input.space, input.scope), value);
@@ -3587,6 +3612,7 @@ var resetAutoDeviceKeys = () => {
   registry.keys.clear();
   registry.hydrating.clear();
   (_a = registry.pending) == null ? void 0 : _a.clear();
+  registry.ambient = void 0;
 };
 
 // src/analytics/currentSession.ts
@@ -3594,25 +3620,51 @@ var CURRENT_SESSION_ID_SLOT = /* @__PURE__ */ Symbol.for(
   "@wireai/activation:currentSessionId"
 );
 var globalSlot = globalThis;
+var SESSION_ID_LISTENERS_SLOT = /* @__PURE__ */ Symbol.for(
+  "@wireai/activation:currentSessionIdListeners"
+);
+var listenerSlot = globalThis;
+var listeners = () => {
+  const existing = listenerSlot[SESSION_ID_LISTENERS_SLOT];
+  if (existing) return existing;
+  const created = /* @__PURE__ */ new Set();
+  listenerSlot[SESSION_ID_LISTENERS_SLOT] = created;
+  return created;
+};
+var writeCurrentSessionId = (id) => {
+  if (globalSlot[CURRENT_SESSION_ID_SLOT] === id) return;
+  globalSlot[CURRENT_SESSION_ID_SLOT] = id;
+  for (const listener of Array.from(listeners())) {
+    try {
+      listener();
+    } catch {
+    }
+  }
+};
 var setCurrentSessionId = (id) => {
   if (typeof id === "string" && id.length > 0) {
-    globalSlot[CURRENT_SESSION_ID_SLOT] = id;
+    writeCurrentSessionId(id);
   }
 };
 var getCurrentSessionId = () => globalSlot[CURRENT_SESSION_ID_SLOT];
 var resetCurrentSessionId = () => {
-  globalSlot[CURRENT_SESSION_ID_SLOT] = void 0;
+  writeCurrentSessionId(void 0);
 };
 var MINT_WARNING = "[wireai] No app-open session was registered, so a session id was minted for this event (the server drops an event that has no session_id, and still answers 200). Mount useLifecycleEvents at your app root so events correlate to a real app-open.";
 var MINT_WARNED_SLOT = /* @__PURE__ */ Symbol.for(
   "@wireai/activation:currentSessionIdMintWarned"
 );
 var warnSlot = globalThis;
+var MINTED_SESSION_ID_SLOT = /* @__PURE__ */ Symbol.for(
+  "@wireai/activation:mintedSessionId"
+);
+var mintedSlot = globalThis;
 var ensureCurrentSessionId = () => {
   const existing = globalSlot[CURRENT_SESSION_ID_SLOT];
   if (typeof existing === "string" && existing.length > 0) return existing;
   const minted = makeSessionId();
-  globalSlot[CURRENT_SESSION_ID_SLOT] = minted;
+  writeCurrentSessionId(minted);
+  mintedSlot[MINTED_SESSION_ID_SLOT] = minted;
   if (!warnSlot[MINT_WARNED_SLOT] && warnInDev(MINT_WARNING)) {
     warnSlot[MINT_WARNED_SLOT] = true;
   }
@@ -4452,17 +4504,31 @@ var failOpen = async (storage, key) => {
   const cached2 = await readCachedFeatures(storage, key);
   return (_a = cached2 == null ? void 0 : cached2.features) != null ? _a : defaultWireFeatures;
 };
-var fetchWithTimeout = async (url, apiKey, timeoutMs) => {
+var NO_ANSWER = /* @__PURE__ */ Symbol("wire-features-no-answer");
+var fetchFeaturesJson = async (url, apiKey, timeoutMs) => {
   const controller = typeof AbortController !== "undefined" ? new AbortController() : void 0;
-  const timer = setTimeout(() => controller == null ? void 0 : controller.abort(), timeoutMs);
-  try {
-    return await fetch(url, {
+  let timer;
+  const expired = new Promise((resolve) => {
+    timer = setTimeout(() => {
+      controller == null ? void 0 : controller.abort();
+      resolve(NO_ANSWER);
+    }, timeoutMs);
+  });
+  const exchange = (async () => {
+    const res = await fetch(url, {
       method: "GET",
       headers: { Accept: "application/json", Authorization: `Bearer ${apiKey}` },
       signal: controller == null ? void 0 : controller.signal
     });
+    if (!res || !res.ok) return NO_ANSWER;
+    return await res.json();
+  })();
+  try {
+    return await Promise.race([exchange, expired]);
   } finally {
     clearTimeout(timer);
+    void exchange.catch(() => {
+    });
   }
 };
 var fetchWireFeatures = async (config) => {
@@ -4472,9 +4538,8 @@ var fetchWireFeatures = async (config) => {
   const url = `${config.serverUrl.replace(/\/$/, "")}/v1/features`;
   const timeoutMs = config.timeoutMs && config.timeoutMs > 0 ? config.timeoutMs : DEFAULT_TIMEOUT_MS;
   try {
-    const res = await fetchWithTimeout(url, config.apiKey, timeoutMs);
-    if (!res || !res.ok) return failOpen(storage, key);
-    const json = await res.json();
+    const json = await fetchFeaturesJson(url, config.apiKey, timeoutMs);
+    if (json === NO_ANSWER) return failOpen(storage, key);
     const features = parseWireFeatures(json);
     if (storage) writeCachedFeatures(storage, key, features);
     return features;
@@ -4488,50 +4553,65 @@ var useStableValue = (value, isEqual) => {
   return ref.current;
 };
 var sameFetchKey = (a, b) => (a == null ? void 0 : a.serverUrl) === (b == null ? void 0 : b.serverUrl) && (a == null ? void 0 : a.apiKey) === (b == null ? void 0 : b.apiKey) && (a == null ? void 0 : a.appId) === (b == null ? void 0 : b.appId);
-var useWireFeatures = (config) => {
+var useWireFeaturesState = (config) => {
   const stableConfig = useStableValue(config, sameFetchKey);
   const [flags, setFlags] = React19.useState(defaultWireFeatures);
   const canFetch = !!(stableConfig == null ? void 0 : stableConfig.serverUrl) && !!(stableConfig == null ? void 0 : stableConfig.apiKey);
+  const [settled, setSettled] = React19.useState(!canFetch);
   React19.useEffect(() => {
     if (!canFetch) {
       setFlags((prev) => featuresEqual(prev, defaultWireFeatures) ? prev : defaultWireFeatures);
+      setSettled(true);
       return;
     }
     let alive = true;
     void fetchWireFeatures(stableConfig).then((next) => {
       if (!alive) return;
       setFlags((prev) => featuresEqual(prev, next) ? prev : next);
+      setSettled(true);
     });
     return () => {
       alive = false;
     };
   }, [canFetch, stableConfig]);
-  return flags;
+  return React19.useMemo(() => ({ flags, settled }), [flags, settled]);
 };
+var useWireFeatures = (config) => useWireFeaturesState(config).flags;
 var CONTEXT_SYMBOL = /* @__PURE__ */ Symbol.for("wireai.features.context");
-var globalObj = globalThis;
-if (!globalObj[CONTEXT_SYMBOL]) {
-  globalObj[CONTEXT_SYMBOL] = React19.createContext(null);
+var featuresContextGlobal = globalThis;
+if (!featuresContextGlobal[CONTEXT_SYMBOL]) {
+  featuresContextGlobal[CONTEXT_SYMBOL] = React19.createContext(null);
 }
-var WireFeaturesContext = globalObj[CONTEXT_SYMBOL];
+var WireFeaturesContext = featuresContextGlobal[CONTEXT_SYMBOL];
+var SETTLED_SYMBOL = /* @__PURE__ */ Symbol.for("wireai.features.settled.context");
+var settledContextGlobal = globalThis;
+if (!settledContextGlobal[SETTLED_SYMBOL]) {
+  settledContextGlobal[SETTLED_SYMBOL] = React19.createContext(true);
+}
+var WireFeaturesSettledContext = settledContextGlobal[SETTLED_SYMBOL];
 var WireFeaturesProvider = ({
   config,
   flags,
   children
 }) => {
-  const fetched = useWireFeatures(flags ? void 0 : config);
-  const value = flags != null ? flags : fetched;
+  const fetched = useWireFeaturesState(flags ? void 0 : config);
+  const value = flags != null ? flags : fetched.flags;
+  const settled = flags ? true : fetched.settled;
   const stable = React19.useMemo(() => value, [value]);
-  return /* @__PURE__ */ jsxRuntime.jsx(WireFeaturesContext.Provider, { value: stable, children });
+  return /* @__PURE__ */ jsxRuntime.jsx(WireFeaturesSettledContext.Provider, { value: settled, children: /* @__PURE__ */ jsxRuntime.jsx(WireFeaturesContext.Provider, { value: stable, children }) });
 };
 WireFeaturesProvider.displayName = "WireFeaturesProvider";
 var useWireFeaturesContext = () => React19.useContext(WireFeaturesContext);
-var useResolvedFeatures = (options) => {
+var useResolvedFeatures = (options) => useResolvedFeaturesState(options).flags;
+var useResolvedFeaturesState = (options) => {
   var _a, _b, _c;
   const ctx = useWireFeaturesContext();
+  const ctxSettled = React19.useContext(WireFeaturesSettledContext);
   const shouldFetch = !(options == null ? void 0 : options.flags) && ctx == null;
-  const fetched = useWireFeatures(shouldFetch ? options == null ? void 0 : options.config : void 0);
-  return (_c = (_b = (_a = options == null ? void 0 : options.flags) != null ? _a : ctx) != null ? _b : fetched) != null ? _c : defaultWireFeatures;
+  const fetched = useWireFeaturesState(shouldFetch ? options == null ? void 0 : options.config : void 0);
+  const flags = (_c = (_b = (_a = options == null ? void 0 : options.flags) != null ? _a : ctx) != null ? _b : fetched.flags) != null ? _c : defaultWireFeatures;
+  const settled = (options == null ? void 0 : options.flags) ? true : ctx != null ? ctxSettled : fetched.settled;
+  return React19.useMemo(() => ({ flags, settled }), [flags, settled]);
 };
 
 // src/config/wireConfigFromEnv.ts
@@ -5275,8 +5355,12 @@ var useSessionStart = (config, options = {}) => {
         fireOpen(void 0);
         return;
       }
-      void hydrateDeviceIdentity({ appId: cfg.appId, storage: cfg.storage }).then((identity) => {
+      void withTimeout(
+        hydrateDeviceIdentity({ appId: cfg.appId, storage: cfg.storage }),
+        READ_TIMEOUT_MS
+      ).then((read) => {
         if (cancelled) return;
+        const identity = read === READ_TIMED_OUT ? void 0 : read;
         fireOpen((identity == null ? void 0 : identity.durable) ? identity.value : void 0);
       });
     };
@@ -5376,8 +5460,9 @@ var emitFirstOpen = (opts) => {
   routeLifecycleEvent(buildLifecycleEvent(FIRST_OPEN_EVENT, opts), opts);
 };
 var reportFirstOpen = (opts) => {
-  var _a;
-  const appId = (_a = opts.appId) != null ? _a : "default";
+  var _a, _b;
+  if (!opts.sink && !((_a = opts.target) == null ? void 0 : _a.serverUrl)) return;
+  const appId = (_b = opts.appId) != null ? _b : "default";
   if (_firstOpenLatched.has(appId)) return;
   _firstOpenLatched.add(appId);
   const storage = opts.storage;
@@ -5462,8 +5547,12 @@ var useLifecycleEvents = (config, options = {}) => {
         fire(void 0);
         return;
       }
-      void hydrateDeviceIdentity({ appId: cfg.appId, storage: cfg.storage }).then((identity) => {
+      void withTimeout(
+        hydrateDeviceIdentity({ appId: cfg.appId, storage: cfg.storage }),
+        READ_TIMEOUT_MS
+      ).then((read) => {
         if (cancelled) return;
+        const identity = read === READ_TIMED_OUT ? void 0 : read;
         fire((identity == null ? void 0 : identity.durable) ? identity.value : void 0);
       });
     };