@solidtv/renderer 1.2.8 → 1.2.10

package/src/core/CoreNode.ts

@@ -295,6 +295,10 @@ export interface CoreNodeProps {
    * its descendants from overflowing outside of the Node's x/y/width/height
    * bounds.
    *
+   * Pass `true` to clip exactly to the Node's bounds, or pass a
+   * `[top, right, bottom, left]` tuple to expand the clip rectangle outward
+   * by the given pixel amounts on each side (negative values inset it).
+   *
    * For WebGL, clipping is implemented using the high-performance WebGL
    * operation scissor. As a consequence, clipping does not work for
    * non-rectangular areas. So, if the element is rotated
@@ -305,7 +309,7 @@ export interface CoreNodeProps {
    *
    * @default `false`
    */
-  clipping: boolean;
+  clipping: boolean | [number, number, number, number];
   /**
    * The color of the Node.
    *
@@ -804,13 +808,14 @@ export class CoreNode extends EventEmitter {
   public renderBound?: Bound;
   public strictBound?: Bound;
   public preloadBound?: Bound;
-  public clippingRect: RectWithValid = {
-    x: 0,
-    y: 0,
-    w: 0,
-    h: 0,
-    valid: false,
-  };
+  /**
+   * Points at the shared `NO_CLIPPING_RECT` until this node actually
+   * participates in clipping (either it clips, or an ancestor's clip rect
+   * propagates down). Clipping is rare across the scene graph, so most nodes
+   * never allocate their own rect — `calculateClippingRect` swaps in a private
+   * object lazily the first time one is needed.
+   */
+  public clippingRect: RectWithValid = NO_CLIPPING_RECT;
   public textureCoords?: TextureCoords;
   public updateShaderUniforms: boolean = false;
   public isRenderable = false;
@@ -1366,7 +1371,7 @@ export class CoreNode extends EventEmitter {
         childUpdateType |= UpdateType.Global;
       }
 
-      if (this.clipping === true) {
+      if (this.props.clipping !== false) {
         updateType |= UpdateType.Clipping | UpdateType.RenderBounds;
         childUpdateType |= UpdateType.RenderBounds;
       }
@@ -1669,14 +1674,31 @@ export class CoreNode extends EventEmitter {
     }
 
     // clipping is enabled and we are in bounds create our own bounds
-    const { x, y, w, h } = this.props;
+    const { x, y, w, h, clipping } = this.props;
 
     // Pick the global transform if available, otherwise use the local transform
     // global transform is only available if the node in an RTT chain
     const { tx, ty } = this.sceneGlobalTransform || this.globalTransform || {};
     const _x = tx ?? x;
     const _y = ty ?? y;
-    this.strictBound = createBound(_x, _y, _x + w, _y + h, this.strictBound);
+
+    let mT = 0;
+    let mR = 0;
+    let mB = 0;
+    let mL = 0;
+    if (Array.isArray(clipping) === true) {
+      mT = clipping[0];
+      mR = clipping[1];
+      mB = clipping[2];
+      mL = clipping[3];
+    }
+    this.strictBound = createBound(
+      _x - mL,
+      _y - mT,
+      _x + w + mR,
+      _y + h + mB,
+      this.strictBound,
+    );
 
     this.preloadBound = createPreloadBounds(
       this.strictBound,
@@ -1912,15 +1934,47 @@ export class CoreNode extends EventEmitter {
    * Finally, the node's parentClippingRect and clippingRect properties are updated.
    */
   calculateClippingRect(parentClippingRect: RectWithValid) {
-    const { clippingRect, props, globalTransform: gt } = this;
+    const { props, globalTransform: gt } = this;
     const { clipping } = props;
     const isRotated = gt!.tb !== 0 || gt!.tc !== 0;
+    const nodeClips = clipping !== false && isRotated === false;
 
-    if (clipping === true && isRotated === false) {
-      clippingRect.x = gt!.tx;
-      clippingRect.y = gt!.ty;
-      clippingRect.w = this.props.w * gt!.ta;
-      clippingRect.h = this.props.h * gt!.td;
+    // Common case: this node doesn't clip and no ancestor clip rect needs to
+    // propagate. No node-owned rect is required, so point at the shared
+    // invalid default and skip the allocation entirely.
+    if (nodeClips === false && parentClippingRect.valid === false) {
+      this.clippingRect = NO_CLIPPING_RECT;
+      return;
+    }
+
+    // A node-owned, mutable rect is needed. Allocate one lazily the first time
+    // (the default shares NO_CLIPPING_RECT, which must never be written to).
+    let clippingRect = this.clippingRect;
+    if (clippingRect === NO_CLIPPING_RECT) {
+      clippingRect = this.clippingRect = {
+        x: 0,
+        y: 0,
+        w: 0,
+        h: 0,
+        valid: false,
+      };
+    }
+
+    if (nodeClips === true) {
+      let mT = 0;
+      let mR = 0;
+      let mB = 0;
+      let mL = 0;
+      if (Array.isArray(clipping) === true) {
+        mT = clipping[0];
+        mR = clipping[1];
+        mB = clipping[2];
+        mL = clipping[3];
+      }
+      clippingRect.x = gt!.tx - mL;
+      clippingRect.y = gt!.ty - mT;
+      clippingRect.w = this.props.w * gt!.ta + mL + mR;
+      clippingRect.h = this.props.h * gt!.td + mT + mB;
       clippingRect.valid = true;
     } else {
       clippingRect.valid = false;
@@ -2421,11 +2475,14 @@ export class CoreNode extends EventEmitter {
     this.setUpdateType(UpdateType.RenderBounds);
   }
 
-  get clipping(): boolean {
+  get clipping(): boolean | [number, number, number, number] {
     return this.props.clipping;
   }
 
-  set clipping(value: boolean) {
+  set clipping(value: boolean | [number, number, number, number]) {
+    if (this.props.clipping === value) {
+      return;
+    }
     this.props.clipping = value;
     this.setUpdateType(
       UpdateType.Clipping | UpdateType.RenderBounds | UpdateType.Children,

package/src/core/Stage.contextLoss.test.ts

@@ -0,0 +1,45 @@
+/**
+ * Tests for WebGL context-loss handling on the Stage.
+ *
+ * Covers the pragmatic core support added for low-RAM devices (Chromium 123+
+ * drops the GPU context when backgrounded). On loss we stop the render loop
+ * and emit a `contextLost` event so consumers can reload; the engine does not
+ * rebuild GL resources in place, so there is no restore path.
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { Stage } from './Stage.js';
+import { EventEmitter } from '../common/EventEmitter.js';
+
+// Build a minimal Stage-like object that exercises the context-loss methods
+// without standing up the full GL-backed constructor.
+function makeStage() {
+  const eventBus = new EventEmitter();
+  const stage = Object.create(Stage.prototype) as Stage;
+  (stage as unknown as { eventBus: EventEmitter }).eventBus = eventBus;
+  stage.isContextLost = false;
+  return { stage, eventBus };
+}
+
+describe('Stage.setContextLost', () => {
+  it('sets the flag and emits contextLost', () => {
+    const { stage, eventBus } = makeStage();
+    const onLost = vi.fn();
+    eventBus.on('contextLost', onLost);
+
+    stage.setContextLost();
+
+    expect(stage.isContextLost).toBe(true);
+    expect(onLost).toHaveBeenCalledTimes(1);
+  });
+
+  it('is idempotent — does not re-emit when already lost', () => {
+    const { stage, eventBus } = makeStage();
+    const onLost = vi.fn();
+    eventBus.on('contextLost', onLost);
+
+    stage.setContextLost();
+    stage.setContextLost();
+
+    expect(onLost).toHaveBeenCalledTimes(1);
+  });
+});

package/src/core/Stage.ts

@@ -119,6 +119,18 @@ export class Stage {
    */
   public readonly eventBus: EventEmitter;
 
+  /**
+   * Whether the underlying WebGL context has been lost.
+   *
+   * @remarks
+   * Set by the renderer's `webglcontextlost` listener. Once true it stays true:
+   * the engine does not rebuild GPU resources in-place, so the render loop
+   * stops and the supported recovery is to reload the app (see the `contextLost`
+   * event). This avoids issuing GL calls against a dead context, which return
+   * null/throw on low-RAM devices (e.g. Chromium 123+ backgrounding behaviour).
+   */
+  public isContextLost = false;
+
   /// State
   startTime = 0;
   deltaTime = 0;
@@ -429,6 +441,21 @@ export class Stage {
     });
   }
 
+  /**
+   * Mark the WebGL context as lost. Stops GL work and notifies consumers.
+   *
+   * @remarks
+   * The engine does not rebuild GPU resources in-place; consumers are expected
+   * to reload the app in response to the `contextLost` event.
+   */
+  setContextLost() {
+    if (this.isContextLost === true) {
+      return;
+    }
+    this.isContextLost = true;
+    this.eventBus.emit('contextLost');
+  }
+
   /**
    * Create default PixelTexture
    */

package/src/core/platforms/web/WebPlatform.contextLoss.test.ts

@@ -0,0 +1,80 @@
+/**
+ * Tests that the render loop stops doing GL work once the WebGL context is
+ * lost.
+ *
+ * When `stage.isContextLost === true`, `runLoop` must issue no GL-touching
+ * calls and must not reschedule itself — the engine does not rebuild GL
+ * resources, so recovery is via app reload.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { WebPlatform } from './WebPlatform.js';
+import type { Stage } from '../../Stage.js';
+
+function makeFakeStage(isContextLost: boolean) {
+  return {
+    isContextLost,
+    targetFrameTime: 0,
+    updateFrameTime: vi.fn(),
+    updateAnimations: vi.fn(() => false),
+    hasSceneUpdates: vi.fn(() => true),
+    drawFrame: vi.fn(),
+    flushFrameEvents: vi.fn(),
+    calculateFps: vi.fn(),
+  } as unknown as Stage;
+}
+
+describe('WebPlatform render loop context-loss guard', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('skips all GL work and does not reschedule while context is lost', () => {
+    let capturedLoop: ((t?: number) => void) | null = null;
+    const raf = vi.fn((cb: (t?: number) => void) => {
+      capturedLoop = cb;
+      return 1;
+    });
+    const setTimeoutSpy = vi.fn(
+      (_cb: () => void, _ms?: number) =>
+        1 as unknown as ReturnType<typeof setTimeout>,
+    );
+    vi.stubGlobal('requestAnimationFrame', raf);
+    vi.stubGlobal('setTimeout', setTimeoutSpy);
+
+    const stage = makeFakeStage(true);
+    new WebPlatform().startLoop(stage);
+
+    // startLoop kicks off the first frame via requestAnimationFrame
+    expect(capturedLoop).not.toBeNull();
+    expect(raf).toHaveBeenCalledTimes(1);
+
+    // Run one iteration with the context lost
+    capturedLoop!(0);
+
+    // No GL-touching frame work happened
+    expect(stage.updateFrameTime).not.toHaveBeenCalled();
+    expect(stage.drawFrame).not.toHaveBeenCalled();
+    expect(stage.hasSceneUpdates).not.toHaveBeenCalled();
+
+    // The loop did not reschedule itself (neither RAF nor setTimeout)
+    expect(raf).toHaveBeenCalledTimes(1);
+    expect(setTimeoutSpy).not.toHaveBeenCalled();
+  });
+
+  it('runs frame work when the context is healthy', () => {
+    let capturedLoop: ((t?: number) => void) | null = null;
+    const raf = vi.fn((cb: (t?: number) => void) => {
+      capturedLoop = cb;
+      return 1;
+    });
+    vi.stubGlobal('requestAnimationFrame', raf);
+
+    const stage = makeFakeStage(false);
+    new WebPlatform().startLoop(stage);
+
+    capturedLoop!(0);
+
+    expect(stage.updateFrameTime).toHaveBeenCalledTimes(1);
+    expect(stage.drawFrame).toHaveBeenCalledTimes(1);
+  });
+});

package/src/core/platforms/web/WebPlatform.ts

@@ -32,6 +32,13 @@ export class WebPlatform extends Platform {
     const buffer = 4;
 
     const runLoop = (currentTime: number = 0) => {
+      // The GL context is lost and the engine does not rebuild it in place.
+      // Stop the loop entirely (no reschedule) so we issue no GL calls against
+      // a dead context. Recovery is via app reload (see the `contextLost` event).
+      if (stage.isContextLost === true) {
+        return;
+      }
+
       const targetFrameTime = stage.targetFrameTime;
 
       // Frame Limiting logic

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;