inkplot 0.0.0-stage → 1.0.0-beta.1

package/dist/stats.js

@@ -0,0 +1,159 @@
+/**
+ * Statistics as a data transform: samples in, the numbers that summarise them out.
+ *
+ *   <DomainSeries>
+ *     <BoxStats><ObjectDataSource source={samples} domain="group" value="x" /></BoxStats>
+ *     <BoxPath />
+ *   </DomainSeries>
+ *
+ * `BoxStats` sits between a series and a source whose points are samples: the domain says which group a sample belongs to
+ * (samples with the same domain are one group) and the value is the measurement. Its output has a point for each group, at the
+ * group's domain, with the **median** as the value (`value="mean"` for the mean) and these channels:
+ *
+ *   min, q1, median, q3, max   the box and its whiskers
+ *   mean, sd, sem, n           for error bars (`sd` is the sample standard deviation, `sem` that over √n)
+ *
+ * so `BoxPath` finds what it needs by their names, and with `value="mean"`, `<ErrorBars error="sd" />` (or `sem`) on a
+ * series of its output draws the mean with its spread. Whiskers reach the furthest sample within `fence` times the interquartile range of the box (1.5 by default,
+ * Tukey's rule); samples beyond are **outliers**. `fence="minmax"` has the whiskers reach the extremes and no outliers.
+ * `output="outliers"` gives those outliers instead (a point for each, at its group's domain, with the sample as the value) to feed
+ * a series of markers, so the two series are made from the one source:
+ *
+ *   <BoxStats output="outliers">{source}</BoxStats>
+ *
+ * `method` is how a quartile falls between samples: 'inclusive' (the default: linear between the closest ranks, as most
+ * packages do) or 'exclusive' (the quartile of the data without its ends, as the textbook method does). Gaps (NaN samples)
+ * are left out. The result is cached against the source's version, so a change of the samples recomputes it once.
+ */
+/* oxlint-disable typescript/no-non-null-assertion -- numeric kernels over flat typed-array buffers (stride-addressed rows): every index is bounded by the row count, which `noUncheckedIndexedAccess` cannot see */
+import { AUTO, STRING } from './attrs.js';
+import { quantile } from './quantile.js';
+import { DataSource, DataTransform } from './data.js';
+import { fail } from './element.js';
+/** The channels of a summary, in the order they are stored. */
+const SUMMARY = ['min', 'q1', 'median', 'q3', 'max', 'mean', 'sd', 'sem', 'n'];
+export class BoxStats extends DataTransform {
+    static attrTypes = { ...DataTransform.attrTypes, output: STRING, fence: AUTO, method: STRING, value: STRING };
+    #version = 0;
+    #cache = null;
+    get source() { return this.child(0, DataSource, DataTransform); }
+    get channelNames() { return this.attrs.output === 'outliers' ? [] : SUMMARY; }
+    /** Anything beneath (the source) bubbles an invalidation up through here, so one counter covers the source and the attributes. */
+    invalidate() {
+        this.#version++;
+        super.invalidate();
+    }
+    get version() { return this.#version; }
+    #compute() {
+        if (this.#cache && this.#cache.version === this.#version)
+            return this.#cache.value;
+        const src = this.source, plan = src.plan({ width: 0, height: 0, domainRange: { min: -Infinity, max: Infinity }, channels: [] });
+        const buf = new Float64Array(plan.capacity * 2), { count } = plan.fill(buf);
+        const a = this.attrs, fence = a.fence === 'minmax' ? Infinity : a.fence ?? 1.5, method = a.method ?? 'inclusive';
+        if (a.fence !== undefined && a.fence !== 'minmax' && !(typeof a.fence === 'number' && a.fence >= 0))
+            fail('BoxStats: fence is a number of interquartile ranges, or "minmax"');
+        const groups = [], cols = { min: [], q1: [], median: [], q3: [], max: [], mean: [], sd: [], sem: [], n: [] };
+        const outD = [], outV = [];
+        for (let i = 0; i < count;) {
+            const key = buf[2 * i];
+            let j = i;
+            const values = [];
+            for (; j < count && buf[2 * j] === key; j++) {
+                const y = buf[2 * j + 1];
+                if (Number.isFinite(y))
+                    values.push(y);
+            }
+            i = j;
+            if (values.length === 0)
+                continue;
+            values.sort((p, q) => p - q);
+            const n = values.length, q1 = quantile(values, 0.25, method), med = quantile(values, 0.5, method), q3 = quantile(values, 0.75, method);
+            const reach = fence * (q3 - q1);
+            let lo = values[0], hi = values[n - 1];
+            if (reach !== Infinity) {
+                // The furthest samples still inside the fences; those beyond are outliers.
+                lo = values.find((v) => v >= q1 - reach) ?? q1;
+                hi = [...values].reverse().find((v) => v <= q3 + reach) ?? q3;
+                for (const v of values)
+                    if (v < q1 - reach || v > q3 + reach) {
+                        outD.push(key);
+                        outV.push(v);
+                    }
+            }
+            let sum = 0;
+            for (const v of values)
+                sum += v;
+            const mean = sum / n;
+            let ss = 0;
+            for (const v of values)
+                ss += (v - mean) * (v - mean);
+            const sd = n > 1 ? Math.sqrt(ss / (n - 1)) : NaN;
+            groups.push(key);
+            cols.min.push(lo);
+            cols.q1.push(q1);
+            cols.median.push(med);
+            cols.q3.push(q3);
+            cols.max.push(hi);
+            cols.mean.push(mean);
+            cols.sd.push(sd);
+            cols.sem.push(sd / Math.sqrt(n));
+            cols.n.push(n);
+        }
+        const value = {
+            groups: Float64Array.from(groups),
+            columns: Object.fromEntries(SUMMARY.map((c) => [c, Float64Array.from(cols[c])])),
+            outlierDomain: Float64Array.from(outD), outlierValue: Float64Array.from(outV),
+        };
+        this.#cache = { version: this.#version, value };
+        return value;
+    }
+    get pointCount() { const c = this.#compute(); return this.attrs.output === 'outliers' ? c.outlierDomain.length : c.groups.length; }
+    domain() {
+        const c = this.#compute(), d = this.attrs.output === 'outliers' ? c.outlierDomain : c.groups;
+        return d.length > 0 ? { min: d[0], max: d[d.length - 1] } : null;
+    }
+    #extent(a) {
+        let min = Infinity, max = -Infinity;
+        for (const v of a) {
+            if (v < min)
+                min = v;
+            if (v > max)
+                max = v;
+        }
+        return min <= max ? { min, max } : null;
+    }
+    valueExtent() {
+        const c = this.#compute();
+        return this.#extent(this.attrs.output === 'outliers' ? c.outlierValue : c.columns[this.attrs.value ?? 'median']);
+    }
+    channelExtent(name) {
+        if (this.attrs.output === 'outliers')
+            return null;
+        return SUMMARY.includes(name) ? this.#extent(this.#compute().columns[name]) : null;
+    }
+    plan(context) {
+        const c = this.#compute(), outliers = this.attrs.output === 'outliers';
+        const names = context.channels;
+        if (outliers && names.length > 0)
+            fail('BoxStats: the outliers have no channels, only the sample (the value)');
+        const want = names.map((n) => SUMMARY.includes(n) ? n : fail(`BoxStats has no channel "${n}" (it has ${SUMMARY.join(', ')})`));
+        const count = outliers ? c.outlierDomain.length : c.groups.length, stride = 2 + want.length;
+        return {
+            capacity: count,
+            fill: (out) => {
+                const domain = outliers ? c.outlierDomain : c.groups, value = outliers ? c.outlierValue : c.columns[this.attrs.value ?? 'median'];
+                const extents = [domain.length > 0 ? { min: domain[0], max: domain[domain.length - 1] } : { min: Infinity, max: -Infinity }];
+                for (let i = 0; i < count; i++) {
+                    out[stride * i] = domain[i];
+                    out[stride * i + 1] = value[i];
+                    for (let k = 0; k < want.length; k++)
+                        out[stride * i + 2 + k] = c.columns[want[k]][i];
+                }
+                extents.push(this.#extent(value) ?? { min: Infinity, max: -Infinity });
+                for (const w of want)
+                    extents.push(this.#extent(c.columns[w]) ?? { min: Infinity, max: -Infinity });
+                return { count, extents };
+            },
+        };
+    }
+}

package/dist/steps.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Steps: a value that holds until it changes, drawn as a line or a filled area by giving a `StepCurve` to a `LinePath` or `AreaPath`.
+ *
+ * Where it changes is `mode`, for a step between a point and the next:
+ *  - `after` (default): the value holds from its point until the next one, then jumps there. A price, a setting.
+ *  - `before`: it jumps at its own point, and holds back to the previous one. A count of what happened by then.
+ *  - `center`: it changes halfway between the two.
+ *
+ * The step is worked out in the plane's own terms, never in pixels: the level part runs along the first axis at one value
+ * and the jump along the second, and both are placed like any other point. So on a rectangle the levels are horizontal and
+ * the jumps vertical (or the other way round when the domain is on the vertical axis), and on a polar plane a level is an
+ * arc round the middle and a jump a spoke. A level on a curved plane is cut into pieces to follow it (at the corners of
+ * a radar's polygon, exactly), which a straight chord between the two ends would cut across.
+ *
+ * The line passes through every point of the data, and a marker on the series sits on a corner. A gap in the data
+ * breaks the steps in two, unless the series says its `gaps` are 'connect'. The curve `trace`s what it draws, so a
+ * 'line' or 'area' hit is measured to the steps on the screen and reports the point whose level it is on, and a tooltip
+ * reading between points (`interpolate`) gives the level there, not a value on a straight line between the points.
+ */
+import type { PointBuffer } from './data.ts';
+import type { Series } from './series.ts';
+import { Curve, type CurveAttributes } from './curve.ts';
+import type { Trace } from './renderer.ts';
+export type StepMode = 'after' | 'before' | 'center';
+/**
+ * The line of a series as steps, and the line it is filled from, as placed points: runs of them, each ended by a NaN
+ * point. `owner` says, for each vertex, which of the series' own points the value there is (a level is its point's, and a
+ * jump is shared by the two it joins), which is a `Trace`.
+ */
+export interface Stepped extends Trace {
+    readonly top: PointBuffer;
+    readonly base: PointBuffer | null;
+}
+/**
+ * The steps of a series in plot pixels. `baseline` is the value a step area is filled from (null for a line, which needs
+ * no second buffer); in a stack the baseline is the layer below, row by row, as everywhere else. Null before the first
+ * projection. The two buffers have the same shape, so a point of one has its foot at the same place in the other.
+ */
+export declare function stepLines(series: Series, mode: StepMode, baseline: number | null): Stepped | null;
+export interface StepCurveAttributes extends CurveAttributes {
+    /** Where the value changes between one point and the next. Default 'after'. */
+    mode?: StepMode;
+}
+/** A line, or the edge of an area, that holds its value and jumps. In a stack, the baseline steps too. */
+export declare class StepCurve extends Curve<StepCurveAttributes> {
+    #private;
+    line(series: Series): string;
+    area(series: Series, baseline: number): string;
+    trace(series: Series, baseline: number | null): Trace | null;
+}

package/dist/steps.js

@@ -0,0 +1,154 @@
+import { Curve, areaOutline, polyline } from './curve.js';
+/** Pieces a level is cut into for a whole turn of a curved plane. */
+const PIECES = 96;
+/** Most pieces one level is cut into. */
+const MOST = 64;
+/**
+ * The steps of a series in plot pixels. `baseline` is the value a step area is filled from (null for a line, which needs
+ * no second buffer); in a stack the baseline is the layer below, row by row, as everywhere else. Null before the first
+ * projection. The two buffers have the same shape, so a point of one has its foot at the same place in the other.
+ */
+export function stepLines(series, mode, baseline) {
+    const d = series.drawn;
+    if (!d)
+        return null;
+    const plane = d.plane, first = series.firstAxis, second = series.secondAxis;
+    const n = d.points.count, rs = d.stride, raw = d.raw, wantBase = baseline !== null;
+    const zero = series.attrs.gaps === 'zero' && !d.top, connect = series.attrs.gaps === 'connect';
+    const norm = new Float64Array(n * 3);
+    for (let i = 0; i < n; i++) {
+        const x = raw[i * rs + d.firstColumn];
+        let v = raw[i * rs + d.secondColumn];
+        if (zero && !Number.isFinite(v) && Number.isFinite(x))
+            v = 0;
+        const ok = Number.isFinite(v);
+        norm[3 * i] = x;
+        norm[3 * i + 1] = ok ? (d.top ? d.top[i] : v) : NaN;
+        norm[3 * i + 2] = ok ? (d.base ? d.base[i] : baseline ?? 0) : NaN;
+    }
+    first.normalize(norm, n, 3, 0);
+    second.normalize(norm, n, 3, 1);
+    second.normalize(norm, n, 3, 2);
+    // The foot stays on the axis, as `Series.baseline` keeps it.
+    for (let i = 0; i < n; i++) {
+        const b = norm[3 * i + 2];
+        if (b < 0)
+            norm[3 * i + 2] = 0;
+        else if (b > 1)
+            norm[3 * i + 2] = 1;
+    }
+    const real = (i) => {
+        const x = norm[3 * i], t = norm[3 * i + 1], b = norm[3 * i + 2];
+        return Number.isFinite(x) && Number.isFinite(t) && (!wantBase || Number.isFinite(b));
+    };
+    const corners = plane.curved ? plane.breaks(first) : [];
+    let top = new Float64Array(Math.max(16, 4 * n)), foot = wantBase ? new Float64Array(top.length) : null, owner = new Int32Array(top.length / 2), k = 0;
+    const put = (x, t, b, by) => {
+        if (2 * k + 2 > top.length) {
+            const bigger = new Float64Array(top.length * 2);
+            bigger.set(top);
+            top = bigger;
+            const o2 = new Int32Array(top.length / 2);
+            o2.set(owner);
+            owner = o2;
+            if (foot) {
+                const f2 = new Float64Array(top.length);
+                f2.set(foot);
+                foot = f2;
+            }
+        }
+        top[2 * k] = x;
+        top[2 * k + 1] = t;
+        owner[k] = by;
+        if (foot) {
+            foot[2 * k] = x;
+            foot[2 * k + 1] = b;
+        }
+        k++;
+    };
+    /** A level from `a` to `b` along the first axis at one pair of values, all belonging to point `by`: the pieces between, then the end. */
+    const level = (a, b, t, bs, by) => {
+        if (plane.curved && a !== b) {
+            const lo = Math.min(a, b), hi = Math.max(a, b), cuts = [];
+            if (corners.length > 0) {
+                for (const c of corners)
+                    if (c > lo + 1e-9 && c < hi - 1e-9)
+                        cuts.push(c);
+            }
+            else {
+                const pieces = Math.min(MOST, Math.ceil((hi - lo) * PIECES));
+                for (let j = 1; j < pieces; j++)
+                    cuts.push(lo + ((hi - lo) * j) / pieces);
+            }
+            if (a > b)
+                cuts.reverse();
+            for (const c of cuts)
+                put(c, t, bs, by);
+        }
+        put(b, t, bs, by);
+    };
+    const run = [];
+    const flush = () => {
+        if (run.length === 0)
+            return;
+        let p = run[0];
+        put(norm[3 * p], norm[3 * p + 1], norm[3 * p + 2], p);
+        for (let j = 1; j < run.length; j++) {
+            const c = run[j], xp = norm[3 * p], xc = norm[3 * c], tp = norm[3 * p + 1], tc = norm[3 * c + 1], bp = norm[3 * p + 2], bc = norm[3 * c + 2];
+            if (mode === 'after') {
+                level(xp, xc, tp, bp, p);
+                put(xc, tc, bc, c);
+            }
+            else if (mode === 'before') {
+                put(xp, tc, bc, c);
+                level(xp, xc, tc, bc, c);
+            }
+            else {
+                const m = (xp + xc) / 2;
+                level(xp, m, tp, bp, p);
+                put(m, tc, bc, c);
+                level(m, xc, tc, bc, c);
+            }
+            p = c;
+        }
+        put(NaN, NaN, NaN, -1);
+        run.length = 0;
+    };
+    for (let i = 0; i < n; i++) {
+        if (real(i))
+            run.push(i);
+        else if (!connect)
+            flush();
+    }
+    flush();
+    const out = (data) => {
+        const buffer = { data: data.subarray(0, 2 * k), stride: 2, count: k };
+        plane.place(buffer, first, second);
+        return buffer;
+    };
+    const placedTop = out(top);
+    return { top: placedTop, line: placedTop, base: foot ? out(foot) : null, owner: owner.subarray(0, k) };
+}
+/** A line, or the edge of an area, that holds its value and jumps. In a stack, the baseline steps too. */
+export class StepCurve extends Curve {
+    #key = '';
+    #value = null;
+    /** The steps of a series, kept until it is projected again or they are asked for differently. */
+    #steps(series, baseline) {
+        const mode = this.attrs.mode ?? 'after', key = `${series.projection}|${mode}|${baseline}|${series.attrs.gaps}`;
+        if (key !== this.#key) {
+            this.#value = stepLines(series, mode, baseline);
+            this.#key = key;
+        }
+        return this.#value;
+    }
+    line(series) {
+        const steps = this.#steps(series, null);
+        return steps ? polyline(steps.top, false) : '';
+    }
+    area(series, baseline) {
+        const steps = this.#steps(series, baseline);
+        return steps?.base ? areaOutline(steps.top, steps.base, false) : '';
+    }
+    trace(series, baseline) { return this.#steps(series, baseline); }
+}

package/dist/stub.d.ts

@@ -0,0 +1,3 @@
+/** What a part of the API that is declared and not yet supported says when it is used. */
+/** Fails when used rather than drawing something wrong, so a half-supported option cannot be relied on by accident. */
+export declare function notImplemented(what: string): never;

package/dist/stub.js

@@ -0,0 +1,5 @@
+/** What a part of the API that is declared and not yet supported says when it is used. */
+/** Fails when used rather than drawing something wrong, so a half-supported option cannot be relied on by accident. */
+export function notImplemented(what) {
+    throw new Error(`${what} is not implemented yet`);
+}

package/dist/style-names.d.ts

@@ -0,0 +1 @@
+export declare const STYLE_NAMES: readonly ["annotationLabel", "annotationLine", "axisLine", "axisTitle", "boxLine", "calloutArm", "calloutBox", "calloutText", "chartCaption", "chartSubtitle", "chartTitle", "dotMarker", "errorBand", "errorBar", "focusRing", "heatCell", "keyLabel", "keyLine", "keyTitle", "legendLabel", "legendTitle", "lineMarker", "seriesArea", "seriesBar", "seriesBox", "seriesLine", "shapeMarker", "tickLabel", "tooltipBox", "tooltipText", "haloWidth", "strokeWidth", "tickLength", "labelGap"];

package/dist/style-names.js

@@ -0,0 +1,6 @@
+export const STYLE_NAMES = [
+    // Selectors
+    'annotationLabel', 'annotationLine', 'axisLine', 'axisTitle', 'boxLine', 'calloutArm', 'calloutBox', 'calloutText', 'chartCaption', 'chartSubtitle', 'chartTitle', 'dotMarker', 'errorBand', 'errorBar', 'focusRing', 'heatCell', 'keyLabel', 'keyLine', 'keyTitle', 'legendLabel', 'legendTitle', 'lineMarker', 'seriesArea', 'seriesBar', 'seriesBox', 'seriesLine', 'shapeMarker', 'tickLabel', 'tooltipBox', 'tooltipText',
+    // Properties
+    'haloWidth', 'strokeWidth', 'tickLength', 'labelGap',
+];

package/dist/summary.d.ts

@@ -0,0 +1,44 @@
+import type { Chart, Describer } from './chart.ts';
+import { type BaseAttributes, ChartElement } from './element.ts';
+/** What a summary is made from. Plain data, so a function in any language can word it. */
+export interface ChartFacts {
+    /** The chart's own name, from `meta.title`. */
+    readonly title?: string;
+    readonly series: readonly {
+        readonly name: string;
+        readonly points: number;
+        readonly shown: boolean;
+    }[];
+    /** Each axis with a span: its title, whether it runs across, and its first and last tick labels. */
+    readonly axes: readonly {
+        readonly title?: string;
+        readonly horizontal: boolean;
+        readonly from: string;
+        readonly to: string;
+    }[];
+}
+export interface ChartSummaryAttributes extends BaseAttributes {
+    /** Words the facts. Default: English sentences. */
+    text?: (facts: ChartFacts) => string;
+    /** What the chart is, as a screen reader announces it. Default 'chart'. */
+    roleDescription?: string;
+}
+/** The English summary: how many series and points, then the span of each axis. */
+export declare function englishSummary(f: ChartFacts): string;
+export declare class ChartSummary extends ChartElement<Chart, [], ChartSummaryAttributes> implements Describer {
+    static attrTypes: {
+        roleDescription: 1;
+        id: 1;
+        meta: {
+            title: 1;
+            description: 1;
+            role: 1;
+        };
+    };
+    /** What the chart holds as of the last layout. */
+    get facts(): ChartFacts;
+    describe(): {
+        description: string;
+        roleDescription: string;
+    };
+}

package/dist/summary.js

@@ -0,0 +1,58 @@
+/**
+ * A spoken summary of the chart, for a screen reader: what the chart holds, written out in words.
+ *
+ *   new Chart({ meta: { title: 'Rates' } }, plane, new ChartSummary())
+ *
+ * It is a separate, opt-in chart child because the words are language-specific, and the core carries none: leave it out and a
+ * chart says only what its `meta` says. This one writes English. For another language, pass `text`, a function from the facts
+ * (`ChartFacts`) to the sentence, and `roleDescription` (what the chart is called, "chart" by default). `meta.description`
+ * on the chart, when given, is used instead of the summary.
+ */
+import { STRING } from './attrs.js';
+import { ChartElement } from './element.js';
+import { Plane } from './plane.js';
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+/** The English summary: how many series and points, then the span of each axis. */
+export function englishSummary(f) {
+    const parts = [];
+    if (f.series.length > 0) {
+        const list = f.series.map((s) => `${s.name}, ${plural(s.points, 'point', 'points')}${s.shown ? '' : ', hidden'}`).join('; ');
+        parts.push(`${plural(f.series.length, 'series', 'series')}: ${list}.`);
+    }
+    for (const a of f.axes)
+        parts.push(`${a.horizontal ? 'Horizontal' : 'Vertical'} axis${a.title ? ` ${a.title}` : ''}, from ${a.from} to ${a.to}.`);
+    return parts.join(' ');
+}
+export class ChartSummary extends ChartElement {
+    static attrTypes = { ...ChartElement.attrTypes, roleDescription: STRING };
+    /** What the chart holds as of the last layout. */
+    get facts() {
+        const chart = this.requireParent(), series = [], axes = [];
+        const seen = new Set();
+        let n = 0;
+        for (const plane of chart) {
+            if (!(plane instanceof Plane))
+                continue;
+            for (const s of plane.allSeries) {
+                n++;
+                series.push({ name: s.attrs.name ?? s.attrs.meta?.title ?? `${n}`, points: s.points.count, shown: s.shown });
+            }
+            for (const axis of plane.axes) {
+                if (seen.has(axis))
+                    continue;
+                seen.add(axis);
+                const ticks = axis.getTicks(axis.ruler.length);
+                if (ticks.length < 2)
+                    continue;
+                // oxlint-disable-next-line typescript/no-non-null-assertion -- in range: the index comes from a loop bound or a length checked in the same function
+                axes.push({ ...(axis.attrs.title && { title: axis.attrs.title }), horizontal: axis.ruler.horizontal, from: ticks[0].label, to: ticks[ticks.length - 1].label });
+            }
+        }
+        const title = chart.attrs.meta?.title;
+        return { ...(title !== undefined && { title }), series, axes };
+    }
+    describe() {
+        const a = this.attrs;
+        return { description: (a.text ?? englishSummary)(this.facts), roleDescription: a.roleDescription ?? 'chart' };
+    }
+}

package/dist/surface.d.ts

@@ -0,0 +1,94 @@
+/**
+ * A surface: the platform nodes one element owns, and the counters a flush accumulates.
+ *
+ * Why this layer exists: every flush re-runs every element's drawing code, so drawing has to be idempotent and cheap.
+ * Surface makes it so by (a) handing out the same node for the same key, and (b) remembering the last value written
+ * to each attribute and skipping identical writes. Elements therefore just say "this node has these attributes" every
+ * time, and only real changes reach the platform (and, in a browser, the DOM).
+ */
+import type { Platform, PlatformNode, SvgTag } from './platform.ts';
+/** The timed phases of producing a series' path, for the chart's diagnostics. */
+export type StageName = 'generate' | 'decimate' | 'normalize' | 'place' | 'path';
+/** What a flush accumulates. One per chart, shared by every surface and element in it. */
+export interface Counters {
+    writes: number;
+    skipped: number;
+    names: Set<string>;
+    filled: number;
+    cached: number;
+    projected: number;
+    pointsIn: number;
+    pointsDrawn: number;
+    pathBytes: number;
+    stages: Record<StageName, number>;
+}
+/** Fresh zeroed counters; the chart resets (rather than replaces) them each flush so surfaces keep a valid reference. */
+export declare const newCounters: () => Counters;
+/**
+ * Where an element's nodes go, answered from the live element tree each time one is created.
+ * Nothing about neighbours is stored, so nothing can go stale when siblings come and go.
+ */
+export interface Placement {
+    /** The node own content goes into when the element has no wrapper: the nearest wrapper above, or the platform root. */
+    container(): PlatformNode;
+    /** The node this element's whole content must end before. Null means append. */
+    end(): PlatformNode | null;
+    /** The first node among the element's children, if any of them has drawn. */
+    childrenFirst(): PlatformNode | null;
+}
+export interface NodeOptions {
+    /** Put the node inside another of this element's nodes instead of at the top level. */
+    parent?: PlatformNode;
+    /** Draw after the element's children instead of before them (an axis' labels over the series, say). */
+    above?: boolean;
+}
+/**
+ * What an element draws with. Nodes are keyed, created on demand, positioned from the live tree,
+ * and written only when a value changed. An element's own content sits below its children (or above, with `above`).
+ *
+ * An element has no node of its own unless it asks for a wrapper, which it should only do when the wrapper
+ * does something: a transform, a clip, or style its content inherits. Otherwise its nodes sit directly
+ * in the parent's, in order, with nothing to mark where they start.
+ */
+export declare class Surface {
+    private readonly platform;
+    private readonly counters;
+    private readonly placement;
+    private wrapperNode;
+    private hidden;
+    private readonly nodes;
+    private readonly cache;
+    constructor(platform: Platform, counters: Counters, placement: Placement);
+    /**
+     * The element's own `<g>` (or another tag). Children and own nodes go inside it. Create it before the
+     * element draws anything, typically on attach; asking again returns the same node.
+     */
+    wrapper(tag?: SvgTag): PlatformNode;
+    /** The wrapper, if the element has one. */
+    get wrapperRoot(): PlatformNode | null;
+    /** First own node below the children, if any. */
+    get firstBelow(): PlatformNode | null;
+    /** First own node above the children, if any. */
+    get firstAbove(): PlatformNode | null;
+    /**
+     * The node for `key`, created the first time and the same node afterwards. Keys are per element, so two elements
+     * can both use 'grid' without clashing.
+     */
+    node(key: string, tag: SvgTag, options?: NodeOptions): PlatformNode;
+    /** Set an attribute if (and only if) it differs from what was last written. The platform cannot unset one, so use a neutral value ('none', 0) instead of removing. */
+    set(node: PlatformNode, name: string, value: string | number): void;
+    /** Set a text node's content, skipping unchanged writes like `set`. */
+    text(node: PlatformNode, content: string): void;
+    /** Drop one keyed node, for content that comes and goes (a title, a clip path). */
+    remove(key: string): void;
+    /** Drop a keyed node and every node keyed beneath it (`key/…`), for a group made of several. */
+    removePrefix(key: string): void;
+    /** Hide or show everything this element draws (the wrapper, or each top-level node if it has none). */
+    setHidden(hidden: boolean): void;
+    /** Take this element's nodes out of the platform. */
+    dispose(): void;
+    /** The first top-level node of one layer; the layers are what `end()`/`first()` placement is computed from. */
+    private firstOf;
+    /** The write cache lives per node (a WeakMap) so a removed node's entries are collected with it. */
+    private write;
+}