@perspective-dev/viewer-charts 4.3.0

package/src/ts/index.ts

@@ -0,0 +1,53 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 CHARTS from "./plugin/charts";
+import { HTMLPerspectiveViewerWebGLPluginElement } from "./plugin/plugin";
+
+export type { PerspectiveClickDetail } from "./event-detail";
+export { PerspectiveSelectDetail } from "./event-detail";
+
+export function register(...plugin_names: string[]) {
+    const plugins = new Set(
+        plugin_names.length > 0
+            ? plugin_names
+            : CHARTS.map((chart) => chart.name),
+    );
+
+    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.
+            customElements.define(
+                tagName,
+                class extends HTMLPerspectiveViewerWebGLPluginElement {
+                    _chartType = chart;
+                    static _chartType = chart;
+                },
+            );
+
+            customElements.whenDefined("perspective-viewer").then(async () => {
+                const Viewer = customElements.get("perspective-viewer") as any;
+                await Viewer.registerPlugin(tagName);
+            });
+        }
+    });
+}
+
+register();

package/src/ts/interaction/hit-test.ts

@@ -0,0 +1,106 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 { SpatialGrid } from "./spatial-grid";
+
+export interface HitBounds {
+    xMin: number;
+    xMax: number;
+    yMin: number;
+    yMax: number;
+}
+
+/**
+ * Wraps SpatialGrid with dirty-flag bookkeeping + the cell-size heuristic
+ * (~√n cells), so chart code no longer repeats the insertion loop scaffold.
+ * Callers drive the iteration through `rebuild` and the `visit` callback,
+ * which lets scatter (flat array) and line (series-indexed array) share
+ * the same code path.
+ */
+export class SpatialHitTester {
+    private _grid: SpatialGrid | null = null;
+    private _dirty = true;
+
+    markDirty(): void {
+        this._dirty = true;
+    }
+
+    get isDirty(): boolean {
+        return this._dirty;
+    }
+
+    /**
+     * Rebuild the grid. `forEachPoint` is called once with an insert
+     * function; the caller drives iteration. Cleared when `pointCount`
+     * is zero.
+     */
+    rebuild(
+        bounds: HitBounds,
+        pointCount: number,
+        forEachPoint: (
+            insert: (idx: number, x: number, y: number) => void,
+        ) => void,
+    ): void {
+        if (pointCount === 0) {
+            this._grid = null;
+            this._dirty = false;
+            return;
+        }
+
+        const xRange = bounds.xMax - bounds.xMin || 1;
+        const yRange = bounds.yMax - bounds.yMin || 1;
+        const avgRange = (xRange + yRange) / 2;
+        const cellSize = avgRange / Math.max(1, Math.sqrt(pointCount));
+        const grid = new SpatialGrid(
+            bounds.xMin,
+            bounds.xMax,
+            bounds.yMin,
+            bounds.yMax,
+            cellSize,
+        );
+        forEachPoint((idx, x, y) => grid.insert(idx, x, y));
+        this._grid = grid;
+        this._dirty = false;
+    }
+
+    /**
+     * Query the nearest point within `radiusPx` of (dataX, dataY).
+     */
+    query(
+        dataX: number,
+        dataY: number,
+        radiusPx: number,
+        pxPerDataX: number,
+        pxPerDataY: number,
+        xData: Float32Array | null,
+        yData: Float32Array | null,
+    ): number {
+        if (!this._grid || !xData || !yData) {
+            return -1;
+        }
+
+        return this._grid.query(
+            dataX,
+            dataY,
+            radiusPx,
+            pxPerDataX,
+            pxPerDataY,
+            xData,
+            yData,
+        );
+    }
+
+    clear(): void {
+        this._grid = null;
+        this._dirty = true;
+    }
+}

package/src/ts/interaction/host-sink-dom.ts

@@ -0,0 +1,85 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 { CssBounds, HostSink } from "./tooltip-controller";
+
+/**
+ * Host-side `HostSink` that materializes pinned tooltips as a `<div>`
+ * next to the GL canvas, and applies cursor changes to the canvas's
+ * own `style.cursor`. Host-only — depends on `document` /
+ * `getComputedStyle`.
+ */
+export class DomHostSink implements HostSink {
+    private _glCanvas: HTMLCanvasElement;
+    private _parent: HTMLElement;
+    private _div: HTMLDivElement | null = null;
+
+    constructor(glCanvas: HTMLCanvasElement, parent: HTMLElement) {
+        this._glCanvas = glCanvas;
+        this._parent = parent;
+    }
+
+    pin(
+        lines: string[],
+        pos: { px: number; py: number },
+        bounds: CssBounds,
+    ): void {
+        this.dismiss();
+        const div = document.createElement("div");
+
+        div.className = "webgl-tooltip";
+        div.style.maxHeight = `${Math.round(bounds.cssHeight * 0.6)}px`;
+        div.textContent = lines.join("\n");
+
+        if (getComputedStyle(this._parent).position === "static") {
+            this._parent.style.position = "relative";
+        }
+
+        div.style.left = "-9999px";
+        div.style.top = "0px";
+        this._parent.appendChild(div);
+        this._div = div;
+        const divW = div.getBoundingClientRect().width;
+        const divH = div.getBoundingClientRect().height;
+        let tx = pos.px + 12;
+        let ty = pos.py - divH - 8;
+        if (tx + divW > bounds.cssWidth) {
+            tx = pos.px - divW - 12;
+        }
+
+        if (tx < 0) {
+            tx = 4;
+        }
+
+        if (ty < 0) {
+            ty = pos.py + 12;
+        }
+
+        if (ty + divH > bounds.cssHeight) {
+            ty = bounds.cssHeight - divH - 4;
+        }
+
+        div.style.left = `${tx}px`;
+        div.style.top = `${ty}px`;
+    }
+
+    dismiss(): void {
+        if (this._div) {
+            this._div.remove();
+            this._div = null;
+        }
+    }
+
+    setCursor(cursor: string): void {
+        this._glCanvas.style.cursor = cursor;
+    }
+}

package/src/ts/interaction/host-sink-message.ts

@@ -0,0 +1,75 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 {
+    CssBounds,
+    HostSink,
+    UserClickPayload,
+    UserSelectPayload,
+} from "./tooltip-controller";
+
+/**
+ * Envelope shape sent by `MessageHostSink`. The transport translates
+ * each one into a corresponding `WorkerMsg` (`pinTooltip` /
+ * `dismissTooltip` / `setCursor` / `userClick` / `userSelect`).
+ */
+export type HostSinkEnvelope =
+    | {
+          kind: "pin";
+          payload: {
+              lines: string[];
+              pos: { px: number; py: number };
+              bounds: CssBounds;
+          };
+      }
+    | { kind: "dismiss" }
+    | { kind: "setCursor"; cursor: string }
+    | { kind: "userClick"; payload: UserClickPayload }
+    | { kind: "userSelect"; payload: UserSelectPayload };
+
+/**
+ * `HostSink` that posts pin / dismiss / setCursor / user-event intents
+ * over a `postMessage`-style channel. The host-side transport listens
+ * for these envelopes and drives a `DomHostSink` for pin/dismiss and
+ * dispatches `CustomEvent`s on the viewer for user events.
+ */
+export class MessageHostSink implements HostSink {
+    private _send: (msg: HostSinkEnvelope) => void;
+
+    constructor(send: (msg: HostSinkEnvelope) => void) {
+        this._send = send;
+    }
+
+    pin(
+        lines: string[],
+        pos: { px: number; py: number },
+        bounds: CssBounds,
+    ): void {
+        this._send({ kind: "pin", payload: { lines, pos, bounds } });
+    }
+
+    dismiss(): void {
+        this._send({ kind: "dismiss" });
+    }
+
+    setCursor(cursor: string): void {
+        this._send({ kind: "setCursor", cursor });
+    }
+
+    emitUserClick(payload: UserClickPayload): void {
+        this._send({ kind: "userClick", payload });
+    }
+
+    emitUserSelect(payload: UserSelectPayload): void {
+        this._send({ kind: "userSelect", payload });
+    }
+}

package/src/ts/interaction/lazy-tooltip.ts

@@ -0,0 +1,102 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+/**
+ * Serial-checked async tooltip cache.
+ *
+ * Every chart family that paints tooltip text from a lazy row fetch
+ * needs the same dance: each hover (or pin) bumps a serial; the async
+ * line-build resolves later; if the user has moved on by then the
+ * resolved lines must be discarded so we don't paint stale text.
+ *
+ * Hit-test logic stays per-chart — that genuinely diverges (spatial
+ * grid for cartesian, walk-visible-nodes for treemap, angular for
+ * sunburst). The serial discipline is what was getting copy-pasted.
+ *
+ * `Target` is whatever identity the chart uses for hover/pin (flat
+ * slot index, node id, etc.); it's stored on `hoveredTarget` so the
+ * render path can tell whether cached `lines` belong to the currently
+ * hovered entity (some charts paint tooltip text only when both
+ * agree).
+ */
+export class LazyTooltip<Target> {
+    /**
+     * Cached lines for the latest committed hover, or `null`.
+     */
+    lines: string[] | null = null;
+
+    /**
+     * Identity of the entity `lines` describe. `null` when cleared.
+     */
+    hoveredTarget: Target | null = null;
+
+    private _hoverSerial = 0;
+    private _pinSerial = 0;
+
+    /**
+     * Begin a new hover. Call this only when the hovered entity has
+     * actually changed. Clears the cached lines, records the new
+     * target, bumps the hover serial, and returns the new value — pass
+     * it back to {@link commitHover} from your async resolver to gate
+     * the write.
+     */
+    beginHover(target: Target): number {
+        this.lines = null;
+        this.hoveredTarget = target;
+        return ++this._hoverSerial;
+    }
+
+    /**
+     * Commit a freshly-resolved line list for `serial`. Returns true
+     * when the write happened (caller should repaint), false when the
+     * serial was stale.
+     */
+    commitHover(serial: number, lines: string[]): boolean {
+        if (serial !== this._hoverSerial) {
+            return false;
+        }
+
+        this.lines = lines;
+        return true;
+    }
+
+    /**
+     * Clear hover state (mouse left, view changed, etc.).
+     */
+    clearHover(): void {
+        this.lines = null;
+        this.hoveredTarget = null;
+        this._hoverSerial++;
+    }
+
+    /**
+     * Begin a pin operation. Returns the serial; pass it to
+     * {@link isPinFresh} from your async resolver.
+     */
+    beginPin(): number {
+        return ++this._pinSerial;
+    }
+
+    /**
+     * True when `serial` still names the latest pin attempt.
+     */
+    isPinFresh(serial: number): boolean {
+        return serial === this._pinSerial;
+    }
+
+    /**
+     * Bump the pin serial without starting a new pin (e.g. dismiss).
+     */
+    invalidatePin(): void {
+        this._pinSerial++;
+    }
+}

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

@@ -0,0 +1,175 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 { InteractionEvent } from "../transport/protocol";
+
+/**
+ * Worker-mode counterpart to {@link ZoomRouter}. Captures wheel /
+ * pointer events on the GL canvas, normalizes coords to canvas-relative
+ * CSS pixels, and emits semantic {@link InteractionEvent}s to the
+ * Renderer over its transport. The Renderer (running in a Web Worker)
+ * owns the `ZoomController`s and runs the actual hit-test + apply
+ * logic — see `applyWheel` / `applyPan` in `zoom-router.ts`.
+ *
+ * Pointer capture is set on `pointerdown` and released on `pointerup`
+ * so drags continue to deliver `pointermove` events when the cursor
+ * leaves the canvas, matching the in-process `ZoomRouter` behavior.
+ */
+export class RawEventForwarder {
+    private _element: HTMLElement | null = null;
+    private _emit: ((e: InteractionEvent) => void) | null = null;
+    private _pointerId: number | null = null;
+
+    private _onWheel: ((e: WheelEvent) => void) | null = null;
+    private _onPointerDown: ((e: PointerEvent) => void) | null = null;
+    private _onPointerMove: ((e: PointerEvent) => void) | null = null;
+    private _onPointerUp: ((e: PointerEvent) => void) | null = null;
+    private _onPointerLeave: (() => void) | null = null;
+    private _onClick: ((e: MouseEvent) => void) | null = null;
+    private _onDblClick: ((e: MouseEvent) => void) | null = null;
+
+    attach(element: HTMLElement, emit: (e: InteractionEvent) => void): void {
+        this.detach();
+        this._element = element;
+        this._emit = emit;
+
+        this._onWheel = (e: WheelEvent) => {
+            const rect = element.getBoundingClientRect();
+            const mx = e.clientX - rect.left;
+            const my = e.clientY - rect.top;
+
+            // Match `ZoomRouter`: only consume the wheel event if the
+            // cursor is over the canvas. `preventDefault` is fired
+            // unconditionally so the page does not scroll while the
+            // chart is hovered — the worker may still no-op if the
+            // cursor is outside any facet's plot rect.
+            e.preventDefault();
+            emit({ type: "wheel", mx, my, deltaY: e.deltaY });
+        };
+
+        this._onPointerDown = (e: PointerEvent) => {
+            const rect = element.getBoundingClientRect();
+            const mx = e.clientX - rect.left;
+            const my = e.clientY - rect.top;
+            element.setPointerCapture(e.pointerId);
+            this._pointerId = e.pointerId;
+            emit({ type: "pointerdown", mx, my, pointerId: e.pointerId });
+        };
+
+        this._onPointerMove = (e: PointerEvent) => {
+            const rect = element.getBoundingClientRect();
+            const mx = e.clientX - rect.left;
+            const my = e.clientY - rect.top;
+            emit({ type: "pointermove", mx, my });
+        };
+
+        this._onPointerUp = (e: PointerEvent) => {
+            if (this._pointerId !== null) {
+                try {
+                    element.releasePointerCapture(this._pointerId);
+                } catch {
+                    // capture may have already been released
+                }
+
+                this._pointerId = null;
+            }
+
+            void e;
+            emit({ type: "pointerup" });
+        };
+
+        // Pointerleave gives the renderer a single signal that the
+        // cursor truly exited the canvas — used for tooltip dismissal.
+        // Hover + drag both ride the `pointermove` stream above, so no
+        // parallel `mousemove` channel exists.
+        this._onPointerLeave = () => {
+            emit({ type: "pointerleave" });
+        };
+
+        this._onClick = (e: MouseEvent) => {
+            const rect = element.getBoundingClientRect();
+            emit({
+                type: "click",
+                mx: e.clientX - rect.left,
+                my: e.clientY - rect.top,
+            });
+        };
+
+        this._onDblClick = (e: MouseEvent) => {
+            const rect = element.getBoundingClientRect();
+            emit({
+                type: "dblclick",
+                mx: e.clientX - rect.left,
+                my: e.clientY - rect.top,
+            });
+        };
+
+        element.addEventListener("wheel", this._onWheel, { passive: false });
+        element.addEventListener("pointerdown", this._onPointerDown);
+        element.addEventListener("pointermove", this._onPointerMove);
+        element.addEventListener("pointerup", this._onPointerUp);
+        element.addEventListener("pointerleave", this._onPointerLeave);
+        element.addEventListener("click", this._onClick);
+        element.addEventListener("dblclick", this._onDblClick);
+    }
+
+    detach(): void {
+        if (this._element) {
+            if (this._onWheel) {
+                this._element.removeEventListener("wheel", this._onWheel);
+            }
+
+            if (this._onPointerDown) {
+                this._element.removeEventListener(
+                    "pointerdown",
+                    this._onPointerDown,
+                );
+            }
+
+            if (this._onPointerMove) {
+                this._element.removeEventListener(
+                    "pointermove",
+                    this._onPointerMove,
+                );
+            }
+
+            if (this._onPointerUp) {
+                this._element.removeEventListener(
+                    "pointerup",
+                    this._onPointerUp,
+                );
+            }
+
+            if (this._onPointerLeave) {
+                this._element.removeEventListener(
+                    "pointerleave",
+                    this._onPointerLeave,
+                );
+            }
+
+            if (this._onClick) {
+                this._element.removeEventListener("click", this._onClick);
+            }
+
+            if (this._onDblClick) {
+                this._element.removeEventListener("dblclick", this._onDblClick);
+            }
+        }
+
+        this._element = null;
+        this._emit = null;
+        this._pointerId = null;
+        this._onPointerLeave = null;
+        this._onClick = null;
+        this._onDblClick = null;
+    }
+}