@perspective-dev/viewer-charts 4.5.1 → 5.0.0

package/src/ts/webgl/context-manager.ts

@@ -11,137 +11,125 @@
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
 import { ShaderRegistry } from "./shader-registry";
-import { SHADER_MANIFEST } from "./shader-manifest";
 import { BufferPool } from "./buffer-pool";
+import { GLContext, type WebGLCanvas } from "./gl-context";
 
-export type WebGLCanvas = HTMLCanvasElement | OffscreenCanvas;
+export type { WebGLCanvas } from "./gl-context";
 
 export interface WebGLContextManagerOptions {
     /**
      * If `true`, compile + link every shader in `SHADER_MANIFEST`
-     * during construction (and again after a context-loss/restore
-     * cycle). Trades ~30-100ms of init time for elimination of the
-     * compile/link cost on the first-frame path of every chart type
-     * that ends up rendered. Default `false` keeps the original
-     * lazy-compile behavior — programs are compiled on first
-     * `getOrCreate(name, ...)` call from a glyph's render path.
+     * during context construction (and again after a context-loss/
+     * restore cycle). Trades ~30-100ms of init time for elimination of
+     * the compile/link cost on the first-frame path. Ignored when the
+     * manager is constructed against an already-built shared
+     * {@link GLContext} — that context owns the precompile decision.
+     * Default `false` keeps lazy-compile behavior.
      */
     precompile?: boolean;
 }
 
+/**
+ * Per-chart render handle. Owns the chart's GPU **buffers** and frame
+ * bookkeeping, but only *borrows* its GL **context** — either a private
+ * one it constructs (the default 1:1 mode, where the manager is handed a
+ * raw canvas) or a shared {@link GLContext} from the
+ * [ContextPool](./context-pool.ts) (pooled blit mode, where many
+ * managers share K contexts to stay under the browser's per-agent
+ * context cap).
+ *
+ * Buffers are always per-manager: {@link BufferPool} keys buffers by
+ * name, so two charts sharing one pool would stomp each other's `"x"` /
+ * `"y"` / `"color"`. Shaders, the GL context, and the canvas drawing
+ * buffer are shared per {@link GLContext}; the scheduler serializes
+ * renders of managers that share a context so the shared drawing buffer
+ * only ever holds one chart's frame at a time (see {@link beginFrame}).
+ */
 export class WebGLContextManager {
-    private _canvas: WebGLCanvas;
-    private _gl: WebGL2RenderingContext | WebGLRenderingContext;
-    private _isWebGL2: boolean;
-    private _shaders: ShaderRegistry;
+    private _ctx: GLContext;
+    private _ownsCtx: boolean;
+    private _disposeRestore: () => void;
     private _buffers: BufferPool;
     private _uploadedCount = 0;
     private _cssWidth = 0;
     private _cssHeight = 0;
     private _dpr = 1;
-    private _precompile: boolean;
+    private _destroyed = false;
     private _frameCallback: ((bitmap: ImageBitmap) => void) | null = null;
 
     /**
      * Per-instance `MessageChannel` used by `_yieldToTask` to resume a
-     * polling `awaitGpuFence` loop on the next task. Allocated lazily —
-     * the polling path is rarely hit when the GPU is idle, and many
-     * `WebGLContextManager` instances never need one.
-     *
+     * polling `awaitGpuFence` loop on the next task. Allocated lazily.
      * Must be per-instance: a module-level singleton races when two
-     * managers poll concurrently. Both call sites assign
-     * `port1.onmessage = resolve`, the second assignment overwrites the
-     * first, and the first poll's promise never settles — leaving its
-     * `awaitGpuFence` hung. The hang propagates up through the render
-     * scheduler's `present` → `uploadAndRender` → the worker's
-     * `uploadChunkAck` → the host's `with_typed_arrays` callback,
-     * stalling `draw()` indefinitely. (Now that fence waits across
-     * different `WebGLContextManager`s run in parallel inside one
-     * scheduler drain, the per-instance discipline matters even
-     * more — concurrent poll loops are the common case, not the
-     * exception.)
-     *
-     * Cost of per-instance allocation: one extra `MessageChannel` (two
-     * `MessagePort`s, ~negligible bytes, zero idle CPU) per chart on
-     * top of the per-chart proxy channel that the transport already
-     * holds. Bounded by chart count; safe even for pathological pages
-     * with hundreds of charts. The alternative — allocating a fresh
-     * channel on every `_yieldToTask` call — would churn ports on every
-     * fence poll (potentially many per frame on slow GPUs), which is
-     * far worse for the structured-clone subsystem than holding one
-     * port pair for the manager's lifetime.
+     * managers poll concurrently (the second `onmessage` assignment
+     * clobbers the first's resolver, hanging that fence wait). Now that
+     * fence waits across managers run in parallel within one scheduler
+     * drain, concurrent poll loops are the common case.
      */
     private _yieldChannel: MessageChannel | null = null;
 
-    constructor(canvas: WebGLCanvas, options: WebGLContextManagerOptions = {}) {
-        this._canvas = canvas;
-        this._precompile = options.precompile ?? false;
-        const gl2 = canvas.getContext("webgl2", {
-            antialias: true,
-            alpha: true,
-            premultipliedAlpha: false,
-        });
+    private _pendingYieldResolve: (() => void) | null = null;
 
-        if (gl2) {
-            this._gl = gl2 as WebGL2RenderingContext;
-            this._isWebGL2 = true;
+    /**
+     * @param source A raw canvas (manager constructs and **owns** a
+     *   private {@link GLContext}) or an existing shared `GLContext`
+     *   (manager borrows it; the pool owns its lifecycle).
+     */
+    constructor(
+        source: WebGLCanvas | GLContext,
+        options: WebGLContextManagerOptions = {},
+    ) {
+        if (source instanceof GLContext) {
+            this._ctx = source;
+            this._ownsCtx = false;
         } else {
-            const gl1 = canvas.getContext("webgl", {
-                antialias: true,
-                alpha: true,
-                premultipliedAlpha: false,
+            this._ctx = new GLContext(source, {
+                precompile: options.precompile ?? false,
             });
-
-            if (!gl1) {
-                throw new Error("WebGL is not supported");
-            }
-
-            this._gl = gl1 as WebGLRenderingContext;
-            this._isWebGL2 = false;
+            this._ownsCtx = true;
         }
 
-        this._shaders = new ShaderRegistry(this._gl);
-        this._buffers = new BufferPool(this._gl);
-
-        if (this._precompile) {
-            this._shaders.precompile(SHADER_MANIFEST);
-        }
+        this._buffers = new BufferPool(this._ctx.gl);
 
-        // Both `HTMLCanvasElement` and `OffscreenCanvas` dispatch
-        // `webglcontextlost` / `webglcontextrestored` events on the
-        // canvas itself. `addEventListener` exists on both.
-        (canvas as EventTarget).addEventListener(
-            "webglcontextlost",
-            (e: Event) => {
-                e.preventDefault();
-            },
-        );
-
-        (canvas as EventTarget).addEventListener("webglcontextrestored", () => {
-            this._shaders.releaseAll();
+        // Rebuild this tenant's buffers after a context restore. The
+        // shared `GLContext` rebuilds the shader cache itself, once.
+        this._disposeRestore = this._ctx.onRestore(() => {
             this._buffers.releaseAll();
-            this._shaders = new ShaderRegistry(this._gl);
-            this._buffers = new BufferPool(this._gl);
+            this._buffers = new BufferPool(this._ctx.gl);
             this._uploadedCount = 0;
-
-            // Re-prime the cache after restore so post-recovery
-            // first-frame doesn't re-pay the lazy compile cost.
-            if (this._precompile) {
-                this._shaders.precompile(SHADER_MANIFEST);
-            }
         });
     }
 
     get gl(): WebGL2RenderingContext | WebGLRenderingContext {
-        return this._gl;
+        return this._ctx.gl;
+    }
+
+    /**
+     * Identifies the shared GL context behind this manager. The
+     * scheduler groups pending renders by this id: managers on the same
+     * backend serialize (they share one drawing buffer); managers on
+     * different backends render in parallel. In the default 1:1 mode
+     * every manager has its own backend, so every render is independent
+     * — identical to the pre-pooling behavior.
+     */
+    get backendId(): number {
+        return this._ctx.id;
+    }
+
+    /**
+     * True once this manager's context has been lost — its own
+     * {@link destroy}, or a browser eviction of the shared context.
+     */
+    isContextLost(): boolean {
+        return this._destroyed || this._ctx.isContextLost();
     }
 
     get isWebGL2(): boolean {
-        return this._isWebGL2;
+        return this._ctx.isWebGL2;
     }
 
     get shaders(): ShaderRegistry {
-        return this._shaders;
+        return this._ctx.shaders;
     }
 
     get bufferPool(): BufferPool {
@@ -158,11 +146,10 @@ export class WebGLContextManager {
 
     /**
      * Resize the GL canvas's bitmap to match the host's CSS layout. The
-     * Host is responsible for measuring the DOM element (or otherwise
-     * deciding the target CSS size) and the device pixel ratio — the
-     * manager itself does not touch DOM, so the same code path works
-     * whether the canvas is an `HTMLCanvasElement` (in-process) or an
-     * `OffscreenCanvas` (in-process via transfer, or in a worker).
+     * host measures the DOM element and DPR — the manager never touches
+     * DOM, so the same path works for an `HTMLCanvasElement`
+     * (in-process), a transferred `OffscreenCanvas` (direct/worker), or
+     * a pool-shared `OffscreenCanvas` (pooled blit).
      */
     resize(cssWidth: number, cssHeight: number, dpr: number): void {
         this._cssWidth = cssWidth;
@@ -171,11 +158,11 @@ export class WebGLContextManager {
 
         const width = Math.round(cssWidth * dpr);
         const height = Math.round(cssHeight * dpr);
-
-        if (this._canvas.width !== width || this._canvas.height !== height) {
-            this._canvas.width = width;
-            this._canvas.height = height;
-            this._gl.viewport(0, 0, width, height);
+        const canvas = this._ctx.canvas;
+        if (canvas.width !== width || canvas.height !== height) {
+            canvas.width = width;
+            canvas.height = height;
+            this._ctx.gl.viewport(0, 0, width, height);
         }
     }
 
@@ -191,28 +178,16 @@ export class WebGLContextManager {
     } | null = null;
 
     /**
-     * Record a dimension change to be applied at the start of the
-     * next render's Phase 1, *before* `_fullRender` runs. The actual
-     * `canvas.width = N` assignment (which clears the drawing buffer
-     * per the WebGL spec) happens inside `applyPendingResize()`,
-     * paired in the same synchronous task as the paint that fills
-     * the new buffer.
-     *
-     * Why split the dimension change off from the existing
-     * {@link resize} method: in direct / in-process modes the
-     * GL canvas IS the host's visible canvas, and `canvas.width = N`
-     * is immediately observable to the browser's compositor as a
-     * cleared buffer. If the resize lands in the message handler
-     * (one task) but the matching `_fullRender` lands in the next
-     * RAF (a later task), the compositor cycles between them and
-     * presents one full frame of empty canvas — visible flicker.
-     * Deferring the dimension change to the same RAF as the paint
-     * eliminates the inter-frame gap; both happen inside Phase 1's
-     * un-yielded loop.
+     * Record a dimension change to be applied at the start of the next
+     * render's Phase 1, before `_fullRender` runs. The actual
+     * `canvas.width = N` assignment (which clears the drawing buffer per
+     * the WebGL spec) happens inside {@link applyPendingResize} /
+     * {@link beginFrame}, paired in the same synchronous task as the
+     * paint that fills the new buffer — eliminating the one-frame blank
+     * the compositor would otherwise show in direct/in-process modes
+     * (where the GL canvas IS the visible canvas).
      *
-     * Multiple `requestResize` calls before the next render coalesce
-     * to last-write-wins — five rapid width changes from a window
-     * drag produce one resize+paint, not five.
+     * Multiple calls before the next render coalesce to last-write-wins.
      */
     requestResize(cssWidth: number, cssHeight: number, dpr: number): void {
         this._pendingResize = { cssWidth, cssHeight, dpr };
@@ -220,11 +195,7 @@ export class WebGLContextManager {
 
     /**
      * Apply any pending dimension change recorded by
-     * {@link requestResize}. Called by the scheduler's Phase 1
-     * (immediately before each entry's `fullRender`) and by the
-     * `snapshotPng` bypass path. Returns `true` when a resize was
-     * applied, `false` when there was nothing pending — useful for
-     * callers that want to skip a no-op render.
+     * {@link requestResize}. Returns `true` when a resize was applied.
      */
     applyPendingResize(): boolean {
         if (!this._pendingResize) {
@@ -238,61 +209,99 @@ export class WebGLContextManager {
     }
 
     /**
-     * Last CSS width passed to `resize()`.
+     * Prepare the shared GL surface for *this* manager's render. Called
+     * by the scheduler immediately before `_fullRender` (and by the
+     * `snapshotPng` bypass).
+     *
+     * - **Own context (1:1):** identical to the old Phase-1 step — apply
+     *   only a *pending* resize. The context isn't shared, so there is
+     *   no sibling state to reset and no need to touch the canvas when
+     *   dimensions are unchanged.
+     * - **Shared context (pooled):** a co-tenant chart rendered last and
+     *   left the shared canvas at *its* dimensions with *its* GL state.
+     *   Force the canvas to this manager's dimensions and reset the
+     *   global GL state a sibling might have left dirty (bound
+     *   framebuffer, viewport, scissor/depth enables) so frames can't
+     *   bleed across charts. Per-frame draw state (blend, clear) is
+     *   re-established by the chart's `clearAndSetupFrame`.
      */
+    beginFrame(): void {
+        if (this._ownsCtx) {
+            this.applyPendingResize();
+            return;
+        }
+
+        // Honor a queued `requestResize` (it carries the latest dims but
+        // hasn't touched the canvas yet), then force the shared canvas
+        // to this manager's dims — a co-tenant chart may have left it at
+        // its own size. `resize` is a no-op when dims already match.
+        const pending = this._pendingResize;
+        this._pendingResize = null;
+        if (pending) {
+            this.resize(pending.cssWidth, pending.cssHeight, pending.dpr);
+        } else {
+            this.resize(this._cssWidth, this._cssHeight, this._dpr);
+        }
+
+        const gl = this._ctx.gl;
+        const canvas = this._ctx.canvas;
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        gl.viewport(0, 0, canvas.width, canvas.height);
+        gl.disable(gl.SCISSOR_TEST);
+        gl.disable(gl.DEPTH_TEST);
+        this._ctx.resetVertexArrayState();
+    }
+
     get cssWidth(): number {
         return this._cssWidth;
     }
 
-    /**
-     * Last CSS height passed to `resize()`.
-     */
     get cssHeight(): number {
         return this._cssHeight;
     }
 
-    /**
-     * Last device pixel ratio passed to `resize()`.
-     */
     get dpr(): number {
         return this._dpr;
     }
 
     clear(): void {
-        this._gl.clearColor(0, 0, 0, 0);
-        this._gl.clear(this._gl.COLOR_BUFFER_BIT | this._gl.DEPTH_BUFFER_BIT);
+        this._ctx.gl.clearColor(0, 0, 0, 0);
+        this._ctx.gl.clear(
+            this._ctx.gl.COLOR_BUFFER_BIT | this._ctx.gl.DEPTH_BUFFER_BIT,
+        );
         this._uploadedCount = 0;
     }
 
     /**
      * Register a per-frame hook invoked at the end of each render. In
-     * blit-mode rendering, the worker installs a callback that
-     * transfers an `ImageBitmap` from `_canvas` (an `OffscreenCanvas`)
-     * back to the host so the visible display canvas can `drawImage`
-     * it. In direct mode the callback is left null and `endFrame` is a
-     * no-op.
-     *
-     * Pass `null` to detach.
+     * blit-mode rendering the worker installs a callback that transfers
+     * an `ImageBitmap` from the canvas back to the host. In direct mode
+     * the callback is null and `endFrame` is a no-op. Pass `null` to
+     * detach.
      */
     setFrameCallback(cb: ((bitmap: ImageBitmap) => void) | null): void {
         this._frameCallback = cb;
     }
 
     /**
-     * Called by chart impls at the bottom of `_fullRender` (and any
-     * other path that produces a complete frame). When a frame
-     * callback is registered AND the GL surface is an
-     * `OffscreenCanvas`, ship its current contents as an
-     * `ImageBitmap` to the host. Otherwise no-op — direct-mode
-     * rendering has nothing to ship; the visible canvas already holds
-     * the drawing buffer.
+     * Ship the current canvas contents as an `ImageBitmap` to the host
+     * when a frame callback is registered and the surface is an
+     * `OffscreenCanvas`. Otherwise no-op (direct mode paints straight to
+     * the visible drawing buffer).
      */
     endFrame(): void {
         if (!this._frameCallback) {
             return;
         }
 
-        const canvas = this._canvas as
+        // A context lost mid-frame (our own `destroy`, or a browser
+        // eviction between paint and present) makes
+        // `transferToImageBitmap` throw. Bail quietly.
+        if (this.isContextLost()) {
+            return;
+        }
+
+        const canvas = this._ctx.canvas as
             | OffscreenCanvas
             | (HTMLCanvasElement & { transferToImageBitmap?: never });
         if (
@@ -308,30 +317,17 @@ export class WebGLContextManager {
 
     /**
      * Resolve when every GL command submitted up to this call has been
-     * executed by the GPU.
-     *
-     * On WebGL2 this issues a `fenceSync(SYNC_GPU_COMMANDS_COMPLETE)`
-     * and polls `clientWaitSync` with a zero timeout, yielding to the
-     * task queue between polls. The first poll passes
-     * `SYNC_FLUSH_COMMANDS_BIT` so the fence becomes reachable without
-     * a separate `gl.flush()`.
-     *
-     * On WebGL1 there is no fenceSync; we fall back to the blocking
-     * `gl.finish()`. This is acceptable in a worker — never call this
-     * from the main thread on a heavy frame.
-     *
-     * Used as a per-frame "GPU is idle" barrier so callers can serialize
-     * follow-on work (`endFrame` snapshot, present roundtrip, the next
-     * chunk upload) against actual GPU completion instead of the
-     * implicit, implementation-defined timing of `transferToImageBitmap`.
+     * executed by the GPU. WebGL2 issues a `fenceSync` and polls
+     * `clientWaitSync` (yielding to the task queue between polls); WebGL1
+     * falls back to a blocking `gl.finish()` (acceptable in a worker).
      */
     async awaitGpuFence(): Promise<void> {
-        if (!this._isWebGL2) {
-            this._gl.finish();
+        if (!this._ctx.isWebGL2) {
+            this._ctx.gl.finish();
             return;
         }
 
-        const gl = this._gl as WebGL2RenderingContext;
+        const gl = this._ctx.gl as WebGL2RenderingContext;
         const fence = gl.fenceSync(gl.SYNC_GPU_COMMANDS_COMPLETE, 0);
         if (!fence) {
             gl.finish();
@@ -356,6 +352,10 @@ export class WebGLContextManager {
 
                 flags = 0;
                 await this._yieldToTask();
+
+                if (this._destroyed) {
+                    return;
+                }
             }
         } finally {
             gl.deleteSync(fence);
@@ -367,48 +367,54 @@ export class WebGLContextManager {
     }
 
     /**
-     * Yield to the task queue between fence polls. We avoid
-     * `setTimeout(0)` because Chromium clamps nested `setTimeout` to
-     * ~4ms in workers, which would inflate the measured cost of
-     * `awaitGpuFence`. A reused per-instance `MessageChannel` lands the
-     * resume in the next task with sub-ms latency.
-     *
-     * `addEventListener(..., { once: true })` is used over
-     * `port1.onmessage = ...` so concurrent in-flight resumes (should
-     * any path ever introduce them) cannot clobber each other's
-     * resolvers — the previous module-level singleton lost a resolver
-     * on every overlap and hung one chart's `draw()` indefinitely.
+     * Yield to the task queue between fence polls. `setTimeout(0)` is
+     * avoided because Chromium clamps nested worker `setTimeout` to
+     * ~4ms; a reused per-instance `MessageChannel` resumes in the next
+     * task with sub-ms latency. `{ once: true }` over `onmessage = ...`
+     * so concurrent resumes can't clobber each other's resolvers.
      */
     private _yieldToTask(): Promise<void> {
         if (!this._yieldChannel) {
             this._yieldChannel = new MessageChannel();
-            // `addEventListener` does not auto-start a `MessagePort` —
-            // only `onmessage = ...` does. Start once at allocation so
-            // posted resumes are actually delivered.
             this._yieldChannel.port1.start();
         }
 
         return new Promise<void>((resolve) => {
             const ch = this._yieldChannel!;
-            ch.port1.addEventListener("message", () => resolve(), {
-                once: true,
-            });
+            this._pendingYieldResolve = resolve;
+            ch.port1.addEventListener(
+                "message",
+                () => {
+                    this._pendingYieldResolve = null;
+                    resolve();
+                },
+                { once: true },
+            );
             ch.port2.postMessage(null);
         });
     }
 
     destroy(): void {
+        this._destroyed = true;
+        this._frameCallback = null;
+        this._disposeRestore();
         this._buffers.releaseAll();
-        this._shaders.releaseAll();
+        if (this._pendingYieldResolve) {
+            const resolve = this._pendingYieldResolve;
+            this._pendingYieldResolve = null;
+            resolve();
+        }
+
         if (this._yieldChannel) {
             this._yieldChannel.port1.close();
             this._yieldChannel.port2.close();
             this._yieldChannel = null;
         }
 
-        const ext = this._gl.getExtension("WEBGL_lose_context");
-        if (ext) {
-            ext.loseContext();
+        // Only lose the GL context when we own it. A shared context
+        // outlives any one tenant — the pool destroys it.
+        if (this._ownsCtx) {
+            this._ctx.destroy();
         }
     }
 }

package/src/ts/webgl/context-pool.ts

@@ -0,0 +1,78 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+import { GLContext } from "./gl-context";
+
+/**
+ * Renderer-scope pool of shared {@link GLContext}s for pooled blit mode.
+ *
+ * The browser caps live WebGL contexts per agent (~16 in Chromium) and
+ * force-loses the oldest past that cap. A page with more than ~16 charts
+ * therefore can't give each its own context. This pool caps the number
+ * of live contexts at `size`, distributing renderers across them
+ * round-robin (sticky for a renderer's lifetime — a renderer keeps the
+ * same context so its resident GPU buffers and any cached textures/FBOs
+ * stay valid frame to frame). N charts render through K = `size`
+ * contexts; the scheduler serializes renders that land on the same
+ * context.
+ *
+ * Pooling applies to blit mode only: direct mode renders into the host's
+ * transferred visible canvas, which is permanently 1:1 with a context.
+ *
+ * One pool per renderer scope (the worker, or the main thread in
+ * in-process mode). Contexts are created lazily on first `acquire` and
+ * live until renderer-scope teardown — like the contexts they replace,
+ * they are not refcounted, because a shared context outlives any single
+ * borrowing renderer.
+ */
+export class ContextPool {
+    private _size: number;
+    private _precompile: boolean;
+    private _contexts: GLContext[] = [];
+    private _next = 0;
+
+    constructor(size: number, options: { precompile?: boolean } = {}) {
+        this._size = Math.max(1, size);
+        this._precompile = options.precompile ?? false;
+    }
+
+    /**
+     * Borrow a context for a new renderer. Fills the pool to `size`
+     * before reusing, then round-robins. A dead context (browser
+     * eviction) is replaced in place so a borrower never receives a lost
+     * context.
+     */
+    acquire(): GLContext {
+        let ctx: GLContext;
+        if (this._contexts.length < this._size) {
+            ctx = this._make();
+            this._contexts.push(ctx);
+        } else {
+            const idx = this._next % this._contexts.length;
+            this._next++;
+            if (this._contexts[idx].isContextLost()) {
+                this._contexts[idx] = this._make();
+            }
+
+            ctx = this._contexts[idx];
+        }
+
+        return ctx;
+    }
+
+    private _make(): GLContext {
+        // Initial size is arbitrary — every render resizes the shared
+        // canvas to the borrowing renderer's dimensions in `beginFrame`.
+        const canvas = new OffscreenCanvas(1, 1);
+        return new GLContext(canvas, { precompile: this._precompile });
+    }
+}