@perspective-dev/viewer-charts 4.5.1 → 5.0.0

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/dist/esm/webgl/instanced-attrs.d.ts

@@ -34,11 +34,17 @@ export declare function createQuadCornerBuffer(gl: GL): WebGLBuffer;
  * paint zero data). No-op return `true` when `attr` is negative
  * (optimized-out attribute — drawing the rest is still valid).
  *
+ * `firstInstance` byte-offsets the attribute pointer so the draw's
+ * instance 0 reads element `firstInstance` of the buffer — the WebGL
+ * substitute for a `baseInstance` draw parameter. Faceted renderers
+ * use it to draw a contiguous per-facet sub-range of a shared
+ * instance buffer.
+ *
  * Render-path uses `peek`, never `getOrCreate`: the latter recreates
  * with zero-initialized contents when `_totalCapacity` has grown past
  * the current buffer, which would wipe the previous draw's vertex
  * data and leave `drawArraysInstanced` to render zeros. See
  * {@link BufferPool#peek} for the full rationale.
  */
-export declare function bindInstancedFloatAttr(glManager: WebGLContextManager, instancing: Instancing, attr: number, name: string, components: number): boolean;
+export declare function bindInstancedFloatAttr(glManager: WebGLContextManager, instancing: Instancing, attr: number, name: string, components: number, firstInstance?: number): boolean;
 export {};

package/dist/esm/worker/renderer.worker.d.ts

@@ -72,6 +72,18 @@ export declare class WorkerRenderer {
      */
     loadAndRender(msg: LoadAndRenderMsg): Promise<void>;
     redraw(): void;
+    /**
+     * `redraw`, acked to the host AFTER the frame's present completes —
+     * the reply backing the viewer's presize contract (`ResizeAckMsg`):
+     * `plugin.resize()` must not resolve until the resized frame is
+     * actually on screen. A resize landing mid-present defers its
+     * canvas mutation (`deferIfDraining`), but the redraw's own frame
+     * applies pending dimensions in `beginFrame`, so the present this
+     * awaits IS at the new size. Always acks — a failed present or a
+     * torn-down chart resolves the host's await rather than stranding
+     * it (completion, not success, is the contract).
+     */
+    redrawAck(msgId: number): void;
     resize(cssWidth: number, cssHeight: number, dpr: number): void;
     clear(): void;
     saveZoom(): any;

package/package.json

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

package/src/ts/charts/candlestick/candlestick-render.ts

@@ -224,7 +224,10 @@ export function renderCandlestickFrame(
     chart._lastCatTicks = numericCat
         ? computeNiceTicks(vis.xMin, vis.xMax, 6)
         : null;
-    renderCandlestickChromeOverlay(chart);
+    // Deferred past the GPU fence (see `_defer2D`) so the chrome canvas
+    // doesn't present ahead of the GL glyphs on resize. Reads the
+    // `_last*` frame state set above.
+    chart._defer2D(() => renderCandlestickChromeOverlay(chart));
 }
 
 export function renderCandlestickChromeOverlay(chart: CandlestickChart): void {

package/src/ts/charts/candlestick/candlestick.ts

@@ -92,15 +92,16 @@ export class CandlestickChart extends CategoricalYChart {
     _yDomain: { min: number; max: number } = { min: 0, max: 1 };
 
     /**
-     * `domain_mode: "expand"` accumulators. Hold the running union of
-     * the value-axis (and, in numeric-category mode, category-axis)
-     * extent across data loads. Cleared in `resetExpandedDomain` —
-     * wired from the worker's `resetAllZooms` and from view-config
-     * mutations on `AbstractChart`. `null` whenever the option is
-     * `"fit"` or the accumulator has just been cleared.
+     * `domain_mode: "expand"` accumulator — the VALUE (Y) axis only.
+     * The category axis has NO accumulator on band charts (see
+     * `SeriesChart._expandedLeftDomain`): a numeric/datetime `group_by`
+     * axis always fits the current data. Cleared in
+     * `resetExpandedDomain` — wired from the worker's `resetAllZooms`
+     * and from view-config mutations on `AbstractChart`. `null`
+     * whenever the option is `"fit"` or the accumulator has just been
+     * cleared.
      */
     _expandedYDomain: { min: number; max: number } | null = null;
-    _expandedCategoryDomain: { min: number; max: number } | null = null;
 
     /**
      * Numeric category-axis state (single non-string group_by).
@@ -267,22 +268,17 @@ export class CandlestickChart extends CategoricalYChart {
             scratchCandles: this._candles,
         });
         // `domain_mode: "expand"` post-build union — mirrors the series
-        // pipeline. `expandDomainInPlace` mutates `result.*` so the
-        // assignments below pick up the grown extent automatically.
+        // pipeline: VALUE (Y) axis only, never the category axis (see
+        // `SeriesChart.uploadAndRender`). `expandDomainInPlace` mutates
+        // `result.yDomain` so the assignment below picks up the grown
+        // extent automatically.
         if (this._pluginConfig.domain_mode === "expand") {
             this._expandedYDomain = expandDomainInPlace(
                 this._expandedYDomain,
                 result.yDomain,
             );
-            if (result.numericCategoryDomain) {
-                this._expandedCategoryDomain = expandDomainInPlace(
-                    this._expandedCategoryDomain,
-                    result.numericCategoryDomain,
-                );
-            }
         } else {
             this._expandedYDomain = null;
-            this._expandedCategoryDomain = null;
         }
 
         this._rowPaths = result.rowPaths;
@@ -320,7 +316,6 @@ export class CandlestickChart extends CategoricalYChart {
 
     override resetExpandedDomain(): void {
         this._expandedYDomain = null;
-        this._expandedCategoryDomain = null;
     }
 
     protected destroyInternal(): void {

package/src/ts/charts/cartesian/cartesian-render.ts

@@ -204,7 +204,11 @@ export function renderCartesianFrame(
         });
     }
 
-    renderCartesianChromeOverlay(chart);
+    // Defer the chrome (axes/legend/tooltip) draw past the GPU fence so
+    // the chrome canvas doesn't present ahead of the GL glyphs on resize.
+    // `renderCartesianChromeOverlay` reads the `_last*` frame state set
+    // above, which stays stable until the next `_fullRender`.
+    chart._defer2D(() => renderCartesianChromeOverlay(chart));
 }
 
 interface RenderFrameCtx {
@@ -406,26 +410,25 @@ function renderSinglePlotFrame(
 
     const isMap = chart._renderMode === "map";
 
-    if (chart._gridlineCanvas && !isMap) {
-        // One-shot destructive prep (resizes + clears + scales to DPR).
-        // `renderGridlines` itself is non-destructive.
-        const dpr = glManager.dpr;
-        initCanvas(chart._gridlineCanvas, layout, dpr);
-        renderGridlines(
-            chart._gridlineCanvas,
-            layout,
-            xTicks,
-            yTicks,
-            theme,
-            dpr,
-        );
-    } else if (chart._gridlineCanvas && isMap) {
+    // Defer the gridline draw past the GPU fence (see `_defer2D`) so the
+    // gridline canvas doesn't present ahead of the GL glyphs on resize.
+    // The closure captures this frame's `layout` / ticks / `theme`.
+    const dpr = glManager.dpr;
+    const gridlineCanvas = chart._gridlineCanvas;
+    if (gridlineCanvas && !isMap) {
+        chart._defer2D(() => {
+            // One-shot destructive prep (resizes + clears + scales to
+            // DPR). `renderGridlines` itself is non-destructive.
+            initCanvas(gridlineCanvas, layout, dpr);
+            renderGridlines(gridlineCanvas, layout, xTicks, yTicks, theme, dpr);
+        });
+    } else if (gridlineCanvas && isMap) {
         // Map mode draws no cartesian gridlines, but the gridline
         // canvas may carry stale ink from a prior cartesian chart
         // type. Reset it to a clean transparent surface so the
         // basemap (rendered into the GL canvas below) reads as the
         // only background layer.
-        initCanvas(chart._gridlineCanvas, layout, glManager.dpr);
+        chart._defer2D(() => initCanvas(gridlineCanvas, layout, dpr));
     }
 
     renderInPlotFrame(gl, layout, glManager.dpr, () => {
@@ -571,10 +574,17 @@ function renderFacetedFrame(
     // One-shot destructive prep for the gridline + WebGL canvases.
     // Both phases below are per-facet; calling their destructive
     // helpers (initCanvas / renderInPlotFrame) in the loop would wipe
-    // every previously-drawn facet, leaving only the last cell
-    // visible.
-    if (chart._gridlineCanvas && sampleLayout) {
-        initCanvas(chart._gridlineCanvas, sampleLayout, glManager.dpr);
+    // every previously-drawn facet, leaving only the last cell visible.
+    //
+    // The gridline draws are deferred past the GPU fence (see
+    // `_defer2D`) so the gridline canvas doesn't present ahead of the GL
+    // glyphs on resize. `initCanvas` is deferred first so it runs before
+    // the per-facet `renderGridlines` closures below (FIFO flush order);
+    // the GL prep (`clearAndSetupFrame`) and draws stay in this pass.
+    const dpr = glManager.dpr;
+    const gridlineCanvas = chart._gridlineCanvas;
+    if (gridlineCanvas && sampleLayout) {
+        chart._defer2D(() => initCanvas(gridlineCanvas, sampleLayout, dpr));
     }
 
     clearAndSetupFrame(gl);
@@ -609,49 +619,56 @@ function renderFacetedFrame(
         // basemap layer is rendered into the GL canvas inside the
         // facet's scissor below.
         const isMap = chart._renderMode === "map";
-        if (chart._gridlineCanvas && !isMap) {
-            const localXTicks = independent
-                ? computeTicks(
-                      buildXDomain(
-                          chart,
-                          facetDomain.xMin,
-                          facetDomain.xMax,
-                          xIsDate,
-                      ),
-                      buildYDomain(
-                          chart,
-                          facetDomain.yMin,
-                          facetDomain.yMax,
-                          yIsDate,
-                      ),
-                      cell.layout,
-                  ).xTicks
-                : xTicks;
-            const localYTicks = independent
-                ? computeTicks(
-                      buildXDomain(
-                          chart,
-                          facetDomain.xMin,
-                          facetDomain.xMax,
-                          xIsDate,
-                      ),
-                      buildYDomain(
-                          chart,
-                          facetDomain.yMin,
-                          facetDomain.yMax,
-                          yIsDate,
-                      ),
-                      cell.layout,
-                  ).yTicks
-                : yTicks;
-            renderGridlines(
-                chart._gridlineCanvas,
-                cell.layout,
-                localXTicks,
-                localYTicks,
-                theme,
-                glManager.dpr,
-            );
+        if (gridlineCanvas && !isMap) {
+            // Deferred to the post-fence 2D flush. The closure captures
+            // this facet's `cell` (whose `cell.layout` already carries
+            // the padded domain from `buildProjectionMatrix` above) plus
+            // the frame-local domain/ticks, so it stays correct without
+            // recomputing at flush time.
+            chart._defer2D(() => {
+                const localXTicks = independent
+                    ? computeTicks(
+                          buildXDomain(
+                              chart,
+                              facetDomain.xMin,
+                              facetDomain.xMax,
+                              xIsDate,
+                          ),
+                          buildYDomain(
+                              chart,
+                              facetDomain.yMin,
+                              facetDomain.yMax,
+                              yIsDate,
+                          ),
+                          cell.layout,
+                      ).xTicks
+                    : xTicks;
+                const localYTicks = independent
+                    ? computeTicks(
+                          buildXDomain(
+                              chart,
+                              facetDomain.xMin,
+                              facetDomain.xMax,
+                              xIsDate,
+                          ),
+                          buildYDomain(
+                              chart,
+                              facetDomain.yMin,
+                              facetDomain.yMax,
+                              yIsDate,
+                          ),
+                          cell.layout,
+                      ).yTicks
+                    : yTicks;
+                renderGridlines(
+                    gridlineCanvas,
+                    cell.layout,
+                    localXTicks,
+                    localYTicks,
+                    theme,
+                    dpr,
+                );
+            });
         }
 
         withScissor(gl, cell.layout, glManager.dpr, () => {

package/src/ts/charts/chart-base.ts

@@ -142,6 +142,23 @@ export abstract class AbstractChart implements ChartImplementation {
     _gridlineCanvas: HTMLCanvasElement | OffscreenCanvas | null = null;
     _chromeCanvas: HTMLCanvasElement | OffscreenCanvas | null = null;
 
+    /**
+     * 2D-canvas draw closures collected during `_fullRender` (the GL
+     * pass) and flushed by {@link _flush2D} *after* the scheduler's
+     * `awaitGpuFence`. Deferring the gridline/chrome draws past the GPU
+     * fence stops the 2D placeholder canvases from pushing a resized
+     * frame to the compositor a frame ahead of the GL present — the
+     * visible GL/2D misalignment on resize.
+     *
+     * Renderers wrap their 2D drawing in {@link _defer2D}; the closures
+     * capture the exact per-frame locals (layout, ticks, theme) so no
+     * state needs to be recomputed or replayed from cache at flush time.
+     * Reset at the start of every GL pass (see {@link requestRender} /
+     * {@link renderFrameSync}) so a `_fullRender` that throws mid-way
+     * can't leak stale closures into the next frame.
+     */
+    _deferred2D: Array<() => void> = [];
+
     /**
      * Host-supplied CSS-variable map. The host snapshots its DOM via
      * `snapshotThemeVars(el)` and ships it over the control channel;
@@ -630,6 +647,20 @@ export abstract class AbstractChart implements ChartImplementation {
         }
     }
 
+    /**
+     * Silently dismiss any pinned tooltip (the chart's selection visual)
+     * WITHOUT emitting `perspective-global-filter` — unlike the `setView`
+     * implicit dismiss above, the HOST initiated this (its global filter
+     * bar removed the clause this selection contributed), so an unselect
+     * emit would double-mutate the host's filter set.
+     * `TooltipController.dismiss()` posts the host-side pin teardown but
+     * never fires `onUnpin` (that emit belongs to `dispatchClick`'s
+     * click-to-unpin gesture), so this is emit-free by construction.
+     */
+    deselect(): void {
+        this._tooltip.dismiss();
+    }
+
     /**
      * Build the chart-specific {@link TooltipCallbacks} object — the
      * `onHover` / `onLeave` / `onClickPre` / `onPin` / `onDblClick`
@@ -810,17 +841,66 @@ export abstract class AbstractChart implements ChartImplementation {
      * scheduler so concurrent calls collapse to one `_fullRender` per
      * RAF and the host blitter receives one bitmap per frame. The
      * returned promise resolves after this chart's `awaitGpuFence` +
-     * `endFrame` chain — independent of other charts in the same
-     * RAF, which run their fence waits in parallel.
+     * `render2D` + `endFrame` chain — independent of other charts in the
+     * same RAF, which run their fence waits in parallel.
+     *
+     * `_fullRender` submits the GL commands and stashes the frame's 2D
+     * draws (gridlines + chrome) via {@link _defer2D}; the scheduler
+     * flushes them with {@link _flush2D} *after* the GPU fence, so the
+     * 2D canvases don't present ahead of the GL frame. The GL pass
+     * resets `_deferred2D` first so a mid-pass throw can't leak stale
+     * closures into the next frame.
      *
      * Every render-triggering caller — upload chunks, zoom / pan,
      * resize, theme invalidation, host-driven redraws — calls this.
-     * The only sanctioned bypass is `snapshotPng`, which calls
-     * `_fullRender` directly to keep the GL backbuffer intact for
+     * The only sanctioned bypass is `snapshotPng`, which uses
+     * {@link renderFrameSync} to keep the GL backbuffer intact for
      * `gl.readPixels`.
      */
     requestRender(glManager: WebGLContextManager): Promise<void> {
-        return scheduleRender(glManager, () => this._fullRender(glManager));
+        return scheduleRender(
+            glManager,
+            () => {
+                this._deferred2D = [];
+                this._fullRender(glManager);
+            },
+            () => this._flush2D(),
+        );
+    }
+
+    /**
+     * Queue a 2D-canvas draw (gridline or chrome) to run after the
+     * GPU fence. Called from the chart renderers in place of drawing to
+     * the gridline/chrome canvases inline during the GL pass. See
+     * {@link _deferred2D}.
+     */
+    _defer2D(fn: () => void): void {
+        this._deferred2D.push(fn);
+    }
+
+    /**
+     * Run and clear the queued 2D-canvas draws. Invoked by the scheduler
+     * after `awaitGpuFence` (Phase 2), and by {@link renderFrameSync}.
+     */
+    _flush2D(): void {
+        const draws = this._deferred2D;
+        this._deferred2D = [];
+        for (const draw of draws) {
+            draw();
+        }
+    }
+
+    /**
+     * Synchronous full frame (GL + 2D) for the `snapshotPng` bypass,
+     * which sits outside the scheduler and needs the gridline/chrome
+     * canvases painted before it composites them. Resets the deferred
+     * queue, runs the GL pass, then flushes the 2D draws immediately
+     * (no fence split — a snapshot isn't presented to the compositor).
+     */
+    renderFrameSync(glManager: WebGLContextManager): void {
+        this._deferred2D = [];
+        this._fullRender(glManager);
+        this._flush2D();
     }
 
     //  Lifecycle

package/src/ts/charts/chart.ts

@@ -44,13 +44,23 @@ export interface ChartImplementation {
     requestRender(glManager: WebGLContextManager): Promise<void>;
 
     /**
-     * The chart-specific frame builder. The scheduler wraps this with
-     * fence + `endFrame`; callers must not invoke it directly except
-     * for `snapshotPng`, which needs an intact GL backbuffer for
-     * `gl.readPixels` and so must skip the `endFrame` pair.
+     * The chart-specific GL frame builder. Submits the GL draw commands
+     * and stashes the frame's 2D-canvas draws (gridlines + chrome) for
+     * the scheduler to flush after `awaitGpuFence`. The scheduler wraps
+     * this with fence + 2D flush + `endFrame`; callers must not invoke
+     * it directly — `snapshotPng` uses {@link renderFrameSync} instead.
      */
     _fullRender(glManager: WebGLContextManager): void;
 
+    /**
+     * Synchronous full frame (GL + 2D) for the `snapshotPng` bypass,
+     * which sits outside the scheduler and needs the gridline/chrome
+     * canvases painted before compositing. Runs the GL pass then flushes
+     * the deferred 2D draws immediately, skipping the fence split and
+     * `endFrame` so the GL backbuffer stays intact for `gl.readPixels`.
+     */
+    renderFrameSync(glManager: WebGLContextManager): void;
+
     /**
      * Hand the current View to the chart so it can make on-demand
      * per-row queries (for lazy tooltip column lookups). Called on
@@ -174,6 +184,15 @@ export interface ChartImplementation {
      */
     resetExpandedDomain?(): void;
 
+    /**
+     * Silently clear any active selection state (pinned tooltip) WITHOUT
+     * emitting selection events. Driven from the host's `deselect`
+     * message — its global filter bar removed a clause this chart's
+     * selection contributed, so an unselect emit would double-mutate the
+     * host's filter set.
+     */
+    deselect?(): void;
+
     destroy(): void;
 }
 
@@ -246,8 +265,19 @@ export interface PluginConfig {
      * Faceting strategy when `split_by` is non-empty.
      *
      * - `"grid"` — one small-multiple sub-plot per split group.
-     * - `"overlay"` — single plot with split groups differentiated by
-     *   color. Synced into `_facetConfig.facet_mode`.
+     * - `"overlay"` — a single plot: cartesian charts differentiate
+     *   split groups by color; the categorical band pipeline (series
+     *   charts) stacks splits within each aggregate's band slot.
+     *   Synced into `_facetConfig.facet_mode`.
+     *
+     * The default differs by family via
+     * `ChartTypeConfig.plugin_field_defaults`: cartesian / density /
+     * map chart types default to `"grid"`, the series / financial
+     * band-pipeline types to `"overlay"` (their historical split
+     * rendering). Series charts REBUILD on a mode change — grid mode
+     * keys the stack ladder per split (`facetSplits` in
+     * `buildSeriesPipeline`) so each facet grows from its own
+     * baseline.
      */
     facet_mode: "grid" | "overlay";
 
@@ -283,15 +313,23 @@ export interface PluginConfig {
     /**
      * Domain accumulation policy across successive `View` updates.
      *
-     * - `"fit"` — every update recomputes the rendered domain (and on
-     *   cartesian charts, the X/Y range and color/size scales) from
+     * - `"fit"` — every update recomputes the affected domains from
      *   the current data extent. Can grow or shrink frame-to-frame.
-     * - `"expand"` — the rendered domain monotonically *grows*: each
+     * - `"expand"` — the affected domains monotonically *grow*: each
      *   update unions the new data extent with the previously rendered
      *   extent, so once a value is in scope it stays in scope. Reset
      *   by the "Reset Zoom" button, view-config changes (group_by /
      *   split_by / column-slot / column-type), or toggling back to
      *   `"fit"`.
+     *
+     * AXIS SCOPE differs by family: cartesian charts (X/Y Scatter,
+     * X/Y Line, Density, Maps) apply it to BOTH axes plus the
+     * color/size scales (categorical string axes opt out — slot
+     * indices are frame-local); the categorical band pipeline (series
+     * / financial) applies it to the VALUE axis only — Y for the
+     * Y-family, X for X Bar — while the category axis always fits, so
+     * a streaming numeric/datetime `group_by` axis releases departed
+     * categories instead of pinning to its history.
      */
     domain_mode: "fit" | "expand";
 

package/src/ts/charts/common/category-axis-resolver.ts

@@ -157,7 +157,11 @@ function formatLevelValue(
     valid: boolean,
     levelType: string,
 ): string {
-    if (!valid) {
+    // `value` can be `undefined` even when `valid` claims otherwise — an
+    // out-of-bounds read when a row window outran the delivered Arrow
+    // (belt to `loadAndRender`'s delivered-rows clamp) — treat it as
+    // null rather than crash the label formatters.
+    if (!valid || value == null || Number.isNaN(value)) {
         return "";
     }