@solidtv/renderer 1.5.0-1 → 1.5.1

package/src/core/TextureMemoryManager.test.ts

@@ -1,10 +1,11 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import {
   TextureMemoryManager,
   type TextureMemoryManagerSettings,
 } from './TextureMemoryManager.js';
 import type { Stage } from './Stage.js';
-import type { Texture } from './textures/Texture.js';
+import { TextureType, type Texture } from './textures/Texture.js';
+import { EventEmitter } from '../common/EventEmitter.js';
 
 function makeSettings(
   overrides: Partial<TextureMemoryManagerSettings> = {},
@@ -20,23 +21,38 @@ function makeSettings(
   };
 }
 
-// The only Stage method the OOM path touches is queueFrameEvent.
+// The OOM path touches queueFrameEvent; cleanup() additionally sweeps the
+// texture manager's keyCache and evicts orphans via removeTextureFromCache.
 function makeStage(): {
   stage: Stage;
   queueFrameEvent: ReturnType<typeof vi.fn>;
+  keyCache: Map<string, Texture>;
 } {
   const queueFrameEvent = vi.fn();
-  const stage = { queueFrameEvent } as unknown as Stage;
-  return { stage, queueFrameEvent };
+  const keyCache = new Map<string, Texture>();
+  const txManager = {
+    keyCache,
+    removeTextureFromCache: (texture: Texture) => {
+      // Mirrors CoreTextureManager.removeTextureFromCache
+      const cacheKey = texture.cacheKey;
+      if (cacheKey !== null) {
+        keyCache.delete(cacheKey);
+        texture.cacheKey = null;
+      }
+    },
+  };
+  const stage = { queueFrameEvent, txManager } as unknown as Stage;
+  return { stage, queueFrameEvent, keyCache };
 }
 
 function makeManager(overrides: Partial<TextureMemoryManagerSettings> = {}): {
   mgr: TextureMemoryManager;
   queueFrameEvent: ReturnType<typeof vi.fn>;
+  keyCache: Map<string, Texture>;
 } {
-  const { stage, queueFrameEvent } = makeStage();
+  const { stage, queueFrameEvent, keyCache } = makeStage();
   const mgr = new TextureMemoryManager(stage, makeSettings(overrides));
-  return { mgr, queueFrameEvent };
+  return { mgr, queueFrameEvent, keyCache };
 }
 
 // setTextureMemUse expects a Texture with a mutable memUsed field; nothing else
@@ -96,3 +112,303 @@ describe('TextureMemoryManager — out-of-memory event', () => {
     });
   });
 });
+
+// A cleanable image texture: spies on free()/destroy() so we can assert which
+// reclamation path cleanup() takes. memUsed starts at 0 — setTextureMemUse is
+// what registers its size with the manager.
+function cleanableTexture(): Texture & {
+  free: ReturnType<typeof vi.fn>;
+  destroy: ReturnType<typeof vi.fn>;
+} {
+  return {
+    memUsed: 0,
+    state: 'loaded',
+    type: TextureType.image,
+    free: vi.fn(),
+    destroy: vi.fn(),
+    canBeCleanedUp: () => true,
+  } as unknown as Texture & {
+    free: ReturnType<typeof vi.fn>;
+    destroy: ReturnType<typeof vi.fn>;
+  };
+}
+
+describe('TextureMemoryManager — cleanup is reversible', () => {
+  it('frees textures rather than destroying them so they can reload', () => {
+    const { mgr } = makeManager({ criticalThreshold: 200e6 });
+    const texture = cleanableTexture();
+    mgr.setTextureMemUse(texture, 100e6);
+
+    mgr.cleanup(true);
+
+    // Reversible free path — keeps listeners + cache so a node still
+    // referencing the texture reloads (and is re-notified) on viewport
+    // re-entry. The terminal destroy path (removeAllListeners + cache evict)
+    // must NOT be taken.
+    expect(texture.free).toHaveBeenCalledTimes(1);
+    expect(texture.destroy).not.toHaveBeenCalled();
+  });
+
+  it('reclaims the freed texture memory', () => {
+    const { mgr } = makeManager({ criticalThreshold: 200e6 });
+    const texture = cleanableTexture();
+    mgr.setTextureMemUse(texture, 100e6);
+    expect(mgr.getMemoryInfo().memUsed).toBe(126e6); // 26e6 baseline + 100e6
+
+    mgr.cleanup(true);
+
+    expect(mgr.getMemoryInfo().memUsed).toBe(26e6); // back to baseline
+    expect(texture.memUsed).toBe(0);
+  });
+});
+
+// A cached, already-freed texture as left behind by a prior cleanup(): GPU and
+// CPU data released (memUsed 0, not in loadedTextures), but the Texture object
+// still sits in the keyCache. Built on a real EventEmitter so hasListeners()
+// reflects actual on()/off() subscriptions, exactly like CoreNode's
+// loadTextureTask/unloadTexture.
+function freedCachedTexture(cacheKey: string): Texture & {
+  destroy: ReturnType<typeof vi.fn>;
+} {
+  const texture = Object.assign(new EventEmitter(), {
+    memUsed: 0,
+    state: 'freed',
+    type: TextureType.image,
+    preventCleanup: false,
+    renderableOwners: [],
+    cacheKey,
+    free: vi.fn(),
+    destroy: vi.fn(),
+    canBeCleanedUp: () => true,
+    // Fresh texture by default — within the 2s startup grace period.
+    isWithinStartupGracePeriod: () => true,
+  });
+  return texture as unknown as Texture & {
+    destroy: ReturnType<typeof vi.fn>;
+  };
+}
+
+describe('TextureMemoryManager — orphaned freed texture eviction', () => {
+  it('keeps a freed texture that a node still references via listeners', () => {
+    const { mgr, keyCache } = makeManager();
+    const texture = freedCachedTexture('img:poster.png');
+    keyCache.set('img:poster.png', texture);
+    // CoreNode.loadTextureTask subscribes; the node is alive but offscreen.
+    texture.on('freed', () => {});
+
+    mgr.cleanup();
+
+    expect(texture.destroy).not.toHaveBeenCalled();
+    expect(keyCache.get('img:poster.png')).toBe(texture);
+    expect(texture.cacheKey).toBe('img:poster.png');
+  });
+
+  it('keeps a freed texture that still has renderable owners', () => {
+    const { mgr, keyCache } = makeManager();
+    const texture = freedCachedTexture('img:poster.png');
+    (texture.renderableOwners as unknown[]).push(1);
+    keyCache.set('img:poster.png', texture);
+
+    mgr.cleanup();
+
+    expect(texture.destroy).not.toHaveBeenCalled();
+    expect(keyCache.get('img:poster.png')).toBe(texture);
+  });
+
+  it('keeps a freed texture marked preventCleanup', () => {
+    const { mgr, keyCache } = makeManager();
+    const texture = freedCachedTexture('img:poster.png');
+    (texture as { preventCleanup: boolean }).preventCleanup = true;
+    keyCache.set('img:poster.png', texture);
+
+    mgr.cleanup();
+
+    expect(texture.destroy).not.toHaveBeenCalled();
+    expect(keyCache.get('img:poster.png')).toBe(texture);
+  });
+
+  it('does not evict loaded or in-flight cached textures, even aged orphans', () => {
+    const { mgr, keyCache } = makeManager();
+    const states = ['loaded', 'fetching', 'fetched', 'loading'];
+    const textures: ReturnType<typeof freedCachedTexture>[] = [];
+    for (const state of states) {
+      const texture = freedCachedTexture(`img:${state}.png`);
+      (texture as { state: string }).state = state;
+      // Aged out — eviction must be blocked by state alone.
+      (
+        texture as { isWithinStartupGracePeriod: () => boolean }
+      ).isWithinStartupGracePeriod = () => false;
+      keyCache.set(`img:${state}.png`, texture);
+      textures.push(texture);
+    }
+
+    mgr.cleanup();
+
+    for (const texture of textures) {
+      expect(texture.destroy).not.toHaveBeenCalled();
+    }
+    expect(keyCache.size).toBe(states.length);
+  });
+
+  it('keeps a fresh initial texture during the startup grace period', () => {
+    // A node created this same frame subscribes in a queued microtask, so a
+    // brand-new texture can look orphaned during a same-frame cleanup. The
+    // grace period is the race guard.
+    const { mgr, keyCache } = makeManager();
+    const texture = freedCachedTexture('img:fresh.png');
+    (texture as { state: string }).state = 'initial';
+
+    keyCache.set('img:fresh.png', texture);
+    mgr.cleanup();
+
+    expect(texture.destroy).not.toHaveBeenCalled();
+    expect(keyCache.get('img:fresh.png')).toBe(texture);
+  });
+
+  it('evicts an orphaned initial texture once the grace period expires', () => {
+    const { mgr, keyCache } = makeManager();
+    const texture = freedCachedTexture('img:never-loaded.png');
+    (texture as { state: string }).state = 'initial';
+    (
+      texture as { isWithinStartupGracePeriod: () => boolean }
+    ).isWithinStartupGracePeriod = () => false;
+
+    keyCache.set('img:never-loaded.png', texture);
+    mgr.cleanup();
+
+    expect(texture.destroy).toHaveBeenCalledTimes(1);
+    expect(keyCache.has('img:never-loaded.png')).toBe(false);
+    expect(texture.cacheKey).toBe(null);
+  });
+
+  it('evicts an orphaned failed texture once the grace period expires', () => {
+    // Retry only happens through a node's 'failed' listener — with no
+    // listeners nothing will ever retry it.
+    const { mgr, keyCache } = makeManager();
+    const texture = freedCachedTexture('img:404.png');
+    (texture as { state: string }).state = 'failed';
+    (
+      texture as { isWithinStartupGracePeriod: () => boolean }
+    ).isWithinStartupGracePeriod = () => false;
+
+    keyCache.set('img:404.png', texture);
+    mgr.cleanup();
+
+    expect(texture.destroy).toHaveBeenCalledTimes(1);
+    expect(keyCache.has('img:404.png')).toBe(false);
+  });
+
+  it('keeps an aged initial texture that a node references via listeners', () => {
+    const { mgr, keyCache } = makeManager();
+    const texture = freedCachedTexture('img:queued.png');
+    (texture as { state: string }).state = 'initial';
+    (
+      texture as { isWithinStartupGracePeriod: () => boolean }
+    ).isWithinStartupGracePeriod = () => false;
+    texture.on('loaded', () => {});
+
+    keyCache.set('img:queued.png', texture);
+    mgr.cleanup();
+
+    expect(texture.destroy).not.toHaveBeenCalled();
+    expect(keyCache.get('img:queued.png')).toBe(texture);
+  });
+
+  it('destroys and evicts an orphaned freed texture', () => {
+    const { mgr, keyCache } = makeManager();
+    const texture = freedCachedTexture('img:gone.png');
+    keyCache.set('img:gone.png', texture);
+
+    mgr.cleanup();
+
+    expect(texture.destroy).toHaveBeenCalledTimes(1);
+    expect(keyCache.has('img:gone.png')).toBe(false);
+    expect(texture.cacheKey).toBe(null);
+  });
+
+  it('evicts only once the last listener is removed (node destroyed)', () => {
+    const { mgr, keyCache } = makeManager();
+    const texture = freedCachedTexture('img:row-item.png');
+    keyCache.set('img:row-item.png', texture);
+    const onFreed = () => {};
+    texture.on('freed', onFreed);
+
+    mgr.cleanup();
+    expect(texture.destroy).not.toHaveBeenCalled();
+    expect(keyCache.has('img:row-item.png')).toBe(true);
+
+    // Node destroyed: CoreNode.unloadTexture removes its subscriptions.
+    texture.off('freed', onFreed);
+
+    mgr.cleanup();
+    expect(texture.destroy).toHaveBeenCalledTimes(1);
+    expect(keyCache.has('img:row-item.png')).toBe(false);
+  });
+
+  it('evicts orphans freed by the same cleanup pass', () => {
+    const { mgr, keyCache } = makeManager({ criticalThreshold: 200e6 });
+    // A loaded, cleanable texture whose free() transitions it to 'freed',
+    // mirroring ctxTexture.free() -> setState('freed'). No listeners and no
+    // owners: its node was already destroyed.
+    const texture = freedCachedTexture('img:orphan.png');
+    (texture as { state: string }).state = 'loaded';
+    (texture as { free: () => void }).free = () => {
+      (texture as { state: string }).state = 'freed';
+    };
+    keyCache.set('img:orphan.png', texture);
+    mgr.setTextureMemUse(texture, 100e6);
+
+    mgr.cleanup(true);
+
+    expect(texture.destroy).toHaveBeenCalledTimes(1);
+    expect(keyCache.has('img:orphan.png')).toBe(false);
+    expect(mgr.getMemoryInfo().memUsed).toBe(26e6); // baseline only
+  });
+});
+
+describe('EventEmitter — hasListeners', () => {
+  it('is false before any listener is registered', () => {
+    const emitter = new EventEmitter();
+    expect(emitter.hasListeners()).toBe(false);
+  });
+
+  it('is true while a listener is registered and false after off()', () => {
+    const emitter = new EventEmitter();
+    const listener = () => {};
+    emitter.on('loaded', listener);
+    expect(emitter.hasListeners()).toBe(true);
+
+    emitter.off('loaded', listener);
+    expect(emitter.hasListeners()).toBe(false);
+  });
+
+  it('is false after off() removes all listeners for an event by name', () => {
+    const emitter = new EventEmitter();
+    emitter.on('loaded', () => {});
+    emitter.off('loaded');
+    expect(emitter.hasListeners()).toBe(false);
+  });
+
+  it('is true if any one of several events still has a listener', () => {
+    const emitter = new EventEmitter();
+    const a = () => {};
+    emitter.on('loaded', a);
+    emitter.on('freed', () => {});
+    emitter.off('loaded', a);
+    expect(emitter.hasListeners()).toBe(true);
+  });
+
+  it('is false after a once() listener has fired', () => {
+    const emitter = new EventEmitter();
+    emitter.once('loaded', () => {});
+    emitter.emit('loaded');
+    expect(emitter.hasListeners()).toBe(false);
+  });
+
+  it('is false after removeAllListeners()', () => {
+    const emitter = new EventEmitter();
+    emitter.on('loaded', () => {});
+    emitter.removeAllListeners();
+    expect(emitter.hasListeners()).toBe(false);
+  });
+});

package/src/core/TextureMemoryManager.ts

@@ -167,11 +167,58 @@ export class TextureMemoryManager {
   }
 
   /**
-   * Destroy a texture and remove it from the memory manager
+   * Reversibly free a texture's GPU resources under memory pressure.
+   *
+   * @remarks
+   * Unlike {@link destroyTexture}, this keeps the `Texture` object, its event
+   * listeners, and its cache entry intact. It only releases the GPU-side
+   * resource and transitions the source to the `freed` state. A `CoreNode` that
+   * still references this texture will reload it — and be re-notified via its
+   * `loaded` listener — when it re-enters the viewport (see
+   * `Texture.setRenderableOwner` → `Texture.load`).
+   *
+   * This is the correct path for LRU/idle cleanup: destroying instead would
+   * sever the node's subscription (`removeAllListeners`) and evict the cache
+   * entry, leaving the node stuck on a texture that reloads to `loaded` but is
+   * never displayed.
+   *
+   * `texture.free()` reclaims tracked memory via `setTextureMemUse(0)` when a
+   * ctxTexture exists; the guard below keeps the accounting correct for any
+   * texture that entered `loadedTextures` without one.
+   *
+   * @param texture - The texture to free
+   */
+  freeTexture(texture: Texture) {
+    if (this.debugLogging === true) {
+      console.log(
+        `[TextureMemoryManager] Freeing texture. State: ${texture.state}`,
+      );
+    }
+
+    texture.free();
+
+    if (this.loadedTextures.has(texture) === true) {
+      this.loadedTextures.delete(texture);
+      this.memUsed -= texture.memUsed;
+      texture.memUsed = 0;
+    }
+  }
+
+  /**
+   * Destroy a texture, evict its cache entry, and remove it from the memory
+   * manager.
+   *
+   * @remarks
+   * Private on purpose: `destroy()` calls `removeAllListeners()`, so running
+   * this on a texture that still has subscribers severs a live `CoreNode`'s
+   * (or `SubTexture`'s) connection — the blank-poster bug. The only safe
+   * entry point is {@link evictOrphanedTextures}, which proves the texture
+   * is unreferenced first. For memory pressure use {@link freeTexture},
+   * which is reversible.
    *
    * @param texture - The texture to destroy
    */
-  destroyTexture(texture: Texture) {
+  private destroyTexture(texture: Texture) {
     if (this.debugLogging === true) {
       console.log(
         `[TextureMemoryManager] Destroying texture. State: ${texture.state}`,
@@ -230,15 +277,18 @@ export class TextureMemoryManager {
 
       // Immediate cleanup if eligible
       if (isCleanableType && texture.canBeCleanedUp() === true) {
-        // Get memory before destroying
+        // Get memory before freeing
         const textureMemory = texture.memUsed;
 
-        // Destroy texture (which will null out the array position)
-        this.destroyTexture(texture);
+        // Reversibly free (keeps listeners + cache) so the texture reloads when
+        // its node re-enters the viewport.
+        this.freeTexture(texture);
         currentMemUsed -= textureMemory;
       }
     }
 
+    this.evictOrphanedTextures();
+
     if (this.memUsed >= this.criticalThreshold) {
       this.stage.queueFrameEvent('criticalCleanupFailed', {
         memUsed: this.memUsed,
@@ -261,6 +311,52 @@ export class TextureMemoryManager {
     }
   }
 
+  /**
+   * Destroy-and-evict freed textures that nothing references anymore.
+   *
+   * @remarks
+   * {@link freeTexture} intentionally keeps the texture's cache entry and
+   * listeners so a live `CoreNode` can reload it in place. But once the last
+   * referencing node is destroyed (`unloadTexture` removes its listeners and
+   * owner), the freed texture's `keyCache` entry can never be displayed again
+   * — without eviction the cache grows unboundedly in apps cycling many
+   * unique textures.
+   *
+   * A texture is an orphan only when it has zero `renderableOwners` AND zero
+   * event listeners: every live referencer (`CoreNode.loadTextureTask`,
+   * `SubTexture`) subscribes via `on()`. A texture with any listener must
+   * NEVER be destroyed here — `destroy()` calls `removeAllListeners()`, which
+   * would sever the node's subscription and reintroduce the blank-poster bug
+   * that {@link freeTexture} exists to prevent.
+   *
+   * `'initial'` and `'failed'` orphans leak the same way (created or failed,
+   * then the node was destroyed before the texture ever loaded; nothing will
+   * ever retry a `'failed'` texture without a listener). They are evicted only
+   * after the startup grace period: a node created this same frame subscribes
+   * in a queued microtask, so a fresh texture can look orphaned during a
+   * same-frame cleanup. In-flight states (`'fetching'`/`'loading'`/`'fetched'`)
+   * are never evicted; `'loaded'` orphans go through the pressure-driven free
+   * loop first and are swept here as `'freed'` on a later pass.
+   */
+  private evictOrphanedTextures(): void {
+    const keyCache = this.stage.txManager.keyCache;
+    for (const texture of keyCache.values()) {
+      const state = texture.state;
+      const evictable =
+        state === 'freed' ||
+        ((state === 'initial' || state === 'failed') &&
+          texture.isWithinStartupGracePeriod() === false);
+      if (
+        evictable === true &&
+        texture.preventCleanup === false &&
+        texture.renderableOwners.length === 0 &&
+        texture.hasListeners() === false
+      ) {
+        this.destroyTexture(texture);
+      }
+    }
+  }
+
   /**
    * Get the current texture memory usage information
    *

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

@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest';
+import { WebGlContextWrapper } from './WebGlContextWrapper.js';
+
+// The wrapper reads `self.WebGL2RenderingContext` to detect WebGL2. The unit
+// test environment is plain Node where `self` is undefined, so provide one.
+// With no WebGL2RenderingContext on it, the mock context is treated as WebGL1.
+const g = globalThis as unknown as { self?: unknown };
+if (g.self === undefined) {
+  g.self = globalThis;
+}
+
+// Minimal WebGL1-like context. A Proxy returns 0 for every GLenum constant the
+// constructor copies; only the handful of methods/props it actually calls are
+// implemented.
+function mockWebGl1(hasVaoExtension: boolean): WebGLRenderingContext {
+  const vaoExt = {
+    createVertexArrayOES: () => ({}),
+    bindVertexArrayOES: (_vao: unknown) => undefined,
+    deleteVertexArrayOES: (_vao: unknown) => undefined,
+  };
+  const target: Record<string, unknown> = {
+    canvas: {},
+    drawingBufferWidth: 100,
+    drawingBufferHeight: 100,
+    getParameter: () => 8,
+    getExtension: (name: string) =>
+      name === 'OES_vertex_array_object' && hasVaoExtension ? vaoExt : null,
+  };
+  return new Proxy(target, {
+    get(t, prop) {
+      if (prop in t) {
+        return t[prop as string];
+      }
+      // Every other access is a GLenum constant.
+      return 0;
+    },
+  }) as unknown as WebGLRenderingContext;
+}
+
+describe('WebGlContextWrapper VAO support', () => {
+  it('enables VAOs when the OES extension is present', () => {
+    const glw = new WebGlContextWrapper(mockWebGl1(true));
+    expect(glw.canUseVertexArrayObject).toBe(true);
+    expect(glw.isWebGl2).toBe(false);
+  });
+
+  it('disables VAOs when the OES extension is absent', () => {
+    const glw = new WebGlContextWrapper(mockWebGl1(false));
+    expect(glw.canUseVertexArrayObject).toBe(false);
+  });
+
+  it('forces VAOs off when disableVertexArrayObject is true, even if supported', () => {
+    const glw = new WebGlContextWrapper(mockWebGl1(true), true);
+    expect(glw.canUseVertexArrayObject).toBe(false);
+    // The flag gates VAO usage only; it does not change the detected context.
+    expect(glw.isWebGl2).toBe(false);
+  });
+});

package/src/core/lib/WebGlContextWrapper.ts

@@ -111,7 +111,10 @@ export class WebGlContextWrapper {
   public readonly INVALID_OPERATION: number;
   //#endregion WebGL Enums
 
-  constructor(private gl: WebGLRenderingContext | WebGL2RenderingContext) {
+  constructor(
+    private gl: WebGLRenderingContext | WebGL2RenderingContext,
+    disableVertexArrayObject = false,
+  ) {
     // A freshly created WebGL context is in a fully specified default state.
     // Rather than reading that state back with getParameter/isEnabled — each a
     // synchronous CPU<->GPU round-trip, and previously ~one per texture unit
@@ -154,9 +157,16 @@ export class WebGlContextWrapper {
       self.WebGL2RenderingContext && gl instanceof self.WebGL2RenderingContext
         ? (gl as WebGL2RenderingContext)
         : null;
+    // `disableVertexArrayObject` forces the per-draw attribute-binding path even
+    // when VAOs are available (diagnostics / benchmarking). isWebGl2 still
+    // reflects the real context — the flag only gates VAO usage.
     this.vaoExt =
-      this.gl2 === null ? gl.getExtension('OES_vertex_array_object') : null;
-    this.canUseVertexArrayObject = this.gl2 !== null || this.vaoExt !== null;
+      this.gl2 === null && disableVertexArrayObject !== true
+        ? gl.getExtension('OES_vertex_array_object')
+        : null;
+    this.canUseVertexArrayObject =
+      disableVertexArrayObject !== true &&
+      (this.gl2 !== null || this.vaoExt !== null);
     this.isWebGl2 = this.gl2 !== null;
 
     this.canvas = gl.canvas;