@agent-native/core 0.205.0 → 0.206.0-nightly-20261009011246

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

@@ -1,5 +1,17 @@
 import type { OnboardingAppProfile, OnboardingMethod, OnboardingStepStatus } from "../../onboarding/types.js";
+type CustomKeyOnboardingSetupKind = "credential" | "local_endpoint";
+type CustomKeyOnboardingOutcome = "credential_entry_started" | "credential_validated" | "credential_saved" | "credential_skipped" | "credential_abandoned" | "local_endpoint_saved" | "local_endpoint_skipped" | "local_endpoint_abandoned";
+type CustomKeyOutcomeResult = "tracked" | "tracked_uncorrelated" | "tracked_storage_unavailable" | "pending" | "missing" | "unavailable" | "stale" | "identity_mismatch" | "duplicate";
+export declare function createOnboardingCorrelationId(): string;
+export declare function setCustomKeyOnboardingAttempt(id: string): Promise<"stored" | "no_session" | "unavailable">;
+export declare function setCustomKeyOnboardingSetupKind(setupKind: CustomKeyOnboardingSetupKind): "stored" | "memory" | "missing" | "unavailable";
+export declare function trackCustomKeyOnboardingOutcome(outcome: CustomKeyOnboardingOutcome): CustomKeyOutcomeResult;
+export declare function withCustomKeyOnboardingCredentialSave<T>(save: () => Promise<T>): Promise<T>;
+export declare function withCustomKeyOnboardingLocalEndpointSave<T>(save: () => Promise<T>): Promise<T>;
+export declare function requestCustomKeyOnboardingAbandonment(): void;
+export declare function useCustomKeyOnboardingAttemptLifecycle(): void;
 export declare function __resetOnboardingSummaryReadsForTests(): void;
+export declare function __resetOnboardingEventDedupeForTests(): void;
 export declare function trackOnboardingEvent(name: string, properties: Record<string, unknown>): void;
 export interface UseOnboardingResult {
     steps: OnboardingStepStatus[];

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

@@ -1,11 +1,464 @@
 import { useCallback, useEffect, useRef, useState } from "react";
-import { getAnalyticsIdentityKey, trackEvent } from "../analytics.js";
+import { getAnalyticsIdentityKey, getAnalyticsSessionId, resolveAnalyticsIdentityKey, trackEvent, } from "../analytics.js";
 import { agentNativePath } from "../api-path.js";
 import { scheduleAfterPaint, scheduleAfterStartup, } from "../use-after-paint.js";
 import { dispatchFirstRunOnboardingStatus, fetchFirstRunOnboardingStatus, readFirstRunOnboardingCookieState, } from "./first-run-status.js";
+const lastOnboardingStepViews = new Map();
 const seenOnboardingEvents = new Set();
+const CUSTOM_KEY_ATTEMPT_STORAGE_KEY = "agent-native.onboarding.custom_keys_attempt";
+const locallyTrackedCustomKeyOutcomes = new Set();
+const pendingCustomKeyCredentialSaves = new Map();
+let onboardingDocumentId = null;
+let onboardingCorrelationSequence = 0;
 const ONBOARDING_SUMMARY_TIMEOUT_MS = 15_000;
 const ONBOARDING_SUMMARY_REUSE_MS = 5_000;
+function isTerminalCustomKeyOnboardingOutcome(outcome) {
+    return (outcome === "credential_saved" ||
+        outcome === "credential_skipped" ||
+        outcome === "credential_abandoned" ||
+        outcome === "local_endpoint_saved" ||
+        outcome === "local_endpoint_skipped" ||
+        outcome === "local_endpoint_abandoned");
+}
+export function createOnboardingCorrelationId() {
+    const cryptoApi = globalThis.crypto;
+    if (typeof cryptoApi?.randomUUID === "function") {
+        return cryptoApi.randomUUID();
+    }
+    onboardingCorrelationSequence += 1;
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}-${onboardingCorrelationSequence.toString(36)}`;
+}
+function getOnboardingDocumentId() {
+    return (onboardingDocumentId ??= createOnboardingCorrelationId());
+}
+// Keep the handoff alive while the SPA opens settings before auth refresh settles.
+let pendingCustomKeyOnboardingAttempt = null;
+function flushPendingCustomKeyOnboardingOutcomes(pending) {
+    const outcomes = pending.outcomes.splice(0);
+    for (const outcome of outcomes) {
+        trackCustomKeyOnboardingOutcome(outcome);
+    }
+}
+function readCustomKeyOnboardingAttempt() {
+    if (typeof window === "undefined")
+        return { kind: "unavailable" };
+    const pending = pendingCustomKeyOnboardingAttempt;
+    if (pending?.attempt.documentId === getOnboardingDocumentId()) {
+        if (pending.status === "resolving" || pending.status === "unavailable") {
+            return { kind: "pending", pending };
+        }
+    }
+    try {
+        const value = window.sessionStorage.getItem(CUSTOM_KEY_ATTEMPT_STORAGE_KEY);
+        if (!value) {
+            if (pending?.attempt.documentId === getOnboardingDocumentId() &&
+                pending.attempt.identityKey) {
+                return {
+                    kind: "available",
+                    attempt: pending.attempt,
+                };
+            }
+            return { kind: "available", attempt: null };
+        }
+        const parsed = JSON.parse(value);
+        if (!parsed || typeof parsed !== "object") {
+            return { kind: "unavailable" };
+        }
+        const attempt = parsed;
+        if (typeof attempt.id !== "string")
+            return { kind: "unavailable" };
+        if (attempt.documentId !== getOnboardingDocumentId()) {
+            return { kind: "stale" };
+        }
+        if (typeof attempt.identityKey !== "string") {
+            return { kind: "unavailable" };
+        }
+        if (pending?.attempt.id === attempt.id &&
+            pending.attempt.documentId === attempt.documentId &&
+            pending.attempt.identityKey) {
+            return {
+                kind: "available",
+                attempt: pending.attempt,
+            };
+        }
+        return {
+            kind: "available",
+            attempt: attempt,
+        };
+    }
+    catch {
+        if (pending?.attempt.documentId === getOnboardingDocumentId() &&
+            pending.attempt.identityKey) {
+            return {
+                kind: "available",
+                attempt: pending.attempt,
+            };
+        }
+        return { kind: "unavailable" };
+    }
+}
+function writePendingCustomKeyOnboardingAttempt(pending, identityKey) {
+    pending.attempt.identityKey = identityKey;
+    try {
+        window.sessionStorage.setItem(CUSTOM_KEY_ATTEMPT_STORAGE_KEY, JSON.stringify(pending.attempt));
+        pending.status = "stored";
+        return "stored";
+    }
+    catch {
+        pending.status = "memory";
+        return "unavailable";
+    }
+}
+export function setCustomKeyOnboardingAttempt(id) {
+    if (typeof window === "undefined")
+        return Promise.resolve("unavailable");
+    const sessionId = getAnalyticsSessionId();
+    const pending = {
+        attempt: {
+            id,
+            documentId: getOnboardingDocumentId(),
+            setupKind: "credential",
+        },
+        identityKeyAtStart: getAnalyticsIdentityKey(),
+        status: "resolving",
+        outcomes: [],
+    };
+    pendingCustomKeyOnboardingAttempt = pending;
+    return resolveAnalyticsIdentityKey()
+        .then((identityKey) => {
+        if (!sessionId || !identityKey) {
+            pending.status = "unavailable";
+            flushPendingCustomKeyOnboardingOutcomes(pending);
+            return "no_session";
+        }
+        const result = writePendingCustomKeyOnboardingAttempt(pending, identityKey);
+        flushPendingCustomKeyOnboardingOutcomes(pending);
+        return result;
+    })
+        .catch(() => {
+        pending.status = "unavailable";
+        flushPendingCustomKeyOnboardingOutcomes(pending);
+        return "unavailable";
+    });
+}
+export function setCustomKeyOnboardingSetupKind(setupKind) {
+    const pending = pendingCustomKeyOnboardingAttempt;
+    if (pending && pending.attempt.documentId === getOnboardingDocumentId()) {
+        pending.attempt.setupKind = setupKind;
+        if (pending.status === "resolving")
+            return "memory";
+        if (pending.status === "unavailable")
+            return "unavailable";
+    }
+    const stored = readCustomKeyOnboardingAttempt();
+    if (stored.kind === "pending") {
+        stored.pending.attempt.setupKind = setupKind;
+        return stored.pending.status === "resolving" ? "memory" : "unavailable";
+    }
+    if (stored.kind !== "available" || !stored.attempt) {
+        return stored.kind === "available" ? "missing" : "unavailable";
+    }
+    const attempt = { ...stored.attempt, setupKind };
+    if (pending?.attempt.id === attempt.id)
+        pending.attempt.setupKind = setupKind;
+    try {
+        window.sessionStorage.setItem(CUSTOM_KEY_ATTEMPT_STORAGE_KEY, JSON.stringify(attempt));
+        return "stored";
+    }
+    catch {
+        return "unavailable";
+    }
+}
+function trackUnavailableCustomKeyOnboardingOutcome(pending, outcome) {
+    const identityKey = pending.attempt.identityKey ?? pending.identityKeyAtStart;
+    if (identityKey !== getAnalyticsIdentityKey()) {
+        if (pendingCustomKeyOnboardingAttempt === pending) {
+            pendingCustomKeyOnboardingAttempt = null;
+        }
+        try {
+            window.sessionStorage.removeItem(CUSTOM_KEY_ATTEMPT_STORAGE_KEY);
+        }
+        catch {
+            return "unavailable";
+        }
+        return "identity_mismatch";
+    }
+    const attemptOutcomeKey = `${pending.attempt.id}:${outcome}`;
+    if (locallyTrackedCustomKeyOutcomes.has(attemptOutcomeKey)) {
+        return "duplicate";
+    }
+    trackOnboardingEvent("onboarding_method_outcome", {
+        flow: "first_run",
+        step_id: "choice",
+        method_id: "custom_keys",
+        onboarding_attempt_id: pending.attempt.id,
+        outcome,
+        correlation_status: "unavailable",
+    });
+    locallyTrackedCustomKeyOutcomes.add(attemptOutcomeKey);
+    if (isTerminalCustomKeyOnboardingOutcome(outcome)) {
+        if (pendingCustomKeyOnboardingAttempt === pending) {
+            pendingCustomKeyOnboardingAttempt = null;
+        }
+    }
+    return "tracked_uncorrelated";
+}
+export function trackCustomKeyOnboardingOutcome(outcome) {
+    const stored = readCustomKeyOnboardingAttempt();
+    if (stored.kind === "unavailable")
+        return "unavailable";
+    if (stored.kind === "pending") {
+        if (stored.pending.status === "resolving") {
+            if (stored.pending.outcomes.includes(outcome))
+                return "duplicate";
+            stored.pending.outcomes.push(outcome);
+            return "pending";
+        }
+        return trackUnavailableCustomKeyOnboardingOutcome(stored.pending, outcome);
+    }
+    if (stored.kind === "stale") {
+        // A duplicated tab can copy sessionStorage while the original attempt is live.
+        try {
+            window.sessionStorage.removeItem(CUSTOM_KEY_ATTEMPT_STORAGE_KEY);
+        }
+        catch {
+            return "unavailable";
+        }
+        return "stale";
+    }
+    const { attempt } = stored;
+    if (!attempt)
+        return "missing";
+    if (attempt.identityKey !== getAnalyticsIdentityKey()) {
+        try {
+            window.sessionStorage.removeItem(CUSTOM_KEY_ATTEMPT_STORAGE_KEY);
+        }
+        catch {
+            if (pendingCustomKeyOnboardingAttempt?.attempt.id === attempt.id) {
+                pendingCustomKeyOnboardingAttempt = null;
+            }
+            return "unavailable";
+        }
+        if (pendingCustomKeyOnboardingAttempt?.attempt.id === attempt.id) {
+            pendingCustomKeyOnboardingAttempt = null;
+        }
+        return "identity_mismatch";
+    }
+    const attemptOutcomeKey = `${attempt.id}:${outcome}`;
+    const alreadyTracked = (outcome === "credential_entry_started" && attempt.entryStarted) ||
+        (outcome === "credential_validated" && attempt.credentialValidated);
+    if (alreadyTracked ||
+        locallyTrackedCustomKeyOutcomes.has(attemptOutcomeKey)) {
+        if (isTerminalCustomKeyOnboardingOutcome(outcome)) {
+            try {
+                window.sessionStorage.removeItem(CUSTOM_KEY_ATTEMPT_STORAGE_KEY);
+            }
+            catch {
+                return "unavailable";
+            }
+        }
+        return "duplicate";
+    }
+    trackOnboardingEvent("onboarding_method_outcome", {
+        flow: "first_run",
+        step_id: "choice",
+        method_id: "custom_keys",
+        onboarding_attempt_id: attempt.id,
+        outcome,
+    });
+    locallyTrackedCustomKeyOutcomes.add(attemptOutcomeKey);
+    if (outcome === "credential_entry_started" ||
+        outcome === "credential_validated") {
+        try {
+            window.sessionStorage.setItem(CUSTOM_KEY_ATTEMPT_STORAGE_KEY, JSON.stringify({
+                ...attempt,
+                [outcome === "credential_entry_started"
+                    ? "entryStarted"
+                    : "credentialValidated"]: true,
+            }));
+            if (pendingCustomKeyOnboardingAttempt?.attempt.id === attempt.id) {
+                pendingCustomKeyOnboardingAttempt.attempt = {
+                    ...pendingCustomKeyOnboardingAttempt.attempt,
+                    ...attempt,
+                    [outcome === "credential_entry_started"
+                        ? "entryStarted"
+                        : "credentialValidated"]: true,
+                };
+            }
+        }
+        catch {
+            if (pendingCustomKeyOnboardingAttempt?.attempt.id !== attempt.id) {
+                return "tracked_storage_unavailable";
+            }
+            pendingCustomKeyOnboardingAttempt.status = "memory";
+        }
+    }
+    else if (isTerminalCustomKeyOnboardingOutcome(outcome)) {
+        try {
+            window.sessionStorage.removeItem(CUSTOM_KEY_ATTEMPT_STORAGE_KEY);
+        }
+        catch {
+            if (pendingCustomKeyOnboardingAttempt?.attempt.id !== attempt.id) {
+                return "tracked_storage_unavailable";
+            }
+        }
+        if (pendingCustomKeyOnboardingAttempt?.attempt.id === attempt.id) {
+            pendingCustomKeyOnboardingAttempt = null;
+        }
+    }
+    return "tracked";
+}
+function trackCustomKeyOnboardingOutcomeForAttempt(attemptId, outcome) {
+    const stored = readCustomKeyOnboardingAttempt();
+    if ((stored.kind !== "available" && stored.kind !== "pending") ||
+        (stored.kind === "available" && stored.attempt?.id !== attemptId) ||
+        (stored.kind === "pending" && stored.pending.attempt.id !== attemptId) ||
+        (stored.kind === "available" &&
+            stored.attempt?.identityKey !== getAnalyticsIdentityKey()) ||
+        (stored.kind === "pending" &&
+            stored.pending.attempt.identityKey !== undefined &&
+            stored.pending.attempt.identityKey !== getAnalyticsIdentityKey())) {
+        return "missing";
+    }
+    return trackCustomKeyOnboardingOutcome(outcome);
+}
+function beginCustomKeyOnboardingSave(saveOutcome, abandonmentOutcome) {
+    const stored = readCustomKeyOnboardingAttempt();
+    if (stored.kind === "available" && stored.attempt) {
+        if (stored.attempt.identityKey !== getAnalyticsIdentityKey())
+            return null;
+        return beginCustomKeyOnboardingSaveForAttempt(stored.attempt.id, saveOutcome, abandonmentOutcome);
+    }
+    if (stored.kind === "pending" &&
+        stored.pending.attempt.documentId === getOnboardingDocumentId() &&
+        (stored.pending.attempt.identityKey === undefined ||
+            stored.pending.attempt.identityKey === getAnalyticsIdentityKey())) {
+        return beginCustomKeyOnboardingSaveForAttempt(stored.pending.attempt.id, saveOutcome, abandonmentOutcome);
+    }
+    return null;
+}
+function beginCustomKeyOnboardingSaveForAttempt(attemptId, saveOutcome, abandonmentOutcome) {
+    const pending = pendingCustomKeyCredentialSaves.get(attemptId) ?? {
+        count: 0,
+        abandonmentRequested: false,
+        saved: false,
+        saveOutcome,
+        abandonmentOutcome,
+    };
+    pending.count += 1;
+    pendingCustomKeyCredentialSaves.set(attemptId, pending);
+    let finished = false;
+    return {
+        finish(saved) {
+            if (finished)
+                return;
+            finished = true;
+            const current = pendingCustomKeyCredentialSaves.get(attemptId);
+            if (!current)
+                return;
+            try {
+                if (saved) {
+                    const result = trackCustomKeyOnboardingOutcomeForAttempt(attemptId, current.saveOutcome);
+                    if (result === "tracked" ||
+                        result === "tracked_uncorrelated" ||
+                        result === "tracked_storage_unavailable" ||
+                        result === "duplicate") {
+                        current.saved = true;
+                    }
+                }
+            }
+            finally {
+                current.count -= 1;
+                if (current.count === 0) {
+                    pendingCustomKeyCredentialSaves.delete(attemptId);
+                    if (current.abandonmentRequested && !current.saved) {
+                        trackCustomKeyOnboardingOutcomeForAttempt(attemptId, current.abandonmentOutcome);
+                    }
+                }
+            }
+        },
+    };
+}
+export async function withCustomKeyOnboardingCredentialSave(save) {
+    return withCustomKeyOnboardingSave(save, "credential_saved", "credential_abandoned");
+}
+export async function withCustomKeyOnboardingLocalEndpointSave(save) {
+    return withCustomKeyOnboardingSave(save, "local_endpoint_saved", "local_endpoint_abandoned");
+}
+async function withCustomKeyOnboardingSave(save, saveOutcome, abandonmentOutcome) {
+    const credentialSave = beginCustomKeyOnboardingSave(saveOutcome, abandonmentOutcome);
+    let saved = false;
+    try {
+        const result = await save();
+        saved = true;
+        return result;
+    }
+    finally {
+        credentialSave?.finish(saved);
+    }
+}
+function handleCustomKeyOnboardingAbandonment() {
+    const stored = readCustomKeyOnboardingAttempt();
+    const attempt = stored.kind === "available"
+        ? stored.attempt
+        : stored.kind === "pending"
+            ? stored.pending.attempt
+            : null;
+    if (attempt &&
+        (attempt.identityKey === undefined ||
+            attempt.identityKey === getAnalyticsIdentityKey())) {
+        const attemptId = attempt.id;
+        const completedOutcome = [
+            "credential_saved",
+            "credential_skipped",
+            "credential_abandoned",
+            "local_endpoint_saved",
+            "local_endpoint_skipped",
+            "local_endpoint_abandoned",
+        ].find((outcome) => locallyTrackedCustomKeyOutcomes.has(`${attemptId}:${outcome}`));
+        if (completedOutcome) {
+            trackCustomKeyOnboardingOutcome(completedOutcome);
+            return;
+        }
+        const pending = pendingCustomKeyCredentialSaves.get(attemptId);
+        if (pending && pending.count > 0) {
+            pending.abandonmentRequested = true;
+            return;
+        }
+        trackCustomKeyOnboardingOutcome(attempt.setupKind === "local_endpoint"
+            ? "local_endpoint_abandoned"
+            : "credential_abandoned");
+        return;
+    }
+    trackCustomKeyOnboardingOutcome("credential_abandoned");
+}
+export function requestCustomKeyOnboardingAbandonment() {
+    handleCustomKeyOnboardingAbandonment();
+}
+export function useCustomKeyOnboardingAttemptLifecycle() {
+    const mountedRef = useRef(false);
+    useEffect(() => {
+        mountedRef.current = true;
+        if (readCustomKeyOnboardingAttempt().kind === "stale") {
+            trackCustomKeyOnboardingOutcome("credential_abandoned");
+        }
+        const handlePageHide = (event) => {
+            if (!event.persisted) {
+                handleCustomKeyOnboardingAbandonment();
+            }
+        };
+        window.addEventListener("pagehide", handlePageHide);
+        return () => {
+            window.removeEventListener("pagehide", handlePageHide);
+            mountedRef.current = false;
+            queueMicrotask(() => {
+                if (!mountedRef.current) {
+                    handleCustomKeyOnboardingAbandonment();
+                }
+            });
+        };
+    }, []);
+}
 const sharedSummaryReads = new Map();
 /**
  * The setup button, the checklist panel, and the first-run surface each mount
@@ -58,11 +511,17 @@ function readOnboardingSummary(url, fresh) {
 export function __resetOnboardingSummaryReadsForTests() {
     sharedSummaryReads.clear();
 }
+export function __resetOnboardingEventDedupeForTests() {
+    lastOnboardingStepViews.clear();
+    seenOnboardingEvents.clear();
+}
 export function trackOnboardingEvent(name, properties) {
     if (typeof window === "undefined")
         return;
     const identityKey = getAnalyticsIdentityKey() ?? "anonymous";
+    const sessionId = getAnalyticsSessionId() ?? "unknown-session";
     const key = [
+        sessionId,
         identityKey,
         name,
         properties.flow,
@@ -70,9 +529,20 @@ export function trackOnboardingEvent(name, properties) {
         properties.extension_id,
         properties.integration_id,
         properties.role,
+        properties.step_view_id,
+        properties.onboarding_attempt_id,
     ]
         .map((value) => String(value ?? ""))
         .join(":");
+    const stepViewScope = JSON.stringify([
+        sessionId,
+        identityKey,
+        properties.flow,
+    ]);
+    const stepIdentity = JSON.stringify([
+        properties.step_id,
+        properties.extension_id,
+    ]);
     const isRepeatableInteraction = name.startsWith("integration_") ||
         name === "onboarding_role_save_started" ||
         name === "onboarding_method_clicked" ||
@@ -81,10 +551,27 @@ export function trackOnboardingEvent(name, properties) {
         name === "onboarding_dismissed" ||
         name === "onboarding_reopened" ||
         name === "onboarding_abandoned";
-    if (!isRepeatableInteraction && seenOnboardingEvents.has(key))
-        return;
-    if (!isRepeatableInteraction)
+    if (name === "onboarding_step_viewed") {
+        if (typeof properties.step_view_id === "string" &&
+            properties.step_view_id) {
+            if (seenOnboardingEvents.has(key))
+                return;
+            seenOnboardingEvents.add(key);
+        }
+        else {
+            if (lastOnboardingStepViews.get(stepViewScope) === stepIdentity)
+                return;
+            lastOnboardingStepViews.set(stepViewScope, stepIdentity);
+        }
+    }
+    else if (name === "onboarding_reopened") {
+        lastOnboardingStepViews.delete(stepViewScope);
+    }
+    else if (!isRepeatableInteraction) {
+        if (seenOnboardingEvents.has(key))
+            return;
         seenOnboardingEvents.add(key);
+    }
     trackEvent(name, properties);
 }
 export function useOnboarding(options = {}) {

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

@@ -0,0 +1,8 @@
+export declare const SESSION_REPLAY_MASK_ATTRIBUTE = "data-an-mask";
+export declare const SESSION_REPLAY_MASK_PROPS: {
+    readonly "data-an-mask": "";
+};
+export declare const SESSION_REPLAY_BLOCK_ATTRIBUTE = "data-an-block";
+export declare const SESSION_REPLAY_BLOCK_PROPS: {
+    readonly "data-an-block": "";
+};

package/dist/client/session-replay-privacy.js

@@ -0,0 +1,8 @@
+export const SESSION_REPLAY_MASK_ATTRIBUTE = "data-an-mask";
+export const SESSION_REPLAY_MASK_PROPS = {
+    [SESSION_REPLAY_MASK_ATTRIBUTE]: "",
+};
+export const SESSION_REPLAY_BLOCK_ATTRIBUTE = "data-an-block";
+export const SESSION_REPLAY_BLOCK_PROPS = {
+    [SESSION_REPLAY_BLOCK_ATTRIBUTE]: "",
+};

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

@@ -39,6 +39,7 @@ export interface SessionReplayOptions {
     blockSelector?: string;
     ignoreSelector?: string;
     maskTextClass?: string | RegExp;
+    /** App selectors extend the framework's `data-an-mask` privacy marker. */
     maskTextSelector?: string;
     maskAllInputs?: boolean;
     recordCanvas?: boolean;

package/dist/client/session-replay.js

@@ -3,6 +3,7 @@ import { resolveLaneEndpoint } from "../shared/environment-lanes.js";
 import { loadOptionalPeer, OptionalPeerDependencyError, } from "../shared/optional-peer.js";
 import { isSyntheticTrafficValue } from "../shared/test-traffic.js";
 import { getOrCreateAnalyticsAnonymousId, getOrCreateAnalyticsSessionId, } from "./analytics-session.js";
+import { SESSION_REPLAY_BLOCK_ATTRIBUTE, SESSION_REPLAY_MASK_ATTRIBUTE, } from "./session-replay-privacy.js";
 import { decideReplayQuotaResponse, parseRetryAfterSeconds, } from "./session-replay-quota.js";
 import { scrubUrl } from "./url-scrub.js";
 function isSyntheticBrowserTraffic() {
@@ -24,7 +25,7 @@ const SESSION_REPLAY_IFRAME_BLOCK_SELECTOR = `iframe[${SESSION_REPLAY_IFRAME_ATT
 const DEFAULT_BLOCK_SELECTOR = [
     SESSION_REPLAY_IFRAME_BLOCK_SELECTOR,
     "[data-sensitive]",
-    "[data-an-block]",
+    `[${SESSION_REPLAY_BLOCK_ATTRIBUTE}]`,
     "[data-an-private]",
     "[data-private]",
     ".an-block",
@@ -39,9 +40,18 @@ const DEFAULT_BLOCK_SELECTOR = [
     "[name*='card' i]",
     "[name*='ssn' i]",
 ].join(", ");
+/**
+ * App block selectors extend these framework markers instead of replacing them.
+ * Append them whole: a custom selector can mention one, as in
+ * `[data-an-block] .secret`, without matching the bare marker.
+ */
+const REQUIRED_BLOCK_SELECTORS = [
+    SESSION_REPLAY_IFRAME_BLOCK_SELECTOR,
+    `[${SESSION_REPLAY_BLOCK_ATTRIBUTE}]`,
+];
 const DEFAULT_IGNORE_SELECTOR = ".an-ignore, [data-an-ignore]";
 const DEFAULT_MASK_TEXT_CLASS = "an-mask";
-const DEFAULT_MASK_TEXT_SELECTOR = "[data-an-mask]";
+const DEFAULT_MASK_TEXT_SELECTOR = `[${SESSION_REPLAY_MASK_ATTRIBUTE}]`;
 const DEFAULT_MASK_INPUT_OPTIONS = {
     color: true,
     date: true,
@@ -586,10 +596,14 @@ function normalizeOptions(options) {
         checkoutEveryNth: options.checkoutEveryNth,
         checkoutEveryNms: options.checkoutEveryNms,
         inlineStylesheet: options.inlineStylesheet ?? true,
-        blockSelector: mergeReplayBlockSelector(options.blockSelector || DEFAULT_BLOCK_SELECTOR),
+        blockSelector: options.blockSelector
+            ? [options.blockSelector, ...REQUIRED_BLOCK_SELECTORS].join(", ")
+            : DEFAULT_BLOCK_SELECTOR,
         ignoreSelector: options.ignoreSelector || DEFAULT_IGNORE_SELECTOR,
         maskTextClass: options.maskTextClass || DEFAULT_MASK_TEXT_CLASS,
-        maskTextSelector: options.maskTextSelector || DEFAULT_MASK_TEXT_SELECTOR,
+        maskTextSelector: options.maskTextSelector
+            ? `${DEFAULT_MASK_TEXT_SELECTOR}, ${options.maskTextSelector}`
+            : DEFAULT_MASK_TEXT_SELECTOR,
         maskAllInputs: options.maskAllInputs ?? true,
         recordCanvas: options.recordCanvas ?? false,
         recordCrossOriginIframes: options.recordCrossOriginIframes ?? window.parent === window,
@@ -605,11 +619,6 @@ function normalizeOptions(options) {
         shouldStart: options.shouldStart,
     };
 }
-function mergeReplayBlockSelector(blockSelector) {
-    return blockSelector.includes(SESSION_REPLAY_IFRAME_BLOCK_SELECTOR)
-        ? blockSelector
-        : `${blockSelector}, ${SESSION_REPLAY_IFRAME_BLOCK_SELECTOR}`;
-}
 function normalizeCaptureToggle(value, defaultMaxEvents) {
     if (value === false)
         return null;