@solidtv/renderer 1.5.0-0 → 1.5.0

package/src/core/TextureMemoryManager.ts

@@ -166,6 +166,44 @@ export class TextureMemoryManager {
     return this.criticalThreshold > 0 && this.memUsed > this.criticalThreshold;
   }
 
+  /**
+   * Reversibly free a texture's GPU resources under memory pressure.
+   *
+   * @remarks
+   * Unlike {@link destroyTexture}, this keeps the `Texture` object, its event
+   * listeners, and its cache entry intact. It only releases the GPU-side
+   * resource and transitions the source to the `freed` state. A `CoreNode` that
+   * still references this texture will reload it — and be re-notified via its
+   * `loaded` listener — when it re-enters the viewport (see
+   * `Texture.setRenderableOwner` → `Texture.load`).
+   *
+   * This is the correct path for LRU/idle cleanup: destroying instead would
+   * sever the node's subscription (`removeAllListeners`) and evict the cache
+   * entry, leaving the node stuck on a texture that reloads to `loaded` but is
+   * never displayed.
+   *
+   * `texture.free()` reclaims tracked memory via `setTextureMemUse(0)` when a
+   * ctxTexture exists; the guard below keeps the accounting correct for any
+   * texture that entered `loadedTextures` without one.
+   *
+   * @param texture - The texture to free
+   */
+  freeTexture(texture: Texture) {
+    if (this.debugLogging === true) {
+      console.log(
+        `[TextureMemoryManager] Freeing texture. State: ${texture.state}`,
+      );
+    }
+
+    texture.free();
+
+    if (this.loadedTextures.has(texture) === true) {
+      this.loadedTextures.delete(texture);
+      this.memUsed -= texture.memUsed;
+      texture.memUsed = 0;
+    }
+  }
+
   /**
    * Destroy a texture and remove it from the memory manager
    *
@@ -230,11 +268,12 @@ export class TextureMemoryManager {
 
       // Immediate cleanup if eligible
       if (isCleanableType && texture.canBeCleanedUp() === true) {
-        // Get memory before destroying
+        // Get memory before freeing
         const textureMemory = texture.memUsed;
 
-        // Destroy texture (which will null out the array position)
-        this.destroyTexture(texture);
+        // Reversibly free (keeps listeners + cache) so the texture reloads when
+        // its node re-enters the viewport.
+        this.freeTexture(texture);
         currentMemUsed -= textureMemory;
       }
     }

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

@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest';
+import { WebGlContextWrapper } from './WebGlContextWrapper.js';
+
+// The wrapper reads `self.WebGL2RenderingContext` to detect WebGL2. The unit
+// test environment is plain Node where `self` is undefined, so provide one.
+// With no WebGL2RenderingContext on it, the mock context is treated as WebGL1.
+const g = globalThis as unknown as { self?: unknown };
+if (g.self === undefined) {
+  g.self = globalThis;
+}
+
+// Minimal WebGL1-like context. A Proxy returns 0 for every GLenum constant the
+// constructor copies; only the handful of methods/props it actually calls are
+// implemented.
+function mockWebGl1(hasVaoExtension: boolean): WebGLRenderingContext {
+  const vaoExt = {
+    createVertexArrayOES: () => ({}),
+    bindVertexArrayOES: (_vao: unknown) => undefined,
+    deleteVertexArrayOES: (_vao: unknown) => undefined,
+  };
+  const target: Record<string, unknown> = {
+    canvas: {},
+    drawingBufferWidth: 100,
+    drawingBufferHeight: 100,
+    getParameter: () => 8,
+    getExtension: (name: string) =>
+      name === 'OES_vertex_array_object' && hasVaoExtension ? vaoExt : null,
+  };
+  return new Proxy(target, {
+    get(t, prop) {
+      if (prop in t) {
+        return t[prop as string];
+      }
+      // Every other access is a GLenum constant.
+      return 0;
+    },
+  }) as unknown as WebGLRenderingContext;
+}
+
+describe('WebGlContextWrapper VAO support', () => {
+  it('enables VAOs when the OES extension is present', () => {
+    const glw = new WebGlContextWrapper(mockWebGl1(true));
+    expect(glw.canUseVertexArrayObject).toBe(true);
+    expect(glw.isWebGl2).toBe(false);
+  });
+
+  it('disables VAOs when the OES extension is absent', () => {
+    const glw = new WebGlContextWrapper(mockWebGl1(false));
+    expect(glw.canUseVertexArrayObject).toBe(false);
+  });
+
+  it('forces VAOs off when disableVertexArrayObject is true, even if supported', () => {
+    const glw = new WebGlContextWrapper(mockWebGl1(true), true);
+    expect(glw.canUseVertexArrayObject).toBe(false);
+    // The flag gates VAO usage only; it does not change the detected context.
+    expect(glw.isWebGl2).toBe(false);
+  });
+});

package/src/core/lib/WebGlContextWrapper.ts

@@ -111,7 +111,10 @@ export class WebGlContextWrapper {
   public readonly INVALID_OPERATION: number;
   //#endregion WebGL Enums
 
-  constructor(private gl: WebGLRenderingContext | WebGL2RenderingContext) {
+  constructor(
+    private gl: WebGLRenderingContext | WebGL2RenderingContext,
+    disableVertexArrayObject = false,
+  ) {
     // A freshly created WebGL context is in a fully specified default state.
     // Rather than reading that state back with getParameter/isEnabled — each a
     // synchronous CPU<->GPU round-trip, and previously ~one per texture unit
@@ -154,9 +157,16 @@ export class WebGlContextWrapper {
       self.WebGL2RenderingContext && gl instanceof self.WebGL2RenderingContext
         ? (gl as WebGL2RenderingContext)
         : null;
+    // `disableVertexArrayObject` forces the per-draw attribute-binding path even
+    // when VAOs are available (diagnostics / benchmarking). isWebGl2 still
+    // reflects the real context — the flag only gates VAO usage.
     this.vaoExt =
-      this.gl2 === null ? gl.getExtension('OES_vertex_array_object') : null;
-    this.canUseVertexArrayObject = this.gl2 !== null || this.vaoExt !== null;
+      this.gl2 === null && disableVertexArrayObject !== true
+        ? gl.getExtension('OES_vertex_array_object')
+        : null;
+    this.canUseVertexArrayObject =
+      disableVertexArrayObject !== true &&
+      (this.gl2 !== null || this.vaoExt !== null);
     this.isWebGl2 = this.gl2 !== null;
 
     this.canvas = gl.canvas;

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/WebGlShaderProgram.ts

@@ -276,17 +276,25 @@ export class WebGlShaderProgram implements CoreShaderProgram {
     if (glw.canUseVertexArrayObject === true) {
       let vao = this.vaos.get(buffer);
       if (vao === undefined) {
-        // First draw with this collection: record the attribute layout into a
-        // VAO. createVao leaves the new VAO bound, so there's nothing more to do.
+        // First draw with this collection: try to capture the attribute layout
+        // in a VAO. Cache the result — including a null on allocation failure,
+        // so we don't retry createVertexArray every frame.
         vao = this.createVao(buffer);
         this.vaos.set(buffer, vao);
+      }
+      if (vao !== null) {
+        // createVao leaves a freshly built VAO bound; re-binding is cheap and
+        // keeps the build and reuse paths identical.
+        glw.bindVertexArray(vao);
         return;
       }
-      glw.bindVertexArray(vao);
-      return;
+      // VAO allocation failed (e.g. under GL OOM). Bind the default VAO so the
+      // per-draw attribute setup below records into it rather than corrupting
+      // another program's cached VAO, then fall through.
+      glw.bindVertexArray(null);
     }
 
-    // No VAO support: re-point every attribute on each draw.
+    // No (usable) VAO: re-point every attribute on each draw.
     this.bindAttributes(buffer);
   }
 
@@ -322,10 +330,15 @@ export class WebGlShaderProgram implements CoreShaderProgram {
   /**
    * Create and populate a Vertex Array Object capturing this program's
    * attribute layout for the given buffer collection. The new VAO is left bound.
+   * Returns null if the context reports VAO support but allocation fails (e.g.
+   * under GL OOM), in which case the caller falls back to per-draw binding.
    */
   private createVao(buffer: BufferCollection): WebGLVertexArrayObject | null {
     const { glw } = this;
     const vao = glw.createVertexArray();
+    if (vao === null) {
+      return null;
+    }
     glw.bindVertexArray(vao);
 
     this.bindAttributes(buffer);

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