@motionscript/plot 0.0.0-stage → 0.1.0-alpha.3

package/dist/graph2d/plane.d.ts

@@ -0,0 +1,179 @@
+/**
+ * What part of the plane a 2D graph is looking at, and the furniture that makes
+ * it readable: the graph→pixel mapping, the tick ladder, and how a number on an
+ * axis is written.
+ *
+ * ## The view is four numbers, and none of them is a matrix
+ *
+ * `centerX`/`centerY` say where you are, `xSpan`/`ySpan` say how much you can
+ * see. Four independently tweenable numbers rather than a transform, for exactly
+ * the reason the 3D graph's camera is three: the studio renders a *timeline*, so
+ * every frame has to be reproducible from stored values under scrubbing and
+ * export, and "pan across while zooming in" has to be one command rather than a
+ * hand-built parallel over matrix entries.
+ *
+ * ## `ySpan: 0` means "keep the grid square"
+ *
+ * The vertical span is the one number that usually shouldn't be typed. A grapher
+ * whose units are square is one where a circle is round and a 45° line looks
+ * like one, and the span that achieves that depends on the node's *box* — which
+ * the author changes by dragging a handle, not by editing this field. So zero
+ * means "derive it", the same convention a node's own width and height use for
+ * auto-sizing, and any positive value takes over.
+ *
+ * Nothing is lost by it: the moment a gesture or a command scales the axes
+ * apart, the derived value is written down and the field is an ordinary number
+ * from then on — the same handover the canvas makes when a resize drag turns a
+ * filling axis into a fixed one.
+ */
+import type { PixelRect, PlaneMap } from "./curve.js";
+/** Where a 2D graph is looking, as the four numbers its props hold. */
+export interface PlaneView {
+    /** Graph x at the centre of the node's box. */
+    centerX: number;
+    /** Graph y at the centre of the node's box. */
+    centerY: number;
+    /** Width of the visible window, in graph units. */
+    xSpan: number;
+    /** Height of the visible window in graph units, or 0 to keep units square. */
+    ySpan: number;
+}
+/**
+ * Bounds on a span.
+ *
+ * A hundred decades inside the double's own range, so nothing downstream —
+ * `width / span`, `step * scale`, `y * scale` — can overflow or fall into the
+ * denormals on the way through.
+ *
+ * Deliberately far wider than anything usable, because what actually limits how
+ * far a plane can be zoomed is not a floor on the span but a **ratio**:
+ * `x - centerX` keeps about sixteen significant digits, so a window narrower
+ * than `|centerX| · 4.3e-13` has fewer distinct representable x values across it
+ * than it has pixels, and the curve staircases whatever these constants say.
+ * That limit belongs to the *gesture* — see `planeSpanLimits` — which is the
+ * thing a person can be stopped at. A scene that deliberately authored a deeper
+ * zoom still renders, badly and visibly, rather than being silently clamped to
+ * something it never asked for.
+ */
+export declare const MIN_SPAN = 1e-200;
+export declare const MAX_SPAN = 1e+200;
+/** A {@link PlaneView} resolved against a box: everything in concrete numbers. */
+export interface ResolvedPlane extends PlaneMap {
+    /** The box, in node-local pixels. */
+    width: number;
+    height: number;
+    /** Visible graph range, low to high. */
+    xMin: number;
+    xMax: number;
+    yMin: number;
+    yMax: number;
+    /** The vertical span actually in force — the derived one when `ySpan` is 0. */
+    ySpan: number;
+}
+/**
+ * Resolves a view against the node's box: what a graph unit is worth in pixels,
+ * and which part of the plane that puts on screen.
+ *
+ * The single place `ySpan: 0` is turned into a number, so nothing downstream —
+ * the grid, the curves, the gesture — has to know the convention exists.
+ */
+export declare function resolvePlane(view: PlaneView, width: number, height: number): ResolvedPlane;
+/** Holds a span inside the range a double can still draw a grid over. */
+export declare function clampSpan(span: number): number;
+/** The node's box as a pixel rectangle, y-up and centred on the origin. */
+export declare function planeBox(plane: ResolvedPlane): PixelRect;
+/** Grows a rectangle by `margin` on every side. */
+export declare function inflate(rect: PixelRect, margin: number): PixelRect;
+/** Graph x → node-local pixels. */
+export declare function toPx(plane: PlaneMap, x: number): number;
+/** Graph y → node-local pixels, y-up. */
+export declare function toPy(plane: PlaneMap, y: number): number;
+/** Slides the view by a delta in **graph units**. Spans are untouched. */
+export declare function panPlane(view: PlaneView, dx: number, dy: number): PlaneView;
+/**
+ * Scales the view about a fixed point in **graph units** — the gesture every map
+ * makes: whatever was under the cursor stays under the cursor.
+ *
+ * `factorX`/`factorY` are how much bigger the *window* gets, so a factor above 1
+ * zooms out. Passing the same factor twice keeps a square grid square, and is
+ * the only case that leaves an auto {@link PlaneView.ySpan} auto: scaling one
+ * axis on its own is the statement "this axis is mine now", so the derived span
+ * is written down and stops following the box.
+ */
+export declare function zoomPlane(view: PlaneView, plane: ResolvedPlane, factorX: number, factorY: number, anchorX: number, anchorY: number): PlaneView;
+/** One axis's tick ladder: where the numbers go and how finely to rule between. */
+export interface TickLadder {
+    /** Distance between labelled ticks, in graph units. */
+    step: number;
+    /** Distance between the faint lines between them. */
+    minorStep: number;
+    /**
+     * Faint lines inside one labelled step — `step / minorStep`, as a whole
+     * number.
+     *
+     * The faint lines have no list of their own any more: they are generated by
+     * the plane's shader from a pitch and a phase, so what the ladder has to hand
+     * over is how many of them fit rather than where each one is. Building and
+     * filtering a few hundred numbers per axis per frame for a paint that never
+     * reads them was most of what the old ladder cost.
+     */
+    divisions: number;
+    /** Labelled positions across the visible range, ascending. */
+    major: number[];
+}
+/**
+ * The tick ladder for a range, at a scale, given the closest two labels may sit.
+ *
+ * Steps climb the 1–2–5 ladder, which is the one every plotting tool uses
+ * because those are the numbers people can subdivide in their heads. Minor lines
+ * subdivide a step into 5 — or into 4 when the step is a 2, so that the faint
+ * lines land on halves rather than on fifths of a two.
+ */
+export declare function tickLadder(min: number, max: number, pxPerUnit: number, minSpacingPx: number): TickLadder;
+/**
+ * A ladder whose numbers are guaranteed not to overlap, however long they are.
+ *
+ * The base pitch assumes a label of about five characters, which is what an
+ * axis anywhere near the origin actually carries. Zoom to `x = 1.23456789` at a
+ * span of 1e-6 and every number is fourteen, so the ladder is rebuilt once at a
+ * pitch wide enough to hold the widest one it just produced. One extra pass and
+ * not a loop: the second ladder is coarser than the first, so its labels are no
+ * longer, and a third pass could only ever agree with the second.
+ */
+export declare function labelLadder(min: number, max: number, pxPerUnit: number, fontSize: number): TickLadder;
+/**
+ * Room the widest number on `ladder` needs beside its neighbour, in font sizes.
+ *
+ * Also what the node aligns its numbers within — a right-aligned `-1200` and a
+ * right-aligned `5` end in the same place only if the box holds the longer of
+ * the two.
+ */
+export declare function labelWidthEm(ladder: TickLadder): number;
+/**
+ * How wide a number on this ladder can be, in characters.
+ *
+ * The longest is not always at an extreme — `-0.5` is longer than `10` — so this
+ * scans, which costs at most {@link MAX_TICKS} formats and is a rounding error
+ * beside the labels the node is about to shape anyway.
+ */
+export declare function widestLabel(ladder: TickLadder): number;
+/**
+ * A tick value as it is written on the axis.
+ *
+ * The precision comes from the **step**, not from the value: what a number on an
+ * axis has to do is tell you which tick it is, so a ladder of 0.2s reads
+ * `0.2 0.4 0.6` and the same values on a ladder of 1s would be rounded away
+ * rather than shown as `0.2` next to `1`.
+ *
+ * That is also the rule for choosing the exponent, and the reason the two fixed
+ * magnitude thresholds this used to carry are gone. `1e6` as a ceiling is wrong
+ * about *both* directions at once: pan to `x = 1e7` at the default zoom and a
+ * whole axis of distinct ticks reads `1e7`, `1e7`, `1e7`; while at a span of
+ * 1e-9 around `x = 1` no threshold on the magnitude helps at all, because the
+ * values are all near 1 and it is the *step* that has run out of room. What
+ * decides it is how many significant digits it takes to tell two neighbouring
+ * ticks apart: the exponent is only shorter when that count is small and the
+ * number is far from 1.
+ */
+export declare function formatTick(value: number, step: number): string;
+//# sourceMappingURL=plane.d.ts.map

package/dist/graph2d/plane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plane.d.ts","sourceRoot":"","sources":["../../src/graph2d/plane.ts"],"names":[],"mappings":"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"}

package/dist/graph2d/plane.js

@@ -0,0 +1,359 @@
+/**
+ * What part of the plane a 2D graph is looking at, and the furniture that makes
+ * it readable: the graph→pixel mapping, the tick ladder, and how a number on an
+ * axis is written.
+ *
+ * ## The view is four numbers, and none of them is a matrix
+ *
+ * `centerX`/`centerY` say where you are, `xSpan`/`ySpan` say how much you can
+ * see. Four independently tweenable numbers rather than a transform, for exactly
+ * the reason the 3D graph's camera is three: the studio renders a *timeline*, so
+ * every frame has to be reproducible from stored values under scrubbing and
+ * export, and "pan across while zooming in" has to be one command rather than a
+ * hand-built parallel over matrix entries.
+ *
+ * ## `ySpan: 0` means "keep the grid square"
+ *
+ * The vertical span is the one number that usually shouldn't be typed. A grapher
+ * whose units are square is one where a circle is round and a 45° line looks
+ * like one, and the span that achieves that depends on the node's *box* — which
+ * the author changes by dragging a handle, not by editing this field. So zero
+ * means "derive it", the same convention a node's own width and height use for
+ * auto-sizing, and any positive value takes over.
+ *
+ * Nothing is lost by it: the moment a gesture or a command scales the axes
+ * apart, the derived value is written down and the field is an ordinary number
+ * from then on — the same handover the canvas makes when a resize drag turns a
+ * filling axis into a fixed one.
+ */
+import { niceStep } from "@motionscript/sdk/component";
+/**
+ * Bounds on a span.
+ *
+ * A hundred decades inside the double's own range, so nothing downstream —
+ * `width / span`, `step * scale`, `y * scale` — can overflow or fall into the
+ * denormals on the way through.
+ *
+ * Deliberately far wider than anything usable, because what actually limits how
+ * far a plane can be zoomed is not a floor on the span but a **ratio**:
+ * `x - centerX` keeps about sixteen significant digits, so a window narrower
+ * than `|centerX| · 4.3e-13` has fewer distinct representable x values across it
+ * than it has pixels, and the curve staircases whatever these constants say.
+ * That limit belongs to the *gesture* — see `planeSpanLimits` — which is the
+ * thing a person can be stopped at. A scene that deliberately authored a deeper
+ * zoom still renders, badly and visibly, rather than being silently clamped to
+ * something it never asked for.
+ */
+export const MIN_SPAN = 1e-200;
+export const MAX_SPAN = 1e200;
+/**
+ * Resolves a view against the node's box: what a graph unit is worth in pixels,
+ * and which part of the plane that puts on screen.
+ *
+ * The single place `ySpan: 0` is turned into a number, so nothing downstream —
+ * the grid, the curves, the gesture — has to know the convention exists.
+ */
+export function resolvePlane(view, width, height) {
+    const w = Math.max(1, width);
+    const h = Math.max(1, height);
+    const xSpan = clampSpan(view.xSpan);
+    const scaleX = w / xSpan;
+    // Square units: a graph unit is the same number of pixels either way, so the
+    // visible height is however many of them fit in the box.
+    const ySpan = view.ySpan > 0 ? clampSpan(view.ySpan) : h / scaleX;
+    const scaleY = h / ySpan;
+    return {
+        centerX: view.centerX,
+        centerY: view.centerY,
+        scaleX,
+        scaleY,
+        width: w,
+        height: h,
+        xMin: view.centerX - xSpan / 2,
+        xMax: view.centerX + xSpan / 2,
+        yMin: view.centerY - ySpan / 2,
+        yMax: view.centerY + ySpan / 2,
+        ySpan,
+    };
+}
+/** Holds a span inside the range a double can still draw a grid over. */
+export function clampSpan(span) {
+    if (!Number.isFinite(span) || span <= 0)
+        return MIN_SPAN;
+    return Math.min(MAX_SPAN, Math.max(MIN_SPAN, span));
+}
+/** The node's box as a pixel rectangle, y-up and centred on the origin. */
+export function planeBox(plane) {
+    return {
+        left: -plane.width / 2,
+        right: plane.width / 2,
+        bottom: -plane.height / 2,
+        top: plane.height / 2,
+    };
+}
+/** Grows a rectangle by `margin` on every side. */
+export function inflate(rect, margin) {
+    return {
+        left: rect.left - margin,
+        right: rect.right + margin,
+        bottom: rect.bottom - margin,
+        top: rect.top + margin,
+    };
+}
+/** Graph x → node-local pixels. */
+export function toPx(plane, x) {
+    return (x - plane.centerX) * plane.scaleX;
+}
+/** Graph y → node-local pixels, y-up. */
+export function toPy(plane, y) {
+    return (y - plane.centerY) * plane.scaleY;
+}
+// --- Moving the view -------------------------------------------------------
+/** Slides the view by a delta in **graph units**. Spans are untouched. */
+export function panPlane(view, dx, dy) {
+    return {
+        ...view,
+        centerX: view.centerX + dx,
+        centerY: view.centerY + dy,
+    };
+}
+/**
+ * Scales the view about a fixed point in **graph units** — the gesture every map
+ * makes: whatever was under the cursor stays under the cursor.
+ *
+ * `factorX`/`factorY` are how much bigger the *window* gets, so a factor above 1
+ * zooms out. Passing the same factor twice keeps a square grid square, and is
+ * the only case that leaves an auto {@link PlaneView.ySpan} auto: scaling one
+ * axis on its own is the statement "this axis is mine now", so the derived span
+ * is written down and stops following the box.
+ */
+export function zoomPlane(view, plane, factorX, factorY, anchorX, anchorY) {
+    const uniform = factorX === factorY && view.ySpan <= 0;
+    const xSpan = clampSpan(plane.xMax - plane.xMin) * factorX;
+    const ySpan = plane.ySpan * factorY;
+    return {
+        // The anchor keeps its distance from each edge as a *fraction* of the span,
+        // which is what "stays under the cursor" means once the span has changed.
+        //
+        // Written as a *displacement from the current centre* rather than as
+        // `anchor + (centre - anchor) · factor`, which is the same expression
+        // rearranged and much better conditioned. The anchor is up to half a span
+        // away from the centre, so at a wide view the direct form subtracts two
+        // enormous numbers to recover a small one and loses it: at a span of 1e200 a
+        // centre of 4 comes back as 0, and at a stop — where the factor is exactly 1
+        // and the centre must not move at all — it came back as 0 rather than as 4.
+        // This form multiplies the big quantity by `1 - factor`, which is what is
+        // actually small, and is bit-exact when the wheel is doing nothing.
+        centerX: view.centerX + (anchorX - view.centerX) * (1 - factorX),
+        centerY: view.centerY + (anchorY - view.centerY) * (1 - factorY),
+        xSpan: clampSpan(xSpan),
+        ySpan: uniform ? 0 : clampSpan(ySpan),
+    };
+}
+/**
+ * Cap on how many *numbers* one axis may carry.
+ *
+ * The step is chosen from how close two labels may sit, so this is unreachable
+ * in normal use — a 1920-px axis at the tightest legal pitch holds about
+ * seventeen. It is there because `xSpan` is an animatable number and a tween
+ * passing through an absurd value must not try to shape a thousand strings for
+ * one frame. Half what it was, because it no longer bounds the grid: the shader
+ * rules the plane at O(1) however far it is zoomed.
+ */
+const MAX_TICKS = 200;
+/**
+ * Largest tick index the ladder will build from.
+ *
+ * Past `2^53` an integer is no longer exactly representable, so `first + i`
+ * repeats values and `(first + i) * step` produces garbage. At that view the
+ * ticks genuinely have no distinct values, and an empty ladder says so.
+ */
+const MAX_INDEX = Number.MAX_SAFE_INTEGER;
+/**
+ * The decade a positive number sits in: `1` for 42, `-2` for 0.03.
+ *
+ * The nudge is not cosmetic. `Math.log10(1e-7)` is `-7.000000000000001` in V8,
+ * so a bare `floor` answers -8 for an exact power of ten — which put the leading
+ * digit of a 1e-7 step at 10 and handed {@link minorDivisions} the wrong answer
+ * on several perfectly ordinary zooms.
+ */
+function decadeOf(value) {
+    return Math.floor(Math.log10(value) + 1e-12);
+}
+/**
+ * The tick ladder for a range, at a scale, given the closest two labels may sit.
+ *
+ * Steps climb the 1–2–5 ladder, which is the one every plotting tool uses
+ * because those are the numbers people can subdivide in their heads. Minor lines
+ * subdivide a step into 5 — or into 4 when the step is a 2, so that the faint
+ * lines land on halves rather than on fifths of a two.
+ */
+export function tickLadder(min, max, pxPerUnit, minSpacingPx) {
+    const span = max - min;
+    if (!(span > 0) || !(pxPerUnit > 0)) {
+        return { step: 1, minorStep: 1, divisions: 1, major: [] };
+    }
+    const step = niceStep(Math.max(minSpacingPx, 1) / pxPerUnit);
+    const divisions = minorDivisions(step);
+    return {
+        step,
+        minorStep: step / divisions,
+        divisions,
+        major: multiplesWithin(min, max, step),
+    };
+}
+/**
+ * A digit's advance in the built-in face, as a fraction of the font size.
+ *
+ * Approximate on purpose: the node draws its numbers through the renderer's
+ * shaper and this arithmetic runs in `scene-core`, which has no font metrics and
+ * shouldn't grow any. It only has to be close enough to decide whether two
+ * labels would collide, and it errs wide.
+ */
+const DIGIT_EM = 0.58;
+/** Blank either side of a number, in font sizes. */
+const LABEL_MARGIN = 0.8;
+/**
+ * Room an x-axis number needs before the ladder steps up, as multiples of its
+ * font size — the pitch {@link labelLadder} widens *from*.
+ *
+ * Wider than the five characters it nominally buys, and left that way: it is
+ * what every graph anywhere near the origin has always been ruled at, and
+ * tightening it here would re-space every existing scene to fix a problem only
+ * deep zoom has.
+ */
+const BASE_LABEL_PITCH = 5;
+/**
+ * A ladder whose numbers are guaranteed not to overlap, however long they are.
+ *
+ * The base pitch assumes a label of about five characters, which is what an
+ * axis anywhere near the origin actually carries. Zoom to `x = 1.23456789` at a
+ * span of 1e-6 and every number is fourteen, so the ladder is rebuilt once at a
+ * pitch wide enough to hold the widest one it just produced. One extra pass and
+ * not a loop: the second ladder is coarser than the first, so its labels are no
+ * longer, and a third pass could only ever agree with the second.
+ */
+export function labelLadder(min, max, pxPerUnit, fontSize) {
+    const base = fontSize * BASE_LABEL_PITCH;
+    const ladder = tickLadder(min, max, pxPerUnit, base);
+    const needed = fontSize * labelWidthEm(ladder);
+    return needed > base ? tickLadder(min, max, pxPerUnit, needed) : ladder;
+}
+/**
+ * Room the widest number on `ladder` needs beside its neighbour, in font sizes.
+ *
+ * Also what the node aligns its numbers within — a right-aligned `-1200` and a
+ * right-aligned `5` end in the same place only if the box holds the longer of
+ * the two.
+ */
+export function labelWidthEm(ladder) {
+    return DIGIT_EM * widestLabel(ladder) + LABEL_MARGIN;
+}
+/**
+ * How wide a number on this ladder can be, in characters.
+ *
+ * The longest is not always at an extreme — `-0.5` is longer than `10` — so this
+ * scans, which costs at most {@link MAX_TICKS} formats and is a rounding error
+ * beside the labels the node is about to shape anyway.
+ */
+export function widestLabel(ladder) {
+    let widest = 0;
+    for (const value of ladder.major) {
+        const length = formatTick(value, ladder.step).length;
+        if (length > widest)
+            widest = length;
+    }
+    return widest;
+}
+/**
+ * How many faint lines a step is divided into. A 1 or a 5 takes five, a 2 takes
+ * four — see {@link tickLadder}.
+ */
+function minorDivisions(step) {
+    const magnitude = Math.pow(10, decadeOf(step));
+    const leading = Math.round(step / magnitude);
+    return leading === 2 ? 4 : 5;
+}
+/**
+ * Every multiple of `step` within `[min, max]`, ascending.
+ *
+ * Built from an integer index times the step rather than by accumulation, so the
+ * hundredth tick is still exactly a hundred steps out — repeated addition drifts
+ * enough to put a `0.30000000000000004` on an axis.
+ */
+function multiplesWithin(min, max, step) {
+    // The nudge absorbs the case where a bound *is* a multiple and lands a hair
+    // outside it after the division, which would drop the tick on the edge.
+    const first = Math.ceil(min / step - 1e-9);
+    const last = Math.floor(max / step + 1e-9);
+    if (!Number.isFinite(first) || !Number.isFinite(last))
+        return [];
+    if (Math.abs(first) > MAX_INDEX || Math.abs(last) > MAX_INDEX)
+        return [];
+    const count = last - first + 1;
+    if (count <= 0 || count > MAX_TICKS)
+        return [];
+    const out = new Array(count);
+    for (let i = 0; i < count; i++)
+        out[i] = (first + i) * step;
+    return out;
+}
+/**
+ * Largest number of digits worth writing out in full, before the exponent is the
+ * shorter answer.
+ */
+const MAX_DIGITS = 14;
+/** `toFixed` and `toExponential` both refuse an argument past 100. */
+const MAX_FRACTION = 100;
+/**
+ * A tick value as it is written on the axis.
+ *
+ * The precision comes from the **step**, not from the value: what a number on an
+ * axis has to do is tell you which tick it is, so a ladder of 0.2s reads
+ * `0.2 0.4 0.6` and the same values on a ladder of 1s would be rounded away
+ * rather than shown as `0.2` next to `1`.
+ *
+ * That is also the rule for choosing the exponent, and the reason the two fixed
+ * magnitude thresholds this used to carry are gone. `1e6` as a ceiling is wrong
+ * about *both* directions at once: pan to `x = 1e7` at the default zoom and a
+ * whole axis of distinct ticks reads `1e7`, `1e7`, `1e7`; while at a span of
+ * 1e-9 around `x = 1` no threshold on the magnitude helps at all, because the
+ * values are all near 1 and it is the *step* that has run out of room. What
+ * decides it is how many significant digits it takes to tell two neighbouring
+ * ticks apart: the exponent is only shorter when that count is small and the
+ * number is far from 1.
+ */
+export function formatTick(value, step) {
+    if (value === 0)
+        return "0";
+    if (!Number.isFinite(value))
+        return "";
+    if (!(step > 0) || !Number.isFinite(step))
+        return String(value);
+    const decade = decadeOf(Math.abs(value));
+    // At least one: a value smaller than its own step isn't a tick of this ladder,
+    // but it is still a number somebody may ask this to write.
+    const digits = Math.max(1, decade - decadeOf(step) + 1);
+    // Far from 1 and cheap to write in scientific form — `2e7`, `1.5e-9`.
+    if ((decade >= 6 || decade <= -5) && digits <= 6) {
+        return trimExponent(value.toExponential(digits - 1));
+    }
+    if (digits <= MAX_DIGITS) {
+        const decimals = Math.min(MAX_FRACTION, Math.max(0, -decadeOf(step)));
+        const text = value.toFixed(decimals);
+        // `toFixed` keeps the zeros a nice step can't produce (0.50 for a 0.1 ladder
+        // is only ever written that way by the formatter).
+        return decimals > 0 ? text.replace(/\.?0+$/, "") : text;
+    }
+    // More digits than anybody can read off an axis. The exponent at least keeps
+    // the ticks distinguishable from one another.
+    const precision = Math.min(17, Math.max(0, digits - 1));
+    return trimExponent(value.toExponential(precision));
+}
+/** `1.20e-7` → `1.2e-7`, and `1.00e+21` → `1e21`. */
+function trimExponent(text) {
+    const [mantissa, exponent] = text.split("e");
+    const trimmed = mantissa.replace(/\.?0+$/, "");
+    return `${trimmed}e${Number(exponent)}`;
+}
+//# sourceMappingURL=plane.js.map

package/dist/graph2d/plane.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plane.js","sourceRoot":"","sources":["../../src/graph2d/plane.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What part of the plane a 2D graph is looking at, and the furniture that makes\n * it readable: the graph→pixel mapping, the tick ladder, and how a number on an\n * axis is written.\n *\n * ## The view is four numbers, and none of them is a matrix\n *\n * `centerX`/`centerY` say where you are, `xSpan`/`ySpan` say how much you can\n * see. Four independently tweenable numbers rather than a transform, for exactly\n * the reason the 3D graph's camera is three: the studio renders a *timeline*, so\n * every frame has to be reproducible from stored values under scrubbing and\n * export, and \"pan across while zooming in\" has to be one command rather than a\n * hand-built parallel over matrix entries.\n *\n * ## `ySpan: 0` means \"keep the grid square\"\n *\n * The vertical span is the one number that usually shouldn't be typed. A grapher\n * whose units are square is one where a circle is round and a 45° line looks\n * like one, and the span that achieves that depends on the node's *box* — which\n * the author changes by dragging a handle, not by editing this field. So zero\n * means \"derive it\", the same convention a node's own width and height use for\n * auto-sizing, and any positive value takes over.\n *\n * Nothing is lost by it: the moment a gesture or a command scales the axes\n * apart, the derived value is written down and the field is an ordinary number\n * from then on — the same handover the canvas makes when a resize drag turns a\n * filling axis into a fixed one.\n */\n\nimport { niceStep } from \"@motionscript/sdk/component\"\nimport type { PixelRect, PlaneMap } from \"./curve\"\n\n/** Where a 2D graph is looking, as the four numbers its props hold. */\nexport interface PlaneView {\n  /** Graph x at the centre of the node's box. */\n  centerX: number\n  /** Graph y at the centre of the node's box. */\n  centerY: number\n  /** Width of the visible window, in graph units. */\n  xSpan: number\n  /** Height of the visible window in graph units, or 0 to keep units square. */\n  ySpan: number\n}\n\n/**\n * Bounds on a span.\n *\n * A hundred decades inside the double's own range, so nothing downstream —\n * `width / span`, `step * scale`, `y * scale` — can overflow or fall into the\n * denormals on the way through.\n *\n * Deliberately far wider than anything usable, because what actually limits how\n * far a plane can be zoomed is not a floor on the span but a **ratio**:\n * `x - centerX` keeps about sixteen significant digits, so a window narrower\n * than `|centerX| · 4.3e-13` has fewer distinct representable x values across it\n * than it has pixels, and the curve staircases whatever these constants say.\n * That limit belongs to the *gesture* — see `planeSpanLimits` — which is the\n * thing a person can be stopped at. A scene that deliberately authored a deeper\n * zoom still renders, badly and visibly, rather than being silently clamped to\n * something it never asked for.\n */\nexport const MIN_SPAN = 1e-200\nexport const MAX_SPAN = 1e200\n\n/** A {@link PlaneView} resolved against a box: everything in concrete numbers. */\nexport interface ResolvedPlane extends PlaneMap {\n  /** The box, in node-local pixels. */\n  width: number\n  height: number\n  /** Visible graph range, low to high. */\n  xMin: number\n  xMax: number\n  yMin: number\n  yMax: number\n  /** The vertical span actually in force — the derived one when `ySpan` is 0. */\n  ySpan: number\n}\n\n/**\n * Resolves a view against the node's box: what a graph unit is worth in pixels,\n * and which part of the plane that puts on screen.\n *\n * The single place `ySpan: 0` is turned into a number, so nothing downstream —\n * the grid, the curves, the gesture — has to know the convention exists.\n */\nexport function resolvePlane(\n  view: PlaneView,\n  width: number,\n  height: number\n): ResolvedPlane {\n  const w = Math.max(1, width)\n  const h = Math.max(1, height)\n  const xSpan = clampSpan(view.xSpan)\n  const scaleX = w / xSpan\n  // Square units: a graph unit is the same number of pixels either way, so the\n  // visible height is however many of them fit in the box.\n  const ySpan = view.ySpan > 0 ? clampSpan(view.ySpan) : h / scaleX\n  const scaleY = h / ySpan\n\n  return {\n    centerX: view.centerX,\n    centerY: view.centerY,\n    scaleX,\n    scaleY,\n    width: w,\n    height: h,\n    xMin: view.centerX - xSpan / 2,\n    xMax: view.centerX + xSpan / 2,\n    yMin: view.centerY - ySpan / 2,\n    yMax: view.centerY + ySpan / 2,\n    ySpan,\n  }\n}\n\n/** Holds a span inside the range a double can still draw a grid over. */\nexport function clampSpan(span: number): number {\n  if (!Number.isFinite(span) || span <= 0) return MIN_SPAN\n  return Math.min(MAX_SPAN, Math.max(MIN_SPAN, span))\n}\n\n/** The node's box as a pixel rectangle, y-up and centred on the origin. */\nexport function planeBox(plane: ResolvedPlane): PixelRect {\n  return {\n    left: -plane.width / 2,\n    right: plane.width / 2,\n    bottom: -plane.height / 2,\n    top: plane.height / 2,\n  }\n}\n\n/** Grows a rectangle by `margin` on every side. */\nexport function inflate(rect: PixelRect, margin: number): PixelRect {\n  return {\n    left: rect.left - margin,\n    right: rect.right + margin,\n    bottom: rect.bottom - margin,\n    top: rect.top + margin,\n  }\n}\n\n/** Graph x → node-local pixels. */\nexport function toPx(plane: PlaneMap, x: number): number {\n  return (x - plane.centerX) * plane.scaleX\n}\n\n/** Graph y → node-local pixels, y-up. */\nexport function toPy(plane: PlaneMap, y: number): number {\n  return (y - plane.centerY) * plane.scaleY\n}\n\n// --- Moving the view -------------------------------------------------------\n\n/** Slides the view by a delta in **graph units**. Spans are untouched. */\nexport function panPlane(\n  view: PlaneView,\n  dx: number,\n  dy: number\n): PlaneView {\n  return {\n    ...view,\n    centerX: view.centerX + dx,\n    centerY: view.centerY + dy,\n  }\n}\n\n/**\n * Scales the view about a fixed point in **graph units** — the gesture every map\n * makes: whatever was under the cursor stays under the cursor.\n *\n * `factorX`/`factorY` are how much bigger the *window* gets, so a factor above 1\n * zooms out. Passing the same factor twice keeps a square grid square, and is\n * the only case that leaves an auto {@link PlaneView.ySpan} auto: scaling one\n * axis on its own is the statement \"this axis is mine now\", so the derived span\n * is written down and stops following the box.\n */\nexport function zoomPlane(\n  view: PlaneView,\n  plane: ResolvedPlane,\n  factorX: number,\n  factorY: number,\n  anchorX: number,\n  anchorY: number\n): PlaneView {\n  const uniform = factorX === factorY && view.ySpan <= 0\n  const xSpan = clampSpan(plane.xMax - plane.xMin) * factorX\n  const ySpan = plane.ySpan * factorY\n  return {\n    // The anchor keeps its distance from each edge as a *fraction* of the span,\n    // which is what \"stays under the cursor\" means once the span has changed.\n    //\n    // Written as a *displacement from the current centre* rather than as\n    // `anchor + (centre - anchor) · factor`, which is the same expression\n    // rearranged and much better conditioned. The anchor is up to half a span\n    // away from the centre, so at a wide view the direct form subtracts two\n    // enormous numbers to recover a small one and loses it: at a span of 1e200 a\n    // centre of 4 comes back as 0, and at a stop — where the factor is exactly 1\n    // and the centre must not move at all — it came back as 0 rather than as 4.\n    // This form multiplies the big quantity by `1 - factor`, which is what is\n    // actually small, and is bit-exact when the wheel is doing nothing.\n    centerX: view.centerX + (anchorX - view.centerX) * (1 - factorX),\n    centerY: view.centerY + (anchorY - view.centerY) * (1 - factorY),\n    xSpan: clampSpan(xSpan),\n    ySpan: uniform ? 0 : clampSpan(ySpan),\n  }\n}\n\n// --- Ticks -----------------------------------------------------------------\n\n/** One axis's tick ladder: where the numbers go and how finely to rule between. */\nexport interface TickLadder {\n  /** Distance between labelled ticks, in graph units. */\n  step: number\n  /** Distance between the faint lines between them. */\n  minorStep: number\n  /**\n   * Faint lines inside one labelled step — `step / minorStep`, as a whole\n   * number.\n   *\n   * The faint lines have no list of their own any more: they are generated by\n   * the plane's shader from a pitch and a phase, so what the ladder has to hand\n   * over is how many of them fit rather than where each one is. Building and\n   * filtering a few hundred numbers per axis per frame for a paint that never\n   * reads them was most of what the old ladder cost.\n   */\n  divisions: number\n  /** Labelled positions across the visible range, ascending. */\n  major: number[]\n}\n\n/**\n * Cap on how many *numbers* one axis may carry.\n *\n * The step is chosen from how close two labels may sit, so this is unreachable\n * in normal use — a 1920-px axis at the tightest legal pitch holds about\n * seventeen. It is there because `xSpan` is an animatable number and a tween\n * passing through an absurd value must not try to shape a thousand strings for\n * one frame. Half what it was, because it no longer bounds the grid: the shader\n * rules the plane at O(1) however far it is zoomed.\n */\nconst MAX_TICKS = 200\n\n/**\n * Largest tick index the ladder will build from.\n *\n * Past `2^53` an integer is no longer exactly representable, so `first + i`\n * repeats values and `(first + i) * step` produces garbage. At that view the\n * ticks genuinely have no distinct values, and an empty ladder says so.\n */\nconst MAX_INDEX = Number.MAX_SAFE_INTEGER\n\n/**\n * The decade a positive number sits in: `1` for 42, `-2` for 0.03.\n *\n * The nudge is not cosmetic. `Math.log10(1e-7)` is `-7.000000000000001` in V8,\n * so a bare `floor` answers -8 for an exact power of ten — which put the leading\n * digit of a 1e-7 step at 10 and handed {@link minorDivisions} the wrong answer\n * on several perfectly ordinary zooms.\n */\nfunction decadeOf(value: number): number {\n  return Math.floor(Math.log10(value) + 1e-12)\n}\n\n/**\n * The tick ladder for a range, at a scale, given the closest two labels may sit.\n *\n * Steps climb the 1–2–5 ladder, which is the one every plotting tool uses\n * because those are the numbers people can subdivide in their heads. Minor lines\n * subdivide a step into 5 — or into 4 when the step is a 2, so that the faint\n * lines land on halves rather than on fifths of a two.\n */\nexport function tickLadder(\n  min: number,\n  max: number,\n  pxPerUnit: number,\n  minSpacingPx: number\n): TickLadder {\n  const span = max - min\n  if (!(span > 0) || !(pxPerUnit > 0)) {\n    return { step: 1, minorStep: 1, divisions: 1, major: [] }\n  }\n\n  const step = niceStep(Math.max(minSpacingPx, 1) / pxPerUnit)\n  const divisions = minorDivisions(step)\n\n  return {\n    step,\n    minorStep: step / divisions,\n    divisions,\n    major: multiplesWithin(min, max, step),\n  }\n}\n\n/**\n * A digit's advance in the built-in face, as a fraction of the font size.\n *\n * Approximate on purpose: the node draws its numbers through the renderer's\n * shaper and this arithmetic runs in `scene-core`, which has no font metrics and\n * shouldn't grow any. It only has to be close enough to decide whether two\n * labels would collide, and it errs wide.\n */\nconst DIGIT_EM = 0.58\n/** Blank either side of a number, in font sizes. */\nconst LABEL_MARGIN = 0.8\n/**\n * Room an x-axis number needs before the ladder steps up, as multiples of its\n * font size — the pitch {@link labelLadder} widens *from*.\n *\n * Wider than the five characters it nominally buys, and left that way: it is\n * what every graph anywhere near the origin has always been ruled at, and\n * tightening it here would re-space every existing scene to fix a problem only\n * deep zoom has.\n */\nconst BASE_LABEL_PITCH = 5\n\n/**\n * A ladder whose numbers are guaranteed not to overlap, however long they are.\n *\n * The base pitch assumes a label of about five characters, which is what an\n * axis anywhere near the origin actually carries. Zoom to `x = 1.23456789` at a\n * span of 1e-6 and every number is fourteen, so the ladder is rebuilt once at a\n * pitch wide enough to hold the widest one it just produced. One extra pass and\n * not a loop: the second ladder is coarser than the first, so its labels are no\n * longer, and a third pass could only ever agree with the second.\n */\nexport function labelLadder(\n  min: number,\n  max: number,\n  pxPerUnit: number,\n  fontSize: number\n): TickLadder {\n  const base = fontSize * BASE_LABEL_PITCH\n  const ladder = tickLadder(min, max, pxPerUnit, base)\n  const needed = fontSize * labelWidthEm(ladder)\n  return needed > base ? tickLadder(min, max, pxPerUnit, needed) : ladder\n}\n\n/**\n * Room the widest number on `ladder` needs beside its neighbour, in font sizes.\n *\n * Also what the node aligns its numbers within — a right-aligned `-1200` and a\n * right-aligned `5` end in the same place only if the box holds the longer of\n * the two.\n */\nexport function labelWidthEm(ladder: TickLadder): number {\n  return DIGIT_EM * widestLabel(ladder) + LABEL_MARGIN\n}\n\n/**\n * How wide a number on this ladder can be, in characters.\n *\n * The longest is not always at an extreme — `-0.5` is longer than `10` — so this\n * scans, which costs at most {@link MAX_TICKS} formats and is a rounding error\n * beside the labels the node is about to shape anyway.\n */\nexport function widestLabel(ladder: TickLadder): number {\n  let widest = 0\n  for (const value of ladder.major) {\n    const length = formatTick(value, ladder.step).length\n    if (length > widest) widest = length\n  }\n  return widest\n}\n\n/**\n * How many faint lines a step is divided into. A 1 or a 5 takes five, a 2 takes\n * four — see {@link tickLadder}.\n */\nfunction minorDivisions(step: number): number {\n  const magnitude = Math.pow(10, decadeOf(step))\n  const leading = Math.round(step / magnitude)\n  return leading === 2 ? 4 : 5\n}\n\n/**\n * Every multiple of `step` within `[min, max]`, ascending.\n *\n * Built from an integer index times the step rather than by accumulation, so the\n * hundredth tick is still exactly a hundred steps out — repeated addition drifts\n * enough to put a `0.30000000000000004` on an axis.\n */\nfunction multiplesWithin(min: number, max: number, step: number): number[] {\n  // The nudge absorbs the case where a bound *is* a multiple and lands a hair\n  // outside it after the division, which would drop the tick on the edge.\n  const first = Math.ceil(min / step - 1e-9)\n  const last = Math.floor(max / step + 1e-9)\n  if (!Number.isFinite(first) || !Number.isFinite(last)) return []\n  if (Math.abs(first) > MAX_INDEX || Math.abs(last) > MAX_INDEX) return []\n\n  const count = last - first + 1\n  if (count <= 0 || count > MAX_TICKS) return []\n\n  const out: number[] = new Array(count)\n  for (let i = 0; i < count; i++) out[i] = (first + i) * step\n  return out\n}\n\n/**\n * Largest number of digits worth writing out in full, before the exponent is the\n * shorter answer.\n */\nconst MAX_DIGITS = 14\n/** `toFixed` and `toExponential` both refuse an argument past 100. */\nconst MAX_FRACTION = 100\n\n/**\n * A tick value as it is written on the axis.\n *\n * The precision comes from the **step**, not from the value: what a number on an\n * axis has to do is tell you which tick it is, so a ladder of 0.2s reads\n * `0.2 0.4 0.6` and the same values on a ladder of 1s would be rounded away\n * rather than shown as `0.2` next to `1`.\n *\n * That is also the rule for choosing the exponent, and the reason the two fixed\n * magnitude thresholds this used to carry are gone. `1e6` as a ceiling is wrong\n * about *both* directions at once: pan to `x = 1e7` at the default zoom and a\n * whole axis of distinct ticks reads `1e7`, `1e7`, `1e7`; while at a span of\n * 1e-9 around `x = 1` no threshold on the magnitude helps at all, because the\n * values are all near 1 and it is the *step* that has run out of room. What\n * decides it is how many significant digits it takes to tell two neighbouring\n * ticks apart: the exponent is only shorter when that count is small and the\n * number is far from 1.\n */\nexport function formatTick(value: number, step: number): string {\n  if (value === 0) return \"0\"\n  if (!Number.isFinite(value)) return \"\"\n  if (!(step > 0) || !Number.isFinite(step)) return String(value)\n\n  const decade = decadeOf(Math.abs(value))\n  // At least one: a value smaller than its own step isn't a tick of this ladder,\n  // but it is still a number somebody may ask this to write.\n  const digits = Math.max(1, decade - decadeOf(step) + 1)\n\n  // Far from 1 and cheap to write in scientific form — `2e7`, `1.5e-9`.\n  if ((decade >= 6 || decade <= -5) && digits <= 6) {\n    return trimExponent(value.toExponential(digits - 1))\n  }\n\n  if (digits <= MAX_DIGITS) {\n    const decimals = Math.min(MAX_FRACTION, Math.max(0, -decadeOf(step)))\n    const text = value.toFixed(decimals)\n    // `toFixed` keeps the zeros a nice step can't produce (0.50 for a 0.1 ladder\n    // is only ever written that way by the formatter).\n    return decimals > 0 ? text.replace(/\\.?0+$/, \"\") : text\n  }\n\n  // More digits than anybody can read off an axis. The exponent at least keeps\n  // the ticks distinguishable from one another.\n  const precision = Math.min(17, Math.max(0, digits - 1))\n  return trimExponent(value.toExponential(precision))\n}\n\n/** `1.20e-7` → `1.2e-7`, and `1.00e+21` → `1e21`. */\nfunction trimExponent(text: string): string {\n  const [mantissa, exponent] = text.split(\"e\")\n  const trimmed = mantissa.replace(/\\.?0+$/, \"\")\n  return `${trimmed}e${Number(exponent)}`\n}\n"]}

package/dist/graph2d/shared.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The mappers and tweens the {@link Graph2D} node is built from — the same shape
+ * `graph3d/impl/shared.ts` has, and mostly the same short list, because a
+ * `@property` is only as good as the `mapper`/`tween` it is declared with.
+ *
+ * Almost everything here is a re-export. That is the point: the match-by-id
+ * equation tween lives in `nodes/graph-kit` because both graphs animate a list of
+ * equations the same way, and colour normalisation lives in `nodes/view3d-kit`
+ * because the 3D nodes needed it first. What is genuinely this node's own is one
+ * function: turning a two-argument compiled expression into the one-argument
+ * curve the sampler asks for, without losing the identity the tween compares.
+ */
+import { type GraphEquationResolved } from "../kit/index.js";
+import type { CurveFunction } from "./curve.js";
+/**
+ * Colour normalisation and its tween, plus the two number tweens that fix what a
+ * plain lerp gets wrong.
+ *
+ * They live in `view3d-kit` because the 3D nodes needed them first, and there is
+ * nothing three-dimensional about any of them — a `NormalizedColor` is an RGBA
+ * tuple, which is both interpolatable and still a valid `Color` to hand back to
+ * `Graphics`. Renamed on the way through so the call sites don't read as though
+ * this node draws in perspective.
+ */
+export { resolveColor3D as resolveColor, lerpColor3D as lerpColor, lerpCount, snapFlag, snapValue, } from "@motionscript/sdk/component";
+/**
+ * One curve after {@link Graph2D}'s mapper has run: compiled, resolved and fully
+ * defaulted, so the per-frame draw never re-derives anything and the tween never
+ * tests for an absent field.
+ */
+export type CurveResolved = GraphEquationResolved<CurveFunction>;
+export declare function compileCurveCached(source: string): CurveFunction | null;
+/**
+ * Tween for the curve list — the shared match-by-id walk, with the one thing a
+ * curve does differently: mid-morph its height is sampled from both functions
+ * and blended, so it deforms into the new one rather than cross-fading through
+ * a frame where both are drawn.
+ */
+export declare function lerpCurves(from: CurveResolved[], to: CurveResolved[], t: number): CurveResolved[];
+//# sourceMappingURL=shared.d.ts.map

package/dist/graph2d/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/graph2d/shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAIL,KAAK,qBAAqB,EAC3B,MAAM,QAAQ,CAAA;AACf,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAE5C;;;;;;;;;GASG;AACH,OAAO,EACL,cAAc,IAAI,YAAY,EAC9B,WAAW,IAAI,SAAS,EACxB,SAAS,EACT,QAAQ,EACR,SAAS,GACV,MAAM,6BAA6B,CAAA;AAEpC;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,qBAAqB,CAAC,aAAa,CAAC,CAAA;AAoBhE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAYvE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,aAAa,EAAE,EACrB,EAAE,EAAE,aAAa,EAAE,EACnB,CAAC,EAAE,MAAM,GACR,aAAa,EAAE,CAEjB"}