@solidtv/renderer 1.3.0 → 1.3.2

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

@@ -0,0 +1,79 @@
+/**
+ * Tests that the GPU out-of-memory probe runs at the idle transition (end of a
+ * render burst), not on every active frame.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { WebPlatform } from './WebPlatform.js';
+import type { Stage } from '../../Stage.js';
+
+function makeIdleStage(outOfMemory: boolean) {
+  const checkForOutOfMemory = vi.fn(() => outOfMemory);
+  const handleOutOfMemory = vi.fn();
+  const stage = {
+    isContextLost: false,
+    targetFrameTime: 0,
+    updateFrameTime: vi.fn(),
+    updateAnimations: vi.fn(() => false),
+    hasSceneUpdates: vi.fn(() => false), // idle
+    calculateFps: vi.fn(),
+    drawFrame: vi.fn(),
+    flushFrameEvents: vi.fn(),
+    shManager: { cleanup: vi.fn() },
+    cleanupTextRenderers: vi.fn(),
+    eventBus: { emit: vi.fn() },
+    txMemManager: {
+      checkCleanup: vi.fn(() => false),
+      cleanup: vi.fn(),
+      handleOutOfMemory,
+    },
+    renderer: { checkForOutOfMemory },
+  } as unknown as Stage;
+  return { stage, checkForOutOfMemory, handleOutOfMemory };
+}
+
+describe('WebPlatform render loop — out-of-memory probe at idle', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  function runOneIdleFrame(stage: Stage) {
+    let capturedLoop: ((t?: number) => void) | null = null;
+    const raf = vi.fn((cb: (t?: number) => void) => {
+      capturedLoop = cb;
+      return 1;
+    });
+    vi.stubGlobal('requestAnimationFrame', raf);
+    vi.stubGlobal(
+      'setTimeout',
+      vi.fn(() => 1 as unknown as ReturnType<typeof setTimeout>),
+    );
+
+    new WebPlatform().startLoop(stage);
+    capturedLoop!(0);
+  }
+
+  it('probes the renderer once when the scene goes idle', () => {
+    const { stage, checkForOutOfMemory } = makeIdleStage(false);
+    runOneIdleFrame(stage);
+    expect(checkForOutOfMemory).toHaveBeenCalledTimes(1);
+  });
+
+  it('handles OOM when the probe reports it at idle', () => {
+    const { stage, handleOutOfMemory } = makeIdleStage(true);
+    runOneIdleFrame(stage);
+    expect(handleOutOfMemory).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not handle OOM when the probe reports none', () => {
+    const { stage, handleOutOfMemory } = makeIdleStage(false);
+    runOneIdleFrame(stage);
+    expect(handleOutOfMemory).not.toHaveBeenCalled();
+  });
+
+  it('does not probe on an active (non-idle) frame', () => {
+    const { stage, checkForOutOfMemory } = makeIdleStage(false);
+    (stage.hasSceneUpdates as ReturnType<typeof vi.fn>).mockReturnValue(true);
+    runOneIdleFrame(stage);
+    expect(checkForOutOfMemory).not.toHaveBeenCalled();
+  });
+});

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

@@ -77,7 +77,16 @@ export class WebPlatform extends Platform {
         setTimeout(requestLoop, Math.max(targetFrameTime, 15));
 
         if (isIdle === false) {
+          // The render burst has settled. Probe for a GPU out-of-memory now
+          // rather than every frame: GL errors accumulate and persist until
+          // drained, so a single check here still catches any OOM raised during
+          // the active frames, without paying the getError() CPU/GPU sync on
+          // every frame. Queues the `outOfMemory` event, flushed below.
+          if (stage.renderer.checkForOutOfMemory() === true) {
+            stage.txMemManager.handleOutOfMemory();
+          }
           stage.shManager.cleanup();
+          stage.cleanupTextRenderers();
           stage.eventBus.emit('idle');
           isIdle = true;
         }

package/src/core/renderers/CoreRenderer.ts

@@ -67,4 +67,16 @@ export abstract class CoreRenderer {
    * on the next render call.
    */
   invalidateQuadBuffer?(): void;
+
+  /**
+   * Probe the backend for a GPU out-of-memory condition since the last call.
+   * Returns `true` when an out-of-memory was seen. Backends that cannot detect
+   * this (e.g. Canvas2D) return `false`.
+   *
+   * @remarks
+   * Called once per frame by the Stage. Backends where the probe is expensive
+   * (a CPU/GPU sync, e.g. WebGL `gl.getError()`) rely on this once-per-frame
+   * cadence rather than checking per draw/upload.
+   */
+  abstract checkForOutOfMemory(): boolean;
 }

package/src/core/renderers/CoreShaderNode.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect, vi } from 'vitest';
+import { CoreShaderNode } from './CoreShaderNode.js';
+import type { Stage } from '../Stage.js';
+import type { CoreShaderType } from './CoreShaderNode.js';
+
+const makeNode = (mutate: ReturnType<typeof vi.fn>) => {
+  const stage = {
+    shManager: { mutateShaderValueUsage: mutate },
+  } as unknown as Stage;
+  return new CoreShaderNode(
+    'test',
+    { time: undefined } as CoreShaderType,
+    stage,
+  );
+};
+
+describe('CoreShaderNode.detachNode', () => {
+  it('releases the held value-cache key so idle cleanup can evict it', () => {
+    const mutate = vi.fn();
+    const node = makeNode(mutate);
+    node.valueKey = 'color:1;node-width:10node-height:10';
+
+    node.detachNode();
+
+    expect(mutate).toHaveBeenCalledTimes(1);
+    expect(mutate).toHaveBeenCalledWith(
+      'color:1;node-width:10node-height:10',
+      -1,
+    );
+    // Key is cleared so a double-detach can't decrement twice.
+    expect(node.valueKey).toBe('');
+  });
+
+  it('is a no-op when no value key is held', () => {
+    const mutate = vi.fn();
+    const node = makeNode(mutate);
+
+    node.detachNode();
+
+    expect(mutate).not.toHaveBeenCalled();
+  });
+
+  it('does not double-decrement on repeated detach', () => {
+    const mutate = vi.fn();
+    const node = makeNode(mutate);
+    node.valueKey = 'k';
+
+    node.detachNode();
+    node.detachNode();
+
+    expect(mutate).toHaveBeenCalledTimes(1);
+  });
+});

package/src/core/renderers/CoreShaderNode.ts

@@ -96,6 +96,12 @@ export class CoreShaderNode<Props extends object = Record<string, unknown>> {
   protected node: CoreNode | null = null;
   readonly time: CoreShaderType['time'] = undefined;
   update: (() => void) | undefined = undefined;
+  /**
+   * The shader-value cache key currently held by this node (set by the
+   * subclass `update()` after the most recent successful value resolution).
+   * Tracked on the base so {@link detachNode} can release it on teardown.
+   */
+  valueKey = '';
   private _valueKeyCache = '';
   private _valueKeyDirty = true;
   private _lastW = 0;
@@ -162,6 +168,23 @@ export class CoreShaderNode<Props extends object = Record<string, unknown>> {
     this.node = node;
   }
 
+  /**
+   * Release this node's currently-held shader-value cache entry so the shader
+   * manager's idle `cleanup()` can reclaim it, and detach from the owning node.
+   *
+   * Called from {@link CoreNode.destroy}. Mirrors the `prevKey` release done on
+   * every value-key change in the subclass `update()`; without it a destroyed
+   * node's last value-cache entry stays pinned at usage >= 1 forever and can
+   * never be evicted.
+   */
+  detachNode() {
+    if (this.valueKey.length > 0) {
+      this.stage.shManager.mutateShaderValueUsage(this.valueKey, -1);
+      this.valueKey = '';
+    }
+    this.node = null;
+  }
+
   createValueKey() {
     if (
       this._valueKeyDirty === false &&

package/src/core/renderers/canvas/CanvasRenderer.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it, vi } from 'vitest';
+import { CanvasRenderer } from './CanvasRenderer.js';
+import { TextureType } from '../../textures/Texture.js';
+
+describe('CanvasRenderer.renderContext', () => {
+  it('skips drawing when canvas texture image is undefined', () => {
+    const drawImage = vi.fn();
+
+    const renderer = Object.create(CanvasRenderer.prototype) as CanvasRenderer;
+    (renderer as any).context = {
+      drawImage,
+      globalAlpha: 1,
+    };
+
+    const node = {
+      premultipliedColorTl: 0xffffffff,
+      globalTransform: { tx: 10, ty: 20 },
+      props: { w: 100, h: 50 },
+      worldAlpha: 1,
+      textureCoords: { x1: 0, y1: 0, x2: 1, y2: 1 },
+    } as any;
+
+    const texture = {
+      type: TextureType.image,
+      ctxTexture: {
+        getImage: () => undefined,
+      },
+    } as any;
+
+    expect(() => renderer.renderContext(node, texture)).not.toThrow();
+    expect(drawImage).not.toHaveBeenCalled();
+    expect((renderer as any).context.globalAlpha).toBe(1);
+  });
+});

package/src/core/renderers/canvas/CanvasRenderer.ts

@@ -63,7 +63,19 @@ export class CanvasRenderer extends CoreRenderer {
     }
 
     const hasTransform = ta !== 1;
-    const hasClipping = clippingRect.w !== 0 && clippingRect.h !== 0;
+    const clippingValid = clippingRect.valid === true;
+
+    // If the clipping rect is valid but zero-area, the node is fully clipped — skip rendering
+    if (
+      clippingValid === true &&
+      clippingRect.w === 0 &&
+      clippingRect.h === 0
+    ) {
+      return;
+    }
+
+    const hasClipping =
+      clippingValid === true && clippingRect.w !== 0 && clippingRect.h !== 0;
     const shader = node.props.shader;
     const hasShader = shader !== null;
 
@@ -124,7 +136,7 @@ export class CanvasRenderer extends CoreRenderer {
 
     if (textureType !== TextureType.color) {
       const tintColor = parseColor(color);
-      let image: ImageBitmap | HTMLCanvasElement | HTMLImageElement;
+      let image: ImageBitmap | HTMLCanvasElement | HTMLImageElement | null;
 
       if (textureType === TextureType.subTexture) {
         image = (
@@ -134,12 +146,29 @@ export class CanvasRenderer extends CoreRenderer {
         image = (texture.ctxTexture as CanvasTexture).getImage(tintColor);
       }
 
+      // The texture can disappear while an async load/fetch is racing (e.g. 404);
+      // skip drawing this frame instead of dereferencing an invalid image object.
+      if (image === null || image === undefined) {
+        return;
+      }
+
+      const imageWidth = image.width;
+      const imageHeight = image.height;
+      if (
+        typeof imageWidth !== 'number' ||
+        typeof imageHeight !== 'number' ||
+        imageWidth <= 0 ||
+        imageHeight <= 0
+      ) {
+        return;
+      }
+
       this.context.globalAlpha = tintColor.a ?? node.worldAlpha;
 
       const txCoords = node.textureCoords;
       if (txCoords) {
-        const ix = image.width;
-        const iy = image.height;
+        const ix = imageWidth;
+        const iy = imageHeight;
 
         let sx = txCoords.x1 * ix;
         let sy = txCoords.y1 * iy;
@@ -264,6 +293,11 @@ export class CanvasRenderer extends CoreRenderer {
     return null;
   }
 
+  // Canvas2D has no GPU out-of-memory signal to probe.
+  checkForOutOfMemory(): boolean {
+    return false;
+  }
+
   /**
    * Updates the clear color of the canvas renderer.
    *

package/src/core/renderers/canvas/CanvasShaderNode.ts

@@ -26,7 +26,6 @@ export class CanvasShaderNode<
 > extends CoreShaderNode<Props> {
   private updater: ((node: CoreNode, props?: Props) => void) | undefined =
     undefined;
-  private valueKey: string = '';
   computed: Partial<Computed> = {};
   applySNR: boolean;
   render: CanvasShaderType<Props>['render'];

package/src/core/renderers/canvas/CanvasTexture.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+import { CanvasTexture } from './CanvasTexture.js';
+
+describe('CanvasTexture.load', () => {
+  it('fails gracefully when textureData.data is null', async () => {
+    const textureSource = {
+      textureData: { data: null },
+      state: 'initial',
+      dimensions: null,
+      setState(nextState: string) {
+        this.state = nextState;
+      },
+      freeTextureData() {
+        // no-op
+      },
+    } as any;
+
+    const memManager = {
+      setTextureMemUse() {
+        // no-op
+      },
+    } as any;
+
+    const ctxTexture = new CanvasTexture(memManager, textureSource);
+
+    await expect(ctxTexture.load()).rejects.toThrow(
+      'CanvasTexture: Texture data is null',
+    );
+    expect(textureSource.state).toBe('failed');
+  });
+});

package/src/core/renderers/canvas/CanvasTexture.ts

@@ -2,6 +2,7 @@ import type { Dimensions } from '../../../common/CommonTypes.js';
 import { assertTruthy } from '../../../utils.js';
 import { formatRgba, type IParsedColor } from '../../lib/colorParser.js';
 import { CoreContextTexture } from '../CoreContextTexture.js';
+import type { Texture } from '../../textures/Texture.js';
 
 export class CanvasTexture extends CoreContextTexture {
   protected image:
@@ -17,10 +18,23 @@ export class CanvasTexture extends CoreContextTexture {
     | undefined;
 
   async load(): Promise<void> {
+    // Capture textureData synchronously before any await - a pending
+    // freeTextureDataTask microtask could null textureSource.textureData
+    // during the first async suspension, causing onLoadRequest to fail.
+    const textureData = this.textureSource.textureData;
+    assertTruthy(textureData?.data, 'Texture data is null before load');
+
     this.textureSource.setState('loading');
 
     try {
-      const size = await this.onLoadRequest();
+      const size = await this.onLoadRequest(textureData.data);
+
+      // Guard against the texture being freed while the load was in flight
+      if (this.textureSource.state === 'freed') {
+        this.image = undefined;
+        return;
+      }
+
       this.textureSource.setState('loaded', size);
       this.textureSource.freeTextureData();
       this.updateMemSize();
@@ -63,9 +77,11 @@ export class CanvasTexture extends CoreContextTexture {
 
   getImage(
     color: IParsedColor,
-  ): ImageBitmap | HTMLCanvasElement | HTMLImageElement {
+  ): ImageBitmap | HTMLCanvasElement | HTMLImageElement | null {
     const image = this.image;
-    assertTruthy(image, 'Attempt to get unloaded image texture');
+    if (image === undefined) {
+      return null;
+    }
 
     if (color.isWhite) {
       if (this.tintCache) {
@@ -114,9 +130,21 @@ export class CanvasTexture extends CoreContextTexture {
     return canvas;
   }
 
-  private async onLoadRequest(): Promise<Dimensions> {
-    assertTruthy(this.textureSource?.textureData?.data, 'Texture data is null');
-    const { data } = this.textureSource.textureData;
+  private async onLoadRequest(
+    data: NonNullable<Texture['textureData']>['data'],
+  ): Promise<Dimensions> {
+    if (data === null) {
+      throw new Error('CanvasTexture: Texture data is null');
+    }
+
+    // CompressedData objects (KTX, PVR, ASTC) carry GPU-format mipmap buffers
+    // that cannot be decoded by Canvas2D. Reject explicitly rather than falling
+    // through silently and leaving this.image unassigned.
+    if (typeof data === 'object' && 'mipmaps' in data) {
+      throw new Error(
+        'CanvasTexture: Compressed texture data is not supported in Canvas2D render mode',
+      );
+    }
 
     // TODO: canvas from text renderer should be able to provide the canvas directly
     // instead of having to re-draw it into a new canvas...
@@ -125,7 +153,7 @@ export class CanvasTexture extends CoreContextTexture {
       canvas.width = data.width;
       canvas.height = data.height;
       const ctx = canvas.getContext('2d');
-      if (ctx) ctx.putImageData(data, 0, 0);
+      if (ctx !== null) ctx.putImageData(data, 0, 0);
       this.image = canvas;
       return { w: data.width, h: data.height };
     } else if (

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

@@ -42,6 +42,15 @@ import type { Dimensions } from '../../../common/CommonTypes.js';
 
 export type WebGlRendererOptions = CoreRendererOptions;
 
+const GL_OUT_OF_MEMORY = 0x0505;
+
+/**
+ * Upper bound on how many queued GL errors we drain per frame in
+ * {@link WebGlRenderer.checkForOutOfMemory}. Keeps the per-frame `getError()`
+ * sync cost fixed even if the error queue is unexpectedly deep.
+ */
+const MAX_DRAINED_GL_ERRORS = 8;
+
 interface CoreWebGlSystem {
   parameters: CoreWebGlParameters;
   extensions: CoreWebGlExtensions;
@@ -1283,6 +1292,33 @@ export class WebGlRenderer extends CoreRenderer {
     return bufferInfo;
   }
 
+  /**
+   * Drain the GL error queue once and report whether a GL_OUT_OF_MEMORY was
+   * seen since the last call.
+   *
+   * @remarks
+   * `gl.getError()` forces a CPU↔GPU sync, so this is deliberately invoked at
+   * most once per frame by the Stage rather than after each texture upload.
+   * `getError()` returns one error at a time, so we drain a bounded number of
+   * queued errors to ensure a non-OOM error ahead of the OOM doesn't mask it
+   * for this frame. Non-OOM errors are ignored here (the renderer otherwise
+   * only inspects them in development builds).
+   */
+  override checkForOutOfMemory(): boolean {
+    const glw = this.glw;
+    let outOfMemory = false;
+    for (let i = 0; i < MAX_DRAINED_GL_ERRORS; i++) {
+      const error = glw.getError();
+      if (error === 0) {
+        break;
+      }
+      if (error === GL_OUT_OF_MEMORY) {
+        outOfMemory = true;
+      }
+    }
+    return outOfMemory;
+  }
+
   getDefaultShaderNode(): WebGlShaderNode {
     if (this.defaultShaderNode !== null) {
       return this.defaultShaderNode as WebGlShaderNode;

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

@@ -53,7 +53,6 @@ export class WebGlShaderNode<
   readonly program: WebGlShaderProgram;
   private updater: ((node: CoreNode, props?: Props) => void) | undefined =
     undefined;
-  private valueKey: string = '';
   uniforms: UniformCollection = {
     single: {},
     vec2: {},

package/src/core/text-rendering/CanvasTextRenderer.ts

@@ -40,10 +40,22 @@ const layoutCache = new Map<
   }
 >();
 
+// Upper bound on layoutCache entries, enforced on idle via `cleanup`.
+// Overridden from stage options in `init`. Note: the Canvas path does not
+// currently populate `layoutCache`, so this is effectively inert today and
+// exists to keep the eviction policy uniform with the SDF backend should
+// Canvas layout caching be wired up later.
+let maxLayoutCacheSize = 250;
+
 // Initialize the Text Renderer
 const init = (stage: Stage): void => {
   const dpr = stage.options.devicePhysicalPixelRatio;
 
+  const configuredCacheSize = stage.options.textLayoutCacheSize;
+  if (configuredCacheSize !== undefined) {
+    maxLayoutCacheSize = configuredCacheSize;
+  }
+
   // Drawing canvas and context
   canvas = stage.platform.createCanvas() as HTMLCanvasElement | OffscreenCanvas;
   context = canvas.getContext('2d', { willReadFrequently: true }) as
@@ -224,6 +236,19 @@ const clearLayoutCache = (): void => {
   layoutCache.clear();
 };
 
+/**
+ * Trim the layout cache back down to `maxLayoutCacheSize`, evicting the
+ * least-recently-used entries first. Called when the stage goes idle. The
+ * Canvas path does not currently populate `layoutCache`, so this is a no-op in
+ * practice today; it mirrors the SDF backend's eviction policy.
+ */
+const cleanup = (): void => {
+  while (layoutCache.size > maxLayoutCacheSize) {
+    const oldest = layoutCache.keys().next().value as string;
+    layoutCache.delete(oldest);
+  }
+};
+
 /**
  * Add quads for rendering (Canvas doesn't use quads)
  */
@@ -252,6 +277,7 @@ const CanvasTextRenderer = {
   renderQuads,
   init,
   clearLayoutCache,
+  cleanup,
 };
 
 export default CanvasTextRenderer;

package/src/core/text-rendering/SdfFontHandler.ts

@@ -12,6 +12,7 @@ import { UpdateType } from '../CoreNode.js';
 import { hasZeroWidthSpace } from './Utils.js';
 import { normalizeFontMetrics } from './TextLayoutEngine.js';
 import { isProductionEnvironment } from '../../utils.js';
+import type { TextureError } from '../TextureError.js';
 
 /**
  * SDF Font Data structure matching msdf-bmfont-xml output
@@ -397,7 +398,11 @@ export const loadFont = (
         resolve();
       });
 
-      atlasTexture.on('failed', (error: Error) => {
+      // EventEmitter invokes listeners as (target, data), so the error payload
+      // is the SECOND argument. The first arg is the Texture that emitted the
+      // event. Reading it as the only param (the previous behavior) rejected
+      // and logged the Texture instead of the actual TextureError.
+      atlasTexture.on('failed', (_target, error: TextureError) => {
         // Cleanup on error
         fontLoadPromises.delete(fontFamily);
         if (fontCache[fontFamily]) {