fix: handle transient ShareDB errors and inactive-tab reconnection (#1965)

- fix event name mismatch: 'realtime:asset:error' → 'realtime:assets:error'
- add 3s grace period before showing fatal error overlay
- detect zombie sockets when tab returns from background
- pause keep-alive pings while tab is hidden
- always emit asset errors instead of silently swallowing them
- log swallowed ShareDB errors for debugging

Author: kpal81xd

src/editor-api/realtime/asset.ts

@@ -107,11 +107,8 @@ class RealtimeAsset extends Events {
     }
 
     _onError(err: string) {
-        if (this._connection.connected) {
-            console.log(err);
-        } else {
-            this._realtime.emit('error:asset', err, this._uniqueId);
-        }
+        console.warn('asset error:', this._uniqueId, err);
+        this._realtime.emit('error:asset', err, this._uniqueId);
     }
 
     _onLoad() {

src/editor-api/realtime/connection.ts

@@ -55,21 +55,54 @@ class RealtimeConnection extends Events {
         this._realtime = realtime;
         this._domEvtVisibilityChange = () => {
             if (document.hidden) {
+                // pause keep-alive while tab is hidden
+                if (this._alive) {
+                    clearInterval(this._alive);
+                    this._alive = null;
+                }
+                return;
+            }
+
+            // tab became visible — check if socket is still alive
+            if (this._state === 'connected' && this._socket?.readyState !== WebSocket.OPEN) {
+                // socket died while tab was hidden but close event hasn't fired yet
+                this._socket?.close();
                 return;
             }
+
+            // restart keep-alive if connected
+            if (this._state === 'connected' && !this._alive) {
+                this._startKeepAlive();
+            }
+
             if (this._state === 'disconnected' && this._url) {
                 this.connect(this._url);
             }
         };
     }
 
+    private _startKeepAlive() {
+        if (this._alive) {
+            clearInterval(this._alive);
+        }
+        this._alive = setInterval(() => {
+            if (!this._sharedb) {
+                return;
+            }
+            if (this._sharedb.state === 'connected') {
+                this._sharedb.ping();
+            }
+        }, 1000);
+    }
+
     private _onauth(socket: WebSocket) {
         if (this._sharedb) {
             this._sharedb.bindToSocket(socket);
         } else {
             this._sharedb = new share.Connection(socket) as ShareDb;
             this._sharedb.on('error', (err) => {
                 if (this._sharedb?.state === 'connected') {
+                    console.warn('sharedb error while connected:', err);
                     return;
                 }
                 this._realtime.emit('error', err);
@@ -79,18 +112,7 @@ class RealtimeConnection extends Events {
             });
         }
 
-        // reset keep alive
-        if (this._alive) {
-            clearInterval(this._alive);
-        }
-        this._alive = setInterval(() => {
-            if (!this._sharedb) {
-                return;
-            }
-            if (this._sharedb.state === 'connected') {
-                this._sharedb.ping();
-            }
-        }, 1000);
+        this._startKeepAlive();
 
         // intercept messages
         const onmessage = socket.onmessage;

src/editor/alerts/alert-connection.ts

@@ -28,6 +28,8 @@ editor.once('load', () => {
     overlay.domContent.appendChild(content);
 
     editor.on('realtime:connected', () => {
+        clearErrorGrace();
+
         if (viewportError) {
             return;
         }
@@ -67,6 +69,8 @@ editor.once('load', () => {
     });
 
     editor.on('realtime:connecting', (attempt) => {
+        clearErrorGrace();
+
         if (viewportError) {
             return;
         }
@@ -81,11 +85,37 @@ editor.once('load', () => {
         content.innerHTML = 'Cannot connect to the server. Please try again later.';
     });
 
+    const ERROR_GRACE_MS = 3000;
+    let errorGraceTimeout: ReturnType<typeof setTimeout> | null = null;
+
+    const clearErrorGrace = () => {
+        if (errorGraceTimeout) {
+            clearTimeout(errorGraceTimeout);
+            errorGraceTimeout = null;
+        }
+    };
+
     const onError = function (err: unknown) {
-        console.log(err);
-        console.trace();
-        content.innerHTML = 'Error while saving changes. Please refresh the editor.';
-        overlay.hidden = false;
+        console.warn('realtime error:', err);
+
+        // debounce — only one grace period at a time
+        if (errorGraceTimeout) {
+            return;
+        }
+
+        errorGraceTimeout = setTimeout(() => {
+            errorGraceTimeout = null;
+
+            // if connection recovered during grace period, skip the fatal overlay
+            const conn = editor.call('realtime:connection');
+            if (conn?.state === 'connected') {
+                console.warn('realtime error suppressed — connection recovered during grace period');
+                return;
+            }
+
+            content.innerHTML = 'Error while saving changes. Please refresh the editor.';
+            overlay.hidden = false;
+        }, ERROR_GRACE_MS);
     };
 
     editor.on('viewport:error', (err) => {
@@ -122,6 +152,8 @@ editor.once('load', () => {
     });
 
     editor.on('scene:unload', () => {
+        clearErrorGrace();
+
         if (viewportError) {
             return;
         }

src/editor/realtime/realtime.ts

@@ -33,7 +33,7 @@ editor.once('start', () => {
     });
 
     realtime.on('error:asset', (err: unknown) => {
-        editor.emit('realtime:asset:error', err);
+        editor.emit('realtime:assets:error', err);
     });
 
     realtime.on('disconnect', (reason: string) => {

src/launch/assets/assets-sync.ts

@@ -49,7 +49,7 @@ editor.once('load', () => {
         // error
         doc.on('error', (err: unknown) => {
             if (connection.state === 'connected') {
-                console.log(err);
+                console.warn('asset doc error while connected:', err);
                 return;
             }