@perspective-dev/viewer-charts 4.5.1 → 4.5.2

package/dist/esm/plugin/plugin.d.ts

@@ -11,7 +11,6 @@ export declare class HTMLPerspectiveViewerWebGLPluginElement extends HTMLElement
     private _rendererPromise;
     private _rawEventForwarder;
     private _generation;
-    private _renderBlitMode;
     private _resetClickAbort;
     /**
      * Plugin-scoped global config. Seeded lazily from
@@ -64,7 +63,21 @@ export declare class HTMLPerspectiveViewerWebGLPluginElement extends HTMLElement
      */
     private _setupInteraction;
     private _buildRenderer;
-    setBlitMode(mode: "direct" | "blit"): void;
+    /**
+     * Select the GL presentation strategy for *all* chart-type plugins
+     * in this renderer. Static + process-global: the value is shared by
+     * every per-chart-type subclass, so it must be set once before the
+     * charts that should use it build their renderers (a renderer reads
+     * {@link BLIT_MODE} at construction in `_buildRenderer`; charts
+     * already built keep their mode until torn down and rebuilt).
+     *
+     * - `"direct"` — each chart owns a GL context 1:1 with its visible
+     *   canvas (lowest latency; bounded by the browser's ~16-context
+     *   cap).
+     * - `"blit"` — charts render off-screen and share a pool of GL
+     *   contexts ([webgl/context-pool.ts]), so a page can exceed the cap.
+     */
+    static setBlitMode(mode: "direct" | "blit"): void;
     get_static_config(): PluginStaticConfig;
     column_config_schema(column_type: string, _group: string | undefined, _column_name: string, current_value: Record<string, unknown> | null, _viewer_config?: {
         group_by?: string[];

package/dist/esm/render/scheduler.d.ts

@@ -34,6 +34,29 @@ export declare function requestRender(glManager: WebGLContextManager, fullRender
  * picks it up for the next RAF.
  */
 export declare function deferIfDraining(glManager: WebGLContextManager, op: () => void): void;
+/**
+ * Drop every scheduler reference to `glManager` — called from
+ * `WebGLContextManager`'s owning renderer at teardown, *before*
+ * `glManager.destroy()` loses the GL context.
+ *
+ * Without this, a frame queued for the next RAF (an `Entry` in
+ * `pending`) or a `deferIfDraining` op still parked in `deferred`
+ * would survive the destroy and, on the next `drain()`, drive
+ * `fullRender` / `present` against a context-lost manager. In blit
+ * mode that surfaces as `endFrame`'s `transferToImageBitmap` throwing
+ * "Cannot transfer to ImageBitmap because WebGL context is lost" —
+ * logged as "scheduler: present failed". In direct mode it's a wasted
+ * paint against a dead context.
+ *
+ * Outstanding waiters for a destroyed manager are resolved (not
+ * rejected): the caller asked to tear the chart down, so its awaited
+ * `draw()` should observe a clean no-op rather than an error it would
+ * have to suppress. An in-flight `present()` (manager in `inFlight`)
+ * is left to unwind on its own — its `finally` clause will not find a
+ * `deferred` entry to flush, and the manager is already gone from
+ * `pending`, so it cannot re-enqueue.
+ */
+export declare function unregister(glManager: WebGLContextManager): void;
 /**
  * Test-only: clear pending state. Production callers must not use
  * this — outstanding waiters are silently dropped.

package/dist/esm/webgl/context-manager.d.ts

@@ -1,62 +1,78 @@
 import { ShaderRegistry } from "./shader-registry";
 import { BufferPool } from "./buffer-pool";
-export type WebGLCanvas = HTMLCanvasElement | OffscreenCanvas;
+import { GLContext, type WebGLCanvas } from "./gl-context";
+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 declare class WebGLContextManager {
-    private _canvas;
-    private _gl;
-    private _isWebGL2;
-    private _shaders;
+    private _ctx;
+    private _ownsCtx;
+    private _disposeRestore;
     private _buffers;
     private _uploadedCount;
     private _cssWidth;
     private _cssHeight;
     private _dpr;
-    private _precompile;
+    private _destroyed;
     private _frameCallback;
     /**
      * 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;
-    constructor(canvas: WebGLCanvas, options?: WebGLContextManagerOptions);
+    private _pendingYieldResolve;
+    /**
+     * @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);
     get gl(): WebGL2RenderingContext | WebGLRenderingContext;
+    /**
+     * 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;
+    /**
+     * True once this manager's context has been lost — its own
+     * {@link destroy}, or a browser eviction of the shared context.
+     */
+    isContextLost(): boolean;
     get isWebGL2(): boolean;
     get shaders(): ShaderRegistry;
     get bufferPool(): BufferPool;
@@ -64,11 +80,10 @@ export declare class WebGLContextManager {
     set uploadedCount(count: number);
     /**
      * 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;
     /**
@@ -78,106 +93,74 @@ export declare class WebGLContextManager {
      */
     private _pendingResize;
     /**
-     * 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.
+     * 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).
      *
-     * 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.
-     *
-     * 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;
     /**
      * 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;
     /**
-     * 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;
     get cssWidth(): number;
-    /**
-     * Last CSS height passed to `resize()`.
-     */
     get cssHeight(): number;
-    /**
-     * Last device pixel ratio passed to `resize()`.
-     */
     get dpr(): number;
     clear(): void;
     /**
      * 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;
     /**
-     * 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;
     /**
      * 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).
      */
     awaitGpuFence(): Promise<void>;
     ensureBufferCapacity(totalRows: number): void;
     /**
-     * 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;
     destroy(): void;

package/dist/esm/webgl/context-pool.d.ts

@@ -0,0 +1,40 @@
+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 declare class ContextPool {
+    private _size;
+    private _precompile;
+    private _contexts;
+    private _next;
+    constructor(size: number, options?: {
+        precompile?: boolean;
+    });
+    /**
+     * 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;
+    private _make;
+}

package/dist/esm/webgl/gl-context.d.ts

@@ -0,0 +1,54 @@
+import { ShaderRegistry } from "./shader-registry";
+export type WebGLCanvas = HTMLCanvasElement | OffscreenCanvas;
+export declare class GLContext {
+    readonly id: number;
+    readonly canvas: WebGLCanvas;
+    readonly gl: WebGL2RenderingContext | WebGLRenderingContext;
+    readonly isWebGL2: boolean;
+    shaders: ShaderRegistry;
+    private _maxVertexAttribs;
+    private _angle;
+    private _precompile;
+    private _destroyed;
+    /**
+     * Per-tenant hooks fired after a `webglcontextrestored`. Each
+     * {@link WebGLContextManager} on this context registers one that
+     * rebuilds its `BufferPool` (the shaders are rebuilt here, once, for
+     * all tenants). On an intentional {@link destroy} these are dropped
+     * without firing.
+     */
+    private _onRestore;
+    constructor(canvas: WebGLCanvas, options?: {
+        precompile?: boolean;
+    });
+    /**
+     * Return every vertex-attribute slot to its default state: disabled,
+     * with a zero instance divisor. Vertex-array state (enable flags,
+     * pointers, divisors) is global to a context's default VAO — there
+     * are no per-chart VAOs in this codebase — so when many charts share
+     * one pooled context, a slot a prior chart enabled stays enabled for
+     * the next chart, now pointing at a buffer the prior chart's
+     * teardown deleted. Its next `drawArraysInstanced` then fails GL
+     * validation: "no buffer is bound to enabled attribute", silently
+     * dropping the draw.
+     *
+     * Glyphs already (re)enable + bind + set the divisor for every slot
+     * they use on each frame, so clearing to the default here is a safe
+     * baseline — it only removes the *leftover* enables a sibling chart
+     * left behind. Called from {@link WebGLContextManager.beginFrame} in
+     * shared (pooled) mode only; the 1:1 default never shares a context
+     * and so keeps its original, reset-free path.
+     */
+    resetVertexArrayState(): void;
+    /**
+     * Register a tenant's post-restore rebuild hook. Returns a disposer.
+     */
+    onRestore(cb: () => void): () => void;
+    /**
+     * True once lost — either our own {@link destroy} or a browser
+     * eviction of the oldest context past the per-agent cap.
+     */
+    isContextLost(): boolean;
+    get destroyed(): boolean;
+    destroy(): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perspective-dev/viewer-charts",
-  "version": "4.5.1",
+  "version": "4.5.2",
   "description": "Perspective.js WebGL Plugin",
   "unpkg": "./dist/cdn/perspective-viewer-charts.js",
   "jsdelivr": "./dist/cdn/perspective-viewer-charts.js",

package/src/ts/config.ts

@@ -33,7 +33,27 @@ export const RUNTIME_MODE: "worker" | "inprocess" = "worker";
  *   `ImageBitmap` over the control channel; the host blits the bitmap
  *   into the visible canvas via `drawImage`.
  */
-export const RENDER_BLIT_MODE: "direct" | "blit" = "direct";
+export const RENDER_BLIT_MODE: "direct" | "blit" = "blit";
+
+/**
+ * Number of shared WebGL contexts in pooled blit mode.
+ *
+ * The browser caps live contexts per agent (~16 in Chromium) and
+ * force-loses the oldest past that cap, so a page with more charts than
+ * the cap cannot give each its own context. When `> 0` *and*
+ * `RENDER_BLIT_MODE === "blit"`, every chart borrows one of this many
+ * shared contexts (round-robin, sticky for the chart's lifetime) instead
+ * of allocating its own — decoupling live-context count from chart
+ * count. N charts render through K = this many contexts; the scheduler
+ * serializes renders that land on the same context.
+ *
+ * `0` disables pooling (every chart gets its own context — the original
+ * behavior). Pooling never applies to `"direct"` mode, which renders
+ * into the host's transferred visible canvas and is permanently 1:1 with
+ * a context; keep pages that need more than ~16 simultaneous charts on
+ * `"blit"`.
+ */
+export const RENDER_CONTEXT_POOL_SIZE: number = 4;
 
 /**
  * Strict-mode validation for `BufferPool.upload`.

package/src/ts/plugin/plugin.ts

@@ -125,6 +125,22 @@ const GLOBAL_STYLES = (() => {
     return [sheet];
 })();
 
+/**
+ * Process-global GL presentation strategy, shared by *every* chart-type
+ * plugin in this renderer. Seeded from the build-time {@link RENDER_BLIT_MODE}
+ * and overridable at runtime via
+ * {@link HTMLPerspectiveViewerWebGLPluginElement.setBlitMode}.
+ *
+ * Module scope (not per-instance) on purpose: blit-vs-direct is a
+ * whole-renderer decision — in `"blit"` mode the worker shares a pool of
+ * GL contexts across all charts ([webgl/context-pool.ts]), so a page
+ * can't sensibly mix strategies per chart. Every per-chart-type subclass
+ * registered in [index.ts] reads this one value when it builds its
+ * renderer, so setting it once (before the first chart renders) applies
+ * to all of them.
+ */
+let BLIT_MODE: "direct" | "blit" = RENDER_BLIT_MODE;
+
 export class HTMLPerspectiveViewerWebGLPluginElement
     extends HTMLElement
     implements IPerspectiveViewerPlugin
@@ -139,7 +155,6 @@ export class HTMLPerspectiveViewerWebGLPluginElement
     private _rendererPromise: Promise<RendererTransport> | null = null;
     private _rawEventForwarder: RawEventForwarder | null = null;
     private _generation = 0;
-    private _renderBlitMode: "direct" | "blit" = RENDER_BLIT_MODE;
     private _resetClickAbort: AbortController | null = null;
 
     /**
@@ -257,13 +272,41 @@ export class HTMLPerspectiveViewerWebGLPluginElement
             return this._rendererPromise;
         }
 
-        this._rendererPromise = this._buildRenderer(view).then((r) => {
-            this._renderer = r;
-            this._setupInteraction(r);
-            return r;
-        });
+        // `_buildRenderer` is async — it awaits `getClient`, `getTable`,
+        // and a full worker handshake — so a `disconnectedCallback`
+        // (toggle / chart-type switch) frequently lands *before* this
+        // `.then` runs. At that point `this._renderer` is still null,
+        // so `delete()`'s `if (this._renderer)` teardown is skipped and
+        // the freshly-built transport (and its WebGL context) would be
+        // assigned to a detached element and leak — one context per
+        // raced toggle, until the browser evicts the oldest.
+        //
+        // `delete()` sets `_rendererPromise = null`, so promise identity
+        // is the dispose signal: if `this._rendererPromise` no longer
+        // points at *this* build when it resolves, the element was
+        // deleted (or a reconnect started a newer build) and we destroy
+        // the orphan instead of adopting it. Promise identity — not
+        // `_generation`, which every `draw`/`update` bumps — is the
+        // right token: a rapid draw→update must NOT tear down the
+        // single in-flight build it shares via this memoized promise.
+        const p: Promise<RendererTransport> = this._buildRenderer(view).then(
+            (r) => {
+                if (this._rendererPromise !== p) {
+                    r.destroy();
+                    throw new Error("renderer disposed during init");
+                }
+
+                this._renderer = r;
+                this._setupInteraction(r);
+                return r;
+            },
+        );
 
-        return this._rendererPromise;
+        // Swallow the dispose rejection so it doesn't surface as an
+        // unhandled rejection; `_drawImpl` catches it and bails.
+        p.catch(() => {});
+        this._rendererPromise = p;
+        return p;
     }
 
     /**
@@ -350,15 +393,28 @@ export class HTMLPerspectiveViewerWebGLPluginElement
             },
             pluginConfig: this._pluginConfig,
             defaultChartType: this._chartType.default_chart_type,
-            renderBlitMode: this._renderBlitMode,
+            renderBlitMode: BLIT_MODE,
         });
 
         return transport;
     }
 
-    setBlitMode(mode: "direct" | "blit") {
-        console.assert(this._initialized, "Already initialized");
-        this._renderBlitMode = mode;
+    /**
+     * Select the GL presentation strategy for *all* chart-type plugins
+     * in this renderer. Static + process-global: the value is shared by
+     * every per-chart-type subclass, so it must be set once before the
+     * charts that should use it build their renderers (a renderer reads
+     * {@link BLIT_MODE} at construction in `_buildRenderer`; charts
+     * already built keep their mode until torn down and rebuilt).
+     *
+     * - `"direct"` — each chart owns a GL context 1:1 with its visible
+     *   canvas (lowest latency; bounded by the browser's ~16-context
+     *   cap).
+     * - `"blit"` — charts render off-screen and share a pool of GL
+     *   contexts ([webgl/context-pool.ts]), so a page can exceed the cap.
+     */
+    static setBlitMode(mode: "direct" | "blit") {
+        BLIT_MODE = mode;
     }
 
     get_static_config(): PluginStaticConfig {
@@ -499,7 +555,15 @@ export class HTMLPerspectiveViewerWebGLPluginElement
 
     private async _drawImpl(view: View): Promise<void> {
         const gen = ++this._generation;
-        const renderer = await this._ensureRenderer(view);
+        let renderer: RendererTransport;
+        try {
+            renderer = await this._ensureRenderer(view);
+        } catch {
+            // Renderer was disposed mid-init (element disconnected
+            // during the async build) — nothing to draw.
+            return;
+        }
+
         if (this._generation !== gen) {
             return;
         }