@agent-native/core 0.216.0 → 0.218.0

package/dist/app-config/analytics.js

@@ -32,6 +32,6 @@ export const analyticsConfig = z.object({
         .optional()
         .meta({
         env: "AGENT_NATIVE_HEAD_SCRIPT_SRC",
-        doc: "HTTPS URL of a script loaded with `defer` on every server-rendered page, for deployment-specific tooling such as support or feedback widgets.",
+        doc: "HTTPS URL of a script added to every server-rendered page, for deployment-specific tooling such as support or feedback widgets. Where the consent banner shows, it waits for analytics consent, like Google Analytics.",
     }),
 });

package/dist/client/agent-chat/index.d.ts

@@ -19,7 +19,7 @@ export { AGENT_NATIVE_MCP_APP_HOST_MESSAGE_TYPES, getMcpAppHostContext, initiali
 export { buildDynamicAgentSuggestions, dedupeSuggestions, mergeAgentSuggestions, normalizeAgentDynamicSuggestionsConfig, useAgentDynamicSuggestions, useAgentDynamicSuggestionsResult, type AgentDynamicSuggestionContext, type AgentDynamicSuggestionsConfig, type AgentDynamicSuggestionsOption, } from "../dynamic-suggestions.js";
 export { clearChatStorage } from "../chat/storage.js";
 export { isAssistantChatHistoryVersion, coerceAssistantChatHistoryDate, type AssistantChatHistoryDate, type AssistantChatHistoryVersion, } from "../chat/assistant-chat-history-version.js";
-export { ChatThreadListConfigError, useChatThreadList, type UseChatThreadListOptions, type UseChatThreadListResult, } from "../use-chat-thread-list.js";
+export { ChatThreadListConfigError, useChatThreadList, type UseChatThreadListOptions, type UseChatThreadListResult, type ChatThreadListRefreshOutcome, } from "../use-chat-thread-list.js";
 export { ChatThreadListError, fetchChatThreadListPage, notifyChatThreadsUpdated, useChatThreads, type ChatThreadAccessBasis, type ChatThreadListPage, type ChatThreadListRow, type ChatThreadListPageRequest, type ChatThreadOwnership, type ChatThreadVisibility, type ChatThreadScope, type ChatThreadSnapshot, type ChatThreadSummary, type ChatThreadData, type ChatThreadShareLink, type ChatThreadShareState, type UseChatThreadsOptions, } from "../use-chat-threads.js";
 export { type AgentCallProgress, type ContentPart, } from "../sse-event-processor.js";
 export { useRunStuckDetection, useAbortRun, type RunStuckState, type UseRunStuckDetectionOptions, } from "../use-run-stuck-detection.js";

package/dist/client/analytics-session.d.ts

@@ -1,5 +1,12 @@
 /** One id for this page load, shared by every pageview until it reloads. */
 export declare function getAnalyticsPageLoadId(): string;
+/**
+ * The visitor id, `an_aid`, waits for analytics consent where the banner
+ * applies, and for the server's region rather than the time zone's guess,
+ * since a sent id can't be recalled. Until then this returns `undefined` and
+ * stores nothing, so events still count but can't be tied to one visitor
+ * across pages.
+ */
 export declare function getOrCreateAnalyticsAnonymousId(): string | undefined;
 export declare function setAnalyticsSessionId(sessionId: string): string | undefined;
 export declare function clearAnalyticsSessionId(): void;

package/dist/client/analytics-session.js

@@ -1,5 +1,6 @@
-import { serializeAnalyticsAnonymousIdCookie } from "../shared/analytics-anonymous-id.js";
+import { ANALYTICS_ANONYMOUS_ID_COOKIE_NAME, serializeAnalyticsAnonymousIdCookie, } from "../shared/analytics-anonymous-id.js";
 import { ANALYTICS_SESSION_ID_COOKIE_NAME, ANALYTICS_SESSION_ID_MAX_LENGTH, normalizeAnalyticsSessionId, serializeAnalyticsSessionIdCookie, } from "../shared/analytics-session-id.js";
+import { consentDecision, whenConsentAllows } from "./consent.js";
 const ANONYMOUS_ID_STORAGE_KEY = "agent-native.anonymous_id";
 const SESSION_ID_STORAGE_KEY = "agent-native.session_id";
 const SESSION_ID_PIN_STORAGE_KEY = "agent-native.session_id_pin";
@@ -72,9 +73,34 @@ export function getAnalyticsPageLoadId() {
     pageLoadId ??= generateVisitorId();
     return pageLoadId;
 }
+let anonymousIdConsentWatched = false;
+function clearAnalyticsAnonymousId() {
+    safeStorageRemove(ANONYMOUS_ID_STORAGE_KEY);
+    try {
+        document.cookie = `${ANALYTICS_ANONYMOUS_ID_COOKIE_NAME}=; path=/; max-age=0; SameSite=Lax`;
+    }
+    catch {
+        // coercion-ok: a frame that can't read cookies never stored one.
+    }
+}
+/**
+ * The visitor id, `an_aid`, waits for analytics consent where the banner
+ * applies, and for the server's region rather than the time zone's guess,
+ * since a sent id can't be recalled. Until then this returns `undefined` and
+ * stores nothing, so events still count but can't be tied to one visitor
+ * across pages.
+ */
 export function getOrCreateAnalyticsAnonymousId() {
     if (typeof window === "undefined")
         return undefined;
+    if (!anonymousIdConsentWatched) {
+        anonymousIdConsentWatched = true;
+        whenConsentAllows("performance", () => { }, {
+            revoke: clearAnalyticsAnonymousId,
+        });
+    }
+    if (consentDecision("performance") !== true)
+        return undefined;
     let id = safeStorageGet(ANONYMOUS_ID_STORAGE_KEY);
     if (!id) {
         id = generateVisitorId();

package/dist/client/analytics.js

@@ -16,7 +16,7 @@ import { agentNativePath } from "./api-path.js";
 import { agentNativeApiDisabledReason } from "./api-surface.js";
 import { injectedAgentNativeConfig } from "./app-config.js";
 import { clientBuildId } from "./build-compatibility.js";
-import { consentAllowsNow, whenConsentAllows } from "./consent.js";
+import { consentAllowsNow, consentDecision, getConsentChoice, whenConsentAllows, whenConsentDecided, } from "./consent.js";
 import { clientFailureContext } from "./failure-report.js";
 import { replayEndpointFromAnalyticsEndpoint } from "./session-replay-endpoint.js";
 import { scheduleAfterPaint } from "./use-after-paint.js";
@@ -39,6 +39,7 @@ let _amplitudeModule = null;
 let _amplitudeLoadPromise = null;
 let _amplitudeApiKey = null;
 let _pendingAmplitudeEvents = [];
+let _amplitudeConsent = "unasked";
 let _sentryInitialized = false;
 let _sentryModule = null;
 let _sentryLoadPromise = null;
@@ -881,20 +882,82 @@ function isSyntheticBrowserTraffic() {
     return (typeof window !== "undefined" &&
         isSyntheticTrafficValue(window.__AGENT_NATIVE_SYNTHETIC_TRAFFIC__));
 }
+/**
+ * Amplitude keeps its device id in a cookie on the widest domain it can set,
+ * and its marketing touch and unsent events beside it, all named from the
+ * API key. A reject clears them at every level of this host.
+ */
+function clearAmplitudeStorage(apiKey) {
+    const key = apiKey.slice(0, 10);
+    const names = [
+        `AMP_${key}`,
+        `AMP_MKTG_${key}`,
+        `AMP_MKTG_ORIGINAL_${key}`,
+        `AMP_unsent_${key}`,
+        `amp_${apiKey.slice(0, 6)}`,
+    ];
+    try {
+        const labels = window.location.hostname.split(".");
+        const domains = [""];
+        for (let i = 0; i < labels.length - 1; i += 1) {
+            domains.push(`; domain=.${labels.slice(i).join(".")}`);
+        }
+        for (const name of names) {
+            for (const domain of domains) {
+                document.cookie = `${name}=; path=/; max-age=0${domain}`;
+            }
+        }
+    }
+    catch {
+        // coercion-ok: a sandboxed iframe can't read or write cookies, so
+        // Amplitude stored none here.
+    }
+    for (const name of names)
+        safeStorageRemove(name);
+}
 function ensureAmplitude() {
     if (isSyntheticBrowserTraffic())
         return false;
-    if (_amplitudeInitialized)
-        return true;
     const key = import.meta.env
         ?.VITE_AMPLITUDE_API_KEY;
     if (!key)
         return false;
     _amplitudeApiKey = key;
+    if (_amplitudeConsent !== "granted") {
+        if (_amplitudeConsent === "unasked") {
+            _amplitudeConsent = "waiting";
+            // Amplitude keeps a device id in the browser, so where the banner
+            // applies it waits for performance cookies.
+            whenConsentAllows("performance", () => {
+                _amplitudeConsent = "granted";
+                // Held before the region answered: with a choice on record, the
+                // visitor had to choose, so what came before it never goes out.
+                if (getConsentChoice())
+                    _pendingAmplitudeEvents = [];
+                _amplitudeModule?.setOptOut(false);
+                ensureAmplitude();
+            }, {
+                revoke: () => {
+                    _amplitudeConsent = "revoked";
+                    _pendingAmplitudeEvents = [];
+                    _amplitudeModule?.setOptOut(true);
+                    // A later accept starts a new device id, not the one in memory.
+                    _amplitudeModule?.reset();
+                    clearAmplitudeStorage(key);
+                },
+            });
+        }
+        return false;
+    }
+    if (_amplitudeInitialized)
+        return true;
     if (_amplitudeLoadPromise)
         return false;
     _amplitudeLoadPromise = loadOptionalPeer("@amplitude/analytics-browser", () => import("@amplitude/analytics-browser"))
         .then((module) => {
+        // A reject while the SDK loaded: the next accept initializes it.
+        if (_amplitudeConsent !== "granted")
+            return null;
         module.init(key, { autocapture: false });
         _amplitudeModule = module;
         _amplitudeInitialized = true;
@@ -2155,15 +2218,30 @@ function sendAgentNativeAnalytics(name, properties) {
             ?.VITE_AGENT_NATIVE_ANALYTICS_ENDPOINT ||
         AGENT_NATIVE_ANALYTICS_DEFAULT_ENDPOINT, window.location.hostname);
     const userId = typeof properties.userId === "string" ? properties.userId : undefined;
-    const body = JSON.stringify({
-        publicKey,
-        event: name,
-        properties,
-        userId,
-        anonymousId: getOrCreateAnonymousId(),
-        sessionId: getOrCreateSessionId(),
-        timestamp: new Date().toISOString(),
+    const sessionId = getOrCreateSessionId();
+    const timestamp = new Date().toISOString();
+    whenConsentDecided((decided) => {
+        const anonymousId = decided ? getOrCreateAnonymousId() : undefined;
+        postAgentNativeAnalytics(endpoint, JSON.stringify({
+            publicKey,
+            event: name,
+            // The visitor id waits for analytics consent; mark the event so
+            // reports can tell it from one that lost its id some other way, and
+            // a refusal from a page that closed before the region was known.
+            properties: anonymousId
+                ? properties
+                : {
+                    ...properties,
+                    analytics_consent: decided ? "withheld" : "unknown",
+                },
+            userId,
+            anonymousId,
+            sessionId,
+            timestamp,
+        }));
     });
+}
+function postAgentNativeAnalytics(endpoint, body) {
     try {
         if (navigator.sendBeacon) {
             const sent = navigator.sendBeacon(endpoint, body);
@@ -2187,17 +2265,34 @@ function createTrackingAliasId() {
         ? crypto.randomUUID()
         : undefined;
 }
+function pageHasGoogleTags() {
+    const holder = window;
+    return Boolean(holder.__AN_CONSENT_LAYERS__ ||
+        window.__AGENT_NATIVE_GA_GTAG__ ||
+        window.gtag);
+}
 function emitBrowserTrackingEvent(name, props, options = {}) {
     const { agentNativeProperties = props, gtagProperties = props, sendGtag = true, } = options;
     const amplitudeProps = amplitudeEventProperties(name, props);
-    if (sendGtag) {
-        const gtag = window.__AGENT_NATIVE_GA_GTAG__ ?? window.gtag;
-        gtag?.("event", name.replace(/\s+/g, "_"), gtagProperties);
+    // Without Google tags there is nothing to hold, and asking for the region
+    // would be a request a scoped embed (an MCP App widget) may not make.
+    if (sendGtag && pageHasGoogleTags()) {
+        whenConsentDecided(() => {
+            if (consentDecision("performance") !== true)
+                return;
+            const gtag = window.__AGENT_NATIVE_GA_GTAG__ ?? window.gtag;
+            gtag?.("event", name.replace(/\s+/g, "_"), gtagProperties);
+        });
     }
     if (ensureAmplitude()) {
         _amplitudeModule?.track(name, amplitudeProps);
     }
-    else if (_amplitudeApiKey) {
+    else if (_amplitudeApiKey &&
+        // Only while it loads after an accept, or before the region is known;
+        // the region's answer clears what's held if the visitor must choose.
+        (_amplitudeConsent === "granted" ||
+            (_amplitudeConsent !== "revoked" &&
+                consentDecision("performance") === null))) {
         if (_pendingAmplitudeEvents.length < 100) {
             _pendingAmplitudeEvents.push([name, amplitudeProps]);
         }

package/dist/client/consent.d.ts

@@ -13,6 +13,12 @@ export declare function resolveConsentRegion(): Promise<ConsentRegion>;
  * whatever this let through.
  */
 export declare function consentAllowsNow(category: ConsentCategory): boolean;
+/**
+ * Whether `category` is allowed, from the visitor's choice or the server's
+ * region; `null` until one of them is known, where `consentAllowsNow` would
+ * guess from the time zone. For what `revoke` can't undo once it's sent.
+ */
+export declare function consentDecision(category: ConsentCategory): boolean | null;
 export interface WhenConsentAllowsOptions {
     /**
      * Run now on the time zone's guess instead of waiting for the server, and
@@ -27,6 +33,12 @@ export interface WhenConsentAllowsOptions {
  * and inside it when the visitor accepts. A later "reject" calls `revoke`.
  */
 export declare function whenConsentAllows(category: ConsentCategory, run: () => void, options?: WhenConsentAllowsOptions): void;
+/**
+ * Run `send` once the visitor's choice or the server's region is known, so
+ * the time zone's guess never sends what consent covers. `decided` is false
+ * when the page closes first; send then without what consent covers.
+ */
+export declare function whenConsentDecided(send: (decided: boolean) => void): void;
 /** Store the visitor's choice for every app on this site, and apply it. */
 export declare function setConsentChoice(choice: ConsentChoice): void;
 /** Reopen the banner so the visitor can change their choice. */

package/dist/client/consent.js

@@ -8,6 +8,8 @@ const REGION_STORAGE_KEY = "an_consent_region";
  * injects into the page, queue `[category, run]` here.
  */
 const SCRIPT_QUEUE_KEY = "__AN_CONSENT_QUEUE__";
+/** The Google data layers the server's Consent Mode default script set up. */
+const GOOGLE_CONSENT_LAYERS_KEY = "__AN_CONSENT_LAYERS__";
 // One state per page, however many copies of this module a bundle carries.
 const STATE_KEY = Symbol.for("agent-native.client.consent");
 function state() {
@@ -18,6 +20,7 @@ function state() {
         waiters: [],
         listeners: new Set(),
         settingsOpen: false,
+        pageChoice: null,
     });
 }
 function readCookie(name) {
@@ -39,7 +42,7 @@ function readCookie(name) {
 }
 /** The visitor's stored choice, or `null` before they've made one. */
 export function getConsentChoice() {
-    return parseConsent(readCookie(CONSENT_COOKIE_NAME));
+    return (parseConsent(readCookie(CONSENT_COOKIE_NAME)) ?? state().pageChoice ?? null);
 }
 function cookieDomain() {
     const host = typeof window === "undefined" ? "" : window.location.hostname;
@@ -183,21 +186,69 @@ export function consentAllowsNow(category) {
         void resolveConsentRegion();
     return allows(category, regionGuess());
 }
+/**
+ * Whether `category` is allowed, from the visitor's choice or the server's
+ * region; `null` until one of them is known, where `consentAllowsNow` would
+ * guess from the time zone. For what `revoke` can't undo once it's sent.
+ */
+export function consentDecision(category) {
+    if (typeof window === "undefined")
+        return false;
+    const choice = getConsentChoice();
+    if (choice)
+        return choice[category];
+    const region = state().region ?? readCachedRegion();
+    if (region)
+        return region === "none";
+    void resolveConsentRegion();
+    return null;
+}
+/**
+ * Google's tags can't be unloaded, but they follow Consent Mode: a reject
+ * stops what's already on the page from storing or sending identifiers.
+ */
+function updateGoogleConsent(region) {
+    const holder = window;
+    const layers = holder[GOOGLE_CONSENT_LAYERS_KEY];
+    if (!Array.isArray(layers))
+        return;
+    const grant = (category) => allows(category, region) ? "granted" : "denied";
+    const update = {
+        analytics_storage: grant("performance"),
+        ad_storage: grant("targeting"),
+        ad_user_data: grant("targeting"),
+        ad_personalization: grant("targeting"),
+    };
+    for (const name of layers) {
+        if (typeof name !== "string")
+            continue;
+        const layer = (holder[name] ??= []);
+        // gtag reads an `arguments` object from the data layer, never an array.
+        (function gtag(..._args) {
+            layer.push(arguments);
+        })("consent", "update", update);
+    }
+}
 function settle() {
     const region = state().region;
+    if (region || getConsentChoice())
+        updateGoogleConsent(region);
     for (const waiter of state().waiters) {
         const allowed = allows(waiter.category, region);
         if (allowed && !waiter.ran) {
             waiter.ran = true;
             isolate(waiter.run);
         }
-        else if (!allowed && region) {
+        else if (!allowed && (region || getConsentChoice())) {
             // Also clears what an earlier page stored before the banner existed.
             waiter.ran = false;
             if (waiter.revoke)
                 isolate(waiter.revoke);
         }
     }
+    // A choice stored here or in another tab decides before the region does.
+    if (region || getConsentChoice())
+        releaseHeldForDecision?.(true);
 }
 /**
  * One callback throwing must not skip the waiters after it, or a later revoke
@@ -234,15 +285,93 @@ export function whenConsentAllows(category, run, options = {}) {
         waiter.ran = true;
         isolate(run);
     }
+    else if (state().region || getConsentChoice()) {
+        // A reject decided before this caller asked still clears what it stored.
+        if (options.revoke)
+            isolate(options.revoke);
+    }
     if (!state().region)
         void resolveConsentRegion();
 }
+let heldForDecision = null;
+let releaseHeldForDecision = null;
+/**
+ * Run `send` once the visitor's choice or the server's region is known, so
+ * the time zone's guess never sends what consent covers. `decided` is false
+ * when the page closes first; send then without what consent covers.
+ */
+export function whenConsentDecided(send) {
+    if (consentDecision("performance") !== null) {
+        send(true);
+        return;
+    }
+    if (!heldForDecision) {
+        const held = [];
+        heldForDecision = held;
+        const release = (decided) => {
+            if (heldForDecision !== held)
+                return;
+            heldForDecision = null;
+            releaseHeldForDecision = null;
+            window.removeEventListener("pagehide", onPageHide);
+            for (const run of held)
+                run(decided);
+        };
+        const onPageHide = () => release(false);
+        releaseHeldForDecision = release;
+        window.addEventListener("pagehide", onPageHide);
+        void resolveConsentRegion().then(() => release(true));
+    }
+    heldForDecision.push(send);
+}
+const CONSENT_CHANNEL_NAME = "agent-native-consent";
+let seenChoice = null;
+let consentChannel = null;
+/**
+ * Apply a choice another tab or app stored: at once in other tabs of this
+ * app, and on the next focus for another app on the site.
+ */
+function recheckStoredChoice() {
+    const raw = readCookie(CONSENT_COOKIE_NAME);
+    if (raw === seenChoice)
+        return;
+    seenChoice = raw;
+    state().settingsOpen = false;
+    settle();
+    notify();
+}
+function watchOtherTabs() {
+    if (typeof window === "undefined" || typeof document === "undefined")
+        return;
+    seenChoice = readCookie(CONSENT_COOKIE_NAME);
+    window.addEventListener?.("focus", recheckStoredChoice);
+    document.addEventListener?.("visibilitychange", recheckStoredChoice);
+    if (typeof BroadcastChannel !== "function")
+        return;
+    try {
+        consentChannel = new BroadcastChannel(CONSENT_CHANNEL_NAME);
+        consentChannel.onmessage = recheckStoredChoice;
+    }
+    catch {
+        // coercion-ok: without the channel, other tabs recheck on focus.
+    }
+}
 /** Store the visitor's choice for every app on this site, and apply it. */
 export function setConsentChoice(choice) {
     if (typeof document === "undefined")
         return;
     writeChoiceCookie(choice);
     storeChoiceOnServer(choice);
+    seenChoice = readCookie(CONSENT_COOKIE_NAME);
+    // Only a browser that won't keep the cookie falls back to this page's
+    // copy; a cookie the visitor clears later means they're asked again.
+    state().pageChoice = seenChoice === null ? choice : null;
+    try {
+        consentChannel?.postMessage("changed");
+    }
+    catch {
+        // coercion-ok: other tabs still recheck on focus.
+    }
     state().settingsOpen = false;
     if (!state().region)
         state().region = "consent";
@@ -281,3 +410,4 @@ function drainScriptQueue() {
         push(...queued);
 }
 drainScriptQueue();
+watchOtherTabs();

package/dist/client/onboarding/index.d.ts

@@ -1,4 +1,5 @@
 export { useOnboarding, type UseOnboardingResult } from "./use-onboarding.js";
+export { useOnboardingChecklist, type UseOnboardingChecklistResult, } from "./use-onboarding-checklist.js";
 export { isFirstRunOnboardingEnabled } from "./first-run-enabled.js";
 export { dispatchFirstRunOnboardingStatus, fetchFirstRunOnboardingStatus, FIRST_RUN_ONBOARDING_STATUS_RESOLVED_EVENT, } from "./first-run-status.js";
 export { useOnboardingPreviewMode, useOnboardingPreviewStep, ONBOARDING_PREVIEW_STORAGE_KEY, ONBOARDING_PREVIEW_QUERY_PARAM, ONBOARDING_PREVIEW_QUERY_VALUE, ONBOARDING_PREVIEW_STEP_QUERY_PARAM, ONBOARDING_PREVIEW_STEPS, getOnboardingPreviewStep, isOnboardingPreviewQuery, } from "./use-preview-mode.js";

package/dist/client/onboarding/index.js

@@ -1,4 +1,5 @@
 export { useOnboarding } from "./use-onboarding.js";
+export { useOnboardingChecklist, } from "./use-onboarding-checklist.js";
 export { isFirstRunOnboardingEnabled } from "./first-run-enabled.js";
 export { dispatchFirstRunOnboardingStatus, fetchFirstRunOnboardingStatus, FIRST_RUN_ONBOARDING_STATUS_RESOLVED_EVENT, } from "./first-run-status.js";
 export { useOnboardingPreviewMode, useOnboardingPreviewStep, ONBOARDING_PREVIEW_STORAGE_KEY, ONBOARDING_PREVIEW_QUERY_PARAM, ONBOARDING_PREVIEW_QUERY_VALUE, ONBOARDING_PREVIEW_STEP_QUERY_PARAM, ONBOARDING_PREVIEW_STEPS, getOnboardingPreviewStep, isOnboardingPreviewQuery, } from "./use-preview-mode.js";

package/dist/client/onboarding/use-onboarding-checklist.d.ts

@@ -0,0 +1,23 @@
+import type { OnboardingStepStatus } from "../../onboarding/types.js";
+export interface UseOnboardingChecklistResult {
+    steps: OnboardingStepStatus[];
+    completeCount: number;
+    totalCount: number;
+    dismissed: boolean;
+    collapsed: boolean;
+    /** `loading` only before the first answer; a refresh keeps the last one. */
+    status: "loading" | "ready" | "error";
+    error: Error | null;
+    refresh: () => Promise<unknown>;
+    dismiss: () => Promise<void>;
+    reopen: () => Promise<void>;
+    setCollapsed: (collapsed: boolean) => Promise<void>;
+}
+/**
+ * Reads one named onboarding checklist (steps registered with
+ * `registerOnboardingStep({ checklist })`). Rows are re-read whenever a local
+ * action or an agent tool finishes, so a step checks itself off after the work
+ * that completes it. Dismissal is stored by the onboarding plugin and the
+ * collapsed state in application state, so both follow the user across devices.
+ */
+export declare function useOnboardingChecklist(checklist: string): UseOnboardingChecklistResult;

package/dist/client/onboarding/use-onboarding-checklist.js

@@ -0,0 +1,115 @@
+import { useMutation, useQuery, useQueryClient, } from "@tanstack/react-query";
+import { useCallback } from "react";
+import { agentNativePath } from "../api-path.js";
+import { readClientAppState, writeClientAppState, } from "../application-state.js";
+import { useChangeVersions } from "../use-change-version.js";
+const CHECKLIST_TIMEOUT_MS = 10_000;
+function summaryKey(checklist) {
+    return ["onboarding-checklist", checklist];
+}
+function collapsedKey(checklist) {
+    return ["onboarding-checklist-collapsed", checklist];
+}
+function collapsedStateKey(checklist) {
+    return `onboarding:collapsed:${checklist}`;
+}
+function checklistUrl(path, checklist) {
+    return agentNativePath(`/_agent-native/onboarding/${path}?checklist=${encodeURIComponent(checklist)}`);
+}
+async function fetchChecklist(checklist, signal) {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    signal.addEventListener("abort", abort);
+    const timer = setTimeout(abort, CHECKLIST_TIMEOUT_MS);
+    try {
+        const response = await fetch(checklistUrl("summary", checklist), {
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            throw new Error(`checklist: ${response.status}`);
+        const body = (await response.json());
+        return { steps: body.steps, dismissed: !!body.dismissed };
+    }
+    finally {
+        clearTimeout(timer);
+        signal.removeEventListener("abort", abort);
+    }
+}
+async function postChecklist(path, checklist) {
+    const response = await fetch(checklistUrl(path, checklist), {
+        method: "POST",
+    });
+    if (!response.ok)
+        throw new Error(`checklist ${path}: ${response.status}`);
+}
+function patchSummary(queryClient, checklist, patch) {
+    const snapshot = queryClient.getQueriesData({
+        queryKey: summaryKey(checklist),
+    });
+    queryClient.setQueriesData({ queryKey: summaryKey(checklist) }, (current) => (current ? { ...current, ...patch } : current));
+    return snapshot;
+}
+/**
+ * Reads one named onboarding checklist (steps registered with
+ * `registerOnboardingStep({ checklist })`). Rows are re-read whenever a local
+ * action or an agent tool finishes, so a step checks itself off after the work
+ * that completes it. Dismissal is stored by the onboarding plugin and the
+ * collapsed state in application state, so both follow the user across devices.
+ */
+export function useOnboardingChecklist(checklist) {
+    const queryClient = useQueryClient();
+    const changeVersion = useChangeVersions(["action"]);
+    const summary = useQuery({
+        queryKey: [...summaryKey(checklist), changeVersion],
+        queryFn: ({ signal }) => fetchChecklist(checklist, signal),
+        placeholderData: (previous) => previous,
+    });
+    const collapsedQuery = useQuery({
+        queryKey: collapsedKey(checklist),
+        queryFn: async () => {
+            const value = await readClientAppState(collapsedStateKey(checklist));
+            return value?.collapsed === true;
+        },
+        staleTime: Infinity,
+    });
+    const dismissMutation = useMutation({
+        mutationFn: (dismissed) => postChecklist(dismissed ? "dismiss" : "reopen", checklist),
+        onMutate: (dismissed) => ({
+            previous: patchSummary(queryClient, checklist, { dismissed }),
+        }),
+        onError: (_error, _dismissed, context) => {
+            for (const [key, data] of context?.previous ?? []) {
+                queryClient.setQueryData(key, data);
+            }
+        },
+        onSettled: () => queryClient.invalidateQueries({ queryKey: summaryKey(checklist) }),
+    });
+    const collapseMutation = useMutation({
+        mutationFn: (collapsed) => writeClientAppState(collapsedStateKey(checklist), { collapsed }),
+        onMutate: (collapsed) => {
+            const previous = queryClient.getQueryData(collapsedKey(checklist));
+            queryClient.setQueryData(collapsedKey(checklist), collapsed);
+            return { previous };
+        },
+        onError: (_error, _collapsed, context) => {
+            queryClient.setQueryData(collapsedKey(checklist), context?.previous);
+        },
+    });
+    const dismiss = useCallback(() => dismissMutation.mutateAsync(true), [dismissMutation]);
+    const reopen = useCallback(() => dismissMutation.mutateAsync(false), [dismissMutation]);
+    const setCollapsed = useCallback((collapsed) => collapseMutation.mutateAsync(collapsed).then(() => undefined), [collapseMutation]);
+    const steps = summary.data?.steps ?? [];
+    return {
+        steps,
+        completeCount: steps.filter((step) => step.complete).length,
+        totalCount: steps.length,
+        dismissed: summary.data?.dismissed ?? false,
+        collapsed: collapsedQuery.data ?? false,
+        status: summary.data ? "ready" : summary.isError ? "error" : "loading",
+        error: summary.error,
+        refresh: () => queryClient.invalidateQueries({ queryKey: summaryKey(checklist) }),
+        dismiss,
+        reopen,
+        setCollapsed,
+    };
+}

package/dist/client/session-replay.d.ts

@@ -64,7 +64,7 @@ export interface SessionReplayOptions {
 }
 export interface SessionReplayStartResult {
     started: boolean;
-    reason?: "disabled" | "not-browser" | "missing-public-key" | "missing-session-id" | "missing-user-id" | "sampled-out" | "url-blocked" | "already-active" | "import-failed" | "record-failed";
+    reason?: "disabled" | "not-browser" | "missing-public-key" | "missing-session-id" | "missing-user-id" | "sampled-out" | "url-blocked" | "already-active" | "import-failed" | "record-failed" | "consent-required";
     replayId?: string;
     sessionId?: string;
     sampled?: boolean;