@solidtv/renderer 1.5.0 → 1.5.2

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,22 @@ 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 === true &&
+            (this.stage.renderOnlyInViewport === false ||
+              this.renderState === CoreNodeRenderState.InViewport),
+        );
         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() ||
@@ -1774,6 +1857,17 @@ export class CoreNode extends EventEmitter {
       newIsRenderable = true;
     }
 
+    // renderOnlyInViewport: nodes in the preload margin keep texture
+    // ownership above (so loading proceeds) but stay out of the render list
+    // until they actually intersect the viewport.
+    if (
+      newIsRenderable === true &&
+      this.stage.renderOnlyInViewport === true &&
+      this.renderState !== CoreNodeRenderState.InViewport
+    ) {
+      newIsRenderable = false;
+    }
+
     this.updateTextureOwnership(needsTextureOwnership);
     this.setRenderable(newIsRenderable);
   }
@@ -2049,6 +2143,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 +2329,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 +2361,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 +2615,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 +3053,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

@@ -1,6 +1,7 @@
 import { describe, expect, it, vi } from 'vitest';
 import { mock } from 'vitest-mock-extended';
 import { CoreTextNode, type CoreTextNodeProps } from './CoreTextNode.js';
+import { CoreNodeRenderState } from './CoreNode.js';
 import { Stage } from './Stage.js';
 import { CoreRenderer } from './renderers/CoreRenderer.js';
 import { createBound } from './lib/utils.js';
@@ -28,6 +29,7 @@ const defaultProps = (
   colorTl: 0xffffffff,
   colorTop: 0xffffffff,
   colorTr: 0xffffffff,
+  placeholderColor: 0,
   h: 0,
   mount: 0,
   mountX: 0,
@@ -143,3 +145,63 @@ describe('CoreTextNode (canvas) clearing text', () => {
     expect(node.isRenderable).toBe(false);
   });
 });
+
+describe('CoreTextNode (sdf) renderOnlyInViewport', () => {
+  const makeSdfRenderer = (): TextRenderer => {
+    const font = mock<FontHandler>({ type: 'sdf' });
+    return {
+      type: 'sdf',
+      font,
+      renderText: vi.fn(),
+      addQuads: vi.fn(),
+      renderQuads: vi.fn(),
+      init: vi.fn(),
+    } as unknown as TextRenderer;
+  };
+
+  function sdfNodeWithLayout(renderOnlyInViewport: boolean): CoreTextNode {
+    const stage = mock<Stage>({
+      strictBound: createBound(0, 0, 200, 200),
+      preloadBound: createBound(0, 0, 400, 200),
+      defaultTexture: { state: 'loaded' } as never,
+      defShaderNode: null as never,
+      renderer: mock<CoreRenderer>() as CoreRenderer,
+      renderOnlyInViewport,
+    });
+    const node = new CoreTextNode(
+      stage,
+      defaultProps({ text: 'Hello' }),
+      makeSdfRenderer(),
+    );
+    (node as unknown as { _cachedLayout: object })._cachedLayout = {};
+    node.worldAlpha = 1;
+    return node;
+  }
+
+  it('off: margin-ring SDF text is renderable (legacy behavior)', () => {
+    const node = sdfNodeWithLayout(false);
+    node.renderState = CoreNodeRenderState.InBounds;
+
+    node.updateIsRenderable();
+
+    expect(node.isRenderable).toBe(true);
+  });
+
+  it('on: margin-ring SDF text stays out of the render list', () => {
+    const node = sdfNodeWithLayout(true);
+    node.renderState = CoreNodeRenderState.InBounds;
+
+    node.updateIsRenderable();
+
+    expect(node.isRenderable).toBe(false);
+  });
+
+  it('on: viewport SDF text is renderable', () => {
+    const node = sdfNodeWithLayout(true);
+    node.renderState = CoreNodeRenderState.InViewport;
+
+    node.updateIsRenderable();
+
+    expect(node.isRenderable).toBe(true);
+  });
+});

package/src/core/CoreTextNode.ts

@@ -227,9 +227,14 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
       return;
     }
 
-    // For SDF, check if we have a cached layout
+    // For SDF, check if we have a cached layout. renderOnlyInViewport gates
+    // SDF text the same way CoreNode gates quads: margin-ring text stays out
+    // of the render list until it intersects the viewport.
     this.setRenderable(
-      this.checkBasicRenderability() === true && this._cachedLayout !== null,
+      this.checkBasicRenderability() === true &&
+        this._cachedLayout !== null &&
+        (this.stage.renderOnlyInViewport === false ||
+          this.renderState === CoreNodeRenderState.InViewport),
     );
   }
 
@@ -271,8 +276,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

@@ -97,6 +97,12 @@ export class Stage {
   public readonly renderer: CoreRenderer;
   public readonly root: CoreNode;
   public boundsMargin: [number, number, number, number];
+  /**
+   * When true, nodes inside the bounds margin but outside the viewport keep
+   * loading textures yet stay out of the render list. Read by
+   * `CoreNode.updateIsRenderable` on the scroll path.
+   */
+  public readonly renderOnlyInViewport: boolean;
   public readonly defShaderNode: CoreShaderNode | null = null;
   public strictBound: Bound;
   public preloadBound: Bound;
@@ -208,6 +214,7 @@ export class Stage {
     setBaselineMode(options.textBaselineMode);
 
     this.platform = platform;
+    this.renderOnlyInViewport = options.renderOnlyInViewport !== false;
 
     this.startTime = platform.getTimeStamp();
 
@@ -382,6 +389,7 @@ export class Stage {
       colorRight: 0x00000000,
       colorTl: 0x00000000,
       colorTr: 0x00000000,
+      placeholderColor: 0x00000000,
       colorBl: 0x00000000,
       colorBr: 0x00000000,
       zIndex: 0,
@@ -1043,6 +1051,7 @@ export class Stage {
       colorTr,
       colorBl,
       colorBr,
+      placeholderColor: props.placeholderColor ?? 0,
       zIndex: props.zIndex ?? 0,
       parent: props.parent ?? null,
       texture: props.texture ?? null,