@perspective-dev/viewer-charts 5.1.0 → 5.3.0

package/src/ts/theme/gradient.ts

@@ -10,7 +10,7 @@
 // ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-import { parseCSSColorToVec3 } from "../utils/css";
+import { parseCSSColorToVec3, vec3ToHexColor } from "../utils/css";
 
 /**
  * A single stop on a parsed CSS gradient. `offset` ∈ [0, 1].
@@ -178,6 +178,246 @@ export function parseCssGradient(
     return result;
 }
 
+/**
+ * A color literal — `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb()` or
+ * `rgba()` — as a `[0, 1]` RGB triple, or `null` for anything else.
+ */
+export function parseCssColorStrict(
+    src: string,
+): [number, number, number] | null {
+    const s = src.trim();
+    if (s.startsWith("#")) {
+        const hex = s.slice(1);
+        if (!/^[0-9a-f]+$/i.test(hex)) {
+            return null;
+        }
+
+        if (hex.length === 3 || hex.length === 4) {
+            return [
+                parseInt(hex[0] + hex[0], 16) / 255,
+                parseInt(hex[1] + hex[1], 16) / 255,
+                parseInt(hex[2] + hex[2], 16) / 255,
+            ];
+        }
+
+        if (hex.length === 6 || hex.length === 8) {
+            return [
+                parseInt(hex.slice(0, 2), 16) / 255,
+                parseInt(hex.slice(2, 4), 16) / 255,
+                parseInt(hex.slice(4, 6), 16) / 255,
+            ];
+        }
+
+        return null;
+    }
+
+    const m = s.match(/^rgba?\(([^)]*)\)$/i);
+    if (!m) {
+        return null;
+    }
+
+    const tokens = m[1]
+        .split("/")[0]
+        .split(/[\s,]+/)
+        .filter((x) => x.length > 0);
+    if (tokens.length < 3 || tokens.length > 4) {
+        return null;
+    }
+
+    const channel = (token: string): number | null => {
+        const pct = token.endsWith("%");
+        const n = parseFloat(pct ? token.slice(0, -1) : token);
+        if (!isFinite(n)) {
+            return null;
+        }
+
+        const v = pct ? (n / 100) * 255 : n;
+        return Math.max(0, Math.min(255, Math.round(v))) / 255;
+    };
+
+    const r = channel(tokens[0]);
+    const g = channel(tokens[1]);
+    const b = channel(tokens[2]);
+    return r === null || g === null || b === null ? null : [r, g, b];
+}
+
+/**
+ * The shared `linear-gradient(...)` tokenizer of the viewer's CSS-valued
+ * config grammar.
+ */
+export function tokenizeLinearGradient(
+    src: string,
+): Array<[[number, number, number], number | null]> | null {
+    const m = src.trim().match(/^linear-gradient\s*\((.*)\)$/is);
+    if (!m) {
+        return null;
+    }
+
+    const body = m[1];
+    const parts: string[] = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < body.length; i++) {
+        const ch = body[i];
+        if (ch === "(") {
+            depth++;
+        } else if (ch === ")") {
+            depth--;
+        } else if (ch === "," && depth === 0) {
+            parts.push(body.substring(start, i));
+            start = i + 1;
+        }
+    }
+
+    parts.push(body.substring(start));
+    const out: Array<[[number, number, number], number | null]> = [];
+    for (let i = 0; i < parts.length; i++) {
+        const piece = parts[i].trim();
+        if (!piece) {
+            return null;
+        }
+
+        const lower = piece.toLowerCase();
+        if (
+            i === 0 &&
+            (lower.startsWith("to ") ||
+                /^[-\d.]+(deg|rad|grad|turn)$/.test(lower))
+        ) {
+            continue;
+        }
+
+        const posMatch = piece.match(/\s([^\s)]+)$/);
+        let color = piece;
+        let offset: number | null = null;
+        if (posMatch) {
+            const tail = posMatch[1];
+            if (tail.endsWith("%")) {
+                const n = parseFloat(tail.slice(0, -1));
+                if (!isFinite(n)) {
+                    return null;
+                }
+
+                color = piece.substring(0, posMatch.index).trim();
+                offset = n / 100;
+            } else if (/^[-\d.]/.test(tail)) {
+                return null;
+            }
+        }
+
+        const rgb = parseCssColorStrict(color);
+        if (!rgb) {
+            return null;
+        }
+
+        out.push([rgb, offset]);
+    }
+
+    return out;
+}
+
+/**
+ * Strict gradient reader: a `linear-gradient(...)` with ≥ 2 stops,
+ * positions optional, offsets clamped to `[0, 1]` and sorted, or `null`
+ * on malformed input.
+ */
+export function parseCssGradientStrict(src: string): GradientStop[] | null {
+    const entries = tokenizeLinearGradient(src);
+    if (!entries || entries.length < 2) {
+        return null;
+    }
+
+    const offsets: Array<number | null> = entries.map(([, p]) => p);
+    const last = offsets.length - 1;
+    if (offsets[0] === null) {
+        offsets[0] = 0;
+    }
+
+    if (offsets[last] === null) {
+        offsets[last] = 1;
+    }
+
+    for (let i = 1; i < last; i++) {
+        if (offsets[i] !== null) {
+            continue;
+        }
+
+        let j = i + 1;
+        while (offsets[j] === null) {
+            j++;
+        }
+
+        const before = offsets[i - 1]!;
+        const after = offsets[j]!;
+        const span = j - (i - 1);
+        for (let k = i; k < j; k++) {
+            offsets[k] = before + ((k - (i - 1)) / span) * (after - before);
+        }
+
+        i = j - 1;
+    }
+
+    const stops: GradientStop[] = entries.map(([rgb], i) => ({
+        offset: Math.max(0, Math.min(1, offsets[i]!)),
+        color: [rgb[0], rgb[1], rgb[2], 1],
+    }));
+
+    stops.sort((a, b) => a.offset - b.offset);
+    return stops;
+}
+
+/**
+ * Strict palette reader: a `linear-gradient(...)` of ≥ 1 colors with no
+ * positions, or `null` on malformed input.
+ */
+export function parseCssColorList(
+    src: string,
+): Array<[number, number, number]> | null {
+    const entries = tokenizeLinearGradient(src);
+    if (!entries || entries.length === 0) {
+        return null;
+    }
+
+    const out: Array<[number, number, number]> = [];
+    for (const [rgb, offset] of entries) {
+        if (offset !== null) {
+            return null;
+        }
+
+        out.push(rgb);
+    }
+
+    return out;
+}
+
+function formatPercent(offset: number): string {
+    const rounded = Math.round(Math.max(0, Math.min(1, offset)) * 1000) / 10;
+    return `${rounded}%`;
+}
+
+/**
+ * The viewer's canonical gradient string for `stops`: `linear-gradient(to
+ * right, #rrggbb P%, …)`, sorted, positions at 0.1% resolution.
+ */
+export function stopsToCss(stops: GradientStop[]): string {
+    const body = [...stops]
+        .sort((a, b) => a.offset - b.offset)
+        .map(
+            (stop) =>
+                `${vec3ToHexColor([stop.color[0], stop.color[1], stop.color[2]])} ${formatPercent(stop.offset)}`,
+        )
+        .join(", ");
+
+    return `linear-gradient(to right, ${body})`;
+}
+
+/**
+ * The viewer's canonical palette string for `colors`: the same frame
+ * with bare `#rrggbb` entries and no positions.
+ */
+export function colorsToCss(colors: Array<[number, number, number]>): string {
+    return `linear-gradient(to right, ${colors.map(vec3ToHexColor).join(", ")})`;
+}
+
 /**
  * Piecewise-linear color sample at `t ∈ [0, 1]`. Returns RGBA in [0, 1].
  * Clamps `t` to the gradient's first/last stop outside `[0, 1]`.

package/src/ts/theme/overrides.ts

@@ -0,0 +1,76 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+import {
+    parseCssColorList,
+    parseCssGradientStrict,
+    type GradientStop,
+} from "./gradient";
+import type { Theme } from "./theme";
+import type { Vec3 } from "./palette";
+
+/**
+ * Per-column color-scale overrides from the viewer's `columns_config`,
+ * patched into the resolved `Theme`'s `seriesPalette` / `gradientStops`
+ * fields.
+ */
+export function applyColumnColorOverrides(
+    theme: Theme,
+    columnsConfig: Record<string, any> | undefined,
+    colorColumn: string | null,
+): Theme {
+    if (!colorColumn) {
+        return theme;
+    }
+
+    const cfg = columnsConfig?.[colorColumn];
+    if (!cfg) {
+        return theme;
+    }
+
+    let out = theme;
+    const gradient = parseGradientOverride(cfg.gradient);
+    if (gradient) {
+        out = { ...out, gradientStops: gradient };
+    }
+
+    const palette = parsePaletteOverride(cfg.palette);
+    if (palette) {
+        out = { ...out, seriesPalette: palette };
+    }
+
+    return out;
+}
+
+/**
+ * Parse a stored `palette` value into the `seriesPalette` shape, or
+ * `null` on anything malformed.
+ */
+export function parsePaletteOverride(raw: unknown): Vec3[] | null {
+    if (typeof raw !== "string") {
+        return null;
+    }
+
+    return parseCssColorList(raw);
+}
+
+/**
+ * Parse a stored `gradient` value into sorted `GradientStop[]`, or
+ * `null` on malformed input or fewer than 2 stops.
+ */
+export function parseGradientOverride(raw: unknown): GradientStop[] | null {
+    if (typeof raw !== "string") {
+        return null;
+    }
+
+    return parseCssGradientStrict(raw);
+}

package/src/ts/transport/protocol.ts

@@ -100,8 +100,20 @@ export interface InitMsg {
      * `dpr` and there is no host-side GL drawing buffer.
      */
     glCanvas?: OffscreenCanvas;
-    gridlinesCanvas: OffscreenCanvas;
-    chromeCanvas: OffscreenCanvas;
+
+    /**
+     * The gridlines (bottom) and chrome/axes (top) 2D layers.
+     * Transferred via `transferControlToOffscreen` on the host, present
+     * iff `renderMode === "direct"` — their pixels reach the screen
+     * through the compositor. In blit mode the renderer allocates
+     * worker-local surfaces instead and composites both layers into the
+     * shipped `FrameBitmapMsg`, so every layer of the frame rides the
+     * host's staged-present hold (a transferred canvas presents on the
+     * compositor's own schedule, unsynchronized with the host's layout
+     * commits — the one-frame axes warp on anticipated resizes).
+     */
+    gridlinesCanvas?: OffscreenCanvas;
+    chromeCanvas?: OffscreenCanvas;
 
     /**
      * `MessagePort` to the host's `ProxySession`. Worker mode only —

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

@@ -299,15 +299,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);
@@ -365,14 +374,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);
             }

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/renderer.worker.ts

@@ -106,6 +106,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;
 
@@ -182,20 +196,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) {
@@ -588,6 +613,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 +755,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();
     }