@perspective-dev/viewer-charts 4.5.1 → 5.0.0

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

@@ -30,9 +30,12 @@ export interface ChartTypeConfig {
      * Per-chart-type overrides for `DEFAULT_PLUGIN_CONFIG`. Used when a
      * field's sensible default differs by chart family — currently
      * `include_zero` (true for Y Bar / Y Area / X Bar, false for line
-     * / scatter / cartesian / financial). Applied at schema generation
-     * and at `restore({})` so the effective default matches the
-     * surfaced UI default.
+     * / scatter / cartesian / financial) and `facet_mode` ("overlay"
+     * for the band-pipeline families — series / financial — whose
+     * historical split_by rendering is the single stacked/colored
+     * plot; "grid" elsewhere). Applied at schema generation and at
+     * `restore({})` so the effective default matches the surfaced UI
+     * default.
      */
     plugin_field_defaults?: Partial<PluginConfig>;
 }

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

@@ -10,8 +10,6 @@ export declare class HTMLPerspectiveViewerWebGLPluginElement extends HTMLElement
     private _renderer;
     private _rendererPromise;
     private _rawEventForwarder;
-    private _generation;
-    private _renderBlitMode;
     private _resetClickAbort;
     /**
      * Plugin-scoped global config. Seeded lazily from
@@ -64,7 +62,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[];
@@ -84,10 +96,40 @@ export declare class HTMLPerspectiveViewerWebGLPluginElement extends HTMLElement
     };
     draw(view: View): Promise<void>;
     update(view: View): Promise<void>;
+    /**
+     * Shared body of `draw` / `update`. No re-entrancy guard: the host
+     * serializes every rendering call (`draw`, `update`, `render`,
+     * `resize`) and `delete` on its per-renderer draw lock, so this
+     * method never overlaps itself or a teardown. The one exception —
+     * an external DOM disconnect `delete()`ing the element mid-draw —
+     * is absorbed by `RendererTransport`, whose post-`destroy()`
+     * requests settle immediately instead of pending forever.
+     */
     private _drawImpl;
     clear(): Promise<void>;
     resize(): Promise<void>;
-    restyle(): number;
+    /**
+     * OPTIONAL host presize protocol: render at the TARGET element box
+     * `(width, height)` — the box the host's pending layout commit will
+     * produce — holding the resulting frame offscreen, so nothing on
+     * screen changes during the round-trip. Resolves, once the resized
+     * frame is staged, to a present closure; the host calls it in the
+     * same task as the layout commit, landing geometry and pixels in
+     * one paint. Plugins without this method get the host's held
+     * style-override presize path instead.
+     */
+    presize(width: number, height: number): Promise<(() => void) | void>;
+    restyle(): void;
+    /**
+     * Clear any active selection state (pinned tooltip) WITHOUT emitting
+     * selection events — the host calls this when a global filter
+     * contributed by this panel's selection is removed from the global
+     * filter bar, so the pin can't outlive the filter it produced. The
+     * transport's `_lastInsertConfig` (remove-set memory) is deliberately
+     * RETAINED so a subsequent selection still replaces any leftover
+     * clauses rather than accumulating.
+     */
+    deselect(): Promise<void>;
     render(view: View): Promise<Blob>;
     restore(config: any, columns_config?: Record<string, any>): void;
     delete(): void;

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

@@ -1,16 +1,19 @@
 import type { WebGLContextManager } from "../webgl/context-manager";
 /**
- * Request a coalesced render of `glManager` whose body is
- * `fullRender`. Returns a promise that resolves when this entry's
- * Phase 2 (`awaitGpuFence` + `endFrame`) completes.
+ * Request a coalesced render of `glManager`. `fullRender` submits the
+ * GL commands (Phase 1, synchronous); `render2D` draws the 2D layers
+ * (gridlines + chrome) and runs in Phase 2 *after* `awaitGpuFence`, so
+ * the 2D canvases don't present ahead of the GL frame. Returns a
+ * promise that resolves when this entry's Phase 2 (`awaitGpuFence` +
+ * `render2D` + `endFrame`) completes.
  *
  * If a request is already pending for the same glManager, the new
- * call's `fullRender` closure replaces the prior one (latest call
- * wins; closures read chart state lazily so this is functionally a
- * no-op, but keeps the closure fresh) and the returned promise
- * resolves alongside the existing waiters.
+ * call's `fullRender` / `render2D` closures replace the prior ones
+ * (latest call wins; closures read chart state lazily so this is
+ * functionally a no-op, but keeps the closures fresh) and the returned
+ * promise resolves alongside the existing waiters.
  */
-export declare function requestRender(glManager: WebGLContextManager, fullRender: () => void): Promise<void>;
+export declare function requestRender(glManager: WebGLContextManager, fullRender: () => void, render2D: () => void): Promise<void>;
 /**
  * Run `op` synchronously if no drain `present()` is currently active
  * for `glManager`. Otherwise queue `op` to run as soon as that
@@ -34,6 +37,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/transport/protocol.d.ts

@@ -9,8 +9,8 @@ export type { ThemeSnapshot };
  * host's real `Client` — that's pure protobuf bytes; this one is the
  * chart's own renderer control plane.
  */
-export type ControlMsg = InitMsg | SetViewByNameMsg | SetColumnsConfigMsg | SetPluginConfigMsg | SetBufferMaxCapacityMsg | LoadAndRenderMsg | RedrawMsg | ResizeMsg | ClearMsg | InvalidateThemeMsg | RestoreZoomMsg | ResetAllZoomsMsg | ResetExpandedDomainMsg | SaveZoomReqMsg | SnapshotPngReqMsg | InteractionMsg | DestroyMsg;
-export type WorkerMsg = ReadyMsg | ZoomChangedMsg | SaveZoomReplyMsg | SnapshotPngReplyMsg | PinTooltipMsg | DismissTooltipMsg | SetCursorMsg | UserClickMsg | UserSelectMsg | LoadAndRenderAckMsg | FrameBitmapMsg | ErrorMsg;
+export type ControlMsg = InitMsg | SetViewByNameMsg | SetColumnsConfigMsg | SetPluginConfigMsg | SetBufferMaxCapacityMsg | LoadAndRenderMsg | RedrawMsg | DeselectMsg | ResizeMsg | ClearMsg | InvalidateThemeMsg | RestoreZoomMsg | ResetAllZoomsMsg | ResetExpandedDomainMsg | SaveZoomReqMsg | SnapshotPngReqMsg | InteractionMsg | DestroyMsg;
+export type WorkerMsg = ReadyMsg | ZoomChangedMsg | SaveZoomReplyMsg | SnapshotPngReplyMsg | PinTooltipMsg | DismissTooltipMsg | SetCursorMsg | UserClickMsg | UserSelectMsg | LoadAndRenderAckMsg | ResizeAckMsg | FrameBitmapMsg | ErrorMsg;
 /**
  * Session-tagged envelopes for the shared-worker transport. Every
  * message between the host and the shared `Worker` carries a numeric
@@ -230,12 +230,41 @@ export interface LoadAndRenderAckMsg {
 export interface RedrawMsg {
     kind: "redraw";
 }
+/**
+ * Host → worker: silently clear the chart's selection state (pinned
+ * tooltip) — no `userSelect` reply, so the host filter-bar removal that
+ * triggered it can't echo back into the host's filter set. The worker's
+ * `TooltipController.dismiss()` posts `dismissTooltip` to tear down the
+ * host-side pinned artifact.
+ */
+export interface DeselectMsg {
+    kind: "deselect";
+}
+/**
+ * Host → worker: resize the chart to a new CSS box. Replied with
+ * {@link ResizeAckMsg} AFTER the resized frame PRESENTS — the host's
+ * `plugin.resize()` promise is the viewer's presize contract ("the
+ * plugin has repainted at the target box when this resolves"), so an
+ * ack at message-receipt would let the settings-pane layout commit
+ * against the old-dimensions bitmap (the aspect-ratio warp).
+ */
 export interface ResizeMsg {
     kind: "resize";
+    msgId: number;
     cssWidth: number;
     cssHeight: number;
     dpr: number;
 }
+/**
+ * Worker → host reply to a `ResizeMsg`, posted after the resized
+ * frame's present completes. Always sent — present failures and
+ * torn-down charts included — so the host's awaited promise resolves
+ * deterministically.
+ */
+export interface ResizeAckMsg {
+    kind: "resizeAck";
+    msgId: number;
+}
 export interface ClearMsg {
     kind: "clear";
 }

package/dist/esm/transport/renderer-transport.d.ts

@@ -20,11 +20,21 @@ import type { InteractionEvent } from "./protocol";
  */
 export declare class RendererTransport {
     private _handle;
+    /**
+     * Set by {@link destroy}. Requests allocated after teardown settle
+     * immediately in `_allocPending` — `_post` is already a no-op once
+     * `_handle` is null, so a late request would otherwise never
+     * receive its reply and pend forever.
+     */
+    private _destroyed;
     private _proxyChannel;
     private _proxySession;
     private _client;
     private _view;
     private _tableName;
+    /** Source panel `slot`, tagged onto dispatched interaction events so the
+     * host can route them (master/detail, global filter) to the right panel. */
+    private _panel;
     private _clientWorkerURL;
     private _clientWasm;
     private _chartTag;
@@ -63,6 +73,30 @@ export declare class RendererTransport {
      * canvas's drawing buffer is the worker's transferred GL canvas).
      */
     private _displayCtx;
+    /**
+     * Present-hold state for the staged-present presize protocol
+     * ({@link presize}). While holding, inbound `frameBitmap`s are
+     * STAGED (latest wins) instead of blitted, so the on-screen frame
+     * — old dimensions in the old, unchanged box — stays put until the
+     * host invokes the present closure `presize` resolved to, in the
+     * same task as its layout commit. Entered only by `presize`;
+     * exited by the present closure, by `presize`'s rejection path, or
+     * by `destroy` — every settle path releases the hold or hands the
+     * caller the release.
+     */
+    /**
+     * The last `(cssWidth, cssHeight, dpr)` posted to the worker — at init
+     * or any resize — i.e. the dimensions the worker has already rendered
+     * (or has an in-flight render for). {@link resize} short-circuits when
+     * its measurement matches (±0.5px, the presize protocol's own
+     * threshold): reactive resizes fan in from several host paths per
+     * layout transition (the post-commit fan-out, activation nudges, the
+     * fresh-restore tail), and every worker resize is an unconditional
+     * full re-render.
+     */
+    private _lastPostedSize;
+    private _holdPresent;
+    private _stagedFrame;
     /**
      * Host-side sink for tooltip + cursor side-effects. The chart
      * inside the renderer calls into a `MessageHostSink` that posts
@@ -85,6 +119,7 @@ export declare class RendererTransport {
         client: Client;
         view: View;
         tableName?: string;
+        panel?: string;
         clientWasm: WebAssembly.Module;
         clientWorkerURL: URL;
         chartTag: string;
@@ -125,7 +160,8 @@ export declare class RendererTransport {
      * `loadAndRenderAck`. Per the worker's "resolve on stale"
      * contract, a mid-flight cancellation (a newer `loadAndRender`
      * superseding this one) still acks — the host's awaiter just
-     * resolves quietly.
+     * resolves quietly. Calls issued after `destroy()` resolve
+     * immediately (see `_allocPending`).
      */
     loadAndRender(opts: {
         viewerConfig: {
@@ -138,7 +174,41 @@ export declare class RendererTransport {
         };
     }): Promise<void>;
     redraw(): void;
-    resize(): void;
+    /**
+     * Silently clear the worker chart's selection state (pinned tooltip) —
+     * no selection events are emitted; the worker echoes `dismissTooltip`
+     * to drop the host-side pinned artifact. See `DeselectMsg`.
+     */
+    deselect(): void;
+    /**
+     * Resize the chart to the GL canvas's CURRENT CSS box and resolve
+     * once the resized frame has PRESENTED (the worker's `resizeAck`) —
+     * not at message-post, which would let callers proceed while the
+     * old-dimensions bitmap is still on screen. Reactive geometry
+     * changes only; anticipated ones go through {@link presize}.
+     *
+     * A measurement matching {@link _lastPostedSize} resolves immediately
+     * WITHOUT a worker round trip: the worker has already rendered (or is
+     * presenting) that exact frame, and re-posting would be a full
+     * re-render of an identical bitmap.
+     */
+    resize(): Promise<void>;
+    /**
+     * Staged-present variant of {@link resize}: render at the given
+     * TARGET canvas CSS box (no measurement — the caller supplies the
+     * box the pending layout commit will produce), HOLDING the
+     * resulting frame (and any others that arrive meanwhile) offscreen
+     * instead of blitting, so nothing on screen changes. Resolves,
+     * once the resized frame is staged, to a present closure: calling
+     * it blits the latest staged frame and exits the hold — the host
+     * runs it in the same task as its layout commit so geometry and
+     * pixels land in one paint. On rejection (teardown) the hold is
+     * released here, so every settle path either frees the display or
+     * hands the caller the release.
+     */
+    presize(cssWidth: number, cssHeight: number): Promise<(() => void) | void>;
+    private _postResize;
+    private _presentStaged;
     clear(): void;
     invalidateTheme(): void;
     saveZoom(): Promise<void>;
@@ -146,7 +216,8 @@ export declare class RendererTransport {
      * Allocate a pending request slot of the given `kind`. Returns the
      * id (encoded into the outgoing `ControlMsg`) and a promise that
      * resolves / rejects when the matching reply arrives or
-     * `destroy()` drains the table.
+     * `destroy()` drains the table. Requests issued *after* `destroy()`
+     * settle immediately with the same per-kind semantics as the drain.
      */
     private _allocPending;
     restoreZoom(state: any): void;

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