@solidtv/renderer 1.2.10 → 1.3.1

package/src/core/TextureMemoryManager.ts

@@ -342,10 +342,36 @@ export class TextureMemoryManager {
       }, 1000);
     }
 
-    // If the threshold is 0, we disable the memory manager by replacing the
-    // setTextureMemUse method with a no-op function.
+    // If the threshold is 0, we disable memory tracking/cleanup by replacing the
+    // setTextureMemUse method with a no-op function. Note this only disables LRU
+    // tracking — GPU out-of-memory detection still runs (see handleOutOfMemory).
     if (criticalThreshold === 0) {
       this.setTextureMemUse = () => {};
     }
   }
+
+  /**
+   * React to a real GPU out-of-memory reported by the renderer.
+   *
+   * @remarks
+   * WebGL never exposes the VRAM budget up front, so the only certain signal is
+   * a `GL_OUT_OF_MEMORY` after the fact. When it fires we queue an `outOfMemory`
+   * frame event carrying the estimated memory in use and the critical threshold
+   * in effect — the estimate is a *measured ceiling* (the real budget is at or
+   * below it). What to do about it (lower the threshold, persist, reload) is
+   * application policy, not the renderer's; see the `outOfMemory` event docs on
+   * the public Renderer for the recommended integration.
+   *
+   * The engine also requests an immediate cleanup as a best-effort mitigation
+   * to free non-renderable textures before the app reacts.
+   */
+  handleOutOfMemory(): void {
+    this.stage.queueFrameEvent('outOfMemory', {
+      memUsed: this.memUsed,
+      criticalThreshold: this.criticalThreshold,
+    });
+
+    // Free whatever non-renderable textures we can right now.
+    this.criticalCleanupRequested = true;
+  }
 }

package/src/core/lib/ImageWorker.ts

@@ -43,12 +43,14 @@ function createImageWorker() {
     options: {
       supportsOptionsCreateImageBitmap: boolean;
       supportsFullCreateImageBitmap: boolean;
+      premultiplyAlphaHonored: boolean;
     },
   ): Promise<getImageReturn> {
     return new Promise(function (resolve, reject) {
       var supportsOptionsCreateImageBitmap =
         options.supportsOptionsCreateImageBitmap;
       var supportsFullCreateImageBitmap = options.supportsFullCreateImageBitmap;
+      var premultiplyAlphaHonored = options.premultiplyAlphaHonored;
       var xhr = new XMLHttpRequest();
       xhr.open('GET', src, true);
       xhr.responseType = 'blob';
@@ -71,6 +73,17 @@ function createImageWorker() {
             ? premultiplyAlpha
             : hasAlphaChannel(blob.type);
 
+        // When the device ignores the createImageBitmap premultiply option,
+        // create a straight ('none') bitmap and let WebGL premultiply on
+        // upload. `premultiplyAlpha` in the resolved value means "WebGL should
+        // premultiply this source on upload".
+        var useGlPremultiply =
+          withAlphaChannel === true && premultiplyAlphaHonored === false;
+        var bitmapMode: 'premultiply' | 'none' =
+          withAlphaChannel === true && useGlPremultiply === false
+            ? 'premultiply'
+            : 'none';
+
         // createImageBitmap with crop and options
         if (
           supportsFullCreateImageBitmap === true &&
@@ -78,12 +91,12 @@ function createImageWorker() {
           height !== null
         ) {
           createImageBitmap(blob, x || 0, y || 0, width, height, {
-            premultiplyAlpha: withAlphaChannel ? 'premultiply' : 'none',
+            premultiplyAlpha: bitmapMode,
             colorSpaceConversion: 'none',
             imageOrientation: 'none',
           })
             .then(function (data) {
-              resolve({ data: data, premultiplyAlpha: withAlphaChannel });
+              resolve({ data: data, premultiplyAlpha: useGlPremultiply });
             })
             .catch(function (error) {
               reject(error);
@@ -94,22 +107,23 @@ function createImageWorker() {
           supportsFullCreateImageBitmap === false
         ) {
           // Fallback for browsers that do not support createImageBitmap with options
-          // this is supported for Chrome v50 to v52/54 that doesn't support options
+          // this is supported for Chrome v50 to v52/54 that doesn't support options.
+          // The browser default premultiplies, so WebGL must not premultiply again.
           createImageBitmap(blob)
             .then(function (data) {
-              resolve({ data: data, premultiplyAlpha: withAlphaChannel });
+              resolve({ data: data, premultiplyAlpha: false });
             })
             .catch(function (error) {
               reject(error);
             });
         } else {
           createImageBitmap(blob, {
-            premultiplyAlpha: withAlphaChannel ? 'premultiply' : 'none',
+            premultiplyAlpha: bitmapMode,
             colorSpaceConversion: 'none',
             imageOrientation: 'none',
           })
             .then(function (data) {
-              resolve({ data: data, premultiplyAlpha: withAlphaChannel });
+              resolve({ data: data, premultiplyAlpha: useGlPremultiply });
             })
             .catch(function (error) {
               reject(error);
@@ -139,10 +153,13 @@ function createImageWorker() {
     // these will be set to true if the browser supports the createImageBitmap options or full
     var supportsOptionsCreateImageBitmap = false;
     var supportsFullCreateImageBitmap = false;
+    // set to false when the device is known to ignore the premultiply option
+    var premultiplyAlphaHonored = true;
 
     getImage(src, premultiplyAlpha, x, y, width, height, {
       supportsOptionsCreateImageBitmap,
       supportsFullCreateImageBitmap,
+      premultiplyAlphaHonored,
     })
       .then(function (data) {
         // @ts-ignore ts has wrong postMessage signature
@@ -240,6 +257,13 @@ export class ImageWorkerManager {
       );
     }
 
+    if (createImageBitmapSupport.premultiplyHonored === false) {
+      workerCode = workerCode.replace(
+        'var premultiplyAlphaHonored = true;',
+        'var premultiplyAlphaHonored = false;',
+      );
+    }
+
     workerCode = workerCode.replace('"use strict";', '');
     const blob: Blob = new Blob([workerCode], {
       type: 'application/javascript',

package/src/core/lib/textureSvg.ts

@@ -91,8 +91,11 @@ export const loadSvg = async (
     }
   }
 
+  // getImageData returns straight (un-premultiplied) pixels, so WebGL must
+  // premultiply this source on upload (unlike the ImageBitmap path above,
+  // where the canvas is already premultiplied by createImageBitmap's default).
   return {
     data: ctx.getImageData(0, 0, physW, physH),
-    premultiplyAlpha: false,
+    premultiplyAlpha: true,
   };
 };

package/src/core/lib/validateImageBitmap.test.ts

@@ -0,0 +1,119 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { detectPremultiplyAlphaHonored } from './validateImageBitmap.js';
+import type { Platform } from '../platforms/Platform.js';
+
+/**
+ * Minimal stand-in for the WebGL constants/methods the probe touches. The probe
+ * uploads a known straight pixel, reads it back, and infers whether
+ * createImageBitmap premultiplied it. `readbackRed` is what readPixels returns
+ * for the red channel: ~128 = premultiplied (honored), ~255 = straight (ignored).
+ */
+function createFakeGl(readbackRed: number, framebufferComplete = true) {
+  return {
+    TEXTURE_2D: 0x0de1,
+    UNPACK_PREMULTIPLY_ALPHA_WEBGL: 0x9241,
+    UNPACK_FLIP_Y_WEBGL: 0x9240,
+    RGBA: 0x1908,
+    UNSIGNED_BYTE: 0x1401,
+    FRAMEBUFFER: 0x8d40,
+    COLOR_ATTACHMENT0: 0x8ce0,
+    FRAMEBUFFER_COMPLETE: 0x8cd5,
+    createTexture: vi.fn(() => ({})),
+    bindTexture: vi.fn(),
+    pixelStorei: vi.fn(),
+    texImage2D: vi.fn(),
+    createFramebuffer: vi.fn(() => ({})),
+    bindFramebuffer: vi.fn(),
+    framebufferTexture2D: vi.fn(),
+    checkFramebufferStatus: vi.fn(() => (framebufferComplete ? 0x8cd5 : 0)),
+    readPixels: vi.fn(
+      (
+        _x: number,
+        _y: number,
+        _w: number,
+        _h: number,
+        _format: number,
+        _type: number,
+        px: Uint8Array,
+      ) => {
+        px[0] = readbackRed;
+        px[1] = 0;
+        px[2] = 0;
+        px[3] = 128;
+      },
+    ),
+    deleteFramebuffer: vi.fn(),
+    deleteTexture: vi.fn(),
+  };
+}
+
+function createPlatform(gl: object | null): Platform {
+  const close = vi.fn();
+  return {
+    createImageBitmap: vi.fn(() => Promise.resolve({ close })),
+    createCanvas: vi.fn(() => ({
+      width: 0,
+      height: 0,
+      getContext: vi.fn((type: string) => (type === 'webgl' ? gl : null)),
+    })),
+  } as unknown as Platform;
+}
+
+describe('detectPremultiplyAlphaHonored', () => {
+  beforeEach(() => {
+    // node test env has no ImageData global; the probe constructs one.
+    (globalThis as unknown as { ImageData: unknown }).ImageData = class {
+      data: Uint8ClampedArray;
+      width: number;
+      height: number;
+      constructor(data: Uint8ClampedArray, width: number, height: number) {
+        this.data = data;
+        this.width = width;
+        this.height = height;
+      }
+    };
+  });
+
+  afterEach(() => {
+    delete (globalThis as unknown as { ImageData?: unknown }).ImageData;
+  });
+
+  it('returns true when the bitmap reads back premultiplied (~128)', async () => {
+    const platform = createPlatform(createFakeGl(128));
+    expect(await detectPremultiplyAlphaHonored(platform)).toBe(true);
+  });
+
+  it('returns false when the bitmap reads back straight (~255)', async () => {
+    const platform = createPlatform(createFakeGl(255));
+    expect(await detectPremultiplyAlphaHonored(platform)).toBe(false);
+  });
+
+  it('returns null when createImageBitmap throws', async () => {
+    const platform = {
+      createImageBitmap: vi.fn(() => Promise.reject(new Error('unsupported'))),
+      createCanvas: vi.fn(),
+    } as unknown as Platform;
+    expect(await detectPremultiplyAlphaHonored(platform)).toBe(null);
+  });
+
+  it('returns null when no WebGL context is available', async () => {
+    const platform = createPlatform(null);
+    expect(await detectPremultiplyAlphaHonored(platform)).toBe(null);
+  });
+
+  it('returns null when the framebuffer is incomplete', async () => {
+    const platform = createPlatform(createFakeGl(128, false));
+    expect(await detectPremultiplyAlphaHonored(platform)).toBe(null);
+  });
+
+  it('disables GL-side premultiply on the probe upload', async () => {
+    const gl = createFakeGl(128);
+    await detectPremultiplyAlphaHonored(createPlatform(gl));
+    // The probe must observe the bitmap's own alpha state, so GL premultiply
+    // has to be off during the readback upload.
+    expect(gl.pixelStorei).toHaveBeenCalledWith(
+      gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL,
+      false,
+    );
+  });
+});

package/src/core/lib/validateImageBitmap.ts

@@ -4,6 +4,11 @@ export interface CreateImageBitmapSupport {
   basic: boolean; // Supports createImageBitmap(image)
   options: boolean; // Supports createImageBitmap(image, options)
   full: boolean; // Supports createImageBitmap(image, sx, sy, sw, sh, options)
+  // Whether `premultiplyAlpha: 'premultiply'` is actually HONORED (not just
+  // accepted without throwing). null = could not determine. Older Safari/WebKit
+  // accepts the option but ignores it, returning straight alpha — the source of
+  // the edge-ghosting bug on those devices.
+  premultiplyHonored: boolean | null;
 }
 
 export async function validateCreateImageBitmap(
@@ -47,6 +52,7 @@ export async function validateCreateImageBitmap(
     basic: false,
     options: false,
     full: false,
+    premultiplyHonored: null,
   };
 
   // Test basic createImageBitmap support
@@ -83,5 +89,88 @@ export async function validateCreateImageBitmap(
     /* ignore */
   }
 
+  // premultiplyHonored is resolved separately by the caller (it may be a
+  // forced override or an explicit opt-in to the probe), so it is left as its
+  // default (null) here.
   return support;
 }
+
+/**
+ * Determine whether `createImageBitmap(..., { premultiplyAlpha: 'premultiply' })`
+ * is actually honored by this browser.
+ *
+ * Strategy: feed a known straight-alpha pixel (255, 0, 0, 128) through
+ * createImageBitmap with 'premultiply', upload it to a WebGL texture with
+ * GL-side premultiply DISABLED (so we observe the bitmap's own state), then
+ * read the raw texel back via a framebuffer.
+ *
+ *  - honored   -> red comes back premultiplied (~128)
+ *  - ignored   -> red comes back straight (~255)  [older Safari/WebKit]
+ *
+ * @returns true if honored, false if ignored, null if it couldn't be measured
+ * (no WebGL, createImageBitmap from ImageData unsupported, framebuffer
+ * incomplete, etc.) — caller should treat null as "unknown".
+ */
+export async function detectPremultiplyAlphaHonored(
+  platform: Platform,
+): Promise<boolean | null> {
+  let bitmap: ImageBitmap;
+  try {
+    // Straight (un-premultiplied) RGBA. ImageData is straight-alpha by spec.
+    const imageData = new ImageData(
+      new Uint8ClampedArray([255, 0, 0, 128]),
+      1,
+      1,
+    );
+    bitmap = await platform.createImageBitmap(imageData, {
+      premultiplyAlpha: 'premultiply',
+      colorSpaceConversion: 'none',
+      imageOrientation: 'none',
+    });
+  } catch (e) {
+    return null;
+  }
+
+  const canvas = platform.createCanvas();
+  canvas.width = 1;
+  canvas.height = 1;
+  const gl = (canvas.getContext('webgl') ||
+    canvas.getContext('experimental-webgl')) as WebGLRenderingContext | null;
+  if (gl === null) {
+    bitmap.close?.();
+    return null;
+  }
+
+  const tex = gl.createTexture();
+  gl.bindTexture(gl.TEXTURE_2D, tex);
+  // Critical: do NOT let GL premultiply. We want to observe whatever state the
+  // bitmap itself is in.
+  gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
+  gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
+  gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, bitmap);
+
+  const fb = gl.createFramebuffer();
+  gl.bindFramebuffer(gl.FRAMEBUFFER, fb);
+  gl.framebufferTexture2D(
+    gl.FRAMEBUFFER,
+    gl.COLOR_ATTACHMENT0,
+    gl.TEXTURE_2D,
+    tex,
+    0,
+  );
+
+  let result: boolean | null = null;
+  if (gl.checkFramebufferStatus(gl.FRAMEBUFFER) === gl.FRAMEBUFFER_COMPLETE) {
+    const px = new Uint8Array(4);
+    gl.readPixels(0, 0, 1, 1, gl.RGBA, gl.UNSIGNED_BYTE, px);
+    // Straight red reads ~255; premultiplied red reads ~128. Split at the
+    // midpoint to tolerate rounding/colorspace drift.
+    result = px[0]! < 192;
+  }
+
+  gl.deleteFramebuffer(fb);
+  gl.deleteTexture(tex);
+  bitmap.close?.();
+
+  return result;
+}

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

@@ -0,0 +1,78 @@
+/**
+ * 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() },
+    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,6 +77,14 @@ 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.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/canvas/CanvasRenderer.ts

@@ -264,6 +264,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/webgl/WebGlCtxTexture.ts

@@ -188,9 +188,13 @@ export class WebGlCtxTexture extends CoreContextTexture {
       w = tdata.width;
       h = tdata.height;
       glw.bindTexture(this._nativeCtxTexture);
+      // `premultiplyAlpha` carries the source's GL-upload intent: true when the
+      // source pixels are straight and WebGL must premultiply (e.g. a straight
+      // bitmap produced when the device ignores the createImageBitmap
+      // premultiply option), false when the source is already premultiplied.
       glw.pixelStorei(
         glw.UNPACK_PREMULTIPLY_ALPHA_WEBGL,
-        isImageBitmap ? false : !!textureData.premultiplyAlpha,
+        !!textureData.premultiplyAlpha,
       );
 
       glw.texImage2D(0, format, format, glw.UNSIGNED_BYTE, tdata);

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/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]) {