@perspective-dev/viewer-charts 4.5.2 → 5.1.0

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

package/src/ts/charts/common/tree-data.ts

@@ -156,6 +156,33 @@ function insertRow(
     }
 }
 
+/**
+ * Arrow validity-bitmap test. Columns without a bitmap are all-valid.
+ */
+function isValidCell(col: ColumnData, rowIdx: number): boolean {
+    const v = col.valid;
+    return !v || !!((v[rowIdx >> 3] >> (rowIdx & 7)) & 1);
+}
+
+/**
+ * Read a size cell, honoring the validity bitmap: the bytes under an
+ * invalid slot are UNDEFINED (DuckDB's Arrow leaves NaN where the
+ * engine zero-fills), and a NaN here would poison every ancestor sum
+ * in `finalizeTree`. Invalid → 0 (no contribution); no size column at
+ * all → 1 (count semantics).
+ */
+function readSize(col: ColumnData | null | undefined, rowIdx: number): number {
+    if (!col?.values) {
+        return 1;
+    }
+
+    if (!isValidCell(col, rowIdx)) {
+        return 0;
+    }
+
+    return col.values[rowIdx] as number;
+}
+
 function readColor(
     chart: TreeChartBase,
     colorCol: ColumnData | null | undefined,
@@ -163,7 +190,7 @@ function readColor(
 ): { colorValue: number; colorLabel: string } {
     let colorValue = NaN;
     let colorLabel = "";
-    if (!colorCol) {
+    if (!colorCol || !isValidCell(colorCol, rowIdx)) {
         return { colorValue, colorLabel };
     }
 
@@ -261,7 +288,11 @@ export function processTreeChunk(
     chart: TreeChartBase,
     columns: ColumnDataMap,
 ): void {
-    const rpCols: { indices: Int32Array; dictionary: string[] }[] = [];
+    const rpCols: {
+        indices: Int32Array;
+        dictionary: string[];
+        valid?: Uint8Array;
+    }[] = [];
     for (let n = 0; ; n++) {
         const rp = columns.get(`__ROW_PATH_${n}__`);
         if (!rp) {
@@ -269,7 +300,11 @@ export function processTreeChunk(
         }
 
         if (rp.type === "string" && rp.indices && rp.dictionary) {
-            rpCols.push({ indices: rp.indices, dictionary: rp.dictionary });
+            rpCols.push({
+                indices: rp.indices,
+                dictionary: rp.dictionary,
+                valid: rp.valid,
+            });
         } else if (rp.values) {
             // Non-string group_by (integer / float / date / datetime /
             // boolean) — synthesize a string-indexed dictionary so the
@@ -397,9 +432,7 @@ export function processTreeChunk(
                     // Pass the signed value through; `insertRow` stores
                     // `|size|` and `sizeSign` separately so the
                     // render pass can dim negative leaves.
-                    const sizeValue = src.sizeCol?.values
-                        ? (src.sizeCol.values[i] as number)
-                        : 1;
+                    const sizeValue = readSize(src.sizeCol, i);
                     const { colorValue, colorLabel } = readColor(
                         chart,
                         src.colorCol,
@@ -416,9 +449,7 @@ export function processTreeChunk(
                     );
                 }
             } else {
-                const sizeValue = sizeCol?.values
-                    ? (sizeCol.values[i] as number)
-                    : 1;
+                const sizeValue = readSize(sizeCol, i);
                 const { colorValue, colorLabel } = readColor(
                     chart,
                     colorCol,
@@ -449,6 +480,19 @@ export function processTreeChunk(
         let pathLen = 0;
         for (let d = 0; d < rpCols.length; d++) {
             const rp = rpCols[d];
+
+            // In `"rollup"` mode the view emits total / subtotal rows
+            // whose deeper row-path levels are INVALID — index slot 0,
+            // which decodes to a REAL dictionary value (the engine's
+            // string row-path dictionaries carry no `""` sentinel), so
+            // the validity bitmap is the only truthful signal. Truncate
+            // the path at the first invalid level; the `!label` check
+            // below still covers synthesized non-string levels, whose
+            // dictionary index 0 IS the `""` sentinel.
+            if (rp.valid && !((rp.valid[i >> 3] >> (i & 7)) & 1)) {
+                break;
+            }
+
             const label = rp.dictionary[rp.indices[i]];
             if (!label && label !== "0") {
                 break;
@@ -465,9 +509,7 @@ export function processTreeChunk(
             for (const src of splitSources!) {
                 pathScratch[0] = src.prefix;
                 const rowPath = pathScratch.slice(0, pathLen + 1);
-                const sizeValue = src.sizeCol?.values
-                    ? (src.sizeCol.values[i] as number)
-                    : 1;
+                const sizeValue = readSize(src.sizeCol, i);
                 const { colorValue, colorLabel } = readColor(
                     chart,
                     src.colorCol,
@@ -485,9 +527,7 @@ export function processTreeChunk(
             }
         } else {
             const rowPath = pathScratch.slice(0, pathLen);
-            const sizeValue = sizeCol?.values
-                ? (sizeCol.values[i] as number)
-                : 1;
+            const sizeValue = readSize(sizeCol, i);
             const { colorValue, colorLabel } = readColor(chart, colorCol, i);
             insertRow(
                 chart,
@@ -556,7 +596,12 @@ export function finalizeTree(chart: TreeChartBase): void {
             }
         } else {
             if (firstChild[id] === NULL_NODE) {
-                value[id] = Math.max(0, size[id]);
+                // NOT `Math.max(0, x)`: that maps NaN → NaN, and one NaN
+                // leaf would poison every ancestor sum (dropping whole
+                // subtrees in `squarify`'s `value > 0` filter). The
+                // comparison form maps NaN → 0.
+                const s = size[id];
+                value[id] = s > 0 ? s : 0;
             } else {
                 let sum = 0;
                 for (

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

@@ -225,7 +225,9 @@ export function renderHeatmapFrame(
         drawCellsInstanced(chart, gl, glManager, 0, chart._uploadedCells);
     });
 
-    renderHeatmapChromeOverlay(chart);
+    // Deferred past the GPU fence (see `_defer2D`) so the chrome canvas
+    // doesn't present ahead of the GL cells on resize.
+    chart._defer2D(() => renderHeatmapChromeOverlay(chart));
 }
 
 function ensureProgram(
@@ -650,7 +652,9 @@ function renderFacetedHeatmap(
         });
     }
 
-    renderHeatmapChromeOverlay(chart);
+    // Deferred past the GPU fence (see `_defer2D`) so the chrome canvas
+    // doesn't present ahead of the GL cells on resize.
+    chart._defer2D(() => renderHeatmapChromeOverlay(chart));
 }
 
 /**

package/src/ts/charts/series/glyphs/draw-areas.ts

@@ -187,7 +187,10 @@ export class AreaGlyph {
 
     /**
      * Bind persistent strip buffers and dispatch one TRIANGLE_STRIP per
-     * series-run. Skips hidden series.
+     * series-run. Skips hidden series. `splitFilter` (faceted frames)
+     * draws only the series whose `splitIdx` matches; `aggRange` (mixed
+     * glyph-run frames) only those whose `aggIdx` lies in the inclusive
+     * run span.
      */
     draw(
         chart: SeriesChart,
@@ -196,6 +199,8 @@ export class AreaGlyph {
         projLeft: Float32Array,
         projRight: Float32Array,
         opacity: number,
+        splitFilter?: number,
+        aggRange?: { start: number; end: number },
     ): void {
         const buf = this._buffers;
         const cache = this._program;
@@ -212,6 +217,21 @@ export class AreaGlyph {
                 continue;
             }
 
+            if (
+                splitFilter !== undefined &&
+                chart._series[s.seriesId].splitIdx !== splitFilter
+            ) {
+                continue;
+            }
+
+            const aggIdx = chart._series[s.seriesId].aggIdx;
+            if (
+                aggRange !== undefined &&
+                (aggIdx < aggRange.start || aggIdx > aggRange.end)
+            ) {
+                continue;
+            }
+
             gl.uniformMatrix4fv(
                 cache.u_projection,
                 false,

package/src/ts/charts/series/glyphs/draw-bars.ts

@@ -30,13 +30,20 @@ type GL = WebGL2RenderingContext | WebGLRenderingContext;
 /**
  * Draw the bar-typed subset of `chart._bars` as instanced quads. Assumes
  * the caller has already `useProgram`'d the bar shader and set uniforms.
+ *
+ * `range` draws a contiguous instance sub-range instead of the full
+ * uploaded set — the faceted renderer uploads instances split-major
+ * (see `uploadBarInstances`) and dispatches one range per facet.
  */
 export function drawBars(
     chart: SeriesChart,
     gl: GL,
     glManager: WebGLContextManager,
+    range?: { start: number; count: number },
 ): void {
-    if (chart._uploadedBars === 0) {
+    const first = range?.start ?? 0;
+    const count = range?.count ?? chart._uploadedBars;
+    if (chart._uploadedBars === 0 || count === 0) {
         return;
     }
 
@@ -62,6 +69,7 @@ export function drawBars(
             loc.a_x_center,
             "bar_x",
             1,
+            first,
         ) &&
         bindInstancedFloatAttr(
             glManager,
@@ -69,15 +77,31 @@ export function drawBars(
             loc.a_half_width,
             "bar_hw",
             1,
+            first,
+        ) &&
+        bindInstancedFloatAttr(
+            glManager,
+            instancing,
+            loc.a_y0,
+            "bar_y0",
+            1,
+            first,
+        ) &&
+        bindInstancedFloatAttr(
+            glManager,
+            instancing,
+            loc.a_y1,
+            "bar_y1",
+            1,
+            first,
         ) &&
-        bindInstancedFloatAttr(glManager, instancing, loc.a_y0, "bar_y0", 1) &&
-        bindInstancedFloatAttr(glManager, instancing, loc.a_y1, "bar_y1", 1) &&
         bindInstancedFloatAttr(
             glManager,
             instancing,
             loc.a_color,
             "bar_color",
             3,
+            first,
         ) &&
         bindInstancedFloatAttr(
             glManager,
@@ -85,6 +109,7 @@ export function drawBars(
             loc.a_series_id,
             "bar_sid",
             1,
+            first,
         ) &&
         bindInstancedFloatAttr(
             glManager,
@@ -92,15 +117,11 @@ export function drawBars(
             loc.a_axis,
             "bar_axis",
             1,
+            first,
         );
 
     if (ok) {
-        instancing.drawArraysInstanced(
-            gl.TRIANGLE_STRIP,
-            0,
-            4,
-            chart._uploadedBars,
-        );
+        instancing.drawArraysInstanced(gl.TRIANGLE_STRIP, 0, 4, count);
     }
 
     setDivisor(loc.a_x_center, 0);

package/src/ts/charts/series/glyphs/draw-lines.ts

@@ -271,7 +271,10 @@ export class LineGlyph {
      * Bind the persistent vertex buffers and dispatch one instanced draw
      * per series. Skips hidden series via `_hiddenSeries`. Gap /
      * transparency rendering is governed by `u_interp_alpha`, set per
-     * series.
+     * series. `splitFilter` (faceted frames) draws only the series
+     * whose `splitIdx` matches — one call per facet. `aggRange` (mixed
+     * glyph-run frames) draws only the series whose `aggIdx` lies in
+     * the inclusive run span.
      */
     draw(
         chart: SeriesChart,
@@ -279,6 +282,8 @@ export class LineGlyph {
         glManager: WebGLContextManager,
         projLeft: Float32Array,
         projRight: Float32Array,
+        splitFilter?: number,
+        aggRange?: { start: number; end: number },
     ): void {
         const buf = this._buffers;
         const cache = this._program;
@@ -310,6 +315,21 @@ export class LineGlyph {
                 continue;
             }
 
+            if (
+                splitFilter !== undefined &&
+                chart._series[s.seriesId].splitIdx !== splitFilter
+            ) {
+                continue;
+            }
+
+            const aggIdx = chart._series[s.seriesId].aggIdx;
+            if (
+                aggRange !== undefined &&
+                (aggIdx < aggRange.start || aggIdx > aggRange.end)
+            ) {
+                continue;
+            }
+
             gl.uniformMatrix4fv(
                 cache.u_projection,
                 false,