@perspective-dev/viewer-charts 4.3.0

package/src/ts/webgl/plot-frame.ts

@@ -0,0 +1,91 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 type { PlotLayout } from "../layout/plot-layout";
+
+type GL = WebGL2RenderingContext | WebGLRenderingContext;
+
+/**
+ * Return CSS-pixel dimensions of the GL canvas.
+ */
+export function cssSize(
+    gl: GL,
+    dpr: number,
+): { cssWidth: number; cssHeight: number } {
+    return {
+        cssWidth: gl.canvas.width / dpr,
+        cssHeight: gl.canvas.height / dpr,
+    };
+}
+
+/**
+ * Clear the framebuffer + enable alpha blending. Call once per frame,
+ * before any per-plot-rect {@link withScissor} invocations. Faceted
+ * renderers call this once and then loop {@link withScissor} per cell
+ * so the inter-facet clears don't wipe each other's pixels.
+ */
+export function clearAndSetupFrame(gl: GL): void {
+    gl.clearColor(0, 0, 0, 0);
+    gl.clear(gl.COLOR_BUFFER_BIT);
+    gl.enable(gl.BLEND);
+    gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+}
+
+/**
+ * Scissor-constrain `draw` to `layout.plotRect`. Caller handles
+ * projection / uniforms / VBO bindings inside `draw`; this helper only
+ * manages the scissor enable/disable bracket.
+ *
+ * Unlike {@link renderInPlotFrame}, this does *not* clear the
+ * framebuffer — so it's safe to call repeatedly per frame (one per
+ * facet). Pair with {@link clearAndSetupFrame} at the start of each
+ * frame.
+ */
+export function withScissor(
+    gl: GL,
+    layout: PlotLayout,
+    dpr: number,
+    draw: () => void,
+): void {
+    gl.enable(gl.SCISSOR_TEST);
+    gl.scissor(
+        Math.round(layout.margins.left * dpr),
+        Math.round(layout.margins.bottom * dpr),
+        Math.round(layout.plotRect.width * dpr),
+        Math.round(layout.plotRect.height * dpr),
+    );
+    try {
+        draw();
+    } finally {
+        gl.disable(gl.SCISSOR_TEST);
+    }
+}
+
+/**
+ * One-shot convenience: clear + setup blend + scissor + draw. Used by
+ * single-plot callers (bar / heatmap / candlestick / scatter-without-
+ * splits) that only draw into one plot rect per frame.
+ *
+ * Faceted callers must use {@link clearAndSetupFrame} +
+ * {@link withScissor} instead; calling this helper in a per-facet loop
+ * would clear the framebuffer on each invocation and wipe out every
+ * previously-drawn facet.
+ */
+export function renderInPlotFrame(
+    gl: GL,
+    layout: PlotLayout,
+    dpr: number,
+    draw: () => void,
+): void {
+    clearAndSetupFrame(gl);
+    withScissor(gl, layout, dpr, draw);
+}

package/src/ts/webgl/program-cache.ts

@@ -0,0 +1,46 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 type { WebGLContextManager } from "./context-manager";
+
+/**
+ * Compile (or fetch from the shader registry) a program and resolve a
+ * flat record of uniform + attribute locations keyed by name. Uniforms
+ * resolve to `WebGLUniformLocation | null`; attribs resolve to `number`.
+ *
+ * Each glyph drawer used to repeat ~10 lines of `gl.getUniformLocation`
+ * / `gl.getAttribLocation` calls — replacing those with one
+ * `compileProgram(...)` call shrinks the worker bundle by ~80 bytes per
+ * site (uniform/attrib name strings still ship — WebGL needs them
+ * verbatim — but the per-call wrapper goes away).
+ */
+export function compileProgram<C>(
+    glManager: WebGLContextManager,
+    key: string,
+    vert: string,
+    frag: string,
+    uniforms: readonly string[],
+    attrs: readonly string[],
+): C {
+    const program = glManager.shaders.getOrCreate(key, vert, frag);
+    const gl = glManager.gl;
+    const out: any = { program };
+    for (const n of uniforms) {
+        out[n] = gl.getUniformLocation(program, n);
+    }
+
+    for (const n of attrs) {
+        out[n] = gl.getAttribLocation(program, n);
+    }
+
+    return out as C;
+}

package/src/ts/webgl/shader-manifest.ts

@@ -0,0 +1,148 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 barVert from "../shaders/bar.vert.glsl";
+import barFrag from "../shaders/bar.frag.glsl";
+import lineVert from "../shaders/line.vert.glsl";
+import lineFrag from "../shaders/line.frag.glsl";
+import scatterVert from "../shaders/scatter.vert.glsl";
+import scatterFrag from "../shaders/scatter.frag.glsl";
+import areaVert from "../shaders/area.vert.glsl";
+import areaFrag from "../shaders/area.frag.glsl";
+import lineUniformVert from "../shaders/line-uniform.vert.glsl";
+import lineUniformFrag from "../shaders/line-uniform.frag.glsl";
+import yScatterVert from "../shaders/y-scatter.vert.glsl";
+import yScatterFrag from "../shaders/y-scatter.frag.glsl";
+import candlestickBodyVert from "../shaders/candlestick-body.vert.glsl";
+import candlestickBodyFrag from "../shaders/candlestick-body.frag.glsl";
+import heatmapVert from "../shaders/heatmap.vert.glsl";
+import heatmapFrag from "../shaders/heatmap.frag.glsl";
+import sunburstArcVert from "../shaders/sunburst-arc.vert.glsl";
+import sunburstArcFrag from "../shaders/sunburst-arc.frag.glsl";
+import treemapVert from "../shaders/treemap.vert.glsl";
+import treemapFrag from "../shaders/treemap.frag.glsl";
+import densitySplatVert from "../shaders/density-splat.vert.glsl";
+import densitySplatFrag from "../shaders/density-splat.frag.glsl";
+import densityExtremeFrag from "../shaders/density-extreme.frag.glsl";
+import densityMrtVert from "../shaders/density-mrt.vert.glsl";
+import densityMrtFrag from "../shaders/density-mrt.frag.glsl";
+import densityResolveVert from "../shaders/density-resolve.vert.glsl";
+import densityResolveFrag from "../shaders/density-resolve.frag.glsl";
+import tileVert from "../shaders/tile.vert.glsl";
+import tileFrag from "../shaders/tile.frag.glsl";
+
+/**
+ * One shader program in the build's static manifest. The `name` is the
+ * cache key consumed by `ShaderRegistry.getOrCreate(name, ...)` —
+ * call sites must pass the same name (and the same vert/frag source)
+ * for the cache to hit. The single source of truth for both fields is
+ * this file; glyph code re-imports from here so the manifest and the
+ * call sites can never drift.
+ */
+export interface ShaderSpec {
+    name: string;
+    vert: string;
+    frag: string;
+}
+
+/**
+ * Every WebGL program the build ships, keyed by cache name. Used by
+ * `ShaderRegistry.precompile(SHADER_MANIFEST)` to compile + link all
+ * programs eagerly during renderer construction so the first-frame
+ * path doesn't pay the compile cost inline.
+ *
+ * Names mirror the existing `getOrCreate` keys at each call site —
+ * the lazy path stays valid; precompile just primes the cache early.
+ */
+export const SHADER_MANIFEST: readonly ShaderSpec[] = [
+    { name: "bar", vert: barVert, frag: barFrag },
+    { name: "line", vert: lineVert, frag: lineFrag },
+    { name: "scatter", vert: scatterVert, frag: scatterFrag },
+    { name: "bar-area", vert: areaVert, frag: areaFrag },
+    { name: "bar-scatter", vert: yScatterVert, frag: yScatterFrag },
+
+    // Shared by series-line glyph (`bar-line` consolidated here),
+    // candlestick wicks, and OHLC. One compile per context.
+    { name: "line-uniform", vert: lineUniformVert, frag: lineUniformFrag },
+    {
+        name: "candlestick-body",
+        vert: candlestickBodyVert,
+        frag: candlestickBodyFrag,
+    },
+    { name: "heatmap", vert: heatmapVert, frag: heatmapFrag },
+    { name: "sunburst-arc", vert: sunburstArcVert, frag: sunburstArcFrag },
+    { name: "treemap", vert: treemapVert, frag: treemapFrag },
+    {
+        name: "density-splat",
+        vert: densitySplatVert,
+        frag: densitySplatFrag,
+    },
+    {
+        name: "density-extreme",
+        vert: densitySplatVert,
+        frag: densityExtremeFrag,
+    },
+    {
+        name: "density-resolve",
+        vert: densityResolveVert,
+        frag: densityResolveFrag,
+    },
+    // The MRT variant declares `#extension GL_EXT_draw_buffers :
+    // require` and only compiles on contexts that advertise it. The
+    // glyph compiles it lazily after probing `OES_draw_buffers_indexed`
+    // — adding it here would crash precompile on hardware without
+    // multi-render-target support.
+
+    // Map tile basemap (textured quad in Mercator space). Compiled
+    // unconditionally because the program is GLSL 100 and links on
+    // every WebGL1/2 context; the loader only kicks in when a map
+    // plugin tag activates.
+    { name: "map-tile", vert: tileVert, frag: tileFrag },
+];
+
+// Re-export each shader source so glyph modules can import their
+// source from the manifest rather than from `../shaders/*.glsl`
+// directly. This keeps the manifest's vert/frag fields and the
+// `getOrCreate` call sites pointing at exactly the same string
+// constants — module dedup ensures reference identity, so cache
+// hits work even on the lazy path.
+export {
+    barVert,
+    barFrag,
+    lineVert,
+    lineFrag,
+    scatterVert,
+    scatterFrag,
+    areaVert,
+    areaFrag,
+    lineUniformVert,
+    lineUniformFrag,
+    yScatterVert,
+    yScatterFrag,
+    candlestickBodyVert,
+    candlestickBodyFrag,
+    heatmapVert,
+    heatmapFrag,
+    sunburstArcVert,
+    sunburstArcFrag,
+    treemapVert,
+    treemapFrag,
+    densitySplatVert,
+    densitySplatFrag,
+    densityExtremeFrag,
+    densityMrtVert,
+    densityMrtFrag,
+    densityResolveVert,
+    densityResolveFrag,
+    tileVert,
+    tileFrag,
+};

package/src/ts/webgl/shader-registry.ts

@@ -0,0 +1,97 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 type { ShaderSpec } from "./shader-manifest";
+
+type GL = WebGL2RenderingContext | WebGLRenderingContext;
+
+export class ShaderRegistry {
+    private _gl: GL;
+    private _programs: Map<string, WebGLProgram> = new Map();
+
+    constructor(gl: GL) {
+        this._gl = gl;
+    }
+
+    /**
+     * Compile + link every program in `specs` eagerly. Used by
+     * `WebGLContextManager` when constructed with `precompile: true`
+     * so the first-frame path doesn't pay the compile cost inline.
+     *
+     * Compilation is synchronous and serial — single-digit ms per
+     * program on a modern GPU. With `KHR_parallel_shader_compile`
+     * (browser-supported but not yet wired here) the work could be
+     * dispatched to driver threads; today we accept the wall-time
+     * cost in exchange for simpler code and a deterministic init.
+     */
+    precompile(specs: readonly ShaderSpec[]): void {
+        for (const spec of specs) {
+            this.getOrCreate(spec.name, spec.vert, spec.frag);
+        }
+    }
+
+    getOrCreate(name: string, vertSrc: string, fragSrc: string): WebGLProgram {
+        let program = this._programs.get(name);
+        if (program) {
+            return program;
+        }
+
+        const gl = this._gl;
+
+        const vert = gl.createShader(gl.VERTEX_SHADER)!;
+        gl.shaderSource(vert, vertSrc);
+        gl.compileShader(vert);
+        if (!gl.getShaderParameter(vert, gl.COMPILE_STATUS)) {
+            const info = gl.getShaderInfoLog(vert);
+            gl.deleteShader(vert);
+            throw new Error(`Vertex shader compile error [${name}]: ${info}`);
+        }
+
+        const frag = gl.createShader(gl.FRAGMENT_SHADER)!;
+        gl.shaderSource(frag, fragSrc);
+        gl.compileShader(frag);
+        if (!gl.getShaderParameter(frag, gl.COMPILE_STATUS)) {
+            const info = gl.getShaderInfoLog(frag);
+            gl.deleteShader(vert);
+            gl.deleteShader(frag);
+            throw new Error(`Fragment shader compile error [${name}]: ${info}`);
+        }
+
+        program = gl.createProgram()!;
+        gl.attachShader(program, vert);
+        gl.attachShader(program, frag);
+        gl.linkProgram(program);
+
+        if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+            const info = gl.getProgramInfoLog(program);
+            gl.deleteProgram(program);
+            gl.deleteShader(vert);
+            gl.deleteShader(frag);
+            throw new Error(`Shader link error [${name}]: ${info}`);
+        }
+
+        // Shaders can be deleted after linking
+        gl.deleteShader(vert);
+        gl.deleteShader(frag);
+
+        this._programs.set(name, program);
+        return program;
+    }
+
+    releaseAll(): void {
+        for (const program of this._programs.values()) {
+            this._gl.deleteProgram(program);
+        }
+
+        this._programs.clear();
+    }
+}

package/src/ts/worker/boot.ts

@@ -0,0 +1,22 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+// In Web Worker scope, `window` is undefined but some bundled code
+// (`@perspective-dev/viewer` wasm-bindgen JS, plus a few feature
+// detects) probes it. Provide a stub *only* in worker scope — when
+// this module is dynamic-imported on the main thread for the
+// in-process renderer path, `window` is the real `Window` and we must
+// not clobber it.
+if (typeof window === "undefined") {
+    // @ts-ignore
+    globalThis.window = {};
+}

package/src/ts/worker/dispatch.ts

@@ -0,0 +1,99 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 type { ControlMsg } from "../transport/protocol";
+import type { WorkerRenderer } from "./renderer.worker";
+
+/**
+ * Stateless control-message dispatcher. The renderer instance is
+ * supplied by the caller so worker mode (one global instance) and
+ * in-process mode (one instance per host element) share the same
+ * routing logic.
+ */
+export function dispatch(r: WorkerRenderer, msg: ControlMsg): void {
+    switch (msg.kind) {
+        case "setViewByName":
+            r.setViewByName(msg.name);
+            break;
+        case "setColumnsConfig":
+            r.chartImpl.setColumnsConfig?.(msg.cfg);
+            break;
+        case "setPluginConfig":
+            r.chartImpl.setPluginConfig?.(msg.cfg);
+            r.redraw();
+            break;
+        case "setBufferMaxCapacity":
+            r.glManager.bufferPool.maxCapacity = msg.n;
+            break;
+        case "loadAndRender":
+            r.loadAndRender(msg);
+            break;
+        case "redraw":
+            r.redraw();
+            break;
+        case "resize":
+            console.log("resize");
+            r.resize(msg.cssWidth, msg.cssHeight, msg.dpr);
+            r.redraw();
+            break;
+        case "clear":
+            r.clear();
+            break;
+        case "invalidateTheme":
+            r.chartImpl.setTheme?.(msg.themeVars);
+            r.chartImpl.invalidateTheme?.();
+            r.resize(r.cssWidth, r.cssHeight, r.dpr);
+            break;
+        case "restoreZoom":
+            r.restoreZoom(msg.state);
+            break;
+        case "resetAllZooms":
+            r.resetAllZooms();
+            r.redraw();
+            r.post({
+                kind: "zoomChanged",
+                isDefault: r.allZoomsDefault(),
+            });
+            break;
+        case "resetExpandedDomain":
+            r.resetExpandedDomain();
+            break;
+        case "interaction":
+            r.onInteraction(msg.event);
+            break;
+        case "saveZoom":
+            r.post({
+                kind: "saveZoomReply",
+                requestId: msg.requestId,
+                state: r.saveZoom(),
+            });
+            break;
+        case "destroy":
+            r.destroy();
+            break;
+        case "init":
+            // Re-init not supported; ignore to keep the renderer alive
+            // for the host's `delete()` cleanup path.
+            break;
+        case "snapshotPng": {
+            const requestId = msg.requestId;
+            r.snapshotPng()
+                .then((blob) => {
+                    r.post({ kind: "snapshotPngReply", requestId, blob });
+                })
+                .catch((err) => {
+                    r.post({ kind: "error", message: String(err) });
+                });
+            break;
+        }
+    }
+}

package/src/ts/worker/font-loader.ts

@@ -0,0 +1,89 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 type { FontFaceDescriptor } from "../transport/protocol";
+
+/**
+ * Worker-scope font registration cache, keyed by `family|src|weight|
+ * style`. Multiple sessions in one shared worker often ship identical
+ * font snapshots (the host's `snapshotFontFaces()` walks
+ * `document.styleSheets`, which is page-global). Without this cache,
+ * each session would `face.load()` + `fonts.add(face)` afresh —
+ * harmless but wasteful, since `fonts.add` dedupes by family but each
+ * `face.load()` still pays the await.
+ *
+ * The first session to ask for a given font owns the load promise;
+ * every subsequent session awaits it.
+ */
+const FONT_LOADS = new Map<string, Promise<void>>();
+
+export async function loadFontDeduped(d: FontFaceDescriptor): Promise<void> {
+    const key = [
+        d.family,
+        d.src,
+        d.weight ?? "",
+        d.style ?? "",
+        // d.stretch ?? "",
+        // d.unicodeRange ?? "",
+        // d.variant ?? "",
+        // d.featureSettings ?? "",
+        // d.display ?? "",
+    ].join("|");
+
+    let p = FONT_LOADS.get(key);
+    if (p) {
+        await p;
+        return;
+    }
+
+    p = (async () => {
+        try {
+            const descriptors: FontFaceDescriptors = {};
+            if (d.style) {
+                descriptors.style = d.style;
+            }
+
+            if (d.weight) {
+                descriptors.weight = d.weight;
+            }
+
+            if (d.stretch) {
+                descriptors.stretch = d.stretch;
+            }
+
+            // if (d.unicodeRange) {
+            //     descriptors.unicodeRange = d.unicodeRange;
+            // }
+
+            // if (d.variant) {
+            //     (descriptors as any).variant = d.variant;
+            // }
+
+            // if (d.featureSettings) {
+            //     descriptors.featureSettings = d.featureSettings;
+            // }
+
+            // if (d.display) {
+            //     (descriptors as any).display = d.display;
+            // }
+
+            const face = new FontFace(d.family, d.src, descriptors);
+            await face.load();
+            (self as any).fonts.add(face);
+        } catch (err) {
+            console.warn(`Failed to load font ${d.family}:`, err);
+        }
+    })();
+
+    FONT_LOADS.set(key, p);
+    await p;
+}