@perspective-dev/viewer-charts 4.3.0

package/dist/esm/charts/series/series.d.ts

@@ -0,0 +1,317 @@
+import type { ColumnDataMap } from "../../data/view-reader";
+import type { WebGLContextManager } from "../../webgl/context-manager";
+import type { ZoomConfig } from "../../interaction/zoom-controller";
+import { CategoricalYChart } from "../common/categorical-y-chart";
+import { type PlotRect } from "../../layout/plot-layout";
+import { type AxisDomain } from "../../axis/numeric-axis";
+import { type SeriesChartRecord, type NumericCategoryDomain, type SeriesInfo, type BarColumns } from "./series-build";
+import { LineGlyph } from "./glyphs/draw-lines";
+import { ScatterGlyph } from "./glyphs/draw-scatter";
+import { AreaGlyph } from "./glyphs/draw-areas";
+/**
+ * Per-frame memo of the auto-fit value extent for a {@link SeriesChart},
+ * keyed on the visible categorical window. Two axis slots (`left*` /
+ * `right*`) because dual-axis bar charts refit independently.
+ */
+export interface SeriesAutoFitCache {
+    catMin: number;
+    catMax: number;
+    hidden: Set<number>;
+    leftMin: number;
+    leftMax: number;
+    hasLeft: boolean;
+    rightMin: number;
+    rightMax: number;
+    hasRight: boolean;
+}
+export interface CachedLocations {
+    u_proj_left: WebGLUniformLocation | null;
+    u_proj_right: WebGLUniformLocation | null;
+    u_hover_series: WebGLUniformLocation | null;
+    u_horizontal: WebGLUniformLocation | null;
+    a_corner: number;
+    a_x_center: number;
+    a_half_width: number;
+    a_y0: number;
+    a_y1: number;
+    a_color: number;
+    a_series_id: number;
+    a_axis: number;
+}
+/**
+ * Bar chart. Fields are package-internal (no `private`) so helper modules
+ * in this folder can read/write them.
+ *
+ * Orientation: vertical (Y Bar) is the default — categorical X, numeric
+ * Y. When `_isHorizontal` is true (X Bar) the roles swap: numeric X,
+ * categorical Y reading top-to-bottom. The data pipeline + instance
+ * attributes stay in *logical* coordinates (xCenter = category center,
+ * y0/y1 = value extent); the swap happens in three places only:
+ *   1. Projection matrix (`bar-render.ts`) — args reordered, Y flipped.
+ *   2. Vertex shader — `u_horizontal` uniform transposes position.
+ *   3. Chrome (`bar-axis.ts`) — categorical axis moves from bottom to
+ *      left; numeric axis from left to bottom.
+ * Hit-testing reads the swapped pixel→data mapping via the projected
+ * `PlotLayout`, so its logical comparisons don't need changes.
+ */
+export declare class SeriesChart extends CategoricalYChart {
+    readonly _isHorizontal: boolean;
+    constructor(orientation?: "vertical" | "horizontal");
+    /**
+     * Lock the categorical axis — scrolling through category indices
+     * isn't meaningful, and the layout code assumes all categories are
+     * always present. The value axis stays freely zoomable.
+     */
+    protected getZoomConfig(): ZoomConfig;
+    _locations: CachedLocations | null;
+    _aggregates: string[];
+    _splitPrefixes: string[];
+    _series: SeriesInfo[];
+    /**
+     * Columnar bar/area record storage. Indexed by bar slot in
+     * `[0, _bars.count)`. Replaces the legacy `SeriesChartRecord[]` to
+     * avoid per-record POJO allocation on data load.
+     */
+    _bars: BarColumns;
+    /**
+     * Pre-partitioned series indices by glyph type — populated at the end
+     * of `uploadAndRender` and reused across frames. Eliminates per-glyph
+     * `chart._series.filter(...)` allocations in the render loop. Each
+     * holds the full list of that type (including hidden series); the
+     * draw paths still skip hidden via `_hiddenSeries` lookup.
+     */
+    _barSeries: SeriesInfo[];
+    _lineSeries: SeriesInfo[];
+    _scatterSeries: SeriesInfo[];
+    _areaSeries: SeriesInfo[];
+    /**
+     * Cached primary / secondary axis labels — `_series.filter().map().
+     * dedupe().join()` per axis, recomputed only on series-set change.
+     */
+    _primaryValueLabel: string;
+    _altValueLabel: string;
+    /**
+     * (seriesId * 1e9 + catIdx) → bar-record index in `_bars`. Built once
+     * per pipeline run for area-strip lookups; rebuilt on hidden-toggle
+     * is unnecessary because the index keys don't depend on hidden state.
+     */
+    _areaBarIndex: Map<number, number> | null;
+    /**
+     * Cached Y-color buffer state for `uploadBarColors` short-circuit.
+     * `_lastUploadedColors` mirrors the bytes last shipped to the GPU;
+     * `uploadBarColors` skips when the new buffer matches byte-for-byte.
+     * Reset (set to `null`) on data load or palette change.
+     */
+    _lastUploadedColors: Float32Array | null;
+    /**
+     * Cached palette + identity-keys for short-circuiting per-frame
+     * resolution. Inputs (`seriesPalette` ref, `gradientStops` ref,
+     * `series.length`) only change on data load or `restyle()`.
+     */
+    _paletteCache: [number, number, number][] | null;
+    _paletteCacheKey: {
+        seriesPalette: [number, number, number][] | null;
+        gradientStops: unknown;
+        seriesLength: number;
+    } | null;
+    /**
+     * Reusable scratch for the build pipeline — keeps the stack ladder
+     * `Float64Array(N*M)` capacity hot across data reloads. The pipeline
+     * resizes if the new build's footprint exceeds capacity.
+     */
+    _posStackScratch: Float64Array | null;
+    _negStackScratch: Float64Array | null;
+    _leftDomain: {
+        min: number;
+        max: number;
+    };
+    _rightDomain: {
+        min: number;
+        max: number;
+    } | null;
+    _hasRightAxis: boolean;
+    /**
+     * `domain_mode: "expand"` accumulators. Hold the running union of
+     * every prior build's value-axis (and, in numeric-category mode,
+     * category-axis) extent for as long as the option is active.
+     * Cleared in `resetExpandedDomain` — wired from the worker's
+     * `resetAllZooms` and from view-config mutations on the base
+     * class. `null` whenever the option is `"fit"` or the accumulator
+     * has just been cleared; the next build re-seeds.
+     */
+    _expandedLeftDomain: {
+        min: number;
+        max: number;
+    } | null;
+    _expandedRightDomain: {
+        min: number;
+        max: number;
+    } | null;
+    _expandedCategoryDomain: {
+        min: number;
+        max: number;
+    } | null;
+    /**
+     * Numeric category-axis state. Populated only when `group_by` has
+     * exactly one level and that level is `date | datetime | integer |
+     * float` (boolean → category). When set, `_bars[].xCenter` lives in
+     * real data units (not logical category indices), and the
+     * categorical-side axis renders as a numeric axis instead of the
+     * stringified-category one.
+     */
+    _categoryAxisMode: "category" | "numeric";
+    _numericCategoryDomain: NumericCategoryDomain | null;
+    /**
+     * Origin used to rebase category positions before f32 narrowing.
+     * Datetime numeric category axes carry ~1.7e12-magnitude values
+     * which f32 cannot represent below ~256ms; the GPU buffers store
+     * `(xCenter - _categoryOrigin)` and the projection matrix is built
+     * with the same origin so its `tx` term stays small. Leftover
+     * absolute coords are still available via `_numericCategoryDomain`
+     * for axis-tick formatting and `dataToPixel`. `0` in category mode
+     * (where positions are small integer indices) and in non-datetime
+     * numeric modes (integer / float categories also fit in f32).
+     */
+    _categoryOrigin: number;
+    /**
+     * Cached numeric category-axis ticks for the last frame.
+     */
+    _lastCatTicks: number[] | null;
+    /**
+     * Per-category X coordinate in real data units (numeric axis mode
+     * only). `null` in category mode — line/scatter/area glyphs fall
+     * back to using `catIdx` directly as the X coordinate.
+     */
+    _categoryPositions: Float64Array | null;
+    _hiddenSeries: Set<number>;
+    _hoveredBarIdx: number;
+    _pinnedBarIdx: number;
+    /**
+     * Synthetic bar record for hover hits on line / scatter glyphs that
+     * don't have a real `BarRecord` in `_bars`. At most one of
+     * `_hoveredBarIdx` and `_hoveredSample` is populated per frame; see
+     * {@link ./bar-interact.getHoveredBar}.
+     */
+    _hoveredSample: SeriesChartRecord | null;
+    _samples: Float32Array;
+    _sampleValid: Uint8Array;
+    /**
+     * Typed glyph composition. Each glyph (line / scatter / area) owns
+     * its program cache and persistent vertex buffers privately; the
+     * chart routes draw / rebuild / invalidate via `_glyphs`. Bar
+     * glyph state lives on the chart directly (shared bar program +
+     * `_locations` + buffer pool), so it's a free function rather than
+     * a class.
+     */
+    readonly _glyphs: {
+        readonly lines: LineGlyph;
+        readonly scatter: ScatterGlyph;
+        readonly areas: AreaGlyph;
+    };
+    _lastAltYDomain: AxisDomain | null;
+    _lastAltYTicks: number[] | null;
+    _uploadedBars: number;
+    /**
+     * Bar-record indices uploaded to the instance buffers, in dispatch
+     * order. `_uploadedBars` is the active prefix length; the trailing
+     * capacity is reused across data reloads / legend toggles.
+     */
+    _visibleBarIndices: Int32Array;
+    _legendRects: {
+        seriesId: number;
+        rect: PlotRect;
+    }[];
+    /**
+     * Cached legend layout — recomputed only on series-set / palette /
+     * hidden-set / theme change. Frame-rate redraws read from this
+     * directly; otherwise `ctx.measureText` would run per series each
+     * frame. `null` flags an invalidation; `_legendRects` is rebuilt
+     * lazily on the next chrome pass.
+     */
+    _legendCacheValid: boolean;
+    /**
+     * Per-frame memo of the auto-fit value extent keyed on the visible
+     * categorical window. Two comparisons per hit → no walk. Reset to
+     * null on any mutation that would change the outcome (data reload,
+     * legend toggle).
+     *
+     * Two axis slots because dual-axis bar charts refit left and right
+     * independently.
+     *
+     * TODO(perf): when the visible window shrinks from a large N, the
+     * linear walk over `_bars` dominates for N > ~100K. `_bars` is
+     * already ordered by `catIdx`, so a binary-search pair to find the
+     * visible slice drops this to O(log N + K_visible). Deferred until
+     * profiling shows the walk in the hot path — current scale caps
+     * keep it below 1% of frame time.
+     */
+    _autoFitCache: SeriesAutoFitCache | null;
+    /**
+     * Per-category extent buckets. Built once per data load (and
+     * rebuilt when `_hiddenSeries` changes), then read per-frame by
+     * `computeVisibleValueExtent` to compute the auto-fit window over
+     * the visible cat range in O(visibleCats) instead of
+     * O(`bars.count`). Capacity reused across builds via
+     * length-checked grow.
+     *
+     * Memory: 4 × Float64 + 2 × Uint8 = 34 bytes per category. For
+     * typical N (≤ 1000 cats) this is < 35 KB; for high-cardinality
+     * N = 100k it's 3.4 MB. Acceptable trade for eliminating the
+     * O(N×M×P) per-frame walk during pan/zoom animations.
+     */
+    _catExtents: {
+        leftMin: Float64Array;
+        leftMax: Float64Array;
+        rightMin: Float64Array;
+        rightMax: Float64Array;
+        hasLeft: Uint8Array;
+        hasRight: Uint8Array;
+        n: number;
+    } | null;
+    /**
+     * Identity of the `_hiddenSeries` set baked into `_catExtents`.
+     * Pointer-compares to detect legend-toggle invalidations.
+     */
+    _catExtentsHidden: Set<number> | null;
+    protected tooltipCallbacks(): {
+        onHover: (mx: number, my: number) => void;
+        onLeave: () => void;
+        onClickPre: (mx: number, my: number) => boolean;
+        onPin: (mx: number, my: number) => void;
+        onUnpin: () => void;
+    };
+    /**
+     * Resolve a clicked bar / point into a `PerspectiveClickDetail`
+     * (via `buildClickDetail`) and emit both
+     * `perspective-click` and `perspective-global-filter` to the host.
+     *
+     * `rowIdx` derivation: the series pipeline emits one record per
+     * (catIdx, agg, split) tuple, and a pivoted view has one view row
+     * per category — so `catIdx + _rowOffset` is the source-view row.
+     * `_aggregates[aggIdx]` is the *base* column name (no split
+     * prefix). Group-by values come from per-level `_rowPaths`, split-by
+     * values are recovered by splitting `_splitPrefixes[splitIdx]` on
+     * the `|` delimiter the engine uses for pivoted column names.
+     */
+    private _emitSeriesClickSelect;
+    uploadAndRender(glManager: WebGLContextManager, columns: ColumnDataMap, startRow: number, endRow: number): Promise<void>;
+    _fullRender(glManager: WebGLContextManager): void;
+    resetExpandedDomain(): void;
+    protected destroyInternal(): void;
+}
+/**
+ * Resolve the per-series palette and stamp it onto `_series[i].color`.
+ * Cached on `_paletteCache` keyed by reference identity of the theme
+ * inputs + series count — only `restyle()` (which clears `_paletteCache`
+ * via `invalidateTheme`) or a data load (which clears it explicitly)
+ * forces re-resolution.
+ *
+ * Returns true when the cache changed (caller invalidates color upload).
+ */
+export declare function ensurePalette(chart: SeriesChart): boolean;
+/**
+ * Horizontal bar chart — numeric X, categorical Y.
+ */
+export declare class XBarChart extends SeriesChart {
+    constructor();
+}

package/dist/esm/charts/sunburst/sunburst-interact.d.ts

@@ -0,0 +1,7 @@
+import type { SunburstChart } from "./sunburst";
+export type { BreadcrumbRegion as SunburstBreadcrumbRegion } from "../common/tree-chrome";
+export declare function handleSunburstHover(chart: SunburstChart, mx: number, my: number): void;
+export declare function handleSunburstClick(chart: SunburstChart, mx: number, my: number): void;
+export declare function showSunburstPinnedTooltip(chart: SunburstChart, nodeId: number): void;
+export declare function dismissSunburstPinnedTooltip(chart: SunburstChart): void;
+export declare function buildSunburstTooltipLines(chart: SunburstChart, nodeId: number): Promise<string[]>;

package/dist/esm/charts/sunburst/sunburst-layout.d.ts

@@ -0,0 +1,33 @@
+import type { SunburstChart } from "./sunburst";
+import { type NodeStore } from "../common/node-store";
+/**
+ * Minimum arc area (in pixels²) below which a subtree stops being
+ * subdivided. Keeps the visible count bounded independent of tree
+ * size — the core mechanism that lets sunburst scale to 2M nodes.
+ */
+declare const MIN_VISIBLE_ARC_AREA = 4;
+/**
+ * Inner radius: reserved for the current-root drill-up target.
+ */
+declare const INNER_RING_PX = 30;
+/**
+ * Recursive polar partition writing `(a0, a1, r0, r1)` into the store.
+ * The root node's own ring is reserved (inner radius = 0, outer =
+ * `INNER_RING_PX`) for the drill-up click target; descendants start at
+ * `INNER_RING_PX` and extend out.
+ */
+export declare function partitionSunburst(store: NodeStore, currentRootId: number, maxRadius: number): void;
+/**
+ * Walk from `startId` depth-first, emitting every descendant whose
+ * arc area exceeds `MIN_VISIBLE_ARC_AREA`.
+ *
+ * The single-facet entry point; faceted rendering uses
+ * {@link collectVisibleArcsAppend} to concatenate across facets.
+ */
+export declare function collectVisibleArcs(chart: SunburstChart, startId: number): void;
+/**
+ * Append visible arcs under `startId` to `_visibleNodeIds` starting at
+ * `startOffset`, returning the new length.
+ */
+export declare function collectVisibleArcsAppend(chart: SunburstChart, startId: number, startOffset: number): number;
+export { INNER_RING_PX, MIN_VISIBLE_ARC_AREA };

package/dist/esm/charts/sunburst/sunburst-render.d.ts

@@ -0,0 +1,22 @@
+import type { WebGLContextManager } from "../../webgl/context-manager";
+import type { SunburstChart } from "./sunburst";
+/**
+ * Resolve the `(centerX, centerY)` of the facet that owns `nodeId`.
+ * Walks the ancestor chain and matches against each facet's
+ * `drillRoot`; returns `chart._centerX/_centerY` in non-faceted mode
+ * or as a defensive fallback. Used by every chrome path that needs to
+ * place geometry around an arc — labels, hover highlight, hover
+ * tooltip, pinned tooltip — so all four agree on which facet owns the
+ * node. The chart-wide `_centerX/_centerY` fields are
+ * `layoutFacetedSunburst`'s legacy first-facet publication and are
+ * not safe for these calls.
+ */
+export declare function facetCenterForNode(chart: SunburstChart, nodeId: number): {
+    centerX: number;
+    centerY: number;
+};
+/**
+ * Full-frame render: layout → WebGL arcs → chrome overlay.
+ */
+export declare function renderSunburstFrame(chart: SunburstChart, glManager: WebGLContextManager): void;
+export declare function renderSunburstChromeOverlay(chart: SunburstChart): void;

package/dist/esm/charts/sunburst/sunburst.d.ts

@@ -0,0 +1,85 @@
+import type { ColumnDataMap } from "../../data/view-reader";
+import type { WebGLContextManager } from "../../webgl/context-manager";
+import { TreeChartBase } from "../common/tree-chart";
+import { type SunburstBreadcrumbRegion } from "./sunburst-interact";
+export interface SunburstLocations {
+    u_center: WebGLUniformLocation | null;
+    u_resolution: WebGLUniformLocation | null;
+    u_border_px: WebGLUniformLocation | null;
+    a_strip_t: number;
+    a_side: number;
+    a_angles: number;
+    a_radii: number;
+    a_color: number;
+}
+/**
+ * Sunburst chart. Shares tree storage + streaming pipeline + color
+ * mode with `TreeChartBase`; adds polar layout + instanced-arc WebGL
+ * rendering + drill / tooltip interactions.
+ *
+ * Internal option: `_labelRotation` — `"upright"` keeps labels on the
+ * left half flipped 180° so they read upright (d3fc behavior);
+ * `"radial"` leaves them purely tangent to the arc. Defaults to
+ * `"upright"`; toggle here if a call site wants flat radial labels.
+ */
+export declare class SunburstChart extends TreeChartBase {
+    _program: WebGLProgram | null;
+    _locations: SunburstLocations | null;
+    _stripBuffer: WebGLBuffer | null;
+    _instanceBuffer: WebGLBuffer | null;
+    _instanceCount: number;
+    /**
+     * Label orientation mode — see class docstring.
+     */
+    _labelRotation: "upright" | "radial";
+    _centerX: number;
+    _centerY: number;
+    _maxRadius: number;
+    _hoveredNodeId: number;
+    _pinnedNodeId: number;
+    _breadcrumbRegions: SunburstBreadcrumbRegion[];
+    _chromeCache: ImageBitmap | null;
+    _chromeCacheDirty: boolean;
+    /**
+     * See `TreemapChart._chromeCacheGen` — same race, same fix.
+     */
+    _chromeCacheGen: number;
+    _facetGrid: import("../../layout/facet-grid").FacetGrid | null;
+    /**
+     * Per-facet drill roots — mirrors `TreemapChart._facetDrillRoots`.
+     */
+    _facetDrillRoots: Map<string, number>;
+    /**
+     * Per-facet rendering state. `index` matches the facet grid cell;
+     * `centerX`, `centerY`, `maxRadius` are used for layout + hit test;
+     * `drillRoot` is the sub-root the facet is currently showing;
+     * `instanceStart`, `instanceCount` index into the shared GPU
+     * instance buffer for draw dispatch (these are post-skip values,
+     * rewritten by `uploadArcInstances` after zero-width arcs and the
+     * drill root are filtered out). `nodeStart`, `nodeCount` are the
+     * pre-skip range over `_visibleNodeIds` and are *not* rewritten —
+     * canvas chrome (arc-label translate origin) walks this range so
+     * each label can be placed around its own facet's center instead
+     * of the chart-wide `_centerX/_centerY` (which always point at the
+     * first facet).
+     */
+    _facets: {
+        label: string;
+        centerX: number;
+        centerY: number;
+        maxRadius: number;
+        drillRoot: number;
+        instanceStart: number;
+        instanceCount: number;
+        nodeStart: number;
+        nodeCount: number;
+    }[];
+    protected tooltipCallbacks(): {
+        onHover: (mx: number, my: number) => void;
+        onLeave: () => void;
+        onClickPre: (mx: number, my: number) => boolean;
+    };
+    uploadAndRender(glManager: WebGLContextManager, columns: ColumnDataMap, startRow: number, _endRow: number): Promise<void>;
+    _fullRender(glManager: WebGLContextManager): void;
+    protected destroyInternal(): void;
+}

package/dist/esm/charts/treemap/treemap-interact.d.ts

@@ -0,0 +1,12 @@
+import type { TreemapChart } from "./treemap";
+export declare function handleTreemapHover(chart: TreemapChart, mx: number, my: number): void;
+export declare function handleTreemapClick(chart: TreemapChart, mx: number, my: number): void;
+export declare function handleTreemapDblClick(chart: TreemapChart, mx: number, my: number): void;
+export declare function showTreemapPinnedTooltip(chart: TreemapChart, nodeId: number): void;
+export declare function dismissTreemapPinnedTooltip(chart: TreemapChart): void;
+/**
+ * Build the tooltip for `nodeId`. The node's own name path + aggregate
+ * value are derived from the tree; per-row tooltip columns come from
+ * the `leafRowIdx` → column-buffer lookup (no per-node `Map`).
+ */
+export declare function buildTreemapTooltipLines(chart: TreemapChart, nodeId: number): Promise<string[]>;

package/dist/esm/charts/treemap/treemap-layout.d.ts

@@ -0,0 +1,28 @@
+import type { TreemapChart } from "./treemap";
+import { NodeStore } from "../common/node-store";
+export type { BreadcrumbRegion } from "../common/tree-chrome";
+export declare const PADDING_OUTER = 1;
+export declare const PADDING_LABEL = 14;
+export declare const PADDING_INNER = 1;
+export { resetTreeState as resetTreemapState, processTreeChunk as processTreemapChunk, finalizeTree as finalizeTreemap, rebuildBreadcrumbs, } from "../common/tree-data";
+/**
+ * Order-preserving treemap layout. Walks the linked-list child graph
+ * and writes `x0/y0/x1/y1` in place into the node store.
+ */
+export declare function squarify(store: NodeStore, id: number, x0: number, y0: number, x1: number, y1: number, baseDepth: number, scratch: Int32Array, showBranchHeader: boolean): void;
+/**
+ * Walk from `startId` depth-first, emitting every descendant whose rect
+ * area is above `MIN_VISIBLE_AREA`. O(visible), not O(total).
+ *
+ * Faceted render paths call {@link collectVisibleAppend} once per facet
+ * and do the final `_visibleNodeCount` bookkeeping themselves; this
+ * single-facet entry point wraps that for non-split trees.
+ */
+export declare function collectVisible(chart: TreemapChart, startId: number, maxDepth: number, baseDepth: number): void;
+/**
+ * Append the visible-node IDs below `startId` into `_visibleNodeIds`
+ * starting at `startOffset`. Returns the new length. Used by faceted
+ * treemap rendering to concatenate per-facet visibility without doing
+ * a second pass.
+ */
+export declare function collectVisibleAppend(chart: TreemapChart, startId: number, maxDepth: number, baseDepth: number, startOffset: number): number;

package/dist/esm/charts/treemap/treemap-render.d.ts

@@ -0,0 +1,18 @@
+import type { WebGLContextManager } from "../../webgl/context-manager";
+import type { TreemapChart } from "./treemap";
+/**
+ * Full-frame treemap render: layout → WebGL rects → chrome overlay.
+ *
+ * When `_splitBy` is populated the top-level children of `_rootId`
+ * become facet roots; each is squarified into its own cell rect via
+ * {@link buildFacetGrid}. The visible-node list is concatenated across
+ * facets so a single vertex buffer + draw call covers the whole scene.
+ */
+export declare function renderTreemapFrame(chart: TreemapChart, glManager: WebGLContextManager): void;
+/**
+ * Render the chrome overlay. On layout changes, draws static content
+ * (labels, breadcrumbs, legend) directly and snapshots it into a cached
+ * bitmap. On hover-only updates, blits the cache and draws only the
+ * tooltip + highlight on top.
+ */
+export declare function renderTreemapChromeOverlay(chart: TreemapChart): void;

package/dist/esm/charts/treemap/treemap.d.ts

@@ -0,0 +1,74 @@
+import type { ColumnDataMap } from "../../data/view-reader";
+import type { WebGLContextManager } from "../../webgl/context-manager";
+import { TreeChartBase } from "../common/tree-chart";
+import { type BreadcrumbRegion } from "./treemap-layout";
+export interface TreemapLocations {
+    u_resolution: WebGLUniformLocation | null;
+    a_position: number;
+    a_color: number;
+}
+/**
+ * Treemap chart. Shares tree storage + streaming-pipeline + color-mode
+ * state with `TreeChartBase`; adds rectangular layout + WebGL quad
+ * rendering + drill / tooltip interactions.
+ */
+export declare class TreemapChart extends TreeChartBase {
+    _program: WebGLProgram | null;
+    _locations: TreemapLocations | null;
+    _positionBuffer: WebGLBuffer | null;
+    _colorBuffer: WebGLBuffer | null;
+    _vertexCount: number;
+    _hoveredNodeId: number;
+    _pinnedNodeId: number;
+    _breadcrumbRegions: BreadcrumbRegion[];
+    _chromeCache: ImageBitmap | null;
+    _chromeCacheDirty: boolean;
+    /**
+     * 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: number;
+    /**
+     * 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>;
+    _facetGrid: import("../../layout/facet-grid").FacetGrid | 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: boolean;
+    /**
+     * 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;
+    /**
+     * 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;
+    protected tooltipCallbacks(): {
+        onHover: (mx: number, my: number) => void;
+        onLeave: () => void;
+        onClickPre: (mx: number, my: number) => boolean;
+        onDblClick: (mx: number, my: number) => void;
+    };
+    uploadAndRender(glManager: WebGLContextManager, columns: ColumnDataMap, startRow: number, _endRow: number): Promise<void>;
+    _fullRender(glManager: WebGLContextManager): void;
+    protected destroyInternal(): void;
+}

package/dist/esm/config.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 declare const RUNTIME_MODE: "worker" | "inprocess";
+/**
+ * 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 declare const RENDER_BLIT_MODE: "direct" | "blit";
+/**
+ * Strict-mode validation for `BufferPool.upload`.
+ */
+export declare const BUFFER_POOL_STRICT: boolean;

package/dist/esm/data/lazy-row.d.ts

@@ -0,0 +1,32 @@
+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>;
+/**
+ * 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 declare class LazyRowFetcher {
+    private _view;
+    private _cache;
+    private _inFlight;
+    private readonly _maxCacheSize;
+    constructor(view: View, maxCacheSize?: number);
+    fetchRow(rowIdx: number): Promise<LazyRow>;
+    private _fetch;
+    dispose(): void;
+    get isDisposed(): boolean;
+}