@myko/core 4.2.0-canary.3

package/dist/client.js

@@ -0,0 +1,1316 @@
+/**
+ * Pure TypeScript WebSocket client for Myko servers
+ *
+ * Maintains connections to all known servers for instant failover.
+ * When the current server disconnects, instantly switches to another open connection.
+ */
+import { GetPeerServers, MykoEvent, } from './generated';
+import { Packr, Unpackr } from 'msgpackr';
+import { bufferCount, bufferTime, catchError, combineLatest, filter, finalize, firstValueFrom, interval, map, merge, Observable, of, ReplaySubject, scan, shareReplay, Subject, switchMap, } from 'rxjs';
+import { v4 as uuid } from 'uuid';
+// msgpackr defaults can emit extension types for values that don't exist in JSON (notably
+// `undefined`). Our Rust server deserializes msgpack into `serde_json::Value`, so ensure we
+// encode `undefined` as nil/null instead of an extension.
+const packr = new Packr({ encodeUndefinedAsNil: true });
+const unpackr = new Unpackr({});
+const EVENT_BATCH = 'ws:m:event-batch';
+function stableStringify(value) {
+    const seen = new WeakSet();
+    try {
+        return JSON.stringify(value, (_key, raw) => {
+            if (typeof raw === 'bigint')
+                return `__bigint:${raw.toString()}`;
+            if (!raw || typeof raw !== 'object')
+                return raw;
+            if (seen.has(raw))
+                return '__circular__';
+            seen.add(raw);
+            if (Array.isArray(raw))
+                return raw;
+            const sorted = {};
+            for (const key of Object.keys(raw).sort()) {
+                sorted[key] = raw[key];
+            }
+            return sorted;
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/** Connection status */
+export var ConnectionStatus;
+(function (ConnectionStatus) {
+    ConnectionStatus["Connected"] = "Connected";
+    ConnectionStatus["Disconnected"] = "Disconnected";
+    ConnectionStatus["Connecting"] = "Connecting";
+})(ConnectionStatus || (ConnectionStatus = {}));
+/** Wire protocol for encoding messages */
+export var MykoProtocol;
+(function (MykoProtocol) {
+    MykoProtocol["JSON"] = "JSON";
+    MykoProtocol["MSGPACK"] = "MSGPACK";
+})(MykoProtocol || (MykoProtocol = {}));
+function queryCacheKey(query, options) {
+    const queryPayload = stableStringify(query.query) ?? '__unstable_query__';
+    const windowPayload = stableStringify(options?.window ?? null) ?? '__unstable_window__';
+    return `query:${query.queryId}:${queryPayload}:${windowPayload}`;
+}
+function viewCacheKey(view, options) {
+    const viewPayload = stableStringify(view.view) ?? '__unstable_view__';
+    const windowPayload = stableStringify(options?.window ?? null) ?? '__unstable_window__';
+    return `view:${view.viewId}:${viewPayload}:${windowPayload}`;
+}
+function reportCacheKey(report) {
+    const payload = stableStringify(report.report) ?? '__unstable_report__';
+    return `report:${report.reportId}:${payload}`;
+}
+/**
+ * Reactive WebSocket client for Myko servers with automatic failover.
+ */
+export class MykoClient {
+    // Socket management
+    sockets = new Map();
+    reconnectTimers = new Map();
+    endpointSockets = new Map();
+    // Main server: the socket used for outbound sends.
+    // Other open sockets are warm standbys for failover.
+    currentServer = null;
+    shouldReconnect = true;
+    // Message routing
+    queryResponses = new Subject();
+    reportResponses = new Subject();
+    commandResponses = new Subject();
+    commandErrors = new Subject();
+    queryErrors = new Subject();
+    reportErrors = new Subject();
+    pingResponses = new Subject();
+    commandIncoming = new Subject();
+    // State observables
+    connectionStatusSubject = new ReplaySubject(1);
+    currentServerSubject = new ReplaySubject(1);
+    // Subscription tracking
+    activeQueries = new Map();
+    activeViews = new Map();
+    activeReports = new Map();
+    activeQueryNames = new Map();
+    activeViewNames = new Map();
+    activeReportNames = new Map();
+    sharedQueries = new Map();
+    sharedViews = new Map();
+    sharedQueryDiffs = new Map();
+    sharedViewDiffs = new Map();
+    sharedReports = new Map();
+    subscriptionStartMs = new Map();
+    firstResponseLogged = new Set();
+    messageQueue = [];
+    pendingEventBatch = [];
+    eventBatchFlushScheduled = false;
+    eventBatchMaxSize = 256;
+    connectionLogLevelThreshold = MykoClient.resolveDefaultConnectionLogLevel();
+    // Stats
+    downMsgCounter = new Subject();
+    upMsgCounter = new Subject();
+    // Auth & peer discovery
+    userToken = null;
+    peerDiscoveryEnabled = true;
+    peerDiscoverySubscription = null;
+    useSecureWebSocket = false;
+    // Protocol defaults to JSON for maximum compatibility (no msgpack extensions, bigint issues, etc).
+    protocol = MykoProtocol.JSON;
+    constructor() {
+        this.setConnectionStatus(ConnectionStatus.Disconnected, 'init');
+        this.setCurrentServer(null, 'init');
+    }
+    /** Set connection log verbosity at runtime. */
+    setConnectionLogLevel(level) {
+        this.connectionLogLevelThreshold = level;
+    }
+    /** Set the wire protocol (JSON or MSGPACK). Default is MSGPACK. */
+    setProtocol(protocol) {
+        this.protocol = protocol;
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Connection Management
+    // ─────────────────────────────────────────────────────────────────────────────
+    /** Set a single server address, clearing any existing connections */
+    setAddress(address) {
+        this.shouldReconnect = true; // Re-enable autoreconnect when setting new address
+        this.closeAllSockets();
+        if (address) {
+            this.useSecureWebSocket = address.startsWith('wss://');
+            this.createSocket(address, true);
+        }
+    }
+    /** Set multiple server addresses, clearing any existing connections */
+    setAddresses(addresses) {
+        this.shouldReconnect = true; // Re-enable autoreconnect when setting new addresses
+        this.closeAllSockets();
+        for (const addr of addresses) {
+            this.createSocket(addr, true);
+        }
+    }
+    /** Add additional servers (connects immediately) */
+    addServers(addresses, reconnectOnClose = true) {
+        this.shouldReconnect = true; // Re-enable autoreconnect when adding servers
+        for (const addr of addresses) {
+            if (!this.hasConnectionTo(addr)) {
+                this.createSocket(addr, reconnectOnClose);
+            }
+        }
+    }
+    /** Disconnect from all servers */
+    disconnect() {
+        this.shouldReconnect = false;
+        this.stopPeerDiscovery();
+        this.closeAllSockets();
+    }
+    /** Get the currently active server address */
+    getCurrentServer() {
+        return this.currentServer;
+    }
+    /** Get the current main server address used for outbound sends */
+    getMainServer() {
+        return this.currentServer;
+    }
+    /** Get all server addresses */
+    getServers() {
+        return Array.from(this.sockets.values()).map((m) => m.address);
+    }
+    /** Get addresses of all open connections */
+    getOpenServers() {
+        return Array.from(this.sockets.values())
+            .filter((m) => m.ws.readyState === WebSocket.OPEN)
+            .map((m) => m.address);
+    }
+    /** Observable of current server changes */
+    get currentServer$() {
+        return this.currentServerSubject.asObservable();
+    }
+    /** Observable of main server changes */
+    get mainServer$() {
+        return this.currentServer$;
+    }
+    /** Get current connection status */
+    getConnectionStatus() {
+        if (this.currentServer)
+            return ConnectionStatus.Connected;
+        for (const m of this.sockets.values()) {
+            if (m.ws.readyState === WebSocket.CONNECTING)
+                return ConnectionStatus.Connecting;
+        }
+        return ConnectionStatus.Disconnected;
+    }
+    /** Observable of connection status changes */
+    get connectionStatus$() {
+        return this.connectionStatusSubject.asObservable();
+    }
+    /** Observable of incoming command messages (ws:m:command) from the server */
+    get commandIncoming$() {
+        return this.commandIncoming.asObservable();
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Peer Discovery
+    // ─────────────────────────────────────────────────────────────────────────────
+    /** Enable automatic peer discovery via GetPeerServers query */
+    enablePeerDiscovery(enabled, secure = false) {
+        this.peerDiscoveryEnabled = enabled;
+        this.useSecureWebSocket = secure;
+        if (!enabled && this.peerDiscoverySubscription) {
+            this.peerDiscoverySubscription.unsubscribe();
+            this.peerDiscoverySubscription = null;
+        }
+        else if (enabled && this.hasOpenConnection()) {
+            this.startPeerDiscovery();
+        }
+    }
+    startPeerDiscovery() {
+        this.peerDiscoverySubscription?.unsubscribe();
+        this.logConnection('peer_discovery_started', {
+            secure: this.useSecureWebSocket,
+            via: 'query:GetPeerServers',
+        });
+        this.peerDiscoverySubscription = this.watchQuery(new GetPeerServers({})).subscribe((servers) => {
+            const addresses = servers.map((s) => this.useSecureWebSocket
+                ? `wss://${s.address}/myko`
+                : `ws://${s.address}:${s.port}/myko`);
+            this.logConnection('peer_discovery_update', {
+                peers: servers.length,
+                addresses,
+            });
+            // Discovered peers are ephemeral: if they disconnect, wait for discovery
+            // to advertise them again rather than actively redialing.
+            if (addresses.length > 0)
+                this.addServers(addresses, false);
+        });
+    }
+    stopPeerDiscovery() {
+        this.peerDiscoverySubscription?.unsubscribe();
+        this.peerDiscoverySubscription = null;
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Auth & Stats
+    // ─────────────────────────────────────────────────────────────────────────────
+    /** Set authentication token for commands */
+    setToken(token) {
+        this.userToken = token;
+    }
+    /** Observable of all errors */
+    get errors$() {
+        const toError = (e) => ({ event: e.event, tx: e.data.tx, message: e.data.message });
+        return merge(this.queryErrors.pipe(map(toError)), this.commandErrors.pipe(map(toError)), this.reportErrors.pipe(map(toError)));
+    }
+    /** Observable of successful command completions (tx id) */
+    get successes$() {
+        return this.commandResponses.pipe(map((r) => r.data.tx));
+    }
+    /** Measure round-trip latency */
+    async ping() {
+        const id = uuid();
+        const nowMs = Date.now();
+        // IMPORTANT: the Rust server expects `timestamp: i64`.
+        // - JSON cannot encode bigint, so use number in JSON mode.
+        // - msgpack can encode bigint as int64, so use bigint in MSGPACK mode.
+        const timestamp = this.protocol === MykoProtocol.MSGPACK ? BigInt(nowMs) : nowMs;
+        this.send({
+            event: MykoEvent.Ping,
+            data: { id, timestamp },
+        });
+        return firstValueFrom(this.pingResponses.pipe(filter((p) => p.data.id === id), map((p) => Date.now() - Number(p.data.timestamp))));
+    }
+    /** Get real-time client statistics (emits every second) */
+    stats() {
+        const pingLatency = interval(1000).pipe(switchMap(() => this.ping()), catchError(() => of(0)));
+        const mpsDown = this.downMsgCounter.pipe(bufferTime(100), bufferCount(10), map((b) => b.flat().length));
+        const mpsUp = this.upMsgCounter.pipe(bufferTime(100), bufferCount(10), map((b) => b.flat().length));
+        return combineLatest([pingLatency, mpsDown, mpsUp]).pipe(map(([ping, down, up]) => ({ ping, mpsDown: down, mpsUp: up })));
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Queries & Reports
+    // ─────────────────────────────────────────────────────────────────────────────
+    /** Start a query subscription, returns [tx, responses$] */
+    startQuery(query, options) {
+        if (!query.queryId || !query.queryItemType || !query.query) {
+            const details = {
+                ctor: query.constructor?.name ?? 'unknown',
+                keys: Object.keys(query ?? {}),
+                queryId: query.queryId,
+                queryItemType: query.queryItemType,
+            };
+            this.logConnection('query_shape_invalid', details);
+            throw new Error(`Invalid query shape for ${details.ctor}: expected { queryId, queryItemType, query }`);
+        }
+        const tx = uuid();
+        const window = options?.window ?? undefined;
+        const queryName = query.constructor?.name ?? query.queryId;
+        const wrappedQuery = {
+            query: { ...query.query, tx, createdAt: new Date().toISOString() },
+            queryId: query.queryId,
+            queryItemType: query.queryItemType,
+            ...(window ? { window } : {}),
+        };
+        this.activeQueries.set(tx, wrappedQuery);
+        this.activeQueryNames.set(tx, queryName);
+        this.subscriptionStartMs.set(tx, this.nowMs());
+        this.firstResponseLogged.delete(tx);
+        this.logConnection('query_subscribe', {
+            tx,
+            queryId: wrappedQuery.queryId,
+            queryItemType: wrappedQuery.queryItemType,
+            queryName,
+            window: window ?? null,
+            activeQueries: this.activeQueries.size,
+        });
+        this.send({ event: MykoEvent.Query, data: wrappedQuery });
+        const responses$ = new Observable((subscriber) => {
+            const responseSub = this.queryResponses
+                .pipe(filter((r) => r.data.tx === tx))
+                .subscribe({
+                next: (response) => subscriber.next(response),
+                error: (error) => subscriber.error(error),
+            });
+            const errorSub = this.queryErrors
+                .pipe(filter((error) => error.data.tx === tx))
+                .subscribe((error) => {
+                subscriber.error(new Error(error.data.message));
+            });
+            return () => {
+                responseSub.unsubscribe();
+                errorSub.unsubscribe();
+            };
+        }).pipe(finalize(() => {
+            this.logConnection('query_cancel', {
+                tx,
+                queryId: wrappedQuery.queryId,
+                queryItemType: wrappedQuery.queryItemType,
+                queryName,
+                activeQueriesBefore: this.activeQueries.size,
+            });
+            this.activeQueries.delete(tx);
+            this.activeQueryNames.delete(tx);
+            this.subscriptionStartMs.delete(tx);
+            this.firstResponseLogged.delete(tx);
+            this.send({ event: MykoEvent.QueryCancel, data: { tx } });
+        }));
+        return [tx, responses$];
+    }
+    /** Update server-side window for an active query subscription */
+    setQueryWindow(tx, window) {
+        const active = this.activeQueries.get(tx);
+        if (!active)
+            return;
+        const updated = {
+            ...active,
+            ...(window ? { window } : {}),
+        };
+        if (!window) {
+            delete updated.window;
+        }
+        this.activeQueries.set(tx, updated);
+        this.logConnection('query_window_set', {
+            tx,
+            queryId: active.queryId,
+            queryItemType: active.queryItemType,
+            queryName: this.activeQueryNames.get(tx) ?? active.queryId,
+            window,
+        });
+        this.send({ event: MykoEvent.QueryWindow, data: { tx, window } });
+    }
+    /** Start a view subscription, returns [tx, responses$] */
+    startView(view, options) {
+        if (!view.viewId || !view.viewItemType || !view.view) {
+            const details = {
+                ctor: view.constructor?.name ?? 'unknown',
+                keys: Object.keys(view ?? {}),
+                viewId: view.viewId,
+                viewItemType: view.viewItemType,
+            };
+            this.logConnection('view_shape_invalid', details);
+            throw new Error(`Invalid view shape for ${details.ctor}: expected { viewId, viewItemType, view }`);
+        }
+        const tx = uuid();
+        const window = options?.window ?? undefined;
+        const viewName = view.constructor?.name ?? view.viewId;
+        const wrappedView = {
+            view: { ...view.view, tx, createdAt: new Date().toISOString() },
+            viewId: view.viewId,
+            viewItemType: view.viewItemType,
+            ...(window ? { window } : {}),
+        };
+        this.activeViews.set(tx, wrappedView);
+        this.activeViewNames.set(tx, viewName);
+        this.subscriptionStartMs.set(tx, this.nowMs());
+        this.firstResponseLogged.delete(tx);
+        this.logConnection('view_subscribe', {
+            tx,
+            viewId: wrappedView.viewId,
+            viewItemType: wrappedView.viewItemType,
+            viewName,
+            window: wrappedView.window ?? null,
+            activeViews: this.activeViews.size,
+        });
+        this.send({ event: MykoEvent.View, data: wrappedView });
+        const responses$ = new Observable((subscriber) => {
+            const responseSub = this.queryResponses
+                .pipe(filter((r) => r.data.tx === tx))
+                .subscribe({
+                next: (response) => subscriber.next(response),
+                error: (error) => subscriber.error(error),
+            });
+            const errorSub = this.queryErrors
+                .pipe(filter((error) => error.data.tx === tx))
+                .subscribe((error) => {
+                subscriber.error(new Error(error.data.message));
+            });
+            return () => {
+                responseSub.unsubscribe();
+                errorSub.unsubscribe();
+            };
+        }).pipe(finalize(() => {
+            this.logConnection('view_cancel', {
+                tx,
+                viewId: wrappedView.viewId,
+                viewName,
+                activeViewsBefore: this.activeViews.size,
+            });
+            this.activeViews.delete(tx);
+            this.activeViewNames.delete(tx);
+            this.subscriptionStartMs.delete(tx);
+            this.firstResponseLogged.delete(tx);
+            this.send({ event: MykoEvent.ViewCancel, data: { tx } });
+        }));
+        return [tx, responses$];
+    }
+    /** Update server-side window for an active view subscription */
+    setViewWindow(tx, window) {
+        const active = this.activeViews.get(tx);
+        if (!active)
+            return;
+        const updated = {
+            ...active,
+            ...(window ? { window } : {}),
+        };
+        if (!window) {
+            delete updated.window;
+        }
+        this.activeViews.set(tx, updated);
+        this.logConnection('view_window_set', {
+            tx,
+            viewId: active.viewId,
+            viewName: this.activeViewNames.get(tx) ?? active.viewId,
+            window,
+        });
+        this.send({ event: MykoEvent.ViewWindow, data: { tx, window } });
+    }
+    /** Watch a query and receive live updates with automatic deduplication */
+    watchQuery(query, options) {
+        const cacheKey = queryCacheKey(query, options);
+        const existing = this.sharedQueries.get(cacheKey);
+        if (existing)
+            return existing;
+        const [, responses$] = this.startQuery(query, options);
+        const shared$ = responses$.pipe(scan((acc, update) => {
+            if (BigInt(update.data.sequence) === 0n)
+                acc.clear();
+            for (const id of update.data.deletes)
+                acc.delete(id);
+            for (const wrapped of update.data.upserts) {
+                const item = wrapped.item;
+                if (item?.id)
+                    acc.set(item.id, wrapped);
+            }
+            return acc;
+        }, new Map()), map((items) => [...items.values()].map((w) => w.item)), finalize(() => {
+            this.sharedQueries.delete(cacheKey);
+        }), shareReplay({ bufferSize: 1, refCount: true }), 
+        // Defensive copy: shareReplay replays the same array reference to all
+        // subscribers, so a mutation (e.g. .shift()) by one subscriber would
+        // corrupt the shared value for others. Cloning per-subscriber prevents this.
+        map((x) => (Array.isArray(x) ? x.slice() : x)));
+        this.sharedQueries.set(cacheKey, shared$);
+        return shared$;
+    }
+    /** Watch a view and receive live updates with automatic deduplication */
+    watchView(view, options) {
+        const cacheKey = viewCacheKey(view, options);
+        const existing = this.sharedViews.get(cacheKey);
+        if (existing)
+            return existing;
+        const [, responses$] = this.startView(view, options);
+        const shared$ = responses$.pipe(scan((acc, update) => {
+            if (BigInt(update.data.sequence) === 0n)
+                acc.clear();
+            for (const id of update.data.deletes)
+                acc.delete(id);
+            for (const wrapped of update.data.upserts) {
+                const item = wrapped.item;
+                if (item?.id)
+                    acc.set(item.id, wrapped);
+            }
+            return acc;
+        }, new Map()), map((items) => [...items.values()].map((w) => w.item)), finalize(() => {
+            this.sharedViews.delete(cacheKey);
+        }), shareReplay({ bufferSize: 1, refCount: true }), map((x) => (Array.isArray(x) ? x.slice() : x)));
+        this.sharedViews.set(cacheKey, shared$);
+        return shared$;
+    }
+    /** Watch a query and receive raw diff events */
+    watchQueryDiff(query, options) {
+        const cacheKey = queryCacheKey(query, options);
+        const existing = this.sharedQueryDiffs.get(cacheKey);
+        if (existing)
+            return existing;
+        const [, responses$] = this.startQuery(query, options);
+        const shared$ = responses$.pipe(map((r) => ({
+            sequence: BigInt(r.data.sequence),
+            deletes: r.data.deletes.slice(),
+            upserts: r.data.upserts.map((w) => w.item),
+        })), finalize(() => {
+            this.sharedQueryDiffs.delete(cacheKey);
+        }), shareReplay({ bufferSize: 1, refCount: true }), map((diff) => ({
+            sequence: diff.sequence,
+            deletes: diff.deletes.slice(),
+            upserts: diff.upserts.slice(),
+        })));
+        this.sharedQueryDiffs.set(cacheKey, shared$);
+        return shared$;
+    }
+    /** Watch a view and receive raw diff events */
+    watchViewDiff(view, options) {
+        const cacheKey = viewCacheKey(view, options);
+        const existing = this.sharedViewDiffs.get(cacheKey);
+        if (existing)
+            return existing;
+        const [, responses$] = this.startView(view, options);
+        const shared$ = responses$.pipe(map((r) => ({
+            sequence: BigInt(r.data.sequence),
+            deletes: r.data.deletes.slice(),
+            upserts: r.data.upserts.map((w) => w.item),
+        })), finalize(() => {
+            this.sharedViewDiffs.delete(cacheKey);
+        }), shareReplay({ bufferSize: 1, refCount: true }), map((diff) => ({
+            sequence: diff.sequence,
+            deletes: diff.deletes.slice(),
+            upserts: diff.upserts.slice(),
+        })));
+        this.sharedViewDiffs.set(cacheKey, shared$);
+        return shared$;
+    }
+    /**
+     * Start a live query with a mutable server-side window.
+     * Use `setWindow` to scroll without re-subscribing.
+     */
+    watchQueryWindowed(query, options) {
+        const [tx, responses$] = this.startQuery(query, options);
+        const sharedResponses$ = responses$.pipe(shareReplay({ bufferSize: 1, refCount: true }));
+        const results$ = sharedResponses$.pipe(scan((state, update) => {
+            const data = update.data;
+            if (BigInt(update.data.sequence) === 0n) {
+                state.cache.clear();
+                state.visibleIds = [];
+            }
+            for (const id of update.data.deletes)
+                state.cache.delete(id);
+            for (const wrapped of update.data.upserts) {
+                const item = wrapped.item;
+                if (item?.id)
+                    state.cache.set(item.id, wrapped);
+            }
+            const order = data.changes?.find((change) => change.kind === 'windowOrder');
+            if (order) {
+                state.visibleIds = order.ids.slice();
+            }
+            else {
+                // Fallback when window-order diffs are unavailable: derive visible ids
+                // from current cache contents (in insertion order).
+                state.visibleIds = [...state.cache.keys()];
+            }
+            return state;
+        }, {
+            cache: new Map(),
+            visibleIds: [],
+        }), map((state) => state.visibleIds
+            .map((id) => state.cache.get(id)?.item)
+            .filter((item) => item !== undefined)), map((x) => x.slice()));
+        const windowInfo$ = sharedResponses$.pipe(map((update) => {
+            const data = update.data;
+            const order = data.changes?.find((change) => change.kind === 'windowOrder');
+            const orderTotalCount = order?.totalCount ?? order?.total_count;
+            return {
+                totalCount: typeof data.totalCount === 'number'
+                    ? data.totalCount
+                    : typeof data.total_count === 'number'
+                        ? data.total_count
+                        : typeof orderTotalCount === 'number'
+                            ? orderTotalCount
+                            : null,
+                window: data.window ?? order?.window ?? null,
+            };
+        }), shareReplay({ bufferSize: 1, refCount: true }));
+        return {
+            tx,
+            results$,
+            windowInfo$,
+            setWindow: (window) => this.setQueryWindow(tx, window),
+        };
+    }
+    /** Start a live view with a mutable server-side window. */
+    watchViewWindowed(view, options) {
+        const [tx, responses$] = this.startView(view, options);
+        const sharedResponses$ = responses$.pipe(shareReplay({ bufferSize: 1, refCount: true }));
+        const results$ = sharedResponses$.pipe(scan((state, update) => {
+            const data = update.data;
+            if (BigInt(update.data.sequence) === 0n) {
+                state.cache.clear();
+                state.visibleIds = [];
+            }
+            for (const id of update.data.deletes)
+                state.cache.delete(id);
+            for (const wrapped of update.data.upserts) {
+                const item = wrapped.item;
+                if (item?.id)
+                    state.cache.set(item.id, wrapped);
+            }
+            const order = data.changes?.find((change) => change.kind === 'windowOrder');
+            if (order) {
+                state.visibleIds = order.ids.slice();
+            }
+            else {
+                state.visibleIds = [...state.cache.keys()];
+            }
+            return state;
+        }, {
+            cache: new Map(),
+            visibleIds: [],
+        }), map((state) => state.visibleIds
+            .map((id) => state.cache.get(id)?.item)
+            .filter((item) => item !== undefined)), map((x) => x.slice()));
+        const windowInfo$ = sharedResponses$.pipe(map((update) => {
+            const data = update.data;
+            const order = data.changes?.find((change) => change.kind === 'windowOrder');
+            const orderTotalCount = order?.totalCount ?? order?.total_count;
+            return {
+                totalCount: typeof data.totalCount === 'number'
+                    ? data.totalCount
+                    : typeof data.total_count === 'number'
+                        ? data.total_count
+                        : typeof orderTotalCount === 'number'
+                            ? orderTotalCount
+                            : null,
+                window: data.window ?? order?.window ?? null,
+            };
+        }), shareReplay({ bufferSize: 1, refCount: true }));
+        return {
+            tx,
+            results$,
+            windowInfo$,
+            setWindow: (window) => this.setViewWindow(tx, window),
+        };
+    }
+    /** Watch a report with automatic deduplication */
+    watchReport(report) {
+        const cacheKey = reportCacheKey(report);
+        const existing = this.sharedReports.get(cacheKey);
+        if (existing)
+            return existing;
+        const tx = uuid();
+        const reportName = report.constructor?.name ??
+            report.reportId;
+        const wrappedReport = {
+            report: { ...report.report, tx },
+            reportId: report.reportId,
+        };
+        this.activeReports.set(tx, wrappedReport);
+        this.activeReportNames.set(tx, reportName);
+        this.logConnection('report_subscribe', {
+            tx,
+            reportId: wrappedReport.reportId,
+            reportName,
+            report: report.report,
+            activeReports: this.activeReports.size,
+        });
+        this.send({ event: MykoEvent.Report, data: wrappedReport });
+        const shared$ = this.reportResponses.pipe(filter((r) => r.data.tx === tx), map((r) => {
+            this.logConnection('report_response', {
+                tx,
+                reportId: wrappedReport.reportId,
+                reportName,
+            });
+            return r;
+        }), map((r) => r.data.response), finalize(() => {
+            this.logConnection('report_cancel', {
+                tx,
+                reportId: wrappedReport.reportId,
+                reportName,
+                activeReportsBefore: this.activeReports.size,
+            });
+            this.sharedReports.delete(cacheKey);
+            this.activeReports.delete(tx);
+            this.activeReportNames.delete(tx);
+            this.send({ event: MykoEvent.ReportCancel, data: { tx } });
+        }), shareReplay({ bufferSize: 1, refCount: true }), 
+        // Defensive copy: prevent one subscriber's mutations from affecting others
+        map((x) => {
+            if (Array.isArray(x))
+                return x.slice();
+            if (x && typeof x === 'object') {
+                return { ...x };
+            }
+            return x;
+        }));
+        this.sharedReports.set(cacheKey, shared$);
+        return shared$;
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Commands & Events
+    // ─────────────────────────────────────────────────────────────────────────────
+    /** Send an event to the server */
+    sendEvent(event) {
+        // Pulses are latency-sensitive; bypass batching and send immediately.
+        if (event.itemType === 'Pulse') {
+            this.flushPendingEventBatch();
+            this.sendNow({ event: MykoEvent.Event, data: event });
+            return;
+        }
+        this.sendEventBatch([event]);
+    }
+    /** Send a batch of events to the server */
+    sendEventBatch(events) {
+        if (events.length === 0)
+            return;
+        const buffered = [];
+        const immediatePulses = [];
+        for (const event of events) {
+            if (event.itemType === 'Pulse') {
+                immediatePulses.push(event);
+            }
+            else {
+                buffered.push(event);
+            }
+        }
+        if (buffered.length > 0) {
+            this.pendingEventBatch.push(...buffered);
+        }
+        if (immediatePulses.length > 0) {
+            this.flushPendingEventBatch();
+            for (const pulse of immediatePulses) {
+                this.sendNow({ event: MykoEvent.Event, data: pulse });
+            }
+            return;
+        }
+        if (this.pendingEventBatch.length >= this.eventBatchMaxSize) {
+            this.flushPendingEventBatch();
+            return;
+        }
+        this.scheduleEventBatchFlush();
+    }
+    /** Send a command and wait for response */
+    sendCommand(command) {
+        const tx = uuid();
+        const wrappedCommand = {
+            command: {
+                ...command.command,
+                tx,
+                createdAt: new Date().toISOString(),
+                ...(this.userToken && { userToken: this.userToken }),
+            },
+            commandId: command.commandId,
+        };
+        return new Promise((resolve, reject) => {
+            const responseSub = this.commandResponses
+                .pipe(filter((r) => r.data.tx === tx))
+                .subscribe((r) => {
+                cleanup();
+                resolve(r.data.response);
+            });
+            const errorSub = this.commandErrors
+                .pipe(filter((r) => r.data.tx === tx))
+                .subscribe((r) => {
+                cleanup();
+                reject(new Error(r.data.message));
+            });
+            const cleanup = () => {
+                responseSub.unsubscribe();
+                errorSub.unsubscribe();
+            };
+            this.send({ event: MykoEvent.Command, data: wrappedCommand });
+        });
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Private: Socket Management
+    // ─────────────────────────────────────────────────────────────────────────────
+    getFirstOpenSocket() {
+        for (const m of this.sockets.values()) {
+            if (m.ws.readyState === WebSocket.OPEN)
+                return m;
+        }
+        return null;
+    }
+    hasOpenConnection() {
+        return this.getFirstOpenSocket() !== null;
+    }
+    hasConnectionTo(address) {
+        return this.endpointSockets.has(this.endpointKey(address));
+    }
+    parseAddress(address) {
+        try {
+            const url = new URL(address);
+            const port = url.port
+                ? parseInt(url.port, 10)
+                : url.protocol === 'wss:'
+                    ? 443
+                    : 80;
+            return { host: url.hostname.toLowerCase(), port };
+        }
+        catch {
+            return null;
+        }
+    }
+    endpointKey(address) {
+        const parsed = this.parseAddress(address);
+        if (!parsed)
+            return address;
+        const host = this.hostsEquivalent(parsed.host, 'localhost')
+            ? 'localhost'
+            : parsed.host;
+        return `${host}:${parsed.port}`;
+    }
+    hostsEquivalent(a, b) {
+        if (a === b)
+            return true;
+        const loopback = new Set(['localhost', '127.0.0.1', '::1']);
+        return loopback.has(a) && loopback.has(b);
+    }
+    closeAllSockets() {
+        for (const timer of this.reconnectTimers.values())
+            clearTimeout(timer);
+        this.reconnectTimers.clear();
+        this.endpointSockets.clear();
+        for (const m of this.sockets.values()) {
+            m.ws.onclose = null;
+            m.ws.onerror = null;
+            m.ws.onopen = null;
+            m.ws.onmessage = null;
+            m.ws.close();
+        }
+        this.sockets.clear();
+        this.setCurrentServer(null, 'all sockets closed');
+        this.setConnectionStatus(ConnectionStatus.Disconnected, 'all sockets closed');
+    }
+    createSocket(address, reconnectOnClose = true) {
+        const endpointKey = this.endpointKey(address);
+        if (this.endpointSockets.has(endpointKey))
+            return;
+        this.endpointSockets.set(endpointKey, address);
+        const reconnectTimer = this.reconnectTimers.get(endpointKey);
+        if (reconnectTimer) {
+            clearTimeout(reconnectTimer);
+            this.reconnectTimers.delete(endpointKey);
+        }
+        this.logConnection('socket_connecting', {
+            address,
+            openServers: this.getOpenServers(),
+            knownServers: this.getServers(),
+        });
+        const ws = new WebSocket(address);
+        ws.binaryType = 'arraybuffer'; // Receive binary messages as ArrayBuffer for msgpack
+        const managed = {
+            ws,
+            address,
+            endpointKey,
+            reconnectOnClose,
+        };
+        this.sockets.set(address, managed);
+        if (this.sockets.size === 1) {
+            this.setConnectionStatus(ConnectionStatus.Connecting, `connecting to ${address}`);
+        }
+        ws.onopen = () => {
+            if (this.sockets.get(address) !== managed) {
+                ws.close();
+                return;
+            }
+            if (!this.currentServer) {
+                this.setCurrentServer(address, 'socket open');
+                this.setConnectionStatus(ConnectionStatus.Connected, `connected to ${address}`);
+                this.flushQueue();
+                this.resendSubscriptions();
+                if (this.peerDiscoveryEnabled)
+                    this.startPeerDiscovery();
+            }
+        };
+        ws.onclose = () => {
+            if (this.sockets.get(address) !== managed)
+                return;
+            this.sockets.delete(address);
+            this.endpointSockets.delete(endpointKey);
+            if (this.currentServer === address) {
+                const next = this.getFirstOpenSocket();
+                if (next) {
+                    this.setCurrentServer(next.address, `failover from ${address} to ${next.address}`);
+                    this.setConnectionStatus(ConnectionStatus.Connected, `main failover to ${next.address}`);
+                    this.resendSubscriptions();
+                    return; // Peer discovery will re-add this server when it's back
+                }
+                this.setCurrentServer(null, `disconnected from ${address}`);
+                this.setConnectionStatus(ConnectionStatus.Disconnected, `no open servers after ${address} closed`);
+            }
+            // Only retry explicitly configured sockets when completely disconnected.
+            // Discovered peers are expected to reappear via peer discovery.
+            if (managed.reconnectOnClose &&
+                this.shouldReconnect &&
+                !this.hasOpenConnection()) {
+                this.scheduleReconnect(address, endpointKey);
+            }
+        };
+        ws.onerror = () => { };
+        ws.onmessage = (event) => {
+            if (this.sockets.get(address) !== managed)
+                return;
+            this.onMessage(event.data);
+        };
+    }
+    scheduleReconnect(address, endpointKey) {
+        if (this.reconnectTimers.has(endpointKey))
+            return;
+        this.logConnection('reconnect_scheduled', { address, delayMs: 1000 });
+        const timer = setTimeout(() => {
+            this.reconnectTimers.delete(endpointKey);
+            if (this.shouldReconnect &&
+                !this.hasOpenConnection() &&
+                !this.endpointSockets.has(endpointKey)) {
+                this.logConnection('reconnect_attempt', { address });
+                this.createSocket(address);
+            }
+        }, 1000);
+        this.reconnectTimers.set(endpointKey, timer);
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Private: Message Handling
+    // ─────────────────────────────────────────────────────────────────────────────
+    onMessage(data) {
+        this.downMsgCounter.next();
+        try {
+            let message;
+            if (typeof data === 'string') {
+                // JSON text message
+                message = JSON.parse(data);
+            }
+            else if (data instanceof ArrayBuffer) {
+                // Binary msgpack message
+                message = unpackr.unpack(new Uint8Array(data));
+            }
+            else if (data instanceof Blob) {
+                // Handle Blob asynchronously - convert to ArrayBuffer first
+                data.arrayBuffer().then((buffer) => {
+                    const decoded = unpackr.unpack(new Uint8Array(buffer));
+                    this.routeMessage(decoded);
+                });
+                return;
+            }
+            else {
+                return;
+            }
+            this.routeMessage(message);
+        }
+        catch {
+            // Ignore parse errors
+        }
+    }
+    routeMessage(message) {
+        switch (message.event) {
+            case MykoEvent.QueryResponse:
+                this.maybeLogFirstResponseTiming('query', message.data.tx, {
+                    queryId: this.activeQueries.get(message.data.tx)?.queryId,
+                    queryName: this.activeQueryNames.get(message.data.tx) ??
+                        this.activeQueries.get(message.data.tx)?.queryId ??
+                        'unknown',
+                    sequence: message.data.sequence,
+                    upserts: message.data.upserts.length,
+                    deletes: message.data.deletes.length,
+                });
+                this.logConnection('query_response', {
+                    tx: message.data.tx,
+                    queryId: this.activeQueries.get(message.data.tx)?.queryId,
+                    queryItemType: this.activeQueries.get(message.data.tx)?.queryItemType,
+                    queryName: this.activeQueryNames.get(message.data.tx) ??
+                        this.activeQueries.get(message.data.tx)?.queryId ??
+                        'unknown',
+                    sequence: message.data.sequence,
+                    upserts: message.data.upserts.length,
+                    deletes: message.data.deletes.length,
+                    changes: message.data.changes?.length ?? 0,
+                    totalCount: message.data.totalCount ??
+                        message.data.total_count ??
+                        null,
+                    window: message.data.window ?? null,
+                });
+                const queryPublishStarted = this.nowMs();
+                this.queryResponses.next(message);
+                this.logConnection('query_publish_ms', {
+                    tx: message.data.tx,
+                    sequence: message.data.sequence,
+                    publishMs: Number((this.nowMs() - queryPublishStarted).toFixed(2)),
+                });
+                break;
+            case MykoEvent.ViewResponse:
+                // ViewResponse and QueryResponse share the same payload shape.
+                const viewMessage = message;
+                this.maybeLogFirstResponseTiming('view', viewMessage.data.tx, {
+                    viewId: this.activeViews.get(viewMessage.data.tx)?.viewId,
+                    viewName: this.activeViewNames.get(viewMessage.data.tx) ??
+                        this.activeViews.get(viewMessage.data.tx)?.viewId ??
+                        'unknown',
+                    sequence: viewMessage.data.sequence,
+                    upserts: viewMessage.data.upserts.length,
+                    deletes: viewMessage.data.deletes.length,
+                });
+                this.logConnection('view_response', {
+                    tx: viewMessage.data.tx,
+                    sequence: viewMessage.data.sequence,
+                    upserts: viewMessage.data.upserts.length,
+                    deletes: viewMessage.data.deletes.length,
+                    changes: viewMessage.data.changes?.length ?? 0,
+                    totalCount: viewMessage.data
+                        .totalCount ??
+                        viewMessage.data.total_count ??
+                        null,
+                    window: viewMessage.data.window ?? null,
+                });
+                const viewPublishStarted = this.nowMs();
+                this.queryResponses.next(viewMessage);
+                this.logConnection('view_publish_ms', {
+                    tx: viewMessage.data.tx,
+                    sequence: viewMessage.data.sequence,
+                    publishMs: Number((this.nowMs() - viewPublishStarted).toFixed(2)),
+                });
+                break;
+            case MykoEvent.ReportResponse:
+                this.reportResponses.next(message);
+                break;
+            case MykoEvent.CommandResponse:
+                this.commandResponses.next(message);
+                break;
+            case MykoEvent.CommandError:
+                this.commandErrors.next(message);
+                break;
+            case MykoEvent.QueryError:
+                this.queryErrors.next(message);
+                this.logConnection('query_error', {
+                    tx: message.data.tx,
+                    message: message.data.message,
+                    queryId: this.activeQueries.get(message.data.tx)?.queryId,
+                    queryItemType: this.activeQueries.get(message.data.tx)?.queryItemType,
+                    queryName: this.activeQueryNames.get(message.data.tx) ??
+                        this.activeQueries.get(message.data.tx)?.queryId ??
+                        'unknown',
+                });
+                break;
+            case MykoEvent.ViewError:
+                this.queryErrors.next(message);
+                this.logConnection('view_error', {
+                    tx: message.data.tx,
+                    message: message.data.message,
+                    viewId: this.activeViews.get(message.data.tx)?.viewId,
+                    viewItemType: this.activeViews.get(message.data.tx)?.viewItemType,
+                    viewName: this.activeViewNames.get(message.data.tx) ??
+                        this.activeViews.get(message.data.tx)?.viewId ??
+                        'unknown',
+                });
+                break;
+            case MykoEvent.ReportError:
+                this.reportErrors.next(message);
+                this.logConnection('report_error', {
+                    tx: message.data.tx,
+                    message: message.data.message,
+                    reportId: this.activeReports.get(message.data.tx)?.reportId,
+                    reportName: this.activeReportNames.get(message.data.tx) ??
+                        this.activeReports.get(message.data.tx)?.reportId ??
+                        'unknown',
+                });
+                break;
+            case MykoEvent.Ping:
+                this.pingResponses.next(message);
+                break;
+            case MykoEvent.Command:
+                this.commandIncoming.next(message);
+                break;
+        }
+    }
+    scheduleEventBatchFlush() {
+        if (this.eventBatchFlushScheduled)
+            return;
+        this.eventBatchFlushScheduled = true;
+        queueMicrotask(() => {
+            this.eventBatchFlushScheduled = false;
+            this.flushPendingEventBatch();
+        });
+    }
+    flushPendingEventBatch() {
+        if (this.pendingEventBatch.length === 0)
+            return;
+        while (this.pendingEventBatch.length > 0) {
+            const batch = this.pendingEventBatch.splice(0, this.eventBatchMaxSize);
+            this.sendNow({ event: EVENT_BATCH, data: batch });
+        }
+    }
+    send(message) {
+        if (message.event !== EVENT_BATCH) {
+            this.flushPendingEventBatch();
+        }
+        this.sendNow(message);
+    }
+    messageTx(message) {
+        const data = message.data;
+        return typeof data?.tx === 'string' ? data.tx : null;
+    }
+    sendNow(message) {
+        const event = message.event;
+        const tx = this.messageTx(message);
+        if (this.currentServer) {
+            const managed = this.sockets.get(this.currentServer);
+            if (managed?.ws.readyState === WebSocket.OPEN) {
+                const encoded = this.protocol === MykoProtocol.MSGPACK
+                    ? new Uint8Array(packr.pack(message))
+                    : JSON.stringify(message);
+                managed.ws.send(encoded);
+                this.upMsgCounter.next();
+                return;
+            }
+        }
+        this.messageQueue.push(message);
+        this.logConnection('ws_enqueue', {
+            event,
+            tx,
+            queueDepth: this.messageQueue.length,
+            currentServer: this.currentServer,
+        });
+    }
+    flushQueue() {
+        const queue = this.messageQueue;
+        this.messageQueue = [];
+        this.logConnection('ws_flush_queue', {
+            queuedMessages: queue.length,
+            currentServer: this.currentServer,
+        });
+        for (const msg of queue)
+            this.send(msg);
+    }
+    withReconnectSequenceReset(query) {
+        const queryPayload = query.query;
+        if (queryPayload &&
+            typeof queryPayload === 'object' &&
+            !Array.isArray(queryPayload)) {
+            return {
+                ...query,
+                query: {
+                    ...queryPayload,
+                    seq: 0,
+                },
+            };
+        }
+        return query;
+    }
+    resendSubscriptions() {
+        for (const q of this.activeQueries.values()) {
+            this.send({
+                event: MykoEvent.Query,
+                data: this.withReconnectSequenceReset(q),
+            });
+        }
+        for (const v of this.activeViews.values()) {
+            this.send({ event: MykoEvent.View, data: v });
+        }
+        for (const r of this.activeReports.values()) {
+            this.send({ event: MykoEvent.Report, data: r });
+        }
+    }
+    setConnectionStatus(status, reason) {
+        this.connectionStatusSubject.next(status);
+        this.logConnection('status', {
+            status,
+            reason,
+            currentServer: this.currentServer,
+            openServers: this.getOpenServers(),
+        });
+    }
+    setCurrentServer(server, reason) {
+        this.currentServer = server;
+        this.currentServerSubject.next(server);
+        this.logConnection('current_server', { server, reason });
+    }
+    nowMs() {
+        if (typeof performance !== 'undefined' && typeof performance.now === 'function') {
+            return performance.now();
+        }
+        return Date.now();
+    }
+    maybeLogFirstResponseTiming(kind, tx, details) {
+        if (this.firstResponseLogged.has(tx))
+            return;
+        const startedAt = this.subscriptionStartMs.get(tx);
+        if (startedAt === undefined)
+            return;
+        const elapsedMs = this.nowMs() - startedAt;
+        this.firstResponseLogged.add(tx);
+        this.logConnection(`${kind}_first_response_timing`, {
+            tx,
+            subscribeToFirstResponseMs: Number(elapsedMs.toFixed(2)),
+            ...details,
+        });
+    }
+    connectionLogLevel(event) {
+        // Main lifecycle state transitions remain visible at info.
+        const infoEvents = new Set(['status', 'current_server']);
+        if (infoEvents.has(event))
+            return 'info';
+        // Subscription setup and first-response timing are debug-level diagnostics.
+        const debugEvents = new Set([
+            'socket_connecting',
+            'peer_discovery_started',
+            'peer_discovery_update',
+            'query_subscribe',
+            'view_subscribe',
+            'report_subscribe',
+            'query_cancel',
+            'view_cancel',
+            'report_cancel',
+            'query_first_response_timing',
+            'view_first_response_timing',
+            'reconnect_scheduled',
+            'reconnect_attempt',
+            'query_shape_invalid',
+        ]);
+        if (debugEvents.has(event))
+            return 'debug';
+        // Follow-up response churn and transport internals are verbose-level.
+        const verboseEvents = new Set([
+            'ws_enqueue',
+            'ws_flush_queue',
+            'query_response',
+            'view_response',
+            'report_response',
+            'query_publish_ms',
+            'view_publish_ms',
+        ]);
+        if (verboseEvents.has(event))
+            return 'verbose';
+        if (event.endsWith('_error'))
+            return 'error';
+        return 'debug';
+    }
+    static resolveDefaultConnectionLogLevel() {
+        const readGlobal = () => {
+            const globalObj = globalThis;
+            const value = globalObj.MYKO_CLIENT_LOG_LEVEL;
+            return typeof value === 'string' ? value : undefined;
+        };
+        const readProcessEnv = () => {
+            const processLike = globalThis.process;
+            return processLike?.env?.MYKO_CLIENT_LOG_LEVEL;
+        };
+        const value = (readGlobal() ?? readProcessEnv() ?? '').toLowerCase();
+        switch (value) {
+            case 'silent':
+            case 'error':
+            case 'warn':
+            case 'info':
+            case 'debug':
+            case 'verbose':
+                return value;
+            default:
+                return 'warn';
+        }
+    }
+    shouldLogConnection(level) {
+        const priority = {
+            silent: 0,
+            error: 1,
+            warn: 2,
+            info: 3,
+            debug: 4,
+            verbose: 5,
+        };
+        return priority[level] <= priority[this.connectionLogLevelThreshold];
+    }
+    logConnection(event, details) {
+        const level = this.connectionLogLevel(event);
+        if (!this.shouldLogConnection(level))
+            return;
+        const maybeVerbose = console.verbose;
+        const logger = level === 'info'
+            ? console.info
+            : level === 'warn'
+                ? console.warn
+                : level === 'error'
+                    ? console.error
+                    : level === 'verbose' || level === 'debug'
+                        ? maybeVerbose ?? console.debug ?? console.log
+                        : console.log;
+        const levelPrefix = level === 'verbose' ? '[verbose] ' : '';
+        logger(`${levelPrefix}[MykoClient] ${event}`, {
+            tsIso: new Date().toISOString(),
+            tsMs: Date.now(),
+            ...details,
+        });
+    }
+}