@perspective-dev/viewer-charts 4.3.0

package/src/ts/charts/treemap/treemap.ts

@@ -0,0 +1,247 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 { ColumnDataMap } from "../../data/view-reader";
+import type { WebGLContextManager } from "../../webgl/context-manager";
+import { TreeChartBase } from "../common/tree-chart";
+import { NULL_NODE } from "../common/node-store";
+import {
+    type BreadcrumbRegion,
+    processTreemapChunk,
+    finalizeTreemap,
+    resetTreemapState,
+} from "./treemap-layout";
+import { renderTreemapFrame } from "./treemap-render";
+import {
+    handleTreemapHover,
+    handleTreemapClick,
+    handleTreemapDblClick,
+    dismissTreemapPinnedTooltip,
+} from "./treemap-interact";
+
+export interface TreemapLocations {
+    u_resolution: WebGLUniformLocation | null;
+    a_position: number;
+    a_color: number;
+}
+
+/**
+ * Sentinel fallback for the Size slot when the user hasn't picked one:
+ * use the first non-metadata column in the incoming view. Treemap
+ * still needs *some* numeric-ish column to size rects.
+ */
+function firstNonMetadataColumn(columns: ColumnDataMap): string {
+    for (const k of columns.keys()) {
+        if (!k.startsWith("__")) {
+            return k;
+        }
+    }
+
+    return "";
+}
+
+/**
+ * Treemap chart. Shares tree storage + streaming-pipeline + color-mode
+ * state with `TreeChartBase`; adds rectangular layout + WebGL quad
+ * rendering + drill / tooltip interactions.
+ */
+export class TreemapChart extends TreeChartBase {
+    _program: WebGLProgram | null = null;
+    _locations: TreemapLocations | null = null;
+    _positionBuffer: WebGLBuffer | null = null;
+    _colorBuffer: WebGLBuffer | null = null;
+    _vertexCount = 0;
+
+    //  Interaction
+    _hoveredNodeId: number = NULL_NODE;
+    _pinnedNodeId: number = NULL_NODE;
+    _breadcrumbRegions: BreadcrumbRegion[] = [];
+    _chromeCache: ImageBitmap | null = null;
+    _chromeCacheDirty = true;
+
+    /**
+     * Monotonic generation counter bumped every time the static chrome
+     * content changes (a new `drawStaticChrome` call). The async
+     * `createImageBitmap` callback captures the current gen at kickoff
+     * and only installs the resulting bitmap if its gen is still the
+     * most-recent one. Without this, out-of-order bitmap resolutions
+     * can store a stale bitmap in `_chromeCache` — any subsequent
+     * hover-only overlay call then blits that stale snapshot over the
+     * fresh chart, producing "leftover labels / cells" artefacts.
+     */
+    _chromeCacheGen = 0;
+
+    //  Faceted state
+    /**
+     * Per-facet drill roots in split_by mode. Key is the facet label
+     * (the top-level child of `_rootId`); value is the currently drilled
+     * node inside that facet's subtree. Missing keys mean the facet
+     * shows its full subtree.
+     */
+    _facetDrillRoots: Map<string, number> = new Map();
+    _facetGrid: import("../../layout/facet-grid").FacetGrid | null = null;
+
+    /** When `false`, branch nodes at relDepth=1 render as a centered
+     *  overlay (same style as relDepth=2) and no top-of-rect label
+     *  reservation is made in `squarify`. Default `true` preserves the
+     *  legacy title-bar look. */
+    _showBranchHeader = false;
+
+    /**
+     * Parallel to `_visibleNodeIds`. Each entry stores the depth of the
+     * drill root that owns the corresponding visible node, so render
+     * paths can compute `relDepth` uniformly without knowing whether
+     * faceting is active. Populated in `renderTreemapFrame` during
+     * layout.
+     */
+    _visibleBaseDepths: Int32Array | null = null;
+
+    /**
+     * Parallel to `_visibleNodeIds`. The drill-root node id that owns
+     * each visible node (= `_currentRootId` in non-facet mode, per-
+     * facet drill root in facet mode). Used by hit-testing and chrome
+     * to skip the drill-root itself without a separate equality check.
+     */
+    _visibleRootIds: Int32Array | null = null;
+
+    protected override tooltipCallbacks() {
+        return {
+            onHover: (mx: number, my: number) =>
+                handleTreemapHover(this, mx, my),
+            onLeave: () => {
+                if (
+                    this._hoveredNodeId !== NULL_NODE &&
+                    this._pinnedNodeId === NULL_NODE
+                ) {
+                    this._hoveredNodeId = NULL_NODE;
+                    if (this._glManager) {
+                        renderTreemapFrame(this, this._glManager);
+                    }
+                }
+            },
+            onClickPre: (mx: number, my: number) => {
+                handleTreemapClick(this, mx, my);
+                return true; // treemap owns all click logic
+            },
+            onDblClick: (mx: number, my: number) =>
+                handleTreemapDblClick(this, mx, my),
+        };
+    }
+
+    async uploadAndRender(
+        glManager: WebGLContextManager,
+        columns: ColumnDataMap,
+        startRow: number,
+        _endRow: number,
+    ): Promise<void> {
+        this._glManager = glManager;
+
+        if (startRow === 0) {
+            const slots = this._columnSlots;
+            this._sizeName = slots[0] || firstNonMetadataColumn(columns) || "";
+            this._colorName = slots[1] || "";
+            if (!this._colorName) {
+                this._colorMode = "empty";
+            } else {
+                const t = this._columnTypes[this._colorName];
+                const isNumeric =
+                    t === "float" ||
+                    t === "integer" ||
+                    t === "date" ||
+                    t === "datetime";
+                this._colorMode = isNumeric ? "numeric" : "series";
+            }
+
+            // Clear per-draw state that's tied to the OLD tree. Node
+            // IDs from the previous render don't map to anything in
+            // the fresh tree; leaving them around lets stale drill
+            // roots, hovered/pinned IDs, breadcrumb regions, the
+            // cached chrome bitmap, or an old WebGL vertex count bleed
+            // into the new render as ghost rects / labels / hit
+            // targets. See tree-data.ts's `resetTreeState` for the
+            // shared fields; everything below is treemap-specific.
+            this._hoveredNodeId = NULL_NODE;
+            this._pinnedNodeId = NULL_NODE;
+            this._breadcrumbRegions = [];
+            this._facetDrillRoots.clear();
+            this._facetGrid = null;
+            this._visibleBaseDepths = null;
+            this._visibleRootIds = null;
+
+            // Invalidate the GPU buffer contents so any render that
+            // fires before `generateAndUploadTreemap` has refilled the
+            // buffers draws zero triangles instead of the previous
+            // tree's geometry.
+            this._vertexCount = 0;
+
+            // Drop any in-flight hover tooltip promise — bumping the
+            // controller's serials makes stale resolutions no-ops
+            // rather than painting old lines on the new chart.
+            this._lazyTooltip.clearHover();
+            this._lazyTooltip.invalidatePin();
+            dismissTreemapPinnedTooltip(this);
+            this._chromeCache?.close();
+            this._chromeCache = null;
+            this._chromeCacheDirty = true;
+            this._chromeCacheGen++;
+
+            resetTreemapState(this);
+        }
+
+        processTreemapChunk(this, columns);
+        finalizeTreemap(this);
+        if (this._rootId !== NULL_NODE) {
+            await this.requestRender(glManager);
+        }
+    }
+
+    _fullRender(glManager: WebGLContextManager): void {
+        if (this._rootId === NULL_NODE) {
+            return;
+        }
+
+        this._glManager = glManager;
+        renderTreemapFrame(this, glManager);
+    }
+
+    protected destroyInternal(): void {
+        dismissTreemapPinnedTooltip(this);
+        this._chromeCache?.close();
+        this._chromeCache = null;
+        const gl = this._glManager?.gl;
+        if (gl) {
+            if (this._positionBuffer) {
+                gl.deleteBuffer(this._positionBuffer);
+            }
+
+            if (this._colorBuffer) {
+                gl.deleteBuffer(this._colorBuffer);
+            }
+        }
+
+        this._positionBuffer = null;
+        this._colorBuffer = null;
+        this._program = null;
+        this._locations = null;
+        this._rootId = NULL_NODE;
+        this._currentRootId = NULL_NODE;
+        this._breadcrumbIds = [];
+        this._childLookup.clear();
+        this._visibleNodeIds = null;
+        this._visibleNodeCount = 0;
+        this._breadcrumbRegions = [];
+        this._facetDrillRoots.clear();
+        this._facetGrid = null;
+        this._visibleBaseDepths = null;
+        this._visibleRootIds = null;
+    }
+}

package/src/ts/config.ts

@@ -0,0 +1,41 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+/**
+ * Renderer mode. `"worker"` runs the chart code in a Web Worker (off
+ * the main thread, gets parallelism but pays a postMessage hop on
+ * every interaction). `"inprocess"` dynamic-imports the same worker
+ * module on the main thread so the bundle stays single-copy without
+ * the worker boundary. The two paths share a `MessageChannel`-shaped
+ * control protocol — only the handle around it differs.
+ */
+export const RUNTIME_MODE: "worker" | "inprocess" = "worker";
+
+/**
+ * Build-time toggle between the two GL-canvas display strategies.
+ *
+ * - `"direct"` — host transfers `.webgl-canvas` to the renderer via
+ *   `transferControlToOffscreen`. The renderer's GL context renders
+ *   straight into the visible drawing buffer.
+ *
+ * - `"blit"` — host keeps the visible canvas main-thread with a 2D
+ *   context. The renderer creates its own internal `OffscreenCanvas`
+ *   for GL rendering and emits each completed frame as an
+ *   `ImageBitmap` over the control channel; the host blits the bitmap
+ *   into the visible canvas via `drawImage`.
+ */
+export const RENDER_BLIT_MODE: "direct" | "blit" = "direct";
+
+/**
+ * Strict-mode validation for `BufferPool.upload`.
+ */
+export const BUFFER_POOL_STRICT: boolean = false;

package/src/ts/data/lazy-row.ts

@@ -0,0 +1,140 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 { View } from "@perspective-dev/client";
+
+/**
+ * A single row's column values, keyed by column name. Numeric columns
+ * yield a `number`; string (dictionary) columns yield the decoded
+ * `string`; invalid (null) cells yield `null`.
+ */
+export type LazyRow = Map<string, string | number | null>;
+
+const DEFAULT_CACHE_SIZE = 128;
+
+/**
+ * On-demand single-row fetcher backing lazy tooltip lookups. Given a
+ * view row index, performs `view.with_typed_arrays({start_row, end_row:
+ * start_row+1})` and projects the result into a plain `Map`. Concurrent
+ * fetches for the same index are deduped into one Promise; resolved
+ * rows are cached in a bounded LRU keyed by rowIdx.
+ *
+ * Invalidation is lifecycle-driven: the owning chart disposes and
+ * constructs a new fetcher whenever its underlying view changes (i.e.
+ * on each `draw`). In-flight fetches from the prior fetcher still
+ * resolve, but callers stamp each fetch with a serial and discard
+ * results whose serial no longer matches — so stale rows never reach
+ * the tooltip. See the per-chart hover/pin paths for that plumbing.
+ */
+export class LazyRowFetcher {
+    private _view: View | null;
+    private _cache: Map<number, LazyRow> = new Map();
+    private _inFlight: Map<number, Promise<LazyRow>> = new Map();
+    private readonly _maxCacheSize: number;
+
+    constructor(view: View, maxCacheSize: number = DEFAULT_CACHE_SIZE) {
+        this._view = view;
+        this._maxCacheSize = maxCacheSize;
+    }
+
+    async fetchRow(rowIdx: number): Promise<LazyRow> {
+        if (!this._view) {
+            throw new Error("LazyRowFetcher disposed");
+        }
+
+        const cached = this._cache.get(rowIdx);
+        if (cached) {
+            // LRU touch: re-insert to move to tail.
+            this._cache.delete(rowIdx);
+            this._cache.set(rowIdx, cached);
+            return cached;
+        }
+
+        const inflight = this._inFlight.get(rowIdx);
+        if (inflight) {
+            return inflight;
+        }
+
+        const p = this._fetch(rowIdx);
+        this._inFlight.set(rowIdx, p);
+        try {
+            const result = await p;
+            if (!this._view) {
+                return result;
+            } // disposed mid-flight
+
+            this._cache.set(rowIdx, result);
+            if (this._cache.size > this._maxCacheSize) {
+                const oldest = this._cache.keys().next().value;
+                if (oldest !== undefined) {
+                    this._cache.delete(oldest);
+                }
+            }
+
+            return result;
+        } finally {
+            this._inFlight.delete(rowIdx);
+        }
+    }
+
+    private async _fetch(rowIdx: number): Promise<LazyRow> {
+        const view = this._view;
+        if (!view) {
+            throw new Error("LazyRowFetcher disposed");
+        }
+
+        const row: LazyRow = new Map();
+        await (view as any).with_typed_arrays(
+            {
+                start_row: rowIdx,
+                end_row: rowIdx + 1,
+                float32: true,
+            },
+            (
+                names: string[],
+                values: ArrayLike<number>[],
+                validities: (Uint8Array | null)[],
+                dictionaries: (string[] | null)[],
+            ) => {
+                for (let i = 0; i < names.length; i++) {
+                    const name = names[i];
+                    if (name.startsWith("__")) {
+                        continue;
+                    }
+
+                    const vals = values[i];
+                    const valid = validities[i];
+                    const dict = dictionaries[i];
+                    const isInvalid = valid ? !((valid[0] >> 0) & 1) : false;
+                    if (isInvalid) {
+                        row.set(name, null);
+                    } else if (dict) {
+                        row.set(name, dict[vals[0] as number]);
+                    } else {
+                        row.set(name, vals[0] as number);
+                    }
+                }
+            },
+        );
+        return row;
+    }
+
+    dispose(): void {
+        this._view = null;
+        this._cache.clear();
+        this._inFlight.clear();
+    }
+
+    get isDisposed(): boolean {
+        return this._view === null;
+    }
+}

package/src/ts/data/split-groups.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 { ColumnDataMap } from "./view-reader";
+
+export interface SplitGroup {
+    /**
+     * Composite prefix (e.g., "East", "East|Enterprise" for multi-level).
+     */
+    prefix: string;
+
+    /**
+     * Map of base column name → full Arrow column name ("prefix|base").
+     */
+    colNames: Map<string, string>;
+}
+
+/**
+ * Group Arrow column names by their split prefix (everything before the
+ * last "|"). A split exists for a prefix only when every `requiredBases`
+ * entry has a non-empty column present for that prefix. `optionalBases`
+ * are included when present but do not gate group inclusion.
+ *
+ * Empty/falsy entries in either base list are skipped.
+ */
+export function buildSplitGroups(
+    columns: ColumnDataMap,
+    requiredBases: string[],
+    optionalBases: string[] = [],
+): SplitGroup[] {
+    const prefixCols = new Map<string, Set<string>>();
+    for (const key of columns.keys()) {
+        if (key.startsWith("__")) {
+            continue;
+        }
+
+        const pipeIdx = key.lastIndexOf("|");
+        if (pipeIdx === -1) {
+            continue;
+        }
+
+        const prefix = key.substring(0, pipeIdx);
+        if (!prefixCols.has(prefix)) {
+            prefixCols.set(prefix, new Set());
+        }
+
+        prefixCols.get(prefix)!.add(key);
+    }
+
+    const out: SplitGroup[] = [];
+    for (const [prefix, keys] of prefixCols) {
+        const resolved = new Map<string, string>();
+        let ok = true;
+        for (const base of requiredBases) {
+            if (!base) {
+                continue;
+            }
+
+            const full = `${prefix}|${base}`;
+            const col = columns.get(full);
+            if (!keys.has(full) || !col?.values) {
+                ok = false;
+                break;
+            }
+
+            resolved.set(base, full);
+        }
+
+        if (!ok) {
+            continue;
+        }
+
+        for (const base of optionalBases) {
+            if (!base) {
+                continue;
+            }
+
+            const full = `${prefix}|${base}`;
+            if (keys.has(full) && columns.get(full)?.values) {
+                resolved.set(base, full);
+            }
+        }
+
+        out.push({ prefix, colNames: resolved });
+    }
+
+    return out;
+}

package/src/ts/data/view-reader.ts

@@ -0,0 +1,107 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 { View } from "@perspective-dev/client";
+
+export interface ColumnData {
+    type: "float32" | "float64" | "int32" | "string";
+    values?: Float32Array | Float64Array | Int32Array;
+
+    /**
+     * Dictionary key indices for string columns.
+     */
+    indices?: Int32Array;
+
+    /**
+     * Dictionary values for string columns.
+     */
+    dictionary?: string[];
+
+    /**
+     * Arrow validity bitfield (1 bit per row).
+     */
+    valid?: Uint8Array;
+}
+
+export type ColumnDataMap = Map<string, ColumnData>;
+
+export interface TypedArrayWindowOptions {
+    start_row?: number;
+    end_row?: number;
+    start_col?: number;
+    end_col?: number;
+    float32?: boolean;
+}
+
+/**
+ * Fetches all columns from a View using `with_typed_arrays` and
+ * builds a `ColumnDataMap`. The `values` typed arrays and `valid`
+ * bitmaps are zero-copy views into WASM memory and remain valid only
+ * for the duration of the `render` callback — if `render` returns a
+ * `Promise`, the underlying `with_typed_arrays` call awaits it before
+ * releasing the backing Arrow buffer. Callers must not retain any
+ * `ColumnData` reference past `render`'s resolution.
+ */
+export async function viewToColumnDataMap(
+    view: View,
+    render: (data: ColumnDataMap) => void | Promise<void>,
+    options?: TypedArrayWindowOptions,
+): Promise<void> {
+    const result: ColumnDataMap = new Map();
+
+    await (view as any).with_typed_arrays(
+        options ?? {},
+        async (
+            names: string[],
+            values: ArrayLike<number>[],
+            validities: (Uint8Array | null)[],
+            dictionaries: (string[] | null)[],
+        ) => {
+            for (let i = 0; i < names.length; i++) {
+                const name = names[i];
+                const vals = values[i];
+                const valid = validities[i] ?? undefined;
+                const dict = dictionaries[i];
+
+                if (dict !== null) {
+                    result.set(name, {
+                        type: "string",
+                        indices: vals as Int32Array,
+                        dictionary: dict,
+                        valid,
+                    });
+                } else if (vals instanceof Float32Array) {
+                    result.set(name, { type: "float32", values: vals, valid });
+                } else if (vals instanceof Int32Array) {
+                    result.set(name, { type: "int32", values: vals, valid });
+                } else if (vals instanceof Float64Array) {
+                    // Datetime/Date columns are emitted as Float64 to keep
+                    // millisecond precision; numeric Float64 also lands here
+                    // when `float32` mode is off. Keep them as f64 — the
+                    // chart's CPU mirrors and extents will rebase to f32 at
+                    // upload time.
+                    result.set(name, { type: "float64", values: vals, valid });
+                } else {
+                    // Fallback: treat as float32
+                    // TODO: Instance check if this needs a copy?
+                    result.set(name, {
+                        type: "float32",
+                        values: new Float32Array(vals as any),
+                        valid,
+                    });
+                }
+            }
+
+            await render(result);
+        },
+    );
+}

package/src/ts/event-detail.ts

@@ -0,0 +1,44 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 { ViewConfig } from "@perspective-dev/client";
+
+/**
+ * Detail payload for the `perspective-click` CustomEvent dispatched on
+ * the `<perspective-viewer>` host when the user clicks a chart glyph.
+ * Shape matches the equivalent type in `@perspective-dev/viewer-datagrid`
+ * so consumers can listen to either plugin uniformly.
+ */
+export interface PerspectiveClickDetail {
+    /**
+     * Source-view row data — keys are column names, values are scalar
+     * cell values. Empty `{}` when the click hit a non-leaf aggregate
+     * (e.g. a treemap branch).
+     */
+    row: Record<string, unknown>;
+
+    /**
+     * Aggregate column(s) the click targeted. Single-entry for series /
+     * heatmap / tree charts; multi-entry would only appear for plugins
+     * that surface multiple measures per glyph (none today).
+     */
+    column_names: string[];
+
+    /**
+     * Pre-built `viewer.restore({ filter })` patch — concatenates the
+     * group_by and split_by pivot values at the click target as
+     * `[<col>, "==", <value>]` clauses.
+     */
+    config: Partial<ViewConfig>;
+}
+
+export { PerspectiveSelectDetail } from "@perspective-dev/viewer/src/ts/extensions.js";