@rebasepro/client 0.9.0 → 0.9.1-canary.09aaf62

package/src/websocket.ts

@@ -12,6 +12,7 @@ import {
     BranchInfo,
     RebaseApiError
 } from "@rebasepro/types";
+import { buildCompositeId, COMPOSITE_ID_SEPARATOR, type PrimaryKeyInfo } from "@rebasepro/common";
 import { rebaseReviver } from "./reviver";
 
 
@@ -29,7 +30,14 @@ function extractMessageError(message: WebSocketMessage): { errorMessage: string;
     const errorCode = typeof errPayload === "object"
         ? errPayload.code
         : payload?.code;
-    return { errorMessage,
+    // Callers treat this as a string (`.toLowerCase()` in isAuthError). A frame
+    // carrying a non-string here would throw inside the message handler, where
+    // the surrounding try/catch would swallow it — and a subscription error that
+    // never reaches its listener is a view stuck loading forever.
+    const safeMessage = typeof errorMessage === "string"
+        ? errorMessage
+        : (errorMessage == null ? "Unknown error" : JSON.stringify(errorMessage));
+    return { errorMessage: safeMessage,
 errorCode };
 }
 
@@ -50,7 +58,7 @@ export interface RebaseWebSocketConfig {
  * @internal Not a stable app-facing API. `createRebaseClient()` constructs and
  * manages this internally (exposed as `client.ws`, typed by the minimal
  * `RebaseWebSocket` contract in `@rebasepro/types`). It is re-exported from the
- * package root only because the `@rebasepro/client-postgresql` driver
+ * package root only because the `@rebasepro/client-postgres` driver
  * instantiates it directly; its surface may change without a major bump.
  */
 export class RebaseWebSocketClient {
@@ -64,6 +72,26 @@ export class RebaseWebSocketClient {
 
     private listeners = new Map<string, Set<(...args: unknown[]) => void>>();
 
+    /** Channel-name → handlers, for broadcast and presence frames. */
+    private channelHandlers = new Map<string, Set<(message: Record<string, unknown>) => void>>();
+
+    /** Subscribe to broadcast/presence frames for one channel. */
+    public onChannelMessage(channel: string, handler: (message: Record<string, unknown>) => void): () => void {
+        if (!this.channelHandlers.has(channel)) this.channelHandlers.set(channel, new Set());
+        this.channelHandlers.get(channel)!.add(handler);
+        return () => {
+            const handlers = this.channelHandlers.get(channel);
+            if (!handlers) return;
+            handlers.delete(handler);
+            if (handlers.size === 0) this.channelHandlers.delete(channel);
+        };
+    }
+
+    /** Notified after the socket comes back, so channels can re-join. */
+    public onReconnect(handler: () => void): () => void {
+        return this.on("reconnect", handler);
+    }
+
     public on(event: "connect" | "disconnect" | "reconnect" | "error", cb: (...args: unknown[]) => void) {
         if (!this.listeners.has(event)) {
             this.listeners.set(event, new Set());
@@ -89,6 +117,25 @@ export class RebaseWebSocketClient {
         latestData?: Record<string, unknown>[]; // Cache the latest flat rows
         lastUpdated?: number; // Timestamp for cache invalidation
         isInitialDataReceived?: boolean; // Track if we got initial data
+        /**
+         * A `subscribe_collection` frame is on the wire and its initial payload
+         * has not arrived yet. Without this, a subscription whose subscribe
+         * failed is indistinguishable from one still loading, and every later
+         * listener attaches to it and waits forever.
+         */
+        subscribeInFlight?: boolean;
+        /**
+         * Watchdog for the above. `subscribe_collection` expects no response
+         * envelope, so it is not covered by `pendingRequests`' timeout — a lost
+         * initial payload would otherwise hang the subscription indefinitely.
+         */
+        subscribeTimeout?: ReturnType<typeof setTimeout>;
+        /**
+         * The key columns of this collection, as told by the server on a patch.
+         * Rows are columns only, and the SDK holds no collection config, so
+         * without this there is nothing to derive an address from.
+         */
+        pks?: PrimaryKeyInfo[];
     }>();
 
     private singleSubscriptions = new Map<string, {
@@ -101,6 +148,9 @@ export class RebaseWebSocketClient {
         latestData?: Record<string, unknown> | null; // Cache the latest flat row
         lastUpdated?: number; // Timestamp for cache invalidation
         isInitialDataReceived?: boolean; // Track if we got initial data
+        /** See the collection subscription counterparts. */
+        subscribeInFlight?: boolean;
+        subscribeTimeout?: ReturnType<typeof setTimeout>;
     }>();
 
     // Maps to quickly find subscription by backend subscription ID
@@ -118,6 +168,7 @@ export class RebaseWebSocketClient {
     private isConnected = false;
     private messageQueue: Record<string, unknown>[] = [];
     private requestTimeoutMs = 30000;
+    private subscriptionTimeoutMs = 30000;
     private reconnectTimeout: ReturnType<typeof setTimeout> | null = null;
 
     private isAuthenticated = false;
@@ -263,6 +314,10 @@ export class RebaseWebSocketClient {
                 if (wasReconnect) {
                     this.resubscribeAll();
                 }
+
+                // Subscribes requested while offline have just gone out; they
+                // could not be watchdogged at request time.
+                this.armPendingSubscribeWatchdogs();
             };
 
             this.ws!.onmessage = (event) => {
@@ -279,6 +334,9 @@ export class RebaseWebSocketClient {
                 this.isConnected = false;
                 this.isAuthenticated = false;
                 this.authPromise = null;
+                // The reconnect path re-subscribes everything; a watchdog firing
+                // in the meantime would tear down healthy subscriptions.
+                this.suspendSubscribeWatchdogs();
                 this.emit("disconnect");
 
                 // Re-queue pending requests so the UI doesn't hang indefinitely or crash
@@ -319,6 +377,11 @@ export class RebaseWebSocketClient {
     private attemptReconnect() {
         if (this.reconnectAttempts >= this.maxReconnectAttempts) {
             console.error("Max reconnection attempts reached");
+            // Nothing will re-subscribe now, so stop every subscription that
+            // never loaded from spinning forever.
+            this.failAllPendingSubscriptions(
+                new RebaseApiError("Connection lost", { code: "CONNECTION_LOST" })
+            );
             return;
         }
 
@@ -399,29 +462,32 @@ export class RebaseWebSocketClient {
                 backendKeyMap.delete(oldBackendId);
                 backendKeyMap.set(newBackendId, subscriptionKey);
 
-                this.sendMessage({
-                    type: messageType,
-                    payload: {
-                        ...subscription.props,
-                        subscriptionId: newBackendId
-                    }
-                }).catch(error => {
-                    console.error(`[WS] Failed to re-subscribe ${idPrefix} after auth refresh:`, subscriptionKey, error);
-                    subscription.callbacks.forEach(callback => {
-                        if (callback.onError) callback.onError(error);
-                    });
-                });
+                // Route through the helpers so the retry is watchdogged too.
+                if (messageType === "subscribe_collection") {
+                    this.sendCollectionSubscribe(subscriptionKey);
+                } else {
+                    this.sendEntitySubscribe(subscriptionKey);
+                }
+                return;
+            }
+
+            // The refresh did not produce usable credentials. Report the original
+            // error and drop the registration, so a later mount can try again
+            // rather than attaching to a subscription that will never load.
+            const { errorMessage, errorCode } = extractMessageError(message);
+            const error = new RebaseApiError(errorMessage, { code: errorCode });
+            if (messageType === "subscribe_collection") {
+                this.failCollectionSubscription(subscriptionKey, error);
             } else {
-                const { errorMessage, errorCode } = extractMessageError(message);
-                const error = new RebaseApiError(errorMessage, { code: errorCode });
-                subscription.callbacks.forEach(callback => {
-                    if (callback.onError) callback.onError(error);
-                });
+                this.failEntitySubscription(subscriptionKey, error);
             }
         }).catch(err => {
-            subscription.callbacks.forEach(callback => {
-                if (callback.onError) callback.onError(err);
-            });
+            const error = err instanceof Error ? err : new Error(String(err));
+            if (messageType === "subscribe_collection") {
+                this.failCollectionSubscription(subscriptionKey, error);
+            } else {
+                this.failEntitySubscription(subscriptionKey, error);
+            }
         });
     }
 
@@ -460,6 +526,25 @@ export class RebaseWebSocketClient {
             return;
         }
 
+        // Channel traffic (broadcast / presence) is addressed by channel name
+        // rather than by requestId or subscriptionId, so it is dispatched
+        // before the subscription paths — none of which would match it, and
+        // the message would otherwise fall through and be dropped silently.
+        if (typeof message.channel === "string" &&
+            (type === "broadcast" || type === "presence_state" || type === "presence_diff")) {
+            const handlers = this.channelHandlers.get(message.channel);
+            if (handlers) {
+                for (const handler of [...handlers]) {
+                    try {
+                        handler(message as unknown as Record<string, unknown>);
+                    } catch (error) {
+                        console.error("Error in channel handler:", error);
+                    }
+                }
+            }
+            return;
+        }
+
         // Handle subscription updates for collection subscriptions
         if (subscriptionId && type === "collection_update") {
             const subscriptionKey = this.backendToCollectionKey.get(subscriptionId);
@@ -469,16 +554,27 @@ export class RebaseWebSocketClient {
                     const wireEntities = (message.rows || []) as unknown as Record<string, unknown>[];
                     const incomingRows = wireEntities;
 
+                    // The keys arrive with the rows, so they are known before the
+                    // first merge — a CDC-driven change never sends a patch, and
+                    // learning them from patches alone would leave every
+                    // externally-written collection unable to match a thing.
+                    const updatePks = (message as unknown as { pks?: PrimaryKeyInfo[] }).pks;
+                    if (updatePks) collectionSub.pks = updatePks;
+
                     // Structural merge: preserve cached row references for rows
                     // whose values haven't changed. This prevents downstream React components
                     // from re-rendering (VirtualTableCell uses deepEqual on rowData —
                     // same reference = instant true, avoiding expensive deep comparison).
-                    const rows = this.mergeRows(collectionSub.latestData, incomingRows);
+                    const rows = this.mergeRows(collectionSub.latestData, incomingRows, collectionSub.pks);
 
                     // Cache the latest data with optimizations
                     collectionSub.latestData = rows;
                     collectionSub.lastUpdated = Date.now();
                     collectionSub.isInitialDataReceived = true;
+                    // The subscribe landed — stand the watchdog down.
+                    if (collectionSub.subscribeTimeout) clearTimeout(collectionSub.subscribeTimeout);
+                    collectionSub.subscribeTimeout = undefined;
+                    collectionSub.subscribeInFlight = false;
 
                     // Notify all callbacks for this subscription
                     collectionSub.callbacks.forEach(callback => {
@@ -504,16 +600,28 @@ export class RebaseWebSocketClient {
                 const collectionSub = this.collectionSubscriptions.get(subscriptionKey);
                 if (collectionSub && collectionSub.isInitialDataReceived && collectionSub.latestData) {
                     const patchWireEntity = message.row ?? null;
-                    const patchEntityId = (message as unknown as { id: string }).id;
+                    const patchMessage = message as unknown as { id: string; pks?: PrimaryKeyInfo[] };
+                    const patchEntityId = patchMessage.id;
+                    // The server knows the key columns; remember them, because the
+                    // refetch reconciliation needs them too and carries no id.
+                    if (patchMessage.pks) collectionSub.pks = patchMessage.pks;
                     const patchRow = patchWireEntity ? (patchWireEntity as unknown as Record<string, unknown>) : null;
                     let updated: Record<string, unknown>[];
 
                     if (patchRow === null) {
                         // Row was deleted — remove it from the cached list
-                        updated = collectionSub.latestData.filter(e => String(e.id) !== String(patchEntityId));
+                        updated = collectionSub.latestData.filter(
+                            e => this.rowAddress(e, collectionSub.pks) !== String(patchEntityId)
+                        );
                     } else {
-                        // Row was created or updated — merge into the cached list
-                        const idx = collectionSub.latestData.findIndex(e => String(e.id) === String(patchRow.id));
+                        // Row was created or updated — merge into the cached list.
+                        // Matched against the patch's own address rather than
+                        // anything read off the row: `patchRow.id` is undefined
+                        // for a table not keyed on `id`, so every update looked
+                        // like a new row and was prepended as a duplicate.
+                        const idx = collectionSub.latestData.findIndex(
+                            e => this.rowAddress(e, collectionSub.pks) === String(patchEntityId)
+                        );
                         if (idx >= 0) {
                             // Update in place (preserve array position)
                             updated = [...collectionSub.latestData];
@@ -555,6 +663,9 @@ export class RebaseWebSocketClient {
                     entitySub.latestData = row;
                     entitySub.lastUpdated = Date.now();
                     entitySub.isInitialDataReceived = true;
+                    if (entitySub.subscribeTimeout) clearTimeout(entitySub.subscribeTimeout);
+                    entitySub.subscribeTimeout = undefined;
+                    entitySub.subscribeInFlight = false;
 
                     // Notify all callbacks for this subscription
                     entitySub.callbacks.forEach(callback => {
@@ -590,6 +701,14 @@ export class RebaseWebSocketClient {
                         return;
                     }
 
+                    // The server answered, so nothing is in flight any more. Leave
+                    // the registration in place (its listeners are still mounted
+                    // and have been told), but marked idle so the next listener
+                    // re-subscribes instead of attaching to a dead entry.
+                    if (collectionSub.subscribeTimeout) clearTimeout(collectionSub.subscribeTimeout);
+                    collectionSub.subscribeTimeout = undefined;
+                    collectionSub.subscribeInFlight = false;
+
                     const { errorMessage, errorCode } = extractMessageError(message);
                     const error = new RebaseApiError(errorMessage, { code: errorCode });
                     collectionSub.callbacks.forEach(callback => {
@@ -617,6 +736,10 @@ export class RebaseWebSocketClient {
                         return;
                     }
 
+                    if (entitySub.subscribeTimeout) clearTimeout(entitySub.subscribeTimeout);
+                    entitySub.subscribeTimeout = undefined;
+                    entitySub.subscribeInFlight = false;
+
                     const { errorMessage, errorCode } = extractMessageError(message);
                     const error = new RebaseApiError(errorMessage, { code: errorCode });
                     entitySub.callbacks.forEach(callback => {
@@ -717,7 +840,11 @@ export class RebaseWebSocketClient {
         }
     }
 
-    private sendMessage(message: Record<string, unknown>): Promise<unknown> {
+    /**
+     * Public because `RebaseRealtimeChannel` sends channel frames through it.
+     * Not part of the stable surface — prefer `client.realtime.channel(name)`.
+     */
+    public sendMessage(message: Record<string, unknown>): Promise<unknown> {
         // If already has a requestId (re-sending from queue), use the stored promise handlers
         const queuedMsg = message as Record<string, unknown> & { _queuedResolve?: (p: unknown) => void; _queuedReject?: (p: Error) => void };
         if (queuedMsg._queuedResolve && queuedMsg._queuedReject) {
@@ -1016,23 +1143,48 @@ options }
         return val;
     }
 
+    /**
+     * The address of a row, for matching it against another copy of itself.
+     *
+     * A row is exactly its columns and carries no address, so it is derived
+     * from the key columns the server named — including the ordinary case where
+     * that key is `id`, which the server reports like any other.
+     *
+     * Undefined when there are no keys, which means the server could not
+     * resolve any: such rows genuinely cannot be recognised, and guessing at a
+     * column called `id` would be inventing an identity for a table that has
+     * none.
+     */
+    private rowAddress(row: Record<string, unknown>, pks: PrimaryKeyInfo[] | undefined): string | undefined {
+        if (!pks || pks.length === 0) return undefined;
+        const address = buildCompositeId(row, pks);
+        if (!address || address.split(COMPOSITE_ID_SEPARATOR).every(part => part === "")) return undefined;
+        return address;
+    }
+
     /**
      * Merge incoming rows with cached data, preserving cached references
      * for rows whose values haven't changed. This avoids unnecessary
      * React re-renders when the server refetches all rows but most
      * haven't actually changed.
      */
-    private mergeRows(cached: Record<string, unknown>[] | undefined, incoming: Record<string, unknown>[]): Record<string, unknown>[] {
+    private mergeRows(
+        cached: Record<string, unknown>[] | undefined,
+        incoming: Record<string, unknown>[],
+        pks?: PrimaryKeyInfo[]
+    ): Record<string, unknown>[] {
         if (!cached || cached.length === 0) return incoming;
 
-        // Build a lookup from cached rows by ID for O(1) access
-        const cachedById = new Map<string | number, Record<string, unknown>>();
+        // Build a lookup from cached rows by address for O(1) access
+        const cachedById = new Map<string, Record<string, unknown>>();
         for (const row of cached) {
-            cachedById.set(row.id as string | number, row);
+            const address = this.rowAddress(row, pks);
+            if (address !== undefined) cachedById.set(address, row);
         }
 
         return incoming.map(incomingRow => {
-            const cachedRow = cachedById.get(incomingRow.id as string | number);
+            const address = this.rowAddress(incomingRow, pks);
+            const cachedRow = address === undefined ? undefined : cachedById.get(address);
             if (!cachedRow) return incomingRow;
 
             // Compare flat rows directly (no more path/values nesting)
@@ -1051,7 +1203,7 @@ options }
 incoming: normIncoming[key] };
                     }
                 }
-                console.debug(`[RebaseWS] Row ${incomingRow.id} refetch mismatch:\n`, JSON.stringify(mismatches, null, 2));
+                console.debug(`[RebaseWS] Row ${address} refetch mismatch:\n`, JSON.stringify(mismatches, null, 2));
             }
             return incomingRow;
         });
@@ -1088,13 +1240,21 @@ onError });
                         onError(error instanceof Error ? error : new Error(String(error)));
                     }
                 }
+            } else if (!existingSubscription.subscribeInFlight) {
+                // Registered but idle: its subscribe never landed (the send failed,
+                // or the server answered with an error). Nothing is coming, so
+                // re-issue it — otherwise this listener waits forever.
+                this.sendCollectionSubscribe(subscriptionKey);
             }
 
             // Return unsubscribe function
             return () => {
                 callbackMap.delete(callbackId);
                 if (callbackMap.size === 0) {
-                    // No more callbacks, unsubscribe from backend
+                    // Only tear down if this is still the same registration — a
+                    // failed subscribe may have replaced it in the meantime.
+                    if (this.collectionSubscriptions.get(subscriptionKey) !== existingSubscription) return;
+                    if (existingSubscription.subscribeTimeout) clearTimeout(existingSubscription.subscribeTimeout);
                     this.collectionSubscriptions.delete(subscriptionKey);
                     this.backendToCollectionKey.delete(existingSubscription.backendSubscriptionId);
                     if (this.isConnected && this.ws) {
@@ -1125,16 +1285,9 @@ onError });
         // Add reverse lookup
         this.backendToCollectionKey.set(backendSubscriptionId, subscriptionKey);
 
-        // Send subscription request to backend
-        this.sendMessage({
-            type: "subscribe_collection",
-            payload: {
-                ...props,
-                subscriptionId: backendSubscriptionId
-            }
-        }).catch(error => {
-            if (onError) onError(error);
-        });
+        // Send subscription request to backend. A failure here drops the
+        // registration and notifies every listener, so the next mount retries.
+        this.sendCollectionSubscribe(subscriptionKey);
 
         // Return unsubscribe function
         return () => {
@@ -1143,6 +1296,7 @@ onError });
                 const callbacks = subscription.callbacks;
                 callbacks.delete(callbackId);
                 if (callbacks.size === 0) {
+                    if (subscription.subscribeTimeout) clearTimeout(subscription.subscribeTimeout);
                     this.collectionSubscriptions.delete(subscriptionKey);
                     this.backendToCollectionKey.delete(subscription.backendSubscriptionId);
                     if (this.isConnected && this.ws) {
@@ -1186,12 +1340,18 @@ onError });
                         onError(error instanceof Error ? error : new Error(String(error)));
                     }
                 }
+            } else if (!existingSubscription.subscribeInFlight) {
+                // See listenCollection: a registration with nothing in flight is
+                // dead, and attaching to it silently would hang this listener.
+                this.sendEntitySubscribe(subscriptionKey);
             }
 
             // Return unsubscribe function
             return () => {
                 callbackMap.delete(callbackId);
                 if (callbackMap.size === 0) {
+                    if (this.singleSubscriptions.get(subscriptionKey) !== existingSubscription) return;
+                    if (existingSubscription.subscribeTimeout) clearTimeout(existingSubscription.subscribeTimeout);
                     // No more callbacks, unsubscribe from backend
                     this.singleSubscriptions.delete(subscriptionKey);
                     this.backendToEntityKey.delete(existingSubscription.backendSubscriptionId);
@@ -1224,15 +1384,7 @@ onError });
         this.backendToEntityKey.set(backendSubscriptionId, subscriptionKey);
 
         // Send subscription request to backend
-        this.sendMessage({
-            type: "subscribe_one",
-            payload: {
-                ...props,
-                subscriptionId: backendSubscriptionId
-            }
-        }).catch(error => {
-            if (onError) onError(error);
-        });
+        this.sendEntitySubscribe(subscriptionKey);
 
         // Return unsubscribe function
         return () => {
@@ -1254,6 +1406,201 @@ onError });
         };
     }
 
+    /**
+     * Send a `subscribe_collection` for an already-registered subscription and
+     * arm its watchdog.
+     *
+     * Every path that registers a collection subscription goes through here, so
+     * that a subscribe which never lands — a rejected send, or a server that
+     * never answers — always ends up in `failCollectionSubscription` rather than
+     * leaving the entry parked with `isInitialDataReceived === false` forever.
+     */
+    private sendCollectionSubscribe(subscriptionKey: string): void {
+        const subscription = this.collectionSubscriptions.get(subscriptionKey);
+        if (!subscription) return;
+
+        const backendSubscriptionId = subscription.backendSubscriptionId;
+        subscription.subscribeInFlight = true;
+
+        if (subscription.subscribeTimeout) clearTimeout(subscription.subscribeTimeout);
+        subscription.subscribeTimeout = undefined;
+        // Only time out a frame that is actually on the wire. While offline the
+        // message just sits in the queue, and reconnect backoff can exceed the
+        // timeout — `armPendingSubscribeWatchdogs` picks these up on connect.
+        if (this.isConnected) this.sendCollectionSubscribeWatchdog(subscriptionKey);
+
+        this.sendMessage({
+            type: "subscribe_collection",
+            payload: {
+                ...subscription.props,
+                subscriptionId: backendSubscriptionId
+            }
+        }).catch(error => {
+            const current = this.collectionSubscriptions.get(subscriptionKey);
+            if (!current || current.backendSubscriptionId !== backendSubscriptionId) return;
+            this.failCollectionSubscription(
+                subscriptionKey,
+                error instanceof Error ? error : new Error(String(error))
+            );
+        });
+    }
+
+    /** The `listenOne` counterpart of {@link sendCollectionSubscribe}. */
+    private sendEntitySubscribe(subscriptionKey: string): void {
+        const subscription = this.singleSubscriptions.get(subscriptionKey);
+        if (!subscription) return;
+
+        const backendSubscriptionId = subscription.backendSubscriptionId;
+        subscription.subscribeInFlight = true;
+
+        if (subscription.subscribeTimeout) clearTimeout(subscription.subscribeTimeout);
+        subscription.subscribeTimeout = undefined;
+        if (this.isConnected) this.sendEntitySubscribeWatchdog(subscriptionKey);
+
+        this.sendMessage({
+            type: "subscribe_one",
+            payload: {
+                ...subscription.props,
+                subscriptionId: backendSubscriptionId
+            }
+        }).catch(error => {
+            const current = this.singleSubscriptions.get(subscriptionKey);
+            if (!current || current.backendSubscriptionId !== backendSubscriptionId) return;
+            this.failEntitySubscription(
+                subscriptionKey,
+                error instanceof Error ? error : new Error(String(error))
+            );
+        });
+    }
+
+    /**
+     * Report a subscribe failure to every listener and drop the registration.
+     *
+     * Dropping it is the point: the callbacks stay live (their components are
+     * still mounted and have been told), but the next `listenCollection` for
+     * these params finds no entry and issues a fresh subscribe instead of
+     * silently attaching to a dead one.
+     */
+    private failCollectionSubscription(subscriptionKey: string, error: Error): void {
+        const subscription = this.collectionSubscriptions.get(subscriptionKey);
+        if (!subscription) return;
+
+        if (subscription.subscribeTimeout) clearTimeout(subscription.subscribeTimeout);
+        subscription.subscribeInFlight = false;
+
+        this.collectionSubscriptions.delete(subscriptionKey);
+        this.backendToCollectionKey.delete(subscription.backendSubscriptionId);
+
+        subscription.callbacks.forEach(callback => {
+            if (callback.onError) {
+                try {
+                    callback.onError(error);
+                } catch (callbackError) {
+                    console.error("Error in collection subscription error callback:", callbackError);
+                }
+            }
+        });
+    }
+
+    /** The `listenOne` counterpart of {@link failCollectionSubscription}. */
+    private failEntitySubscription(subscriptionKey: string, error: Error): void {
+        const subscription = this.singleSubscriptions.get(subscriptionKey);
+        if (!subscription) return;
+
+        if (subscription.subscribeTimeout) clearTimeout(subscription.subscribeTimeout);
+        subscription.subscribeInFlight = false;
+
+        this.singleSubscriptions.delete(subscriptionKey);
+        this.backendToEntityKey.delete(subscription.backendSubscriptionId);
+
+        subscription.callbacks.forEach(callback => {
+            if (callback.onError) {
+                try {
+                    callback.onError(error);
+                } catch (callbackError) {
+                    console.error("Error in row subscription error callback:", callbackError);
+                }
+            }
+        });
+    }
+
+    /**
+     * Stop the watchdogs without failing anything — used when the socket drops,
+     * since the reconnect path re-subscribes everything anyway and a watchdog
+     * firing mid-reconnect would tear down healthy subscriptions.
+     */
+    private suspendSubscribeWatchdogs(): void {
+        for (const sub of this.collectionSubscriptions.values()) {
+            if (sub.subscribeTimeout) clearTimeout(sub.subscribeTimeout);
+            sub.subscribeTimeout = undefined;
+            sub.subscribeInFlight = false;
+        }
+        for (const sub of this.singleSubscriptions.values()) {
+            if (sub.subscribeTimeout) clearTimeout(sub.subscribeTimeout);
+            sub.subscribeTimeout = undefined;
+            sub.subscribeInFlight = false;
+        }
+    }
+
+    /**
+     * Arm watchdogs for subscribes that were requested while offline and have
+     * just been flushed to the socket. Their timers were deliberately not set at
+     * request time, so without this they would have no timeout at all.
+     */
+    private armPendingSubscribeWatchdogs(): void {
+        for (const [key, sub] of this.collectionSubscriptions.entries()) {
+            if (sub.subscribeInFlight && !sub.subscribeTimeout) this.sendCollectionSubscribeWatchdog(key);
+        }
+        for (const [key, sub] of this.singleSubscriptions.entries()) {
+            if (sub.subscribeInFlight && !sub.subscribeTimeout) this.sendEntitySubscribeWatchdog(key);
+        }
+    }
+
+    private sendCollectionSubscribeWatchdog(subscriptionKey: string): void {
+        const subscription = this.collectionSubscriptions.get(subscriptionKey);
+        if (!subscription) return;
+        const backendSubscriptionId = subscription.backendSubscriptionId;
+        subscription.subscribeTimeout = setTimeout(() => {
+            const current = this.collectionSubscriptions.get(subscriptionKey);
+            if (!current || current.backendSubscriptionId !== backendSubscriptionId) return;
+            if (!current.subscribeInFlight) return;
+            this.failCollectionSubscription(
+                subscriptionKey,
+                new RebaseApiError("Subscription timed out", { code: "SUBSCRIPTION_TIMEOUT" })
+            );
+        }, this.subscriptionTimeoutMs);
+    }
+
+    private sendEntitySubscribeWatchdog(subscriptionKey: string): void {
+        const subscription = this.singleSubscriptions.get(subscriptionKey);
+        if (!subscription) return;
+        const backendSubscriptionId = subscription.backendSubscriptionId;
+        subscription.subscribeTimeout = setTimeout(() => {
+            const current = this.singleSubscriptions.get(subscriptionKey);
+            if (!current || current.backendSubscriptionId !== backendSubscriptionId) return;
+            if (!current.subscribeInFlight) return;
+            this.failEntitySubscription(
+                subscriptionKey,
+                new RebaseApiError("Subscription timed out", { code: "SUBSCRIPTION_TIMEOUT" })
+            );
+        }, this.subscriptionTimeoutMs);
+    }
+
+    /**
+     * Fail every subscription that never received data. Called when reconnection
+     * is given up on, so views surface an error instead of spinning forever.
+     */
+    private failAllPendingSubscriptions(error: Error): void {
+        for (const key of [...this.collectionSubscriptions.keys()]) {
+            const sub = this.collectionSubscriptions.get(key);
+            if (sub && !sub.isInitialDataReceived) this.failCollectionSubscription(key, error);
+        }
+        for (const key of [...this.singleSubscriptions.keys()]) {
+            const sub = this.singleSubscriptions.get(key);
+            if (sub && !sub.isInitialDataReceived) this.failEntitySubscription(key, error);
+        }
+    }
+
     /**
      * Re-send all active subscriptions to the backend after a reconnect.
      * The server wipes subscription state when a client disconnects, so
@@ -1273,15 +1620,7 @@ onError });
             this.backendToCollectionKey.delete(oldBackendId);
             this.backendToCollectionKey.set(newBackendId, key);
 
-            this.sendMessage({
-                type: "subscribe_collection",
-                payload: {
-                    ...sub.props,
-                    subscriptionId: newBackendId
-                }
-            }).catch(error => {
-                console.error("[WS] Failed to re-subscribe collection:", key, error);
-            });
+            this.sendCollectionSubscribe(key);
         }
 
         // Re-subscribe row subscriptions
@@ -1293,15 +1632,7 @@ onError });
             this.backendToEntityKey.delete(oldBackendId);
             this.backendToEntityKey.set(newBackendId, key);
 
-            this.sendMessage({
-                type: "subscribe_one",
-                payload: {
-                    ...sub.props,
-                    subscriptionId: newBackendId
-                }
-            }).catch(error => {
-                console.error("[WS] Failed to re-subscribe row:", key, error);
-            });
+            this.sendEntitySubscribe(key);
         }
     }