@solidtv/renderer 1.5.0 → 1.5.2

package/src/core/TextureMemoryManager.test.ts

@@ -5,6 +5,7 @@ import {
 } from './TextureMemoryManager.js';
 import type { Stage } from './Stage.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
@@ -145,3 +161,254 @@ describe('TextureMemoryManager — cleanup is reversible', () => {
     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

@@ -205,11 +205,20 @@ export class TextureMemoryManager {
   }
 
   /**
-   * Destroy a texture and remove it from the memory manager
+   * 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}`,
@@ -278,6 +287,8 @@ export class TextureMemoryManager {
       }
     }
 
+    this.evictOrphanedTextures();
+
     if (this.memUsed >= this.criticalThreshold) {
       this.stage.queueFrameEvent('criticalCleanupFailed', {
         memUsed: this.memUsed,
@@ -300,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/renderers/canvas/CanvasRenderer.ts

@@ -52,7 +52,13 @@ export class CanvasRenderer extends CoreRenderer {
     const ctx = this.context;
     const { tx, ty, ta, tb, tc, td } = node.globalTransform!;
     const clippingRect = node.clippingRect;
-    let texture = (node.props.texture || this.stage.defaultTexture) as Texture;
+    // While a placeholder is showing, render the color-rect path (the default
+    // ColorTexture) tinted by the node's premultiplied placeholder color.
+    let texture = (
+      node.placeholderActive === true
+        ? this.stage.defaultTexture
+        : node.props.texture || this.stage.defaultTexture
+    ) as Texture;
     // The Canvas2D renderer only supports image textures, no textures are used for color blocks
     if (texture !== null) {
       const textureType = texture.type;

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

@@ -471,7 +471,12 @@ export class WebGlRenderer extends CoreRenderer {
     }
 
     const props = node.props;
-    let tx = props.texture || this.stage.defaultTexture!;
+    // While a placeholder is showing, the quad samples the shared 1x1 white
+    // texture tinted by the node's premultiplied placeholder color.
+    let tx =
+      node.placeholderActive === true
+        ? this.stage.defaultTexture!
+        : props.texture || this.stage.defaultTexture!;
 
     if (tx.type === TextureType.subTexture) {
       tx = (tx as SubTexture).parentTexture;

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

@@ -30,6 +30,35 @@ export class WebGlShaderProgram implements CoreShaderProgram {
   public isDestroyed = false;
   supportsIndexedTextures = false;
 
+  /**
+   * Shadow copies of this program's GL uniform state, used by
+   * {@link bindRenderOp} to skip redundant gl.uniform* calls.
+   *
+   * @remarks
+   * GL uniform values are state on the program object and persist across
+   * useProgram switches, and bindRenderOp is the only writer of these
+   * uniforms, so the shadows always mirror GL truth — even when ops using
+   * other programs are interleaved between two ops of this program.
+   *
+   * `lastBoundUniforms` tracks the shader node's uniform collection by
+   * identity: collections are created once, filled once, and shared by
+   * reference across shader nodes with the same value key (see
+   * WebGlShaderNode.update), so reference equality implies value equality.
+   * The failure direction is safe — a new collection holding identical
+   * values just causes a redundant upload, never a wrong skip.
+   *
+   * Sentinels: -1 never collides with real pixel ratios, resolutions,
+   * alphas, dimensions, or time values (all >= 0).
+   */
+  protected lastBoundUniforms: unknown = null;
+  protected lastPixelRatio = -1;
+  protected lastResolutionW = -1;
+  protected lastResolutionH = -1;
+  protected lastAlpha = -1;
+  protected lastDimensionsW = -1;
+  protected lastDimensionsH = -1;
+  protected lastTime = -1;
+
   /**
    * Cached Vertex Array Objects, keyed by the buffer collection they capture.
    *
@@ -198,44 +227,78 @@ export class WebGlShaderProgram implements CoreShaderProgram {
       return;
     }
 
-    // Bind render texture framebuffer dimensions as resolution
-    // if the parent has a render texture
+    // Resolve target pixel ratio / resolution, then compare-and-set against
+    // the program's shadow state. Each gl.uniform* call below crosses into
+    // the GPU-process command buffer, so skipping value-identical re-uploads
+    // is a real per-op CPU saving on embedded targets.
+    let pixelRatio: number;
+    let resolutionW: number;
+    let resolutionH: number;
     if (USE_RTT && parentHasRenderTexture === true && framebufferDimensions) {
-      const { w, h } = framebufferDimensions;
       // Force pixel ratio to 1.0 for render textures since they are always 1:1
       // the final render texture will be rendered to the screen with the correct pixel ratio
-      this.glw.uniform1f('u_pixelRatio', 1.0);
-
+      pixelRatio = 1.0;
       // Set resolution to the framebuffer dimensions
-      this.glw.uniform2f('u_resolution', w, h);
+      resolutionW = framebufferDimensions.w;
+      resolutionH = framebufferDimensions.h;
     } else {
-      this.glw.uniform1f('u_pixelRatio', renderOp.stage.pixelRatio);
+      pixelRatio = renderOp.stage.pixelRatio;
+      resolutionW = this.glw.canvas.width;
+      resolutionH = this.glw.canvas.height;
+    }
 
-      this.glw.uniform2f(
-        'u_resolution',
-        this.glw.canvas.width,
-        this.glw.canvas.height,
-      );
+    if (pixelRatio !== this.lastPixelRatio) {
+      this.glw.uniform1f('u_pixelRatio', pixelRatio);
+      this.lastPixelRatio = pixelRatio;
     }
 
-    if (this.useTimeValue === true) {
+    if (
+      resolutionW !== this.lastResolutionW ||
+      resolutionH !== this.lastResolutionH
+    ) {
+      this.glw.uniform2f('u_resolution', resolutionW, resolutionH);
+      this.lastResolutionW = resolutionW;
+      this.lastResolutionH = resolutionH;
+    }
+
+    if (this.useTimeValue === true && renderOp.time !== this.lastTime) {
       this.glw.uniform1f('u_time', renderOp.time);
+      this.lastTime = renderOp.time;
     }
 
-    if (this.useSystemAlpha === true) {
+    if (
+      this.useSystemAlpha === true &&
+      renderOp.worldAlpha !== this.lastAlpha
+    ) {
       this.glw.uniform1f('u_alpha', renderOp.worldAlpha);
+      this.lastAlpha = renderOp.worldAlpha;
     }
 
-    if (this.useSystemDimensions === true) {
+    if (
+      this.useSystemDimensions === true &&
+      (renderOp.w !== this.lastDimensionsW ||
+        renderOp.h !== this.lastDimensionsH)
+    ) {
       this.glw.uniform2f('u_dimensions', renderOp.w, renderOp.h);
+      this.lastDimensionsW = renderOp.w;
+      this.lastDimensionsH = renderOp.h;
     }
 
     const shader = renderOp.shader as WebGlShaderNode;
     if (shader.props !== undefined) {
       /**
        * loop over all precalculated uniform types
+       *
+       * Collections are immutable after being filled and shared by reference
+       * across shader nodes with equal value keys, so when the same object is
+       * already bound the GL program still holds exactly these values and the
+       * whole pass (loops + gl calls) can be skipped.
        */
       const uniforms = shader.uniforms;
+      if ((uniforms as unknown) === this.lastBoundUniforms) {
+        return;
+      }
+      this.lastBoundUniforms = uniforms;
 
       for (const key in uniforms.single) {
         const { method, value } = uniforms.single[key]!;