@solidtv/renderer 1.5.1 → 1.5.3

package/src/core/CoreNode.test.ts

@@ -13,6 +13,7 @@ import { premultiplyColorABGR } from '../utils.js';
 describe('set color()', () => {
   const defaultProps = (overrides?: Partial<CoreNodeProps>): CoreNodeProps => ({
     alpha: 0,
+    ignoreParentAlpha: false,
     autosize: false,
     boundsMargin: null,
     clipping: false,
@@ -264,6 +265,112 @@ describe('set color()', () => {
     });
   });
 
+  describe('ignoreParentAlpha', () => {
+    const makeParent = (worldAlpha: number) => {
+      const parent = new CoreNode(stage, defaultProps());
+      parent.globalTransform = Matrix3d.identity();
+      parent.worldAlpha = worldAlpha;
+      return parent;
+    };
+
+    it('multiplies parent world alpha by default', () => {
+      const parent = makeParent(0.5);
+      const node = new CoreNode(stage, defaultProps({ parent, alpha: 0.8 }));
+
+      node.update(0, clippingRect);
+
+      expect(node.worldAlpha).toBeCloseTo(0.4);
+    });
+
+    it('uses own alpha only when enabled', () => {
+      const parent = makeParent(0.5);
+      const node = new CoreNode(
+        stage,
+        defaultProps({ parent, alpha: 0.8, ignoreParentAlpha: true }),
+      );
+
+      node.update(0, clippingRect);
+
+      expect(node.worldAlpha).toBe(0.8);
+    });
+
+    it('keeps its own world alpha while the parent fades toward 0', () => {
+      const parent = makeParent(0.01);
+      const node = new CoreNode(
+        stage,
+        defaultProps({ parent, alpha: 1, ignoreParentAlpha: true }),
+      );
+      node.w = 100;
+      node.h = 100;
+      node.color = 0xffffffff;
+
+      node.update(0, clippingRect);
+
+      expect(node.worldAlpha).toBe(1);
+      expect(node.isRenderable).toBe(true);
+    });
+
+    it('premultiplies colors with the node own alpha when enabled', () => {
+      const parent = makeParent(0.25);
+      const node = new CoreNode(
+        stage,
+        defaultProps({ parent, alpha: 0.8, ignoreParentAlpha: true }),
+      );
+      node.w = 100;
+      node.h = 100;
+      node.color = 0xff0000ff;
+
+      node.update(0, clippingRect);
+
+      expect(node.premultipliedColorTl).toBe(
+        premultiplyColorABGR(0xff0000ff, 0.8),
+      );
+    });
+
+    it('toggling the setter recomputes world alpha', () => {
+      const parent = makeParent(0.5);
+      const node = new CoreNode(stage, defaultProps({ parent, alpha: 0.8 }));
+
+      node.update(0, clippingRect);
+      expect(node.worldAlpha).toBeCloseTo(0.4);
+
+      node.ignoreParentAlpha = true;
+      node.update(1, clippingRect);
+      expect(node.worldAlpha).toBe(0.8);
+
+      node.ignoreParentAlpha = false;
+      node.update(2, clippingRect);
+      expect(node.worldAlpha).toBeCloseTo(0.4);
+    });
+
+    it('setting the same value does not flag an update', () => {
+      const node = new CoreNode(stage, defaultProps());
+      const updateTypeBefore = node.updateType;
+
+      node.ignoreParentAlpha = false;
+
+      expect(node.updateType).toBe(updateTypeBefore);
+    });
+
+    it('descendants inherit the node world alpha as usual', () => {
+      const parent = makeParent(0.5);
+      const node = new CoreNode(
+        stage,
+        defaultProps({ parent, alpha: 0.8, ignoreParentAlpha: true }),
+      );
+      const child = new CoreNode(
+        stage,
+        defaultProps({ parent: node, alpha: 0.5 }),
+      );
+
+      node.update(0, clippingRect);
+      child.update(0, clippingRect);
+
+      expect(node.worldAlpha).toBe(0.8);
+      expect(child.worldAlpha).toBeCloseTo(0.4);
+    });
+  });
+
   describe('autosize system', () => {
     it('should initialize with autosize disabled', () => {
       const node = new CoreNode(stage, defaultProps());
@@ -1463,4 +1570,146 @@ describe('set color()', () => {
       expect(node.renderTexture).toBe(texture);
     });
   });
+
+  describe('renderOnlyInViewport', () => {
+    // Viewport is 0..200; the preload (bounds-margin) ring extends to 400.
+    // A node at x=250 is InBounds (margin ring); at x=50 it is InViewport;
+    // at x=500 it is OutOfBounds.
+    function boundsStage(renderOnlyInViewport: boolean): Stage {
+      return mock<Stage>({
+        strictBound: createBound(0, 0, 200, 200),
+        preloadBound: createBound(0, 0, 400, 200),
+        defaultTexture: {
+          state: 'loaded',
+        },
+        renderer: mock<CoreRenderer>() as CoreRenderer,
+        renderOnlyInViewport,
+      });
+    }
+
+    function loadedTextureNode(stage: Stage, x: number): CoreNode {
+      const parent = new CoreNode(stage, defaultProps());
+      parent.globalTransform = Matrix3d.identity();
+      parent.worldAlpha = 1;
+
+      const node = new CoreNode(stage, defaultProps({ parent }));
+      node.alpha = 1;
+      node.x = x;
+      node.y = 0;
+      node.w = 100;
+      node.h = 100;
+      node.texture = mock<ImageTexture>({
+        state: 'loaded',
+        setRenderableOwner: vi.fn(),
+      });
+      node.textureLoaded = true;
+      return node;
+    }
+
+    it('off: a margin-ring node is renderable (legacy behavior)', () => {
+      const node = loadedTextureNode(boundsStage(false), 250);
+
+      node.update(0, clippingRect);
+
+      expect(node.isRenderable).toBe(true);
+    });
+
+    it('on: a margin-ring node is not renderable but still owns its texture', () => {
+      const node = loadedTextureNode(boundsStage(true), 250);
+
+      node.update(0, clippingRect);
+
+      expect(node.isRenderable).toBe(false);
+      // Ownership is the load trigger and cleanup protection — it must stay.
+      expect(node.texture!.setRenderableOwner).toHaveBeenCalledWith(
+        expect.anything(),
+        true,
+      );
+    });
+
+    it('on: a viewport node is renderable', () => {
+      const node = loadedTextureNode(boundsStage(true), 50);
+
+      node.update(0, clippingRect);
+
+      expect(node.isRenderable).toBe(true);
+    });
+
+    it('on: a node becomes renderable when it crosses into the viewport', () => {
+      const node = loadedTextureNode(boundsStage(true), 250);
+      node.update(0, clippingRect);
+      expect(node.isRenderable).toBe(false);
+
+      // Scroll it in.
+      node.x = 50;
+      node.update(1, clippingRect);
+      expect(node.isRenderable).toBe(true);
+
+      // And back out into the ring.
+      node.x = 250;
+      node.update(2, clippingRect);
+      expect(node.isRenderable).toBe(false);
+    });
+
+    it('on: an out-of-bounds node releases texture ownership', () => {
+      const node = loadedTextureNode(boundsStage(true), 500);
+
+      node.update(0, clippingRect);
+
+      expect(node.isRenderable).toBe(false);
+      expect(node.texture!.setRenderableOwner).not.toHaveBeenCalledWith(
+        expect.anything(),
+        true,
+      );
+    });
+
+    it('on: a margin-ring placeholder is gated the same way', () => {
+      const stage = boundsStage(true);
+      const parent = new CoreNode(stage, defaultProps());
+      parent.globalTransform = Matrix3d.identity();
+      parent.worldAlpha = 1;
+
+      const node = new CoreNode(stage, defaultProps({ parent }));
+      node.alpha = 1;
+      node.x = 250;
+      node.y = 0;
+      node.w = 100;
+      node.h = 100;
+      node.placeholderColor = 0x336699ff;
+      node.texture = mock<ImageTexture>({
+        state: 'initial',
+        setRenderableOwner: vi.fn(),
+      });
+
+      node.update(0, clippingRect);
+      expect(node.placeholderActive).toBe(true);
+      expect(node.isRenderable).toBe(false);
+
+      node.x = 50;
+      node.update(1, clippingRect);
+      expect(node.isRenderable).toBe(true);
+    });
+
+    it('on: color-only nodes in the margin ring are gated too', () => {
+      const stage = boundsStage(true);
+      const parent = new CoreNode(stage, defaultProps());
+      parent.globalTransform = Matrix3d.identity();
+      parent.worldAlpha = 1;
+
+      const node = new CoreNode(stage, defaultProps({ parent }));
+      node.alpha = 1;
+      node.x = 250;
+      node.y = 0;
+      node.w = 100;
+      node.h = 100;
+      node.color = 0xff0000ff;
+
+      node.update(0, clippingRect);
+      expect(node.isRenderable).toBe(false);
+
+      node.x = 50;
+      node.update(1, clippingRect);
+      expect(node.isRenderable).toBe(true);
+    });
+  });
 });

package/src/core/CoreNode.ts

@@ -46,7 +46,7 @@ import type { IAnimationController } from '../common/IAnimationController.js';
 import { createAnimation } from './animations/CoreAnimation.js';
 import type { CoreShaderNode } from './renderers/CoreShaderNode.js';
 import { AutosizeMode, Autosizer } from './Autosizer.js';
-import { removeChild } from './lib/collectionUtils.js';
+import { removeChild, sortByZIndexStable } from './lib/collectionUtils.js';
 
 export enum CoreNodeRenderState {
   Init = 0,
@@ -63,11 +63,6 @@ const NO_CLIPPING_RECT: RectWithValid = {
   valid: false,
 };
 
-// Hoisted so `sortChildren` doesn't allocate a fresh comparator closure on
-// every z-index reorder.
-const compareZIndex = (a: CoreNode, b: CoreNode): number =>
-  a.props.zIndex - b.props.zIndex;
-
 const CoreNodeRenderStateMap: Map<CoreNodeRenderState, string> = new Map();
 CoreNodeRenderStateMap.set(CoreNodeRenderState.Init, 'init');
 CoreNodeRenderStateMap.set(CoreNodeRenderState.OutOfBounds, 'outOfBounds');
@@ -136,6 +131,7 @@ export enum UpdateType {
    * @remarks
    * CoreNode Properties Updated:
    * - `worldAlpha` = `parent.worldAlpha` * `alpha`
+   *   (or just `alpha` when `ignoreParentAlpha` is enabled)
    */
   WorldAlpha = 64,
 
@@ -250,6 +246,29 @@ export interface CoreNodeProps {
    * @default `1`
    */
   alpha: number;
+  /**
+   * When enabled, the Node's world alpha is computed from its own
+   * {@link alpha} only, ignoring the alpha inherited from its ancestors.
+   *
+   * @remarks
+   * Normally `worldAlpha = parent.worldAlpha * alpha`, so fading a parent
+   * fades every descendant with it. With `ignoreParentAlpha` enabled this
+   * Node keeps rendering at its own alpha while its parent (and the rest of
+   * the subtree) fades.
+   *
+   * Subtrees whose world alpha reaches exactly 0 are culled from rendering
+   * entirely, so this Node still disappears once an ancestor hits alpha 0 —
+   * the prop only has an effect while every ancestor's alpha is above 0.
+   * This keeps the fully-transparent subtree cull free of bookkeeping.
+   *
+   * Descendants of this Node inherit from its world alpha as usual.
+   *
+   * Has no effect inside a render-to-texture subtree: the RTT root's
+   * composited quad is still faded as a single unit by its own world alpha.
+   *
+   * @default `false`
+   */
+  ignoreParentAlpha: boolean;
   /**
    * Autosize
    *
@@ -1453,7 +1472,10 @@ export class CoreNode extends EventEmitter {
     }
 
     if (updateType & UpdateType.WorldAlpha) {
-      this.worldAlpha = parent.worldAlpha * this.props.alpha;
+      this.worldAlpha =
+        props.ignoreParentAlpha === true
+          ? props.alpha
+          : parent.worldAlpha * props.alpha;
       updateType |=
         UpdateType.PremultipliedColors |
         UpdateType.Children |
@@ -1833,7 +1855,11 @@ export class CoreNode extends EventEmitter {
         // 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(this.placeholderActive);
+        this.setRenderable(
+          this.placeholderActive === true &&
+            (this.stage.renderOnlyInViewport === false ||
+              this.renderState === CoreNodeRenderState.InViewport),
+        );
         return;
       }
 
@@ -1853,6 +1879,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);
   }
@@ -2165,7 +2202,7 @@ export class CoreNode extends EventEmitter {
   }
 
   sortChildren() {
-    this.children.sort(compareZIndex);
+    sortByZIndexStable(this.children);
     this.stage.requestRenderListUpdate();
   }
 
@@ -2508,6 +2545,24 @@ export class CoreNode extends EventEmitter {
     this.childUpdateType |= UpdateType.WorldAlpha;
   }
 
+  get ignoreParentAlpha(): boolean {
+    return this.props.ignoreParentAlpha;
+  }
+
+  set ignoreParentAlpha(value: boolean) {
+    if (this.props.ignoreParentAlpha === value) {
+      return;
+    }
+    this.props.ignoreParentAlpha = value;
+    this.setUpdateType(
+      UpdateType.PremultipliedColors |
+        UpdateType.WorldAlpha |
+        UpdateType.Children |
+        UpdateType.IsRenderable,
+    );
+    this.childUpdateType |= UpdateType.WorldAlpha;
+  }
+
   get autosize(): boolean {
     return this.props.autosize;
   }

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';
@@ -16,6 +17,7 @@ const defaultProps = (
 ): CoreTextNodeProps => ({
   // CoreNodeProps
   alpha: 1,
+  ignoreParentAlpha: false,
   autosize: false,
   boundsMargin: null,
   clipping: false,
@@ -144,3 +146,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),
     );
   }
 

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();
 
@@ -372,6 +379,7 @@ export class Stage {
       w: appWidth,
       h: appHeight,
       alpha: 1,
+      ignoreParentAlpha: false,
       autosize: false,
       boundsMargin: null,
       clipping: false,
@@ -1032,6 +1040,7 @@ export class Stage {
       w: props.w ?? 0,
       h: props.h ?? 0,
       alpha: props.alpha ?? 1,
+      ignoreParentAlpha: props.ignoreParentAlpha ?? false,
       autosize: props.autosize ?? false,
       boundsMargin: props.boundsMargin ?? null,
       clipping: props.clipping ?? false,

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

@@ -0,0 +1,91 @@
+import { describe, it, expect } from 'vitest';
+import type { CoreNode } from '../CoreNode.js';
+import { sortByZIndexStable } from './collectionUtils.js';
+
+const makeNode = (zIndex: number, tag: number): CoreNode =>
+  ({ props: { zIndex }, tag } as unknown as CoreNode);
+
+const tags = (nodes: CoreNode[]): number[] => {
+  const out: number[] = [];
+  for (let i = 0; i < nodes.length; i++) {
+    out.push((nodes[i] as unknown as { tag: number }).tag);
+  }
+  return out;
+};
+
+describe('sortByZIndexStable', () => {
+  it('should sort nodes ascending by zIndex', () => {
+    const nodes = [makeNode(3, 0), makeNode(1, 1), makeNode(2, 2)];
+
+    sortByZIndexStable(nodes);
+
+    expect(tags(nodes)).toEqual([1, 2, 0]);
+  });
+
+  it('should preserve insertion order for equal zIndex values', () => {
+    const nodes = [
+      makeNode(1, 0),
+      makeNode(0, 1),
+      makeNode(1, 2),
+      makeNode(0, 3),
+      makeNode(1, 4),
+    ];
+
+    sortByZIndexStable(nodes);
+
+    expect(tags(nodes)).toEqual([1, 3, 0, 2, 4]);
+  });
+
+  it('should be stable for arrays longer than 10 elements', () => {
+    // V8 on Chrome < 70 switched to an unstable quicksort above 10 elements;
+    // this guards the case the native sort got wrong.
+    const nodes: CoreNode[] = [];
+    for (let i = 0; i < 20; i++) {
+      nodes.push(makeNode(i % 2, i));
+    }
+
+    sortByZIndexStable(nodes);
+
+    const expected: number[] = [];
+    for (let i = 0; i < 20; i += 2) {
+      expected.push(i);
+    }
+    for (let i = 1; i < 20; i += 2) {
+      expected.push(i);
+    }
+    expect(tags(nodes)).toEqual(expected);
+  });
+
+  it('should handle negative and fractional zIndex values', () => {
+    const nodes = [
+      makeNode(0.5, 0),
+      makeNode(-2, 1),
+      makeNode(1000000000, 2),
+      makeNode(0, 3),
+      makeNode(-2, 4),
+    ];
+
+    sortByZIndexStable(nodes);
+
+    expect(tags(nodes)).toEqual([1, 4, 3, 0, 2]);
+  });
+
+  it('should leave an already sorted array unchanged', () => {
+    const nodes = [makeNode(0, 0), makeNode(0, 1), makeNode(1, 2)];
+
+    sortByZIndexStable(nodes);
+
+    expect(tags(nodes)).toEqual([0, 1, 2]);
+  });
+
+  it('should handle empty and single-element arrays', () => {
+    const empty: CoreNode[] = [];
+    const single = [makeNode(5, 0)];
+
+    sortByZIndexStable(empty);
+    sortByZIndexStable(single);
+
+    expect(empty.length).toBe(0);
+    expect(tags(single)).toEqual([0]);
+  });
+});

package/src/core/lib/collectionUtils.ts

@@ -1,44 +1,23 @@
 import type { CoreNode } from '../CoreNode.js';
 
-//Bucket sort implementation for sorting CoreNode arrays by zIndex
-export const bucketSortByZIndex = (nodes: CoreNode[], min: number): void => {
-  const buckets: CoreNode[][] = [];
-  const bucketIndices: number[] = [];
-  //distribute nodes into buckets
-  for (let i = 0; i < nodes.length; i++) {
+// Stable in-place sort by zIndex. Array.prototype.sort is not stable on
+// Chrome < 70 (V8 quicksorts arrays longer than 10), and equal-zIndex
+// siblings must keep insertion order or paint order silently reshuffles.
+// Children arrays are small and nearly sorted (kept sorted; a re-sort
+// usually follows a single zIndex change), so insertion sort is O(n) in
+// practice and allocation-free.
+export const sortByZIndexStable = (nodes: CoreNode[]): void => {
+  const len = nodes.length;
+  for (let i = 1; i < len; i++) {
     const node = nodes[i]!;
-    const index = node.props.zIndex - min;
-    //create bucket if it doesn't exist
-    if (buckets[index] === undefined) {
-      buckets[index] = [];
-      bucketIndices.push(index);
-    }
-    buckets[index]!.push(node);
-  }
-
-  //sort each bucket using insertion sort
-  for (let i = 1; i < bucketIndices.length; i++) {
-    const key = bucketIndices[i]!;
+    const z = node.props.zIndex;
     let j = i - 1;
-    while (j >= 0 && bucketIndices[j]! > key) {
-      bucketIndices[j + 1] = bucketIndices[j]!;
+    while (j >= 0 && nodes[j]!.props.zIndex > z) {
+      nodes[j + 1] = nodes[j]!;
       j--;
     }
-    bucketIndices[j + 1] = key;
+    nodes[j + 1] = node;
   }
-
-  //flatten buckets
-  let idx = 0;
-  for (let i = 0; i < bucketIndices.length; i++) {
-    const bucket = buckets[bucketIndices[i]!]!;
-    for (let j = 0; j < bucket.length; j++) {
-      nodes[idx++] = bucket[j]!;
-    }
-  }
-
-  //clean up
-  buckets.length = 0;
-  bucketIndices.length = 0;
 };
 
 export const incrementalRepositionByZIndex = (