@pond-ts/charts 0.48.1 → 0.49.0

package/dist/culling.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Viewport culling (charts decimator wave, Phase 2). Before a layer strokes its
+ * data it clips to the **visible** slice of its key column, so a pan/zoom repaint
+ * costs O(visible), not O(N): a 1M-point line panned to show 800px of data draws
+ * the ~1k points under the plot, not a million.
+ *
+ * This is the "slice plumbing" the RFC pipeline (store → viewport/decimator →
+ * renderer) puts *before* the M4 decimator (Phase 3): culling narrows the input
+ * to the visible window; the decimator later collapses that window to
+ * ~plot-width buckets. Culling alone is the win that hits the failing pan metric
+ * (#256: 100k line pan 120 → 8 fps), and it lands independently of any
+ * decimation semantics — it never changes *which* pixels are drawn, only how
+ * many points are walked to draw them.
+ *
+ * **The §2.3 invariant holds by construction:** culling lives on the *draw* path
+ * only. `sampleAt` / `hitTest` / `yExtent` read the full source series (they
+ * capture `cs` directly), so a hover readout or selection never shifts when the
+ * window resizes — nothing user-facing depends on the visible slice.
+ */
+import type { ChartSeries, BandSeries } from './data.js';
+import type { Scale } from './line.js';
+/**
+ * The visible x-domain of a chart scale as an ascending `[lo, hi]` pair (epoch
+ * ms on a time / trading axis, the axis value on a value axis), or `null` when
+ * the scale exposes no numeric domain.
+ *
+ * The draw contract types `xScale` as a bare `(value) => px` function, but the
+ * runtime object is always a real d3 `scaleTime` / `scaleLinear` or a
+ * `TradingTimeScale` — all three carry `.domain()`, and the domain **is** the
+ * visible range (the container sets it to the current view). Read it through a
+ * localized, documented cast rather than widening the draw signature — the same
+ * trick {@link baselinePxFromScale} uses for the y-axis floor.
+ *
+ * Returns `null` (⇒ callers skip culling, drawing the whole series) when:
+ * - the scale has no `.domain()` — a bare `(v) => v` test stub; or
+ * - the domain isn't a numeric pair — a category {@link ScaleBand}, whose domain
+ *   is ordinal category strings (`+string` is `NaN`).
+ *
+ * A `scaleTime` domain is `[Date, Date]`; `+date` coerces to ms. The pair is
+ * returned ascending (sorted defensively) so the bisect bounds are well-ordered
+ * even under an unusual reversed domain.
+ */
+export declare function scaleDomain(xScale: Scale): [number, number] | null;
+/**
+ * The index window `[start, end)` of a **monotonically ascending** key column
+ * `x` (logical length `length`) that covers the visible range `[lo, hi]` plus
+ * `margin` points on **each** side. Pure, O(log length) — two binary searches,
+ * no allocation.
+ *
+ * The margin points are the **entry / exit** samples: the last point left of the
+ * viewport and the first point right of it, so the line segment that *crosses*
+ * each plot edge is still drawn (drop them and the line would stop at the first
+ * in-view point, leaving a visible notch at each edge under a pan). `margin = 1`
+ * is exact for a straight (linear) segment — the crossing segment's two
+ * endpoints are both present. A smoothing `curve` (monotone) computes an
+ * interior point's tangent from a wider neighbourhood, so the *entry segment*
+ * itself can differ by a sub-pixel from the un-culled render at the very edge;
+ * the visible boundary point's own tangent stays exact (its neighbours are both
+ * in the slice). Pixel-identity across the whole edge is an M4 (Phase 3)
+ * concern, not culling's.
+ *
+ * Degenerate cases fall out of the two bounds:
+ * - **Whole series visible** — `[0, length]` (the caller then skips the slice).
+ * - **Series entirely left of the view** (`hi < x[0]`) — `[length-1, length]`,
+ *   a one-point off-screen slice that strokes nothing.
+ * - **Series entirely right of the view** (`lo > x[last]`) — `[0, 1]`, likewise.
+ * - **Empty series** — `[0, 0]`.
+ */
+export declare function visiblePointWindow(x: Float64Array, length: number, lo: number, hi: number, margin?: number): [number, number];
+/**
+ * A {@link ChartSeries} clipped to the visible window of `xScale` (+`margin`
+ * points each side). Returns the **same object** untouched when the whole series
+ * is in view or the scale exposes no domain (a test stub / category axis) — so
+ * the common "everything fits" frame allocates nothing and the draw stays
+ * byte-identical to the pre-culling pass. Otherwise the returned view is a
+ * zero-copy `subarray` of the source buffers (the source is immutable by
+ * contract, so aliasing is safe).
+ *
+ * **Gap-mode neutrality.** After the pixel bisect, each boundary is walked
+ * outward past any non-finite (`NaN` gap) run until the slice's first and last
+ * samples are **finite** (or the buffer end is hit). Without this, a gap wider
+ * than `margin` straddling a plot edge would drop the finite anchor sitting
+ * >`margin` points off-screen, turning an *interior* gap into a *leading /
+ * trailing* one inside the slice — which `bridgeGaps` and `collectGapEdges` both
+ * leave broken (they only bridge gaps with a finite sample on *both* sides). The
+ * `none` / `dashed` / `step` / `fade` connector that crossed the edge would then
+ * vanish (a notch under pan). Re-including the anchor keeps the boundary gap
+ * *interior*, so every mode draws exactly as it does un-culled. Cost is one
+ * `isFinite` check per side in the common (finite-boundary) case; the walk only
+ * runs for an edge-straddling gap and is bounded by that gap's width. (The
+ * default `empty` mode breaks at gaps regardless, so it is unaffected either
+ * way — this makes the guarantee hold for *all* modes.)
+ */
+export declare function cullChartSeries(cs: ChartSeries, xScale: Scale, margin?: number): ChartSeries;
+/**
+ * A {@link BandSeries} clipped to the visible window of `xScale` — the paired
+ * `lower`/`upper` edges culled in lockstep with the shared `x` axis, so the
+ * envelope stays aligned. Same identity-preserving fast path and zero-copy
+ * `subarray` view as {@link cullChartSeries}.
+ *
+ * Unlike {@link cullChartSeries} this needs **no** finite-anchor boundary walk:
+ * a band has no gap-bridge mode (`drawBand` always breaks the fill at a gap, it
+ * never interpolates one), so a gap straddling a plot edge is a hole on both
+ * sides of the cut — there is no crossing fill to lose. The `margin` entry/exit
+ * sample is enough for a gap-free envelope that spans the edge.
+ */
+export declare function cullBandSeries(band: BandSeries, xScale: Scale, margin?: number): BandSeries;
+/**
+ * The index range `[start, end)` of **interval marks** — each spanning
+ * `[begin[i], end[i]]` on a **monotonically ascending** `begin` axis — whose span
+ * overlaps the visible `[lo, hi]`, plus `margin` marks on each side. A mark is
+ * visible iff `end[i] >= lo && begin[i] <= hi`.
+ *
+ * - **Right:** `begin[i] <= hi` ⇒ everything below `upperBound(begin, hi)`; a
+ *   mark starting past the right edge is off-screen. Exact — no bisect on `end`
+ *   needed.
+ * - **Left:** a mark with `begin[i] < lo` is still visible if its span reaches
+ *   `lo` (`end[i] >= lo`) — a wide bar crossing the left edge. `begin` bisects
+ *   the first in-range mark; from there the scan walks back while the previous
+ *   mark's `end` still reaches `lo`. For sorted non-overlapping marks (the bar /
+ *   candle / box contract) `end` is ascending, so the walk stops at the first
+ *   mark clear of the edge — typically one step.
+ *
+ * Pure, O(log length + crossing marks). `margin` (default 1) pads each side for
+ * a mark whose drawn rect is nudged by `gapPx` / `minWidth` / a pixel `offsetPx`
+ * the data-space window can't see.
+ */
+export declare function visibleSpanWindow(begin: Float64Array, end: Float64Array, length: number, lo: number, hi: number, margin?: number): [number, number];
+/**
+ * The visible `[start, end)` index range of a **point** layer (scatter) against
+ * `xScale` — a thin wrapper over {@link visiblePointWindow} that reads the scale's
+ * domain. Returns the **full** range `[0, length]` when the scale exposes no
+ * numeric domain (a bare test stub / category axis) or the series is empty, so a
+ * caller loops over everything and the draw is unchanged there.
+ *
+ * **Radius-aware widening (`padPx`).** The `margin` is in *index* space, but a
+ * point mark's **disc** has a pixel radius independent of sample spacing — so a
+ * dense scatter of fat marks can put an edge bubble's *centre* several samples
+ * off-screen while its disc still overlaps the plot edge, which a bare index
+ * margin would drop (a subtle flicker under pan — the sharp edge #499 flagged as
+ * a follow-up). Passing `padPx` widens the data window by that many **pixels** on
+ * each side — converted px→data through `xScale.invert` — before the bisect, so
+ * every mark whose disc can paint into the plot is kept. Scatter passes its max
+ * drawn radius (plus any pixel offset); interval marks ({@link visibleSpanRange})
+ * don't need it — their width *is* their x-span.
+ *
+ * The pad is skipped (the plain domain window still applies) when `padPx <= 0` or
+ * the scale carries no `invert` (a real domain-bearing runtime scale always has
+ * one; only a partial stub lacks it, and it degrades to the index window — a
+ * slightly tighter cull, never a dropped mark, since over-padding only *adds*
+ * marks). `padPx` converts as `|invert(padPx) − invert(0)|`, the data span of
+ * `padPx` pixels: exact for the linear `scaleTime`/`scaleLinear` regardless of
+ * range offset, a local estimate for a non-linear axis, and the `Math.abs` keeps
+ * it a *widening* even under a reversed scale.
+ */
+export declare function visiblePointRange(x: Float64Array, length: number, xScale: Scale, padPx?: number, margin?: number): [number, number];
+/**
+ * The visible `[start, end)` index range of an **interval** layer (bars,
+ * candles, boxes) against `xScale` — a thin wrapper over
+ * {@link visibleSpanWindow} that reads the scale's domain. Returns the **full**
+ * range `[0, length]` when the scale exposes no numeric domain or the series is
+ * empty (the draw is unchanged there — a bare stub / category axis draws all).
+ */
+export declare function visibleSpanRange(begin: Float64Array, end: Float64Array, length: number, xScale: Scale, margin?: number): [number, number];
+//# sourceMappingURL=culling.d.ts.map

package/dist/culling.js

@@ -0,0 +1,286 @@
+/**
+ * Viewport culling (charts decimator wave, Phase 2). Before a layer strokes its
+ * data it clips to the **visible** slice of its key column, so a pan/zoom repaint
+ * costs O(visible), not O(N): a 1M-point line panned to show 800px of data draws
+ * the ~1k points under the plot, not a million.
+ *
+ * This is the "slice plumbing" the RFC pipeline (store → viewport/decimator →
+ * renderer) puts *before* the M4 decimator (Phase 3): culling narrows the input
+ * to the visible window; the decimator later collapses that window to
+ * ~plot-width buckets. Culling alone is the win that hits the failing pan metric
+ * (#256: 100k line pan 120 → 8 fps), and it lands independently of any
+ * decimation semantics — it never changes *which* pixels are drawn, only how
+ * many points are walked to draw them.
+ *
+ * **The §2.3 invariant holds by construction:** culling lives on the *draw* path
+ * only. `sampleAt` / `hitTest` / `yExtent` read the full source series (they
+ * capture `cs` directly), so a hover readout or selection never shifts when the
+ * window resizes — nothing user-facing depends on the visible slice.
+ */
+/**
+ * The visible x-domain of a chart scale as an ascending `[lo, hi]` pair (epoch
+ * ms on a time / trading axis, the axis value on a value axis), or `null` when
+ * the scale exposes no numeric domain.
+ *
+ * The draw contract types `xScale` as a bare `(value) => px` function, but the
+ * runtime object is always a real d3 `scaleTime` / `scaleLinear` or a
+ * `TradingTimeScale` — all three carry `.domain()`, and the domain **is** the
+ * visible range (the container sets it to the current view). Read it through a
+ * localized, documented cast rather than widening the draw signature — the same
+ * trick {@link baselinePxFromScale} uses for the y-axis floor.
+ *
+ * Returns `null` (⇒ callers skip culling, drawing the whole series) when:
+ * - the scale has no `.domain()` — a bare `(v) => v` test stub; or
+ * - the domain isn't a numeric pair — a category {@link ScaleBand}, whose domain
+ *   is ordinal category strings (`+string` is `NaN`).
+ *
+ * A `scaleTime` domain is `[Date, Date]`; `+date` coerces to ms. The pair is
+ * returned ascending (sorted defensively) so the bisect bounds are well-ordered
+ * even under an unusual reversed domain.
+ */
+export function scaleDomain(xScale) {
+    const d = xScale.domain?.();
+    if (d === undefined || d.length < 2)
+        return null;
+    const lo = +d[0];
+    const hi = +d[d.length - 1];
+    if (!Number.isFinite(lo) || !Number.isFinite(hi))
+        return null;
+    return lo <= hi ? [lo, hi] : [hi, lo];
+}
+/** First index `i` in `x[0..n)` with `x[i] >= v` (`n` if none) — lower bound. */
+function lowerBound(x, n, v) {
+    let lo = 0;
+    let hi = n;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (x[mid] < v)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+/** First index `i` in `x[0..n)` with `x[i] > v` (`n` if none) — upper bound. */
+function upperBound(x, n, v) {
+    let lo = 0;
+    let hi = n;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (x[mid] <= v)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+/**
+ * The index window `[start, end)` of a **monotonically ascending** key column
+ * `x` (logical length `length`) that covers the visible range `[lo, hi]` plus
+ * `margin` points on **each** side. Pure, O(log length) — two binary searches,
+ * no allocation.
+ *
+ * The margin points are the **entry / exit** samples: the last point left of the
+ * viewport and the first point right of it, so the line segment that *crosses*
+ * each plot edge is still drawn (drop them and the line would stop at the first
+ * in-view point, leaving a visible notch at each edge under a pan). `margin = 1`
+ * is exact for a straight (linear) segment — the crossing segment's two
+ * endpoints are both present. A smoothing `curve` (monotone) computes an
+ * interior point's tangent from a wider neighbourhood, so the *entry segment*
+ * itself can differ by a sub-pixel from the un-culled render at the very edge;
+ * the visible boundary point's own tangent stays exact (its neighbours are both
+ * in the slice). Pixel-identity across the whole edge is an M4 (Phase 3)
+ * concern, not culling's.
+ *
+ * Degenerate cases fall out of the two bounds:
+ * - **Whole series visible** — `[0, length]` (the caller then skips the slice).
+ * - **Series entirely left of the view** (`hi < x[0]`) — `[length-1, length]`,
+ *   a one-point off-screen slice that strokes nothing.
+ * - **Series entirely right of the view** (`lo > x[last]`) — `[0, 1]`, likewise.
+ * - **Empty series** — `[0, 0]`.
+ */
+export function visiblePointWindow(x, length, lo, hi, margin = 1) {
+    if (length === 0)
+        return [0, 0];
+    const left = lowerBound(x, length, lo); // first index with x[i] >= lo
+    const right = upperBound(x, length, hi); // first index with x[i] > hi
+    const start = Math.max(0, left - margin);
+    const end = Math.min(length, right + margin);
+    return [start, end];
+}
+/**
+ * A {@link ChartSeries} clipped to the visible window of `xScale` (+`margin`
+ * points each side). Returns the **same object** untouched when the whole series
+ * is in view or the scale exposes no domain (a test stub / category axis) — so
+ * the common "everything fits" frame allocates nothing and the draw stays
+ * byte-identical to the pre-culling pass. Otherwise the returned view is a
+ * zero-copy `subarray` of the source buffers (the source is immutable by
+ * contract, so aliasing is safe).
+ *
+ * **Gap-mode neutrality.** After the pixel bisect, each boundary is walked
+ * outward past any non-finite (`NaN` gap) run until the slice's first and last
+ * samples are **finite** (or the buffer end is hit). Without this, a gap wider
+ * than `margin` straddling a plot edge would drop the finite anchor sitting
+ * >`margin` points off-screen, turning an *interior* gap into a *leading /
+ * trailing* one inside the slice — which `bridgeGaps` and `collectGapEdges` both
+ * leave broken (they only bridge gaps with a finite sample on *both* sides). The
+ * `none` / `dashed` / `step` / `fade` connector that crossed the edge would then
+ * vanish (a notch under pan). Re-including the anchor keeps the boundary gap
+ * *interior*, so every mode draws exactly as it does un-culled. Cost is one
+ * `isFinite` check per side in the common (finite-boundary) case; the walk only
+ * runs for an edge-straddling gap and is bounded by that gap's width. (The
+ * default `empty` mode breaks at gaps regardless, so it is unaffected either
+ * way — this makes the guarantee hold for *all* modes.)
+ */
+export function cullChartSeries(cs, xScale, margin = 1) {
+    if (cs.length === 0)
+        return cs;
+    const dom = scaleDomain(xScale);
+    if (dom === null)
+        return cs;
+    let [start, end] = visiblePointWindow(cs.x, cs.length, dom[0], dom[1], margin);
+    // Extend each boundary to the nearest finite y-anchor so a gap straddling the
+    // edge stays interior (see "Gap-mode neutrality" above).
+    while (start > 0 && !Number.isFinite(cs.y[start]))
+        start -= 1;
+    while (end < cs.length && !Number.isFinite(cs.y[end - 1]))
+        end += 1;
+    if (start === 0 && end === cs.length)
+        return cs; // whole series in view
+    return {
+        x: cs.x.subarray(start, end),
+        y: cs.y.subarray(start, end),
+        length: end - start,
+    };
+}
+/**
+ * A {@link BandSeries} clipped to the visible window of `xScale` — the paired
+ * `lower`/`upper` edges culled in lockstep with the shared `x` axis, so the
+ * envelope stays aligned. Same identity-preserving fast path and zero-copy
+ * `subarray` view as {@link cullChartSeries}.
+ *
+ * Unlike {@link cullChartSeries} this needs **no** finite-anchor boundary walk:
+ * a band has no gap-bridge mode (`drawBand` always breaks the fill at a gap, it
+ * never interpolates one), so a gap straddling a plot edge is a hole on both
+ * sides of the cut — there is no crossing fill to lose. The `margin` entry/exit
+ * sample is enough for a gap-free envelope that spans the edge.
+ */
+export function cullBandSeries(band, xScale, margin = 1) {
+    if (band.length === 0)
+        return band;
+    const dom = scaleDomain(xScale);
+    if (dom === null)
+        return band;
+    const [start, end] = visiblePointWindow(band.x, band.length, dom[0], dom[1], margin);
+    if (start === 0 && end === band.length)
+        return band; // whole band in view
+    return {
+        x: band.x.subarray(start, end),
+        lower: band.lower.subarray(start, end),
+        upper: band.upper.subarray(start, end),
+        length: end - start,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Index-range culling for **per-mark** layers (scatter, bars, candles, boxes).
+//
+// Unlike the line/area/band draws — which stroke one continuous path and take a
+// zero-copy `subarray` view — these layers loop over *independent* marks with
+// **index-keyed accessors** (a scatter's `colorAt(i)` / `keyAt(i)`, a bar's
+// `begin[i]` selection match). A subarray would renumber `i` and break those, so
+// the fit is instead a visible `[start, end)` **index range** the draw loop runs
+// over (`for (i = start; i < end; …)`), leaving every accessor's `i` intact and
+// the source arrays untouched (the §2.3 interaction-reads-source invariant holds
+// the same way — hit-tests still scan the full arrays).
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * The index range `[start, end)` of **interval marks** — each spanning
+ * `[begin[i], end[i]]` on a **monotonically ascending** `begin` axis — whose span
+ * overlaps the visible `[lo, hi]`, plus `margin` marks on each side. A mark is
+ * visible iff `end[i] >= lo && begin[i] <= hi`.
+ *
+ * - **Right:** `begin[i] <= hi` ⇒ everything below `upperBound(begin, hi)`; a
+ *   mark starting past the right edge is off-screen. Exact — no bisect on `end`
+ *   needed.
+ * - **Left:** a mark with `begin[i] < lo` is still visible if its span reaches
+ *   `lo` (`end[i] >= lo`) — a wide bar crossing the left edge. `begin` bisects
+ *   the first in-range mark; from there the scan walks back while the previous
+ *   mark's `end` still reaches `lo`. For sorted non-overlapping marks (the bar /
+ *   candle / box contract) `end` is ascending, so the walk stops at the first
+ *   mark clear of the edge — typically one step.
+ *
+ * Pure, O(log length + crossing marks). `margin` (default 1) pads each side for
+ * a mark whose drawn rect is nudged by `gapPx` / `minWidth` / a pixel `offsetPx`
+ * the data-space window can't see.
+ */
+export function visibleSpanWindow(begin, end, length, lo, hi, margin = 1) {
+    if (length === 0)
+        return [0, 0];
+    const right = upperBound(begin, length, hi); // first begin > hi
+    let start = lowerBound(begin, length, lo); // first begin >= lo
+    // Walk back to include earlier marks whose span still crosses into [lo, …].
+    while (start > 0 && end[start - 1] >= lo)
+        start -= 1;
+    return [Math.max(0, start - margin), Math.min(length, right + margin)];
+}
+/**
+ * The visible `[start, end)` index range of a **point** layer (scatter) against
+ * `xScale` — a thin wrapper over {@link visiblePointWindow} that reads the scale's
+ * domain. Returns the **full** range `[0, length]` when the scale exposes no
+ * numeric domain (a bare test stub / category axis) or the series is empty, so a
+ * caller loops over everything and the draw is unchanged there.
+ *
+ * **Radius-aware widening (`padPx`).** The `margin` is in *index* space, but a
+ * point mark's **disc** has a pixel radius independent of sample spacing — so a
+ * dense scatter of fat marks can put an edge bubble's *centre* several samples
+ * off-screen while its disc still overlaps the plot edge, which a bare index
+ * margin would drop (a subtle flicker under pan — the sharp edge #499 flagged as
+ * a follow-up). Passing `padPx` widens the data window by that many **pixels** on
+ * each side — converted px→data through `xScale.invert` — before the bisect, so
+ * every mark whose disc can paint into the plot is kept. Scatter passes its max
+ * drawn radius (plus any pixel offset); interval marks ({@link visibleSpanRange})
+ * don't need it — their width *is* their x-span.
+ *
+ * The pad is skipped (the plain domain window still applies) when `padPx <= 0` or
+ * the scale carries no `invert` (a real domain-bearing runtime scale always has
+ * one; only a partial stub lacks it, and it degrades to the index window — a
+ * slightly tighter cull, never a dropped mark, since over-padding only *adds*
+ * marks). `padPx` converts as `|invert(padPx) − invert(0)|`, the data span of
+ * `padPx` pixels: exact for the linear `scaleTime`/`scaleLinear` regardless of
+ * range offset, a local estimate for a non-linear axis, and the `Math.abs` keeps
+ * it a *widening* even under a reversed scale.
+ */
+export function visiblePointRange(x, length, xScale, padPx = 0, margin = 1) {
+    if (length === 0)
+        return [0, 0];
+    const dom = scaleDomain(xScale);
+    if (dom === null)
+        return [0, length];
+    let [lo, hi] = dom;
+    if (padPx > 0) {
+        const invert = xScale
+            .invert;
+        if (typeof invert === 'function') {
+            const dataPad = Math.abs(invert(padPx) - invert(0));
+            lo -= dataPad;
+            hi += dataPad;
+        }
+    }
+    return visiblePointWindow(x, length, lo, hi, margin);
+}
+/**
+ * The visible `[start, end)` index range of an **interval** layer (bars,
+ * candles, boxes) against `xScale` — a thin wrapper over
+ * {@link visibleSpanWindow} that reads the scale's domain. Returns the **full**
+ * range `[0, length]` when the scale exposes no numeric domain or the series is
+ * empty (the draw is unchanged there — a bare stub / category axis draws all).
+ */
+export function visibleSpanRange(begin, end, length, xScale, margin = 1) {
+    if (length === 0)
+        return [0, 0];
+    const dom = scaleDomain(xScale);
+    if (dom === null)
+        return [0, length];
+    return visibleSpanWindow(begin, end, length, dom[0], dom[1], margin);
+}
+//# sourceMappingURL=culling.js.map

package/dist/data.d.ts

@@ -10,7 +10,9 @@ import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
  *
  * Both arrays are length `length`. `x` is a zero-copy view of the key column's
  * `begin` buffer (immutable by contract — do not mutate); `y` is the value
- * column materialized to a `Float64Array`.
+ * column materialized to a `Float64Array`. `x` is **monotonically ascending**
+ * (a series' key column is sorted) — the draw layers and the viewport bisect
+ * (`culling.ts`) rely on it, as `sessionRuns` already does.
  */
 export interface ChartSeries {
     readonly x: Float64Array;

package/dist/decimate.d.ts

@@ -0,0 +1,193 @@
+/**
+ * M4 line decimation (charts decimator wave, Phase 3). Reduces an
+ * already-viewport-culled visible slice to a **pixel-dense** polyline that is
+ * **visually lossless** vs the full line at the current plot width + DPR, from
+ * O(devicePlotWidth) points instead of O(visible) — the win that lifts the
+ * *fully-visible* draw ceiling Phase 2 culling deliberately left in place (a
+ * dense series that fills the plot still strokes every point).
+ *
+ * **Algorithm — M4** (Jugel et al., VLDB 2014). Split the visible key range into
+ * one bucket per device pixel column; per column keep the **min**, **max**,
+ * **first**, and **last** value (the four channels of `Float64Column.binBy(…,
+ * 'minMaxFirstLast')` — the pond-side reducer math from PR #362/#363). Drawing
+ * first → min → max → last per column reproduces what the full line rasterizes
+ * there: the vertical extent (min→max) is the exact band of pixels the dense
+ * samples cover, and first/last carry the slope to the neighbouring columns. It
+ * is lossless to within a **sub-pixel AA seam** along the envelope edges — the
+ * min/max are placed at the column *centre* (their true sub-pixel x isn't carried
+ * by the value-only reducer), so the edge antialiases a fraction of a pixel
+ * differently than the full line (the e2e bounds the whole-plot difference at a
+ * low single-digit %; a broken M4 diffs a large area). An empty column (a gap
+ * with no samples) reduces to `NaN` on all four channels — the canvas
+ * sub-path-break sentinel — so a gap becomes a break for free.
+ *
+ * **Gaps (§2.2 gap-edge union).** A `binBy` bucket straddling a gap *edge* is
+ * validity-blind (min/max/first/last see only the finite samples), so it would
+ * silently bridge a gap `'empty'` must break and rob the dashed/step/fade
+ * connectors of exact edge values. {@link gapKeyEdges} folds every ≥1-column
+ * interior gap's boundaries into the bucket-edge list, so each gap reduces to its
+ * own empty (NaN) bucket and the bordering buckets carry the exact pre/post-gap
+ * values — the decimated series then feeds the *unchanged* gap-mode machinery in
+ * `drawLine` (`'none'` bridges the breaks, dashed/step/fade draw their inferred
+ * connectors from `collectGapEdges`).
+ *
+ * **Reads the frame geometry off the canvas + scale**, not the layer signature:
+ * the bucket count `W` is the backing buffer width `ctx.canvas.width` (already
+ * `plotWidthCss × DPR` — see `Canvas`), so the grid is at **device-pixel**
+ * resolution — twice the columns at 2× DPR, which keeps extremes from
+ * flat-topping (decimator assessment §2.6). The bucket **edges** are the scale's
+ * CSS-pixel range (`xScale.range()`) inverted back to key space at those `W`
+ * positions (see {@link pixelEdges}) — so each bucket is exactly one column on
+ * **any** scale, including a non-affine `TradingTimeScale`.
+ *
+ * The output is a plain {@link ChartSeries} in **key space**, so it feeds
+ * straight back into the existing `drawLine` path (which maps x through the same
+ * `xScale` and breaks its subpath on `NaN`) — decimation is a pre-pass that
+ * shrinks the point count, not a second renderer.
+ */
+import type { ChartSeries, BandSeries } from './data.js';
+import type { Scale } from './line.js';
+/**
+ * A line layer's M4-decimation control (`<LineChart decimate>`). **Default
+ * `true`** — auto-decimate once the visible slice exceeds `2 ×` the device-pixel
+ * column count. `false` disables it (always draw every visible point).
+ * `{ threshold }` overrides the samples-per-pixel factor `k` (higher ⇒
+ * decimate later). Only the honest default draw path decimates (see
+ * `drawLine`); a decimated line is visually identical, so this is a perf knob,
+ * not a rendering-style one.
+ */
+export type DecimateOption = boolean | {
+    readonly threshold?: number;
+};
+/** The device-pixel bucket count for `ctx` — the backing buffer width, i.e.
+ *  `plotWidthCss × DPR` (so buckets land at device-pixel resolution). Falls back
+ *  to `0` when there is no sized canvas (a headless test ctx), which the caller
+ *  reads as "can't decimate". */
+export declare function deviceBucketCount(ctx: CanvasRenderingContext2D): number;
+/**
+ * Whether decimating a series of `length` samples would pay off at the current
+ * frame width: `true` once `length` exceeds `k ×` the device-pixel column count
+ * (default `k = 2` — below ~2 samples per pixel the min/max buckets barely shrink
+ * the point set, so plain drawing is cheaper than the bin walk). Returns `false`
+ * when the canvas has no measurable width (a test ctx) so those draws stay
+ * full-resolution and byte-identical. Shared by the line ({@link shouldDecimate})
+ * and band decimators.
+ */
+export declare function shouldDecimateCount(length: number, ctx: CanvasRenderingContext2D, k?: number): boolean;
+/** {@link shouldDecimateCount} for a {@link ChartSeries} (the line / area case). */
+export declare function shouldDecimate(cs: ChartSeries, ctx: CanvasRenderingContext2D, k?: number): boolean;
+/**
+ * The `W + 1` pixel-column **edges** in key space — built by **inverting uniform
+ * pixel positions** through the scale (`edges[b] = invert(b/W · plotWidthCss)`),
+ * NOT by partitioning the key domain uniformly. The distinction is load-bearing:
+ * "one bucket per pixel column" means uniform in *pixel* space, which equals a
+ * uniform *key* partition only when the scale is **affine** (`scaleLinear` /
+ * `scaleTime`). A `TradingTimeScale` compresses closed-market gaps — its key→px
+ * map is piecewise-linear — so inverting pixel positions is what keeps each
+ * bucket exactly one column wide there too (else the min/max envelope would thin
+ * within a session). `invert` is monotonic, so the edges ascend; the last is the
+ * domain max (`invert(plotWidthCss)`), inclusive in `binBy`.
+ *
+ * `plotWidthCss` is the scale's CSS-pixel range width (`xScale.range()` max);
+ * `W` counts *device* columns (`plotWidthCss × DPR`), so the `W` inverted
+ * positions land at device-pixel resolution across the CSS range.
+ */
+export declare function pixelEdges(invert: (px: number) => number, plotWidthCss: number, W: number): Float64Array;
+/**
+ * Key-space bucket boundaries that isolate each **interior gap** — a `NaN` run in
+ * `y` with a finite sample on both sides — that spans at least one pixel column
+ * (`minSpan`). This is the §2.2 gap-edge union: without it a `binBy` bucket
+ * straddling a gap edge is *validity-blind* (min/max/first/last see only the
+ * finite samples), so it silently bridges a gap `'empty'` mode must break and the
+ * `dashed`/`step`/`fade` connectors lose their exact edge values. For a gap
+ * bounded by finite `x[a]` (last before) and `x[c]` (first after), with the first
+ * `NaN` at `x[a+1]`, two edges are emitted:
+ *
+ * - `x[a+1]` — so `x[a]` stays the **last** finite sample of the prior bucket
+ *   (its `last` channel = the exact pre-gap edge value); and
+ * - `x[c]` — so `x[c]` **starts** the next bucket (its `first` = the exact
+ *   post-gap edge value).
+ *
+ * The `[x[a+1], x[c])` bucket between them is then all-`NaN` → an empty bucket →
+ * the `NaN` break. Only gaps at least one pixel column wide (`x[c] − x[a] ≥
+ * minSpan`) are emitted — a sub-pixel dropout is invisible and left to the
+ * plain empty-bucket convention, which also **bounds the edge count** (disjoint
+ * gaps each ≥ `minSpan` ⇒ ≤ `W` of them ⇒ ≤ `3W` total edges). Emitted ascending
+ * (`x` is). Leading / trailing `NaN` runs are skipped (no bridge to preserve —
+ * the first/last live bucket handles the end).
+ *
+ * `minSpan` is the caller's mean per-column key width (`domainSpan / W`) — exact
+ * on an affine scale, an **approximation** on a `TradingTimeScale` (where a
+ * column's key width varies across compressed gaps). A misfire there is benign:
+ * a real ≥1px gap it skips still breaks in its fully-empty interior columns; only
+ * the ~1px gap *edges* bridge (and session-break charts gate decimation off
+ * entirely). A per-gap pixel-width measure is the follow-up if a consumer hits it.
+ */
+export declare function gapKeyEdges(cs: ChartSeries, minSpan: number): number[];
+/**
+ * Merge the pixel-column `edges` with the interior-gap boundaries `gaps` (both
+ * ascending) into one ascending, duplicate-free edge list, keeping only gap
+ * boundaries strictly inside the domain `(lo, hi)` so the pixel span isn't
+ * extended. Returns the **same** `edges` array (identity — no allocation) when
+ * `gaps` is empty, so the gapless hot path is untouched.
+ */
+export declare function mergeGapEdges(edges: Float64Array, gaps: number[], lo: number, hi: number): Float64Array;
+/**
+ * Decimate `cs` (a viewport-culled visible slice, ascending `x`) to an M4
+ * polyline for `ctx`'s current width + DPR. Returns the **same object** when
+ * decimation doesn't apply — the scale has no domain (a test stub), the canvas
+ * has no width, or the series is already sparse enough ({@link shouldDecimate})
+ * — so those frames draw full-resolution unchanged.
+ *
+ * Otherwise returns a fresh {@link ChartSeries} of up to `4·W` points: per
+ * non-empty column, four points at `[first, min, max, last]` placed at the
+ * column's left / centre / centre / right key positions (sub-pixel within the
+ * 1px column), and a single `NaN` break per empty column. The classic M4 render
+ * — the min→max vertical is the exact pixel band the dense samples cover, and
+ * first/last carry the inter-column slope.
+ *
+ * `boundaries` are trading-axis session-break instants: their keys are unioned
+ * into the bucket edges so no bucket straddles a break (which would merge two
+ * sessions' extremes). The caller's `sessionRuns` then splits the returned
+ * series into per-session subpaths at exactly those instants.
+ */
+export declare function decimateM4(cs: ChartSeries, xScale: Scale, ctx: CanvasRenderingContext2D, k?: number, boundaries?: readonly number[]): ChartSeries;
+/**
+ * Assemble the M4 polyline {@link ChartSeries} from the four binned channels.
+ * Split out (pure, no canvas / pond deps) so the point emission is unit-tested
+ * directly. Per column `b`: an empty bucket (`first[b]` non-finite ⇒ all four
+ * are) emits one `NaN` break; a live bucket emits
+ * `(left, first) (mid, min) (mid, max) (right, last)`.
+ *
+ * `breakAt` holds bucket-edge keys (session-break instants, already unioned into
+ * `edges`) at which the line must **break** rather than connect: a bucket whose
+ * left edge is in `breakAt` emits a `NaN` **before** its points. This makes a
+ * session split explicit in the geometry — clean regardless of whether the break
+ * fell exactly on a pixel edge (where otherwise the closing bucket's `last` and
+ * the opening bucket's `first` would sit at the same x and connect with a
+ * spurious vertical stub).
+ */
+export declare function m4Polyline(edges: Float64Array, mn: Float64Array, mx: Float64Array, first: Float64Array, last: Float64Array, W: number, breakAt?: ReadonlySet<number>): ChartSeries;
+/**
+ * Decimate a {@link BandSeries} (a filled variance envelope) to one sample per
+ * device-pixel column: per column the **min of `lower`** and the **max of
+ * `upper`** — the *widest* envelope the dense samples span, so a decimated band
+ * covers exactly the pixels the full band's silhouette would (decimator
+ * assessment §2.5: paired min-lower / max-upper, so the envelope can never
+ * invert — `max(upper) ≥ min(lower)` for any valid band). Returns the **same
+ * object** when decimation doesn't apply (sparse band, domainless / non-invertible
+ * scale, no canvas width).
+ *
+ * Uses the same pixel-aligned edges as the line decimator ({@link pixelEdges} —
+ * correct on non-affine scales too), binning `lower` with `'min'` and `upper`
+ * with `'max'`. An empty column (no samples) reduces to `NaN` on both edges — the
+ * `drawBand` `.defined` break. Unlike the line path this needs **no gap-edge
+ * union**: a band has no inferred-connector modes (`drawBand` always breaks the
+ * fill at a gap, never bridges), so a sub-pixel gap edge folding into a boundary
+ * bucket is invisible — there is no connector to misplace. Assumes `lower` /
+ * `upper` are finite **together** per sample (the paired-percentile shape bands
+ * are built from); a column where only one edge has finite samples would bin a
+ * band segment that no single sample carried.
+ */
+export declare function decimateBand(band: BandSeries, xScale: Scale, ctx: CanvasRenderingContext2D, k?: number): BandSeries;
+//# sourceMappingURL=decimate.d.ts.map