@solidtv/renderer 1.5.0 → 1.5.1

package/src/core/CoreNode.ts

@@ -392,6 +392,23 @@ export interface CoreNodeProps {
    * rendering.
    */
   colorBl: number;
+  /**
+   * Placeholder color shown while the Node's texture is not yet loaded.
+   *
+   * @remarks
+   * When set to a non-zero color and the Node has a texture (e.g. {@link src}),
+   * the Node renders a solid rectangle of this color until the texture
+   * finishes loading, instead of rendering nothing. The placeholder renders
+   * through the Node's shader, so rounded corners and borders apply to it.
+   * It also shows again if the texture is freed under memory pressure (until
+   * the reload completes) and remains if the texture permanently fails.
+   *
+   * The color value is a number in the format 0xRRGGBBAA. Set to `0` to
+   * disable (default). Has no effect on Nodes without a texture.
+   *
+   * @default `0`
+   */
+  placeholderColor: number;
   /**
    * The Node's parent Node.
    *
@@ -793,6 +810,15 @@ export class CoreNode extends EventEmitter {
   private hasColorProps = false;
   public textureLoaded = false;
 
+  /**
+   * True while this node should render its `placeholderColor` instead of its
+   * texture: `placeholderColor` is non-zero, a texture is set, and that
+   * texture is not loaded. Read by the renderers' quad path to substitute the
+   * stage's default (1x1 white) texture. Maintained by
+   * {@link updatePlaceholderActive} — never written elsewhere.
+   */
+  public placeholderActive = false;
+
   public updateType = UpdateType.All;
   public childUpdateType = UpdateType.None;
 
@@ -953,6 +979,31 @@ export class CoreNode extends EventEmitter {
   }
 
   //#region Textures
+  /**
+   * Recompute {@link placeholderActive} after any of its inputs changed
+   * (placeholderColor, texture, textureLoaded).
+   *
+   * @remarks
+   * On a toggle this raises `PremultipliedColors` (the quad's vertex colors
+   * switch between the placeholder color and the regular color props — this
+   * also marks the quad dirty) and `IsRenderable` (a loading texture with a
+   * placeholder is renderable). Both are processed in the same frame's update
+   * pass, before quads are submitted.
+   */
+  private updatePlaceholderActive(): void {
+    const active =
+      this.props.placeholderColor !== 0 &&
+      this.props.texture !== null &&
+      this.textureLoaded === false;
+
+    if (active !== this.placeholderActive) {
+      this.placeholderActive = active;
+      this.setUpdateType(
+        UpdateType.PremultipliedColors | UpdateType.IsRenderable,
+      );
+    }
+  }
+
   loadTexture(): void {
     if (this.props.texture === null) {
       return;
@@ -1023,6 +1074,7 @@ export class CoreNode extends EventEmitter {
     }
 
     this.textureLoaded = true;
+    this.updatePlaceholderActive();
     this.setUpdateType(UpdateType.IsRenderable);
 
     // Texture was loaded. In case the RAF loop has already stopped, we request
@@ -1057,9 +1109,12 @@ export class CoreNode extends EventEmitter {
 
   private onTextureFailed: TextureFailedEventHandler = (_, error) => {
     // immediately set isRenderable to false, so that we handle the error
-    // without waiting for the next frame loop
+    // without waiting for the next frame loop. With a placeholder set, the
+    // same frame's update pass recomputes this to true and renders the
+    // placeholder instead.
     this.textureLoaded = false;
     this.isRenderable = false;
+    this.updatePlaceholderActive();
     this.updateTextureOwnership(false);
     this.setUpdateType(UpdateType.IsRenderable);
 
@@ -1081,9 +1136,12 @@ export class CoreNode extends EventEmitter {
 
   private onTextureFreed: TextureFreedEventHandler = () => {
     // immediately set isRenderable to false, so that we handle the error
-    // without waiting for the next frame loop
+    // without waiting for the next frame loop. With a placeholder set, the
+    // same frame's update pass recomputes this to true and renders the
+    // placeholder while the texture reloads.
     this.textureLoaded = false;
     this.isRenderable = false;
+    this.updatePlaceholderActive();
     this.updateTextureOwnership(false);
     this.setUpdateType(UpdateType.IsRenderable);
 
@@ -1355,7 +1413,13 @@ export class CoreNode extends EventEmitter {
       this.calculateRenderCoords();
       this.updateBoundingRect();
 
-      updateType |= UpdateType.RenderState | UpdateType.RecalcUniforms;
+      // RecalcUniforms is intentionally NOT set here: shader uniforms are a
+      // function of resolvedProps + w/h only (that is exactly the shader
+      // value-key cache key), so pure transform changes (translate, scale,
+      // rotate) cannot affect them. The flag is raised where w/h actually
+      // change: the w/h setters, Autosizer.applyDimensions, text layout
+      // application, and the shader setter itself.
+      updateType |= UpdateType.RenderState;
 
       //only propagate children updates if not autosizing
       if ((updateType & UpdateType.Autosize) === 0) {
@@ -1420,27 +1484,39 @@ export class CoreNode extends EventEmitter {
     if (updateType & UpdateType.PremultipliedColors) {
       const alpha = this.worldAlpha;
 
-      const tl = props.colorTl;
-      const tr = props.colorTr;
-      const bl = props.colorBl;
-      const br = props.colorBr;
-
-      // Fast equality check (covers all 4 corners)
-      const same = tl === tr && tl === bl && tl === br;
-
-      const merged = premultiplyColorABGR(tl, alpha);
-
-      this.premultipliedColorTl = merged;
-
-      if (same === true) {
-        this.premultipliedColorTr =
+      if (this.placeholderActive === true) {
+        // Placeholder rendering: all four corners take the placeholder color.
+        // The quad samples the stage's default 1x1 white texture, so this is
+        // exactly the color-rect path.
+        const merged = premultiplyColorABGR(props.placeholderColor, alpha);
+        this.premultipliedColorTl =
+          this.premultipliedColorTr =
           this.premultipliedColorBl =
           this.premultipliedColorBr =
             merged;
       } else {
-        this.premultipliedColorTr = premultiplyColorABGR(tr, alpha);
-        this.premultipliedColorBl = premultiplyColorABGR(bl, alpha);
-        this.premultipliedColorBr = premultiplyColorABGR(br, alpha);
+        const tl = props.colorTl;
+        const tr = props.colorTr;
+        const bl = props.colorBl;
+        const br = props.colorBr;
+
+        // Fast equality check (covers all 4 corners)
+        const same = tl === tr && tl === bl && tl === br;
+
+        const merged = premultiplyColorABGR(tl, alpha);
+
+        this.premultipliedColorTl = merged;
+
+        if (same === true) {
+          this.premultipliedColorTr =
+            this.premultipliedColorBl =
+            this.premultipliedColorBr =
+              merged;
+        } else {
+          this.premultipliedColorTr = premultiplyColorABGR(tr, alpha);
+          this.premultipliedColorBl = premultiplyColorABGR(bl, alpha);
+          this.premultipliedColorBr = premultiplyColorABGR(br, alpha);
+        }
       }
     }
 
@@ -1754,15 +1830,18 @@ export class CoreNode extends EventEmitter {
       // preemptive check for failed textures this will mark the current node as non-renderable
       // and will prevent further checks until the texture is reloaded or retry is reset on the texture
       if (this.texture.retryCount > this.texture.maxRetryCount) {
-        // texture has failed to load, we cannot render
+        // texture has failed to load, we cannot render the texture itself —
+        // but a placeholder color still renders in its place
         this.updateTextureOwnership(false);
-        this.setRenderable(false);
+        this.setRenderable(this.placeholderActive);
         return;
       }
 
       needsTextureOwnership = true;
-      // Use cached boolean instead of string comparison
-      newIsRenderable = this.textureLoaded;
+      // Use cached boolean instead of string comparison; a placeholder
+      // renders while the texture is loading
+      newIsRenderable =
+        this.textureLoaded === true || this.placeholderActive === true;
     } else if (
       // check shader
       (this.props.shader !== this.stage.renderer.getDefaultShaderNode() ||
@@ -2049,6 +2128,9 @@ export class CoreNode extends EventEmitter {
   }
 
   get renderTexture(): Texture | null {
+    if (this.placeholderActive === true) {
+      return this.stage.defaultTexture;
+    }
     return this.props.texture || this.stage.defaultTexture;
   }
 
@@ -2232,7 +2314,9 @@ export class CoreNode extends EventEmitter {
     const props = this.props;
     if (props.w !== value) {
       props.w = value;
-      let updateType = UpdateType.Local;
+      // Dimensions feed shader uniforms (e.g. factored corner radius), so a
+      // resize must recompute them; see the Global-update branch in update().
+      let updateType = UpdateType.Local | UpdateType.RecalcUniforms;
 
       if (
         props.texture !== null &&
@@ -2262,7 +2346,9 @@ export class CoreNode extends EventEmitter {
     const props = this.props;
     if (props.h !== value) {
       props.h = value;
-      let updateType = UpdateType.Local;
+      // Dimensions feed shader uniforms (e.g. factored corner radius), so a
+      // resize must recompute them; see the Global-update branch in update().
+      let updateType = UpdateType.Local | UpdateType.RecalcUniforms;
 
       if (
         props.texture !== null &&
@@ -2514,6 +2600,24 @@ export class CoreNode extends EventEmitter {
     this.setUpdateType(UpdateType.PremultipliedColors);
   }
 
+  get placeholderColor(): number {
+    return this.props.placeholderColor;
+  }
+
+  set placeholderColor(value: number) {
+    const p = this.props;
+    if (p.placeholderColor === value) return;
+
+    p.placeholderColor = value;
+    this.updatePlaceholderActive();
+
+    // If the placeholder is (still) showing, the new color must reach the
+    // quad buffer even though the active state did not toggle.
+    if (this.placeholderActive === true) {
+      this.setUpdateType(UpdateType.PremultipliedColors);
+    }
+  }
+
   get colorTop(): number {
     return this.props.colorTop;
   }
@@ -2934,6 +3038,7 @@ export class CoreNode extends EventEmitter {
     this.textureCoords = undefined;
     this.props.texture = value;
     this.textureLoaded = value !== null && value.state === 'loaded';
+    this.updatePlaceholderActive();
 
     if (value !== null) {
       if (this.autosizer !== null) {

package/src/core/CoreTextNode.test.ts

@@ -28,6 +28,7 @@ const defaultProps = (
   colorTl: 0xffffffff,
   colorTop: 0xffffffff,
   colorTr: 0xffffffff,
+  placeholderColor: 0,
   h: 0,
   mount: 0,
   mountX: 0,

package/src/core/CoreTextNode.ts

@@ -271,8 +271,12 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
     this.props.w = width;
     this.props.h = height;
 
-    // Text dimensions may have changed, recalculate transforms and bounds
-    this.setUpdateType(UpdateType.Local | UpdateType.RenderBounds);
+    // Text dimensions may have changed, recalculate transforms and bounds.
+    // RecalcUniforms because the direct props.w/h write above bypasses the
+    // w/h setters and dimensions feed shader uniforms.
+    this.setUpdateType(
+      UpdateType.Local | UpdateType.RenderBounds | UpdateType.RecalcUniforms,
+    );
 
     // Handle SDF renderer (uses layout caching)
     if (textRendererType === 'sdf') {

package/src/core/Stage.ts

@@ -382,6 +382,7 @@ export class Stage {
       colorRight: 0x00000000,
       colorTl: 0x00000000,
       colorTr: 0x00000000,
+      placeholderColor: 0x00000000,
       colorBl: 0x00000000,
       colorBr: 0x00000000,
       zIndex: 0,
@@ -1043,6 +1044,7 @@ export class Stage {
       colorTr,
       colorBl,
       colorBr,
+      placeholderColor: props.placeholderColor ?? 0,
       zIndex: props.zIndex ?? 0,
       parent: props.parent ?? null,
       texture: props.texture ?? null,

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);
+  });
+});