@solidtv/renderer 1.2.10 → 1.3.1

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

@@ -0,0 +1,112 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { loadFont } from '../SdfFontHandler.js';
+import { EventEmitter } from '../../../common/EventEmitter.js';
+import { TextureError, TextureErrorCode } from '../../TextureError.js';
+import type { Stage } from '../../Stage.js';
+
+// Minimal XHR stand-in: synchronously delivers valid SDF font JSON so loadFont
+// proceeds to create the atlas texture and attach its event listeners.
+class FakeXHR {
+  status = 200;
+  response: unknown = null;
+  responseType = '';
+  onload: (() => void) | null = null;
+  onerror: (() => void) | null = null;
+  open(): void {}
+  send(): void {
+    this.response = { chars: [{}] };
+    if (this.onload !== null) {
+      this.onload();
+    }
+  }
+}
+
+// A texture is just an EventEmitter to loadFont; stub the few props it reads.
+function makeFakeTexture() {
+  const tex = new EventEmitter() as unknown as EventEmitter & {
+    state: string;
+    preventCleanup: boolean;
+    setRenderableOwner: (owner: string, val: boolean) => void;
+  };
+  tex.state = 'loading'; // not 'loaded' -> goes through the listener path
+  tex.preventCleanup = false;
+  tex.setRenderableOwner = () => {};
+  return tex;
+}
+
+// Drain microtasks + one macrotask so the async loader reaches listener setup.
+const flush = (): Promise<void> => new Promise((r) => setTimeout(r, 0));
+
+describe('SdfFontHandler loadFont — failed event argument', () => {
+  let errSpy: ReturnType<typeof vi.spyOn>;
+  let originalXHR: unknown;
+
+  beforeEach(() => {
+    errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    originalXHR = (globalThis as unknown as { XMLHttpRequest: unknown })
+      .XMLHttpRequest;
+    (globalThis as unknown as { XMLHttpRequest: unknown }).XMLHttpRequest =
+      FakeXHR;
+  });
+
+  afterEach(() => {
+    errSpy.mockRestore();
+    (globalThis as unknown as { XMLHttpRequest: unknown }).XMLHttpRequest =
+      originalXHR;
+  });
+
+  it('rejects with the TextureError (second emit arg), not the emitting texture', async () => {
+    const tex = makeFakeTexture();
+    const stage = {
+      txManager: { createTexture: () => tex },
+    } as unknown as Stage;
+
+    const promise = loadFont(stage, {
+      fontFamily: 'TestSdfFailFont',
+      atlasUrl: 'atlas.png',
+      atlasDataUrl: 'atlas.json',
+    } as Parameters<typeof loadFont>[1]);
+
+    await flush();
+
+    const error = new TextureError(
+      TextureErrorCode.TEXTURE_UPLOAD_FAILED,
+      'boom',
+    );
+
+    // Attach the rejection assertion before emitting so the handler is ready.
+    const assertion = expect(promise).rejects.toBe(error);
+
+    // EventEmitter calls listeners as (target, data) -> (tex, error).
+    tex.emit('failed', error);
+
+    await assertion;
+  });
+
+  it('logs the error, not the texture, on failure', async () => {
+    const tex = makeFakeTexture();
+    const stage = {
+      txManager: { createTexture: () => tex },
+    } as unknown as Stage;
+
+    const promise = loadFont(stage, {
+      fontFamily: 'TestSdfFailFontLog',
+      atlasUrl: 'atlas.png',
+      atlasDataUrl: 'atlas.json',
+    } as Parameters<typeof loadFont>[1]);
+
+    await flush();
+
+    const error = new TextureError(
+      TextureErrorCode.TEXTURE_UPLOAD_FAILED,
+      'boom',
+    );
+    const rejected = promise.catch(() => {});
+    tex.emit('failed', error);
+    await rejected;
+
+    const lastCall = errSpy.mock.calls[errSpy.mock.calls.length - 1]!;
+    expect(lastCall[1]).toBe(error);
+    expect(lastCall[1]).not.toBe(tex);
+  });
+});

package/src/core/textures/ImageTexture.ts

@@ -192,6 +192,18 @@ export class ImageTexture extends Texture {
     const hasAlphaChannel = premultiplyAlpha ?? blob.type.includes('image/png');
     const imageBitmapSupported = this.txManager.imageBitmapSupported;
 
+    // When the device does NOT honor the createImageBitmap premultiply option
+    // (e.g. older Safari), request a straight ('none') bitmap and let WebGL
+    // premultiply on upload instead. `premultiplyAlpha` in the returned
+    // TextureData means "WebGL should premultiply this source on upload".
+    const useGlPremultiply =
+      hasAlphaChannel === true &&
+      imageBitmapSupported.premultiplyHonored === false;
+    const bitmapMode: 'premultiply' | 'none' =
+      hasAlphaChannel === true && useGlPremultiply === false
+        ? 'premultiply'
+        : 'none';
+
     if (imageBitmapSupported.full === true && sw !== null && sh !== null) {
       // createImageBitmap with crop
       const bitmap = await this.platform.createImageBitmap(
@@ -201,28 +213,29 @@ export class ImageTexture extends Texture {
         sw,
         sh,
         {
-          premultiplyAlpha: hasAlphaChannel ? 'premultiply' : 'none',
+          premultiplyAlpha: bitmapMode,
           colorSpaceConversion: 'none',
           imageOrientation: 'none',
         },
       );
-      return { data: bitmap, premultiplyAlpha: hasAlphaChannel };
+      return { data: bitmap, premultiplyAlpha: useGlPremultiply };
     } else if (imageBitmapSupported.basic === true) {
       // basic createImageBitmap without options or crop
-      // 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.
       return {
         data: await this.platform.createImageBitmap(blob),
-        premultiplyAlpha: hasAlphaChannel,
+        premultiplyAlpha: false,
       };
     }
 
     // default createImageBitmap without crop but with options
     const bitmap = await this.platform.createImageBitmap(blob, {
-      premultiplyAlpha: hasAlphaChannel ? 'premultiply' : 'none',
+      premultiplyAlpha: bitmapMode,
       colorSpaceConversion: 'none',
       imageOrientation: 'none',
     });
-    return { data: bitmap, premultiplyAlpha: hasAlphaChannel };
+    return { data: bitmap, premultiplyAlpha: useGlPremultiply };
   }
 
   async loadImage(src: string) {
@@ -274,9 +287,14 @@ export class ImageTexture extends Texture {
       };
     }
 
+    // The loader computes whether WebGL should premultiply this source on
+    // upload (it depends on the source type and on whether createImageBitmap
+    // honored the premultiply option). Preserve it; fall back to the prop only
+    // when the loader didn't decide.
     return {
       data: resp.data,
-      premultiplyAlpha: this.props.premultiplyAlpha ?? true,
+      premultiplyAlpha:
+        resp.premultiplyAlpha ?? this.props.premultiplyAlpha ?? true,
     };
   }
 

package/src/main-api/Renderer.ts

@@ -28,7 +28,7 @@ import { Platform } from '../core/platforms/Platform.js';
  * @category Events
  * @example
  * ```typescript
- * renderer.on('fpsUpdate', (data) => {
+ * renderer.on('fpsUpdate', (_target, data) => {
  *   console.log(`Current FPS: ${data.fps}`);
  *   if (data.contextSpyData) {
  *     console.log('WebGL calls:', data.contextSpyData);
@@ -49,7 +49,7 @@ export interface RendererMainFpsUpdateEvent {
  * @category Events
  * @example
  * ```typescript
- * renderer.on('frameTick', (data) => {
+ * renderer.on('frameTick', (_target, data) => {
  *   console.log(`Frame time: ${data.time}ms, delta: ${data.delta}ms`);
  * });
  * ```
@@ -67,7 +67,7 @@ export interface RendererMainFrameTickEvent {
  * @category Events
  * @example
  * ```typescript
- * renderer.on('renderUpdate', (data) => {
+ * renderer.on('renderUpdate', (_target, data) => {
  *   console.log(`Rendered quads: ${data.quads}, renderOps: ${data.renderOps}`);
  * });
  * ```
@@ -110,7 +110,7 @@ export interface RendererMainIdleEvent {
  * @category Events
  * @example
  * ```typescript
- * renderer.on('criticalCleanup', (data) => {
+ * renderer.on('criticalCleanup', (_target, data) => {
  *   console.log(`Memory cleanup triggered!`);
  *   console.log(`Memory used: ${data.memUsed} bytes`);
  *   console.log(`Critical threshold: ${data.criticalThreshold} bytes`);
@@ -130,7 +130,7 @@ export interface RendererMainCriticalCleanupEvent {
  * @category Events
  * @example
  * ```typescript
- * renderer.on('criticalCleanupFailed', (data) => {
+ * renderer.on('criticalCleanupFailed', (_target, data) => {
  *   console.warn(`Memory cleanup failed!`);
  *   console.log(`Memory still used: ${data.memUsed} bytes`);
  *   console.log(`Critical threshold: ${data.criticalThreshold} bytes`);
@@ -167,6 +167,90 @@ export interface RendererMainContextLostEvent {
   readonly __eventHasNoPayload?: never;
 }
 
+/**
+ * GPU Out Of Memory Event Data
+ *
+ * @remarks
+ * Fired when the renderer detects a real `GL_OUT_OF_MEMORY` from the GPU (probed
+ * once per frame). This is the only certain signal that the texture memory
+ * estimate has overshot the device's real VRAM budget. At this point a texture
+ * upload has already failed and the driver may soon drop the WebGL context, so
+ * the supported recovery is for the application to reload with a lower
+ * `criticalThreshold`.
+ *
+ * `memUsed` is the estimated texture memory in use at the moment of the failure.
+ * Because the upload failed, the real GPU budget is at or below this value — so
+ * it is a good basis for the next `criticalThreshold`.
+ *
+ * The renderer deliberately does NOT persist, reload, or change the threshold
+ * itself — that is application policy. The recommended integration is to lower
+ * the threshold, persist it, and reload:
+ *
+ * @category Events
+ * @example
+ * ```typescript
+ * // --- on startup: read the calibrated threshold before creating the renderer
+ * //
+ * // Namespace the storage key per app. On TV devices that run from the
+ * // filesystem (file://) the origin is null/opaque, so a bare key can collide
+ * // across apps — including the path keeps each app's calibration separate.
+ * const STORAGE_KEY = `myapp:criticalThreshold:${location.pathname}`;
+ *
+ * // Never let calibration drive the threshold so low the UX breaks. Pick a
+ * // floor that matches your app (here, 70% of the default budget).
+ * const DEFAULT_CRITICAL = 200e6;
+ * const MIN_THRESHOLD = Math.round(DEFAULT_CRITICAL * 0.7);
+ *
+ * function readCriticalThreshold(): number {
+ *   const raw =
+ *     typeof localStorage !== 'undefined'
+ *       ? localStorage.getItem(STORAGE_KEY)
+ *       : null;
+ *   const stored = raw !== null ? parseInt(raw, 10) : NaN;
+ *   if (Number.isNaN(stored) === false && stored > 0) {
+ *     return Math.max(stored, MIN_THRESHOLD);
+ *   }
+ *   return DEFAULT_CRITICAL;
+ * }
+ *
+ * const renderer = new RendererMain(
+ *   { textureMemory: { criticalThreshold: readCriticalThreshold() } },
+ *   'app',
+ * );
+ *
+ * // --- at runtime: react to a real GPU out-of-memory
+ * let handlingOOM = false;
+ * renderer.on('outOfMemory', (_target, { memUsed, criticalThreshold }) => {
+ *   if (handlingOOM === true) {
+ *     return; // debounce — several uploads can fail in the same burst
+ *   }
+ *   handlingOOM = true;
+ *
+ *   // The OOM proves the real budget is <= memUsed. Drop to 90% of the lower
+ *   // of (estimate, current threshold), but never below the floor.
+ *   const ceiling = Math.min(memUsed, criticalThreshold);
+ *   const next = Math.max(Math.round(ceiling * 0.9), MIN_THRESHOLD);
+ *
+ *   try {
+ *     localStorage.setItem(STORAGE_KEY, String(next));
+ *   } catch (e) {
+ *     // storage may be blocked (e.g. file:// with storage disabled); the new
+ *     // value just won't survive the reload.
+ *   }
+ *
+ *   // Reload so the renderer reinitializes with the lower budget. The engine
+ *   // does not rebuild GPU resources in place, so reload is the clean recovery.
+ *   location.reload();
+ * });
+ * ```
+ */
+export interface RendererMainOutOfMemoryEvent {
+  /** Estimated texture memory in use at the time of the failure (bytes) */
+  memUsed: number;
+  /** Critical threshold in effect at the time of the failure (bytes) */
+  criticalThreshold: number;
+}
+
 /**
  * Settings for the Renderer that can be updated during runtime.
  */
@@ -458,6 +542,25 @@ export type RendererMainSettings = RendererRuntimeSettings & {
    */
   createImageBitmapSupport: 'auto' | 'basic' | 'options' | 'full';
 
+  /**
+   * Override for whether `createImageBitmap(..., { premultiplyAlpha: 'premultiply' })`
+   * is actually honored by the target device.
+   *
+   * @remarks
+   * Some older browsers (notably older Safari/WebKit) accept the
+   * `premultiplyAlpha: 'premultiply'` option without throwing but silently
+   * ignore it, returning straight (non-premultiplied) alpha. This causes edge
+   * "ghosting" on images with transparency.
+   *
+   * Set to `'auto'` to detect via a cheap startup probe (one 1×1 texture
+   * upload + framebuffer readback). Set to a boolean to force the value. Leave
+   * unset to assume the option is honored — the default, which preserves
+   * existing behavior with no probe overhead.
+   *
+   * @defaultValue `true` (assume honored; no probe)
+   */
+  premultiplyAlphaHonored?: boolean | 'auto';
+
   /**
    * Provide an alternative platform abstraction layer
    *
@@ -513,11 +616,11 @@ export type RendererMainSettings = RendererRuntimeSettings & {
  *
  * Listen to events using the standard EventEmitter API:
  * ```typescript
- * renderer.on('fpsUpdate', (data: RendererMainFpsUpdateEvent) => {
+ * renderer.on('fpsUpdate', (_target, data: RendererMainFpsUpdateEvent) => {
  *   console.log(`FPS: ${data.fps}`);
  * });
  *
- * renderer.on('idle', (data: RendererMainIdleEvent) => {
+ * renderer.on('idle', () => {
  *   // Renderer is idle - no scene changes
  * });
  * ```
@@ -529,6 +632,7 @@ export type RendererMainSettings = RendererRuntimeSettings & {
  * @see {@link RendererMainCriticalCleanupEvent}
  * @see {@link RendererMainCriticalCleanupFailedEvent}
  * @see {@link RendererMainContextLostEvent}
+ * @see {@link RendererMainOutOfMemoryEvent}
  *
  * @fires RendererMain#fpsUpdate
  * @fires RendererMain#frameTick
@@ -537,6 +641,7 @@ export type RendererMainSettings = RendererRuntimeSettings & {
  * @fires RendererMain#criticalCleanup
  * @fires RendererMain#criticalCleanupFailed
  * @fires RendererMain#contextLost
+ * @fires RendererMain#outOfMemory
  */
 export class RendererMain extends EventEmitter {
   readonly root: INode;
@@ -586,6 +691,12 @@ export class RendererMain extends EventEmitter {
       textureProcessingTimeLimit: settings.textureProcessingTimeLimit || 10,
       canvas: settings.canvas,
       createImageBitmapSupport: settings.createImageBitmapSupport || 'full',
+      // undefined -> true (assume honored, no probe); 'auto' -> probe;
+      // explicit boolean -> force the value.
+      premultiplyAlphaHonored:
+        settings.premultiplyAlphaHonored === undefined
+          ? true
+          : settings.premultiplyAlphaHonored,
       platform: settings.platform || null,
       maxRetryCount: settings.maxRetryCount ?? 5,
     };
@@ -646,6 +757,7 @@ export class RendererMain extends EventEmitter {
       targetFPS: settings.targetFPS!,
       textureProcessingTimeLimit: settings.textureProcessingTimeLimit!,
       createImageBitmapSupport: settings.createImageBitmapSupport!,
+      premultiplyAlphaHonored: settings.premultiplyAlphaHonored,
       platform,
       maxRetryCount: settings.maxRetryCount ?? 5,
     });
@@ -691,11 +803,13 @@ export class RendererMain extends EventEmitter {
     const currentTxSettings =
       (this.stage && this.stage.options.textureMemory) || {};
 
+    const criticalThreshold =
+      textureMemory?.criticalThreshold ??
+      currentTxSettings?.criticalThreshold ??
+      200e6;
+
     return {
-      criticalThreshold:
-        textureMemory?.criticalThreshold ??
-        currentTxSettings?.criticalThreshold ??
-        200e6,
+      criticalThreshold,
       targetThresholdLevel:
         textureMemory?.targetThresholdLevel ??
         currentTxSettings?.targetThresholdLevel ??