@solidtv/renderer 1.2.9 → 1.2.10

package/src/core/renderers/webgl/WebGlRenderer.ts

@@ -174,6 +174,8 @@ export class WebGlRenderer extends CoreRenderer {
     const glw = (this.glw = new WebGlContextWrapper(gl));
     glw.viewport(0, 0, options.canvas.width, options.canvas.height);
 
+    this.attachContextLossListeners(options.canvas);
+
     this.updateClearColor(this.stage.clearColor);
 
     glw.setBlend(true);
@@ -300,6 +302,32 @@ export class WebGlRenderer extends CoreRenderer {
     ]);
   }
 
+  /**
+   * Listen for WebGL context loss on the canvas.
+   *
+   * @remarks
+   * On low-RAM devices (e.g. Chromium 123+ after backgrounding) the GPU
+   * context is dropped, after which `gl.createTexture()` and friends return
+   * null and the engine would crash. We pause the render loop via the Stage
+   * flag and surface a `contextLost` event so consumers can react.
+   *
+   * We intentionally do NOT call `event.preventDefault()` (which would ask the
+   * browser to restore the context) and do NOT listen for
+   * `webglcontextrestored`: the engine cannot rebuild its GPU resources
+   * in-place, so the supported recovery is to reload the app. See BROWSERS.md.
+   */
+  private attachContextLossListeners(
+    canvas: HTMLCanvasElement | OffscreenCanvas,
+  ): void {
+    if ('addEventListener' in canvas === false) {
+      return;
+    }
+    const target = canvas as HTMLCanvasElement;
+    target.addEventListener('webglcontextlost', () => {
+      this.stage.setContextLost();
+    });
+  }
+
   reset() {
     const { glw } = this;
     if (DIRTY_QUAD_BUFFER) {

package/src/main-api/Renderer.ts

@@ -145,6 +145,28 @@ export interface RendererMainCriticalCleanupFailedEvent {
   criticalThreshold: number;
 }
 
+/**
+ * WebGL Context Lost Event Data
+ *
+ * @remarks
+ * Fired when the underlying WebGL context is lost (e.g. on low-RAM devices
+ * running Chromium 123+ after the app has been backgrounded). The render loop
+ * stops; in-engine GL resources are NOT rebuilt, so the supported handling is
+ * to reload the app.
+ *
+ * @category Events
+ * @example
+ * ```typescript
+ * renderer.on('contextLost', () => {
+ *   window.location.reload();
+ * });
+ * ```
+ */
+export interface RendererMainContextLostEvent {
+  /** This event has no payload - listen without parameters */
+  readonly __eventHasNoPayload?: never;
+}
+
 /**
  * Settings for the Renderer that can be updated during runtime.
  */
@@ -506,6 +528,7 @@ export type RendererMainSettings = RendererRuntimeSettings & {
  * @see {@link RendererMainIdleEvent}
  * @see {@link RendererMainCriticalCleanupEvent}
  * @see {@link RendererMainCriticalCleanupFailedEvent}
+ * @see {@link RendererMainContextLostEvent}
  *
  * @fires RendererMain#fpsUpdate
  * @fires RendererMain#frameTick
@@ -513,6 +536,7 @@ export type RendererMainSettings = RendererRuntimeSettings & {
  * @fires RendererMain#idle
  * @fires RendererMain#criticalCleanup
  * @fires RendererMain#criticalCleanupFailed
+ * @fires RendererMain#contextLost
  */
 export class RendererMain extends EventEmitter {
   readonly root: INode;