@solidtv/renderer 1.3.1 → 1.4.0

package/src/core/text-rendering/SdfTextRenderer.test.ts

@@ -0,0 +1,150 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { CoreTextNodeProps } from '../CoreTextNode.js';
+
+// Mock the font handler so renderText/generateTextLayout can run without a
+// real loaded font. getFontData is only invoked on a layout-cache MISS, so the
+// call count is our probe for cache hits vs misses.
+vi.mock('./SdfFontHandler.js', () => {
+  const fontData = {
+    data: {
+      common: { base: 0, scaleW: 512, scaleH: 512, lineHeight: 50 },
+      info: { size: 42 },
+      distanceField: { distanceRange: 4 },
+    },
+    glyphMap: new Map(),
+    kernings: {},
+    atlasTexture: {},
+    metrics: {},
+    maxCharHeight: 50,
+  };
+  const metrics = {
+    ascender: 40,
+    descender: -10,
+    lineGap: 0,
+    capHeight: 30,
+    xHeight: 20,
+  };
+  return {
+    type: 'sdf',
+    init: vi.fn(),
+    getFontData: vi.fn(() => fontData),
+    getFontMetrics: vi.fn(() => metrics),
+    measureText: vi.fn((text: string) => text.length * 10),
+    getAtlas: vi.fn(() => null),
+  };
+});
+
+import SdfTextRenderer from './SdfTextRenderer.js';
+import * as SdfFontHandler from './SdfFontHandler.js';
+
+const makeProps = (text: string): CoreTextNodeProps =>
+  ({
+    text,
+    fontFamily: 'Test',
+    fontStyle: 'normal',
+    fontSize: 42,
+    letterSpacing: 0,
+    lineHeight: 0,
+    maxHeight: 0,
+    maxWidth: 100000,
+    maxLines: 0,
+    textAlign: 'left',
+    wordBreak: 'normal',
+    overflowSuffix: '',
+  } as unknown as CoreTextNodeProps);
+
+const initRenderer = (cacheSize: number): void => {
+  const fakeStage = {
+    options: { textLayoutCacheSize: cacheSize },
+    shManager: {
+      registerShaderType: vi.fn(),
+      createShader: vi.fn(() => ({})),
+    },
+  };
+  SdfTextRenderer.init(fakeStage as never);
+};
+
+const render = (text: string): void => {
+  SdfTextRenderer.renderText(makeProps(text));
+};
+
+describe('SdfTextRenderer layout cache', () => {
+  beforeEach(() => {
+    // Empty the module-level cache between tests, then reset call counts.
+    initRenderer(0);
+    SdfTextRenderer.cleanup();
+    vi.clearAllMocks();
+  });
+
+  it('reuses the cached layout for identical strings', () => {
+    initRenderer(10);
+
+    render('Badge');
+    render('Badge');
+
+    // Second render is a cache hit: no fresh layout generation.
+    expect(SdfFontHandler.getFontData).toHaveBeenCalledTimes(1);
+  });
+
+  it('caches long strings too (no length-based skip)', () => {
+    initRenderer(10);
+    const long = 'x'.repeat(500);
+
+    render(long);
+    render(long);
+
+    // Bounded purely by the LRU cap, not by length.
+    expect(SdfFontHandler.getFontData).toHaveBeenCalledTimes(1);
+  });
+
+  it('cleanup trims to the cap and evicts least-recently-used first', () => {
+    initRenderer(2);
+
+    render('A');
+    render('B');
+    render('C');
+    // Re-access 'A' so it becomes most-recently-used; 'B' is now the LRU.
+    render('A');
+
+    SdfTextRenderer.cleanup();
+
+    vi.clearAllMocks();
+    render('B'); // evicted -> miss
+    render('A'); // survived -> hit
+    render('C'); // survived -> hit
+
+    expect(SdfFontHandler.getFontData).toHaveBeenCalledTimes(1);
+  });
+
+  it('cleanup is a no-op while under the cap', () => {
+    initRenderer(10);
+
+    render('one');
+    render('two');
+
+    SdfTextRenderer.cleanup();
+
+    vi.clearAllMocks();
+    render('one'); // still cached -> hit
+    render('two'); // still cached -> hit
+
+    expect(SdfFontHandler.getFontData).toHaveBeenCalledTimes(0);
+  });
+});
+
+describe('SdfTextRenderer lazy shader compile', () => {
+  it('registers the SDF shader at init but defers compilation', () => {
+    const shManager = {
+      registerShaderType: vi.fn(),
+      createShader: vi.fn(() => ({})),
+    };
+    const fakeStage = { options: { textLayoutCacheSize: 10 }, shManager };
+
+    SdfTextRenderer.init(fakeStage as never);
+
+    // Registration is cheap and stays at boot; the expensive compile + link is
+    // deferred until the first SDF glyph actually renders (see getSdfShader).
+    expect(shManager.registerShaderType).toHaveBeenCalledTimes(1);
+    expect(shManager.createShader).not.toHaveBeenCalled();
+  });
+});

package/src/core/text-rendering/SdfTextRenderer.ts

@@ -24,13 +24,41 @@ const type = 'sdf' as const;
 
 let sdfShader: WebGlShaderNode | null = null;
 
+// Upper bound on layoutCache entries, enforced on idle via `cleanup`.
+// Overridden from stage options in `init`. The cache is allowed to grow past
+// this during active rendering and is trimmed back to it when the stage idles.
+let maxLayoutCacheSize = 250;
+
 // Initialize the SDF text renderer
 const init = (stage: Stage): void => {
   SdfFontHandler.init();
 
-  // Register SDF shader with the shader manager
+  const configuredCacheSize = stage.options.textLayoutCacheSize;
+  if (configuredCacheSize !== undefined) {
+    maxLayoutCacheSize = configuredCacheSize;
+  }
+
+  // Register the SDF shader, but defer the (expensive) compile + link until the
+  // first SDF glyph actually renders — see getSdfShader / renderQuads. SDF fonts
+  // load asynchronously, so the first frame almost never needs the shader, and
+  // compiling it during Stage construction sits on the critical path to first
+  // paint for no benefit.
   stage.shManager.registerShaderType('Sdf', Sdf);
-  sdfShader = stage.shManager.createShader('Sdf') as WebGlShaderNode;
+  sdfShader = null;
+};
+
+/**
+ * Lazily compile (and memoize) the SDF shader on first use.
+ *
+ * @remarks
+ * The shader program is compiled and linked the first time an SDF glyph is
+ * actually drawn, not at boot. Subsequent calls return the cached node.
+ */
+const getSdfShader = (stage: Stage): WebGlShaderNode => {
+  if (sdfShader === null) {
+    sdfShader = stage.shManager.createShader('Sdf') as WebGlShaderNode;
+  }
+  return sdfShader;
 };
 
 const font: FontHandler = SdfFontHandler;
@@ -58,6 +86,11 @@ const renderText = (props: CoreTextNodeProps): TextRenderInfo => {
   const cacheKey = getLayoutCacheKey(props);
   let layout = layoutCache.get(cacheKey);
   if (layout !== undefined) {
+    // Refresh LRU recency: re-insert moves the key to the most-recently-used
+    // end so idle `cleanup` evicts genuinely cold entries first. renderText
+    // runs on text/layout change, not per frame, so this re-insert is cheap.
+    layoutCache.delete(cacheKey);
+    layoutCache.set(cacheKey, layout);
     return {
       remainingLines: 0,
       hasRemainingText: false,
@@ -126,6 +159,8 @@ const renderQuads = (
   const webGlRenderer = renderer as WebGlRenderer;
   const cache = renderProps.sdfCache;
   const ctxTexture = atlasTexture.ctxTexture as WebGlCtxTexture;
+  // Compiles on the first real SDF draw; cheap memoized lookup thereafter.
+  const shader = getSdfShader(webGlRenderer.stage);
 
   // --- Cache-hit fast path ------------------------------------------------
   if (cache !== undefined && cache.vertices !== null) {
@@ -152,7 +187,7 @@ const renderQuads = (
         layout.height,
         renderProps.parentHasRenderTexture,
         renderProps.framebufferDimensions,
-        sdfShader!,
+        shader,
       );
       return null;
     }
@@ -174,7 +209,7 @@ const renderQuads = (
     layout.height,
     renderProps.parentHasRenderTexture,
     renderProps.framebufferDimensions,
-    sdfShader!,
+    shader,
   );
 
   // Snapshot the written vertex data into the cache for future frames
@@ -357,6 +392,20 @@ const generateTextLayout = (
   };
 };
 
+/**
+ * Trim the layout cache back down to `maxLayoutCacheSize`, evicting the
+ * least-recently-used entries first. Called when the stage goes idle so this
+ * never competes with active rendering. A fresh iterator is taken each step so
+ * we always delete the current front (oldest) key without iterator-invalidation
+ * concerns; this runs at most once per idle transition and only when over cap.
+ */
+const cleanup = (): void => {
+  while (layoutCache.size > maxLayoutCacheSize) {
+    const oldest = layoutCache.keys().next().value as string;
+    layoutCache.delete(oldest);
+  }
+};
+
 /**
  * SDF Text Renderer - implements TextRenderer interface
  */
@@ -367,6 +416,7 @@ const SdfTextRenderer = {
   addQuads,
   renderQuads,
   init,
+  cleanup,
 };
 
 export default SdfTextRenderer;

package/src/core/text-rendering/TextRenderer.ts

@@ -435,6 +435,13 @@ export interface TextRenderer {
     renderProps: TextRenderProps,
   ) => void | SdfRenderOp | null;
   init: (stage: Stage) => void;
+  /**
+   * Trim internal caches back down to their configured limits.
+   * Called when the stage goes idle so cache eviction never competes with
+   * active rendering. Backends with no bounded cache may implement this as a
+   * no-op.
+   */
+  cleanup: () => void;
 }
 
 /**

package/src/core/textures/ImageTexture.ts

@@ -269,6 +269,24 @@ export class ImageTexture extends Texture {
   }
 
   override async getTextureSource(): Promise<TextureData> {
+    // Compressed textures are not supported by the Canvas2D renderer.
+    // Fail fast here before incurring a network fetch or binary decode.
+    if (this.txManager.renderer?.mode === 'canvas') {
+      const { src, type } = this.props;
+      if (
+        type === 'compressed' ||
+        (typeof src === 'string' && isCompressedTextureContainer(src) === true)
+      ) {
+        const err = new Error(
+          `ImageTexture: Compressed textures are not supported in Canvas2D render mode (src: ${String(
+            src,
+          )})`,
+        );
+        this.setState('failed', err);
+        return { data: null };
+      }
+    }
+
     let resp: TextureData;
     try {
       resp = await this.determineImageTypeAndLoadImage();

package/src/core/textures/SubTexture.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect, vi } from 'vitest';
+import { SubTexture } from './SubTexture.js';
+import { ImageTexture } from './ImageTexture.js';
+import type { CoreTextureManager } from '../CoreTextureManager.js';
+
+const flushMicrotasks = () => Promise.resolve();
+
+describe('SubTexture lifecycle', () => {
+  it('detaches its parent-texture listeners on destroy', async () => {
+    // 'initial' state means the constructor's microtask attaches listeners
+    // without synchronously firing any of the state handlers.
+    const parent = {
+      state: 'initial',
+      dimensions: null,
+      error: null,
+      on: vi.fn(),
+      off: vi.fn(),
+    };
+    const txManager = {
+      maxRetryCount: 0,
+      platform: {},
+      resolveParentTexture: () => parent,
+    } as unknown as CoreTextureManager;
+
+    const parentImage = new ImageTexture(txManager, {} as never);
+    const sub = new SubTexture(txManager, {
+      texture: parentImage,
+      x: 0,
+      y: 0,
+      w: 10,
+      h: 10,
+    });
+
+    // Listeners are attached in a microtask after construction.
+    await flushMicrotasks();
+    expect(parent.on).toHaveBeenCalledTimes(4);
+
+    sub.destroy();
+
+    const offEvents = (parent.off.mock.calls as Array<[string]>)
+      .map((c) => c[0])
+      .sort();
+    expect(offEvents).toEqual(['failed', 'freed', 'loaded', 'loading']);
+  });
+});

package/src/core/textures/SubTexture.ts

@@ -133,6 +133,19 @@ export class SubTexture extends Texture {
     this.parentTexture.setRenderableOwner(this.subtextureId, isRenderable);
   }
 
+  override destroy(): void {
+    // Detach from the parent texture's event emitter. The parent is typically a
+    // long-lived shared atlas (preventCleanup), so without this each destroyed
+    // SubTexture — and everything its handlers capture — would be retained by
+    // the parent's listener lists for the rest of the session.
+    const parentTx = this.parentTexture;
+    parentTx.off('loading', this.onParentTxLoading);
+    parentTx.off('loaded', this.onParentTxLoaded);
+    parentTx.off('failed', this.onParentTxFailed);
+    parentTx.off('freed', this.onParentTxFreed);
+    super.destroy();
+  }
+
   override async getTextureSource(): Promise<TextureData> {
     // Check if parent texture is loaded
     return new Promise((resolve, reject) => {

package/src/core/textures/Texture.ts

@@ -240,6 +240,11 @@ export abstract class Texture extends EventEmitter {
       return false;
     }
 
+    // Don't cleanup a texture that is in the process of loading
+    if (this.state === 'loading') {
+      return false;
+    }
+
     // Don't cleanup if not renderable
     if (this.renderable === true) {
       return false;
@@ -341,6 +346,9 @@ export abstract class Texture extends EventEmitter {
    */
   free(): void {
     this.ctxTexture?.free();
+    // Null out the freed ctxTexture so a subsequent reload re-creates it via
+    // getCtxTexture() instead of reusing a stale, already-freed reference.
+    this.ctxTexture = undefined;
   }
 
   /**
@@ -370,6 +378,10 @@ export abstract class Texture extends EventEmitter {
 
     // Always free texture data regardless of state
     this.freeTextureData();
+
+    // Drop any remaining subscribers so a texture destroyed while something
+    // still holds a listener does not retain it (and its captures).
+    this.removeAllListeners();
   }
 
   /**

package/src/main-api/Inspector.ts

@@ -230,6 +230,11 @@ const knownProperties = new Set<string>([
   'parent',
   'data',
   'text',
+  'texture',
+  'rtt',
+  'mount',
+  'mountX',
+  'mountY',
   'componentName',
   'componentLocation',
 ]);
@@ -293,6 +298,10 @@ export class Inspector {
   private scaleX = 1;
   private scaleY = 1;
   private textureMetrics = new Map<Texture, TextureMetrics>();
+  // Stable reference so the same function can be passed to both
+  // add/removeEventListener — `.bind()` returns a new fn each call, so binding
+  // inline in destroy() would never actually remove the listener.
+  private boundSetRootPosition = this.setRootPosition.bind(this);
 
   // Performance monitoring for frequent setter calls
   private static setterCallCount = new Map<
@@ -393,7 +402,7 @@ export class Inspector {
     this.resizeObserver.observe(canvas);
 
     //listen for changes on window
-    window.addEventListener('resize', this.setRootPosition.bind(this));
+    window.addEventListener('resize', this.boundSetRootPosition);
 
     // Start animation stats timer if enabled
     this.startAnimationStatsTimer();
@@ -1033,7 +1042,7 @@ export class Inspector {
         });
         coreNodeListeners.clear();
 
-        this.destroyNode(node.id);
+        this.destroyNode(node);
         originalDestroy.call(node, isChild);
       },
       configurable: true,
@@ -1151,7 +1160,7 @@ export class Inspector {
     this.resizeObserver.disconnect();
 
     // Remove resize listener
-    window.removeEventListener('resize', this.setRootPosition.bind(this));
+    window.removeEventListener('resize', this.boundSetRootPosition);
     if (this.root && this.root.parentNode) {
       this.root.remove();
     }
@@ -1160,8 +1169,11 @@ export class Inspector {
     Inspector.clearAnimationStats();
   }
 
-  destroyNode(id: number) {
-    const div = document.getElementById(id.toString());
+  destroyNode(node: CoreNode) {
+    // Use the mirror div stored on the node rather than a document-global
+    // getElementById, which would collide across multiple renderer/inspector
+    // instances sharing one document.
+    const div = (node as CoreNode & { div?: HTMLElement }).div;
     div?.remove();
   }
 
@@ -1180,23 +1192,41 @@ export class Inspector {
      * Special case for parent property
      */
     if (property === 'parent') {
-      const parentId: number = value.id;
-
-      // only way to detect if the parent is the root node
-      // if you are reading this and have a better way, please let me know
-      if (parentId === 1) {
-        this.root.appendChild(div);
-        return;
-      }
+      // value is the parent CoreNode. Its mirror div is stored on the node
+      // itself (see createNode/createTextNode), so use that reference instead
+      // of a document-global getElementById — the latter collides across
+      // multiple renderer/inspector instances sharing one document.
+      //
+      // The stage root (the only node with parent === null) is mirrored by
+      // `this.root`, the container that is actually attached to the document.
+      // createNodes() also makes a plain div for the root node, but that div is
+      // never attached, so the root's direct children must be parented to
+      // `this.root` instead — otherwise the whole mirror tree ends up detached
+      // from the document. This replaces the old `parentId === 1` heuristic.
+      const parentNode = value as CoreNode & { div?: HTMLElement };
+      const parentDiv =
+        parentNode.parent === null ? this.root : parentNode.div ?? this.root;
+      parentDiv.appendChild(div);
+      return;
+    }
 
-      const parent = document.getElementById(parentId.toString());
-      parent?.appendChild(div);
+    // special case for mount changes — mount has no CSS equivalent, but it
+    // shifts the node's left/top, so recompute position from the latest props.
+    if (
+      property === 'mount' ||
+      property === 'mountX' ||
+      property === 'mountY'
+    ) {
+      div.style.left = `${props.x - props.w * (props.mountX ?? 0)}px`;
+      div.style.top = `${props.y - props.h * (props.mountY ?? 0)}px`;
       return;
     }
 
     // special case for text
     if (property === 'text') {
-      div.innerHTML = String(value);
+      // textContent (not innerHTML): text may contain <, &, etc. which would
+      // corrupt the mirror tree or act as an injection vector via innerHTML.
+      div.textContent = String(value);
 
       // Keep DOM text invisible without breaking visibility checks
       // Use very low opacity (0.001) instead of 0 so Playwright still detects it

package/src/main-api/Renderer.ts

@@ -393,6 +393,23 @@ export interface RendererRuntimeSettings {
  * Configuration settings for {@link RendererMain}
  */
 export type RendererMainSettings = RendererRuntimeSettings & {
+  /**
+   * Maximum number of entries kept in the SDF text layout cache
+   *
+   * @remarks
+   * The SDF text renderer caches the computed glyph layout for a given
+   * `text` + font + layout-prop combination so that identical strings (e.g.
+   * repeated badges/labels) are not re-laid-out. The cache is content-keyed
+   * and shared across nodes, and is trimmed down to this many (most recently
+   * used) entries whenever the stage goes idle.
+   *
+   * Set this higher for content-dense UIs with many simultaneous unique
+   * strings, or lower to cap memory more aggressively.
+   *
+   * @defaultValue `250`
+   */
+  textLayoutCacheSize: number;
+
   /**
    * Include context call (i.e. WebGL) information in FPS updates
    *
@@ -497,17 +514,6 @@ export type RendererMainSettings = RendererRuntimeSettings & {
    */
   textBaselineMode: TextBaselineMode;
 
-  /**
-   * Force WebGL2
-   *
-   * @remarks
-   * Force the renderer to use WebGL2. This can be used to force the renderer to
-   * use WebGL2 even if the browser supports WebGL1.
-   *
-   * @defaultValue `false`
-   */
-  forceWebGL2: boolean;
-
   /**
    * Canvas object to use for rendering
    *
@@ -678,10 +684,10 @@ export class RendererMain extends EventEmitter {
       fpsUpdateInterval: settings.fpsUpdateInterval || 0,
       enableClear: settings.enableClear ?? true,
       targetFPS: settings.targetFPS || 0,
+      textLayoutCacheSize: settings.textLayoutCacheSize ?? 250,
       numImageWorkers:
         settings.numImageWorkers !== undefined ? settings.numImageWorkers : 2,
       enableContextSpy: settings.enableContextSpy ?? false,
-      forceWebGL2: settings.forceWebGL2 ?? false,
       inspector: settings.inspector ?? false,
       inspectorOptions: settings.inspectorOptions ?? {},
       renderEngine: settings.renderEngine,
@@ -743,7 +749,6 @@ export class RendererMain extends EventEmitter {
       deviceLogicalPixelRatio,
       devicePhysicalPixelRatio,
       enableContextSpy: settings.enableContextSpy!,
-      forceWebGL2: settings.forceWebGL2!,
       fpsUpdateInterval: settings.fpsUpdateInterval!,
       enableClear: settings.enableClear!,
       numImageWorkers: settings.numImageWorkers!,
@@ -755,6 +760,7 @@ export class RendererMain extends EventEmitter {
       textBaselineMode: settings.textBaselineMode!,
       inspector: settings.inspector !== null,
       targetFPS: settings.targetFPS!,
+      textLayoutCacheSize: settings.textLayoutCacheSize!,
       textureProcessingTimeLimit: settings.textureProcessingTimeLimit!,
       createImageBitmapSupport: settings.createImageBitmapSupport!,
       premultiplyAlphaHonored: settings.premultiplyAlphaHonored,
@@ -922,7 +928,7 @@ export class RendererMain extends EventEmitter {
    */
   destroyNode(node: INode) {
     if (ENABLE_INSPECTOR && this.inspector) {
-      this.inspector.destroyNode(node.id);
+      this.inspector.destroyNode(node as unknown as CoreNode);
     }
 
     return node.destroy();

package/src/utils.ts

@@ -2,7 +2,6 @@ import type { ContextSpy } from './core/lib/ContextSpy.js';
 
 export function createWebGLContext(
   canvas: HTMLCanvasElement | OffscreenCanvas,
-  forceWebGL2 = false,
   contextSpy: ContextSpy | null,
 ): WebGLRenderingContext {
   const config: WebGLContextAttributes = {
@@ -20,7 +19,7 @@ export function createWebGLContext(
   const gl =
     // TODO: Remove this assertion once this issue is fixed in TypeScript
     // https://github.com/microsoft/TypeScript/issues/53614
-    (canvas.getContext(forceWebGL2 ? 'webgl2' : 'webgl', config) ||
+    (canvas.getContext('webgl', config) ||
       canvas.getContext(
         'experimental-webgl' as 'webgl',
         config,

package/src/core/renderers/webgl/internal/WebGlUtils.ts

@@ -1,16 +0,0 @@
-/**
- * Generic WebGL Utility Functions
- *
- * @remarks
- * Nothing here should be coupled to Renderer logic / types.
- *
- * @param gl
- * @returns
- */
-export function isWebGl2(
-  gl: WebGLRenderingContext,
-): gl is WebGL2RenderingContext {
-  return (
-    self.WebGL2RenderingContext && gl instanceof self.WebGL2RenderingContext
-  );
-}