@perspective-dev/viewer-charts 5.0.0 → 5.1.0

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

@@ -14,6 +14,7 @@ import type { Context2D } from "../canvas-types";
 import type { WebGLContextManager } from "../../webgl/context-manager";
 import {
     ensurePalette,
+    type GlyphRun,
     type SeriesChart,
     type SeriesAutoFitCache,
 } from "./series";
@@ -114,6 +115,8 @@ export function uploadBarInstances(
     let n = 0;
 
     chart._facetBarRanges = null;
+    chart._facetBarAggRanges = null;
+    chart._barAggRanges = null;
     if (total > 0) {
         const scratch = ensureBarInstanceScratch(total);
         if (
@@ -137,33 +140,60 @@ export function uploadBarInstances(
         const by1 = bars.y1;
         const ax = bars.axis;
 
-        // Facet mode: counting sort by splitIdx (`seriesId % P`). Pass
-        // 1 counts eligible instances per split; prefix sums become the
-        // per-split write cursors AND the published ranges.
-        let writeAt: ((seriesId: number) => number) | null = null;
-        if (faceted) {
-            const counts = new Array<number>(P).fill(0);
-            for (let i = 0; i < total; i++) {
-                if (ct[i] !== BAR_TYPE_BAR || hidden.has(sid[i])) {
-                    continue;
-                }
-
-                counts[sid[i] % P]++;
+        // Counting sort so contiguous instance ranges exist for every
+        // draw grouping. Overlay: key = aggIdx, publishing
+        // `_barAggRanges` — a glyph run `[aggStart, aggEnd]` is one
+        // contiguous slice, and within-call overlap Z follows `columns`
+        // declaration order. Faceted: key = splitIdx-major then aggIdx,
+        // publishing both the per-split `_facetBarRanges` (facet
+        // dispatch) and the per-(split, agg) `_facetBarAggRanges` (run
+        // slices within a facet). Pass 1 counts eligible instances per
+        // bucket; prefix sums become the write cursors AND the ranges.
+        const M = Math.max(1, chart._aggregates.length);
+        const bucketOf = faceted
+            ? (seriesId: number) =>
+                  (seriesId % P) * M + Math.floor(seriesId / P)
+            : (seriesId: number) =>
+                  P > 0 ? Math.floor(seriesId / P) : seriesId;
+        const numBuckets = faceted ? P * M : M;
+        const counts = new Array<number>(numBuckets).fill(0);
+        for (let i = 0; i < total; i++) {
+            if (ct[i] !== BAR_TYPE_BAR || hidden.has(sid[i])) {
+                continue;
             }
 
-            const ranges: { start: number; count: number }[] = [];
-            const cursors = new Int32Array(P);
-            let acc = 0;
-            for (let p = 0; p < P; p++) {
-                ranges.push({ start: acc, count: counts[p] });
-                cursors[p] = acc;
-                acc += counts[p];
-            }
+            counts[bucketOf(sid[i])]++;
+        }
 
-            chart._facetBarRanges = ranges;
-            writeAt = (seriesId: number) => cursors[seriesId % P]++;
+        const ranges: { start: number; count: number }[] = [];
+        const cursors = new Int32Array(numBuckets);
+        let acc = 0;
+        for (let b = 0; b < numBuckets; b++) {
+            ranges.push({ start: acc, count: counts[b] });
+            cursors[b] = acc;
+            acc += counts[b];
         }
 
+        if (faceted) {
+            chart._barAggRanges = null;
+            chart._facetBarAggRanges = Array.from({ length: P }, (_, p) =>
+                ranges.slice(p * M, (p + 1) * M),
+            );
+            chart._facetBarRanges = Array.from({ length: P }, (_, p) => {
+                const first = ranges[p * M];
+                const last = ranges[(p + 1) * M - 1];
+                return {
+                    start: first.start,
+                    count: last.start + last.count - first.start,
+                };
+            });
+        } else {
+            chart._barAggRanges = ranges;
+            chart._facetBarAggRanges = null;
+        }
+
+        const writeAt = (seriesId: number) => cursors[bucketOf(seriesId)]++;
+
         for (let i = 0; i < total; i++) {
             if (ct[i] !== BAR_TYPE_BAR) {
                 continue;
@@ -174,7 +204,7 @@ export function uploadBarInstances(
                 continue;
             }
 
-            const w = writeAt ? writeAt(seriesId) : n;
+            const w = writeAt(seriesId);
             scratch.xCenters[w] = xC[i] - xOrigin;
             scratch.halfWidths[w] = hw[i];
             scratch.y0s[w] = by0[i];
@@ -643,41 +673,18 @@ export function renderBarFrame(
         );
     }
 
+    const hovered = chart._series.length > 1 ? getHoveredBar(chart) : null;
     renderInPlotFrame(gl, layout, glManager.dpr, () => {
-        // Paint order: areas behind bars (so bar borders stay crisp),
-        // bars above, lines above those, scatter points on top. X Bar
-        // only paints bars — the other glyphs bake in vertical geometry
-        // and aren't supported for horizontal orientation.
-        if (!horizontal) {
-            chart._glyphs.areas.draw(
-                chart,
-                gl,
-                glManager,
-                projLeft,
-                projRight,
-                theme.areaOpacity,
-            );
-        }
-
-        gl.useProgram(chart._program!);
-        const loc = chart._locations!;
-        gl.uniformMatrix4fv(loc.u_proj_left, false, projLeft);
-        gl.uniformMatrix4fv(loc.u_proj_right, false, projRight);
-        gl.uniform1f(loc.u_horizontal, horizontal ? 1.0 : 0.0);
-        const hovered = chart._series.length > 1 ? getHoveredBar(chart) : null;
-        gl.uniform1f(loc.u_hover_series, hovered ? hovered.seriesId : -1);
-        drawBars(chart, gl, glManager);
-
-        if (!horizontal) {
-            chart._glyphs.lines.draw(chart, gl, glManager, projLeft, projRight);
-            chart._glyphs.scatter.draw(
-                chart,
-                gl,
-                glManager,
-                projLeft,
-                projRight,
-            );
-        }
+        drawGlyphRuns(
+            chart,
+            gl,
+            glManager,
+            projLeft,
+            projRight,
+            theme.areaOpacity,
+            horizontal,
+            hovered ? hovered.seriesId : -1,
+        );
     });
 
     chart._lastXDomain = catDomain;
@@ -694,6 +701,124 @@ export function renderBarFrame(
     chart._defer2D(() => renderBarChromeOverlay(chart));
 }
 
+/**
+ * Paint every glyph in `columns` declaration Z-order — one pass per
+ * {@link SeriesChart._glyphRuns} entry, ascending `aggIdx`, later
+ * columns on top; splits within an aggregate paint in `splitIdx`
+ * order. A homogeneous chart is a single run and takes exactly the
+ * legacy one-pass path (no per-series filtering, single instanced bar
+ * draw). X Bar (horizontal) paints bars only — the other glyphs bake
+ * vertical geometry.
+ *
+ * The caller wraps this in its plot clip (`renderInPlotFrame` /
+ * `withScissor`); `splitFilter` is the facet index in faceted frames.
+ */
+function drawGlyphRuns(
+    chart: SeriesChart,
+    gl: WebGL2RenderingContext | WebGLRenderingContext,
+    glManager: WebGLContextManager,
+    projLeft: Float32Array,
+    projRight: Float32Array,
+    areaOpacity: number,
+    horizontal: boolean,
+    hoveredSeriesId: number,
+    splitFilter?: number,
+): void {
+    const runs = chart._glyphRuns;
+    const single = runs.length <= 1;
+    for (const run of runs) {
+        const aggRange = single
+            ? undefined
+            : { start: run.aggStart, end: run.aggEnd };
+        switch (run.chartType) {
+            case "area":
+                if (!horizontal) {
+                    chart._glyphs.areas.draw(
+                        chart,
+                        gl,
+                        glManager,
+                        projLeft,
+                        projRight,
+                        areaOpacity,
+                        splitFilter,
+                        aggRange,
+                    );
+                }
+
+                break;
+            case "bar": {
+                gl.useProgram(chart._program!);
+                const loc = chart._locations!;
+                gl.uniformMatrix4fv(loc.u_proj_left, false, projLeft);
+                gl.uniformMatrix4fv(loc.u_proj_right, false, projRight);
+                gl.uniform1f(loc.u_horizontal, horizontal ? 1.0 : 0.0);
+                gl.uniform1f(loc.u_hover_series, hoveredSeriesId);
+                drawBars(
+                    chart,
+                    gl,
+                    glManager,
+                    barRunRange(chart, run, splitFilter),
+                );
+                break;
+            }
+
+            case "line":
+                if (!horizontal) {
+                    chart._glyphs.lines.draw(
+                        chart,
+                        gl,
+                        glManager,
+                        projLeft,
+                        projRight,
+                        splitFilter,
+                        aggRange,
+                    );
+                }
+
+                break;
+            case "scatter":
+                if (!horizontal) {
+                    chart._glyphs.scatter.draw(
+                        chart,
+                        gl,
+                        glManager,
+                        projLeft,
+                        projRight,
+                        splitFilter,
+                        aggRange,
+                    );
+                }
+
+                break;
+        }
+    }
+}
+
+/**
+ * The contiguous uploaded-instance slice for a bar run — per-aggregate
+ * ranges are adjacent by construction (`uploadBarInstances` counting
+ * sort), so the run `[aggStart, aggEnd]` spans from the first range's
+ * start through the last range's end. Faceted frames slice within the
+ * facet's split-major block.
+ */
+function barRunRange(
+    chart: SeriesChart,
+    run: GlyphRun,
+    splitFilter?: number,
+): { start: number; count: number } | undefined {
+    const table =
+        splitFilter !== undefined
+            ? chart._facetBarAggRanges?.[splitFilter]
+            : chart._barAggRanges;
+    if (!table) {
+        return splitFilter !== undefined ? { start: 0, count: 0 } : undefined;
+    }
+
+    const first = table[run.aggStart];
+    const last = table[run.aggEnd];
+    return { start: first.start, count: last.start + last.count - first.start };
+}
+
 /**
  * Domain window computed by `renderBarFrame`'s shared prologue (zoom
  * window + auto-fit + `include_zero`), handed to the faceted branch.
@@ -873,55 +998,17 @@ function renderFacetedBarFrame(
         }
 
         withScissor(gl, layout, dpr, () => {
-            // Same paint order as the single-plot path: areas behind
-            // bars, lines above, scatter on top. X Bar draws bars only
-            // (the other glyphs bake vertical geometry).
-            if (!horizontal) {
-                chart._glyphs.areas.draw(
-                    chart,
-                    gl,
-                    glManager,
-                    projLeft,
-                    projRight,
-                    theme.areaOpacity,
-                    p,
-                );
-            }
-
-            gl.useProgram(chart._program!);
-            const loc = chart._locations!;
-            gl.uniformMatrix4fv(loc.u_proj_left, false, projLeft);
-            gl.uniformMatrix4fv(loc.u_proj_right, false, projRight);
-            gl.uniform1f(loc.u_horizontal, horizontal ? 1.0 : 0.0);
-            gl.uniform1f(
-                loc.u_hover_series,
-                hovered && hovered.splitIdx === p ? hovered.seriesId : -1,
-            );
-            drawBars(
+            drawGlyphRuns(
                 chart,
                 gl,
                 glManager,
-                chart._facetBarRanges?.[p] ?? { start: 0, count: 0 },
+                projLeft,
+                projRight,
+                theme.areaOpacity,
+                horizontal,
+                hovered && hovered.splitIdx === p ? hovered.seriesId : -1,
+                p,
             );
-
-            if (!horizontal) {
-                chart._glyphs.lines.draw(
-                    chart,
-                    gl,
-                    glManager,
-                    projLeft,
-                    projRight,
-                    p,
-                );
-                chart._glyphs.scatter.draw(
-                    chart,
-                    gl,
-                    glManager,
-                    projLeft,
-                    projRight,
-                    p,
-                );
-            }
         });
     }
 

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

@@ -24,6 +24,7 @@ import {
     type SeriesChartRecord,
     type NumericCategoryDomain,
     type SeriesInfo,
+    type SeriesPipelineResult,
     type BarColumns,
     emptyBarColumns,
 } from "./series-build";
@@ -66,6 +67,16 @@ export interface SeriesAutoFitCache {
     hasRight: boolean;
 }
 
+/**
+ * One paint pass: the contiguous span of aggregates (`columns` indices,
+ * inclusive) sharing a glyph type. See {@link SeriesChart._glyphRuns}.
+ */
+export interface GlyphRun {
+    chartType: SeriesInfo["chartType"];
+    aggStart: number;
+    aggEnd: number;
+}
+
 export interface CachedLocations {
     u_proj_left: WebGLUniformLocation | null;
     u_proj_right: WebGLUniformLocation | null;
@@ -153,6 +164,32 @@ export class SeriesChart extends CategoricalYChart {
      */
     _facetBarRanges: { start: number; count: number }[] | null = null;
 
+    /**
+     * Paint order of the current build: consecutive aggregates sharing
+     * a glyph type, merged into runs, in `columns` declaration order
+     * (`aggIdx` ascending — later columns paint on top). The frame
+     * draws one pass per run; a homogeneous chart is a single run and
+     * degenerates to the legacy one-pass-per-type path. `aggEnd` is
+     * inclusive.
+     */
+    _glyphRuns: GlyphRun[] = [];
+
+    /**
+     * Per-aggregate contiguous instance ranges in the uploaded bar
+     * buffers, indexed by `aggIdx` — the overlay-mode counterpart of
+     * `_facetBarRanges`, populated by `uploadBarInstances`' aggregate
+     * counting sort. `null` until first upload.
+     */
+    _barAggRanges: { start: number; count: number }[] | null = null;
+
+    /**
+     * Faceted per-(split, aggregate) instance ranges,
+     * `[splitIdx][aggIdx]` — instances are emitted split-major then
+     * aggregate-ordered, so a facet's glyph-run slice is contiguous.
+     * `null` in overlay mode.
+     */
+    _facetBarAggRanges: { start: number; count: number }[][] | null = null;
+
     /**
      * Columnar bar/area record storage. Indexed by bar slot in
      * `[0, _bars.count)`. Replaces the legacy `SeriesChartRecord[]` to
@@ -249,6 +286,20 @@ export class SeriesChart extends CategoricalYChart {
     _expandedLeftDomain: { min: number; max: number } | null = null;
     _expandedRightDomain: { min: number; max: number } | null = null;
 
+    /**
+     * The axis partition (per-aggregate axis side) the expand
+     * accumulators were accumulated under. An accumulator is only
+     * meaningful for the partition that produced it: when an aggregate
+     * moves sides (`columns_config.alt_axis` pin via a config-only
+     * `update()`, or a data-driven `auto_alt_y_axis` flip), the side it
+     * LEFT would otherwise retain its extent forever — the departed
+     * column's range never leaves the primary axis. A signature
+     * mismatch resets BOTH accumulators before the union. Keyed per
+     * AGGREGATE (not per series) so split-group growth on a streaming
+     * update never spuriously resets.
+     */
+    _expandedAxisSig: string | null = null;
+
     /**
      * Numeric category-axis state. Populated only when `group_by` has
      * exactly one level and that level is `date | datetime | integer |
@@ -564,6 +615,13 @@ export class SeriesChart extends CategoricalYChart {
         // `"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") {
+            const axisSig = expandAxisSignature(result);
+            if (this._expandedAxisSig !== axisSig) {
+                this._expandedLeftDomain = null;
+                this._expandedRightDomain = null;
+                this._expandedAxisSig = axisSig;
+            }
+
             this._expandedLeftDomain = expandDomainInPlace(
                 this._expandedLeftDomain,
                 result.leftDomain,
@@ -578,6 +636,7 @@ export class SeriesChart extends CategoricalYChart {
         } else {
             this._expandedLeftDomain = null;
             this._expandedRightDomain = null;
+            this._expandedAxisSig = null;
         }
 
         this._aggregates = result.aggregates;
@@ -639,6 +698,25 @@ export class SeriesChart extends CategoricalYChart {
         this._primaryValueLabel = uniqueAggLabels(result.series, 0);
         this._altValueLabel = uniqueAggLabels(result.series, 1);
 
+        // Paint-order runs: every series of an aggregate shares one
+        // glyph type (`resolveChartType` is per-aggName), so sampling
+        // the aggregate's first series suffices. MUST be computed
+        // before `uploadBarInstances` below — the aggregate counting
+        // sort publishes ranges the run passes draw from.
+        this._glyphRuns.length = 0;
+        {
+            const P = Math.max(1, result.splitPrefixes.length);
+            for (let k = 0; k < result.aggregates.length; k++) {
+                const chartType = result.series[k * P].chartType;
+                const last = this._glyphRuns[this._glyphRuns.length - 1];
+                if (last && last.chartType === chartType) {
+                    last.aggEnd = k;
+                } else {
+                    this._glyphRuns.push({ chartType, aggStart: k, aggEnd: k });
+                }
+            }
+        }
+
         // Pre-build the area-strip lookup index (seriesId * 1e9 + catIdx
         // → bar slot). Legacy code rebuilt this every frame inside
         // `drawAreas`. The index is derived purely from `_bars` and is
@@ -657,6 +735,17 @@ export class SeriesChart extends CategoricalYChart {
         this._paletteCacheKey = null;
         this._catExtentsHidden = null;
         this._lastUploadedColors = null;
+
+        // Hover records index into `_bars` / `_series` and MUST NOT
+        // survive a build that replaces them: bar-column capacity is
+        // reused across builds, so a stale `_hoveredBarIdx` reads a
+        // leftover `seriesId` past the new series set (and a retained
+        // `_hoveredSample` carries one verbatim), crashing the tooltip
+        // pass of the next present when the pointer rests over a glyph
+        // through a host `restore`. The next mousemove re-hit-tests
+        // against the new data.
+        this._hoveredBarIdx = -1;
+        this._hoveredSample = null;
         this._sampleValid = result.sampleValid;
         this._leftDomain = result.leftDomain;
         this._rightDomain = result.rightDomain;
@@ -691,6 +780,7 @@ export class SeriesChart extends CategoricalYChart {
     override resetExpandedDomain(): void {
         this._expandedLeftDomain = null;
         this._expandedRightDomain = null;
+        this._expandedAxisSig = null;
     }
 
     protected destroyInternal(): void {
@@ -709,6 +799,9 @@ export class SeriesChart extends CategoricalYChart {
         this._facetActive = false;
         this._facetGrid = null;
         this._facetBarRanges = null;
+        this._facetBarAggRanges = null;
+        this._barAggRanges = null;
+        this._glyphRuns.length = 0;
         this._bars = emptyBarColumns();
         this._series = [];
         this._barSeries = [];
@@ -724,6 +817,8 @@ export class SeriesChart extends CategoricalYChart {
         this._rowPaths = [];
         this._numCategories = 0;
         this._hiddenSeries.clear();
+        this._hoveredBarIdx = -1;
+        this._hoveredSample = null;
     }
 }
 
@@ -770,6 +865,24 @@ function uniqueAggLabels(series: SeriesInfo[], axis: 0 | 1): string {
     return ordered.join(", ");
 }
 
+/**
+ * Per-aggregate axis-partition signature for the `domain_mode:
+ * "expand"` accumulators. Invariant: every series of an aggregate
+ * shares one axis side (both axis-override loops in the build pipeline
+ * assign by `aggIdx`), so sampling the aggregate's first series
+ * suffices. NUL-joined — aggregate names may contain any printable
+ * separator.
+ */
+function expandAxisSignature(result: SeriesPipelineResult): string {
+    const P = Math.max(1, result.splitPrefixes.length);
+    const parts: string[] = [];
+    for (let k = 0; k < result.aggregates.length; k++) {
+        parts.push(`${result.aggregates[k]}:${result.series[k * P].axis}`);
+    }
+
+    return parts.join("\u0000");
+}
+
 /**
  * Resolve the per-series palette and stamp it onto `_series[i].color`.
  * Cached on `_paletteCache` keyed by reference identity of the theme

package/src/ts/plugin/plugin.ts

@@ -171,6 +171,16 @@ export class HTMLPerspectiveViewerWebGLPluginElement
      */
     private _pluginConfigStore: PluginConfig | null = null;
 
+    /**
+     * Per-column config (`alt_axis`, `chart_type`, formats, …), held on
+     * the element for the same reason as `_pluginConfigStore`: the host
+     * calls `restore()` BEFORE the first draw builds the renderer, so
+     * forwarding only to a live renderer silently drops the initial
+     * `columns_config` — `_buildRenderer` ships it in the `InitMsg`
+     * instead.
+     */
+    private _columnsConfig: Record<string, any> = {};
+
     private get _pluginConfig(): PluginConfig {
         if (!this._pluginConfigStore) {
             this._pluginConfigStore = this._effectiveDefaults();
@@ -396,6 +406,7 @@ export class HTMLPerspectiveViewerWebGLPluginElement
                 zoom_mode: this._pluginConfig.facet_zoom_mode,
             },
             pluginConfig: this._pluginConfig,
+            columnsConfig: this._columnsConfig,
             defaultChartType: this._chartType.default_chart_type,
             renderBlitMode: BLIT_MODE,
         });
@@ -693,8 +704,9 @@ export class HTMLPerspectiveViewerWebGLPluginElement
             ...config,
         };
 
+        this._columnsConfig = columns_config ?? {};
         this._renderer?.setPluginConfig(this._pluginConfig);
-        this._renderer?.setColumnsConfig(columns_config ?? {});
+        this._renderer?.setColumnsConfig(this._columnsConfig);
     }
 
     delete() {

package/src/ts/transport/protocol.ts

@@ -162,6 +162,15 @@ export interface InitMsg {
      * a `setPluginConfig` control msg.
      */
     pluginConfig: PluginConfig;
+
+    /**
+     * Initial per-column config (`alt_axis`, `chart_type`, formats, …).
+     * Seeds the chart impl before the first `loadAndRender` — the host
+     * calls `plugin.restore` before the renderer exists, so without
+     * this the initial `columns_config` never reaches the worker.
+     * Later changes arrive as `setColumnsConfig` control msgs.
+     */
+    columnsConfig?: Record<string, any>;
     defaultChartType?: string;
 
     /**

package/src/ts/transport/renderer-transport.ts

@@ -258,6 +258,7 @@ export class RendererTransport {
         chrome: HTMLCanvasElement;
         facetConfig: FacetConfig;
         pluginConfig: PluginConfig;
+        columnsConfig?: Record<string, any>;
         defaultChartType?: string;
         renderBlitMode: "blit" | "direct";
     }): Promise<void> {
@@ -339,6 +340,7 @@ export class RendererTransport {
             tableName: this._tableName,
             facetConfig: opts.facetConfig,
             pluginConfig: opts.pluginConfig,
+            columnsConfig: opts.columnsConfig,
             defaultChartType: opts.defaultChartType,
             themeVars,
             fontFaces,
@@ -577,6 +579,17 @@ export class RendererTransport {
             return Promise.resolve();
         }
 
+        const dpr = window.devicePixelRatio || 1;
+        const last = this._lastPostedSize;
+        if (
+            last &&
+            Math.abs(last.cssWidth - cssWidth) <= 0.5 &&
+            Math.abs(last.cssHeight - cssHeight) <= 0.5 &&
+            last.dpr === dpr
+        ) {
+            return Promise.resolve();
+        }
+
         this._holdPresent = true;
         return this._postResize(cssWidth, cssHeight).then(
             () => () => this._presentStaged(),

package/src/ts/worker/renderer.worker.ts

@@ -204,6 +204,9 @@ export class WorkerRenderer {
 
         this.chartImpl.setFacetConfig?.(msg.facetConfig);
         this.chartImpl.setPluginConfig?.(msg.pluginConfig);
+        if (msg.columnsConfig) {
+            this.chartImpl.setColumnsConfig?.(msg.columnsConfig);
+        }
 
         if (this.chartImpl.setZoomController) {
             this.zoomController = new ZoomController();