@perspective-dev/viewer-charts 4.5.1 → 5.0.0

package/src/ts/charts/series/series.ts

@@ -13,6 +13,7 @@
 import type { ColumnDataMap } from "../../data/view-reader";
 import type { WebGLContextManager } from "../../webgl/context-manager";
 import type { ZoomConfig } from "../../interaction/zoom-controller";
+import type { FacetGrid } from "../../layout/facet-grid";
 import { CategoricalYChart } from "../common/categorical-y-chart";
 import { type PlotRect } from "../../layout/plot-layout";
 import { type AxisDomain } from "../../axis/numeric-axis";
@@ -123,6 +124,35 @@ export class SeriesChart extends CategoricalYChart {
     _splitPrefixes: string[] = [];
     _series: SeriesInfo[] = [];
 
+    /**
+     * Whether the CURRENT build's geometry was produced for facet-grid
+     * mode (`facet_mode: "grid"` with real splits). The render / hover
+     * paths branch on this — never on the live `_facetConfig` — so a
+     * `setPluginConfig` that flips `facet_mode` between a build and a
+     * redraw can't pair grid-mode rendering with overlay-built stack
+     * geometry (or vice versa). The host always follows a
+     * `plugin.restore` with an `update` → `loadAndRender`, so the flag
+     * catches up one build later.
+     */
+    _facetActive = false;
+
+    /**
+     * Facet grid of the most recent faceted frame — one cell per
+     * split group. `null` in overlay / no-split frames. Read by the
+     * chrome overlay, hover hit-test, and tooltip pin to resolve the
+     * per-facet `PlotLayout`.
+     */
+    _facetGrid: FacetGrid | null = null;
+
+    /**
+     * Per-split contiguous instance ranges in the uploaded bar
+     * buffers, indexed by `splitIdx`. Populated by
+     * `uploadBarInstances` when `_facetActive` (instances are emitted
+     * split-major); `null` in overlay mode. Each facet's draw binds
+     * the instance attributes at `start` and draws `count` instances.
+     */
+    _facetBarRanges: { start: number; count: number }[] | null = null;
+
     /**
      * Columnar bar/area record storage. Indexed by bar slot in
      * `[0, _bars.count)`. Replaces the legacy `SeriesChartRecord[]` to
@@ -205,8 +235,12 @@ export class SeriesChart extends CategoricalYChart {
 
     /**
      * `domain_mode: "expand"` accumulators. Hold the running union of
-     * every prior build's value-axis (and, in numeric-category mode,
-     * category-axis) extent for as long as the option is active.
+     * every prior build's VALUE-axis extents (primary + alt) for as
+     * long as the option is active. The category axis deliberately has
+     * NO accumulator: `domain_mode` scopes to the value axis only on
+     * band charts (Y for the Y-family, X for X Bar) — a numeric or
+     * datetime `group_by` axis always fits the current data, so a
+     * streaming chart's time axis releases departed categories.
      * Cleared in `resetExpandedDomain` — wired from the worker's
      * `resetAllZooms` and from view-config mutations on the base
      * class. `null` whenever the option is `"fit"` or the accumulator
@@ -214,7 +248,6 @@ export class SeriesChart extends CategoricalYChart {
      */
     _expandedLeftDomain: { min: number; max: number } | null = null;
     _expandedRightDomain: { min: number; max: number } | null = null;
-    _expandedCategoryDomain: { min: number; max: number } | null = null;
 
     /**
      * Numeric category-axis state. Populated only when `group_by` has
@@ -296,7 +329,13 @@ export class SeriesChart extends CategoricalYChart {
      */
     _visibleBarIndices: Int32Array = new Int32Array(0);
 
-    _legendRects: { seriesId: number; rect: PlotRect }[] = [];
+    /**
+     * Hit-test rects for legend entries. Overlay mode: one entry per
+     * series (`seriesIds.length === 1`). Facet-grid mode: one entry
+     * per AGGREGATE, carrying every split's seriesId — a legend
+     * toggle hides/shows the aggregate across all facets at once.
+     */
+    _legendRects: { seriesIds: number[]; rect: PlotRect }[] = [];
 
     /**
      * Cached legend layout — recomputed only on series-set / palette /
@@ -362,7 +401,14 @@ export class SeriesChart extends CategoricalYChart {
                     this._hoveredBarIdx = -1;
                     this._hoveredSample = null;
                     if (this._glManager) {
-                        renderBarFrame(this, this._glManager);
+                        // Route through the scheduler (not a direct
+                        // `renderBarFrame`) so the frame is serialized
+                        // against sibling charts sharing a pooled GL
+                        // context in blit mode — a direct render would
+                        // paint into the shared canvas outside the
+                        // present cycle and leak into another plugin's
+                        // frame.
+                        this.requestRender(this._glManager);
                     }
                 }
             },
@@ -479,6 +525,9 @@ export class SeriesChart extends CategoricalYChart {
             this._cornerBuffer = createQuadCornerBuffer(gl);
         }
 
+        const facetSplits =
+            this._splitBy.length > 0 && this._facetConfig.facet_mode === "grid";
+
         const result = buildSeriesPipeline({
             columns,
             numRows: endRow,
@@ -497,15 +546,21 @@ export class SeriesChart extends CategoricalYChart {
             bandInnerFrac: this._pluginConfig.band_inner_frac,
             barInnerPad: this._pluginConfig.bar_inner_pad,
             includeZero: this._pluginConfig.include_zero,
+            facetSplits,
             scratchBars: this._bars,
             scratchPosStack: this._posStackScratch,
             scratchNegStack: this._negStackScratch,
         });
 
-        // `domain_mode: "expand"` post-build union. Each call mutates
-        // the pipeline result in place so the downstream assignments
-        // below (`_leftDomain`, `_rightDomain`, `_numericCategoryDomain`,
-        // `_categoryOrigin`) automatically pick up the grown extent.
+        // `domain_mode: "expand"` post-build union — VALUE axes only
+        // (`leftDomain`/`rightDomain` are the logical value domains,
+        // orientation-agnostic, so this is Y for the Y-family and X for
+        // X Bar). The category axis is NEVER expanded: it identifies
+        // the data, and pinning a numeric/datetime `group_by` axis to
+        // departed categories froze streaming charts on their full
+        // history. Each call mutates the pipeline result in place so
+        // the downstream assignments below (`_leftDomain`,
+        // `_rightDomain`) automatically pick up the grown extent.
         // `"fit"` (or a fresh reset) leaves the result untouched and
         // clears the accumulators so the next toggle starts fresh.
         if (this._pluginConfig.domain_mode === "expand") {
@@ -513,27 +568,25 @@ export class SeriesChart extends CategoricalYChart {
                 this._expandedLeftDomain,
                 result.leftDomain,
             );
+
             if (result.rightDomain) {
                 this._expandedRightDomain = expandDomainInPlace(
                     this._expandedRightDomain,
                     result.rightDomain,
                 );
             }
-
-            if (result.numericCategoryDomain) {
-                this._expandedCategoryDomain = expandDomainInPlace(
-                    this._expandedCategoryDomain,
-                    result.numericCategoryDomain,
-                );
-            }
         } else {
             this._expandedLeftDomain = null;
             this._expandedRightDomain = null;
-            this._expandedCategoryDomain = null;
         }
 
         this._aggregates = result.aggregates;
         this._splitPrefixes = result.splitPrefixes;
+
+        // Stamp AFTER the build so render always branches on the mode
+        // the geometry was actually built for. A single "" prefix means
+        // no real splits — facet mode degenerates to the single plot.
+        this._facetActive = facetSplits && result.splitPrefixes.length > 1;
         this._rowPaths = result.rowPaths;
         this._numCategories = result.numCategories;
         this._rowOffset = result.rowOffset;
@@ -638,7 +691,6 @@ export class SeriesChart extends CategoricalYChart {
     override resetExpandedDomain(): void {
         this._expandedLeftDomain = null;
         this._expandedRightDomain = null;
-        this._expandedCategoryDomain = null;
     }
 
     protected destroyInternal(): void {
@@ -654,6 +706,9 @@ export class SeriesChart extends CategoricalYChart {
         this._program = null;
         this._locations = null;
         this._cornerBuffer = null;
+        this._facetActive = false;
+        this._facetGrid = null;
+        this._facetBarRanges = null;
         this._bars = emptyBarColumns();
         this._series = [];
         this._barSeries = [];
@@ -718,9 +773,16 @@ function uniqueAggLabels(series: SeriesInfo[], axis: 0 | 1): string {
 /**
  * Resolve the per-series palette and stamp it onto `_series[i].color`.
  * Cached on `_paletteCache` keyed by reference identity of the theme
- * inputs + series count — only `restyle()` (which clears `_paletteCache`
- * via `invalidateTheme`) or a data load (which clears it explicitly)
- * forces re-resolution.
+ * inputs + resolved color count — only `restyle()` (which clears
+ * `_paletteCache` via `invalidateTheme`) or a data load (which clears
+ * it explicitly) forces re-resolution.
+ *
+ * Facet-grid mode colors by AGGREGATE, not by (agg × split) series:
+ * the facet is the axis of splitting, so aggregate `k` renders the
+ * same color in every facet and the legend lists aggregates once.
+ * Overlay mode keeps the per-series palette (splits are distinguished
+ * by color there). `_facetActive` only changes at build time, which
+ * clears the cache, so the stamp mode can't go stale.
  *
  * Returns true when the cache changed (caller invalidates color upload).
  */
@@ -728,7 +790,9 @@ export function ensurePalette(chart: SeriesChart): boolean {
     const theme = chart._resolveTheme();
     const seriesPalette = theme.seriesPalette;
     const gradientStops = theme.gradientStops;
-    const seriesLength = chart._series.length;
+    const paletteCount = chart._facetActive
+        ? Math.max(1, chart._aggregates.length)
+        : chart._series.length;
 
     const key = chart._paletteCacheKey;
     if (
@@ -736,7 +800,7 @@ export function ensurePalette(chart: SeriesChart): boolean {
         key &&
         key.seriesPalette === seriesPalette &&
         key.gradientStops === gradientStops &&
-        key.seriesLength === seriesLength
+        key.seriesLength === paletteCount
     ) {
         return false;
     }
@@ -744,13 +808,19 @@ export function ensurePalette(chart: SeriesChart): boolean {
     const palette = resolvePaletteCached(
         seriesPalette,
         gradientStops,
-        seriesLength,
+        paletteCount,
     );
     chart._paletteCache = palette;
-    chart._paletteCacheKey = { seriesPalette, gradientStops, seriesLength };
+    chart._paletteCacheKey = {
+        seriesPalette,
+        gradientStops,
+        seriesLength: paletteCount,
+    };
 
     for (let i = 0; i < chart._series.length; i++) {
-        chart._series[i].color = palette[i];
+        chart._series[i].color = chart._facetActive
+            ? palette[chart._series[i].aggIdx]
+            : palette[i];
     }
 
     return true;

package/src/ts/charts/sunburst/sunburst-interact.ts

@@ -13,7 +13,6 @@
 import type { SunburstChart } from "./sunburst";
 import { NULL_NODE } from "../common/node-store";
 import {
-    renderSunburstFrame,
     renderSunburstChromeOverlay,
     facetCenterForNode,
 } from "./sunburst-render";
@@ -264,7 +263,7 @@ export function handleSunburstClick(
                 }
 
                 if (chart._glManager) {
-                    renderSunburstFrame(chart, chart._glManager);
+                    chart.requestRender(chart._glManager);
                 }
             }
 
@@ -289,7 +288,7 @@ export function handleSunburstClick(
 function drillTo(chart: SunburstChart, nodeId: number): void {
     treeDrillTo(chart, nodeId, () => {
         if (chart._glManager) {
-            renderSunburstFrame(chart, chart._glManager);
+            chart.requestRender(chart._glManager);
         }
     });
 }

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

@@ -189,7 +189,9 @@ export function renderSunburstFrame(
         drawArcs(chart, gl, glManager, 0, chart._instanceCount);
     }
 
-    renderSunburstChromeOverlay(chart);
+    // Deferred past the GPU fence (see `_defer2D`) so the chrome canvas
+    // doesn't present ahead of the GL arcs on resize.
+    chart._defer2D(() => renderSunburstChromeOverlay(chart));
 }
 
 /**

package/src/ts/charts/treemap/treemap-interact.ts

@@ -13,10 +13,7 @@
 import type { TreemapChart } from "./treemap";
 import { NULL_NODE } from "../common/node-store";
 import { PADDING_LABEL } from "./treemap-layout";
-import {
-    renderTreemapFrame,
-    renderTreemapChromeOverlay,
-} from "./treemap-render";
+import { renderTreemapChromeOverlay } from "./treemap-render";
 import {
     buildTreeTooltipLines,
     dismissTreePinnedTooltip,
@@ -254,7 +251,7 @@ export function handleTreemapDblClick(
 function drillTo(chart: TreemapChart, nodeId: number): void {
     treeDrillTo(chart, nodeId, () => {
         if (chart._glManager) {
-            renderTreemapFrame(chart, chart._glManager);
+            chart.requestRender(chart._glManager);
         }
     });
 }

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

@@ -173,7 +173,9 @@ export function renderTreemapFrame(
 
     gl.drawArrays(gl.TRIANGLES, 0, chart._vertexCount);
 
-    renderTreemapChromeOverlay(chart);
+    // Deferred past the GPU fence (see `_defer2D`) so the chrome canvas
+    // doesn't present ahead of the GL tiles on resize.
+    chart._defer2D(() => renderTreemapChromeOverlay(chart));
 }
 
 /**

package/src/ts/charts/treemap/treemap.ts

@@ -109,7 +109,12 @@ export class TreemapChart extends TreeChartBase {
                 ) {
                     this._hoveredNodeId = NULL_NODE;
                     if (this._glManager) {
-                        renderTreemapFrame(this, this._glManager);
+                        // Schedule through the render scheduler rather
+                        // than painting directly — a direct frame render
+                        // bypasses the per-context serialization and, in
+                        // pooled blit mode, corrupts a sibling chart's
+                        // in-flight shared-canvas frame.
+                        this.requestRender(this._glManager);
                     }
                 }
             },

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/data/view-reader.ts

@@ -50,10 +50,19 @@ export interface TypedArrayWindowOptions {
  * `Promise`, the underlying `with_typed_arrays` call awaits it before
  * releasing the backing Arrow buffer. Callers must not retain any
  * `ColumnData` reference past `render`'s resolution.
+ *
+ * `render` also receives the DELIVERED row count — the shortest
+ * column's length, which may be less than the requested `end_row`:
+ * the engine clamps the window to the view's size at fetch time, and
+ * on a fast-updating table with deletions that size can shrink after
+ * the caller's `num_rows()` round-trip. Build pipelines must iterate
+ * to THIS count, never the requested one — a typed array indexed past
+ * its length returns `undefined`, which no amount of validity-bitmap
+ * checking catches (the bitmap read is out-of-bounds too).
  */
 export async function viewToColumnDataMap(
     view: View,
-    render: (data: ColumnDataMap) => void | Promise<void>,
+    render: (data: ColumnDataMap, numRows: number) => void | Promise<void>,
     options?: TypedArrayWindowOptions,
 ): Promise<void> {
     const result: ColumnDataMap = new Map();
@@ -101,7 +110,18 @@ export async function viewToColumnDataMap(
                 }
             }
 
-            await render(result);
+            let numRows = 0;
+            if (result.size > 0) {
+                numRows = Infinity;
+                for (const col of result.values()) {
+                    const n = col.indices?.length ?? col.values?.length ?? 0;
+                    if (n < numRows) {
+                        numRows = n;
+                    }
+                }
+            }
+
+            await render(result, numRows);
         },
     );
 }

package/src/ts/event-detail.ts

@@ -39,6 +39,14 @@ export interface PerspectiveClickDetail {
      * `[<col>, "==", <value>]` clauses.
      */
     config: Partial<ViewConfig>;
+
+    /**
+     * The source panel's `slot` name in a multi-panel `<perspective-viewer>`,
+     * so the host can attribute the click to the originating panel. `undefined`
+     * for a lone, unslotted viewer. Mirrors `PerspectiveSelectDetail.panel` and
+     * the datagrid `PerspectiveClickDetail`.
+     */
+    panel?: string;
 }
 
 export { PerspectiveSelectDetail } from "@perspective-dev/viewer/src/ts/extensions.js";

package/src/ts/index.ts

@@ -23,17 +23,17 @@ export function register(...plugin_names: string[]) {
             : CHARTS.map((chart) => chart.name),
     );
 
+    const already_registered: string[] = [];
+
     CHARTS.forEach((chart) => {
         if (plugins.has(chart.name)) {
             const tagName = `perspective-viewer-charts-${chart.tag}`;
 
-            // Each registered tag is a thin subclass that pins
-            // `_chartType` so `draw()` / `save()` / etc. know which
-            // `ChartTypeConfig` they're driving. The chart impl
-            // class itself lives in the worker bundle — only
-            // `ChartTypeConfig.tag` crosses the host/renderer
-            // boundary, and the renderer constructs the impl from
-            // its own `CHART_IMPLS` registry.
+            if (customElements.get(tagName)) {
+                already_registered.push(tagName);
+                return;
+            }
+
             customElements.define(
                 tagName,
                 class extends HTMLPerspectiveViewerWebGLPluginElement {
@@ -48,6 +48,12 @@ export function register(...plugin_names: string[]) {
             });
         }
     });
+
+    if (already_registered.length > 0) {
+        console.warn(
+            `viewer-charts plugins already registered (${already_registered.length}); skipping duplicate registration (Perspective was loaded more than once on this page).`,
+        );
+    }
 }
 
 register();

package/src/ts/interaction/raw-event-forwarder.ts

@@ -55,6 +55,13 @@ export class RawEventForwarder {
         };
 
         this._onPointerDown = (e: PointerEvent) => {
+            // Only forward primary-button pointerdowns. Right/middle clicks must
+            // reach the panel's `contextmenu` handler — capturing the pointer
+            // here would otherwise swallow the right-click.
+            if (e.button !== 0) {
+                return;
+            }
+
             const rect = element.getBoundingClientRect();
             const mx = e.clientX - rect.left;
             const my = e.clientY - rect.top;

package/src/ts/interaction/zoom-controller.ts

@@ -388,6 +388,14 @@ export class ZoomController {
         };
 
         this._onPointerDown = (e: PointerEvent) => {
+            // Only the primary (left) button starts a pan. Right/middle clicks
+            // must fall through so the panel's `contextmenu` handler can open
+            // the menu — capturing the pointer here would otherwise swallow the
+            // right-click.
+            if (e.button !== 0) {
+                return;
+            }
+
             const rect = element.getBoundingClientRect();
             const mouseX = e.clientX - rect.left;
             const mouseY = e.clientY - rect.top;

package/src/ts/layout/ticks.ts

@@ -72,8 +72,17 @@ export function computeNiceTicks(
 /**
  * Format a numeric tick value for display.
  * Uses K/M/B suffixes for large numbers, fixed decimals for small.
+ *
+ * Total over any input: label formatters run inside render passes, so a
+ * non-finite value (or `undefined` smuggled in by an upstream
+ * out-of-bounds read) must degrade to a placeholder, never throw the
+ * frame away.
  */
 export function formatTickValue(val: number): string {
+    if (!Number.isFinite(val)) {
+        return "-";
+    }
+
     const abs = Math.abs(val);
     if (abs === 0) {
         return "0";

package/src/ts/plugin/charts.ts

@@ -48,9 +48,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>;
 }
@@ -85,10 +88,19 @@ const SERIES_FIELDS: readonly PluginConfigField[] = [
     "bar_inner_pad",
 ];
 
+// The band pipeline's historical split_by rendering is a single plot
+// (splits stacked / colored in place), so the series family defaults
+// `facet_mode` to "overlay" — grid faceting is the opt-in. Cartesian
+// charts keep the global "grid" default from `DEFAULT_PLUGIN_CONFIG`.
+const SERIES_DEFAULTS: Partial<PluginConfig> = { facet_mode: "overlay" };
+
 // Bar / area series glyphs grow from the zero baseline, so the value
 // axis must enclose 0 to render correctly. Line / scatter glyphs have
 // no such constraint — their default `include_zero` stays `false`.
-const ZERO_ANCHORED_DEFAULTS: Partial<PluginConfig> = { include_zero: true };
+const ZERO_ANCHORED_DEFAULTS: Partial<PluginConfig> = {
+    ...SERIES_DEFAULTS,
+    include_zero: true,
+};
 
 // Pure Cartesian (X/Y Scatter, X/Y Line) — no categorical axis, so no
 // band geometry; gets the facet-routing variant of zoom_mode.
@@ -210,9 +222,11 @@ const CHARTS: ChartTypeConfig[] = [
     }),
     make("Y Line", "y-line", SERIES, SELECT, 1, Y_AXIS, SERIES_FIELDS, {
         default_chart_type: "line",
+        plugin_field_defaults: SERIES_DEFAULTS,
     }),
     make("Y Scatter", "y-scatter", SERIES, SELECT, 1, Y_AXIS, SERIES_FIELDS, {
         default_chart_type: "scatter",
+        plugin_field_defaults: SERIES_DEFAULTS,
     }),
     make("Y Area", "y-area", SERIES, SELECT, 1, Y_AXIS, SERIES_FIELDS, {
         default_chart_type: "area",
@@ -250,9 +264,11 @@ const CHARTS: ChartTypeConfig[] = [
     make("Heatmap", "heatmap", HIER, SELECT, 1, ["Color"], HEATMAP_FIELDS),
     make("Candlestick", "candlestick", FIN, TOGGLE, 1, FIN_NAMES, FIN_FIELDS, {
         default_chart_type: "candlestick",
+        plugin_field_defaults: SERIES_DEFAULTS,
     }),
     make("OHLC", "ohlc", FIN, TOGGLE, 1, FIN_NAMES, FIN_FIELDS, {
         default_chart_type: "ohlc",
+        plugin_field_defaults: SERIES_DEFAULTS,
     }),
     make(
         "Map Scatter",