@perspective-dev/viewer-charts 4.3.0

package/src/ts/charts/heatmap/heatmap.ts

@@ -0,0 +1,368 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 { AbstractChart } from "../chart-base";
+import { PlotLayout } from "../../layout/plot-layout";
+import type { CategoricalLevel } from "../../axis/categorical-axis";
+import type { FacetGrid } from "../../layout/facet-grid";
+import type {
+    AxisMode,
+    NumericCategoryDomain,
+} from "../common/category-axis-resolver";
+import {
+    buildHeatmapPipeline,
+    partitionColumnsPerFacet,
+    type HeatmapCell,
+    type HeatmapPipelineResult,
+} from "./heatmap-build";
+import {
+    renderHeatmapFrame,
+    renderHeatmapChromeOverlay,
+    type HeatmapLocations,
+} from "./heatmap-render";
+import { handleHeatmapHover } from "./heatmap-interact";
+
+/**
+ * One heatmap in a facet-grid layout. Each facet corresponds to one
+ * user-selected column in the `Color` slot; its `pipeline` holds the
+ * cell data, and `layout` is the cell's `PlotLayout` from `buildFacetGrid`.
+ * `instanceStart`/`instanceCount` give the range of the packed
+ * cell/colorT buffers that belong to this facet.
+ */
+export interface HeatmapFacet {
+    label: string;
+    pipeline: HeatmapPipelineResult;
+    layout: PlotLayout;
+    instanceStart: number;
+    instanceCount: number;
+
+    /**
+     * Origins used to rebase cell positions before f32 narrowing —
+     * matches the per-axis convention in `SeriesChart._categoryOrigin`.
+     * `0` for non-numeric axes; for numeric (especially datetime) axes
+     * pinned to `xNumericDomain.min` / `yNumericDomain.min` so the
+     * shader's projection matrix can be built in rebased space.
+     */
+    xOrigin: number;
+    yOrigin: number;
+}
+
+/**
+ * Heatmap chart. `yIdx` maps 1:1 to the arrow column iteration order
+ * (after skipping `__ROW_PATH_N__` metadata). `xIdx` is the row index
+ * post-`rowOffset`.
+ *
+ * With one user column in the `Color` slot the chart renders a single
+ * heatmap filling the canvas. With more than one, each column becomes
+ * its own heatmap in a facet grid; all facets share a common color
+ * scale and a single legend.
+ */
+export class HeatmapChart extends AbstractChart {
+    _program: WebGLProgram | null = null;
+    _locations: HeatmapLocations | null = null;
+    _cornerBuffer: WebGLBuffer | null = null;
+    _gradientCache:
+        | import("../../webgl/gradient-texture").GradientTextureCache
+        | null = null;
+
+    _xLevels: CategoricalLevel[] = [];
+    _yLevels: CategoricalLevel[] = [];
+    _yColumnNames: string[] = [];
+    _numX = 0;
+    _numY = 0;
+    _rowOffset = 0;
+
+    _xAxisMode: AxisMode = { mode: "category" };
+    _yAxisMode: AxisMode = { mode: "category" };
+    _xPositions: Float64Array | null = null;
+    _yPositions: Float64Array | null = null;
+    _xNumericDomain: NumericCategoryDomain | null = null;
+    _yNumericDomain: NumericCategoryDomain | null = null;
+
+    /**
+     * Single-plot rebase origins. Datetime numeric axes carry ~1.7e12
+     * timestamps which the f32 GPU pipeline cannot resolve below
+     * ~256ms; the cell upload subtracts these and the projection
+     * matrix is built with the same values so its `tx`/`ty` terms stay
+     * small enough for f32 cancellation in the shader. `0` for
+     * categorical or numeric-non-date axes.
+     */
+    _xOrigin = 0;
+    _yOrigin = 0;
+
+    _cells: HeatmapCell[] = [];
+    _cells2D: (HeatmapCell | null)[] = [];
+    _uploadedCells = 0;
+
+    _colorMin = 0;
+    _colorMax = 1;
+    _aggName = "";
+
+    _hoveredCell: HeatmapCell | null = null;
+    _lastLayout: PlotLayout | null = null;
+
+    /**
+     * Last cursor position (canvas-CSS pixels) recorded by
+     * `handleHeatmapHover`. Used as the tooltip anchor instead of the
+     * cell center so the hover label tracks the mouse — necessary
+     * because heatmap cells can be many pixels wide and a center-anchored
+     * tooltip drifts away from the cursor.
+     */
+    _hoveredMouseX = 0;
+    _hoveredMouseY = 0;
+
+    _facets: HeatmapFacet[] = [];
+    _facetGrid: FacetGrid | null = null;
+    _hoveredFacetIdx = -1;
+
+    /**
+     * Bound accessor so the interact module can trigger a chrome redraw.
+     */
+    _renderChromeOverlay = () => renderHeatmapChromeOverlay(this);
+
+    protected override tooltipCallbacks() {
+        return {
+            onHover: (mx: number, my: number) =>
+                handleHeatmapHover(this, mx, my),
+            onLeave: () => {
+                if (this._hoveredCell) {
+                    this._hoveredCell = null;
+                    this._renderChromeOverlay();
+                }
+            },
+            onPin: (mx: number, my: number) => {
+                // Refresh the hit-test at the click coords so the pin
+                // path doesn't depend on the RAF-throttled hover state
+                // — see comment in `series.ts` `onPin`.
+                handleHeatmapHover(this, mx, my);
+                if (this._hoveredCell) {
+                    void this._emitHeatmapClickSelect(
+                        this._hoveredCell.xIdx,
+                        this._hoveredCell.yIdx,
+                    );
+                }
+            },
+            onUnpin: () => {
+                this.emitUnselect();
+            },
+        };
+    }
+
+    /**
+     * Resolve a clicked heatmap cell into a `PerspectiveClickDetail`
+     * and emit both `perspective-click` and
+     * `perspective-global-filter selected:true`. `xIdx` indexes the
+     * outer (group-by) hierarchy; `yIdx` indexes the column-side
+     * hierarchy (split-by + value-column splits). Each level is read
+     * directly from the pre-resolved `_xLevels` / `_yLevels` labels.
+     *
+     * Representative source row: `xIdx + _rowOffset` — the row in the
+     * pivoted view that owns this category. Sufficient for the
+     * `row.{col}` lookups consumers typically do; not authoritative for
+     * cells that aggregate across many source rows.
+     */
+    private async _emitHeatmapClickSelect(
+        xIdx: number,
+        yIdx: number,
+    ): Promise<void> {
+        const groupByValues: (string | null)[] = this._xLevels.map(
+            (level) => level.labels[xIdx] ?? null,
+        );
+        const splitByValues: (string | null)[] = this._yLevels
+            .slice(0, this._splitBy.length)
+            .map((level) => level.labels[yIdx] ?? null);
+
+        const colorColumn = this._columnSlots[0] ?? "";
+        await this.emitClickAndSelect({
+            rowIdx: xIdx + this._rowOffset,
+            columnName: colorColumn,
+            groupByValues,
+            splitByValues,
+        });
+    }
+
+    async uploadAndRender(
+        glManager: WebGLContextManager,
+        columns: ColumnDataMap,
+        startRow: number,
+        endRow: number,
+    ): Promise<void> {
+        this._glManager = glManager;
+
+        if (startRow !== 0) {
+            // Heatmap renders a single consolidated pass; the viewer
+            // should not chunk this but guard defensively.
+            return;
+        }
+
+        const userColumns = this._columnSlots.filter((s): s is string => !!s);
+
+        if (userColumns.length > 1) {
+            const partitions = partitionColumnsPerFacet(columns, userColumns);
+            const facets: HeatmapFacet[] = [];
+            const allCells: HeatmapCell[] = [];
+            let globalMin = Infinity;
+            let globalMax = -Infinity;
+            for (const part of partitions) {
+                const pipeline = buildHeatmapPipeline({
+                    columns: part.columns,
+                    numRows: endRow,
+                    groupBy: this._groupBy,
+                    splitBy: this._splitBy,
+                    groupByTypes: this._groupByTypes,
+                });
+                const instanceStart = allCells.length;
+
+                // Re-stamp each cell with its facet offset so the packed
+                // instance buffer can be drawn in one sweep; the facet's
+                // own `pipeline.cells` keeps its original indices for
+                // hit-testing via `cells2D`.
+                for (const c of pipeline.cells) {
+                    allCells.push({
+                        xIdx: c.xIdx,
+                        yIdx: c.yIdx,
+                        value: c.value,
+                    });
+                }
+
+                facets.push({
+                    label: part.label,
+                    pipeline,
+                    layout: new PlotLayout(1, 1, {
+                        hasXLabel: false,
+                        hasYLabel: false,
+                        hasLegend: false,
+                    }),
+                    instanceStart,
+                    instanceCount: pipeline.cells.length,
+                    xOrigin: pipeline.xNumericDomain?.min ?? 0,
+                    yOrigin: pipeline.yNumericDomain?.min ?? 0,
+                });
+                if (
+                    isFinite(pipeline.colorMin) &&
+                    pipeline.colorMin < globalMin
+                ) {
+                    globalMin = pipeline.colorMin;
+                }
+
+                if (
+                    isFinite(pipeline.colorMax) &&
+                    pipeline.colorMax > globalMax
+                ) {
+                    globalMax = pipeline.colorMax;
+                }
+            }
+
+            if (!isFinite(globalMin) || !isFinite(globalMax)) {
+                globalMin = 0;
+                globalMax = 1;
+            } else if (globalMin === globalMax) {
+                globalMax = globalMin + 1;
+            }
+
+            // Reset single-plot state so render-time dispatch on
+            // `_facets.length > 0` is unambiguous.
+            this._xLevels = [];
+            this._yLevels = [];
+            this._yColumnNames = [];
+            this._numX = 0;
+            this._numY = 0;
+            this._rowOffset = 0;
+            this._cells2D = [];
+            this._lastLayout = null;
+            this._xAxisMode = { mode: "category" };
+            this._yAxisMode = { mode: "category" };
+            this._xPositions = null;
+            this._yPositions = null;
+            this._xNumericDomain = null;
+            this._yNumericDomain = null;
+            this._xOrigin = 0;
+            this._yOrigin = 0;
+
+            this._facets = facets;
+            this._cells = allCells;
+            this._colorMin = globalMin;
+            this._colorMax = globalMax;
+            this._aggName = userColumns.join(", ");
+        } else {
+            const result = buildHeatmapPipeline({
+                columns,
+                numRows: endRow,
+                groupBy: this._groupBy,
+                splitBy: this._splitBy,
+                groupByTypes: this._groupByTypes,
+            });
+
+            this._facets = [];
+            this._facetGrid = null;
+            this._xLevels = result.xLevels;
+            this._yLevels = result.yLevels;
+            this._yColumnNames = result.yColumnNames;
+            this._numX = result.numX;
+            this._numY = result.numY;
+            this._rowOffset = result.rowOffset;
+            this._cells = result.cells;
+            this._cells2D = result.cells2D;
+            this._colorMin = result.colorMin;
+            this._colorMax = result.colorMax;
+            this._aggName = userColumns[0] ?? "Color";
+            this._xAxisMode = result.xAxisMode;
+            this._yAxisMode = result.yAxisMode;
+            this._xPositions = result.xPositions;
+            this._yPositions = result.yPositions;
+            this._xNumericDomain = result.xNumericDomain;
+            this._yNumericDomain = result.yNumericDomain;
+            this._xOrigin = result.xNumericDomain?.min ?? 0;
+            this._yOrigin = result.yNumericDomain?.min ?? 0;
+        }
+
+        await this.requestRender(glManager);
+    }
+
+    _fullRender(glManager: WebGLContextManager): void {
+        this._glManager = glManager;
+        const hasSingle = this._numX > 0 && this._numY > 0;
+        const hasFacets = this._facets.length > 0;
+        if (!hasSingle && !hasFacets) {
+            return;
+        }
+
+        renderHeatmapFrame(this, glManager);
+    }
+
+    protected destroyInternal(): void {
+        if (this._cornerBuffer && this._glManager) {
+            this._glManager.gl.deleteBuffer(this._cornerBuffer);
+        }
+
+        this._program = null;
+        this._locations = null;
+        this._cornerBuffer = null;
+        this._xLevels = [];
+        this._yLevels = [];
+        this._yColumnNames = [];
+        this._cells = [];
+        this._cells2D = [];
+        this._hoveredCell = null;
+        this._facets = [];
+        this._facetGrid = null;
+        this._hoveredFacetIdx = -1;
+        this._xAxisMode = { mode: "category" };
+        this._yAxisMode = { mode: "category" };
+        this._xPositions = null;
+        this._yPositions = null;
+        this._xNumericDomain = null;
+        this._yNumericDomain = null;
+    }
+}

package/src/ts/charts/map/map.ts

@@ -0,0 +1,201 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 { CartesianChart } from "../cartesian/cartesian";
+import { PointGlyph } from "../cartesian/glyphs/points";
+import { LineGlyph } from "../cartesian/glyphs/lines";
+import { DensityGlyph } from "../cartesian/glyphs/density";
+import type { Glyph } from "../cartesian/glyph";
+import type { WebGLContextManager } from "../../webgl/context-manager";
+import type { PlotLayout } from "../../layout/plot-layout";
+import type { Theme } from "../../theme/theme";
+import type { Canvas2D, Context2D } from "../canvas-types";
+import type { ZoomConfig } from "../../interaction/zoom-controller";
+import type { PluginConfig } from "../chart";
+import { TileLayer } from "../../map/tile-layer";
+import { tileSourceFor, type TileProviderId } from "../../map/tile-source";
+import { lonLatToMercator } from "../../map/mercator";
+import { getScaledContext } from "../../axis/canvas";
+
+/**
+ * Map-mode base for cartesian charts. Reuses the entire cartesian
+ * pipeline (build, hit-test, zoom controller, lazy tooltips, faceting,
+ * theme, gradient texture) and swaps three behaviors:
+ *
+ *  - `projectPoint(lon, lat)` Mercator-projects incoming columns so
+ *    the rest of the pipeline operates in meter-space (linear
+ *    projection matrix, screen-space splat radius, hit-test grid all
+ *    "just work").
+ *  - `_renderMode = "map"` flips the render-frame branches to skip
+ *    cartesian gridlines and axes, insert a basemap layer before the
+ *    glyph draw, and use the map-specific chrome (attribution).
+ *  - `getZoomConfig()` returns `lockAspect: true` so wheel zoom keeps
+ *    `dataPerPixel` uniform on both axes (required: Mercator
+ *    preserves angle, glyphs distort otherwise).
+ *
+ * Concrete map plugin tags (`map-scatter`, `map-line`, `map-density`)
+ * pin a glyph in their nullary constructor exactly like the cartesian
+ * convenience subclasses.
+ */
+export class MapChart extends CartesianChart {
+    override _renderMode = "map" as const;
+
+    private _tileLayer: TileLayer;
+
+    constructor(glyph: Glyph) {
+        super(glyph);
+        this._tileLayer = new TileLayer();
+        this._tileLayer.setOnTileLoad(() => {
+            // Tile arrival schedules a fresh frame through the shared
+            // render scheduler; no-ops if a frame is already pending.
+            if (this._glManager) {
+                this.requestRender(this._glManager);
+            }
+        });
+    }
+
+    override projectPoint(lon: number, lat: number): [number, number] {
+        return lonLatToMercator(lon, lat);
+    }
+
+    protected override getZoomConfig(): ZoomConfig {
+        return { lockAspect: true };
+    }
+
+    override setPluginConfig(cfg: PluginConfig): void {
+        super.setPluginConfig(cfg);
+        if (this._glManager) {
+            this._tileLayer.setSource(
+                this._glManager.gl,
+                tileSourceFor(cfg.map_tile_provider as TileProviderId),
+            );
+        }
+
+        this._tileLayer.setAlpha(cfg.map_tile_alpha);
+    }
+
+    override renderBackground(
+        glManager: WebGLContextManager,
+        layout: PlotLayout,
+        projection: Float32Array,
+        domain: { xMin: number; xMax: number; yMin: number; yMax: number },
+        xOrigin: number,
+        yOrigin: number,
+    ): void {
+        // Lazy source bind — `setPluginConfig` runs before
+        // `_glManager` is wired in some host bootstraps, so we
+        // re-attempt on first render if needed.
+        if (!this._tileLayer.source) {
+            this._tileLayer.setSource(
+                glManager.gl,
+                tileSourceFor(
+                    this._pluginConfig.map_tile_provider as TileProviderId,
+                ),
+            );
+            this._tileLayer.setAlpha(this._pluginConfig.map_tile_alpha);
+        }
+
+        this._tileLayer.render(
+            glManager,
+            layout,
+            projection,
+            domain,
+            xOrigin,
+            yOrigin,
+        );
+    }
+
+    override renderMapChrome(
+        canvas: Canvas2D | null,
+        layout: PlotLayout,
+        theme: Theme,
+        dpr: number,
+    ): void {
+        if (!canvas) {
+            return;
+        }
+
+        const ctx = getScaledContext(canvas, dpr) as Context2D | null;
+        if (!ctx) {
+            return;
+        }
+
+        const attribution = this._tileLayer.source?.attribution ?? "";
+        if (!attribution) {
+            return;
+        }
+
+        const plot = layout.plotRect;
+        ctx.save();
+        ctx.font = `10px ${theme.fontFamily}`;
+        ctx.textAlign = "right";
+        ctx.textBaseline = "bottom";
+
+        // Pill background so attribution stays legible over any tile.
+        const padding = 4;
+        const metrics = ctx.measureText(attribution);
+        const textW = metrics.width;
+        const textH = 12;
+        const x = plot.x + plot.width - 4;
+        const y = plot.y + plot.height - 4;
+        ctx.fillStyle = "rgba(255, 255, 255, 0.75)";
+        ctx.fillRect(
+            x - textW - padding * 2,
+            y - textH - padding,
+            textW + padding * 2,
+            textH + padding,
+        );
+        ctx.fillStyle = theme.labelColor;
+        ctx.fillText(attribution, x - padding, y - padding / 2);
+        ctx.restore();
+    }
+
+    protected override destroyInternal(): void {
+        if (this._glManager) {
+            this._tileLayer.destroy(this._glManager.gl);
+        }
+
+        super.destroyInternal();
+    }
+}
+
+/**
+ * Map Scatter — Mercator scatter on a raster basemap. Same glyph as
+ * `X/Y Scatter`; only projection and chrome differ.
+ */
+export class MapScatterChart extends MapChart {
+    constructor() {
+        super(new PointGlyph());
+    }
+}
+
+/**
+ * Map Line — Mercator polyline on a raster basemap. Same glyph as
+ * `X/Y Line`.
+ */
+export class MapLineChart extends MapChart {
+    constructor() {
+        super(new LineGlyph());
+    }
+}
+
+/**
+ * Map Density — Mercator KDE on a raster basemap. Same glyph as
+ * `Density`; the four `gradient_color_mode` variants
+ * (density/mean/extreme/signed) are all available on the map too
+ * because the glyph reads `_pluginConfig` directly.
+ */
+export class MapDensityChart extends MapChart {
+    constructor() {
+        super(new DensityGlyph());
+    }
+}

package/src/ts/charts/registry.ts

@@ -0,0 +1,65 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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 { ScatterChart, LineChart, DensityChart } from "./cartesian/cartesian";
+import { TreemapChart } from "./treemap/treemap";
+import { SunburstChart } from "./sunburst/sunburst";
+import { SeriesChart, XBarChart } from "./series/series";
+import { HeatmapChart } from "./heatmap/heatmap";
+import { CandlestickChart } from "./candlestick/candlestick";
+import type { ChartImplementation } from "./chart";
+
+type ChartImplCtor = new () => ChartImplementation;
+
+/**
+ * Map from `ChartTypeConfig.tag` to a factory returning the chart-impl
+ * class. Consumed by `renderer.worker.ts` which `await`s the factory
+ * before constructing the impl.
+ *
+ * Eager chart types resolve immediately — `Promise.resolve(Class)` is
+ * a microtask, no I/O. Map plugins resolve via dynamic `import()` so
+ * the bundler emits the tile-rendering subsystem and the map-mode
+ * subclasses as a separate chunk; non-map users never fetch it.
+ */
+export const CHART_IMPLS: Record<string, () => Promise<ChartImplCtor>> = {
+    scatter: async () => ScatterChart,
+    line: async () => LineChart,
+    density: async () => DensityChart,
+    treemap: async () => TreemapChart,
+    sunburst: async () => SunburstChart,
+    heatmap: async () => HeatmapChart,
+
+    // All four Y-series plugins share BarChart; they differ only in the
+    // per-plugin default `chart_type` forwarded via `setDefaultChartType`
+    // during plugin setup.
+    "y-bar": async () => SeriesChart,
+    "y-line": async () => SeriesChart,
+    "y-scatter": async () => SeriesChart,
+    "y-area": async () => SeriesChart,
+
+    // X Bar is the horizontal orientation of the same chart class.
+    "x-bar": async () => XBarChart,
+
+    // Both candlestick-family plugins share one impl; the render path
+    // branches on `_defaultChartType` (set from `default_chart_type` in
+    // the plugin config) to pick the glyph.
+    candlestick: async () => CandlestickChart,
+    ohlc: async () => CandlestickChart,
+
+    // Map plugins. Dynamic-imported so the bundler splits the
+    // `map/*` (tile fetch, cache, layer, shaders) and `charts/map/*`
+    // (MapChart + subclasses) modules into a chunk that loads only
+    // when the user activates one of these tags.
+    "map-scatter": async () => (await import("./map/map")).MapScatterChart,
+    "map-line": async () => (await import("./map/map")).MapLineChart,
+    "map-density": async () => (await import("./map/map")).MapDensityChart,
+};