Recover from webgl context loss

On mobile webgl gets stopped when not used if memory is low. But can be restored.

Part of #639

AI use: Sonnet 4.6 to research best practices. Interactives session to implement and review.

Author: tracygardner

flock.js

@@ -137,6 +137,9 @@ export const flock = {
   canvas: null,
   abortController: null,
   _renderLoop: null,
+  _contextLostAt: null,
+  _escalationTimer: null,
+  _webglVisibilityListenerAdded: false,
   document: document,
   disposed: null,
   events: {},
@@ -1329,6 +1332,18 @@ export const flock = {
       }
     });
   },
+  _scheduleContextEscalation() {
+    clearTimeout(flock._escalationTimer);
+    flock._escalationTimer = setTimeout(() => {
+      flock._escalationTimer = null;
+      if (flock.engine?.isContextLost?.()) {
+        handleError(new Error('WebGL context restore timeout'), {
+          source: 'webgl-lost',
+          fatal: true,
+        });
+      }
+    }, 8000);
+  },
   createEngine() {
     flock.engine?.dispose();
     flock.engine = null;
@@ -1341,13 +1356,44 @@ export const flock = {
       lockstepMaxSteps: 4,
     });
 
+    // Call preventDefault() on the raw event so the browser is willing to restore.
+    flock.canvas.addEventListener('webglcontextlost', (event) => {
+      event.preventDefault();
+    });
+
     flock.engine.onContextLostObservable.add(() => {
-      handleError(new Error('WebGL context lost'), {
-        source: 'webgl-lost',
-        fatal: true,
+      flock._contextLostAt = Date.now();
+      showBanner('webgl-lost', {
+        message: translate('error_webgl_restoring'),
       });
+      if (document.visibilityState === 'visible') {
+        flock._scheduleContextEscalation();
+      }
     });
 
+    flock.engine.onContextRestoredObservable.add(() => {
+      clearTimeout(flock._escalationTimer);
+      flock._escalationTimer = null;
+      flock._contextLostAt = null;
+      dismissBanner('webgl-lost');
+      flock.engine.resize();
+      if (flock._renderLoop) {
+        flock.engine.runRenderLoop(flock._renderLoop);
+      }
+    });
+
+    if (!flock._webglVisibilityListenerAdded) {
+      flock._webglVisibilityListenerAdded = true;
+      document.addEventListener('visibilitychange', () => {
+        if (document.visibilityState === 'visible' && flock._contextLostAt) {
+          flock.engine?.resize();
+          if (!flock._escalationTimer) {
+            flock._scheduleContextEscalation();
+          }
+        }
+      });
+    }
+
     flock.engine.enableOfflineSupport = false;
     flock.engine.setHardwareScalingLevel(1 / window.devicePixelRatio);
   },

locale/en.js

@@ -1182,6 +1182,7 @@ export default {
   error_startup: "Flock couldn't start up. Try reloading the page.",
   error_project_crash:
     "Your project hit a problem. Press Stop, check your blocks, then press Play again.",
+  error_webgl_restoring: "3D view paused, restoring…",
   error_webgl_lost: "The 3D view stopped working. Try reloading the page.",
   error_physics_oom:
     "Your project ran out of memory. Try reloading the page and using fewer blocks.",

locale/es.js

@@ -1183,6 +1183,7 @@ export default {
   error_startup: "Flock no se pudo iniciar. Intenta recargar la página.", // human
   error_project_crash:
     "Tu proyecto tuvo un problema. Pulsa Detener, revisa tus bloques y pulsa Reproducir otra vez.", // human
+  error_webgl_restoring: "Vista 3D pausada, restaurando…", // human
   error_webgl_lost:
     "La vista 3D dejó de funcionar. Intenta recargar la página.", // human
   error_physics_oom: