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

package/src/graph2d/plane.ts

@@ -0,0 +1,457 @@
+/**
+ * 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"
+import type { PixelRect, PlaneMap } from "./curve"
+
+/** 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 const MIN_SPAN = 1e-200
+export const MAX_SPAN = 1e200
+
+/** 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 function resolvePlane(
+  view: PlaneView,
+  width: number,
+  height: number
+): ResolvedPlane {
+  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: number): number {
+  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: ResolvedPlane): PixelRect {
+  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: PixelRect, margin: number): PixelRect {
+  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: PlaneMap, x: number): number {
+  return (x - plane.centerX) * plane.scaleX
+}
+
+/** Graph y → node-local pixels, y-up. */
+export function toPy(plane: PlaneMap, y: number): number {
+  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: PlaneView,
+  dx: number,
+  dy: number
+): PlaneView {
+  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: PlaneView,
+  plane: ResolvedPlane,
+  factorX: number,
+  factorY: number,
+  anchorX: number,
+  anchorY: number
+): PlaneView {
+  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),
+  }
+}
+
+// --- Ticks -----------------------------------------------------------------
+
+/** 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[]
+}
+
+/**
+ * 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: number): number {
+  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: number,
+  max: number,
+  pxPerUnit: number,
+  minSpacingPx: number
+): TickLadder {
+  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: number,
+  max: number,
+  pxPerUnit: number,
+  fontSize: number
+): TickLadder {
+  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: TickLadder): number {
+  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: TickLadder): number {
+  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: number): number {
+  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: number, max: number, step: number): number[] {
+  // 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: number[] = 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: number, step: number): string {
+  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: string): string {
+  const [mantissa, exponent] = text.split("e")
+  const trimmed = mantissa.replace(/\.?0+$/, "")
+  return `${trimmed}e${Number(exponent)}`
+}

package/src/graph2d/shared.ts

@@ -0,0 +1,103 @@
+/**
+ * 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 {
+  CURVE_VARIABLES,
+  compileExpressionCached,
+  lerpGraphEquations,
+  type GraphEquationResolved,
+} from "../kit"
+import type { CurveFunction } from "./curve"
+
+/**
+ * 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>
+
+/**
+ * Compiles `source` as `y = f(x)`, memoised, returning `null` for anything that
+ * doesn't parse.
+ *
+ * Two caches deep and both earn their place. The inner one memoises the *parse*,
+ * which is what keeps a node that re-draws sixty times a second from re-reading
+ * its own expressions; this one memoises the **adapter**, and without it every
+ * write would produce a fresh closure over the same parse — which the equation
+ * tween reads as "this expression changed" and would blend a function into
+ * itself, at double the sampling cost, for no visible difference.
+ *
+ * The adapter exists because arity is fixed in the parser for the sake of the
+ * hot path (see `CompiledExpression`) while the sampler quite reasonably wants
+ * to call `f(x)`. The unused second argument is 0 and unreachable: a curve is
+ * compiled with `x` as its only variable, so nothing in the tree reads it.
+ */
+const curves = new Map<string, CurveFunction | null>()
+
+export function compileCurveCached(source: string): CurveFunction | null {
+  const trimmed = source.trim()
+  if (trimmed === "") return null
+
+  const hit = curves.get(trimmed)
+  if (hit !== undefined) return hit
+
+  const compiled = compileExpressionCached(trimmed, CURVE_VARIABLES)
+  const curve: CurveFunction | null =
+    compiled === null ? null : (x: number) => compiled(x, 0)
+  curves.set(trimmed, curve)
+  return curve
+}
+
+/**
+ * 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 function lerpCurves(
+  from: CurveResolved[],
+  to: CurveResolved[],
+  t: number
+): CurveResolved[] {
+  return lerpGraphEquations(from, to, t, blendCurve)
+}
+
+/** How two curves blend mid-tween. */
+function blendCurve(
+  a: CurveFunction,
+  b: CurveFunction,
+  t: number
+): CurveFunction {
+  return (x) => {
+    const start = a(x)
+    return start + (b(x) - start) * t
+  }
+}

package/src/graph3d/expression.ts

@@ -0,0 +1,51 @@
+/**
+ * The `z = f(x, y)` expression language, as this node reaches for it.
+ *
+ * The parser itself now lives in `nodes/graph-kit/expression`, because the 2D
+ * graph writes its curves in the same language and neither node owns it — the
+ * same move `shared.ts` made when the Protein node needed the colour and camera
+ * helpers. What is left here is the *binding*: a surface's two free variables
+ * are `x` and `y`, which is the one thing about the grammar that differs between
+ * the two graphs, and every function below has it applied.
+ *
+ * Re-exported rather than re-implemented so this stays the one import a graph3d
+ * module reaches for, and so the vocabulary the inspector lists cannot drift
+ * from the names the parser will actually accept.
+ */
+
+import {
+  SURFACE_VARIABLES,
+  compileExpression as compile,
+  compileExpressionCached as compileCached,
+  expressionError as errorOf,
+  type CompiledExpression,
+} from "../kit/expression"
+
+export { EXPRESSION_VOCABULARY } from "../kit/expression"
+export type {
+  CompiledExpression,
+  ExpressionVocabulary,
+} from "../kit/expression"
+
+/** Compiles `source` as `z = f(x, y)`. Throws on a syntax error. */
+export function compileExpression(source: string): CompiledExpression {
+  return compile(source, SURFACE_VARIABLES)
+}
+
+/** Why `source` won't compile as `z = f(x, y)`, or `null` when it does. */
+export function expressionError(source: string): string | null {
+  return errorOf(source, SURFACE_VARIABLES)
+}
+
+/**
+ * Compiles with memoisation, returning `null` for anything that doesn't parse.
+ *
+ * The memoisation is what makes the equation tween cheap — equal source compiles
+ * to the identical closure, so "did this equation change" is an `===` — and what
+ * `surfaceRevision` reduces to a number. See the shared module for the rest.
+ */
+export function compileExpressionCached(
+  source: string
+): CompiledExpression | null {
+  return compileCached(source, SURFACE_VARIABLES)
+}