@jarenjs/charts 0.46.5 → 0.56.0

package/README.md

@@ -72,12 +72,15 @@ separate `data` argument). The type-specific fields, briefly:
 
 **Time axes.** An `x: 'time'` axis (and every `candlestick`) accepts epoch milliseconds, a `Date`, or an **RFC 3339 string** — a date in a JSON document plots without being pre-converted, and a bare `2026-07-27` reads as UTC midnight. A *numeric* string still does not coerce: accepting `"5"` where the config asked for a number is a type confusion, not a date.
 
-Ticks land on calendar boundaries rather than on the 1/2/5 ladder, because a quantity axis and a clock have different nice numbers — the ladder puts ticks 50 seconds or 8.64 days apart, which no reader converts back into a time. Steps come from a clock/calendar ladder (1/5/15/30 seconds and minutes, 1/3/6/12 hours, 1/2 days, 1/2 weeks, 1/3/6 months, years), and the label granularity follows the step, so an axis never repeats one string on every tick:
+Ticks land on calendar boundaries rather than on the 1/2/5 ladder, because a quantity axis and a clock have different nice numbers — the ladder puts ticks 50 seconds or 8.64 days apart, which no reader converts back into a time. Steps come from a clock/calendar ladder (1/5/15/30 seconds and minutes, 1/3/6/12 hours, 1/2 days, 1/2 weeks, 1/3/6 months, years, then whole years on the 1/2/5 × 10^k ladder above that), each tick lands on a multiple of its own step, and the label granularity follows the step, so an axis never repeats one string on every tick:
 
 ```javascript
 axisTicksTime(Date.UTC(2024, 0, 1), Date.UTC(2027, 0, 1));  // → 2024, 2025, 2026, 2027
 axisTicksTime(Date.UTC(2026, 6, 27, 0), Date.UTC(2026, 6, 27, 6));  // → 00:00 … 06:00
+axisTicksTime(Date.UTC(1970, 0, 1), Date.UTC(5000, 0, 1));  // → 2000, 3000, 4000, 5000
 ```
+
+`axisTicksTime`, `niceTimeStep`, `axisTicksLinear` and `niceStep` are the kernel's (`@jarenjs/core/dates`, `@jarenjs/core/math`) and are re-exported here as part of this module's tick vocabulary: a timeline that is not a chart wants the same boundaries, and a second copy of either ladder would be a second set of answers.
 | `radar` | `axes: string[]`, `series: [{name, values}]`; `max` pins the domain, `labelEvery` the spoke-label stride |
 | `gauge` | `value`; `min`/`max` (0..100 default), `unit`, `tone` |
 | `boxplot` | `boxes: [{label, values}]` raw, or `{label, min, q1, med, q3, max, outliers?}` |
@@ -248,18 +251,30 @@ property-tested over thousands of random frames rather than assumed.
 
 Measured (`npm run benchmark:charts`, one appended point):
 
-| points × series | session tick | wholesale tick |
-|---|---|---|
-| 100 × 5 | ~8 µs | ~319 µs |
-| 1 000 × 5 | ~4.6 µs | ~1.03 ms |
-| 10 000 × 5 | ~4.2 µs | ~11.3 ms |
-
-The session tick is *flat* in n (10 000 points cost no more than 100)
-while the wholesale tick grows 35×. Supported types: `line` (appends
+<!--fact:charts.sessionTable-->
+| points × series | session tick | wholesale tick | frames incremental |
+|---|---:|---:|---:|
+| 100 × 5 | 6.26 µs | 301 µs | 1100 of 1100 |
+| 1,000 × 5 | 4.84 µs | 1.1 ms | 1100 of 1100 |
+| 10,000 × 5 | 4.44 µs | 8.61 ms | 1100 of 1100 |
+| 10,000 × 5 *(sampled)* | 3.25 ms | 2.53 ms | 0 of 1100 |
+<!--/fact-->
+
+The session tick is *flat* in n — it
+moves <!--fact:charts.sessionFlatness-->0.7× while the wholesale tick grows 28.6×<!--/fact-->. Supported types: `line` (appends
 and ring-buffer evictions), `bar` (live counts and sums) and
 `candlestick` (keyed kline upserts — one candle group re-renders). The
 website's Binance demo runs on it.
 
+The first three rows are lines the **sampler is not choosing the points
+of** (see below). A session over a time line above two thousand points
+rebuilds every frame by design — one appended reading can change which
+vertices the downsampler picks, anywhere on the line — and that rebuild
+costs *more* than the wholesale render it replaces, because it scans the
+extremes a second time. That is the last row, and it is the price of the
+default: a long live line declares `sampling: false`, which is exactly
+what the three rows before it are.
+
 A bar chart's stillness test is the nice-number top rather than a
 declared policy: a count below it repaints one rect, a count that
 pushes the axis higher rebuilds. A new category rebuilds too — every
@@ -279,6 +294,61 @@ does grow with the category count. It grows about 2× where the
 wholesale render grows about 4×; the line session's flatness is the
 stronger claim, and this is deliberately the weaker one.
 
+## Sampling a big line
+
+A hundred thousand readings on a line five hundred pixels wide is two
+hundred readings per column. Something has to choose, and the only
+question is whether the choosing is visible.
+
+Above **two thousand source points** a **time** line is reduced through
+`downsampleSeries` from `@jarenjs/core/series` — the same kernel a query
+and a database call, so a chart cannot disagree with the rest of the
+suite about what a gap is or where a series ends. Everything smaller,
+and every non-time line, is the AST the previous version built, point
+for point.
+
+```js
+compileChart({ type: 'line', x: 'time' }, data);                  // LTTB above 2 000
+compileChart({ type: 'line', x: 'time', sampling: false }, data); // draw every point
+compileChart({ type: 'line', x: 'time', sampling: 'minmax' }, data);
+compileChart({ type: 'line', x: 'time',
+  sampling: { method: 'lttb', target: 800 } }, data);             // an explicit budget
+```
+
+The default budget is a function of the **declared** width
+(`sampling: { width, pixelRatio }`, default 560 × 1, clamped to
+64…8 192) and never of a measured element — nothing in this package
+reads a layout, so an SSR render and a browser render of one definition
+are the same bytes. An explicit `target` fixes it outright.
+
+`ast.sampling` reports what happened: `{ method, target, sourceCount,
+renderedCount }`, or `null` when every point is drawn. What the sampled
+line still promises is the kernel's: every segment's **ends** survive,
+every run of gaps keeps a marker and is never bridged, `minmax` keeps
+the envelope exactly, and no vertex carries an instant that no reading
+had. The domain is scanned from every **source** point, so the axis
+reports the data rather than the drawing.
+
+Measured (`npm run benchmark:charts`, one series):
+
+<!--fact:charts.samplingTable-->
+| source points | drawn | method | source → AST | source → svg |
+|---:|---:|---|---:|---:|
+| 2,000 | 2,000 | none | 73.4 µs → 72.3 µs | 587 µs → 515 µs |
+| 20,000 | 560 | lttb | 838 µs → 1.28 ms | 5.84 ms → 1.05 ms |
+| 100,000 | 560 | lttb | 4.35 ms → 5.36 ms | 27.8 ms → 5.42 ms |
+<!--/fact-->
+
+Choosing the points costs about what mapping them costs — the sampler
+reads every reading either way — so the AST column is a small **loss**.
+What it buys is the render — <!--fact:charts.samplingWin-->100,000 points draw as 560 and render 5.1× faster<!--/fact-->. The invariants above are asserted in the benchmark
+before a single timing is printed.
+
+**Sampling is not retention.** `createStreamAdapter`'s `maxPoints`
+decides what *exists*; sampling decides what is *drawn*, over whatever
+exists. Changing one leaves the other untouched, and a chart can switch
+method or turn sampling off without the adapter noticing.
+
 ## Mermaid interop
 
 `@jarenjs/mermaid` delegates its `pie` diagrams here (the arrow is

package/dist/types/core/axis.d.ts

@@ -1,22 +1,16 @@
 /**
- * @file Tick generators. Linear ticks snap to a nice-number step
- * (1/2/5 × 10^k) so an axis never shows values like `12.75`; log ticks
- * are decade powers (the shape benchmark-ratio charts need, where one
- * axis spans two orders of magnitude); ordinal ticks center on their
- * band. Tick *positions* are the caller's job via the matching scale —
- * these functions return domain values only.
- */
-import { niceStep } from '@jarenjs/core/math';
-export { niceStep };
-/**
- * Linear ticks: multiples of a nice step inside `[min, max]`.
- * Degenerate domains yield a single tick.
- * @param {number} min - Domain minimum
- * @param {number} max - Domain maximum
- * @param {number} [count] - Desired tick count (approximate)
- * @returns {number[]}
- */
-export declare function axisTicksLinear(min: number, max: number, count?: number): number[];
+ * @file Tick generators. The numeric 1/2/5 × 10^k ladder and the
+ * calendar step ladder are the kernel's, so an axis never shows values
+ * like `12.75` and a timeline that is not a chart reads the same
+ * boundaries; log ticks are decade powers (the shape benchmark-ratio
+ * charts need, where one axis spans two orders of magnitude); ordinal
+ * ticks center on their band; and the tick *labels* are this module's.
+ * Tick *positions* are the caller's job via the matching scale — these
+ * functions return domain values only.
+ */
+import { niceStep, axisTicksLinear } from '@jarenjs/core/math';
+import { niceTimeStep, axisTicksTime } from '@jarenjs/core/dates';
+export { niceStep, axisTicksLinear, niceTimeStep, axisTicksTime };
 /**
  * Log ticks: the decade powers (… 0.1, 1, 10, 100 …) inside
  * `[min, max]`. When the domain sits within a single decade the
@@ -42,25 +36,6 @@ export declare function axisTicksOrdinal(categories: readonly string[]): {
  * @returns {string}
  */
 export declare function formatTickValue(v: number): string;
-/**
- * Choose the calendar step closest to covering `span` in `count` ticks.
- * @param {number} span - Domain width in milliseconds
- * @param {number} count - Desired tick count
- * @returns {[string, number]} a [unit, amount] pair
- */
-export declare function niceTimeStep(span: number, count: number): [string, number];
-/**
- * Time ticks on calendar boundaries: the first tick is the start of a
- * `[unit, amount]` step at or after `min`, and each following one is a
- * whole step later. Month and year steps land on the first of the
- * month, so a multi-year axis reads `2024 2025 2026` rather than
- * arbitrary instants.
- * @param {number} min - Domain minimum, epoch milliseconds
- * @param {number} max - Domain maximum, epoch milliseconds
- * @param {number} [count] - Desired tick count (approximate)
- * @returns {number[]} tick values in epoch milliseconds
- */
-export declare function axisTicksTime(min: number, max: number, count?: number): number[];
 /**
  * A time-axis tick label in UTC (deterministic across machines).
  *

package/dist/types/core/sampling.d.ts

@@ -0,0 +1,143 @@
+/**
+ * @file The line sampling policy: how many points a time line draws,
+ * and which ones.
+ *
+ * A hundred thousand readings on a line five hundred pixels wide is two
+ * hundred readings per column. Something has to choose, and the choice
+ * belongs in one place — `downsampleSeries` from `@jarenjs/core/series`,
+ * the same kernel a query and a database call — so a chart cannot
+ * disagree with the rest of the suite about what a gap is or where a
+ * series ends.
+ *
+ * What lives HERE is only the policy: when the sampler runs, how big
+ * its budget is, and which series it may touch at all.
+ *
+ * - **Above two thousand points, a time line samples by default.**
+ *   Below it nothing changes: the AST is the one the previous version
+ *   built, point for point.
+ * - **`sampling: false` is the opt-out**, and `'lttb'` / `'minmax'` /
+ *   `{ method, target }` are the explicit spellings. An explicit
+ *   spelling asks for the sampler whatever the count is, and on a
+ *   linear x axis as well as a time one.
+ * - **The default budget is a function of the declared width**, never
+ *   of a measured element: `width × pixelRatio`, clamped. Nothing in
+ *   this package reads a layout, so an SSR render and a browser render
+ *   of the same definition are the same bytes. A host that wants the
+ *   viewport's budget passes it (`sampling: { width, pixelRatio }`);
+ *   an explicit `target` fixes it outright.
+ *
+ * Two guards keep the sampler off a series it would misread. Its input
+ * must be ASCENDING in x — the kernel sorts, and a line whose points
+ * arrive out of order is drawn in the order it was given, so sampling
+ * an unsorted series would redraw it — and every x must be a finite
+ * instant, because a point with no place on the axis is a break in the
+ * line rather than a sample. A series failing either is mapped whole,
+ * exactly as before.
+ *
+ * This is not retention. `createStreamAdapter`'s `maxPoints` decides
+ * what EXISTS; sampling decides what is DRAWN, over whatever exists,
+ * and changing one leaves the other alone.
+ */
+/** Source points above which an omitted `sampling` starts sampling a
+ * time line. Below it the previous AST is reproduced exactly. */
+export declare const SAMPLING_THRESHOLD = 2000;
+/** The width a derived budget assumes when the caller declares none —
+ * `cartesianFrame`'s own default, so the default budget is about one
+ * point per rendered column. */
+export declare const SAMPLING_WIDTH = 560;
+/** The budget clamp. Under `MIN` a line has no shape left to read;
+ * over `MAX` there are more points than a display can separate, so the
+ * sampler would be cost without a picture. */
+export declare const SAMPLING_TARGET_MIN = 64;
+export declare const SAMPLING_TARGET_MAX = 8192;
+export type SamplingPolicy = {
+    method: 'lttb' | 'minmax';
+    /**
+     * the most points one series may draw
+     */
+    target: number;
+    /**
+     * true when `sampling` was omitted, so the
+     * policy only applies to a time line above {@link SAMPLING_THRESHOLD}
+     */
+    auto: boolean;
+};
+/**
+ * @typedef {object} SamplingPolicy
+ * @property {'lttb'|'minmax'} method
+ * @property {number} target the most points one series may draw
+ * @property {boolean} auto true when `sampling` was omitted, so the
+ *  policy only applies to a time line above {@link SAMPLING_THRESHOLD}
+ */
+/**
+ * Resolve `config.sampling` into a policy, or `null` for "never
+ * sample". Invalid spellings resolve to the default rather than
+ * throwing: a chart definition is validated against the schema when it
+ * is untrusted, and a build that threw would take a whole dashboard
+ * down for a misspelled member.
+ * @param {any} sampling the config member
+ * @returns {SamplingPolicy|null}
+ */
+export declare function normalizeSampling(sampling: any): SamplingPolicy | null;
+/**
+ * Could a series of this many source points be reduced under this
+ * policy? An OVER-approximation by design: it counts source points
+ * where {@link samplingInput} counts the ones a window still draws, so
+ * it may say yes where the build then samples nothing.
+ *
+ * The incremental session asks it, and there the safe direction is
+ * this one: a wholesale rebuild is always the right picture, while an
+ * appended vertex on a line whose points the sampler chose would be a
+ * vertex the wholesale build never selected.
+ * @param {SamplingPolicy|null} policy
+ * @param {boolean} time
+ * @param {number} count
+ * @returns {boolean}
+ */
+export declare function mightSample(policy: SamplingPolicy | null, time: boolean, count: number): boolean;
+/**
+ * The canonical samples one line series offers the sampler, or `null`
+ * when it offers none: a point with no finite x, an x that goes
+ * backwards, or nothing the policy applies to.
+ *
+ * The records are `{ at, value }` and nothing else, which is what lets
+ * `downsampleSeries` hand this very array back without copying it. A
+ * reading with no plottable y — absent, not a number, or non-positive
+ * under a log scale — is a `null` value, which is the same measured
+ * gap the kernel already refuses to draw through.
+ * @param {any[]} points
+ * @param {SamplingPolicy} policy
+ * @param {boolean} time
+ * @param {boolean} log
+ * @param {number|null} xDrop window low bound (samples below it are not drawn)
+ * @returns {{ at: number, value: number|null }[] | null}
+ */
+export declare function samplingInput(points: any[], policy: SamplingPolicy, time: boolean, log: boolean, xDrop: number | null): {
+    at: number;
+    value: number | null;
+}[] | null;
+/**
+ * Sample one series' points into unit vertices, or `null` when the
+ * policy leaves this series alone.
+ *
+ * The kernel keeps every segment's ends and one marker per run of gaps,
+ * so the drawn line still starts and ends where the data does and every
+ * hole stays a hole. Every vertex here carries a source point's own
+ * instant and reading — the sampler chooses points, it never averages
+ * them into new ones.
+ * @param {any[]} points
+ * @param {SamplingPolicy} policy
+ * @param {boolean} time
+ * @param {boolean} log
+ * @param {number|null} xDrop
+ * @param {(v:number)=>number} xScale
+ * @param {(v:number)=>number} yScale
+ * @returns {{ vertices: ({u:number,v:number}|null)[], sourceCount: number } | null}
+ */
+export declare function sampleLineSeries(points: any[], policy: SamplingPolicy, time: boolean, log: boolean, xDrop: number | null, xScale: (v: number) => number, yScale: (v: number) => number): {
+    vertices: ({
+        u: number;
+        v: number;
+    } | null)[];
+    sourceCount: number;
+} | null;

package/dist/types/index.d.ts

@@ -31,5 +31,6 @@ export { buildTreemapAST, renderTreemapAST } from './types/treemap.js';
 export { buildStreamgraphAST, renderStreamgraphAST } from './types/streamgraph.js';
 export { buildSankeyAST, renderSankeyAST } from './types/sankey.js';
 export { buildMapAST, renderMapAST } from './types/map.js';
+export { normalizeSampling, SAMPLING_THRESHOLD, SAMPLING_WIDTH, SAMPLING_TARGET_MIN, SAMPLING_TARGET_MAX, } from './core/sampling.js';
 export { createStreamAdapter } from './core/stream-adapter.js';
 export { createChartSession } from './core/session.js';

package/dist/types/types/line.d.ts

@@ -8,7 +8,14 @@
  *
  *   data   = { series: [{ name, points: [{x, y}] }] }
  *   config = { type:'line', title?, x?: 'linear'|'time', log?,
- *              markers?, xLabel?, yLabel?, domain? }
+ *              markers?, xLabel?, yLabel?, domain?, sampling? }
+ *
+ * `config.sampling` (`core/sampling.js`) decides how many of those
+ * points are drawn: above two thousand a time line is reduced through
+ * `@jarenjs/core/series`'s downsampler by default, and the AST reports
+ * what that cost under `sampling`. The domain is always scanned from
+ * every source point, so what a reader is told about the range does not
+ * depend on what fitted on the line.
  *
  * `config.domain` declares a domain-stability policy (`core/domain.js`)
  * so most streaming ticks keep the scales still: a quantized sliding
@@ -61,6 +68,16 @@ export type LineAST = {
         } | null)[];
     }[];
     markers: boolean;
+    /**
+     * what the downsampler did, or
+     * `null` when every source point is drawn
+     */
+    sampling: {
+        method: 'lttb' | 'minmax';
+        target: number;
+        sourceCount: number;
+        renderedCount: number;
+    } | null;
 };
 /**
  * @typedef {object} LineAST
@@ -72,6 +89,9 @@ export type LineAST = {
  * @property {{name: string, swatch: number}[]|null} legend
  * @property {{name: string, points: ({u:number,v:number}|null)[]}[]} series
  * @property {boolean} markers
+ * @property {{method: 'lttb'|'minmax', target: number, sourceCount: number,
+ *   renderedCount: number}|null} sampling what the downsampler did, or
+ *  `null` when every source point is drawn
  */
 /**
  * Scan the data extremes the domain resolution needs: raw x bounds

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/charts",
   "private": false,
-  "version": "0.46.5",
+  "version": "0.56.0",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -70,7 +70,7 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.46.5",
-    "@jarenjs/view": "^0.46.5"
+    "@jarenjs/core": "^0.56.0",
+    "@jarenjs/view": "^0.56.0"
   }
 }

package/schemas/chart-definition.schema.json

@@ -62,6 +62,7 @@
           "xLabel": { "type": ["string", "null"] },
           "yLabel": { "type": ["string", "null"] },
           "domain": { "$ref": "#/$defs/domainPolicy" },
+          "sampling": { "$ref": "#/$defs/samplingPolicy" },
           "series": {
             "type": "array",
             "items": { "$ref": "#/$defs/lineSeries" }
@@ -418,6 +419,30 @@
         "value": { "type": "number" }
       }
     },
+    "samplingPolicy": {
+      "description": "how many of a line's points are drawn: false never samples, a method name or object samples whatever the count, and an omitted member samples a TIME line above 2000 points through @jarenjs/core/series. Distinct from stream.maxPoints, which decides what exists rather than what is drawn.",
+      "anyOf": [
+        { "const": false },
+        { "enum": ["lttb", "minmax"] },
+        {
+          "type": "object",
+          "properties": {
+            "method": { "enum": ["lttb", "minmax"] },
+            "target": {
+              "description": "the most points one series may draw; an explicit target makes the rendered line independent of any layout",
+              "type": "integer",
+              "minimum": 2
+            },
+            "width": {
+              "description": "the width the derived target assumes, in CSS pixels (default 560)",
+              "type": "number",
+              "exclusiveMinimum": 0
+            },
+            "pixelRatio": { "type": "number", "exclusiveMinimum": 0 }
+          }
+        }
+      ]
+    },
     "domainPolicy": {
       "description": "domain-stability policy: a quantized sliding x window and/or pinned or step-quantized y bounds, so most streaming ticks keep the scales still",
       "type": "object",

package/src/core/axis.js

@@ -1,50 +1,24 @@
 //@ts-check
 /**
- * @file Tick generators. Linear ticks snap to a nice-number step
- * (1/2/5 × 10^k) so an axis never shows values like `12.75`; log ticks
- * are decade powers (the shape benchmark-ratio charts need, where one
- * axis spans two orders of magnitude); ordinal ticks center on their
- * band. Tick *positions* are the caller's job via the matching scale —
- * these functions return domain values only.
+ * @file Tick generators. The numeric 1/2/5 × 10^k ladder and the
+ * calendar step ladder are the kernel's, so an axis never shows values
+ * like `12.75` and a timeline that is not a chart reads the same
+ * boundaries; log ticks are decade powers (the shape benchmark-ratio
+ * charts need, where one axis spans two orders of magnitude); ordinal
+ * ticks center on their band; and the tick *labels* are this module's.
+ * Tick *positions* are the caller's job via the matching scale — these
+ * functions return domain values only.
  */
 
-import { Float64, niceStep } from '@jarenjs/core/math';
-import {
-  partsFromEpoch,
-  epochOfRFC3339Parts,
-  startOfParts,
-  addToParts,
-  compileDateFormat,
-} from '@jarenjs/core/dates';
+import { Float64, niceStep, axisTicksLinear } from '@jarenjs/core/math';
+import { partsFromEpoch, compileDateFormat, niceTimeStep, axisTicksTime } from '@jarenjs/core/dates';
 
-// The 1/2/5 ladder is generic numeric math, so it lives in the kernel; it is
-// re-exported here because it is part of this module's tick vocabulary.
-export { niceStep };
-
-/**
- * Linear ticks: multiples of a nice step inside `[min, max]`.
- * Degenerate domains yield a single tick.
- * @param {number} min - Domain minimum
- * @param {number} max - Domain maximum
- * @param {number} [count] - Desired tick count (approximate)
- * @returns {number[]}
- */
-export function axisTicksLinear(min, max, count = 5) {
-  if (!Number.isFinite(min) || !Number.isFinite(max))
-    return [];
-  if (min === max)
-    return [min];
-  if (min > max)
-    return axisTicksLinear(max, min, count);
-  const step = niceStep(max - min, count);
-  const decimals = Math.max(0, -Math.floor(Math.log10(step)));
-  const ticks = [];
-  const first = Math.ceil(min / step);
-  const last = Math.floor(max / step);
-  for (let i = first; i <= last; ++i)
-    ticks.push(Number((i * step).toFixed(decimals)));
-  return ticks;
-}
+// The 1/2/5 ladder and the ticks it lays down are generic numeric math, and
+// the calendar step ladder is the kernel's too — a timeline that is not a
+// chart wants the same tick positions, and a second copy of either would be
+// a second set of answers. They are re-exported here because they are part
+// of this module's tick vocabulary.
+export { niceStep, axisTicksLinear, niceTimeStep, axisTicksTime };
 
 /**
  * Log ticks: the decade powers (… 0.1, 1, 10, 100 …) inside
@@ -92,92 +66,6 @@ export function formatTickValue(v) {
   return trim(v);
 }
 
-// The steps a clock and a calendar actually have. The 1/2/5 ladder is
-// right for quantities and wrong for time: it puts ticks 50 seconds or
-// 8.64 days apart, which no reader converts back into a date. Each entry
-// is [unit, amount]; the unit names are the kernel's.
-const TIME_STEPS = Object.freeze([
-  ['second', 1], ['second', 5], ['second', 15], ['second', 30],
-  ['minute', 1], ['minute', 5], ['minute', 15], ['minute', 30],
-  ['hour', 1], ['hour', 3], ['hour', 6], ['hour', 12],
-  ['day', 1], ['day', 2], ['week', 1], ['week', 2],
-  ['month', 1], ['month', 3], ['month', 6],
-  ['year', 1],
-]);
-
-// approximate widths, used only to pick a step near the target count
-const STEP_MS = Object.freeze({
-  second: 1000, minute: 60000, hour: 3600000, day: 86400000,
-  week: 604800000, month: 2629800000, year: 31557600000,
-});
-
-/**
- * Choose the calendar step closest to covering `span` in `count` ticks.
- * @param {number} span - Domain width in milliseconds
- * @param {number} count - Desired tick count
- * @returns {[string, number]} a [unit, amount] pair
- */
-export function niceTimeStep(span, count) {
-  const target = span / Math.max(1, count);
-  let best = TIME_STEPS[0];
-  let bestErr = Infinity;
-  for (let i = 0; i < TIME_STEPS.length; i++) {
-    const [unit, amount] = TIME_STEPS[i];
-    const err = Math.abs(Math.log(STEP_MS[unit] * amount / target));
-    if (err < bestErr) {
-      bestErr = err;
-      best = TIME_STEPS[i];
-    }
-  }
-  return best;
-}
-
-/**
- * Time ticks on calendar boundaries: the first tick is the start of a
- * `[unit, amount]` step at or after `min`, and each following one is a
- * whole step later. Month and year steps land on the first of the
- * month, so a multi-year axis reads `2024 2025 2026` rather than
- * arbitrary instants.
- * @param {number} min - Domain minimum, epoch milliseconds
- * @param {number} max - Domain maximum, epoch milliseconds
- * @param {number} [count] - Desired tick count (approximate)
- * @returns {number[]} tick values in epoch milliseconds
- */
-export function axisTicksTime(min, max, count = 4) {
-  if (!Number.isFinite(min) || !Number.isFinite(max))
-    return [];
-  if (min === max)
-    return [min];
-  if (min > max)
-    return axisTicksTime(max, min, count);
-  const span = max - min;
-  // below a second the calendar has nothing to say; the numeric ladder does
-  if (span < 1000 * count)
-    return axisTicksLinear(min, max, count);
-  const [unit, amount] = niceTimeStep(span, count);
-  // snap to the step's own boundary, then advance whole steps
-  let parts = startOfParts(partsFromEpoch(min), unit === 'week' ? 'week' : unit);
-  if (unit === 'month' && amount > 1) {
-    // quarters and half-years start on month 1, 4, 7, 10 (or 1, 7)
-    const aligned = Math.floor((parts.month - 1) / amount) * amount + 1;
-    parts = { ...parts, month: aligned };
-  }
-  const ticks = [];
-  let ms = epochOfRFC3339Parts(parts);
-  if (ms < min) {
-    parts = addToParts(parts, amount, unit);
-    ms = epochOfRFC3339Parts(parts);
-  }
-  // the step is never zero, so this terminates; the cap is a guard
-  // against a pathological domain rather than an expected path
-  for (let i = 0; ms <= max && i < 1000; i++) {
-    ticks.push(ms);
-    parts = addToParts(parts, amount, unit);
-    ms = epochOfRFC3339Parts(parts);
-  }
-  return ticks;
-}
-
 // label patterns by how coarse the step is, compiled once
 const LABEL_SECOND = compileDateFormat('HH:mm:ss');
 const LABEL_MINUTE = compileDateFormat('HH:mm');

package/src/core/sampling.js

@@ -0,0 +1,206 @@
+//@ts-check
+/**
+ * @file The line sampling policy: how many points a time line draws,
+ * and which ones.
+ *
+ * A hundred thousand readings on a line five hundred pixels wide is two
+ * hundred readings per column. Something has to choose, and the choice
+ * belongs in one place — `downsampleSeries` from `@jarenjs/core/series`,
+ * the same kernel a query and a database call — so a chart cannot
+ * disagree with the rest of the suite about what a gap is or where a
+ * series ends.
+ *
+ * What lives HERE is only the policy: when the sampler runs, how big
+ * its budget is, and which series it may touch at all.
+ *
+ * - **Above two thousand points, a time line samples by default.**
+ *   Below it nothing changes: the AST is the one the previous version
+ *   built, point for point.
+ * - **`sampling: false` is the opt-out**, and `'lttb'` / `'minmax'` /
+ *   `{ method, target }` are the explicit spellings. An explicit
+ *   spelling asks for the sampler whatever the count is, and on a
+ *   linear x axis as well as a time one.
+ * - **The default budget is a function of the declared width**, never
+ *   of a measured element: `width × pixelRatio`, clamped. Nothing in
+ *   this package reads a layout, so an SSR render and a browser render
+ *   of the same definition are the same bytes. A host that wants the
+ *   viewport's budget passes it (`sampling: { width, pixelRatio }`);
+ *   an explicit `target` fixes it outright.
+ *
+ * Two guards keep the sampler off a series it would misread. Its input
+ * must be ASCENDING in x — the kernel sorts, and a line whose points
+ * arrive out of order is drawn in the order it was given, so sampling
+ * an unsorted series would redraw it — and every x must be a finite
+ * instant, because a point with no place on the axis is a break in the
+ * line rather than a sample. A series failing either is mapped whole,
+ * exactly as before.
+ *
+ * This is not retention. `createStreamAdapter`'s `maxPoints` decides
+ * what EXISTS; sampling decides what is DRAWN, over whatever exists,
+ * and changing one leaves the other alone.
+ */
+
+import { downsampleSeries } from '@jarenjs/core/series';
+import { clamp01 } from '@jarenjs/core/math';
+import { numOf } from './stream-adapter.js';
+
+/** Source points above which an omitted `sampling` starts sampling a
+ * time line. Below it the previous AST is reproduced exactly. */
+export const SAMPLING_THRESHOLD = 2000;
+
+/** The width a derived budget assumes when the caller declares none —
+ * `cartesianFrame`'s own default, so the default budget is about one
+ * point per rendered column. */
+export const SAMPLING_WIDTH = 560;
+
+/** The budget clamp. Under `MIN` a line has no shape left to read;
+ * over `MAX` there are more points than a display can separate, so the
+ * sampler would be cost without a picture. */
+export const SAMPLING_TARGET_MIN = 64;
+export const SAMPLING_TARGET_MAX = 8192;
+
+const METHODS = Object.freeze(['lttb', 'minmax']);
+
+/**
+ * @typedef {object} SamplingPolicy
+ * @property {'lttb'|'minmax'} method
+ * @property {number} target the most points one series may draw
+ * @property {boolean} auto true when `sampling` was omitted, so the
+ *  policy only applies to a time line above {@link SAMPLING_THRESHOLD}
+ */
+
+/**
+ * Resolve `config.sampling` into a policy, or `null` for "never
+ * sample". Invalid spellings resolve to the default rather than
+ * throwing: a chart definition is validated against the schema when it
+ * is untrusted, and a build that threw would take a whole dashboard
+ * down for a misspelled member.
+ * @param {any} sampling the config member
+ * @returns {SamplingPolicy|null}
+ */
+export function normalizeSampling(sampling) {
+  if (sampling === false) return null;
+  const auto = sampling === undefined || sampling === null;
+  const spec = typeof sampling === 'string' ? { method: sampling }
+    : (sampling !== null && typeof sampling === 'object' ? sampling : {});
+  const method = METHODS.includes(spec.method) ? spec.method : 'lttb';
+  return { method, target: targetOf(spec), auto };
+}
+
+/**
+ * The budget: the declared `target`, else one point per rendered
+ * column at the declared width and pixel ratio, clamped.
+ * @param {any} spec
+ * @returns {number}
+ */
+function targetOf(spec) {
+  const declared = spec.target;
+  if (Number.isInteger(declared) && declared >= 2)
+    return Math.min(SAMPLING_TARGET_MAX, declared);
+  const width = Number.isFinite(spec.width) && spec.width > 0 ? spec.width : SAMPLING_WIDTH;
+  const ratio = Number.isFinite(spec.pixelRatio) && spec.pixelRatio > 0 ? spec.pixelRatio : 1;
+  return Math.min(SAMPLING_TARGET_MAX,
+    Math.max(SAMPLING_TARGET_MIN, Math.round(width * ratio)));
+}
+
+/**
+ * Could a series of this many source points be reduced under this
+ * policy? An OVER-approximation by design: it counts source points
+ * where {@link samplingInput} counts the ones a window still draws, so
+ * it may say yes where the build then samples nothing.
+ *
+ * The incremental session asks it, and there the safe direction is
+ * this one: a wholesale rebuild is always the right picture, while an
+ * appended vertex on a line whose points the sampler chose would be a
+ * vertex the wholesale build never selected.
+ * @param {SamplingPolicy|null} policy
+ * @param {boolean} time
+ * @param {number} count
+ * @returns {boolean}
+ */
+export function mightSample(policy, time, count) {
+  if (policy === null) return false;
+  if (policy.auto && (!time || count <= SAMPLING_THRESHOLD)) return false;
+  return count > policy.target;
+}
+
+/**
+ * The canonical samples one line series offers the sampler, or `null`
+ * when it offers none: a point with no finite x, an x that goes
+ * backwards, or nothing the policy applies to.
+ *
+ * The records are `{ at, value }` and nothing else, which is what lets
+ * `downsampleSeries` hand this very array back without copying it. A
+ * reading with no plottable y — absent, not a number, or non-positive
+ * under a log scale — is a `null` value, which is the same measured
+ * gap the kernel already refuses to draw through.
+ * @param {any[]} points
+ * @param {SamplingPolicy} policy
+ * @param {boolean} time
+ * @param {boolean} log
+ * @param {number|null} xDrop window low bound (samples below it are not drawn)
+ * @returns {{ at: number, value: number|null }[] | null}
+ */
+export function samplingInput(points, policy, time, log, xDrop) {
+  if (policy.auto && !time) return null;
+  // decide before allocating: a window can only REMOVE points, so the
+  // source length bounds the sampler's input, and a series too short to
+  // reduce must cost a line under two thousand points nothing at all
+  if (policy.auto && points.length <= SAMPLING_THRESHOLD) return null;
+  if (points.length <= policy.target) return null;
+  /** @type {any[]} */
+  const out = [];
+  let previous = -Infinity;
+  for (const p of points) {
+    const px = numOf(p?.x);
+    if (!Number.isFinite(px) || px < previous) return null;
+    previous = px;
+    if (xDrop !== null && px < xDrop) continue;
+    const py = numOf(p?.y);
+    const plottable = Number.isFinite(py) && (!log || py > 0);
+    out.push({ at: px, value: plottable ? py : null });
+  }
+  if (policy.auto && out.length <= SAMPLING_THRESHOLD) return null;
+  if (out.length <= policy.target) return null;
+  return out;
+}
+
+/**
+ * Sample one series' points into unit vertices, or `null` when the
+ * policy leaves this series alone.
+ *
+ * The kernel keeps every segment's ends and one marker per run of gaps,
+ * so the drawn line still starts and ends where the data does and every
+ * hole stays a hole. Every vertex here carries a source point's own
+ * instant and reading — the sampler chooses points, it never averages
+ * them into new ones.
+ * @param {any[]} points
+ * @param {SamplingPolicy} policy
+ * @param {boolean} time
+ * @param {boolean} log
+ * @param {number|null} xDrop
+ * @param {(v:number)=>number} xScale
+ * @param {(v:number)=>number} yScale
+ * @returns {{ vertices: ({u:number,v:number}|null)[], sourceCount: number } | null}
+ */
+export function sampleLineSeries(points, policy, time, log, xDrop, xScale, yScale) {
+  const input = samplingInput(points, policy, time, log, xDrop);
+  if (input === null) return null;
+  let kept;
+  try {
+    kept = downsampleSeries(input, { target: policy.target, method: policy.method });
+  }
+  catch {
+    // the one refusal a policy can provoke: a target too small to hold
+    // this series' segment ends and gap markers. Drawing every point is
+    // the honest answer — the kernel would rather refuse than lie, and
+    // the chart would rather be slow than wrong.
+    return null;
+  }
+  const vertices = kept.points.map((sample) => {
+    if (sample.value === null) return null;
+    const v = yScale(sample.value);
+    return Number.isFinite(v) ? { u: xScale(sample.at), v: clamp01(v) } : null;
+  });
+  return { vertices, sourceCount: points.length };
+}

package/src/index.js

@@ -36,5 +36,9 @@ export { buildTreemapAST, renderTreemapAST } from './types/treemap.js';
 export { buildStreamgraphAST, renderStreamgraphAST } from './types/streamgraph.js';
 export { buildSankeyAST, renderSankeyAST } from './types/sankey.js';
 export { buildMapAST, renderMapAST } from './types/map.js';
+export {
+  normalizeSampling, SAMPLING_THRESHOLD, SAMPLING_WIDTH,
+  SAMPLING_TARGET_MIN, SAMPLING_TARGET_MAX,
+} from './core/sampling.js';
 export { createStreamAdapter } from './core/stream-adapter.js';
 export { createChartSession } from './core/session.js';

package/src/types/line.js

@@ -9,7 +9,14 @@
  *
  *   data   = { series: [{ name, points: [{x, y}] }] }
  *   config = { type:'line', title?, x?: 'linear'|'time', log?,
- *              markers?, xLabel?, yLabel?, domain? }
+ *              markers?, xLabel?, yLabel?, domain?, sampling? }
+ *
+ * `config.sampling` (`core/sampling.js`) decides how many of those
+ * points are drawn: above two thousand a time line is reduced through
+ * `@jarenjs/core/series`'s downsampler by default, and the AST reports
+ * what that cost under `sampling`. The domain is always scanned from
+ * every source point, so what a reader is told about the range does not
+ * depend on what fitted on the line.
  *
  * `config.domain` declares a domain-stability policy (`core/domain.js`)
  * so most streaming ticks keep the scales still: a quantized sliding
@@ -41,6 +48,7 @@ import {
 } from '../core/domain.js';
 import { CATEGORICAL, seriesColor } from '../core/palette.js';
 import { normalizeTooltip, markProps } from '../core/marks.js';
+import { normalizeSampling, sampleLineSeries } from '../core/sampling.js';
 
 /**
  * @typedef {object} LineAST
@@ -52,6 +60,9 @@ import { normalizeTooltip, markProps } from '../core/marks.js';
  * @property {{name: string, swatch: number}[]|null} legend
  * @property {{name: string, points: ({u:number,v:number}|null)[]}[]} series
  * @property {boolean} markers
+ * @property {{method: 'lttb'|'minmax', target: number, sourceCount: number,
+ *   renderedCount: number}|null} sampling what the downsampler did, or
+ *  `null` when every source point is drawn
  */
 
 /**
@@ -203,10 +214,24 @@ export function buildLineAST(data, config = {}) {
   const domains = resolveLineDomains(scanLineExtremes(input, policy, log), policy, time, log);
   const { xScale, yScale } = lineScales(domains, time, log);
 
-  const series = input.map((s) => ({
-    name: String(s.name ?? ''),
-    points: s.points.map((p) => lineVertex(p, domains.xDrop, xScale, yScale)),
-  }));
+  // Sampling chooses which points are DRAWN; it never moves a domain,
+  // which is scanned from every source point above. A series the policy
+  // leaves alone is mapped exactly as it always was.
+  const sampler = normalizeSampling(config.sampling);
+  let sourceCount = 0;
+  let renderedCount = 0;
+  let reduced = false;
+  const series = input.map((s) => {
+    sourceCount += s.points.length;
+    const sampled = sampler === null ? null
+      : sampleLineSeries(s.points, sampler, time, log, domains.xDrop, xScale, yScale);
+    const points = sampled === null
+      ? s.points.map((p) => lineVertex(p, domains.xDrop, xScale, yScale))
+      : sampled.vertices;
+    if (sampled !== null) reduced = true;
+    renderedCount += points.length;
+    return { name: String(s.name ?? ''), points };
+  });
 
   return {
     type: 'line',
@@ -226,6 +251,9 @@ export function buildLineAST(data, config = {}) {
     legend: series.length > 1 ? series.map((s, i) => ({ name: s.name, swatch: i })) : null,
     series,
     markers: config.markers === true,
+    sampling: !reduced || sampler === null ? null : {
+      method: sampler.method, target: sampler.target, sourceCount, renderedCount,
+    },
   };
 }