@solidtv/renderer 1.5.0-1 → 1.5.0

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

@@ -0,0 +1,158 @@
+import { describe, it, expect, vi } from 'vitest';
+import { uploadCompressedTexture } from './textureCompression.js';
+import type { WebGlContextWrapper } from './WebGlContextWrapper.js';
+import type { CompressedData } from '../textures/Texture.js';
+
+/**
+ * A compressed format enum is only valid in compressedTexImage2D after its
+ * owning extension has been enabled via getExtension; otherwise the driver
+ * rejects it with GL_INVALID_ENUM (1280). These tests pin that every upload
+ * path enables its extension *before* uploading, and fails loudly when the
+ * device exposes none of the candidates.
+ */
+
+interface MockGlw {
+  glw: WebGlContextWrapper;
+  order: string[];
+  getExtension: ReturnType<typeof vi.fn>;
+  compressedTexImage2D: ReturnType<typeof vi.fn>;
+}
+
+function makeGlw(supported: Set<string>): MockGlw {
+  const order: string[] = [];
+  const getExtension = vi.fn((name: string) => {
+    order.push(`getExtension:${name}`);
+    return supported.has(name) === true ? {} : null;
+  });
+  const compressedTexImage2D = vi.fn(() => {
+    order.push('compressedTexImage2D');
+  });
+  const glw = {
+    getExtension,
+    compressedTexImage2D,
+    bindTexture: vi.fn(),
+    texParameteri: vi.fn(),
+    TEXTURE_WRAP_S: 0,
+    TEXTURE_WRAP_T: 0,
+    TEXTURE_MAG_FILTER: 0,
+    TEXTURE_MIN_FILTER: 0,
+    CLAMP_TO_EDGE: 0,
+    LINEAR: 0,
+    LINEAR_MIPMAP_LINEAR: 0,
+  } as unknown as WebGlContextWrapper;
+  return { glw, order, getExtension, compressedTexImage2D };
+}
+
+function makeData(
+  type: 'ktx' | 'pvr' | 'astc',
+  glInternalFormat: number,
+): CompressedData {
+  return {
+    type,
+    glInternalFormat,
+    w: 4,
+    h: 4,
+    mipmaps: [new ArrayBuffer(16)],
+    blockInfo: { width: 4, height: 4, bytes: 16 },
+  };
+}
+
+const texture = {} as WebGLTexture;
+
+// COMPRESSED_RGBA_S3TC_DXT5_EXT
+const S3TC_DXT5 = 0x83f3;
+// COMPRESSED_RGB_PVRTC_4BPPV1_IMG
+const PVRTC_4BPP = 0x8c00;
+// COMPRESSED_RGB_ETC1_WEBGL
+const ETC1 = 0x8d64;
+// COMPRESSED_RGBA_ASTC_4x4_KHR
+const ASTC_4x4 = 0x93b0;
+
+describe('compressed texture extension guards', () => {
+  it('KTX enables the s3tc extension before uploading', () => {
+    const m = makeGlw(new Set(['WEBGL_compressed_texture_s3tc']));
+    uploadCompressedTexture.ktx!(m.glw, texture, makeData('ktx', S3TC_DXT5));
+
+    expect(m.getExtension).toHaveBeenCalledWith(
+      'WEBGL_compressed_texture_s3tc',
+    );
+    expect(m.compressedTexImage2D).toHaveBeenCalled();
+    // getExtension must precede the first compressedTexImage2D call
+    expect(m.order.indexOf('getExtension:WEBGL_compressed_texture_s3tc')).toBe(
+      0,
+    );
+    expect(
+      m.order.indexOf('getExtension:WEBGL_compressed_texture_s3tc') <
+        m.order.indexOf('compressedTexImage2D'),
+    ).toBe(true);
+  });
+
+  it('KTX throws (no silent 1280) when the s3tc extension is unavailable', () => {
+    const m = makeGlw(new Set());
+    expect(() =>
+      uploadCompressedTexture.ktx!(m.glw, texture, makeData('ktx', S3TC_DXT5)),
+    ).toThrow(/not supported/);
+    expect(m.compressedTexImage2D).not.toHaveBeenCalled();
+  });
+
+  it('KTX enables the etc1 extension for ETC1 formats', () => {
+    const m = makeGlw(new Set(['WEBGL_compressed_texture_etc1']));
+    uploadCompressedTexture.ktx!(m.glw, texture, makeData('ktx', ETC1));
+    expect(m.getExtension).toHaveBeenCalledWith(
+      'WEBGL_compressed_texture_etc1',
+    );
+    expect(m.compressedTexImage2D).toHaveBeenCalled();
+  });
+
+  it('PVR enables the pvrtc extension before uploading', () => {
+    const m = makeGlw(new Set(['WEBGL_compressed_texture_pvrtc']));
+    uploadCompressedTexture.pvr!(m.glw, texture, makeData('pvr', PVRTC_4BPP));
+    expect(m.getExtension).toHaveBeenCalledWith(
+      'WEBGL_compressed_texture_pvrtc',
+    );
+    expect(
+      m.order.indexOf('getExtension:WEBGL_compressed_texture_pvrtc') <
+        m.order.indexOf('compressedTexImage2D'),
+    ).toBe(true);
+  });
+
+  it('PVR falls back to the WebKit-prefixed pvrtc extension', () => {
+    const m = makeGlw(new Set(['WEBKIT_WEBGL_compressed_texture_pvrtc']));
+    uploadCompressedTexture.pvr!(m.glw, texture, makeData('pvr', PVRTC_4BPP));
+    expect(m.getExtension).toHaveBeenCalledWith(
+      'WEBGL_compressed_texture_pvrtc',
+    );
+    expect(m.getExtension).toHaveBeenCalledWith(
+      'WEBKIT_WEBGL_compressed_texture_pvrtc',
+    );
+    expect(m.compressedTexImage2D).toHaveBeenCalled();
+  });
+
+  it('PVR throws when neither pvrtc extension is available', () => {
+    const m = makeGlw(new Set());
+    expect(() =>
+      uploadCompressedTexture.pvr!(m.glw, texture, makeData('pvr', PVRTC_4BPP)),
+    ).toThrow(/not supported/);
+    expect(m.compressedTexImage2D).not.toHaveBeenCalled();
+  });
+
+  it('ASTC enables the astc extension before uploading', () => {
+    const m = makeGlw(new Set(['WEBGL_compressed_texture_astc']));
+    uploadCompressedTexture.astc!(m.glw, texture, makeData('astc', ASTC_4x4));
+    expect(m.getExtension).toHaveBeenCalledWith(
+      'WEBGL_compressed_texture_astc',
+    );
+    expect(
+      m.order.indexOf('getExtension:WEBGL_compressed_texture_astc') <
+        m.order.indexOf('compressedTexImage2D'),
+    ).toBe(true);
+  });
+
+  it('ASTC throws when the astc extension is unavailable', () => {
+    const m = makeGlw(new Set());
+    expect(() =>
+      uploadCompressedTexture.astc!(m.glw, texture, makeData('astc', ASTC_4x4)),
+    ).toThrow(/not supported/);
+    expect(m.compressedTexImage2D).not.toHaveBeenCalled();
+  });
+});

package/src/core/lib/textureCompression.ts

@@ -171,18 +171,90 @@ const loadASTC = async function (view: DataView): Promise<TextureData> {
   };
 };
 
+// Candidate extension name lists, hoisted to module constants so the per-upload
+// resolver returns a shared reference instead of allocating a new array each
+// call (zero GC pressure on the texture-upload path).
+const EXT_ASTC = ['WEBGL_compressed_texture_astc'];
+const EXT_S3TC = ['WEBGL_compressed_texture_s3tc'];
+const EXT_ETC1 = ['WEBGL_compressed_texture_etc1'];
+const EXT_ETC = ['WEBGL_compressed_texture_etc'];
+// WebKit-prefixed name is the legacy fallback.
+const EXT_PVRTC = [
+  'WEBGL_compressed_texture_pvrtc',
+  'WEBKIT_WEBGL_compressed_texture_pvrtc',
+];
+const EXT_NONE: string[] = [];
+
+/**
+ * Resolve the WebGL extension(s) that must be enabled before a given compressed
+ * GL internal format may be used.
+ *
+ * @remarks
+ * `getExtension` is the call that actually enables a compressed format on a
+ * context — until it is called, the format enum is rejected by
+ * `compressedTexImage2D` with `GL_INVALID_ENUM` (1280). Listed in priority
+ * order; the first name the device exposes is used.
+ */
+const requiredExtensionsForFormat = (glInternalFormat: number): string[] => {
+  // ASTC (incl. sRGB variants): 0x93b0–0x93d5
+  if (glInternalFormat >= 0x93b0 && glInternalFormat <= 0x93d5) {
+    return EXT_ASTC;
+  }
+  // S3TC / DXTn: 0x83f0–0x83f3
+  if (glInternalFormat >= 0x83f0 && glInternalFormat <= 0x83f3) {
+    return EXT_S3TC;
+  }
+  // ETC1: 0x8d64
+  if (glInternalFormat === 0x8d64) {
+    return EXT_ETC1;
+  }
+  // ETC2 / EAC: 0x9274–0x9279
+  if (glInternalFormat >= 0x9274 && glInternalFormat <= 0x9279) {
+    return EXT_ETC;
+  }
+  // PVRTC: 0x8c00–0x8c03
+  if (glInternalFormat >= 0x8c00 && glInternalFormat <= 0x8c03) {
+    return EXT_PVRTC;
+  }
+  return EXT_NONE;
+};
+
+/**
+ * Enable the extension owning `glInternalFormat` so the format enum is valid in
+ * `compressedTexImage2D`, throwing a clear error if the device exposes none of
+ * the candidate extensions (instead of leaking a silent `GL_INVALID_ENUM`).
+ */
+const ensureCompressedFormatEnabled = (
+  glw: WebGlContextWrapper,
+  glInternalFormat: number,
+): void => {
+  const names = requiredExtensionsForFormat(glInternalFormat);
+  const len = names.length;
+  if (len === 0) {
+    return;
+  }
+  for (let i = 0; i < len; i++) {
+    if (glw.getExtension(names[i]!) !== null) {
+      return;
+    }
+  }
+  throw new Error(
+    `Compressed texture format 0x${glInternalFormat.toString(
+      16,
+    )} is not supported by this device (requires ${names.join(' or ')})`,
+  );
+};
+
 const uploadASTC = function (
   glw: WebGlContextWrapper,
   texture: WebGLTexture,
   data: CompressedData,
 ) {
-  if (glw.getExtension('WEBGL_compressed_texture_astc') === null) {
-    throw new Error('ASTC compressed textures not supported by this device');
-  }
+  const { glInternalFormat, mipmaps, w, h } = data;
+  ensureCompressedFormatEnabled(glw, glInternalFormat);
 
   glw.bindTexture(texture);
 
-  const { glInternalFormat, mipmaps, w, h } = data;
   if (mipmaps === undefined) {
     return;
   }
@@ -277,6 +349,7 @@ const uploadKTX = function (
   data: CompressedData,
 ) {
   const { glInternalFormat, mipmaps, w: width, h: height, blockInfo } = data;
+  ensureCompressedFormatEnabled(glw, glInternalFormat);
   if (mipmaps === undefined) {
     return;
   }
@@ -415,6 +488,7 @@ const uploadPVR = function (
   data: CompressedData,
 ) {
   const { glInternalFormat, mipmaps, w: width, h: height } = data;
+  ensureCompressedFormatEnabled(glw, glInternalFormat);
   if (mipmaps === undefined) {
     return;
   }

package/src/core/renderers/CoreRenderer.ts

@@ -11,6 +11,7 @@ export interface CoreRendererOptions {
   canvas: HTMLCanvasElement | OffscreenCanvas;
   contextSpy: ContextSpy | null;
   forceWebGL2: boolean;
+  disableVertexArrayObject: boolean;
 }
 
 export interface BufferInfo {

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

@@ -48,6 +48,19 @@ const GL_OUT_OF_MEMORY = 0x0505;
  */
 const MAX_DRAINED_GL_ERRORS = 8;
 
+/**
+ * Dirty-ratio cutoff that flips the per-frame quad upload from surgical
+ * `bufferSubData` (one call per changed node) to a single full `bufferData`.
+ *
+ * The surgical path wins when few nodes change per frame (typical UI), but
+ * degrades to one GL call per node when most of the scene moves at once
+ * (full-screen animation, scroll, zoom). At that point a single bulk upload is
+ * cheaper than N driver round-trips, so when the number of nodes we would
+ * `bufferSubData` exceeds this fraction of the render list we upload everything
+ * in one call instead. Range 0..1; ~0.4 balances the two regimes.
+ */
+const FULL_UPLOAD_DIRTY_RATIO = 0.4;
+
 export type WebGlRenderOp = CoreNode | SdfRenderOp;
 
 export class WebGlRenderer extends CoreRenderer {
@@ -161,6 +174,14 @@ export class WebGlRenderer extends CoreRenderer {
    * capacity, requiring a full re-upload even when needsFullUpload is false.
    */
   lastUploadedBufferSize = 0;
+  /**
+   * Count of main-scene nodes whose quad data changed this frame and which
+   * own a buffer slot. Accumulated for free during the addQuad pass (which
+   * already branches on isQuadDirty) and consumed in render() to choose
+   * between surgical bufferSubData uploads and a single full bufferData,
+   * avoiding a separate counting loop. Reset each frame in reset().
+   */
+  dirtyQuadCount = 0;
   /**
    * Whether the renderer is currently rendering to a texture.
    */
@@ -187,7 +208,10 @@ export class WebGlRenderer extends CoreRenderer {
       options.forceWebGL2,
       options.contextSpy,
     );
-    const glw = (this.glw = new WebGlContextWrapper(gl));
+    const glw = (this.glw = new WebGlContextWrapper(
+      gl,
+      options.disableVertexArrayObject,
+    ));
     glw.viewport(0, 0, options.canvas.width, options.canvas.height);
 
     this.attachContextLossListeners(options.canvas);
@@ -346,6 +370,7 @@ export class WebGlRenderer extends CoreRenderer {
     }
     this.curRenderOp = null;
     this.curSdfRenderOp = null;
+    this.dirtyQuadCount = 0;
     this.sdfBufferIdx = 0;
     this.sdfQuadCount = 0;
     this.renderOps.length = 0;
@@ -496,6 +521,14 @@ export class WebGlRenderer extends CoreRenderer {
     // The GPU upload is deferred to render().
     // During RTT, always write since the buffer is rebuilt from scratch.
     if (!DIRTY_QUAD_BUFFER || isRTT || node.isQuadDirty) {
+      // Count main-scene dirty nodes here, while we already have the node in
+      // hand, so render() can pick full vs. surgical upload without a second
+      // pass over the render list. Slot is guaranteed assigned at this point
+      // (i = quadBufferIndex above), so no quadBufferIndex !== -1 guard needed.
+      if (DIRTY_QUAD_BUFFER && isRTT === false && node.isQuadDirty === true) {
+        this.dirtyQuadCount++;
+      }
+
       const rc = node.renderCoords!;
       const tc = node.textureCoords || this.defaultTextureCoords;
 
@@ -966,31 +999,41 @@ export class WebGlRenderer extends CoreRenderer {
     const BYTES = Float32Array.BYTES_PER_ELEMENT;
 
     if (DIRTY_QUAD_BUFFER) {
-      if (
-        this.needsFullUpload ||
-        this.curBufferIdx > this.lastUploadedBufferSize
-      ) {
-        // Full GPU re-allocation: covers new nodes and structural reorders.
-        // Also triggered when curBufferIdx has grown beyond the last uploaded
-        // size (e.g. after RTT rendering consumed needsFullUpload and then
-        // the main scene added more quads).
-        // Uses DYNAMIC_DRAW to signal to the driver that the buffer will be
-        // updated frequently in smaller pieces going forward.
+      const renderList = this.stage.renderList;
+      const len = renderList.length;
+
+      // Growth/realloc always forces a full upload (new nodes, structural
+      // reorders, or curBufferIdx grown past the last uploaded size).
+      let fullUpload =
+        this.needsFullUpload || this.curBufferIdx > this.lastUploadedBufferSize;
+
+      // Otherwise decide adaptively: if the number of nodes we would upload
+      // surgically exceeds FULL_UPLOAD_DIRTY_RATIO of the render list, a single
+      // bufferData is cheaper than that many bufferSubData calls. The count was
+      // accumulated for free during the addQuad pass (dirtyQuadCount), so no
+      // separate counting loop is needed here.
+      if (fullUpload === false) {
+        fullUpload = this.dirtyQuadCount > len * FULL_UPLOAD_DIRTY_RATIO;
+      }
+
+      if (fullUpload === true) {
+        // Full GPU re-allocation: covers the growth/realloc cases above and the
+        // "most of the scene changed" case where one bulk upload beats N
+        // per-node uploads. Uses DYNAMIC_DRAW to signal to the driver that the
+        // buffer will be updated frequently going forward.
         const arr = new Float32Array(quadBuffer, 0, this.curBufferIdx);
         glw.arrayBufferData(buffer, arr, glw.DYNAMIC_DRAW);
         this.needsFullUpload = false;
         this.lastUploadedBufferSize = this.curBufferIdx;
 
         // Clear dirty flags since we just uploaded everything.
-        const renderList = this.stage.renderList;
-        for (let i = 0, len = renderList.length; i < len; i++) {
+        for (let i = 0; i < len; i++) {
           renderList[i]!.isQuadDirty = false;
         }
       } else {
         // Surgical per-node uploads: only write the 20 float32s for nodes
         // whose quad data changed since the last frame.
-        const renderList = this.stage.renderList;
-        for (let i = 0, len = renderList.length; i < len; i++) {
+        for (let i = 0; i < len; i++) {
           const node = renderList[i]!;
           if (node.isQuadDirty && node.quadBufferIndex !== -1) {
             const byteOffset = node.quadBufferIndex * BYTES;

package/src/core/renderers/webgl/internal/RendererUtils.test.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect } from 'vitest';
+import { createIndexBuffer } from './RendererUtils.js';
+import type { WebGlContextWrapper } from '../../../lib/WebGlContextWrapper.js';
+
+// Capture the Uint16Array handed to elementArrayBufferData so we can assert on
+// the generated quad indices without a real GL context.
+function mockGlw(): {
+  glw: WebGlContextWrapper;
+  getIndices: () => Uint16Array;
+} {
+  let captured: Uint16Array | null = null;
+  const glw = {
+    STATIC_DRAW: 0,
+    createBuffer: () => ({}),
+    elementArrayBufferData: (_buffer: unknown, indices: Uint16Array) => {
+      captured = indices;
+    },
+  } as unknown as WebGlContextWrapper;
+  return {
+    glw,
+    getIndices: () => {
+      if (captured === null) {
+        throw new Error('elementArrayBufferData was not called');
+      }
+      return captured;
+    },
+  };
+}
+
+// The expected 6 element indices for quad `q`: two triangles over the quad's
+// four vertices [4q, 4q+1, 4q+2, 4q+3] wound as [0,1,2, 2,1,3].
+const expectedQuad = (q: number): number[] => {
+  const j = q * 4;
+  return [j, j + 1, j + 2, j + 2, j + 1, j + 3];
+};
+
+describe('createIndexBuffer', () => {
+  it('fills indices for EVERY quad, not just the first 1/6', () => {
+    // size / 80 = 800 quads, comfortably under the Uint16 cap.
+    const { glw, getIndices } = mockGlw();
+    createIndexBuffer(glw, 800 * 80);
+    const indices = getIndices();
+    const maxQuads = 800;
+
+    expect(indices.length).toBe(maxQuads * 6);
+
+    // First, middle and — critically — the LAST quad must be populated. The
+    // original bug stopped the loop at `i < maxQuads`, zeroing every quad past
+    // ~maxQuads/6 and collapsing it into a degenerate triangle.
+    for (const q of [0, 1, maxQuads >> 1, maxQuads - 2, maxQuads - 1]) {
+      const slice = Array.from(indices.subarray(q * 6, q * 6 + 6));
+      expect(slice).toEqual(expectedQuad(q));
+    }
+
+    // No trailing zeroed slots (every quad past index 0 references vertices > 0).
+    const lastQuad = Array.from(indices.subarray((maxQuads - 1) * 6));
+    expect(lastQuad.some((v) => v !== 0)).toBe(true);
+  });
+
+  it('caps at 16384 quads so Uint16 vertex ids never overflow', () => {
+    // Request far more than Uint16 can address (25000 quads worth of bytes).
+    const { glw, getIndices } = mockGlw();
+    createIndexBuffer(glw, 25000 * 80);
+    const indices = getIndices();
+
+    expect(indices.length).toBe(16384 * 6);
+    // The very last vertex id is 16384*4 - 1 = 65535, the Uint16 maximum.
+    expect(indices[indices.length - 1]).toBe(65535);
+    expect(Array.from(indices.subarray(16383 * 6, 16383 * 6 + 6))).toEqual(
+      expectedQuad(16383),
+    );
+  });
+});

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

@@ -11,10 +11,17 @@ export function createIndexBuffer(
   glw: WebGlContextWrapper,
   size: number,
 ): WebGLBuffer | null {
-  const maxQuads = ~~(size / 80);
+  // 4 vertices per quad. Element indices are Uint16, so the largest vertex id
+  // we can address is 65535 — i.e. 16384 quads (16384 * 4 = 65536). Never claim
+  // more than that, regardless of the requested byte budget.
+  const maxQuads = Math.min(~~(size / 80), 16384);
   const indices = new Uint16Array(maxQuads * 6);
 
-  for (let i = 0, j = 0; i < maxQuads; i += 6, j += 4) {
+  // i walks the index slot (6 per quad), j the vertex base (4 per quad). The
+  // bound must be maxQuads * 6 to fill every slot — stopping at maxQuads left
+  // ~5/6 of the buffer zeroed, collapsing every quad past ~maxQuads/6 into a
+  // degenerate triangle (the cause of tail geometry silently disappearing).
+  for (let i = 0, j = 0; i < maxQuads * 6; i += 6, j += 4) {
     indices[i] = j;
     indices[i + 1] = j + 1;
     indices[i + 2] = j + 2;

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

@@ -97,21 +97,22 @@ describe('SdfTextRenderer layout cache', () => {
     expect(SdfFontHandler.getFontData).toHaveBeenCalledTimes(1);
   });
 
-  it('cleanup trims to the cap and evicts least-recently-used first', () => {
+  it('eagerly bounds the cache on insert (does not wait for idle cleanup)', () => {
+    // An animating scene never goes idle, so the cache must be bounded on insert
+    // rather than relying solely on idle `cleanup`. With cap 2, inserting a 3rd
+    // entry must immediately evict the least-recently-used (oldest) one — 'A'.
     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();
+    render('A'); // {A}
+    render('B'); // {A, B}
+    render('C'); // insert -> over cap -> eagerly evict LRU 'A' -> {B, C}
 
     vi.clearAllMocks();
-    render('B'); // evicted -> miss
-    render('A'); // survived -> hit
+    // Probe survivors first (hits only re-order, they don't change membership),
+    // then the evicted entry last so its re-insert can't perturb the assertion.
     render('C'); // survived -> hit
+    render('B'); // survived -> hit
+    render('A'); // evicted -> miss (one layout regen)
 
     expect(SdfFontHandler.getFontData).toHaveBeenCalledTimes(1);
   });

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

@@ -24,9 +24,14 @@ 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.
+// Upper bound on layoutCache entries. Overridden from stage options in `init`.
+// Enforced both eagerly on insert (see `renderText`) and in bulk on idle (see
+// `cleanup`). The eager bound matters because a continuously animating scene
+// never goes idle, so idle-only eviction would let apps with ever-changing text
+// (clocks, counters, score/fps readouts) grow the cache without limit until the
+// page runs out of memory. The per-insert cost is a single Map delete on a
+// cache miss (i.e. only when new text is laid out), so it does not compete with
+// steady-state rendering.
 let maxLayoutCacheSize = 250;
 
 // Initialize the SDF text renderer
@@ -114,6 +119,15 @@ const renderText = (props: CoreTextNodeProps): TextRenderInfo => {
   layout = generateTextLayout(props, fontData);
   layoutCache.set(cacheKey, layout);
 
+  // Eagerly bound the cache. Idle `cleanup` alone is not enough: an animating
+  // scene never idles, so without this, ever-changing text grows the cache
+  // without limit. The Map is insertion-ordered and cache hits re-insert
+  // (delete + set) to the end, so the first key is the least-recently-used.
+  if (layoutCache.size > maxLayoutCacheSize) {
+    const oldest = layoutCache.keys().next().value as string;
+    layoutCache.delete(oldest);
+  }
+
   // For SDF renderer, ImageData is null since we render via WebGL
   return {
     remainingLines: 0,

package/src/main-api/Renderer.ts

@@ -542,6 +542,23 @@ export type RendererMainSettings = RendererRuntimeSettings & {
    */
   forceWebGL2: boolean;
 
+  /**
+   * Disable Vertex Array Objects
+   *
+   * @remarks
+   * By default the WebGL renderer caches each shader program's attribute layout
+   * in a Vertex Array Object (native on WebGL2, or via the
+   * `OES_vertex_array_object` extension on WebGL1) and binds it with a single
+   * call per draw instead of re-pointing every attribute. Set this to `true` to
+   * force the per-draw attribute-binding path instead.
+   *
+   * This is primarily a diagnostic/benchmarking switch — it lets you A/B the VAO
+   * optimization on a target device. It has no effect on the Canvas renderer.
+   *
+   * @defaultValue `false`
+   */
+  disableVertexArrayObject: boolean;
+
   /**
    * Canvas object to use for rendering
    *
@@ -717,6 +734,7 @@ export class RendererMain extends EventEmitter {
         settings.numImageWorkers !== undefined ? settings.numImageWorkers : 2,
       enableContextSpy: settings.enableContextSpy ?? false,
       forceWebGL2: settings.forceWebGL2 ?? false,
+      disableVertexArrayObject: settings.disableVertexArrayObject ?? false,
       inspector: settings.inspector ?? false,
       inspectorOptions: settings.inspectorOptions ?? {},
       renderEngine: settings.renderEngine,
@@ -779,6 +797,7 @@ export class RendererMain extends EventEmitter {
       devicePhysicalPixelRatio,
       enableContextSpy: settings.enableContextSpy!,
       forceWebGL2: settings.forceWebGL2!,
+      disableVertexArrayObject: settings.disableVertexArrayObject!,
       fpsUpdateInterval: settings.fpsUpdateInterval!,
       enableClear: settings.enableClear!,
       numImageWorkers: settings.numImageWorkers!,

package/src/utils.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest';
+import { createWebGLContext } from './utils.js';
+import { ContextSpy } from './core/lib/ContextSpy.js';
+
+describe('createWebGLContext context spy', () => {
+  // Build a minimal fake GL context whose getExtension returns a fake
+  // OES_vertex_array_object so we can assert the spy counts calls on it.
+  function makeContext(spy: ContextSpy) {
+    let vaoCounter = 0;
+    const ext = {
+      createVertexArrayOES: () => ({ id: ++vaoCounter }),
+      bindVertexArrayOES: (_vao: unknown) => undefined,
+      deleteVertexArrayOES: (_vao: unknown) => undefined,
+    };
+    const gl = {
+      getExtension: (name: string) =>
+        name === 'OES_vertex_array_object' ? ext : null,
+      viewport: () => undefined,
+    };
+    const canvas = {
+      getContext: () => gl,
+    } as unknown as HTMLCanvasElement;
+    return createWebGLContext(canvas, false, spy);
+  }
+
+  it('counts methods on extension objects returned by getExtension', () => {
+    const spy = new ContextSpy();
+    const gl = makeContext(spy);
+
+    // WebGL1 VAO calls route through the extension object.
+    const ext = gl.getExtension('OES_vertex_array_object') as unknown as {
+      createVertexArrayOES: () => unknown;
+      bindVertexArrayOES: (vao: unknown) => void;
+    };
+    const vao = ext.createVertexArrayOES();
+    ext.bindVertexArrayOES(vao);
+    ext.bindVertexArrayOES(null);
+
+    const data = spy.getData();
+    expect(data['getExtension']).toBeGreaterThan(0);
+    expect(data['createVertexArrayOES']).toBe(1);
+    expect(data['bindVertexArrayOES']).toBe(2);
+  });
+
+  it('passes through a null extension without throwing', () => {
+    const spy = new ContextSpy();
+    const gl = makeContext(spy);
+    expect(gl.getExtension('NOPE' as 'OES_vertex_array_object')).toBe(null);
+  });
+
+  it('still counts direct context calls', () => {
+    const spy = new ContextSpy();
+    const gl = makeContext(spy);
+    gl.viewport(0, 0, 1, 1);
+    expect(spy.getData()['viewport']).toBe(1);
+  });
+});