@corbado/observe 0.12.0 → 0.13.0

package/dist/index.d.mts

@@ -144,6 +144,15 @@ type StepOptions = {
 type SubflowTrigger = {
     actor: "system" | "user";
     explicitSpecType?: string;
+    /**
+     * Declares this subflow_started / subflow_trigger as not user-driven, excluding it from
+     * interaction-evidence calculations on the backend: a started subflow that produces no step
+     * afterwards is classified as a "no-followup" error unless this flag is set. Set it when the
+     * integration fires the start programmatically (e.g. an automatic passkey attempt after
+     * identifier lookup) and an abandoned attempt is expected rather than an error signal.
+     * Optional; absent/false means the event counts (legacy behavior).
+     */
+    ignoreAsInteraction?: boolean;
 };
 interface PredefinedEvent extends BaseEvent {
     type: "predefined";
@@ -486,6 +495,11 @@ declare abstract class OperationFull {
     private tracker;
     private operationName;
     constructor(tracker: CorbadoTracker, operationName: SubflowType);
+    /**
+     * Emits subflow_started. `data` supports the SubflowTrigger fields (`actor`,
+     * `explicitSpecType`, `ignoreAsInteraction`) plus free-form extras; see SubflowTrigger for when
+     * to set `ignoreAsInteraction` on programmatic starts.
+     */
     subflowStart(data: any, options?: StepOptions): void;
     trigger(data: SubflowTrigger, options?: StepOptions): void;
     customStep<TStart = {}, TFinished = {}>(stepName: string): StepHelper<TStart, TFinished>;
@@ -598,7 +612,18 @@ declare class EmailLinkOperationFull extends OperationFull {
     constructor(tracker: CorbadoTracker);
 }
 
-type PasskeyOperationEnrollmentExplicitSpecType = "conditional-auto-manual" | "auto-manual" | "manual";
+/**
+ * Passkey-enrollment spec types. Two vocabularies coexist:
+ *
+ * - ATTEMPT-scoped (preferred): one subflow per attempt KIND — `"conditional"` (silent conditional
+ *   create), `"auto"` (automatic required-mediation prompt fired by the integration) or `"manual"`
+ *   (fired by the user's button). Create a NEW operation for every attempt; the backend opens a new
+ *   subflow whenever the spec changes, so "auto prompt dismissed, then completed via the button" is two
+ *   subflows and stays distinguishable from "completed by the auto prompt".
+ * - OFFER-scoped (legacy): one subflow per offer — `"conditional-auto-manual"` / `"auto-manual"` name
+ *   the offer mode, and the completing ceremony's `mediation` tells the completion variants apart.
+ */
+type PasskeyOperationEnrollmentExplicitSpecType = "conditional" | "auto" | "manual" | "conditional-auto-manual" | "auto-manual";
 type PasskeyEnrollmentGetOptionsStart = {
     explicitSpecType?: PasskeyOperationEnrollmentExplicitSpecType;
 };
@@ -627,6 +652,13 @@ type PasskeyEnrollmentPostResponseStart = {
 };
 type PasskeyEnrollmentOperationConfig = {
     explicitSpecType?: PasskeyOperationEnrollmentExplicitSpecType;
+    /**
+     * Marks the auto-emitted `subflow_started` as not user-driven (see SubflowTrigger.ignoreAsInteraction).
+     * Set it for attempts the integration fires without a user gesture and without a visible surface —
+     * e.g. a `"conditional"` attempt — so a start that never produced a step is not read as a user asking
+     * to enroll.
+     */
+    ignoreAsInteraction?: boolean;
 };
 declare class PasskeyEnrollmentOperationFull extends OperationFull {
     readonly getOptions: StepHelper<PasskeyEnrollmentGetOptionsStart, PasskeyEnrollmentGetOptionsFinished>;
@@ -838,6 +870,7 @@ declare class ProvideDataOperationFull extends OperationFull {
 }
 
 interface TrackerOptions {
+    /** All persisted SDK state and cross-tab locks are isolated by this project id. */
     projectId: string;
     apiBaseUrl: string;
     apiEventPath?: string;
@@ -878,6 +911,8 @@ declare class CorbadoTracker {
     private sessionStorage;
     /** Dedicated localStorage engine for reliability state (config cache, outbox, continuity session, seq). */
     private persistentStorage;
+    /** Seq/continuity Web Lock name; project-scoped together with the storage keys it guards. */
+    private readonly seqLockName;
     /**
      * Reliability config for this load. A boot with a cached server config is a snapshot (immutable
      * mid-load); a boot on the built-in defaults upgrades once to the first server-returned config
@@ -966,12 +1001,15 @@ declare class CorbadoTracker {
      * same browser. Rotates after `config.sessionInactivityMs` of inactivity (server-controlled,
      * boot-snapshot like the rest of the config), resetting the seq counter.
      *
-     * This is the ONLY place an inactivity rotation happens. Rotating here is safe because the load
-     * that triggers it also re-announces its flow (an integration emits `flow_started` on page load),
-     * so the fresh session id gets a classifiable flow. Mid-page there is no such re-announcement:
-     * rotating between two tracked events would leave the started flow unfinished in the old session
-     * and the remaining events without a flow start in the new one — one gap counted as a drop-off,
-     * one completion counted as nothing. `nextSeq` therefore never rotates on inactivity.
+     * Inactivity rotation happens at boot only, here and on the per-tab path {@link resolveSessionId}
+     * takes without continuity. Boot is chosen on an assumption, not a guarantee: that a load
+     * re-announces its flow, so the fresh session id gets a classifiable flow. That holds where a
+     * flow is opened per load. Where one is opened once and carried across loads it does not, and a
+     * boot rotation splits that flow — such a project needs a window long enough to span the journey.
+     * Mid-page the assumption is not even available: nothing re-announces between two tracked events,
+     * so rotating there would leave the started flow unfinished in the old session and the remaining
+     * events without a flow start in the new one — one gap counted as a drop-off, one completion
+     * counted as nothing. `nextSeq` therefore never rotates on inactivity, on either path.
      */
     private getContinuitySessionId;
     /**
@@ -979,6 +1017,24 @@ declare class CorbadoTracker {
      * section measures from the last write that actually happened — whoever made it.
      */
     private persistContinuitySession;
+    /**
+     * Read the per-tab session record. A bare string is the format that predates dating: it carries no
+     * `lastActiveAt`, so its window can only start on the load that reads it. That load rewrites it in
+     * the dated shape, so a tab converts once and ages normally from then on, and the case drains as
+     * the rollout replaces the bundles that write it.
+     */
+    private readPerTabSession;
+    /**
+     * Persist the per-tab record and remember when, sharing the throttle bookkeeping with the
+     * continuity record — a load resolves its session on one path or the other, never both.
+     *
+     * Only a load that received a server config stamps the window; any other carries forward what the
+     * tab already knows. So a defaults boot never downgrades a tab that has already learned the
+     * project's threshold to the built-in one, and the window survives a rotation within the tab.
+     */
+    private persistPerTabSession;
+    /** The window this tab measures against: what a configured load recorded, else this load's own. */
+    private perTabInactivityMs;
     /**
      * Return the next sequence number. With session continuity the counter is persisted so ordering
      * survives reloads/redirects; the read-increment-write runs under a cross-tab Web Lock
@@ -1028,6 +1084,9 @@ declare class CorbadoTracker {
      *
      * @param data - Flow metadata, including one flow (`flowName`) or multiple candidates (`flowNames`).
      * @param tags - Optional key-value tags for filtering and segmentation.
+     * @param experiments - Optional per-call experiment overrides.
+     * @param contexts - Optional structured event context (e.g. technical metadata that is not an
+     *   analytical dimension). Written to the event's `contexts` field verbatim.
      *
      * @example
      * ```typescript
@@ -1038,7 +1097,7 @@ declare class CorbadoTracker {
      * });
      * ```
      */
-    flowStarted(data: FlowStarted | MultiFlowStarted, tags?: Record<string, string>, experiments?: Record<string, string>): void;
+    flowStarted(data: FlowStarted | MultiFlowStarted, tags?: Record<string, string>, experiments?: Record<string, string>, contexts?: Record<string, unknown>): void;
     /**
      * Track when the user commits to a specific flow.
      *
@@ -1303,6 +1362,28 @@ interface StorageEngine {
     setItem<T>(key: string, value: T): void;
     removeItem(key: string): void;
 }
+/**
+ * Suffix a storage key or cross-tab lock name with a namespace. One shared helper so keys and the
+ * Web Lock names guarding them can never disagree on the derived name.
+ */
+declare function namespacedKey(key: string, namespace: string): string;
+/**
+ * Wraps a storage engine so every key is suffixed with a fixed namespace (see {@link namespacedKey}).
+ *
+ * @remarks
+ * All trackers use their project id as the namespace: all SDK state flows through the engines
+ * created in the tracker constructor, so wrapping them scopes every persisted key (session, seq,
+ * outbox, config cache, experiments, tab id, client-env handle, debug dumps) in one place. Lock
+ * names are not storage keys and must be scoped separately by the call sites that own them.
+ */
+declare class NamespacedStorage implements StorageEngine {
+    private readonly engine;
+    private readonly namespace;
+    constructor(engine: StorageEngine, namespace: string);
+    getItem<T>(key: string): T | null;
+    setItem<T>(key: string, value: T): void;
+    removeItem(key: string): void;
+}
 declare class LocalStorage implements StorageEngine {
     private logger;
     constructor(logger: Logger);
@@ -1402,6 +1483,11 @@ interface QueueOptions {
     onConfigReceived?: (config: SdkReliabilityConfig) => void;
     /** Whether to send the opt-in config header on the first flush of this load. Defaults to true. */
     requestConfig?: boolean;
+    /**
+     * Web Lock name for the durable outbox, scoped alongside the storage engine's keys (see
+     * {@link EventStore}). Defaults to the shared {@link OUTBOX_LOCK_NAME}.
+     */
+    outboxLockName?: string;
 }
 /**
  * @remarks When `window` is defined, `visibilitychange` (when the document becomes hidden) and `pagehide`
@@ -1464,6 +1550,8 @@ declare class RequestQueue {
      * (config.flushOnFlowTypeFinished).
      */
     private priorityFlowTypes;
+    /** Scoped Web Lock name for the durable outbox; undefined = EventStore's shared default. */
+    private outboxLockName?;
     private store?;
     /**
      * Once the server has answered the config request with a 2xx (200 = fresh config cached for the
@@ -1696,7 +1784,7 @@ declare const DEFAULT_MAX_SERIALIZED_LENGTH: number;
  *
  * @remarks
  * Every mutation is a read-merge-write against storage, executed under a cross-tab Web Lock
- * ({@link OUTBOX_LOCK_NAME}) so concurrent tabs sharing the same localStorage cannot interleave
+ * (default {@link OUTBOX_LOCK_NAME}) so concurrent tabs sharing the same localStorage cannot interleave
  * between the read and the write (which would silently drop the other tab's entries). Where the
  * Web Locks API is unavailable the mutation runs unlocked, matching the historical best-effort
  * behavior. Mutations never reject; failures are logged.
@@ -1707,10 +1795,22 @@ declare class EventStore {
     private readonly logger;
     private readonly maxEntries;
     private readonly maxSerializedLength;
+    /**
+     * Web Lock name guarding mutations. Must be scoped together with the storage the engine writes
+     * to: a project-scoped outbox key guarded by the shared lock would serialize unrelated trackers,
+     * and a shared key guarded by scoped locks would lose the cross-tab atomicity guarantee.
+     */
+    private readonly lockName;
     private entries;
     /** Malformed entries are dropped on every read; report only once per instance to avoid log spam. */
     private reportedMalformed;
-    constructor(storage: StorageEngine, logger: Logger, maxEntries?: number, maxSerializedLength?: number);
+    constructor(storage: StorageEngine, logger: Logger, maxEntries?: number, maxSerializedLength?: number, 
+    /**
+     * Web Lock name guarding mutations. Must be scoped together with the storage the engine writes
+     * to: a project-scoped outbox key guarded by the shared lock would serialize unrelated trackers,
+     * and a shared key guarded by scoped locks would lose the cross-tab atomicity guarantee.
+     */
+    lockName?: string);
     private read;
     private mutate;
     /** Evict oldest entries until the serialized outbox fits {@link maxSerializedLength}. */
@@ -1728,7 +1828,13 @@ declare class EventStore {
     size(): number;
 }
 
+/**
+ * Create a tracker and make it the default for all package-level helpers.
+ * Each call replaces the default. For multiple projects, retain the returned instances and call
+ * their methods, or construct {@link CorbadoTracker} instances directly without changing the default.
+ */
 declare function init(options: TrackerOptions): CorbadoTracker;
+/** Return the default tracker from the most recent {@link init} call. */
 declare function getTracker(): CorbadoTracker | undefined;
 declare function resetSession(): string | undefined;
 /**
@@ -1746,4 +1852,4 @@ declare function logInfo(message: string): void;
 declare function logError(message: string): void;
 declare function destroy(): Promise<void>;
 
-export { type AppConfirmationOperationCeremonyTypedError, AppConfirmationOperationFull, type AppConfirmationOperationRetryReason, type AppConfirmationOperationSpecType, type AppConfirmationOperationStart, type AuthDecisionFinished, type AuthDecisionStarted, AuthEventName, type AuthMethodDecisionFinished, type AuthMethodDecisionStarted, type AuthMethodType, type BaseEvent, CEREMONY_LOW_EVENT_TAIL_MS, CONFIG_BOUNDS, CONFIG_REQUEST_HEADER, CONFIG_STORAGE_KEY, type CaptchaOperationConfig, CaptchaOperationFull, type CaptchaOperationSpecType, type ClientCapabilities, type ClientEnvHandleMeta, type ClientEnvHandleMetaSource, type Conversion, CookieStorage, CorbadoTracker, type CreateLoggerOptions, type CustomEvent, DEFAULT_DEVICE_INFO_COLLECTOR_TIMEOUT_MS, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_SERIALIZED_LENGTH, DEFAULT_RELIABILITY_CONFIG, DEFAULT_SEQ_LOCK_TIMEOUT_MS, DEFAULT_SESSION_INACTIVITY_MS, type DeviceInfo, type DeviceInfoCollectionError, type DeviceInfoDataWeb, type DeviceType, EmailLinkOperationFull, type EmailLinkOperationPostResponseStart, type EmailLinkOperationSendStart, type EmailLinkOperationSpecType, type EmailOTPOperationConfig, type EmailOTPOperationPostResponseStart, type EmailOTPOperationSendOTPStart, type EmailOTPOperationSpecType, EmailOtpOperationFull, type Event, type EventBatch, type EventBatchMeta, type EventMeta, EventStore, type EventType, type FlowAutoFinished, type FlowDecided, type FlowFinished, type FlowReset, type FlowStarted, type FlowType, type FlushReason, type JavaScriptHighEntropy, LocalStorage, type Logger, type LowEvent, type MultiFlowReset, type MultiFlowStarted, type NormalizedError, OUTBOX_LOCK_NAME, OUTBOX_STORAGE_KEY, type ObserveSdkConfigSnapshot, OperationFull, OperationFullProvideIdentifierWithCUI, type OperationFullProvideIdentifierWithCUIConfig, type OutboxEntry, type PasskeyEnrollmentCeremonyFinished, type PasskeyEnrollmentCeremonyStart, type PasskeyEnrollmentGetOptionsFinished, type PasskeyEnrollmentGetOptionsStart, type PasskeyEnrollmentOperationConfig, PasskeyEnrollmentOperationFull, type PasskeyEnrollmentPostResponseStart, type PasskeyLoginCUIGetOptionsFinished, type PasskeyLoginCUIGetOptionsStart, type PasskeyLoginCUISpecType, type PasskeyLoginCeremonyFinished, type PasskeyLoginCeremonyStart, type PasskeyLoginClientError, type PasskeyLoginFinish, type PasskeyLoginGetOptionsFinished, type PasskeyLoginGetOptionsStart, PasskeyLoginOperationFull, type PasskeyLoginPostResponseStart, type PasskeyLoginStartable, type PasskeyLoginSubmitted, type PasskeyOperationEnrollmentExplicitSpecType, type PasskeyOperationLoginExplicitSpecType, type PasswordEnrollmentAutoTrackConfig, PasswordEnrollmentOperationFull, type PasswordEnrollmentTypedError, type PasswordLoginAutoTrackConfig, type PasswordLoginCUICeremonyStart, type PasswordLoginCUIGetOptionsFinished, type PasswordLoginCUIGetOptionsStart, type PasswordLoginCUISpecType, type PasswordLoginCUITypedError, PasswordLoginOperationFull, type PasswordLoginTypedError, type PredefinedEvent, type ProvideDataOperationConfig, ProvideDataOperationFull, type ProvideDataOperationPostResponseStart, type ProvideDataOperationSpecType, type ProvideDataOperationStart, type ProvideIdentifierError, type ProvideIdentifierFinish, type ProvideIdentifierPostResponseStart, type ProvideIdentifierSpecType, type ProvideIdentifierStart, type QueueOptions, RequestQueue, SDK_NAME, SDK_VERSION, type SdkInfo, type SdkReliabilityConfig, type SdkRetryConfig, SessionStorage, type SmsOTPOperationConfig, type SmsOTPOperationPostResponseStart, type SmsOTPOperationSpecType, SmsOtpOperationFull, type SocialLoginExchangeCodeFinished, type SocialLoginExchangeCodeStart, type SocialLoginGetRedirectUrlFinished, type SocialLoginGetRedirectUrlStart, SocialLoginOperationFull, type SocialLoginProviderType, type SocialLoginSpecType, type StepHelper, type StepOptions, type StorageEngine, type SubflowTrigger, type SubflowType, type TelemetryEntry, type TelemetryLevel, type TelemetrySink, type TrackerOptions, type Transport, type TransportMakeRequestResponse, type TransportOptions, type UserReference, cacheConfig, clearExperiment, clearExperiments, createLogger, destroy, getExperiments, getSessionId, getTracker, init, loadCachedConfig, logError, logInfo, parseReliabilityConfig, resetSession, setExperiment, setExperiments, telemetry };
+export { type AppConfirmationOperationCeremonyTypedError, AppConfirmationOperationFull, type AppConfirmationOperationRetryReason, type AppConfirmationOperationSpecType, type AppConfirmationOperationStart, type AuthDecisionFinished, type AuthDecisionStarted, AuthEventName, type AuthMethodDecisionFinished, type AuthMethodDecisionStarted, type AuthMethodType, type BaseEvent, CEREMONY_LOW_EVENT_TAIL_MS, CONFIG_BOUNDS, CONFIG_REQUEST_HEADER, CONFIG_STORAGE_KEY, type CaptchaOperationConfig, CaptchaOperationFull, type CaptchaOperationSpecType, type ClientCapabilities, type ClientEnvHandleMeta, type ClientEnvHandleMetaSource, type Conversion, CookieStorage, CorbadoTracker, type CreateLoggerOptions, type CustomEvent, DEFAULT_DEVICE_INFO_COLLECTOR_TIMEOUT_MS, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_SERIALIZED_LENGTH, DEFAULT_RELIABILITY_CONFIG, DEFAULT_SEQ_LOCK_TIMEOUT_MS, DEFAULT_SESSION_INACTIVITY_MS, type DeviceInfo, type DeviceInfoCollectionError, type DeviceInfoDataWeb, type DeviceType, EmailLinkOperationFull, type EmailLinkOperationPostResponseStart, type EmailLinkOperationSendStart, type EmailLinkOperationSpecType, type EmailOTPOperationConfig, type EmailOTPOperationPostResponseStart, type EmailOTPOperationSendOTPStart, type EmailOTPOperationSpecType, EmailOtpOperationFull, type Event, type EventBatch, type EventBatchMeta, type EventMeta, EventStore, type EventType, type FlowAutoFinished, type FlowDecided, type FlowFinished, type FlowReset, type FlowStarted, type FlowType, type FlushReason, type JavaScriptHighEntropy, LocalStorage, type Logger, type LowEvent, type MultiFlowReset, type MultiFlowStarted, NamespacedStorage, type NormalizedError, OUTBOX_LOCK_NAME, OUTBOX_STORAGE_KEY, type ObserveSdkConfigSnapshot, OperationFull, OperationFullProvideIdentifierWithCUI, type OperationFullProvideIdentifierWithCUIConfig, type OutboxEntry, type PasskeyEnrollmentCeremonyFinished, type PasskeyEnrollmentCeremonyStart, type PasskeyEnrollmentGetOptionsFinished, type PasskeyEnrollmentGetOptionsStart, type PasskeyEnrollmentOperationConfig, PasskeyEnrollmentOperationFull, type PasskeyEnrollmentPostResponseStart, type PasskeyLoginCUIGetOptionsFinished, type PasskeyLoginCUIGetOptionsStart, type PasskeyLoginCUISpecType, type PasskeyLoginCeremonyFinished, type PasskeyLoginCeremonyStart, type PasskeyLoginClientError, type PasskeyLoginFinish, type PasskeyLoginGetOptionsFinished, type PasskeyLoginGetOptionsStart, PasskeyLoginOperationFull, type PasskeyLoginPostResponseStart, type PasskeyLoginStartable, type PasskeyLoginSubmitted, type PasskeyOperationEnrollmentExplicitSpecType, type PasskeyOperationLoginExplicitSpecType, type PasswordEnrollmentAutoTrackConfig, PasswordEnrollmentOperationFull, type PasswordEnrollmentTypedError, type PasswordLoginAutoTrackConfig, type PasswordLoginCUICeremonyStart, type PasswordLoginCUIGetOptionsFinished, type PasswordLoginCUIGetOptionsStart, type PasswordLoginCUISpecType, type PasswordLoginCUITypedError, PasswordLoginOperationFull, type PasswordLoginTypedError, type PredefinedEvent, type ProvideDataOperationConfig, ProvideDataOperationFull, type ProvideDataOperationPostResponseStart, type ProvideDataOperationSpecType, type ProvideDataOperationStart, type ProvideIdentifierError, type ProvideIdentifierFinish, type ProvideIdentifierPostResponseStart, type ProvideIdentifierSpecType, type ProvideIdentifierStart, type QueueOptions, RequestQueue, SDK_NAME, SDK_VERSION, type SdkInfo, type SdkReliabilityConfig, type SdkRetryConfig, SessionStorage, type SmsOTPOperationConfig, type SmsOTPOperationPostResponseStart, type SmsOTPOperationSpecType, SmsOtpOperationFull, type SocialLoginExchangeCodeFinished, type SocialLoginExchangeCodeStart, type SocialLoginGetRedirectUrlFinished, type SocialLoginGetRedirectUrlStart, SocialLoginOperationFull, type SocialLoginProviderType, type SocialLoginSpecType, type StepHelper, type StepOptions, type StorageEngine, type SubflowTrigger, type SubflowType, type TelemetryEntry, type TelemetryLevel, type TelemetrySink, type TrackerOptions, type Transport, type TransportMakeRequestResponse, type TransportOptions, type UserReference, cacheConfig, clearExperiment, clearExperiments, createLogger, destroy, getExperiments, getSessionId, getTracker, init, loadCachedConfig, logError, logInfo, namespacedKey, parseReliabilityConfig, resetSession, setExperiment, setExperiments, telemetry };

package/dist/index.d.ts

@@ -144,6 +144,15 @@ type StepOptions = {
 type SubflowTrigger = {
     actor: "system" | "user";
     explicitSpecType?: string;
+    /**
+     * Declares this subflow_started / subflow_trigger as not user-driven, excluding it from
+     * interaction-evidence calculations on the backend: a started subflow that produces no step
+     * afterwards is classified as a "no-followup" error unless this flag is set. Set it when the
+     * integration fires the start programmatically (e.g. an automatic passkey attempt after
+     * identifier lookup) and an abandoned attempt is expected rather than an error signal.
+     * Optional; absent/false means the event counts (legacy behavior).
+     */
+    ignoreAsInteraction?: boolean;
 };
 interface PredefinedEvent extends BaseEvent {
     type: "predefined";
@@ -486,6 +495,11 @@ declare abstract class OperationFull {
     private tracker;
     private operationName;
     constructor(tracker: CorbadoTracker, operationName: SubflowType);
+    /**
+     * Emits subflow_started. `data` supports the SubflowTrigger fields (`actor`,
+     * `explicitSpecType`, `ignoreAsInteraction`) plus free-form extras; see SubflowTrigger for when
+     * to set `ignoreAsInteraction` on programmatic starts.
+     */
     subflowStart(data: any, options?: StepOptions): void;
     trigger(data: SubflowTrigger, options?: StepOptions): void;
     customStep<TStart = {}, TFinished = {}>(stepName: string): StepHelper<TStart, TFinished>;
@@ -598,7 +612,18 @@ declare class EmailLinkOperationFull extends OperationFull {
     constructor(tracker: CorbadoTracker);
 }
 
-type PasskeyOperationEnrollmentExplicitSpecType = "conditional-auto-manual" | "auto-manual" | "manual";
+/**
+ * Passkey-enrollment spec types. Two vocabularies coexist:
+ *
+ * - ATTEMPT-scoped (preferred): one subflow per attempt KIND — `"conditional"` (silent conditional
+ *   create), `"auto"` (automatic required-mediation prompt fired by the integration) or `"manual"`
+ *   (fired by the user's button). Create a NEW operation for every attempt; the backend opens a new
+ *   subflow whenever the spec changes, so "auto prompt dismissed, then completed via the button" is two
+ *   subflows and stays distinguishable from "completed by the auto prompt".
+ * - OFFER-scoped (legacy): one subflow per offer — `"conditional-auto-manual"` / `"auto-manual"` name
+ *   the offer mode, and the completing ceremony's `mediation` tells the completion variants apart.
+ */
+type PasskeyOperationEnrollmentExplicitSpecType = "conditional" | "auto" | "manual" | "conditional-auto-manual" | "auto-manual";
 type PasskeyEnrollmentGetOptionsStart = {
     explicitSpecType?: PasskeyOperationEnrollmentExplicitSpecType;
 };
@@ -627,6 +652,13 @@ type PasskeyEnrollmentPostResponseStart = {
 };
 type PasskeyEnrollmentOperationConfig = {
     explicitSpecType?: PasskeyOperationEnrollmentExplicitSpecType;
+    /**
+     * Marks the auto-emitted `subflow_started` as not user-driven (see SubflowTrigger.ignoreAsInteraction).
+     * Set it for attempts the integration fires without a user gesture and without a visible surface —
+     * e.g. a `"conditional"` attempt — so a start that never produced a step is not read as a user asking
+     * to enroll.
+     */
+    ignoreAsInteraction?: boolean;
 };
 declare class PasskeyEnrollmentOperationFull extends OperationFull {
     readonly getOptions: StepHelper<PasskeyEnrollmentGetOptionsStart, PasskeyEnrollmentGetOptionsFinished>;
@@ -838,6 +870,7 @@ declare class ProvideDataOperationFull extends OperationFull {
 }
 
 interface TrackerOptions {
+    /** All persisted SDK state and cross-tab locks are isolated by this project id. */
     projectId: string;
     apiBaseUrl: string;
     apiEventPath?: string;
@@ -878,6 +911,8 @@ declare class CorbadoTracker {
     private sessionStorage;
     /** Dedicated localStorage engine for reliability state (config cache, outbox, continuity session, seq). */
     private persistentStorage;
+    /** Seq/continuity Web Lock name; project-scoped together with the storage keys it guards. */
+    private readonly seqLockName;
     /**
      * Reliability config for this load. A boot with a cached server config is a snapshot (immutable
      * mid-load); a boot on the built-in defaults upgrades once to the first server-returned config
@@ -966,12 +1001,15 @@ declare class CorbadoTracker {
      * same browser. Rotates after `config.sessionInactivityMs` of inactivity (server-controlled,
      * boot-snapshot like the rest of the config), resetting the seq counter.
      *
-     * This is the ONLY place an inactivity rotation happens. Rotating here is safe because the load
-     * that triggers it also re-announces its flow (an integration emits `flow_started` on page load),
-     * so the fresh session id gets a classifiable flow. Mid-page there is no such re-announcement:
-     * rotating between two tracked events would leave the started flow unfinished in the old session
-     * and the remaining events without a flow start in the new one — one gap counted as a drop-off,
-     * one completion counted as nothing. `nextSeq` therefore never rotates on inactivity.
+     * Inactivity rotation happens at boot only, here and on the per-tab path {@link resolveSessionId}
+     * takes without continuity. Boot is chosen on an assumption, not a guarantee: that a load
+     * re-announces its flow, so the fresh session id gets a classifiable flow. That holds where a
+     * flow is opened per load. Where one is opened once and carried across loads it does not, and a
+     * boot rotation splits that flow — such a project needs a window long enough to span the journey.
+     * Mid-page the assumption is not even available: nothing re-announces between two tracked events,
+     * so rotating there would leave the started flow unfinished in the old session and the remaining
+     * events without a flow start in the new one — one gap counted as a drop-off, one completion
+     * counted as nothing. `nextSeq` therefore never rotates on inactivity, on either path.
      */
     private getContinuitySessionId;
     /**
@@ -979,6 +1017,24 @@ declare class CorbadoTracker {
      * section measures from the last write that actually happened — whoever made it.
      */
     private persistContinuitySession;
+    /**
+     * Read the per-tab session record. A bare string is the format that predates dating: it carries no
+     * `lastActiveAt`, so its window can only start on the load that reads it. That load rewrites it in
+     * the dated shape, so a tab converts once and ages normally from then on, and the case drains as
+     * the rollout replaces the bundles that write it.
+     */
+    private readPerTabSession;
+    /**
+     * Persist the per-tab record and remember when, sharing the throttle bookkeeping with the
+     * continuity record — a load resolves its session on one path or the other, never both.
+     *
+     * Only a load that received a server config stamps the window; any other carries forward what the
+     * tab already knows. So a defaults boot never downgrades a tab that has already learned the
+     * project's threshold to the built-in one, and the window survives a rotation within the tab.
+     */
+    private persistPerTabSession;
+    /** The window this tab measures against: what a configured load recorded, else this load's own. */
+    private perTabInactivityMs;
     /**
      * Return the next sequence number. With session continuity the counter is persisted so ordering
      * survives reloads/redirects; the read-increment-write runs under a cross-tab Web Lock
@@ -1028,6 +1084,9 @@ declare class CorbadoTracker {
      *
      * @param data - Flow metadata, including one flow (`flowName`) or multiple candidates (`flowNames`).
      * @param tags - Optional key-value tags for filtering and segmentation.
+     * @param experiments - Optional per-call experiment overrides.
+     * @param contexts - Optional structured event context (e.g. technical metadata that is not an
+     *   analytical dimension). Written to the event's `contexts` field verbatim.
      *
      * @example
      * ```typescript
@@ -1038,7 +1097,7 @@ declare class CorbadoTracker {
      * });
      * ```
      */
-    flowStarted(data: FlowStarted | MultiFlowStarted, tags?: Record<string, string>, experiments?: Record<string, string>): void;
+    flowStarted(data: FlowStarted | MultiFlowStarted, tags?: Record<string, string>, experiments?: Record<string, string>, contexts?: Record<string, unknown>): void;
     /**
      * Track when the user commits to a specific flow.
      *
@@ -1303,6 +1362,28 @@ interface StorageEngine {
     setItem<T>(key: string, value: T): void;
     removeItem(key: string): void;
 }
+/**
+ * Suffix a storage key or cross-tab lock name with a namespace. One shared helper so keys and the
+ * Web Lock names guarding them can never disagree on the derived name.
+ */
+declare function namespacedKey(key: string, namespace: string): string;
+/**
+ * Wraps a storage engine so every key is suffixed with a fixed namespace (see {@link namespacedKey}).
+ *
+ * @remarks
+ * All trackers use their project id as the namespace: all SDK state flows through the engines
+ * created in the tracker constructor, so wrapping them scopes every persisted key (session, seq,
+ * outbox, config cache, experiments, tab id, client-env handle, debug dumps) in one place. Lock
+ * names are not storage keys and must be scoped separately by the call sites that own them.
+ */
+declare class NamespacedStorage implements StorageEngine {
+    private readonly engine;
+    private readonly namespace;
+    constructor(engine: StorageEngine, namespace: string);
+    getItem<T>(key: string): T | null;
+    setItem<T>(key: string, value: T): void;
+    removeItem(key: string): void;
+}
 declare class LocalStorage implements StorageEngine {
     private logger;
     constructor(logger: Logger);
@@ -1402,6 +1483,11 @@ interface QueueOptions {
     onConfigReceived?: (config: SdkReliabilityConfig) => void;
     /** Whether to send the opt-in config header on the first flush of this load. Defaults to true. */
     requestConfig?: boolean;
+    /**
+     * Web Lock name for the durable outbox, scoped alongside the storage engine's keys (see
+     * {@link EventStore}). Defaults to the shared {@link OUTBOX_LOCK_NAME}.
+     */
+    outboxLockName?: string;
 }
 /**
  * @remarks When `window` is defined, `visibilitychange` (when the document becomes hidden) and `pagehide`
@@ -1464,6 +1550,8 @@ declare class RequestQueue {
      * (config.flushOnFlowTypeFinished).
      */
     private priorityFlowTypes;
+    /** Scoped Web Lock name for the durable outbox; undefined = EventStore's shared default. */
+    private outboxLockName?;
     private store?;
     /**
      * Once the server has answered the config request with a 2xx (200 = fresh config cached for the
@@ -1696,7 +1784,7 @@ declare const DEFAULT_MAX_SERIALIZED_LENGTH: number;
  *
  * @remarks
  * Every mutation is a read-merge-write against storage, executed under a cross-tab Web Lock
- * ({@link OUTBOX_LOCK_NAME}) so concurrent tabs sharing the same localStorage cannot interleave
+ * (default {@link OUTBOX_LOCK_NAME}) so concurrent tabs sharing the same localStorage cannot interleave
  * between the read and the write (which would silently drop the other tab's entries). Where the
  * Web Locks API is unavailable the mutation runs unlocked, matching the historical best-effort
  * behavior. Mutations never reject; failures are logged.
@@ -1707,10 +1795,22 @@ declare class EventStore {
     private readonly logger;
     private readonly maxEntries;
     private readonly maxSerializedLength;
+    /**
+     * Web Lock name guarding mutations. Must be scoped together with the storage the engine writes
+     * to: a project-scoped outbox key guarded by the shared lock would serialize unrelated trackers,
+     * and a shared key guarded by scoped locks would lose the cross-tab atomicity guarantee.
+     */
+    private readonly lockName;
     private entries;
     /** Malformed entries are dropped on every read; report only once per instance to avoid log spam. */
     private reportedMalformed;
-    constructor(storage: StorageEngine, logger: Logger, maxEntries?: number, maxSerializedLength?: number);
+    constructor(storage: StorageEngine, logger: Logger, maxEntries?: number, maxSerializedLength?: number, 
+    /**
+     * Web Lock name guarding mutations. Must be scoped together with the storage the engine writes
+     * to: a project-scoped outbox key guarded by the shared lock would serialize unrelated trackers,
+     * and a shared key guarded by scoped locks would lose the cross-tab atomicity guarantee.
+     */
+    lockName?: string);
     private read;
     private mutate;
     /** Evict oldest entries until the serialized outbox fits {@link maxSerializedLength}. */
@@ -1728,7 +1828,13 @@ declare class EventStore {
     size(): number;
 }
 
+/**
+ * Create a tracker and make it the default for all package-level helpers.
+ * Each call replaces the default. For multiple projects, retain the returned instances and call
+ * their methods, or construct {@link CorbadoTracker} instances directly without changing the default.
+ */
 declare function init(options: TrackerOptions): CorbadoTracker;
+/** Return the default tracker from the most recent {@link init} call. */
 declare function getTracker(): CorbadoTracker | undefined;
 declare function resetSession(): string | undefined;
 /**
@@ -1746,4 +1852,4 @@ declare function logInfo(message: string): void;
 declare function logError(message: string): void;
 declare function destroy(): Promise<void>;
 
-export { type AppConfirmationOperationCeremonyTypedError, AppConfirmationOperationFull, type AppConfirmationOperationRetryReason, type AppConfirmationOperationSpecType, type AppConfirmationOperationStart, type AuthDecisionFinished, type AuthDecisionStarted, AuthEventName, type AuthMethodDecisionFinished, type AuthMethodDecisionStarted, type AuthMethodType, type BaseEvent, CEREMONY_LOW_EVENT_TAIL_MS, CONFIG_BOUNDS, CONFIG_REQUEST_HEADER, CONFIG_STORAGE_KEY, type CaptchaOperationConfig, CaptchaOperationFull, type CaptchaOperationSpecType, type ClientCapabilities, type ClientEnvHandleMeta, type ClientEnvHandleMetaSource, type Conversion, CookieStorage, CorbadoTracker, type CreateLoggerOptions, type CustomEvent, DEFAULT_DEVICE_INFO_COLLECTOR_TIMEOUT_MS, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_SERIALIZED_LENGTH, DEFAULT_RELIABILITY_CONFIG, DEFAULT_SEQ_LOCK_TIMEOUT_MS, DEFAULT_SESSION_INACTIVITY_MS, type DeviceInfo, type DeviceInfoCollectionError, type DeviceInfoDataWeb, type DeviceType, EmailLinkOperationFull, type EmailLinkOperationPostResponseStart, type EmailLinkOperationSendStart, type EmailLinkOperationSpecType, type EmailOTPOperationConfig, type EmailOTPOperationPostResponseStart, type EmailOTPOperationSendOTPStart, type EmailOTPOperationSpecType, EmailOtpOperationFull, type Event, type EventBatch, type EventBatchMeta, type EventMeta, EventStore, type EventType, type FlowAutoFinished, type FlowDecided, type FlowFinished, type FlowReset, type FlowStarted, type FlowType, type FlushReason, type JavaScriptHighEntropy, LocalStorage, type Logger, type LowEvent, type MultiFlowReset, type MultiFlowStarted, type NormalizedError, OUTBOX_LOCK_NAME, OUTBOX_STORAGE_KEY, type ObserveSdkConfigSnapshot, OperationFull, OperationFullProvideIdentifierWithCUI, type OperationFullProvideIdentifierWithCUIConfig, type OutboxEntry, type PasskeyEnrollmentCeremonyFinished, type PasskeyEnrollmentCeremonyStart, type PasskeyEnrollmentGetOptionsFinished, type PasskeyEnrollmentGetOptionsStart, type PasskeyEnrollmentOperationConfig, PasskeyEnrollmentOperationFull, type PasskeyEnrollmentPostResponseStart, type PasskeyLoginCUIGetOptionsFinished, type PasskeyLoginCUIGetOptionsStart, type PasskeyLoginCUISpecType, type PasskeyLoginCeremonyFinished, type PasskeyLoginCeremonyStart, type PasskeyLoginClientError, type PasskeyLoginFinish, type PasskeyLoginGetOptionsFinished, type PasskeyLoginGetOptionsStart, PasskeyLoginOperationFull, type PasskeyLoginPostResponseStart, type PasskeyLoginStartable, type PasskeyLoginSubmitted, type PasskeyOperationEnrollmentExplicitSpecType, type PasskeyOperationLoginExplicitSpecType, type PasswordEnrollmentAutoTrackConfig, PasswordEnrollmentOperationFull, type PasswordEnrollmentTypedError, type PasswordLoginAutoTrackConfig, type PasswordLoginCUICeremonyStart, type PasswordLoginCUIGetOptionsFinished, type PasswordLoginCUIGetOptionsStart, type PasswordLoginCUISpecType, type PasswordLoginCUITypedError, PasswordLoginOperationFull, type PasswordLoginTypedError, type PredefinedEvent, type ProvideDataOperationConfig, ProvideDataOperationFull, type ProvideDataOperationPostResponseStart, type ProvideDataOperationSpecType, type ProvideDataOperationStart, type ProvideIdentifierError, type ProvideIdentifierFinish, type ProvideIdentifierPostResponseStart, type ProvideIdentifierSpecType, type ProvideIdentifierStart, type QueueOptions, RequestQueue, SDK_NAME, SDK_VERSION, type SdkInfo, type SdkReliabilityConfig, type SdkRetryConfig, SessionStorage, type SmsOTPOperationConfig, type SmsOTPOperationPostResponseStart, type SmsOTPOperationSpecType, SmsOtpOperationFull, type SocialLoginExchangeCodeFinished, type SocialLoginExchangeCodeStart, type SocialLoginGetRedirectUrlFinished, type SocialLoginGetRedirectUrlStart, SocialLoginOperationFull, type SocialLoginProviderType, type SocialLoginSpecType, type StepHelper, type StepOptions, type StorageEngine, type SubflowTrigger, type SubflowType, type TelemetryEntry, type TelemetryLevel, type TelemetrySink, type TrackerOptions, type Transport, type TransportMakeRequestResponse, type TransportOptions, type UserReference, cacheConfig, clearExperiment, clearExperiments, createLogger, destroy, getExperiments, getSessionId, getTracker, init, loadCachedConfig, logError, logInfo, parseReliabilityConfig, resetSession, setExperiment, setExperiments, telemetry };
+export { type AppConfirmationOperationCeremonyTypedError, AppConfirmationOperationFull, type AppConfirmationOperationRetryReason, type AppConfirmationOperationSpecType, type AppConfirmationOperationStart, type AuthDecisionFinished, type AuthDecisionStarted, AuthEventName, type AuthMethodDecisionFinished, type AuthMethodDecisionStarted, type AuthMethodType, type BaseEvent, CEREMONY_LOW_EVENT_TAIL_MS, CONFIG_BOUNDS, CONFIG_REQUEST_HEADER, CONFIG_STORAGE_KEY, type CaptchaOperationConfig, CaptchaOperationFull, type CaptchaOperationSpecType, type ClientCapabilities, type ClientEnvHandleMeta, type ClientEnvHandleMetaSource, type Conversion, CookieStorage, CorbadoTracker, type CreateLoggerOptions, type CustomEvent, DEFAULT_DEVICE_INFO_COLLECTOR_TIMEOUT_MS, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_SERIALIZED_LENGTH, DEFAULT_RELIABILITY_CONFIG, DEFAULT_SEQ_LOCK_TIMEOUT_MS, DEFAULT_SESSION_INACTIVITY_MS, type DeviceInfo, type DeviceInfoCollectionError, type DeviceInfoDataWeb, type DeviceType, EmailLinkOperationFull, type EmailLinkOperationPostResponseStart, type EmailLinkOperationSendStart, type EmailLinkOperationSpecType, type EmailOTPOperationConfig, type EmailOTPOperationPostResponseStart, type EmailOTPOperationSendOTPStart, type EmailOTPOperationSpecType, EmailOtpOperationFull, type Event, type EventBatch, type EventBatchMeta, type EventMeta, EventStore, type EventType, type FlowAutoFinished, type FlowDecided, type FlowFinished, type FlowReset, type FlowStarted, type FlowType, type FlushReason, type JavaScriptHighEntropy, LocalStorage, type Logger, type LowEvent, type MultiFlowReset, type MultiFlowStarted, NamespacedStorage, type NormalizedError, OUTBOX_LOCK_NAME, OUTBOX_STORAGE_KEY, type ObserveSdkConfigSnapshot, OperationFull, OperationFullProvideIdentifierWithCUI, type OperationFullProvideIdentifierWithCUIConfig, type OutboxEntry, type PasskeyEnrollmentCeremonyFinished, type PasskeyEnrollmentCeremonyStart, type PasskeyEnrollmentGetOptionsFinished, type PasskeyEnrollmentGetOptionsStart, type PasskeyEnrollmentOperationConfig, PasskeyEnrollmentOperationFull, type PasskeyEnrollmentPostResponseStart, type PasskeyLoginCUIGetOptionsFinished, type PasskeyLoginCUIGetOptionsStart, type PasskeyLoginCUISpecType, type PasskeyLoginCeremonyFinished, type PasskeyLoginCeremonyStart, type PasskeyLoginClientError, type PasskeyLoginFinish, type PasskeyLoginGetOptionsFinished, type PasskeyLoginGetOptionsStart, PasskeyLoginOperationFull, type PasskeyLoginPostResponseStart, type PasskeyLoginStartable, type PasskeyLoginSubmitted, type PasskeyOperationEnrollmentExplicitSpecType, type PasskeyOperationLoginExplicitSpecType, type PasswordEnrollmentAutoTrackConfig, PasswordEnrollmentOperationFull, type PasswordEnrollmentTypedError, type PasswordLoginAutoTrackConfig, type PasswordLoginCUICeremonyStart, type PasswordLoginCUIGetOptionsFinished, type PasswordLoginCUIGetOptionsStart, type PasswordLoginCUISpecType, type PasswordLoginCUITypedError, PasswordLoginOperationFull, type PasswordLoginTypedError, type PredefinedEvent, type ProvideDataOperationConfig, ProvideDataOperationFull, type ProvideDataOperationPostResponseStart, type ProvideDataOperationSpecType, type ProvideDataOperationStart, type ProvideIdentifierError, type ProvideIdentifierFinish, type ProvideIdentifierPostResponseStart, type ProvideIdentifierSpecType, type ProvideIdentifierStart, type QueueOptions, RequestQueue, SDK_NAME, SDK_VERSION, type SdkInfo, type SdkReliabilityConfig, type SdkRetryConfig, SessionStorage, type SmsOTPOperationConfig, type SmsOTPOperationPostResponseStart, type SmsOTPOperationSpecType, SmsOtpOperationFull, type SocialLoginExchangeCodeFinished, type SocialLoginExchangeCodeStart, type SocialLoginGetRedirectUrlFinished, type SocialLoginGetRedirectUrlStart, SocialLoginOperationFull, type SocialLoginProviderType, type SocialLoginSpecType, type StepHelper, type StepOptions, type StorageEngine, type SubflowTrigger, type SubflowType, type TelemetryEntry, type TelemetryLevel, type TelemetrySink, type TrackerOptions, type Transport, type TransportMakeRequestResponse, type TransportOptions, type UserReference, cacheConfig, clearExperiment, clearExperiments, createLogger, destroy, getExperiments, getSessionId, getTracker, init, loadCachedConfig, logError, logInfo, namespacedKey, parseReliabilityConfig, resetSession, setExperiment, setExperiments, telemetry };