@syncular/client 0.15.36 → 0.15.37

package/README.md

@@ -54,14 +54,48 @@ The handle exposes the same logical API as `SyncClient` (subscribe /
 mutate / sync / query / conflicts / …), every method a promise. It
 acquires the Web Locks leader lock *before* spawning the worker — one
 core per origin. Wake-ups are handled inside the worker (`autoSync`,
-SPEC §8.4: the sync-needed signal is host-driven and the worker IS the
-host); the main thread gets `onSyncNeeded` / `onConflict` / `onSynced`
+SPEC §8.4); the supported page-level realtime supervisor owns reconnect and
+resume policy. The main thread gets `onSyncNeeded` / `onConflict` / `onSynced`
 events for rendering.
 
 **Ephemeral in-memory mode is EXPLICIT.** `openWasmDatabase()` returns an
 in-memory sqlite-wasm database for tests, demos and SSR. Nothing
 persists, on purpose, and that is the only main-thread mode.
 
+## Supported realtime lifecycle
+
+Register subscriptions, then install the cross-host supervisor:
+
+```ts
+import {
+  browserConnectivitySignal,
+  documentLifecycleSignal,
+  installRealtimeSupervisor,
+} from '@syncular/client';
+
+await handle.subscribe({ id: 'todos', table: 'todos', scopes });
+installRealtimeSupervisor(handle, {
+  connectivity: browserConnectivitySignal(),
+  lifecycle: documentLifecycleSignal(),
+  // Encrypted/locked apps also pass their active/preflight signal.
+  protection,
+});
+```
+
+It owns one connection attempt, retries initial failure and later socket loss
+with bounded exponential jitter, suspends while offline/background/protected,
+runs `syncUntilIdle()` before reporting `connected`, and cancels before
+`close()`. `realtimeSupervisorSnapshot()` and
+`subscribeRealtimeSupervisor()` expose only `phase`, `attempt`, and the bounded
+library delay for UI/diagnostics—never raw transport prose or identities.
+
+The lower-level `connectRealtime()` is idempotent while connected and
+single-flight while connecting; disconnect invalidates an in-flight result so
+it cannot install a stale socket. It remains available for custom host loops.
+HTTP rounds still work with no socket, but do not imply continuous convergence:
+a host trigger must actually run them. See the complete
+[realtime lifecycle guide](https://syncular.dev/concepts-realtime/).
+
 ## Multi-tab followers (TODO 3.2, REVISE B3)
 
 By default, every tab of the same origin shares ONE core:

package/dist/client.js

@@ -97,6 +97,8 @@ export class SyncClient {
     #conflicts = [];
     #rejections = [];
     #socket;
+    #realtimeConnectPromise;
+    #realtimeGeneration = 0;
     #pendingRound;
     #needsPull = false;
     #syncing = false;
@@ -315,8 +317,7 @@ export class SyncClient {
     async close() {
         this.#devtoolsUnregister?.();
         this.#devtoolsUnregister = undefined;
-        this.#socket?.close();
-        this.#socket = undefined;
+        this.disconnectRealtime();
         this.#abortPendingRound('client closed mid-round');
         await this.#lease?.release();
         this.#lease = undefined;
@@ -1939,31 +1940,59 @@ export class SyncClient {
     }
     // -- realtime (§8 client side) ----------------------------------------------
     connectRealtime() {
-        return this.#runProtectedAsync(() => this.#connectRealtime());
+        this.#requireActive();
+        if (this.#socket !== undefined)
+            return Promise.resolve();
+        if (this.#realtimeConnectPromise !== undefined) {
+            return this.#realtimeConnectPromise;
+        }
+        const generation = this.#realtimeGeneration;
+        const task = this.#runProtectedAsync(() => this.#connectRealtime(generation));
+        this.#realtimeConnectPromise = task;
+        void task.then(() => {
+            if (this.#realtimeConnectPromise === task) {
+                this.#realtimeConnectPromise = undefined;
+            }
+        }, () => {
+            if (this.#realtimeConnectPromise === task) {
+                this.#realtimeConnectPromise = undefined;
+            }
+        });
+        return task;
     }
-    async #connectRealtime() {
+    async #connectRealtime(generation) {
         const connector = this.#config.realtime;
         if (connector === undefined) {
             throw new ClientSyncError('sync.invalid_request', 'no realtime connector configured');
         }
+        let openedSocket;
         const socket = await connector({
             onText: (text) => this.#handleRealtimeText(text),
             onBinary: (bytes) => this.#routeRealtimeBinary(bytes),
             onClose: () => {
+                if (openedSocket === undefined || this.#socket !== openedSocket)
+                    return;
                 this.#socket = undefined;
                 this.#presence.clear(); // §8.6.1: presence is per-connection
                 this.#abortPendingRound('realtime socket closed mid-round (§8.7)');
                 this.#emitDiagnostics();
             },
         });
+        openedSocket = socket;
         if (this.#securityLifecycle === 'preflight') {
             socket.close();
             throw new ClientSyncError(SECURITY_PREFLIGHT_REQUIRED_CODE, 'realtime connected after the client entered security preflight');
         }
+        if (generation !== this.#realtimeGeneration || !this.#started) {
+            socket.close();
+            throw new ClientSyncError('client.realtime_cancelled', 'realtime connection was cancelled before activation');
+        }
         this.#socket = socket;
         this.#emitDiagnostics();
     }
     disconnectRealtime() {
+        this.#realtimeGeneration += 1;
+        this.#realtimeConnectPromise = undefined;
         this.#socket?.close();
         this.#socket = undefined;
         this.#presence.clear(); // §8.6.1: presence is per-connection

package/dist/index.d.ts

@@ -29,6 +29,7 @@ export * from './outbox.js';
 export * from './outcomes.js';
 export * from './query-guard.js';
 export * from './reactive-store.js';
+export * from './realtime-supervisor.js';
 export * from './schema.js';
 export * from './sql-tag.js';
 export * from './state.js';

package/dist/index.js

@@ -29,6 +29,7 @@ export * from './outbox.js';
 export * from './outcomes.js';
 export * from './query-guard.js';
 export * from './reactive-store.js';
+export * from './realtime-supervisor.js';
 export * from './schema.js';
 export * from './sql-tag.js';
 export * from './state.js';

package/dist/realtime-supervisor.d.ts

@@ -0,0 +1,78 @@
+import type { SecurityLifecycle } from './client.js';
+import type { ClientDiagnosticsConnectivity, ClientDiagnosticsListener, ClientDiagnosticsSnapshot } from './diagnostics.js';
+type CancelTimer = () => void;
+export interface RealtimeSupervisorClient {
+    connectRealtime(): Promise<void>;
+    disconnectRealtime(): void | Promise<void>;
+    syncUntilIdle(maxRounds?: number): unknown | Promise<unknown>;
+    diagnosticsSnapshot(): ClientDiagnosticsSnapshot | Promise<ClientDiagnosticsSnapshot>;
+    onDiagnostics(listener: ClientDiagnosticsListener): () => void;
+    close(): void | Promise<void>;
+}
+export interface RealtimeSupervisorSignal<State> {
+    current(): State;
+    subscribe(listener: (state: State) => void): () => void;
+}
+export type RealtimeSupervisorLifecycleState = 'active' | 'background' | 'unknown';
+export type RealtimeSupervisorProtectionState = SecurityLifecycle | 'unknown';
+type RealtimeSuspendedPhase = 'offline' | 'background' | 'protected';
+export type RealtimeSupervisorPhase = 'idle' | 'connecting' | 'connected' | 'retrying' | RealtimeSuspendedPhase | 'unsupported' | 'stopped';
+export interface RealtimeSupervisorSnapshot {
+    readonly phase: RealtimeSupervisorPhase;
+    /** One-based for retries; zero for the initial connection. */
+    readonly attempt: number;
+    /** Bounded host-policy delay, never server or transport prose. */
+    readonly retryDelayMs?: number;
+}
+export interface RealtimeSupervisorOptions {
+    /** Host online/offline evidence. Unknown remains connectable and observable. */
+    readonly connectivity?: RealtimeSupervisorSignal<ClientDiagnosticsConnectivity>;
+    /** Browser/native foreground evidence. Background always suspends the socket. */
+    readonly lifecycle?: RealtimeSupervisorSignal<RealtimeSupervisorLifecycleState>;
+    /** Publish preflight before draining keys so reconnect stops in the same turn. */
+    readonly protection?: RealtimeSupervisorSignal<RealtimeSupervisorProtectionState>;
+    /** Deterministic test/host timer seam. */
+    readonly schedule?: (callback: () => void, delayMs: number) => CancelTimer;
+    readonly random?: () => number;
+    readonly initialDelayMs?: number;
+    readonly maximumDelayMs?: number;
+}
+export interface RealtimeSupervisorEventTarget {
+    addEventListener(type: string, listener: () => void): void;
+    removeEventListener(type: string, listener: () => void): void;
+}
+export interface BrowserConnectivitySignalOptions {
+    readonly events?: RealtimeSupervisorEventTarget;
+    readonly network?: {
+        readonly onLine?: boolean;
+    };
+}
+export interface DocumentLifecycleSignalOptions {
+    readonly events?: RealtimeSupervisorEventTarget;
+    readonly document?: {
+        readonly visibilityState?: string;
+    };
+}
+/** Browser/Tauri-webview connectivity evidence without importing DOM types. */
+export declare function browserConnectivitySignal(options?: BrowserConnectivitySignalOptions): RealtimeSupervisorSignal<ClientDiagnosticsConnectivity>;
+/** Browser/Tauri-webview visibility evidence without importing DOM types. */
+export declare function documentLifecycleSignal(options?: DocumentLifecycleSignalOptions): RealtimeSupervisorSignal<RealtimeSupervisorLifecycleState>;
+/**
+ * Supported host policy for Syncular's explicit realtime transport. It owns
+ * exactly one connect attempt, runs an explicit catch-up round before claiming
+ * connected, retries transient loss with bounded exponential jitter, and
+ * suspends across offline, background, or protected-preflight state.
+ */
+export declare class RealtimeSupervisor {
+    #private;
+    constructor(client: RealtimeSupervisorClient, options?: RealtimeSupervisorOptions);
+    snapshot(): RealtimeSupervisorSnapshot;
+    subscribe(listener: () => void): () => void;
+    start(): void;
+    stop(): void;
+}
+/** Install one supervisor and make client disposal cancel it before close. */
+export declare function installRealtimeSupervisor<T extends RealtimeSupervisorClient>(client: T, options?: RealtimeSupervisorOptions): T;
+export declare function realtimeSupervisorSnapshot(client: object): RealtimeSupervisorSnapshot;
+export declare function subscribeRealtimeSupervisor(client: object, listener: () => void): () => void;
+export {};

package/dist/realtime-supervisor.js

@@ -0,0 +1,452 @@
+const REALTIME_SUPERVISOR_KEY = Symbol.for('syncular.realtime-supervisor.v1');
+const DEFAULT_INITIAL_DELAY_MS = 1_000;
+const DEFAULT_MAXIMUM_DELAY_MS = 30_000;
+const MAXIMUM_CONFIGURED_DELAY_MS = 300_000;
+const UNSUPPORTED_SNAPSHOT = Object.freeze({
+    phase: 'unsupported',
+    attempt: 0,
+});
+function attachment(client) {
+    const candidate = Reflect.get(client, REALTIME_SUPERVISOR_KEY);
+    return candidate?.version === 1 && candidate.supervisor
+        ? candidate
+        : undefined;
+}
+function scheduleTimer(callback, delayMs) {
+    const timer = globalThis.setTimeout(callback, delayMs);
+    return () => globalThis.clearTimeout(timer);
+}
+function boundedDelay(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new TypeError('realtime supervisor delays must be positive safe integers');
+    }
+    return Math.min(value, MAXIMUM_CONFIGURED_DELAY_MS);
+}
+function eventTarget(value) {
+    const candidate = value;
+    return typeof candidate?.addEventListener === 'function' &&
+        typeof candidate.removeEventListener === 'function'
+        ? candidate
+        : undefined;
+}
+/** Browser/Tauri-webview connectivity evidence without importing DOM types. */
+export function browserConnectivitySignal(options = {}) {
+    const root = globalThis;
+    const events = options.events ?? eventTarget(globalThis);
+    const network = options.network ?? root.navigator;
+    const current = () => {
+        if (network?.onLine === true)
+            return 'online';
+        if (network?.onLine === false)
+            return 'offline';
+        return 'unknown';
+    };
+    return {
+        current,
+        subscribe(listener) {
+            if (events === undefined)
+                return () => undefined;
+            const notify = () => listener(current());
+            events.addEventListener('online', notify);
+            events.addEventListener('offline', notify);
+            return () => {
+                events.removeEventListener('online', notify);
+                events.removeEventListener('offline', notify);
+            };
+        },
+    };
+}
+/** Browser/Tauri-webview visibility evidence without importing DOM types. */
+export function documentLifecycleSignal(options = {}) {
+    const root = globalThis;
+    const document = options.document ?? root.document;
+    const events = options.events ?? eventTarget(document);
+    const classify = () => {
+        if (document?.visibilityState === 'visible')
+            return 'active';
+        if (document?.visibilityState === 'hidden')
+            return 'background';
+        return 'unknown';
+    };
+    let state = classify();
+    return {
+        current: () => state,
+        subscribe(listener) {
+            if (events === undefined)
+                return () => undefined;
+            const visibility = () => {
+                state = classify();
+                listener(state);
+            };
+            const background = () => {
+                state = 'background';
+                listener(state);
+            };
+            const active = () => {
+                state = classify() === 'background' ? 'background' : 'active';
+                listener(state);
+            };
+            events.addEventListener('visibilitychange', visibility);
+            events.addEventListener('pagehide', background);
+            events.addEventListener('pageshow', active);
+            return () => {
+                events.removeEventListener('visibilitychange', visibility);
+                events.removeEventListener('pagehide', background);
+                events.removeEventListener('pageshow', active);
+            };
+        },
+    };
+}
+/**
+ * Supported host policy for Syncular's explicit realtime transport. It owns
+ * exactly one connect attempt, runs an explicit catch-up round before claiming
+ * connected, retries transient loss with bounded exponential jitter, and
+ * suspends across offline, background, or protected-preflight state.
+ */
+export class RealtimeSupervisor {
+    #client;
+    #connectivity;
+    #lifecycle;
+    #protection;
+    #scheduleTimer;
+    #random;
+    #initialDelayMs;
+    #maximumDelayMs;
+    #listeners = new Set();
+    #started = false;
+    #initialized = false;
+    #stopped = false;
+    #connected = false;
+    #transportConnected = false;
+    #connecting = false;
+    #realtimeSupported = true;
+    #diagnosticConnectivity = 'unknown';
+    #diagnosticSecurity = 'unknown';
+    #attempt = 0;
+    #generation = 0;
+    #snapshot = { phase: 'idle', attempt: 0 };
+    #cancelRetry;
+    #unsubscribeDiagnostics;
+    #unsubscribeConnectivity;
+    #unsubscribeLifecycle;
+    #unsubscribeProtection;
+    constructor(client, options = {}) {
+        this.#client = client;
+        this.#connectivity = options.connectivity;
+        this.#lifecycle = options.lifecycle;
+        this.#protection = options.protection;
+        this.#scheduleTimer = options.schedule ?? scheduleTimer;
+        this.#random = options.random ?? Math.random;
+        this.#initialDelayMs = boundedDelay(options.initialDelayMs, DEFAULT_INITIAL_DELAY_MS);
+        this.#maximumDelayMs = Math.max(this.#initialDelayMs, boundedDelay(options.maximumDelayMs, DEFAULT_MAXIMUM_DELAY_MS));
+    }
+    snapshot() {
+        return this.#snapshot;
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    start() {
+        if (this.#started || this.#stopped)
+            return;
+        this.#started = true;
+        this.#unsubscribeDiagnostics = this.#client.onDiagnostics((snapshot) => this.#observeDiagnostics(snapshot));
+        this.#unsubscribeConnectivity = this.#connectivity?.subscribe(() => this.#reconcileHostState());
+        this.#unsubscribeLifecycle = this.#lifecycle?.subscribe(() => this.#reconcileHostState());
+        this.#unsubscribeProtection = this.#protection?.subscribe(() => this.#reconcileHostState());
+        this.#reconcileHostState();
+        const generation = this.#generation;
+        void this.#initialize(generation);
+    }
+    stop() {
+        if (this.#stopped)
+            return;
+        this.#stopped = true;
+        this.#generation += 1;
+        const disconnect = this.#connected || this.#transportConnected || this.#connecting;
+        this.#connected = false;
+        this.#transportConnected = false;
+        this.#connecting = false;
+        this.#attempt = 0;
+        this.#clearRetry();
+        this.#unsubscribeDiagnostics?.();
+        this.#unsubscribeConnectivity?.();
+        this.#unsubscribeLifecycle?.();
+        this.#unsubscribeProtection?.();
+        this.#publish({ phase: 'stopped', attempt: 0 });
+        if (disconnect)
+            this.#disconnect();
+    }
+    async #initialize(generation) {
+        let snapshot;
+        try {
+            snapshot = await this.#client.diagnosticsSnapshot();
+        }
+        catch {
+            // Protected or temporarily unavailable diagnostics must not become a
+            // startup dependency. Explicit host gates and the connect result remain.
+        }
+        if (generation !== this.#generation || this.#stopped)
+            return;
+        this.#initialized = true;
+        if (snapshot !== undefined)
+            this.#observeDiagnostics(snapshot, true);
+        this.#reconcileHostState();
+    }
+    #hostBlock() {
+        const protection = this.#protection?.current();
+        if (this.#diagnosticSecurity === 'preflight' ||
+            protection === 'preflight' ||
+            (this.#protection !== undefined && protection !== 'active')) {
+            return 'protected';
+        }
+        if (this.#diagnosticConnectivity === 'offline' ||
+            this.#connectivity?.current() === 'offline') {
+            return 'offline';
+        }
+        if (this.#lifecycle?.current() === 'background')
+            return 'background';
+        return undefined;
+    }
+    #canConnect() {
+        return (this.#initialized &&
+            !this.#stopped &&
+            this.#realtimeSupported &&
+            !this.#hostBlock());
+    }
+    #publish(snapshot) {
+        if (this.#snapshot.phase === snapshot.phase &&
+            this.#snapshot.attempt === snapshot.attempt &&
+            this.#snapshot.retryDelayMs === snapshot.retryDelayMs) {
+            return;
+        }
+        this.#snapshot = Object.freeze(snapshot);
+        for (const listener of this.#listeners) {
+            try {
+                listener();
+            }
+            catch {
+                // Observers cannot alter transport ownership or retry policy.
+            }
+        }
+    }
+    #clearRetry() {
+        this.#cancelRetry?.();
+        this.#cancelRetry = undefined;
+    }
+    #schedule(delayMs) {
+        if (!this.#canConnect() ||
+            this.#connected ||
+            this.#connecting ||
+            this.#cancelRetry) {
+            return;
+        }
+        this.#publish(delayMs > 0
+            ? { phase: 'retrying', attempt: this.#attempt, retryDelayMs: delayMs }
+            : { phase: 'connecting', attempt: this.#attempt });
+        this.#cancelRetry = this.#scheduleTimer(() => {
+            this.#cancelRetry = undefined;
+            void this.#connect();
+        }, delayMs);
+    }
+    #retryDelay() {
+        const exponential = Math.min(this.#maximumDelayMs, this.#initialDelayMs * 2 ** this.#attempt);
+        const random = this.#random();
+        const boundedRandom = Number.isFinite(random)
+            ? Math.max(0, Math.min(1, random))
+            : 0;
+        const jitter = Math.floor(exponential * 0.25 * boundedRandom);
+        return Math.min(this.#maximumDelayMs, exponential + jitter);
+    }
+    #scheduleRetry() {
+        if (!this.#canConnect()) {
+            this.#reconcileHostState();
+            return;
+        }
+        const delay = this.#retryDelay();
+        this.#attempt = Math.min(32, this.#attempt + 1);
+        this.#schedule(delay);
+    }
+    async #connect() {
+        if (!this.#canConnect() || this.#connected || this.#connecting)
+            return;
+        this.#connecting = true;
+        this.#publish({ phase: 'connecting', attempt: this.#attempt });
+        const generation = this.#generation;
+        let failed = false;
+        try {
+            await this.#client.connectRealtime();
+            this.#transportConnected = true;
+            if (generation !== this.#generation || !this.#canConnect()) {
+                this.#disconnect();
+                return;
+            }
+            await this.#catchUpConnectedTransport(generation);
+        }
+        catch {
+            failed = true;
+            this.#connected = false;
+            this.#transportConnected = false;
+            this.#disconnect();
+        }
+        finally {
+            this.#connecting = false;
+        }
+        if (failed && generation === this.#generation)
+            this.#scheduleRetry();
+    }
+    async #catchUpConnectedTransport(generation) {
+        await this.#client.syncUntilIdle();
+        if (generation !== this.#generation ||
+            !this.#canConnect() ||
+            !this.#transportConnected) {
+            this.#disconnect();
+            return;
+        }
+        this.#connected = true;
+        this.#attempt = 0;
+        this.#publish({ phase: 'connected', attempt: 0 });
+    }
+    async #adoptConnectedTransport() {
+        if (!this.#canConnect() || this.#connecting || !this.#transportConnected) {
+            return;
+        }
+        this.#connecting = true;
+        this.#clearRetry();
+        this.#publish({ phase: 'connecting', attempt: this.#attempt });
+        const generation = this.#generation;
+        let failed = false;
+        try {
+            await this.#catchUpConnectedTransport(generation);
+        }
+        catch {
+            failed = true;
+            this.#connected = false;
+            this.#transportConnected = false;
+            this.#disconnect();
+        }
+        finally {
+            this.#connecting = false;
+        }
+        if (failed && generation === this.#generation)
+            this.#scheduleRetry();
+    }
+    #observeDiagnostics(snapshot, initial = false) {
+        if (this.#stopped)
+            return;
+        this.#diagnosticConnectivity = snapshot.host.connectivity;
+        this.#diagnosticSecurity = snapshot.securityLifecycle;
+        if (snapshot.host.realtime === 'unsupported') {
+            const disconnect = this.#connected || this.#transportConnected || this.#connecting;
+            this.#realtimeSupported = false;
+            this.#generation += 1;
+            this.#connected = false;
+            this.#transportConnected = false;
+            this.#attempt = 0;
+            this.#clearRetry();
+            this.#publish({ phase: 'unsupported', attempt: 0 });
+            if (disconnect)
+                this.#disconnect();
+            return;
+        }
+        if (!this.#realtimeSupported)
+            return;
+        this.#realtimeSupported = true;
+        const block = this.#hostBlock();
+        if (block) {
+            this.#suspend(block);
+            return;
+        }
+        if (snapshot.host.realtime === 'connected') {
+            this.#transportConnected = true;
+            if (this.#connecting)
+                return;
+            this.#connected = false;
+            void this.#adoptConnectedTransport();
+            return;
+        }
+        if (snapshot.host.realtime === 'disconnected') {
+            this.#transportConnected = false;
+            this.#connected = false;
+            if (this.#connecting)
+                return;
+            if (this.#initialized && !initial)
+                this.#scheduleRetry();
+            return;
+        }
+        this.#reconcileHostState();
+    }
+    #reconcileHostState() {
+        if (this.#stopped)
+            return;
+        const block = this.#hostBlock();
+        if (block) {
+            this.#suspend(block);
+            return;
+        }
+        if (!this.#initialized) {
+            this.#publish({ phase: 'idle', attempt: 0 });
+            return;
+        }
+        if (!this.#realtimeSupported) {
+            this.#publish({ phase: 'unsupported', attempt: 0 });
+            return;
+        }
+        if (this.#connected) {
+            this.#publish({ phase: 'connected', attempt: 0 });
+            return;
+        }
+        this.#schedule(0);
+    }
+    #suspend(phase) {
+        const disconnect = this.#connected || this.#transportConnected || this.#connecting;
+        const hadScheduledWork = this.#cancelRetry !== undefined;
+        const phaseChanged = this.#snapshot.phase !== phase;
+        if (!disconnect && !hadScheduledWork && !phaseChanged)
+            return;
+        this.#generation += 1;
+        this.#connected = false;
+        this.#transportConnected = false;
+        this.#connecting = false;
+        this.#attempt = 0;
+        this.#clearRetry();
+        this.#publish({ phase, attempt: 0 });
+        if (disconnect)
+            this.#disconnect();
+    }
+    #disconnect() {
+        void Promise.resolve(this.#client.disconnectRealtime()).catch(() => undefined);
+    }
+}
+/** Install one supervisor and make client disposal cancel it before close. */
+export function installRealtimeSupervisor(client, options) {
+    if (attachment(client))
+        return client;
+    const supervisor = new RealtimeSupervisor(client, options);
+    Object.defineProperty(client, REALTIME_SUPERVISOR_KEY, {
+        configurable: false,
+        enumerable: false,
+        writable: false,
+        value: { version: 1, supervisor },
+    });
+    const close = client.close.bind(client);
+    Object.defineProperty(client, 'close', {
+        configurable: true,
+        writable: true,
+        value: async () => {
+            supervisor.stop();
+            await close();
+        },
+    });
+    supervisor.start();
+    return client;
+}
+export function realtimeSupervisorSnapshot(client) {
+    return attachment(client)?.supervisor.snapshot() ?? UNSUPPORTED_SNAPSHOT;
+}
+export function subscribeRealtimeSupervisor(client, listener) {
+    return (attachment(client)?.supervisor.subscribe(listener) ?? (() => undefined));
+}