@perspective-dev/viewer-charts 4.5.2 → 5.0.0

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

@@ -52,21 +52,19 @@ export declare class CandlestickChart extends CategoricalYChart {
         max: number;
     };
     /**
-     * `domain_mode: "expand"` accumulators. Hold the running union of
-     * the value-axis (and, in numeric-category mode, category-axis)
-     * extent across data loads. Cleared in `resetExpandedDomain` —
-     * wired from the worker's `resetAllZooms` and from view-config
-     * mutations on `AbstractChart`. `null` whenever the option is
-     * `"fit"` or the accumulator has just been cleared.
+     * `domain_mode: "expand"` accumulator — the VALUE (Y) axis only.
+     * The category axis has NO accumulator on band charts (see
+     * `SeriesChart._expandedLeftDomain`): a numeric/datetime `group_by`
+     * axis always fits the current data. Cleared in
+     * `resetExpandedDomain` — wired from the worker's `resetAllZooms`
+     * and from view-config mutations on `AbstractChart`. `null`
+     * whenever the option is `"fit"` or the accumulator has just been
+     * cleared.
      */
     _expandedYDomain: {
         min: number;
         max: number;
     } | null;
-    _expandedCategoryDomain: {
-        min: number;
-        max: number;
-    } | null;
     /**
      * Numeric category-axis state (single non-string group_by).
      */

package/dist/esm/charts/chart-base.d.ts

@@ -57,6 +57,22 @@ export declare abstract class AbstractChart implements ChartImplementation {
     _glManager: WebGLContextManager | null;
     _gridlineCanvas: HTMLCanvasElement | OffscreenCanvas | null;
     _chromeCanvas: HTMLCanvasElement | OffscreenCanvas | null;
+    /**
+     * 2D-canvas draw closures collected during `_fullRender` (the GL
+     * pass) and flushed by {@link _flush2D} *after* the scheduler's
+     * `awaitGpuFence`. Deferring the gridline/chrome draws past the GPU
+     * fence stops the 2D placeholder canvases from pushing a resized
+     * frame to the compositor a frame ahead of the GL present — the
+     * visible GL/2D misalignment on resize.
+     *
+     * Renderers wrap their 2D drawing in {@link _defer2D}; the closures
+     * capture the exact per-frame locals (layout, ticks, theme) so no
+     * state needs to be recomputed or replayed from cache at flush time.
+     * Reset at the start of every GL pass (see {@link requestRender} /
+     * {@link renderFrameSync}) so a `_fullRender` that throws mid-way
+     * can't leak stale closures into the next frame.
+     */
+    _deferred2D: Array<() => void>;
     /**
      * Host-supplied CSS-variable map. The host snapshots its DOM via
      * `snapshotThemeVars(el)` and ships it over the control channel;
@@ -299,6 +315,17 @@ export declare abstract class AbstractChart implements ChartImplementation {
      * (pivot / filter / sort changes can all reshuffle rows).
      */
     setView(view: View): void;
+    /**
+     * Silently dismiss any pinned tooltip (the chart's selection visual)
+     * WITHOUT emitting `perspective-global-filter` — unlike the `setView`
+     * implicit dismiss above, the HOST initiated this (its global filter
+     * bar removed the clause this selection contributed), so an unselect
+     * emit would double-mutate the host's filter set.
+     * `TooltipController.dismiss()` posts the host-side pin teardown but
+     * never fires `onUnpin` (that emit belongs to `dispatchClick`'s
+     * click-to-unpin gesture), so this is emit-free by construction.
+     */
+    deselect(): void;
     /**
      * Build the chart-specific {@link TooltipCallbacks} object — the
      * `onHover` / `onLeave` / `onClickPre` / `onPin` / `onDblClick`
@@ -382,16 +409,43 @@ export declare abstract class AbstractChart implements ChartImplementation {
      * scheduler so concurrent calls collapse to one `_fullRender` per
      * RAF and the host blitter receives one bitmap per frame. The
      * returned promise resolves after this chart's `awaitGpuFence` +
-     * `endFrame` chain — independent of other charts in the same
-     * RAF, which run their fence waits in parallel.
+     * `render2D` + `endFrame` chain — independent of other charts in the
+     * same RAF, which run their fence waits in parallel.
+     *
+     * `_fullRender` submits the GL commands and stashes the frame's 2D
+     * draws (gridlines + chrome) via {@link _defer2D}; the scheduler
+     * flushes them with {@link _flush2D} *after* the GPU fence, so the
+     * 2D canvases don't present ahead of the GL frame. The GL pass
+     * resets `_deferred2D` first so a mid-pass throw can't leak stale
+     * closures into the next frame.
      *
      * Every render-triggering caller — upload chunks, zoom / pan,
      * resize, theme invalidation, host-driven redraws — calls this.
-     * The only sanctioned bypass is `snapshotPng`, which calls
-     * `_fullRender` directly to keep the GL backbuffer intact for
+     * The only sanctioned bypass is `snapshotPng`, which uses
+     * {@link renderFrameSync} to keep the GL backbuffer intact for
      * `gl.readPixels`.
      */
     requestRender(glManager: WebGLContextManager): Promise<void>;
+    /**
+     * Queue a 2D-canvas draw (gridline or chrome) to run after the
+     * GPU fence. Called from the chart renderers in place of drawing to
+     * the gridline/chrome canvases inline during the GL pass. See
+     * {@link _deferred2D}.
+     */
+    _defer2D(fn: () => void): void;
+    /**
+     * Run and clear the queued 2D-canvas draws. Invoked by the scheduler
+     * after `awaitGpuFence` (Phase 2), and by {@link renderFrameSync}.
+     */
+    _flush2D(): void;
+    /**
+     * Synchronous full frame (GL + 2D) for the `snapshotPng` bypass,
+     * which sits outside the scheduler and needs the gridline/chrome
+     * canvases painted before it composites them. Resets the deferred
+     * queue, runs the GL pass, then flushes the 2D draws immediately
+     * (no fence split — a snapshot isn't presented to the compositor).
+     */
+    renderFrameSync(glManager: WebGLContextManager): void;
     destroy(): void;
     abstract uploadAndRender(glManager: WebGLContextManager, columns: ColumnDataMap, startRow: number, endRow: number): Promise<void>;
     abstract _fullRender(glManager: WebGLContextManager): void;

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

@@ -24,12 +24,21 @@ export interface ChartImplementation {
      */
     requestRender(glManager: WebGLContextManager): Promise<void>;
     /**
-     * The chart-specific frame builder. The scheduler wraps this with
-     * fence + `endFrame`; callers must not invoke it directly except
-     * for `snapshotPng`, which needs an intact GL backbuffer for
-     * `gl.readPixels` and so must skip the `endFrame` pair.
+     * The chart-specific GL frame builder. Submits the GL draw commands
+     * and stashes the frame's 2D-canvas draws (gridlines + chrome) for
+     * the scheduler to flush after `awaitGpuFence`. The scheduler wraps
+     * this with fence + 2D flush + `endFrame`; callers must not invoke
+     * it directly — `snapshotPng` uses {@link renderFrameSync} instead.
      */
     _fullRender(glManager: WebGLContextManager): void;
+    /**
+     * Synchronous full frame (GL + 2D) for the `snapshotPng` bypass,
+     * which sits outside the scheduler and needs the gridline/chrome
+     * canvases painted before compositing. Runs the GL pass then flushes
+     * the deferred 2D draws immediately, skipping the fence split and
+     * `endFrame` so the GL backbuffer stays intact for `gl.readPixels`.
+     */
+    renderFrameSync(glManager: WebGLContextManager): void;
     /**
      * Hand the current View to the chart so it can make on-demand
      * per-row queries (for lazy tooltip column lookups). Called on
@@ -137,6 +146,14 @@ export interface ChartImplementation {
      * hook internally.
      */
     resetExpandedDomain?(): void;
+    /**
+     * Silently clear any active selection state (pinned tooltip) WITHOUT
+     * emitting selection events. Driven from the host's `deselect`
+     * message — its global filter bar removed a clause this chart's
+     * selection contributed, so an unselect emit would double-mutate the
+     * host's filter set.
+     */
+    deselect?(): void;
     destroy(): void;
 }
 export interface FacetConfig {
@@ -193,8 +210,19 @@ export interface PluginConfig {
      * Faceting strategy when `split_by` is non-empty.
      *
      * - `"grid"` — one small-multiple sub-plot per split group.
-     * - `"overlay"` — single plot with split groups differentiated by
-     *   color. Synced into `_facetConfig.facet_mode`.
+     * - `"overlay"` — a single plot: cartesian charts differentiate
+     *   split groups by color; the categorical band pipeline (series
+     *   charts) stacks splits within each aggregate's band slot.
+     *   Synced into `_facetConfig.facet_mode`.
+     *
+     * The default differs by family via
+     * `ChartTypeConfig.plugin_field_defaults`: cartesian / density /
+     * map chart types default to `"grid"`, the series / financial
+     * band-pipeline types to `"overlay"` (their historical split
+     * rendering). Series charts REBUILD on a mode change — grid mode
+     * keys the stack ladder per split (`facetSplits` in
+     * `buildSeriesPipeline`) so each facet grows from its own
+     * baseline.
      */
     facet_mode: "grid" | "overlay";
     /**
@@ -226,15 +254,23 @@ export interface PluginConfig {
     /**
      * Domain accumulation policy across successive `View` updates.
      *
-     * - `"fit"` — every update recomputes the rendered domain (and on
-     *   cartesian charts, the X/Y range and color/size scales) from
+     * - `"fit"` — every update recomputes the affected domains from
      *   the current data extent. Can grow or shrink frame-to-frame.
-     * - `"expand"` — the rendered domain monotonically *grows*: each
+     * - `"expand"` — the affected domains monotonically *grow*: each
      *   update unions the new data extent with the previously rendered
      *   extent, so once a value is in scope it stays in scope. Reset
      *   by the "Reset Zoom" button, view-config changes (group_by /
      *   split_by / column-slot / column-type), or toggling back to
      *   `"fit"`.
+     *
+     * AXIS SCOPE differs by family: cartesian charts (X/Y Scatter,
+     * X/Y Line, Density, Maps) apply it to BOTH axes plus the
+     * color/size scales (categorical string axes opt out — slot
+     * indices are frame-local); the categorical band pipeline (series
+     * / financial) applies it to the VALUE axis only — Y for the
+     * Y-family, X for X Bar — while the category axis always fits, so
+     * a streaming numeric/datetime `group_by` axis releases departed
+     * categories instead of pinning to its history.
      */
     domain_mode: "fit" | "expand";
     /**

package/dist/esm/charts/series/glyphs/draw-areas.d.ts

@@ -22,9 +22,10 @@ export declare class AreaGlyph {
     rebuildBuffers(chart: SeriesChart, glManager: WebGLContextManager): void;
     /**
      * Bind persistent strip buffers and dispatch one TRIANGLE_STRIP per
-     * series-run. Skips hidden series.
+     * series-run. Skips hidden series. `splitFilter` (faceted frames)
+     * draws only the series whose `splitIdx` matches.
      */
-    draw(chart: SeriesChart, gl: GL, _glManager: WebGLContextManager, projLeft: Float32Array, projRight: Float32Array, opacity: number): void;
+    draw(chart: SeriesChart, gl: GL, _glManager: WebGLContextManager, projLeft: Float32Array, projRight: Float32Array, opacity: number, splitFilter?: number): void;
     destroy(chart: SeriesChart): void;
 }
 export {};

package/dist/esm/charts/series/glyphs/draw-bars.d.ts

@@ -10,6 +10,13 @@ type GL = WebGL2RenderingContext | WebGLRenderingContext;
 /**
  * Draw the bar-typed subset of `chart._bars` as instanced quads. Assumes
  * the caller has already `useProgram`'d the bar shader and set uniforms.
+ *
+ * `range` draws a contiguous instance sub-range instead of the full
+ * uploaded set — the faceted renderer uploads instances split-major
+ * (see `uploadBarInstances`) and dispatches one range per facet.
  */
-export declare function drawBars(chart: SeriesChart, gl: GL, glManager: WebGLContextManager): void;
+export declare function drawBars(chart: SeriesChart, gl: GL, glManager: WebGLContextManager, range?: {
+    start: number;
+    count: number;
+}): void;
 export {};

package/dist/esm/charts/series/glyphs/draw-lines.d.ts

@@ -33,9 +33,10 @@ export declare class LineGlyph {
      * Bind the persistent vertex buffers and dispatch one instanced draw
      * per series. Skips hidden series via `_hiddenSeries`. Gap /
      * transparency rendering is governed by `u_interp_alpha`, set per
-     * series.
+     * series. `splitFilter` (faceted frames) draws only the series
+     * whose `splitIdx` matches — one call per facet.
      */
-    draw(chart: SeriesChart, gl: GL, glManager: WebGLContextManager, projLeft: Float32Array, projRight: Float32Array): void;
+    draw(chart: SeriesChart, gl: GL, glManager: WebGLContextManager, projLeft: Float32Array, projRight: Float32Array, splitFilter?: number): void;
     destroy(chart: SeriesChart): void;
 }
 export {};

package/dist/esm/charts/series/glyphs/draw-scatter.d.ts

@@ -25,9 +25,12 @@ export declare class ScatterGlyph {
     rebuildBuffers(chart: SeriesChart, glManager: WebGLContextManager): void;
     /**
      * Bind the persistent left/right buffers and issue up to two draw
-     * calls. No per-frame allocations or buffer uploads.
+     * calls. No per-frame allocations or buffer uploads. `splitFilter`
+     * (faceted frames) instead draws each matching series' contiguous
+     * bucket sub-range — one `drawArrays(POINTS, first, count)` per
+     * series of the facet.
      */
-    draw(chart: SeriesChart, gl: GL, glManager: WebGLContextManager, projLeft: Float32Array, projRight: Float32Array): void;
+    draw(chart: SeriesChart, gl: GL, glManager: WebGLContextManager, projLeft: Float32Array, projRight: Float32Array, splitFilter?: number): void;
     destroy(chart: SeriesChart): void;
 }
 export {};

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

@@ -168,6 +168,17 @@ export interface SeriesPipelineInput {
      * variation. Maps directly to `PluginConfig.include_zero`.
      */
     includeZero: boolean;
+    /**
+     * `facet_mode: "grid"` geometry: key the stack ladder by
+     * `(catIdx, aggIdx, splitIdx)` instead of `(catIdx, aggIdx)`, so
+     * splits never stack on each other — each facet's bars / areas
+     * grow from their own zero baseline. Slot geometry (`xCenter` /
+     * `halfWidth`) is unchanged: facets separate splits by projection
+     * + scissor, not by X offset, so every split's records share the
+     * same band-slot coordinates. Value extents still accumulate
+     * across ALL splits — the facet grid renders a shared value axis.
+     */
+    facetSplits?: boolean;
     /**
      * Reusable scratch — pipeline writes records into these in place
      * and zero-fills the stack ladder. Pass the previous build's

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

@@ -11,11 +11,21 @@ export declare function getHoveredBar(chart: SeriesChart): SeriesChartRecord | n
  * Handle mouse-move across all glyph types. Tests (in reverse paint order
  * so top glyphs win): scatter points → line points → bars → areas.
  * Updates `_hoveredBarIdx` or `_hoveredSample` and re-renders on change.
+ *
+ * Faceted frames first resolve the cell under the cursor: that cell's
+ * layout supplies the pixel→data mapping and its index becomes the
+ * `splitFilter` — records of other splits share the same band-slot
+ * coordinates by construction, so an unfiltered hit-test would match
+ * a bar from a different facet.
  */
 export declare function handleBarHover(chart: SeriesChart, mx: number, my: number): void;
 /**
  * Handle a click on the legend area. Returns true when the click hit a
  * legend entry (the caller should then treat the event as consumed).
+ *
+ * An entry may own several series (facet-grid mode groups the legend
+ * by aggregate): the toggle is all-or-nothing — any visible member
+ * hides the whole group, a fully-hidden group shows every member.
  */
 export declare function handleBarLegendClick(chart: SeriesChart, mx: number, my: number): boolean;
 /**

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

@@ -1,7 +1,14 @@
 import type { WebGLContextManager } from "../../webgl/context-manager";
 import { type SeriesChart } from "./series";
+import { PlotLayout } from "../../layout/plot-layout";
 /**
  * Upload bar instance buffers from the columnar `_bars` storage.
+ *
+ * Overlay mode emits instances in `_bars` order. Facet-grid mode
+ * (`_facetActive`) emits them split-major via a counting sort so each
+ * facet's instances form a contiguous range — recorded on
+ * `chart._facetBarRanges` and drawn per facet with an instance-offset
+ * `drawBars` call.
  */
 export declare function uploadBarInstances(chart: SeriesChart, glManager: WebGLContextManager): void;
 /**
@@ -28,11 +35,20 @@ export declare function rebuildGlyphBuffers(chart: SeriesChart, glManager: WebGL
  * Full-frame render: gridlines → WebGL bars (instanced) → chrome overlay.
  */
 export declare function renderBarFrame(chart: SeriesChart, glManager: WebGLContextManager): void;
+/**
+ * Resolve the `PlotLayout` a record renders in: the record's facet
+ * cell in faceted frames, the single plot layout otherwise. Tooltip /
+ * pin positioning must map through this so faceted anchors land in the
+ * record's own cell.
+ */
+export declare function layoutForRecord(chart: SeriesChart, b: {
+    splitIdx: number;
+}): PlotLayout | null;
 /**
  * Draw axes chrome + legend + tooltip onto the overlay canvas.
  */
 export declare function renderBarChromeOverlay(chart: SeriesChart): void;
-export declare function rightAxisDataToPixel(chart: SeriesChart, x: number, y: number): {
+export declare function rightAxisDataToPixel(chart: SeriesChart, x: number, y: number, layoutOverride?: PlotLayout): {
     px: number;
     py: number;
 };

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

@@ -1,6 +1,7 @@
 import type { ColumnDataMap } from "../../data/view-reader";
 import type { WebGLContextManager } from "../../webgl/context-manager";
 import type { ZoomConfig } from "../../interaction/zoom-controller";
+import type { FacetGrid } from "../../layout/facet-grid";
 import { CategoricalYChart } from "../common/categorical-y-chart";
 import { type PlotRect } from "../../layout/plot-layout";
 import { type AxisDomain } from "../../axis/numeric-axis";
@@ -68,6 +69,35 @@ export declare class SeriesChart extends CategoricalYChart {
     _aggregates: string[];
     _splitPrefixes: string[];
     _series: SeriesInfo[];
+    /**
+     * Whether the CURRENT build's geometry was produced for facet-grid
+     * mode (`facet_mode: "grid"` with real splits). The render / hover
+     * paths branch on this — never on the live `_facetConfig` — so a
+     * `setPluginConfig` that flips `facet_mode` between a build and a
+     * redraw can't pair grid-mode rendering with overlay-built stack
+     * geometry (or vice versa). The host always follows a
+     * `plugin.restore` with an `update` → `loadAndRender`, so the flag
+     * catches up one build later.
+     */
+    _facetActive: boolean;
+    /**
+     * Facet grid of the most recent faceted frame — one cell per
+     * split group. `null` in overlay / no-split frames. Read by the
+     * chrome overlay, hover hit-test, and tooltip pin to resolve the
+     * per-facet `PlotLayout`.
+     */
+    _facetGrid: FacetGrid | null;
+    /**
+     * Per-split contiguous instance ranges in the uploaded bar
+     * buffers, indexed by `splitIdx`. Populated by
+     * `uploadBarInstances` when `_facetActive` (instances are emitted
+     * split-major); `null` in overlay mode. Each facet's draw binds
+     * the instance attributes at `start` and draws `count` instances.
+     */
+    _facetBarRanges: {
+        start: number;
+        count: number;
+    }[] | null;
     /**
      * Columnar bar/area record storage. Indexed by bar slot in
      * `[0, _bars.count)`. Replaces the legacy `SeriesChartRecord[]` to
@@ -148,8 +178,12 @@ export declare class SeriesChart extends CategoricalYChart {
     _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.
+     * every prior build's VALUE-axis extents (primary + alt) for as
+     * long as the option is active. The category axis deliberately has
+     * NO accumulator: `domain_mode` scopes to the value axis only on
+     * band charts (Y for the Y-family, X for X Bar) — a numeric or
+     * datetime `group_by` axis always fits the current data, so a
+     * streaming chart's time axis releases departed categories.
      * 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
@@ -163,10 +197,6 @@ export declare class SeriesChart extends CategoricalYChart {
         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 |
@@ -233,8 +263,14 @@ export declare class SeriesChart extends CategoricalYChart {
      * capacity is reused across data reloads / legend toggles.
      */
     _visibleBarIndices: Int32Array;
+    /**
+     * Hit-test rects for legend entries. Overlay mode: one entry per
+     * series (`seriesIds.length === 1`). Facet-grid mode: one entry
+     * per AGGREGATE, carrying every split's seriesId — a legend
+     * toggle hides/shows the aggregate across all facets at once.
+     */
     _legendRects: {
-        seriesId: number;
+        seriesIds: number[];
         rect: PlotRect;
     }[];
     /**
@@ -318,9 +354,16 @@ export declare class SeriesChart extends CategoricalYChart {
 /**
  * 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.
+ * inputs + resolved color count — only `restyle()` (which clears
+ * `_paletteCache` via `invalidateTheme`) or a data load (which clears
+ * it explicitly) forces re-resolution.
+ *
+ * Facet-grid mode colors by AGGREGATE, not by (agg × split) series:
+ * the facet is the axis of splitting, so aggregate `k` renders the
+ * same color in every facet and the legend lists aggregates once.
+ * Overlay mode keeps the per-series palette (splits are distinguished
+ * by color there). `_facetActive` only changes at build time, which
+ * clears the cache, so the stamp mode can't go stale.
  *
  * Returns true when the cache changed (caller invalidates color upload).
  */

package/dist/esm/data/view-reader.d.ts

@@ -31,5 +31,14 @@ export interface TypedArrayWindowOptions {
  * `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.
+ *
+ * `render` also receives the DELIVERED row count — the shortest
+ * column's length, which may be less than the requested `end_row`:
+ * the engine clamps the window to the view's size at fetch time, and
+ * on a fast-updating table with deletions that size can shrink after
+ * the caller's `num_rows()` round-trip. Build pipelines must iterate
+ * to THIS count, never the requested one — a typed array indexed past
+ * its length returns `undefined`, which no amount of validity-bitmap
+ * checking catches (the bitmap read is out-of-bounds too).
  */
-export declare function viewToColumnDataMap(view: View, render: (data: ColumnDataMap) => void | Promise<void>, options?: TypedArrayWindowOptions): Promise<void>;
+export declare function viewToColumnDataMap(view: View, render: (data: ColumnDataMap, numRows: number) => void | Promise<void>, options?: TypedArrayWindowOptions): Promise<void>;

package/dist/esm/event-detail.d.ts

@@ -24,5 +24,12 @@ export interface PerspectiveClickDetail {
      * `[<col>, "==", <value>]` clauses.
      */
     config: Partial<ViewConfig>;
+    /**
+     * The source panel's `slot` name in a multi-panel `<perspective-viewer>`,
+     * so the host can attribute the click to the originating panel. `undefined`
+     * for a lone, unslotted viewer. Mirrors `PerspectiveSelectDetail.panel` and
+     * the datagrid `PerspectiveClickDetail`.
+     */
+    panel?: string;
 }
 export { PerspectiveSelectDetail } from "@perspective-dev/viewer/src/ts/extensions.js";

package/dist/esm/layout/ticks.d.ts

@@ -8,6 +8,11 @@ export declare function computeNiceTicks(min: number, max: number, targetCount:
 /**
  * Format a numeric tick value for display.
  * Uses K/M/B suffixes for large numbers, fixed decimals for small.
+ *
+ * Total over any input: label formatters run inside render passes, so a
+ * non-finite value (or `undefined` smuggled in by an upstream
+ * out-of-bounds read) must degrade to a placeholder, never throw the
+ * frame away.
  */
 export declare function formatTickValue(val: number): string;
 /**