@perspective-dev/viewer-charts 5.2.0 → 5.3.1

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

@@ -14,6 +14,7 @@ import type { Client, View, ViewConfig } from "@perspective-dev/client";
 import type { FacetConfig, PluginConfig } from "../charts/chart";
 import type {
     ControlMsg,
+    ErrorMsg,
     InitMsg,
     InteractionEvent,
     LoadAndRenderMsg,
@@ -26,6 +27,7 @@ import {
 } from "../event-detail";
 import { snapshotThemeVars } from "../theme/theme-snapshot";
 import { snapshotFontFaces } from "../utils/font-snapshot";
+import { TILE_SOURCES } from "../map/tile-source";
 import { DomHostSink } from "../interaction/host-sink-dom";
 import { RUNTIME_MODE } from "../config";
 
@@ -72,6 +74,24 @@ async function getSharedWorker(): Promise<Worker> {
             const env = e.data as WorkerEnvelope;
             HOST_LISTENERS.get(env.sessionId)?.(env.msg);
         });
+
+        let poisoned = false;
+        w.addEventListener("error", (event: ErrorEvent) => {
+            if (poisoned) {
+                return;
+            }
+
+            poisoned = true;
+            SHARED_WORKER = null;
+            const detail = event.message || `failed to load ${url}`;
+            const message = `perspective-viewer-charts renderer worker error: ${detail}`;
+            console.error(message, event.error ?? "");
+            const errorMsg: ErrorMsg = { kind: "error", message };
+            for (const listener of HOST_LISTENERS.values()) {
+                listener(errorMsg);
+            }
+        });
+
         return w;
     })();
 
@@ -156,6 +176,10 @@ export class RendererTransport {
     private _pendingCounter = 0;
     private _onZoomChanged: ((isDefault: boolean) => void) | null = null;
 
+    private _onPluginConfigDelta:
+        | ((fields: Record<string, string | number | boolean>) => void)
+        | null = null;
+
     /**
      * Cached zoom-default flag pushed by the renderer after each zoom
      * mutation. Surfaced sync via `allZoomsDefault()`; updates between
@@ -235,6 +259,9 @@ export class RendererTransport {
         maxCells: number;
         precompileShaders?: boolean;
         onZoomChanged?: (isDefault: boolean) => void;
+        onPluginConfigDelta?: (
+            fields: Record<string, string | number | boolean>,
+        ) => void;
     }) {
         this._client = opts.client;
         this._view = opts.view;
@@ -246,6 +273,7 @@ export class RendererTransport {
         this._maxCells = opts.maxCells;
         this._precompileShaders = opts.precompileShaders ?? false;
         this._onZoomChanged = opts.onZoomChanged ?? null;
+        this._onPluginConfigDelta = opts.onPluginConfigDelta ?? null;
         this._ready = new Promise((resolve, reject) => {
             this._resolveReady = resolve;
             this._rejectReady = reject;
@@ -299,15 +327,24 @@ export class RendererTransport {
         // `ImageBitmap`. Direct mode transfers the visible canvas's
         // drawing buffer to the renderer so GL paints straight to
         // screen.
+        // Blit mode also keeps the gridlines/chrome layers worker-side:
+        // a transferred canvas presents on the compositor's schedule,
+        // unsynchronized with the host's layout commits, so it can't
+        // participate in the staged-present hold. The renderer
+        // composites both layers into the shipped frame instead, and
+        // the host-side placeholder canvases stay untouched
+        // (transparent). Direct mode transfers all three surfaces.
         let glOC: OffscreenCanvas | undefined;
+        let gridlinesOC: OffscreenCanvas | undefined;
+        let chromeOC: OffscreenCanvas | undefined;
         if (opts.renderBlitMode === "blit") {
             this._displayCtx = opts.gl.getContext("2d");
         } else {
             glOC = opts.gl.transferControlToOffscreen();
+            gridlinesOC = opts.gridlines.transferControlToOffscreen();
+            chromeOC = opts.chrome.transferControlToOffscreen();
         }
 
-        const gridlinesOC = opts.gridlines.transferControlToOffscreen();
-        const chromeOC = opts.chrome.transferControlToOffscreen();
         const rect = opts.gl.getBoundingClientRect();
         const dpr = window.devicePixelRatio || 1;
         const themeVars = snapshotThemeVars(opts.gl);
@@ -342,6 +379,9 @@ export class RendererTransport {
             pluginConfig: opts.pluginConfig,
             columnsConfig: opts.columnsConfig,
             defaultChartType: opts.defaultChartType,
+            tileSource: TILE_SOURCES.specFor(
+                opts.pluginConfig.map_tile_provider,
+            ),
             themeVars,
             fontFaces,
             cssWidth: rect.width,
@@ -365,14 +405,19 @@ export class RendererTransport {
             // Worker mode: the bootstrap is triggered by posting the
             // init message into the worker's scope (which the
             // `if (IS_WORKER_SCOPE)` block in `renderer.worker.ts`
-            // listens for). `glOC` is omitted in blit mode (the
-            // renderer allocates its own offscreen) — only include the
-            // GL canvas in the transfer list when present.
-            const transfer: Transferable[] = [
-                gridlinesOC,
-                chromeOC,
-                this._proxyChannel!.port2,
-            ];
+            // listens for). All three canvases are omitted in blit mode
+            // (the renderer allocates its own offscreens and ships
+            // composited frames) — only include the transferred
+            // surfaces present on this mode's init message.
+            const transfer: Transferable[] = [this._proxyChannel!.port2];
+            if (chromeOC) {
+                transfer.unshift(chromeOC);
+            }
+
+            if (gridlinesOC) {
+                transfer.unshift(gridlinesOC);
+            }
+
             if (glOC) {
                 transfer.unshift(glOC);
             }
@@ -474,7 +519,11 @@ export class RendererTransport {
     }
 
     setPluginConfig(cfg: PluginConfig): void {
-        this._post({ kind: "setPluginConfig", cfg });
+        this._post({
+            kind: "setPluginConfig",
+            cfg,
+            tileSource: TILE_SOURCES.specFor(cfg.map_tile_provider),
+        });
     }
 
     setBufferMaxCapacity(n: number): void {
@@ -793,7 +842,12 @@ export class RendererTransport {
                 this._resolvePending(msg.requestId, "saveZoom", msg.state);
                 break;
             case "pinTooltip":
-                this._ensureHostSink()?.pin(msg.lines, msg.pos, msg.bounds);
+                this._ensureHostSink()?.pin(
+                    msg.grid,
+                    msg.pos,
+                    msg.bounds,
+                    msg.style,
+                );
                 break;
             case "dismissTooltip":
                 this._hostSink?.dismiss();
@@ -801,6 +855,9 @@ export class RendererTransport {
             case "setCursor":
                 this._ensureHostSink()?.setCursor(msg.cursor);
                 break;
+            case "pluginConfigDelta":
+                this._onPluginConfigDelta?.(msg.fields);
+                break;
             case "userClick":
                 this._dispatchOnViewer(
                     new CustomEvent<PerspectiveClickDetail>(
@@ -864,13 +921,35 @@ export class RendererTransport {
                 this._rejectReady(new Error(msg.message));
                 break;
             case "loadAndRenderAck":
-                this._resolvePending(msg.msgId, "loadAndRender", undefined);
+                if (msg.error !== undefined) {
+                    this._rejectPending(
+                        msg.msgId,
+                        "loadAndRender",
+                        new Error(msg.error),
+                    );
+                } else {
+                    this._resolvePending(msg.msgId, "loadAndRender", undefined);
+                }
+
                 break;
             case "resizeAck":
                 this._resolvePending(msg.msgId, "resize", undefined);
                 break;
             case "snapshotPngReply":
-                this._resolvePending(msg.requestId, "snapshotPng", msg.blob);
+                if (msg.error !== undefined) {
+                    this._rejectPending(
+                        msg.requestId,
+                        "snapshotPng",
+                        new Error(msg.error),
+                    );
+                } else {
+                    this._resolvePending(
+                        msg.requestId,
+                        "snapshotPng",
+                        msg.blob,
+                    );
+                }
+
                 break;
         }
     }
@@ -896,6 +975,20 @@ export class RendererTransport {
         entry.resolve(value);
     }
 
+    private _rejectPending(
+        id: number,
+        kind: PendingRenderType,
+        error: Error,
+    ): void {
+        const entry = this._pending.get(id);
+        if (!entry || entry.kind !== kind) {
+            return;
+        }
+
+        this._pending.delete(id);
+        entry.reject(error);
+    }
+
     /**
      * Blit-mode handler: draw a renderer-emitted frame into the
      * visible 2D-context display canvas, then close the bitmap so its

package/src/ts/utils/css.ts

@@ -34,3 +34,15 @@ export function parseCSSColorToVec3(
 
     return [0.5, 0.5, 0.5];
 }
+
+/**
+ * Format a `[0, 1]`-range RGB triple as a plain `#rrggbb` string.
+ */
+export function vec3ToHexColor(c: [number, number, number]): string {
+    const channel = (x: number) =>
+        Math.round(Math.max(0, Math.min(1, x)) * 255)
+            .toString(16)
+            .padStart(2, "0");
+
+    return `#${channel(c[0])}${channel(c[1])}${channel(c[2])}`;
+}

package/src/ts/worker/dispatch.ts

@@ -28,7 +28,7 @@ export function dispatch(r: WorkerRenderer, msg: ControlMsg): void {
             r.chartImpl.setColumnsConfig?.(msg.cfg);
             break;
         case "setPluginConfig":
-            r.chartImpl.setPluginConfig?.(msg.cfg);
+            r.setPluginConfig(msg.cfg, msg.tileSource);
             r.redraw();
             break;
         case "setBufferMaxCapacity":
@@ -93,7 +93,11 @@ export function dispatch(r: WorkerRenderer, msg: ControlMsg): void {
                     r.post({ kind: "snapshotPngReply", requestId, blob });
                 })
                 .catch((err) => {
-                    r.post({ kind: "error", message: String(err) });
+                    r.post({
+                        kind: "snapshotPngReply",
+                        requestId,
+                        error: String(err),
+                    });
                 });
             break;
         }

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

@@ -18,7 +18,7 @@ import type * as wasm_module_type from "@perspective-dev/viewer/dist/wasm/perspe
 import { WebGLContextManager } from "../webgl/context-manager";
 import { ContextPool } from "../webgl/context-pool";
 import { RENDER_CONTEXT_POOL_SIZE } from "../config";
-import { ChartImplementation } from "../charts/chart";
+import { ChartImplementation, type PluginConfig } from "../charts/chart";
 import { ZoomController } from "../interaction/zoom-controller";
 import {
     applyPan,
@@ -36,6 +36,7 @@ import type {
     WorkerMsg,
 } from "../transport/protocol";
 import { viewToColumnDataMap } from "../data/view-reader";
+import { TILE_SOURCES, type TileSourceSpec } from "../map/tile-source";
 import { loadFontDeduped } from "./font-loader";
 import { dispatch } from "./dispatch";
 import { installSessionHost } from "./session-host";
@@ -106,6 +107,20 @@ export class WorkerRenderer {
     cssWidth: number;
     cssHeight: number;
     dpr: number;
+
+    /**
+     * Blit-mode compose surface: gridlines + GL frame + chrome are
+     * drawn here each `endFrame` and shipped as ONE `ImageBitmap`, so
+     * every layer rides the host's staged-present hold (see
+     * `InitMsg.gridlinesCanvas`). `null` in direct mode.
+     */
+    private _composeCanvas: OffscreenCanvas | null = null;
+    private _composeCtx: OffscreenCanvasRenderingContext2D | null = null;
+
+    private _lastPlot: ImageBitmap | null = null;
+
+    private _frameSerial = 0;
+    private _overlayPresentQueued = false;
     client: Client;
     view: View;
 
@@ -152,6 +167,13 @@ export class WorkerRenderer {
 
         this.chartImpl = new ImplClass();
 
+        // Registry write must precede the chart impl's first
+        // `setPluginConfig` — `pluginConfig.map_tile_provider` may
+        // name this runtime-registered source.
+        if (msg.tileSource) {
+            TILE_SOURCES.register(msg.tileSource);
+        }
+
         // Three surfaces, by mode:
         //  - direct: the host's transferred `.webgl-canvas` (1:1 with a
         //    context, permanently).
@@ -182,20 +204,31 @@ export class WorkerRenderer {
             });
         }
 
+        // Blit mode: the 2D layers are worker-local (the host omits
+        // them from the init message) and every shipped frame is the
+        // full composite — gridlines under the GL plot under chrome,
+        // the same stacking as the host's canvas elements and the
+        // `snapshotPng` composite. Direct mode draws into the host's
+        // transferred surfaces and ships nothing.
+        const w = Math.max(1, Math.round(msg.cssWidth * msg.dpr));
+        const h = Math.max(1, Math.round(msg.cssHeight * msg.dpr));
+        this.gridlines = msg.gridlinesCanvas ?? new OffscreenCanvas(w, h);
+        this.chrome = msg.chromeCanvas ?? new OffscreenCanvas(w, h);
         if (msg.renderMode === "blit") {
             this.glManager.setFrameCallback((bitmap) => {
-                this.post({ kind: "frameBitmap", bitmap }, [bitmap]);
+                this._frameSerial += 1;
+                const frame = this._composeFrame(bitmap);
+                this.post({ kind: "frameBitmap", bitmap: frame }, [frame]);
             });
+            this.chartImpl.setOverlayPresenter?.(() => this._presentOverlay());
         }
 
-        this.gridlines = msg.gridlinesCanvas;
-        this.chrome = msg.chromeCanvas;
         this.cssWidth = msg.cssWidth;
         this.cssHeight = msg.cssHeight;
         this.dpr = msg.dpr;
 
-        this.chartImpl.setGridlineCanvas?.(msg.gridlinesCanvas);
-        this.chartImpl.setChromeCanvas?.(msg.chromeCanvas);
+        this.chartImpl.setGridlineCanvas?.(this.gridlines);
+        this.chartImpl.setChromeCanvas?.(this.chrome);
         this.chartImpl.setTheme?.(msg.themeVars);
 
         if (msg.defaultChartType) {
@@ -228,6 +261,20 @@ export class WorkerRenderer {
         this.chartImpl.setView?.(this.view);
     }
 
+    /**
+     * Registry write precedes the config apply — `cfg` may name the
+     * spec riding alongside it (see `SetPluginConfigMsg.tileSource`),
+     * and a replaced template must be registered first so the map
+     * chart's rebind sees the new content-derived cache id.
+     */
+    setPluginConfig(cfg: PluginConfig, tileSource?: TileSourceSpec): void {
+        if (tileSource) {
+            TILE_SOURCES.register(tileSource);
+        }
+
+        this.chartImpl.setPluginConfig?.(cfg);
+    }
+
     /**
      * Full data-fetch + render pipeline. Owns every `Client`/`Table`/
      * `View` await on the render path:
@@ -258,6 +305,7 @@ export class WorkerRenderer {
      */
     async loadAndRender(msg: LoadAndRenderMsg): Promise<void> {
         const myGen = ++this._renderGen;
+        let error: string | undefined;
         try {
             const [numRows, schema, exprSchema, tableSchema] =
                 await Promise.all([
@@ -327,9 +375,10 @@ export class WorkerRenderer {
         } catch (err) {
             if ((err + "").indexOf("View not found") === -1) {
                 console.error("loadAndRender failed", err);
+                error = String(err);
             }
         } finally {
-            this.post({ kind: "loadAndRenderAck", msgId: msg.msgId });
+            this.post({ kind: "loadAndRenderAck", msgId: msg.msgId, error });
         }
     }
 
@@ -498,7 +547,59 @@ export class WorkerRenderer {
         return { controller: this.zoomController, layout };
     }
 
+    /**
+     * Legend-first interaction routing. The chart's `LegendController`
+     * sees every forwarded event BEFORE the zoom / tooltip paths, so
+     * legend gestures (scroll, width drag, floating move / resize)
+     * structurally preempt plot pan / zoom / hover — a wheel over the
+     * legend can never zoom the plot under it, and a floating-panel
+     * drag can never start a pan.
+     */
+    private _legendInteraction(event: InteractionEvent): boolean {
+        const chart = this.chartImpl as any;
+        const legend = chart?._legend;
+        const cfg = chart?._pluginConfig;
+        if (!legend || !cfg) {
+            return false;
+        }
+
+        return legend.handleEvent(event, {
+            cfg,
+            cssWidth: this.cssWidth,
+            cssHeight: this.cssHeight,
+            legendRects: chart._legendRects ?? [],
+            repaint: (relayout: boolean) => {
+                if (!relayout && typeof chart.repaintChrome === "function") {
+                    chart.repaintChrome();
+                } else {
+                    this.chartImpl.requestRender(this.glManager);
+                }
+            },
+            postDelta: (fields: Record<string, string | number | boolean>) =>
+                this.post({ kind: "pluginConfigDelta", fields }),
+            setCursor: (cursor: string) => chart._hostSink?.setCursor?.(cursor),
+            dispatchLeave: () => this._tooltip()?.dispatchLeave(),
+        });
+    }
+
     onInteraction(event: InteractionEvent): void {
+        try {
+            this._routeInteraction(event);
+        } catch (err) {
+            this._dragTarget = null;
+            (this.chartImpl as any)?._legend?.cancelGesture?.();
+            console.error("interaction dispatch failed", err);
+        }
+    }
+
+    private _routeInteraction(event: InteractionEvent): void {
+        const plotDragging =
+            this._dragTarget !== null &&
+            (event.type === "pointermove" || event.type === "pointerup");
+        if (!plotDragging && this._legendInteraction(event)) {
+            return;
+        }
+
         switch (event.type) {
             case "wheel": {
                 const target = this._resolveTarget(event.mx, event.my);
@@ -588,6 +689,87 @@ export class WorkerRenderer {
         return tt ?? null;
     }
 
+    /**
+     * Blit-mode frame composite: draw the gridlines (bottom), the GL
+     * plot bitmap (middle) and the chrome/axes (top) into the compose
+     * surface and transfer the result — the single `ImageBitmap` the
+     * host blits, and the unit the staged-present hold stages. Runs in
+     * `endFrame`, which the scheduler orders after `render2D`'s 2D
+     * flush, so both layers hold this frame's content.
+     *
+     * A layer whose buffer differs from the plot's dimensions is
+     * skipped rather than scaled: its content is a stale-sized frame
+     * mid-resize (the 2D draws re-size their canvas to `css × dpr` on
+     * the next flush), and scaling it would re-introduce exactly the
+     * warp this composite exists to prevent.
+     */
+    private _composeFrame(plot: ImageBitmap): ImageBitmap {
+        const w = plot.width;
+        const h = plot.height;
+        if (!this._composeCanvas) {
+            this._composeCanvas = new OffscreenCanvas(w, h);
+            this._composeCtx = this._composeCanvas.getContext("2d");
+        }
+
+        const canvas = this._composeCanvas;
+        const ctx = this._composeCtx;
+        if (!ctx) {
+            return plot;
+        }
+
+        if (canvas.width !== w || canvas.height !== h) {
+            canvas.width = w;
+            canvas.height = h;
+        } else {
+            ctx.clearRect(0, 0, w, h);
+        }
+
+        if (this.gridlines.width === w && this.gridlines.height === h) {
+            ctx.drawImage(this.gridlines, 0, 0);
+        }
+
+        ctx.drawImage(plot, 0, 0);
+        if (this._lastPlot !== plot) {
+            this._lastPlot?.close();
+            this._lastPlot = plot;
+        }
+
+        if (this.chrome.width === w && this.chrome.height === h) {
+            ctx.drawImage(this.chrome, 0, 0);
+        }
+
+        return canvas.transferToImageBitmap();
+    }
+
+    private _presentOverlay(): void {
+        if (this._overlayPresentQueued) {
+            return;
+        }
+
+        this._overlayPresentQueued = true;
+        const mark = this._frameSerial;
+        queueMicrotask(() => {
+            this._overlayPresentQueued = false;
+            const plot = this._lastPlot;
+            if (this._frameSerial !== mark || !plot) {
+                return;
+            }
+
+            const w = Math.max(1, Math.round(this.cssWidth * this.dpr));
+            const h = Math.max(1, Math.round(this.cssHeight * this.dpr));
+            if (plot.width !== w || plot.height !== h) {
+                return;
+            }
+
+            const frame = this._composeFrame(plot);
+            if (frame === plot) {
+                return;
+            }
+
+            this.post({ kind: "frameBitmap", bitmap: frame }, [frame]);
+        });
+    }
+
     /**
      * Composite the three layers into a single PNG `Blob`.
      */
@@ -649,6 +831,8 @@ export class WorkerRenderer {
         // next-RAF `drain()` can't paint/present against a dead
         // context (the "scheduler: present failed" path).
         unregister(this.glManager);
+        this._lastPlot?.close();
+        this._lastPlot = null;
         this.chartImpl.destroy();
         this.glManager.destroy();
     }