@jayoncode/browser-lifecycle API

---

@jayoncode/browser-lifecycle API

Classes

BrowserLifecycleError

Base error for all public Browser Lifecycle infrastructure failures.

Extends

• Error

Extended by

• ConfigurationError
• InitializationError
• LifecycleError
• ModuleRegistryError
• PluginError
• UnsupportedFeatureError

Constructors

Constructor

new BrowserLifecycleError(
   message: string, 
   code: BrowserLifecycleErrorCode, 
   options?: BrowserLifecycleErrorOptions): BrowserLifecycleError;

Parameters

Parameter	Type
message	string
code	BrowserLifecycleErrorCode
options	BrowserLifecycleErrorOptions

Returns

BrowserLifecycleError

Overrides

Error.constructor

Properties

Property	Modifier	Type
code	readonly	BrowserLifecycleErrorCode
details	readonly	Readonly<PlainObject> | undefined

---

ConfigurationError

Error thrown when configuration input is invalid.

Extends

• BrowserLifecycleError

Constructors

Constructor

new ConfigurationError(message: string, options?: BrowserLifecycleErrorOptions): ConfigurationError;

Parameters

Parameter	Type
message	string
options	BrowserLifecycleErrorOptions

Returns

ConfigurationError

Overrides

BrowserLifecycleError.constructor

Properties

Property	Modifier	Type	Inherited from
code	readonly	BrowserLifecycleErrorCode	BrowserLifecycleError.code
details	readonly	Readonly<PlainObject> | undefined	BrowserLifecycleError.details

---

UnsupportedFeatureError

Error thrown when a required feature is unavailable.

Extends

• BrowserLifecycleError

Constructors

Constructor

new UnsupportedFeatureError(message: string, options?: BrowserLifecycleErrorOptions): UnsupportedFeatureError;

Parameters

Parameter	Type
message	string
options	BrowserLifecycleErrorOptions

Returns

UnsupportedFeatureError

Overrides

BrowserLifecycleError.constructor

Properties

Property	Modifier	Type	Inherited from
code	readonly	BrowserLifecycleErrorCode	BrowserLifecycleError.code
details	readonly	Readonly<PlainObject> | undefined	BrowserLifecycleError.details

---

InitializationError

Error thrown when the package cannot initialize correctly.

Extends

• BrowserLifecycleError

Constructors

Constructor

new InitializationError(message: string, options?: BrowserLifecycleErrorOptions): InitializationError;

Parameters

Parameter	Type
message	string
options	BrowserLifecycleErrorOptions

Returns

InitializationError

Overrides

BrowserLifecycleError.constructor

Properties

Property	Modifier	Type	Inherited from
code	readonly	BrowserLifecycleErrorCode	BrowserLifecycleError.code
details	readonly	Readonly<PlainObject> | undefined	BrowserLifecycleError.details

---

LifecycleError

Error thrown when a lifecycle transition is invalid.

Extends

• BrowserLifecycleError

Constructors

Constructor

new LifecycleError(message: string, options?: BrowserLifecycleErrorOptions): LifecycleError;

Parameters

Parameter	Type
message	string
options	BrowserLifecycleErrorOptions

Returns

LifecycleError

Overrides

BrowserLifecycleError.constructor

Properties

Property	Modifier	Type	Inherited from
code	readonly	BrowserLifecycleErrorCode	BrowserLifecycleError.code
details	readonly	Readonly<PlainObject> | undefined	BrowserLifecycleError.details

---

ModuleRegistryError

Error thrown when the module registry is used incorrectly.

Extends

• BrowserLifecycleError

Constructors

Constructor

new ModuleRegistryError(message: string, options?: BrowserLifecycleErrorOptions): ModuleRegistryError;

Parameters

Parameter	Type
message	string
options	BrowserLifecycleErrorOptions

Returns

ModuleRegistryError

Overrides

BrowserLifecycleError.constructor

Properties

Property	Modifier	Type	Inherited from
code	readonly	BrowserLifecycleErrorCode	BrowserLifecycleError.code
details	readonly	Readonly<PlainObject> | undefined	BrowserLifecycleError.details

---

PluginError

Placeholder plugin error used before the plugin system is implemented.

Extends

• BrowserLifecycleError

Constructors

Constructor

new PluginError(message: string, options?: BrowserLifecycleErrorOptions): PluginError;

Parameters

Parameter	Type
message	string
options	BrowserLifecycleErrorOptions

Returns

PluginError

Overrides

BrowserLifecycleError.constructor

Properties

Property	Modifier	Type	Inherited from
code	readonly	BrowserLifecycleErrorCode	BrowserLifecycleError.code
details	readonly	Readonly<PlainObject> | undefined	BrowserLifecycleError.details

---

TypedEventEmitter

Generic typed event emitter used by Browser Lifecycle Manager internals.

Type Parameters

Type Parameter
TEventMap extends EventMap

Constructors

Constructor

new TypedEventEmitter<TEventMap>(options?: TypedEventEmitterOptions<TEventMap>): TypedEventEmitter<TEventMap>;

Parameters

Parameter	Type
options	TypedEventEmitterOptions<TEventMap>

Returns

TypedEventEmitter<TEventMap>

Methods

on()

on<TEventName>(event: TEventName, listener: EventListener<TEventMap, TEventName>): EventSubscription<TEventName>;

Registers a persistent listener.

Type Parameters

Type Parameter
TEventName extends string

Parameters

Parameter	Type
event	TEventName
listener	EventListener<TEventMap, TEventName>

Returns

EventSubscription<TEventName>

off()

off<TEventName>(event: TEventName, listener: EventListener<TEventMap, TEventName>): void;

Removes the first listener matching the provided function reference.

Type Parameters

Type Parameter
TEventName extends string

Parameters

Parameter	Type
event	TEventName
listener	EventListener<TEventMap, TEventName>

Returns

void

once()

once<TEventName>(event: TEventName, listener: EventListener<TEventMap, TEventName>): EventSubscription<TEventName>;

Registers a one-time listener.

Type Parameters

Type Parameter
TEventName extends string

Parameters

Parameter	Type
event	TEventName
listener	EventListener<TEventMap, TEventName>

Returns

EventSubscription<TEventName>

emit()

emit<TEventName>(
   event: TEventName, 
   payload: EventPayload<TEventMap, TEventName>, 
options?: EmitEventOptions): EventDispatchMetadata<TEventName>;

Emits an event synchronously and returns dispatch metadata.

Type Parameters

Type Parameter
TEventName extends string

Parameters

Parameter	Type
event	TEventName
payload	EventPayload<TEventMap, TEventName>
options	EmitEventOptions

Returns

EventDispatchMetadata<TEventName>

listeners()

listeners<TEventName>(event: TEventName): readonly EventListener<TEventMap, TEventName>[];

Returns the active listeners for one event in registration order.

Type Parameters

Type Parameter
TEventName extends string

Parameters

Parameter	Type
event	TEventName

Returns

readonly EventListener<TEventMap, TEventName>[]

listenerCount()

listenerCount(event?: EventName<TEventMap>): number;

Returns the active listener count for one event or for the full emitter.

Parameters

Parameter	Type
event?	EventName<TEventMap>

Returns

number

hasListeners()

hasListeners(event?: EventName<TEventMap>): boolean;

Returns true when listeners exist for one event or for the entire emitter.

Parameters

Parameter	Type
event?	EventName<TEventMap>

Returns

boolean

removeAll()

removeAll(event?: EventName<TEventMap>): void;

Removes all listeners for one event or for the entire emitter.

Parameters

Parameter	Type
event?	EventName<TEventMap>

Returns

void

destroy()

destroy(): void;

Destroys the emitter and clears all listeners.

Returns

void

definitions()

definitions(): readonly EventDefinition<EventName<TEventMap>>[];

Returns the registered definitions for diagnostics and tests.

Returns

readonly EventDefinition<EventName<TEventMap>>[]

stats()

stats<TEventName>(event: TEventName): EventRegistryStats<TEventName>;

Returns dispatch statistics for one event.

Type Parameters

Type Parameter
TEventName extends string

Parameters

Parameter	Type
event	TEventName

Returns

EventRegistryStats<TEventName>

Interfaces

PageVisibleEventMetadata

Metadata carried by page:visible events.

Extends

• PlainObject

Extended by

• PageHiddenEventMetadata

Indexable

[key: string]: unknown

Properties

Property	Modifier	Type
reason	readonly	"initial" | "visibilitychange"

---

PageHiddenEventMetadata

Metadata carried by page:hidden events.

Extends

• PageVisibleEventMetadata

Indexable

[key: string]: unknown

Properties

Property	Modifier	Type	Inherited from
reason	readonly	"initial" | "visibilitychange"	PageHiddenEventMetadata.reason
likelyLastSignal	readonly	boolean	-

---

BrowserLifecycleTimestamps

Timestamp metadata exposed in snapshot reads.

Properties

Property	Modifier	Type
createdAt	readonly	number
disposedAt?	readonly	number
lastEventAt?	readonly	number
startedAt?	readonly	number
stoppedAt?	readonly	number
updatedAt	readonly	number

---

BrowserLifecycleSnapshot

Public snapshot shape returned by the Session Core.

Properties

Property	Modifier	Type
activity	readonly	BrowserLifecycleActivityState
attention	readonly	BrowserLifecycleAttentionState
capabilities	readonly	BrowserLifecycleCapabilities
connectivity	readonly	BrowserLifecycleConnectivityState
lifecycle	readonly	BrowserLifecyclePageState
phase	readonly	BrowserLifecyclePhase
tab	readonly	BrowserLifecycleTabState
timestamps	readonly	BrowserLifecycleTimestamps
visibility	readonly	BrowserLifecycleVisibilityState

---

BrowserLifecycleEvent

Shared event payload contract for normalized public events.

Type Parameters

Type Parameter	Default type
TType extends BrowserLifecycleEventName	-
TCurrent	-
TPrevious	-
TMetadata extends PlainObject | undefined	PlainObject | undefined

Properties

Property	Modifier	Type
current	readonly	TCurrent
metadata	readonly	TMetadata
previous	readonly	TPrevious
snapshot	readonly	BrowserLifecycleSnapshot
source	readonly	BrowserLifecycleEventSource
timestamp	readonly	number
type	readonly	TType

---

BrowserLifecycleEventMap

Public event payload map used by the Session Core event API.

Properties

Property	Modifier	Type
activity:detected	readonly	BrowserLifecycleEvent<"activity:detected", "active", BrowserLifecycleActivityState, | { activitySource: string; } | undefined>
activity:reset	readonly	BrowserLifecycleEvent<"activity:reset", "active", BrowserLifecycleActivityState, | { activitySource: string; } | undefined>
connection:offline	readonly	BrowserLifecycleEvent<"connection:offline", "offline", BrowserLifecycleConnectivityState, | { advisory: true; reason?: "offline" | "initial"; } | undefined>
connection:online	readonly	BrowserLifecycleEvent<"connection:online", "online", BrowserLifecycleConnectivityState, | { advisory: true; reason?: "online" | "initial"; } | undefined>
connection:reconnect	readonly	BrowserLifecycleEvent<"connection:reconnect", "online", "offline", | { advisory: true; offlineDuration: number; } | undefined>
page:hidden	readonly	BrowserLifecycleEvent<"page:hidden", "hidden", BrowserLifecycleVisibilityState, PageHiddenEventMetadata>
page:resume	readonly	BrowserLifecycleEvent<"page:resume", "active", BrowserLifecyclePageState>
page:suspend	readonly	BrowserLifecycleEvent<"page:suspend", "hidden" | "frozen" | "terminated", BrowserLifecyclePageState>
page:visible	readonly	BrowserLifecycleEvent<"page:visible", "visible", BrowserLifecycleVisibilityState, PageVisibleEventMetadata>
plugin:error	readonly	BrowserLifecycleEvent<"plugin:error", "error", "registered" | "ready" | undefined, | { hook?: string; pluginId: string; } | undefined>
plugin:registered	readonly	BrowserLifecycleEvent<"plugin:registered", "registered", undefined, | { pluginId: string; } | undefined>
plugin:removed	readonly	BrowserLifecycleEvent<"plugin:removed", "removed", "registered" | undefined, | { pluginId: string; reason?: string; } | undefined>
session:active	readonly	BrowserLifecycleEvent<"session:active", "active", BrowserLifecycleActivityState, | { activitySource: string; idleDuration?: number; } | undefined>
session:idle	readonly	BrowserLifecycleEvent<"session:idle", "idle", BrowserLifecycleActivityState, | { idleTimeout: number; lastActivityAt: number; } | undefined>
session:restored	readonly	BrowserLifecycleEvent<"session:restored", "running" | "stopped", BrowserLifecyclePhase>
session:started	readonly	BrowserLifecycleEvent<"session:started", "running", BrowserLifecyclePhase, | { autoStart: boolean; } | undefined>
session:stopped	readonly	BrowserLifecycleEvent<"session:stopped", "stopped", BrowserLifecyclePhase, | { reason: "dispose" | "manual-stop"; } | undefined>
tab:primary	readonly	BrowserLifecycleEvent<"tab:primary", "primary", BrowserLifecycleTabState, | { reason?: string; tabId?: string; transport?: string; } | undefined>
tab:secondary	readonly	BrowserLifecycleEvent<"tab:secondary", "secondary", BrowserLifecycleTabState, | { reason?: string; tabId?: string; transport?: string; } | undefined>
tab:message	readonly	BrowserLifecycleEvent<"tab:message", "message", undefined, | { messageType: string; senderId: string; value?: string; } | undefined>
window:blur	readonly	BrowserLifecycleEvent<"window:blur", "unfocused", BrowserLifecycleAttentionState>
window:focus	readonly	BrowserLifecycleEvent<"window:focus", "focused", BrowserLifecycleAttentionState>

---

BrowserLifecycle

Public BrowserLifecycle runtime contract.

Methods

dispose()

dispose(): void;

Returns

void

getCapabilities()

getCapabilities(): Readonly<BrowserLifecycleCapabilities>;

Returns

Readonly<BrowserLifecycleCapabilities>

getPluginHookLog()

getPluginHookLog(): readonly BrowserLifecyclePluginHookLogEntry[];

Returns

readonly BrowserLifecyclePluginHookLogEntry[]

getPlugins()

getPlugins(): readonly BrowserLifecyclePluginDiagnostic[];

Returns

readonly BrowserLifecyclePluginDiagnostic[]

getRuntimeDiagnostics()

getRuntimeDiagnostics(): BrowserLifecycleRuntimeDiagnostics;

Returns

BrowserLifecycleRuntimeDiagnostics

getSnapshot()

getSnapshot(): Readonly<BrowserLifecycleSnapshot>;

Returns

Readonly<BrowserLifecycleSnapshot>

isRunning()

isRunning(): boolean;

Returns

boolean

off()

off<TEventName>(event: TEventName, listener: BrowserLifecycleEventListener<TEventName>): void;

Type Parameters

Type Parameter
TEventName extends BrowserLifecycleEventName

Parameters

Parameter	Type
event	TEventName
listener	BrowserLifecycleEventListener<TEventName>

Returns

void

on()

on<TEventName>(event: TEventName, listener: BrowserLifecycleEventListener<TEventName>): () => void;

Type Parameters

Type Parameter
TEventName extends BrowserLifecycleEventName

Parameters

Parameter	Type
event	TEventName
listener	BrowserLifecycleEventListener<TEventName>

Returns

() => void

once()

once<TEventName>(event: TEventName, listener: BrowserLifecycleEventListener<TEventName>): () => void;

Type Parameters

Type Parameter
TEventName extends BrowserLifecycleEventName

Parameters

Parameter	Type
event	TEventName
listener	BrowserLifecycleEventListener<TEventName>

Returns

() => void

setPluginEnabled()

setPluginEnabled(pluginId: string, enabled: boolean): void;

Parameters

Parameter	Type
pluginId	string
enabled	boolean

Returns

void

start()

start(): void;

Returns

void

stop()

stop(): void;

Returns

void

subscribe()

subscribe(listener: BrowserLifecycleSubscriber): () => void;

Parameters

Parameter	Type
listener	BrowserLifecycleSubscriber

Returns

() => void

use()

use(plugin: BrowserLifecyclePlugin): void;

Parameters

Parameter	Type
plugin	BrowserLifecyclePlugin

Returns

void

---

BrowserLifecycleEventStat

Per-event dispatch statistics exposed for diagnostics tooling.

Properties

Property	Modifier	Type
emissionCount	readonly	number
errorCount	readonly	number
event	readonly	BrowserLifecycleEventName
lastDispatchedAt?	readonly	number
listenerCount	readonly	number

---

BrowserLifecycleRuntimeDiagnostics

Runtime diagnostics snapshot for performance and developer tooling.

Properties

Property	Modifier	Type
capabilities	readonly	Readonly<BrowserLifecycleCapabilities>
debug	readonly	boolean
eventBufferSize	readonly	number
eventStats	readonly	readonly BrowserLifecycleEventStat[]
isRunning	readonly	boolean
moduleCount	readonly	number
phase	readonly	BrowserLifecyclePhase
pluginCount	readonly	number
subscriberCount	readonly	number
totalEmissionCount	readonly	number
totalListenerCount	readonly	number

---

ConditionHandle

Methods

unsubscribe()

unsubscribe(): void;

Returns

void

---

ConditionsApi

Methods

visible()

visible(handler: ConditionHandler): ConditionHandle;

Parameters

Parameter	Type
handler	ConditionHandler

Returns

ConditionHandle

hidden()

hidden(handler: ConditionHandler): ConditionHandle;

Parameters

Parameter	Type
handler	ConditionHandler

Returns

ConditionHandle

focused()

focused(handler: ConditionHandler): ConditionHandle;

Parameters

Parameter	Type
handler	ConditionHandler

Returns

ConditionHandle

online()

online(handler: ConditionHandler): ConditionHandle;

Parameters

Parameter	Type
handler	ConditionHandler

Returns

ConditionHandle

dispose()

dispose(): void;

Unsubscribe all active condition handlers. Does not dispose the underlying session.

Returns

void

---

CreateConditionsApiOptions

Properties

Property	Modifier	Type	Description
onHandlerError?	readonly	(error: unknown) => void	Invoked when a condition handler throws (session continues).

---

ResilienceApi

Methods

onReconnect()

onReconnect(handler: ResilienceHandler<"connection:reconnect">): Unsubscribe;

Parameters

Parameter	Type
handler	ResilienceHandler<"connection:reconnect">

Returns

Unsubscribe

onWake()

onWake(handler: ResilienceHandler<"page:resume">): Unsubscribe;

Maps to page:resume.

Parameters

Parameter	Type
handler	ResilienceHandler<"page:resume">

Returns

Unsubscribe

onRestore()

onRestore(handler: ResilienceHandler<"session:restored">): Unsubscribe;

Maps to session:restored.

Parameters

Parameter	Type
handler	ResilienceHandler<"session:restored">

Returns

Unsubscribe

onRecover()

onRecover(handler: (event: 
  | {
  current: "online";
  metadata:   | {
     advisory: true;
     offlineDuration: number;
   }
     | undefined;
  previous: "offline";
  snapshot: {
     activity: BrowserLifecycleActivityState;
     attention: BrowserLifecycleAttentionState;
     capabilities: {
        abortController: boolean;
        broadcastChannel: boolean;
        connectivity: boolean;
        focus: boolean;
        idle: boolean;
        pageLifecycle: boolean;
        requestIdleCallback: boolean;
        visibility: boolean;
     };
     connectivity: BrowserLifecycleConnectivityState;
     lifecycle: BrowserLifecyclePageState;
     phase: BrowserLifecyclePhase;
     tab: BrowserLifecycleTabState;
     timestamps: {
        createdAt: number;
        disposedAt?: number;
        lastEventAt?: number;
        startedAt?: number;
        stoppedAt?: number;
        updatedAt: number;
     };
     visibility: BrowserLifecycleVisibilityState;
  };
  source: BrowserLifecycleEventSource;
  timestamp: number;
  type: "connection:reconnect";
}
  | {
  current: "active";
  metadata:   | {
   [key: string]: unknown;
   }
     | undefined;
  previous: BrowserLifecyclePageState;
  snapshot: {
     activity: BrowserLifecycleActivityState;
     attention: BrowserLifecycleAttentionState;
     capabilities: {
        abortController: boolean;
        broadcastChannel: boolean;
        connectivity: boolean;
        focus: boolean;
        idle: boolean;
        pageLifecycle: boolean;
        requestIdleCallback: boolean;
        visibility: boolean;
     };
     connectivity: BrowserLifecycleConnectivityState;
     lifecycle: BrowserLifecyclePageState;
     phase: BrowserLifecyclePhase;
     tab: BrowserLifecycleTabState;
     timestamps: {
        createdAt: number;
        disposedAt?: number;
        lastEventAt?: number;
        startedAt?: number;
        stoppedAt?: number;
        updatedAt: number;
     };
     visibility: BrowserLifecycleVisibilityState;
  };
  source: BrowserLifecycleEventSource;
  timestamp: number;
  type: "page:resume";
}
  | {
  current: "running" | "stopped";
  metadata:   | {
   [key: string]: unknown;
   }
     | undefined;
  previous: BrowserLifecyclePhase;
  snapshot: {
     activity: BrowserLifecycleActivityState;
     attention: BrowserLifecycleAttentionState;
     capabilities: {
        abortController: boolean;
        broadcastChannel: boolean;
        connectivity: boolean;
        focus: boolean;
        idle: boolean;
        pageLifecycle: boolean;
        requestIdleCallback: boolean;
        visibility: boolean;
     };
     connectivity: BrowserLifecycleConnectivityState;
     lifecycle: BrowserLifecyclePageState;
     phase: BrowserLifecyclePhase;
     tab: BrowserLifecycleTabState;
     timestamps: {
        createdAt: number;
        disposedAt?: number;
        lastEventAt?: number;
        startedAt?: number;
        stoppedAt?: number;
        updatedAt: number;
     };
     visibility: BrowserLifecycleVisibilityState;
  };
  source: BrowserLifecycleEventSource;
  timestamp: number;
  type: "session:restored";
}) => void): Unsubscribe;

Fires on reconnect, wake (page:resume), or restore — ChatGPT-style recovery. Returns a single unsubscribe for all three.

Parameters

Parameter

Type

handler

(event: | { current: "online"; metadata: | { advisory: true; offlineDuration: number; } | undefined; previous: "offline"; snapshot: { activity: BrowserLifecycleActivityState; attention: BrowserLifecycleAttentionState; capabilities: { abortController: boolean; broadcastChannel: boolean; connectivity: boolean; focus: boolean; idle: boolean; pageLifecycle: boolean; requestIdleCallback: boolean; visibility: boolean; }; connectivity: BrowserLifecycleConnectivityState; lifecycle: BrowserLifecyclePageState; phase: BrowserLifecyclePhase; tab: BrowserLifecycleTabState; timestamps: { createdAt: number; disposedAt?: number; lastEventAt?: number; startedAt?: number; stoppedAt?: number; updatedAt: number; }; visibility: BrowserLifecycleVisibilityState; }; source: BrowserLifecycleEventSource; timestamp: number; type: "connection:reconnect"; } | { current: "active"; metadata: | { [key: string]: unknown; } | undefined; previous: BrowserLifecyclePageState; snapshot: { activity: BrowserLifecycleActivityState; attention: BrowserLifecycleAttentionState; capabilities: { abortController: boolean; broadcastChannel: boolean; connectivity: boolean; focus: boolean; idle: boolean; pageLifecycle: boolean; requestIdleCallback: boolean; visibility: boolean; }; connectivity: BrowserLifecycleConnectivityState; lifecycle: BrowserLifecyclePageState; phase: BrowserLifecyclePhase; tab: BrowserLifecycleTabState; timestamps: { createdAt: number; disposedAt?: number; lastEventAt?: number; startedAt?: number; stoppedAt?: number; updatedAt: number; }; visibility: BrowserLifecycleVisibilityState; }; source: BrowserLifecycleEventSource; timestamp: number; type: "page:resume"; } | { current: "running" | "stopped"; metadata: | { [key: string]: unknown; } | undefined; previous: BrowserLifecyclePhase; snapshot: { activity: BrowserLifecycleActivityState; attention: BrowserLifecycleAttentionState; capabilities: { abortController: boolean; broadcastChannel: boolean; connectivity: boolean; focus: boolean; idle: boolean; pageLifecycle: boolean; requestIdleCallback: boolean; visibility: boolean; }; connectivity: BrowserLifecycleConnectivityState; lifecycle: BrowserLifecyclePageState; phase: BrowserLifecyclePhase; tab: BrowserLifecycleTabState; timestamps: { createdAt: number; disposedAt?: number; lastEventAt?: number; startedAt?: number; stoppedAt?: number; updatedAt: number; }; visibility: BrowserLifecycleVisibilityState; }; source: BrowserLifecycleEventSource; timestamp: number; type: "session:restored"; }) => void

Returns

Unsubscribe

dispose()

dispose(): void;

Unsubscribe all active resilience handlers. Does not dispose the underlying session.

Returns

void

---

CreateResilienceApiOptions

Properties

Property	Modifier	Type	Description
onHandlerError?	readonly	(error: unknown) => void	Invoked when a handler throws (session continues).

---

WaitOptions

Properties

Property	Modifier	Type
timeoutMs?	readonly	number
signal?	readonly	AbortSignal

---

WaitApi

Methods

untilVisible()

untilVisible(options?: WaitOptions): Promise<void>;

Parameters

Parameter	Type
options?	WaitOptions

Returns

Promise<void>

untilHidden()

untilHidden(options?: WaitOptions): Promise<void>;

Parameters

Parameter	Type
options?	WaitOptions

Returns

Promise<void>

untilFocused()

untilFocused(options?: WaitOptions): Promise<void>;

Parameters

Parameter	Type
options?	WaitOptions

Returns

Promise<void>

untilBlurred()

untilBlurred(options?: WaitOptions): Promise<void>;

Parameters

Parameter	Type
options?	WaitOptions

Returns

Promise<void>

untilOnline()

untilOnline(options?: WaitOptions): Promise<void>;

Parameters

Parameter	Type
options?	WaitOptions

Returns

Promise<void>

untilOffline()

untilOffline(options?: WaitOptions): Promise<void>;

Parameters

Parameter	Type
options?	WaitOptions

Returns

Promise<void>

dispose()

dispose(): void;

Rejects all pending waits and prevents new ones. Does not dispose the underlying session.

Returns

void

---

EventDefinition

Event definition metadata stored by the internal registry.

Type Parameters

Type Parameter	Default type
TEventName extends string	string

Properties

Property	Modifier	Type
description?	readonly	string
experimental?	readonly	boolean
internal?	readonly	boolean
name	readonly	TEventName
public?	readonly	boolean

---

EventDispatchMetadata

Dispatch metadata created for each emission.

Type Parameters

Type Parameter	Default type
TEventName extends string	string

Properties

Property	Modifier	Type
dispatchId	readonly	number
internal	readonly	Readonly<Record<string, unknown>> | undefined
listenerCount	readonly	number
source	readonly	string
timestamp	readonly	number
type	readonly	TEventName

---

EventSubscription

Cleanup handle returned by subscription methods.

Type Parameters

Type Parameter	Default type
TEventName extends string	string

Properties

Property	Modifier	Type
active	readonly	boolean
event	readonly	TEventName

Methods

unsubscribe()

unsubscribe(): void;

Returns

void

---

EventDispatchContext

Internal dispatch context passed to error handlers.

Type Parameters

Type Parameter
TEventMap extends EventMap
TEventName extends EventName<TEventMap>

Properties

Property	Modifier	Type
metadata	readonly	EventDispatchMetadata<TEventName>
payload	readonly	EventPayload<TEventMap, TEventName>

---

EmitEventOptions

Public emit options for metadata creation.

Properties

Property	Modifier	Type
internal?	readonly	Readonly<Record<string, unknown>>
source?	readonly	string

---

EventRegistryStats

Statistics tracked by the internal event registry.

Type Parameters

Type Parameter	Default type
TEventName extends string	string

Properties

Property	Modifier	Type
definition	readonly	EventDefinition<TEventName> | undefined
emissionCount	readonly	number
errorCount	readonly	number
lastDispatchedAt	readonly	number | undefined
lastDispatchSource	readonly	string | undefined
listenerCount	readonly	number

---

TypedEventEmitterOptions

Constructor options for the typed event emitter.

Type Parameters

Type Parameter
TEventMap extends EventMap

Properties

Property	Modifier	Type
definitions?	readonly	readonly EventDefinition<Extract<keyof TEventMap, string>>[]
onListenerError?	readonly	EventListenerErrorHandler<TEventMap>
timeProvider?	readonly	() => number

---

CreateActivityApiOptions

Properties

Property	Modifier	Type	Description
trackLastActiveAt?	readonly	boolean	When true (default), subscribe to activity-related public events to track lastActiveAt. Set false for a pure snapshot projector with zero subscriptions.

---

ActivityView

Properties

Property	Modifier	Type
status	readonly	ActivityStatus
lastActiveAt	readonly	number | undefined

---

ActivityApi

Methods

state()

state(): ActivityView;

Current core-backed activity view.

Returns

ActivityView

isActive()

isActive(): boolean;

Returns

boolean

isIdle()

isIdle(): boolean;

Returns

boolean

isUnknown()

isUnknown(): boolean;

Returns

boolean

lastActiveAt()

lastActiveAt(): number | undefined;

Returns

number | undefined

lastInteraction()

lastInteraction(): number | undefined;

Alias for lastActiveAt() (ChatGPT lastInteraction).

Returns

number | undefined

idleTime()

idleTime(now?: number): number;

Current idle streak in ms (0 when active/unknown). Uses wall clock vs lastActiveAt when idle.

Parameters

Parameter	Type
now?	number

Returns

number

dispose()

dispose(): void;

Detach optional event tracking used for lastActiveAt. Safe to call multiple times. Does not dispose the underlying session.

Returns

void

---

SessionHealth

Properties

Property	Modifier	Type
active	readonly	boolean
healthy	readonly	boolean
recovering	readonly	boolean
degraded	readonly	boolean
online	readonly	boolean
focused	readonly	boolean
visible	readonly	boolean
idle	readonly	boolean

---

SessionHealthApi

Methods

health()

health(): Readonly<SessionHealth>;

Returns

Readonly<SessionHealth>

dispose()

dispose(): void;

Returns

void

---

CreateMetricsApiOptions

Properties

Property	Modifier	Type	Description
timeProvider?	readonly	() => number	Defaults to Date.now. Inject for tests.

---

MetricsSnapshot

Properties

Property	Modifier	Type	Description
sessionMs	readonly	number	Wall-clock ms since this metrics instance started tracking.
visibleMs	readonly	number	Cumulative durations (ms).
hiddenMs	readonly	number	-
focusedMs	readonly	number	-
blurredMs	readonly	number	-
activeMs	readonly	number	-
idleMs	readonly	number	-
onlineMs	readonly	number	-
offlineMs	readonly	number	-
sleepMs	readonly	number	Time between page:suspend and page:resume.
hiddenCount	readonly	number	Event counts.
visibilityChangeCount	readonly	number	-
focusCount	readonly	number	-
blurCount	readonly	number	-
idleCount	readonly	number	-
reconnectCount	readonly	number	-
sleepCount	readonly	number	-
primaryTabSwitchCount	readonly	number	-
attentionScore	readonly	number	0–100 attention score: round(100 * focusedMs / (focusedMs + blurredMs + hiddenMs)) when the denominator is > 0; otherwise 0.

---

MetricsStats

Count-focused view (ChatGPT “browser statistics”).

Properties

Property	Modifier	Type
focusCount	readonly	number
blurCount	readonly	number
visibilityChangeCount	readonly	number
hiddenCount	readonly	number
idleCount	readonly	number
sleepCount	readonly	number
reconnectCount	readonly	number
primaryTabSwitchCount	readonly	number

---

AttentionReport

Attention breakdown (ChatGPT session.attention.report()).

Properties

Property	Modifier	Type
score	readonly	number
focusedMs	readonly	number
blurredMs	readonly	number
hiddenMs	readonly	number
focusedRatio	readonly	number
blurredRatio	readonly	number
hiddenRatio	readonly	number

---

MetricsApi

Methods

snapshot()

snapshot(): Readonly<MetricsSnapshot>;

Returns

Readonly<MetricsSnapshot>

stats()

stats(): Readonly<MetricsStats>;

Count statistics subset.

Returns

Readonly<MetricsStats>

attention()

attention(): Readonly<AttentionReport>;

Attention score + duration breakdown.

Returns

Readonly<AttentionReport>

sessionDuration()

sessionDuration(): number;

Returns

number

activeDuration()

activeDuration(): number;

Returns

number

hiddenDuration()

hiddenDuration(): number;

Returns

number

focusedDuration()

focusedDuration(): number;

Returns

number

idleDuration()

idleDuration(): number;

Returns

number

offlineDuration()

offlineDuration(): number;

Returns

number

sleepDuration()

sleepDuration(): number;

Returns

number

visibleDuration()

visibleDuration(): number;

Returns

number

reset()

reset(): void;

Returns

void

dispose()

dispose(): void;

Stop reducing and release subscriptions. Does not dispose the underlying session.

Returns

void

---

SessionPrediction

Properties

Property	Modifier	Type
likelyIdle	readonly	boolean
likelySleep	readonly	boolean
attentionScore	readonly	number
engagement	readonly	EngagementLevel

---

SessionPredictApi

Methods

predict()

predict(): Readonly<SessionPrediction>;

Returns

Readonly<SessionPrediction>

dispose()

dispose(): void;

Returns

void

---

CreateSessionPredictApiOptions

Properties

Property	Modifier	Type
metrics	readonly	Pick<MetricsApi, "snapshot" | "attention">
lifecycle	readonly	Pick<BrowserLifecycle, "getSnapshot">

---

ProjectPresenceOptions

Properties

Property	Modifier	Type	Description
requireActive?	readonly	boolean	When true, activity === "idle" counts as away, and activity === "unknown" makes presence unknown. Default false (idle not part of default policy).

---

PresenceView

Properties

Property	Modifier	Type	Description
status	readonly	PresenceStatus	-
reasons	readonly	readonly PresenceReason[]	Machine-readable reasons, e.g. ["hidden", "blurred", "offline"]

---

PresenceApi

Methods

state()

state(): PresenceView;

Returns

PresenceView

isPresent()

isPresent(): boolean;

Returns

boolean

isAway()

isAway(): boolean;

Returns

boolean

isUnknown()

isUnknown(): boolean;

Returns

boolean

label()

label(): PresenceLabel;

Uppercase label for ChatGPT-style ACTIVE / AWAY / UNKNOWN.

Returns

PresenceLabel

dispose()

dispose(): void;

No-op today (pure snapshot reads). Kept for symmetry with ActivityApi and future optional subscriptions.

Returns

void

---

CreateReportsApiOptions

Properties

Property	Modifier	Type	Description
metrics	readonly	Pick<MetricsApi, "snapshot" | "attention">	Required metrics source.
timeline?	readonly	Pick<TimelineApi, "events">	Optional timeline for evidence event ids.
evidenceLimit?	readonly	number	Max timeline ids to cite. Default 10.
timeProvider?	readonly	() => number	-

---

SessionSummaryReport

Properties

Property	Modifier	Type	Description
generatedAt	readonly	number	-
startedAt	readonly	number	-
endedAt	readonly	number	-
metrics	readonly	MetricsSnapshot	-
attention	readonly	AttentionReport	-
focusDuration	readonly	number	-
hiddenDuration	readonly	number	-
idleDuration	readonly	number	-
offlineDuration	readonly	number	-
activeDuration	readonly	number	-
sleepDuration	readonly	number	-
sessionDuration	readonly	number	-
highlights	readonly	readonly string[]	-
evidenceEventIds?	readonly	readonly string[]	Optional Timeline entry ids when a timeline is provided.

---

ReportsApi

Methods

sessionSummary()

sessionSummary(): SessionSummaryReport;

Build a summary on demand (no per-event work).

Returns

SessionSummaryReport

report()

report(): SessionSummaryReport;

Alias for sessionSummary() (ChatGPT session.report()).

Returns

SessionSummaryReport

dispose()

dispose(): void;

No-op reserved for symmetry with other intelligence APIs. Reports do not hold subscriptions.

Returns

void

---

CreateTimelineApiOptions

Properties

Property	Modifier	Type	Description
maxEvents	readonly	number	Hard cap on retained events. Required. Overflow drops the oldest entry (O(1)).
includeSnapshot?	readonly	boolean	When true (default), store a slim snapshot subset on each entry. Set false to retain only type + timestamp (lowest memory).
onOverflow?	readonly	(dropped: TimelineEntry) => void	Called when an entry is dropped due to capacity overflow.

---

TimelineEntry

Properties

Property	Modifier	Type	Description
id	readonly	string	-
type	readonly	BrowserLifecycleEventName	-
timestamp	readonly	number	-
snapshot?	readonly	Readonly<Partial<BrowserLifecycleSnapshot>>	Slim subset of snapshot at emission time (omitted when includeSnapshot is false).

---

TimelineApi

Methods

events()

events(): readonly TimelineEntry[];

Oldest → newest copy of retained entries.

Returns

readonly TimelineEntry[]

record()

record(): readonly TimelineEntry[];

Alias for events() (ChatGPT event timeline / session.record()).

Returns

readonly TimelineEntry[]

format()

format(options?: FormatTimelineOptions): readonly string[];

Human-readable lines for debugging / audit logs. Example: 10:05:42 page:hidden

Parameters

Parameter	Type
options?	FormatTimelineOptions

Returns

readonly string[]

clear()

clear(): void;

Returns

void

size()

size(): number;

Returns

number

maxEvents()

maxEvents(): number;

Maximum retained entries.

Returns

number

dispose()

dispose(): void;

Stop recording and release the buffer. Does not dispose the underlying session.

Returns

void

---

FormatTimelineOptions

Properties

Property	Modifier	Type	Description
timeZone?	readonly	string	Defaults to locale time string from each entry timestamp.
locale?	readonly	string	-

---

BrowserLifecyclePluginLifecycleTransition

Recorded plugin lifecycle transition for diagnostics.

Properties

Property	Modifier	Type
durationMs?	readonly	number
from	readonly	| BrowserLifecyclePluginPhase | undefined
timestamp	readonly	number
to	readonly	BrowserLifecyclePluginPhase

---

BrowserLifecyclePluginDiagnostic

Diagnostic snapshot for one registered plugin.

Properties

Property	Modifier	Type
author?	readonly	string
dependencies	readonly	readonly string[]
description?	readonly	string
enabled	readonly	boolean
hookCount	readonly	number
id	readonly	string
lifecycle	readonly	BrowserLifecyclePluginPhase
loadedAt?	readonly	number
name?	readonly	string
previousLifecycle?	readonly	BrowserLifecyclePluginPhase
priority	readonly	number
registeredAt	readonly	number
registrationOrder	readonly	number
transitionCount	readonly	number
transitions	readonly	readonly BrowserLifecyclePluginLifecycleTransition[]
version?	readonly	string

---

BrowserLifecyclePluginHookLogEntry

Recorded plugin hook execution for debugging and playground tooling.

Properties

Property	Modifier	Type
durationMs	readonly	number
eventType?	readonly	BrowserLifecycleEventName
hook	readonly	BrowserLifecyclePluginHookName
id	readonly	string
pluginId	readonly	string
source	readonly	"plugin-runtime"
timestamp	readonly	number

---

BrowserFeatureEnvironment

Minimal feature-detection environment used to keep capability checks SSR-safe and testable.

Properties

Property	Modifier	Type
AbortController?	readonly	unknown
BroadcastChannel?	readonly	unknown
document?	readonly	Record<string, unknown> & { hasFocus?: () => boolean; hidden?: boolean; visibilityState?: string; }
navigator?	readonly	Record<string, unknown> & { onLine?: boolean; }
requestIdleCallback?	readonly	unknown
window?	readonly	Record<string, unknown> & { addEventListener?: void; removeEventListener?: void; }

---

BrowserLifecycleCapabilities

Public capability snapshot returned by infrastructure feature detection.

Properties

Property	Modifier	Type
abortController	readonly	boolean
broadcastChannel	readonly	boolean
connectivity	readonly	boolean
focus	readonly	boolean
idle	readonly	boolean
pageLifecycle	readonly	boolean
requestIdleCallback	readonly	boolean
visibility	readonly	boolean

---

BrowserLifecyclePlugin

Plugin contract executed by the Session Core plugin runtime.

Properties

Property	Modifier	Type
author?	readonly	string
dependencies?	readonly	readonly string[]
description?	readonly	string
enabled?	readonly	boolean
id	readonly	string
name?	readonly	string
onDestroy?	readonly	(context: BrowserLifecyclePluginRuntimeContext) => void
onEvent?	readonly	(event: BrowserLifecycleEventName, payload: unknown) => void
onRegister?	readonly	(context: BrowserLifecyclePluginRuntimeContext) => void
onStart?	readonly	(context: BrowserLifecyclePluginRuntimeContext) => void
onStop?	readonly	(context: BrowserLifecyclePluginRuntimeContext) => void
priority?	readonly	number
version?	readonly	string

---

BrowserLifecyclePluginRuntimeContext

Read-only context passed to plugin lifecycle hooks.

Properties

Property	Modifier	Type
capabilities	readonly	BrowserLifecycleCapabilities
configuration	readonly	ResolvedBrowserLifecycleConfig
getSnapshot	readonly	() => Readonly<BrowserLifecycleSnapshot>

---

BrowserLifecycleCrossTabConfigInput

Optional cross-tab configuration overrides.

Properties

Property	Modifier	Type
channelName?	readonly	string
heartbeatInterval?	readonly	number
leaderTimeout?	readonly	number

---

BrowserLifecycleCrossTabConfig

Resolved cross-tab configuration used internally after validation.

Properties

Property	Modifier	Type
channelName	readonly	string
enabled	readonly	boolean
heartbeatInterval	readonly	number
leaderTimeout	readonly	number

---

BrowserLifecycleConfig

Public configuration accepted by the package during the core infrastructure phase.

Properties

Property	Modifier	Type
activityDebounce?	readonly	number
activityEvents?	readonly	| "default" | readonly BrowserLifecycleActivityEventName[]
autoStart?	readonly	boolean
crossTab?	readonly	| boolean | BrowserLifecycleCrossTabConfigInput
debug?	readonly	boolean
emitInitialState?	readonly	boolean
eventBufferSize?	readonly	number
idleTimeout?	readonly	number | false
plugins?	readonly	readonly BrowserLifecyclePlugin[]

---

ResolvedBrowserLifecycleConfig

Immutable resolved configuration returned by the configuration system.

Properties

Property	Modifier	Type
activityDebounce	readonly	number
activityEvents	readonly	readonly BrowserLifecycleActivityEventName[]
autoStart	readonly	boolean
crossTab	readonly	BrowserLifecycleCrossTabConfig
debug	readonly	boolean
emitInitialState	readonly	boolean
eventBufferSize	readonly	number
idleTimeout	readonly	number | false
plugins	readonly	readonly BrowserLifecyclePlugin[]

---

BrowserLifecycleValidationIssue

Internal validation issue shape used for detailed configuration errors.

Properties

Property	Modifier	Type
message	readonly	string
path	readonly	string

Type Aliases

BrowserLifecyclePhase

type BrowserLifecyclePhase = "created" | "disposed" | "running" | "stopped";

Public lifecycle phases exposed by the Session Core.

---

BrowserLifecycleAttentionState

type BrowserLifecycleAttentionState = "focused" | "unknown" | "unfocused";

Normalized attention state placeholder for current and future modules.

---

BrowserLifecycleActivityState

type BrowserLifecycleActivityState = "active" | "idle" | "unknown";

Normalized activity state placeholder for current and future modules.

---

BrowserLifecycleConnectivityState

type BrowserLifecycleConnectivityState = "offline" | "online" | "unknown";

Normalized advisory connectivity state placeholder for current and future modules.

---

BrowserLifecyclePageState

type BrowserLifecyclePageState = 
  | "active"
  | "discarded"
  | "frozen"
  | "hidden"
  | "passive"
  | "terminated"
  | "unknown";

Normalized lifecycle state placeholder for current and future modules.

---

BrowserLifecycleTabState

type BrowserLifecycleTabState = "primary" | "secondary" | "single" | "unknown";

Normalized tab role placeholder for current and future modules.

---

BrowserLifecycleEventSource

type BrowserLifecycleEventSource = 
  | "activity"
  | "connectivity"
  | "focus"
  | "internal"
  | "lifecycle"
  | "plugin"
  | "transport"
  | "visibility";

Public event source categories.

---

BrowserLifecycleEventName

type BrowserLifecycleEventName = 
  | "activity:detected"
  | "activity:reset"
  | "connection:offline"
  | "connection:online"
  | "connection:reconnect"
  | "page:hidden"
  | "page:resume"
  | "page:suspend"
  | "page:visible"
  | "plugin:error"
  | "plugin:registered"
  | "plugin:removed"
  | "session:active"
  | "session:idle"
  | "session:restored"
  | "session:started"
  | "session:stopped"
  | "tab:primary"
  | "tab:secondary"
  | "tab:message"
  | "window:blur"
  | "window:focus";

Public event names reserved by Browser Lifecycle Manager.

---

BrowserLifecycleEventListener

type BrowserLifecycleEventListener<TEventName> = (event: DeepReadonly<BrowserLifecycleEventMap[TEventName]>) => void;

Named event listener used by the public BrowserLifecycle object.

Type Parameters

Type Parameter
TEventName extends BrowserLifecycleEventName

Parameters

Parameter	Type
event	DeepReadonly<BrowserLifecycleEventMap[TEventName]>

Returns

void

---

BrowserLifecycleSubscriber

type BrowserLifecycleSubscriber = (event: DeepReadonly<BrowserLifecycleEventMap[BrowserLifecycleEventName]>, snapshot: DeepReadonly<BrowserLifecycleSnapshot>) => void;

Full event feed subscriber used for logging and adapter layers.

Parameters

Parameter	Type
event	DeepReadonly<BrowserLifecycleEventMap[BrowserLifecycleEventName]>
snapshot	DeepReadonly<BrowserLifecycleSnapshot>

Returns

void

---

ConditionHandler

type ConditionHandler = () => void;

Returns

void

---

Unsubscribe

type Unsubscribe = () => void;

Returns

void

---

ResilienceHandler

type ResilienceHandler<TEventName> = (event: DeepReadonly<BrowserLifecycleEventMap[TEventName]>) => void;

Type Parameters

Type Parameter
TEventName extends BrowserLifecycleEventName

Parameters

Parameter	Type
event	DeepReadonly<BrowserLifecycleEventMap[TEventName]>

Returns

void

---

EventMap

type EventMap = object;

Generic event map used by the typed event infrastructure.

---

EventName

type EventName<TEventMap> = Extract<keyof TEventMap, string>;

Valid event names for a given event map.

Type Parameters

Type Parameter
TEventMap extends EventMap

---

EventPayload

type EventPayload<TEventMap, TEventName> = TEventMap[TEventName];

Payload type associated with an event name.

Type Parameters

Type Parameter
TEventMap extends EventMap
TEventName extends EventName<TEventMap>

---

EventInternalMetadata

type EventInternalMetadata = Readonly<Record<string, unknown>>;

Internal metadata bag reserved for diagnostics and future instrumentation.

---

EventListener

type EventListener<TEventMap, TEventName> = (payload: EventPayload<TEventMap, TEventName>, metadata: EventDispatchMetadata<TEventName>) => void;

Listener signature used throughout the infrastructure.

Type Parameters

Type Parameter
TEventMap extends EventMap
TEventName extends EventName<TEventMap>

Parameters

Parameter	Type
payload	EventPayload<TEventMap, TEventName>
metadata	EventDispatchMetadata<TEventName>

Returns

void

---

EventListenerErrorHandler

type EventListenerErrorHandler<TEventMap> = (error: unknown, context: EventDispatchContext<TEventMap, EventName<TEventMap>>) => void;

Error handler used to isolate listener failures.

Type Parameters

Type Parameter
TEventMap extends EventMap

Parameters

Parameter	Type
error	unknown
context	EventDispatchContext<TEventMap, EventName<TEventMap>>

Returns

void

---

ActivityStatus

type ActivityStatus = "active" | "idle" | "unknown";

Activity facade types (Browser Intelligence — derive-only).

Spec: _constuction/browser-lifecycle/03-browser-intelligence/API_CONTRACTS.md

---

EngagementLevel

type EngagementLevel = "low" | "medium" | "high";

---

CreatePresenceApiOptions

type CreatePresenceApiOptions = ProjectPresenceOptions;

---

PresenceStatus

type PresenceStatus = "present" | "away" | "unknown";

Presence facade types (page-local availability — not multi-user presence).

Spec: _constuction/browser-lifecycle/03-browser-intelligence/API_CONTRACTS.md

---

PresenceReason

type PresenceReason = 
  | "hidden"
  | "blurred"
  | "offline"
  | "idle"
  | "visibility-unknown"
  | "attention-unknown"
  | "connectivity-unknown"
  | "activity-unknown";

---

PresenceLabel

type PresenceLabel = "ACTIVE" | "AWAY" | "UNKNOWN";

---

TimelineSnapshotFields

type TimelineSnapshotFields = Pick<BrowserLifecycleSnapshot, 
  | "activity"
  | "attention"
  | "connectivity"
  | "lifecycle"
  | "phase"
  | "tab"
| "visibility">;

Slim fields kept on each entry when snapshot capture is enabled.

---

BrowserLifecyclePluginPhase

type BrowserLifecyclePluginPhase = 
  | "registered"
  | "initialized"
  | "started"
  | "running"
  | "stopped"
  | "destroyed";

Lifecycle phases tracked for each registered plugin.

---

BrowserLifecyclePluginHookName

type BrowserLifecyclePluginHookName = "onDestroy" | "onEvent" | "onRegister" | "onStart" | "onStop";

Supported plugin hook names executed by the Session Core plugin runtime.

---

BrowserLifecyclePluginContext

type BrowserLifecyclePluginContext = BrowserLifecyclePluginRuntimeContext;

Read-only context passed to plugin lifecycle hooks.

---

BrowserLifecycleActivityEventName

type BrowserLifecycleActivityEventName = 
  | "focus"
  | "keydown"
  | "mousedown"
  | "mousemove"
  | "pointerdown"
  | "pointermove"
  | "touchmove"
  | "touchstart"
  | "visibilitychange";

Valid activity events for idle detection inputs.

---

BrowserLifecycleErrorCode

type BrowserLifecycleErrorCode = 
  | "configuration_error"
  | "initialization_error"
  | "lifecycle_error"
  | "module_registry_error"
  | "plugin_error"
  | "unsupported_feature_error";

Supported error codes for the public infrastructure surface.

Functions

createBrowserLifecycle()

function createBrowserLifecycle(config?: BrowserLifecycleConfig): BrowserLifecycle;

Creates a BrowserLifecycle runtime instance.

Parameters

Parameter	Type
config	BrowserLifecycleConfig

Returns

BrowserLifecycle

---

supportsVisibility()

function supportsVisibility(environment?: BrowserFeatureEnvironment): boolean;

Returns true when the environment supports the Page Visibility API.

Parameters

Parameter	Type
environment	BrowserFeatureEnvironment

Returns

boolean

---

supportsBroadcastChannel()

function supportsBroadcastChannel(environment?: BrowserFeatureEnvironment): boolean;

Returns true when the environment supports BroadcastChannel.

Parameters

Parameter	Type
environment	BrowserFeatureEnvironment

Returns

boolean

---

supportsPageLifecycle()

function supportsPageLifecycle(environment?: BrowserFeatureEnvironment): boolean;

Returns true when the environment supports the pagehide and pageshow lifecycle hooks.

Parameters

Parameter	Type
environment	BrowserFeatureEnvironment

Returns

boolean

---

supportsRequestIdleCallback()

function supportsRequestIdleCallback(environment?: BrowserFeatureEnvironment): boolean;

Returns true when the environment supports requestIdleCallback.

Parameters

Parameter	Type
environment	BrowserFeatureEnvironment

Returns

boolean

---

supportsIdle()

function supportsIdle(environment?: BrowserFeatureEnvironment): boolean;

Returns true when the environment supports idle activity observation.

Parameters

Parameter	Type
environment	BrowserFeatureEnvironment

Returns

boolean

---

supportsConnectivity()

function supportsConnectivity(environment?: BrowserFeatureEnvironment): boolean;

Returns true when the environment supports advisory connectivity observation.

Parameters

Parameter	Type
environment	BrowserFeatureEnvironment

Returns

boolean

---

supportsFocus()

function supportsFocus(environment?: BrowserFeatureEnvironment): boolean;

Returns true when the environment supports window focus observation.

Parameters

Parameter	Type
environment	BrowserFeatureEnvironment

Returns

boolean

---

supportsAbortController()

function supportsAbortController(environment?: BrowserFeatureEnvironment): boolean;

Returns true when the environment supports AbortController.

Parameters

Parameter	Type
environment	BrowserFeatureEnvironment

Returns

boolean

---

detectBrowserLifecycleCapabilities()

function detectBrowserLifecycleCapabilities(environment?: BrowserFeatureEnvironment): BrowserLifecycleCapabilities;

Detects the package capability surface without relying on browser sniffing.

Parameters

Parameter	Type
environment	BrowserFeatureEnvironment

Returns

BrowserLifecycleCapabilities

---

getDefaultBrowserLifecycleConfig()

function getDefaultBrowserLifecycleConfig(): ResolvedBrowserLifecycleConfig;

Returns an immutable copy of the default configuration.

Returns

ResolvedBrowserLifecycleConfig

---

validateBrowserLifecycleConfig()

function validateBrowserLifecycleConfig(input: unknown): asserts input is BrowserLifecycleConfig;

Validates a potential Browser Lifecycle configuration object.

Parameters

Parameter	Type
input	unknown

Returns

asserts input is BrowserLifecycleConfig

---

createBrowserLifecycleConfig()

function createBrowserLifecycleConfig(input?: BrowserLifecycleConfig): ResolvedBrowserLifecycleConfig;

Creates an immutable resolved configuration object.

Parameters

Parameter	Type
input	BrowserLifecycleConfig

Returns

ResolvedBrowserLifecycleConfig

---

mergeBrowserLifecycleConfig()

function mergeBrowserLifecycleConfig(base?: BrowserLifecycleConfig, override?: BrowserLifecycleConfig): ResolvedBrowserLifecycleConfig;

Creates an immutable configuration object by layering overrides on top of a base config.

Parameters

Parameter	Type
base	BrowserLifecycleConfig
override	BrowserLifecycleConfig

Returns

ResolvedBrowserLifecycleConfig

---

getPluginIds()

function getPluginIds(config: ResolvedBrowserLifecycleConfig): readonly string[];

Returns a readonly copy of plugin ids for diagnostics and tests.

Parameters

Parameter	Type
config	ResolvedBrowserLifecycleConfig

Returns

readonly string[]

---

createConditionsApi()

function createConditionsApi(lifecycle: Pick<BrowserLifecycle, "on">, options?: CreateConditionsApiOptions): ConditionsApi;

Creates a thin conditions DSL over public lifecycle events.

• No polling.
• Handler errors are isolated (do not tear down the session).
• Allocates nothing on createBrowserLifecycle() — only when this factory is called.

Parameters

Parameter	Type
lifecycle	Pick<BrowserLifecycle, "on">
options	CreateConditionsApiOptions

Returns

ConditionsApi

---

createResilienceApi()

function createResilienceApi(lifecycle: Pick<BrowserLifecycle, "on">, options?: CreateResilienceApiOptions): ResilienceApi;

Creates Resilience helpers for reconnect / wake / restore workflows.

• Wraps existing catalog events only (no browser APIs, no persistence).
• Handler errors are isolated.
• Allocates nothing on createBrowserLifecycle() — only when this factory is called.

Parameters

Parameter	Type
lifecycle	Pick<BrowserLifecycle, "on">
options	CreateResilienceApiOptions

Returns

ResilienceApi

---

createWaitApi()

function createWaitApi(lifecycle: Pick<BrowserLifecycle, "getSnapshot" | "on">): WaitApi;

Creates subscription-based wait helpers.

• No polling / setInterval condition checks.
• Resolves immediately when the snapshot already satisfies the condition.
• Allocates nothing on createBrowserLifecycle() — only when this factory is called.

Parameters

Parameter	Type
lifecycle	Pick<BrowserLifecycle, "getSnapshot" | "on">

Returns

WaitApi

---

createActivityApi()

function createActivityApi(lifecycle: Pick<BrowserLifecycle, "getSnapshot" | "on">, options?: CreateActivityApiOptions): ActivityApi;

Creates an Activity facade over an existing BrowserLifecycle instance.

• Does not attach browser DOM listeners.
• Does not enable idle observation (caller must set idleTimeout on the session).
• Allocates nothing on createBrowserLifecycle() — only when this factory is called.

Parameters

Parameter	Type
lifecycle	Pick<BrowserLifecycle, "getSnapshot" | "on">
options	CreateActivityApiOptions

Returns

ActivityApi

---

projectActivityView()

function projectActivityView(snapshot: Readonly<BrowserLifecycleSnapshot>, lastActiveAt?: number): ActivityView;

Pure projector: snapshot.activity → ActivityView. Never reads browser globals. O(1).

Parameters

Parameter	Type
snapshot	Readonly<BrowserLifecycleSnapshot>
lastActiveAt?	number

Returns

ActivityView

---

createSessionHealthApi()

function createSessionHealthApi(lifecycle: Pick<BrowserLifecycle, "getSnapshot">): SessionHealthApi;

Derive a single session-health view from the core snapshot. No subscriptions; no browser APIs.

Parameters

Parameter	Type
lifecycle	Pick<BrowserLifecycle, "getSnapshot">

Returns

SessionHealthApi

---

createMetricsApi()

function createMetricsApi(lifecycle: Pick<BrowserLifecycle, "getSnapshot" | "subscribe">, options?: CreateMetricsApiOptions): MetricsApi;

Creates an opt-in Metrics reducer over public lifecycle events.

• Live O(1) reducers — Timeline is not required (ADR A6).
• Does not attach browser DOM listeners.
• Allocates nothing on createBrowserLifecycle() — only when this factory is called.

Parameters

Parameter	Type
lifecycle	Pick<BrowserLifecycle, "getSnapshot" | "subscribe">
options	CreateMetricsApiOptions

Returns

MetricsApi

---

createSessionPredictApi()

function createSessionPredictApi(options: CreateSessionPredictApiOptions): SessionPredictApi;

Lightweight derived prediction from Metrics + current snapshot. Heuristic only — not ML.

Parameters

Parameter	Type
options	CreateSessionPredictApiOptions

Returns

SessionPredictApi

---

createPresenceApi()

function createPresenceApi(lifecycle: Pick<BrowserLifecycle, "getSnapshot">, options?: ProjectPresenceOptions): PresenceApi;

Creates a Presence facade over an existing BrowserLifecycle instance.

Page-local availability only (not multi-user presence).

• Does not attach browser DOM listeners.
• Pure snapshot projection on each read (zero subscriptions).
• Allocates nothing on createBrowserLifecycle() — only when this factory is called.

Parameters

Parameter	Type
lifecycle	Pick<BrowserLifecycle, "getSnapshot">
options	ProjectPresenceOptions

Returns

PresenceApi

---

projectPresenceView()

function projectPresenceView(snapshot: Readonly<BrowserLifecycleSnapshot>, options?: ProjectPresenceOptions): PresenceView;

Pure projector: snapshot → page-local PresenceView. Never reads browser globals. O(1).

Default policy: present iff visible ∧ focused ∧ online. Any required input unknown ⇒ unknown.

Parameters

Parameter	Type
snapshot	Readonly<BrowserLifecycleSnapshot>
options	ProjectPresenceOptions

Returns

PresenceView

---

buildMetricHighlights()

function buildMetricHighlights(metrics: Readonly<MetricsSnapshot>): readonly string[];

Pure formatter: MetricsSnapshot → human-readable highlights. Never touches browser APIs or Timeline.

Parameters

Parameter	Type
metrics	Readonly<MetricsSnapshot>

Returns

readonly string[]

---

emptyMetricsSnapshot()

function emptyMetricsSnapshot(): MetricsSnapshot;

Zeroed metrics snapshot for tests and empty reports.

Returns

MetricsSnapshot

---

createReportsApi()

function createReportsApi(options: CreateReportsApiOptions): ReportsApi;

Creates an on-demand Reports facade.

• Consumes Metrics (required).
• May cite Timeline ids (optional).
• Never talks to browser APIs.
• No subscriptions — generation happens only when sessionSummary() / report() is called.

Parameters

Parameter	Type
options	CreateReportsApiOptions

Returns

ReportsApi

---

createTimelineApi()

function createTimelineApi(lifecycle: Pick<BrowserLifecycle, "subscribe">, options: CreateTimelineApiOptions): TimelineApi;

Creates an opt-in Timeline recorder over a BrowserLifecycle instance.

• Does not attach browser DOM listeners.
• Subscribes to the public event feed only while the timeline exists.
• Allocates nothing on createBrowserLifecycle() — only when this factory is called.
• Bounded memory: maxEvents hard cap with drop-oldest overflow.

Parameters

Parameter	Type
lifecycle	Pick<BrowserLifecycle, "subscribe">
options	CreateTimelineApiOptions

Returns

TimelineApi

---

assert()

function assert(condition: unknown, message: string): asserts condition;

Asserts that a condition is truthy.

Parameters

Parameter	Type
condition	unknown
message	string

Returns

asserts condition

---

noop()

function noop(): void;

No-op helper for optional callback defaults.

Returns

void

---

isBrowser()

function isBrowser(): boolean;

Returns true when the current runtime looks like a browser environment.

Returns

boolean

---

isFunction()

function isFunction(value: unknown): value is (args: readonly unknown[]) => unknown;

Returns true when a value is callable.

Parameters

Parameter	Type
value	unknown

Returns

value is (args: readonly unknown[]) => unknown

---

isObject()

function isObject(value: unknown): value is PlainObject;

Returns true when a value is a non-null object.

Parameters

Parameter	Type
value	unknown

Returns

value is PlainObject

---

deepFreeze()

function deepFreeze<TValue>(value: TValue): DeepReadonly<TValue>;

Deeply freezes an object tree and returns a readonly view.

Type Parameters

Type Parameter
TValue

Parameters

Parameter	Type
value	TValue

Returns

DeepReadonly<TValue>

---

mergeObjects()

function mergeObjects<TBase, TOverride>(base: TBase, override: TOverride): TBase & TOverride;

Merges two plain objects recursively while replacing arrays and scalar values.

Type Parameters

Type Parameter
TBase extends PlainObject
TOverride extends PlainObject

Parameters

Parameter	Type
base	TBase
override	TOverride

Returns

TBase & TOverride