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

package/src/graph3d/shared.ts

@@ -0,0 +1,143 @@
+/**
+ * The mappers, tweens and small maths the {@link Graph3D} node is built from.
+ *
+ * These exist because a `@property` is only as good as the `mapper`/`tween` it
+ * is declared with: the mapper turns a loose authored value (a CSS colour, a
+ * partly-filled options bag) into one canonical internal shape, and the tween is
+ * what makes `node.to({ … })` *interpolate* that shape instead of holding the
+ * old value and snapping at the end. Core's own attributes are built the same
+ * way — see `cornerRadiusOps` behind `Rect.cornerRadius`.
+ *
+ * The colour, number and camera helpers this used to define now live in
+ * `nodes/view3d-kit`, because the Protein node needs the same six and none of
+ * them were ever about graphs. The equation list's shape and its tween moved the
+ * same way, into `nodes/graph-kit`, once the 2D graph needed both. They are
+ * re-exported here so this stays the one import a graph3d module reaches for.
+ */
+
+import { clamp } from "@motionscript/sdk"
+
+import {
+  lerpGraphEquations,
+  type GraphEquationResolved,
+} from "../kit/equations"
+
+export {
+  lerpColor3D,
+  lerpCount,
+  lerpFinite,
+  cameraOrbit,
+  resolveColor3D,
+  snapFlag,
+  type Orbit,
+} from "@motionscript/sdk/component"
+
+import type { CompiledExpression } from "./expression"
+
+// --- Sampling --------------------------------------------------------------
+
+/**
+ * Makes a sampled height safe to put in a vertex buffer.
+ *
+ * `NaN` (from `sqrt` of a negative, `log` of zero) poisons a whole triangle and
+ * leaves a hole; an asymptote (`1/x`, `tan`) produces values large enough to
+ * stretch the mesh off screen and wreck the camera framing. Both are flattened
+ * rather than dropped, so the surface stays continuous.
+ */
+export function sanitizeHeight(value: number, maxHeight: number): number {
+  if (!Number.isFinite(value)) return 0
+  return clamp(value, -maxHeight, maxHeight)
+}
+
+// --- Equations -------------------------------------------------------------
+
+/**
+ * One surface after {@link Graph3D}'s mapper has run: compiled, resolved and
+ * fully defaulted, so the per-frame builder never re-derives anything and the
+ * tween never tests for an absent field.
+ */
+export type EquationResolved = GraphEquationResolved<CompiledExpression>
+
+/**
+ * Tween for the equation list — the shared match-by-id walk, with the one thing
+ * a surface does differently: mid-morph its *height* is sampled from both
+ * functions and blended, so it deforms into the new one rather than popping.
+ *
+ * The blend deliberately returns a **fresh closure** per frame, which is what
+ * {@link surfaceRevision} reads as "re-evaluate this mesh".
+ */
+export function lerpEquations(
+  from: EquationResolved[],
+  to: EquationResolved[],
+  t: number
+): EquationResolved[] {
+  return lerpGraphEquations(from, to, t, blendSurface)
+}
+
+/** How two surfaces' heights blend mid-tween. */
+function blendSurface(
+  a: CompiledExpression,
+  b: CompiledExpression,
+  t: number
+): CompiledExpression {
+  return (x, y) => {
+    const start = a(x, y)
+    return start + (b(x, y) - start) * t
+  }
+}
+
+/**
+ * A small integer standing for a compiled expression's *identity*.
+ *
+ * `Geo.parametric`'s `revision` is a number, and what a surface's vertex callback
+ * actually depends on includes a function — so the function has to be reduced to
+ * something numeric. Identity is the right comparison here rather than the source
+ * text: `compileExpressionCached` memoises by source, so two equal sources are
+ * already `===`, and a mid-morph blend (see {@link blendEquation}) deliberately
+ * builds a *fresh* closure each frame, which is exactly when the surface must be
+ * re-evaluated.
+ *
+ * A `WeakMap` so retiring an expression doesn't pin it, and ids are never reused
+ * — a recycled id could make a changed surface look unchanged.
+ */
+const expressionIds = new WeakMap<CompiledExpression, number>()
+let nextExpressionId = 1
+
+function expressionId(sample: CompiledExpression): number {
+  let id = expressionIds.get(sample)
+  if (id === undefined) {
+    id = nextExpressionId++
+    expressionIds.set(sample, id)
+  }
+  return id
+}
+
+/**
+ * The `revision` for one surface: a value that changes exactly when its vertex
+ * callback would return something different.
+ *
+ * The callback in `Graph3D.addSurface` closes over three things — the compiled
+ * expression, the domain (as `span`/`domain`) and `maxHeight` — so those three
+ * are what this covers, and nothing else. `segments` is deliberately absent: it
+ * is plain data on the descriptor that the renderer already compares itself.
+ *
+ * Mixed by FNV-1a over the three values' text rather than by arithmetic, because
+ * `domain` and `maxHeight` are tweenable floats and there is no cheap numeric
+ * combination of two floats and an int that doesn't collide somewhere. A
+ * collision here would show as a surface that refuses to update, which is a
+ * miserable bug to find; the string is a few dozen characters per surface per
+ * frame, against the ~6.6k vertex evaluations it exists to avoid.
+ */
+export function surfaceRevision(
+  sample: CompiledExpression,
+  domain: number,
+  maxHeight: number
+): number {
+  const key = `${expressionId(sample)}|${domain}|${maxHeight}`
+  let hash = 0x811c9dc5
+  for (let i = 0; i < key.length; i++) {
+    hash ^= key.charCodeAt(i)
+    hash = Math.imul(hash, 0x01000193)
+  }
+  return hash >>> 0
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./graph2d";
+export * from "./graph3d";
+export { NODES } from "./nodes";

package/src/kit/equations.ts

@@ -0,0 +1,102 @@
+/**
+ * What a resolved equation is, and how a list of them interpolates — shared by
+ * both graph nodes because the answer doesn't depend on how many dimensions the
+ * marks are drawn in.
+ *
+ * The tween is the part worth sharing. Matching two lists by `id` is what makes
+ * an equation that stays *morph* rather than pop, one that leaves fade out as
+ * itself, and one that arrives fade in; getting that wrong is invisible until
+ * somebody animates an equation list, at which point every surface deforms into
+ * its neighbour. One implementation, one set of tests.
+ *
+ * What is *not* shared is how two sampled functions blend into one — a surface
+ * blends `f(x, y)` and a curve blends `f(x)` — so that is the one thing a caller
+ * passes in. See `graph3d/impl/shared` and `graph2d/impl/shared`, which are each
+ * three lines because of it.
+ */
+
+import { lerpNumber, type NormalizedColor } from "@motionscript/sdk"
+
+import { lerpColor3D } from "@motionscript/sdk/component"
+
+/**
+ * One equation after a node's mapper has run: compiled, resolved and fully
+ * defaulted, so the per-frame builder never re-derives anything and the tween
+ * never tests for an absent field.
+ *
+ * Generic in the sampled function because that is the only part that differs:
+ * `(x, y) => z` for a surface, `(x) => y` for a curve.
+ */
+export interface GraphEquationResolved<Sample> {
+  id: string
+  /** The compiled expression — compiled once at *write* time, not per sample. */
+  sample: Sample
+  color: NormalizedColor
+  /** `enabled: false` is folded in here as 0, so hiding is a fade. */
+  opacity: number
+}
+
+/**
+ * How two sampled functions blend mid-tween.
+ *
+ * Handed in rather than inferred, and it must return a **fresh closure per
+ * call** when the two differ: that freshness is what a node keyed on the
+ * function's identity reads as "this needs re-evaluating" (see
+ * `surfaceRevision`).
+ */
+export type BlendSample<Sample> = (a: Sample, b: Sample, t: number) => Sample
+
+/**
+ * Tween for an equation list: match by `id`, then morph / fade in / fade out.
+ *
+ * Three outcomes, and each is the one that reads correctly:
+ *
+ * - present in both → the mark **morphs**, because its value is sampled from
+ *   both functions and blended, so it deforms into the new one rather than
+ *   popping;
+ * - only in the old list → it fades out *still sampling its own expression*, so
+ *   it leaves as itself;
+ * - only in the new list → it fades in.
+ */
+export function lerpGraphEquations<Sample>(
+  from: GraphEquationResolved<Sample>[],
+  to: GraphEquationResolved<Sample>[],
+  t: number,
+  blendSample: BlendSample<Sample>
+): GraphEquationResolved<Sample>[] {
+  if (t <= 0) return from
+  if (t >= 1) return to
+
+  const arriving = new Map(to.map((equation) => [equation.id, equation]))
+  const out: GraphEquationResolved<Sample>[] = from.map((a) => {
+    const b = arriving.get(a.id)
+    return b
+      ? blendEquation(a, b, t, blendSample)
+      : { ...a, opacity: a.opacity * (1 - t) }
+  })
+
+  const held = new Set(from.map((equation) => equation.id))
+  for (const b of to) {
+    if (!held.has(b.id)) out.push({ ...b, opacity: b.opacity * t })
+  }
+  return out
+}
+
+/** Interpolates one equation that exists on both sides of the tween. */
+function blendEquation<Sample>(
+  a: GraphEquationResolved<Sample>,
+  b: GraphEquationResolved<Sample>,
+  t: number,
+  blendSample: BlendSample<Sample>
+): GraphEquationResolved<Sample> {
+  return {
+    id: b.id,
+    // Same id, different expression → morph the *geometry*. The double
+    // evaluation is only paid mid-tween, and the identity check skips it
+    // entirely when the source didn't change: the expression cache memoises by
+    // source, so equal source is `===`.
+    sample: a.sample === b.sample ? b.sample : blendSample(a.sample, b.sample, t),
+    color: lerpColor3D(a.color, b.color, t),
+    opacity: lerpNumber(a.opacity, b.opacity, t),
+  }
+}

package/src/kit/expression.ts

@@ -0,0 +1,323 @@
+/**
+ * The little language every graph node's equation tiles are written in — the
+ * one binding behind `z = f(x, y)` on the 3D graph and `y = f(x)` on the 2D one.
+ *
+ * **The grammar is not here.** It is the engine's `expressionOps.parse`
+ * (from `@motionscript/sdk`), shared with the `"=4[g]+3"` expressions a scene
+ * document writes in props. There used to be two parsers, and they agreed on
+ * every rule they documented while disagreeing everywhere they hadn't: this one
+ * scanned `1.2.3` as a single token that `Number` turned into a `NaN` which
+ * parsed, compiled and rendered an invisible surface with no diagnostic
+ * anywhere; it treated `\r` as an unexpected character; and it checked no arity
+ * on its variadic functions, so `atan2(1)` was a silent `NaN` too.
+ *
+ * What is genuinely this language's own is a **dialect** and a back end:
+ *
+ * - {@link PLOT_DIALECT} — trig in **radians** (a plot of `sin(x)` is a plot of
+ *   `sin(x)`, where a document's `rotation` is in degrees like every other angle
+ *   in the library), the hyperbolics and log bases a plot wants, `phi`, and
+ *   references spelled as bare identifiers rather than `[id]`.
+ * - {@link compileExpression} — the emitter, which turns the shared AST into a
+ *   two-argument closure rather than into the signal binding a document prop
+ *   needs.
+ *
+ * **Deliberately not `new Function(...)`.** An expression is a value typed into
+ * the inspector, stored in a scene document and shared with whoever opens it
+ * next; compiling it as JavaScript would make every scene file an execution
+ * vector. The shared parser accepts a fixed grammar and can only ever produce
+ * arithmetic.
+ *
+ * ## Which letters are variables is the caller's business
+ *
+ * What differs between the two graphs is *how many free variables there are*,
+ * and that matters more than it sounds. A 2D curve compiled with `x` alone
+ * rejects `y` as an unknown identifier, so typing `y = x + y` says so in the
+ * tile instead of silently plotting `x` — and a caller cannot forget to check,
+ * because the check is the same one that catches `alert(1)`.
+ */
+import { expressionOps } from "@motionscript/sdk"
+import type { ExpressionDialect, ExpressionNode } from "@motionscript/sdk"
+
+/**
+ * A compiled expression: pure, and safe to call thousands of times per frame.
+ *
+ * Always two arguments regardless of how many variables it was compiled with,
+ * because the arity is a *parse-time* fact and the signature is a hot path — a
+ * variadic form would allocate an array per sample. A one-variable expression
+ * simply never reads the second, so a curve calls it as `sample(x, 0)`.
+ */
+export type CompiledExpression = (x: number, y: number) => number
+
+/** The two free variables a `z = f(x, y)` surface is sampled over. */
+export const SURFACE_VARIABLES = ["x", "y"] as const
+
+/** The one free variable a `y = f(x)` curve is sampled over. */
+export const CURVE_VARIABLES = ["x"] as const
+
+/**
+ * The names bound to the two argument slots, in order.
+ *
+ * At most two, because {@link CompiledExpression} has two argument slots — see
+ * the note there on why that is fixed rather than variadic.
+ */
+export type ExpressionVariables = readonly string[]
+
+/** Single-argument functions available to an expression. */
+const UNARY_FNS: Record<string, (v: number) => number> = {
+  sin: Math.sin,
+  cos: Math.cos,
+  tan: Math.tan,
+  asin: Math.asin,
+  acos: Math.acos,
+  atan: Math.atan,
+  sinh: Math.sinh,
+  cosh: Math.cosh,
+  tanh: Math.tanh,
+  sqrt: Math.sqrt,
+  cbrt: Math.cbrt,
+  abs: Math.abs,
+  exp: Math.exp,
+  log: Math.log,
+  ln: Math.log,
+  log2: Math.log2,
+  log10: Math.log10,
+  floor: Math.floor,
+  ceil: Math.ceil,
+  round: Math.round,
+  sign: Math.sign,
+  trunc: Math.trunc,
+}
+
+/** Multi-argument functions. */
+const NARY_FNS: Record<string, (...args: number[]) => number> = {
+  atan2: Math.atan2,
+  pow: Math.pow,
+  hypot: Math.hypot,
+  min: Math.min,
+  max: Math.max,
+  mod: (a, b) => a % b,
+}
+
+/**
+ * How many arguments each of {@link NARY_FNS} takes.
+ *
+ * Written from what this language already accepts, not copied from core's table:
+ * `hypot(3)` and `min(3)` are meaningful and have always compiled, so they stay
+ * `[1, Infinity]` where the document dialect has `hypot: [2, Infinity]`. What
+ * the arity check is actually for is the other end — `atan2(1)` and `min()`
+ * used to compile to a silent `NaN` and an `Infinity`, which rendered as
+ * nothing at all and said nothing about why.
+ */
+const NARY_ARITY: Record<string, [number, number]> = {
+  atan2: [2, 2],
+  pow: [2, 2],
+  mod: [2, 2],
+  hypot: [1, Infinity],
+  min: [1, Infinity],
+  max: [1, Infinity],
+}
+
+const CONSTANTS: Record<string, number> = {
+  pi: Math.PI,
+  PI: Math.PI,
+  e: Math.E,
+  E: Math.E,
+  tau: Math.PI * 2,
+  phi: (1 + Math.sqrt(5)) / 2,
+}
+
+/** The equation language, as a dialect of the shared grammar. */
+export const PLOT_DIALECT: ExpressionDialect = {
+  functions: {
+    ...Object.fromEntries(
+      Object.keys(UNARY_FNS).map((name) => [name, { arity: [1, 1] as [number, number] }])
+    ),
+    ...Object.fromEntries(
+      Object.entries(NARY_ARITY).map(([name, arity]) => [name, { arity }])
+    ),
+  },
+  constants: CONSTANTS,
+  refs: "bare",
+  unknownName: (name) => `Unknown identifier '${name}'`,
+}
+
+/** Everything an expression may name, minus the variables. */
+const NAMEABLE = {
+  functions: [...Object.keys(UNARY_FNS), ...Object.keys(NARY_FNS)].sort(),
+  /** Lower-case spellings only; `PI`/`E` are accepted but not advertised twice. */
+  constants: ["pi", "e", "tau", "phi"] as const,
+}
+
+/** What a tile's help popover lists, for a node with these free variables. */
+export interface ExpressionVocabulary {
+  variables: readonly string[]
+  functions: readonly string[]
+  constants: readonly string[]
+}
+
+/**
+ * Everything an expression over `variables` may name, for the inspector's
+ * "what can I write here" hint.
+ *
+ * Derived from the parser's own tables rather than re-listed on the client, so
+ * the help can never claim a function the grammar doesn't have — which is the
+ * way this kind of reference always rots.
+ */
+export function expressionVocabulary(
+  variables: ExpressionVariables
+): ExpressionVocabulary {
+  return { variables, ...NAMEABLE }
+}
+
+/** {@link expressionVocabulary} for the 3D graph's `z = f(x, y)` surfaces. */
+export const EXPRESSION_VOCABULARY = expressionVocabulary(SURFACE_VARIABLES)
+
+/** {@link expressionVocabulary} for the 2D graph's `y = f(x)` curves. */
+export const CURVE_VOCABULARY = expressionVocabulary(CURVE_VARIABLES)
+
+/**
+ * Compiles `source` into a callable over `variables`. Throws on a syntax error,
+ * so a caller rendering user-typed text should catch and skip that equation —
+ * see {@link compileExpressionCached}, which does exactly that.
+ */
+export function compileExpression(
+  source: string,
+  variables: ExpressionVariables = SURFACE_VARIABLES
+): CompiledExpression {
+  // The parser folds a constant before it will yield a reference, so a name that
+  // is both would silently stop being the variable it was passed as.
+  for (const name of variables) {
+    if (name in CONSTANTS) {
+      throw new Error(`'${name}' is a constant, so it cannot also be a free variable`)
+    }
+  }
+  return emit(expressionOps.parse(source, PLOT_DIALECT).root, variables)
+}
+
+/** The shared AST into this language's two-argument closure. */
+function emit(
+  node: ExpressionNode,
+  variables: ExpressionVariables
+): CompiledExpression {
+  switch (node.kind) {
+    case "const": {
+      const { value } = node
+      return () => value
+    }
+    case "ref": {
+      // Which argument slot this name reads, or -1 for a name that isn't a
+      // variable *here* — the whole point of taking the list: `y` in a curve is
+      // an unknown identifier, not a silent zero.
+      const slot = variables.indexOf(node.name)
+      if (slot === 0) return (x) => x
+      if (slot === 1) return (_x, y) => y
+      throw new Error(PLOT_DIALECT.unknownName(node.name))
+    }
+    case "unary": {
+      const operand = emit(node.operand, variables)
+      return (x, y) => -operand(x, y)
+    }
+    case "binary": {
+      const l = emit(node.left, variables)
+      const r = emit(node.right, variables)
+      switch (node.op) {
+        case "+": return (x, y) => l(x, y) + r(x, y)
+        case "-": return (x, y) => l(x, y) - r(x, y)
+        case "*": return (x, y) => l(x, y) * r(x, y)
+        case "/": return (x, y) => l(x, y) / r(x, y)
+        case "%": return (x, y) => l(x, y) % r(x, y)
+        case "^": return (x, y) => Math.pow(l(x, y), r(x, y))
+      }
+      break
+    }
+    case "call": {
+      const args = node.args.map((arg) => emit(arg, variables))
+      const unary = UNARY_FNS[node.name]
+      if (unary) {
+        const [a] = args
+        return (x, y) => unary(a(x, y))
+      }
+      const nary = NARY_FNS[node.name]
+      // Specialise the common arity so the hot path doesn't allocate an array
+      // per sample.
+      if (args.length === 2) {
+        const [a, b] = args
+        return (x, y) => nary(a(x, y), b(x, y))
+      }
+      return (x, y) => nary(...args.map((arg) => arg(x, y)))
+    }
+  }
+  throw new Error("Unsupported expression node")
+}
+
+/**
+ * Why an expression won't compile, in the terms the tile shows: the message and
+ * nothing else. `null` means it compiles.
+ *
+ * Separate from {@link compileExpressionCached} because the two callers want
+ * opposite things — the renderer wants the function or nothing, the inspector
+ * wants the *reason* — and both must agree, which they do by going through the
+ * same parser.
+ */
+export function expressionError(
+  source: string,
+  variables: ExpressionVariables = SURFACE_VARIABLES
+): string | null {
+  const trimmed = source.trim()
+  // Empty is not an error: it is a tile nobody has filled in yet, which the
+  // panel already shows as a placeholder rather than as a mistake.
+  if (trimmed === "") return null
+  try {
+    compileExpression(trimmed, variables)
+    return null
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error)
+  }
+}
+
+/**
+ * Compiles with memoisation, returning `null` for anything that doesn't parse.
+ *
+ * Both halves matter here. A node's builder re-runs every frame, so an uncached
+ * compile would re-parse every equation sixty times a second; and the inspector
+ * commits on every keystroke, so half-typed source reaches the renderer
+ * constantly and must be *skipped* rather than thrown out of the render pass.
+ *
+ * The cache is also what makes the equation tween cheap: equal source compiles
+ * to the identical closure, so "did this equation change" is an `===`. Note it
+ * stores a failure as `null` and tests `hit !== undefined`, so unparseable
+ * source is not re-parsed on every frame either.
+ *
+ * Keyed by the variable list as well as the source, because the same text means
+ * different things under different bindings — `x + y` compiles for a surface and
+ * is an error for a curve, and one cache would hand the surface's answer to the
+ * curve that asked second.
+ */
+const caches = new Map<string, Map<string, CompiledExpression | null>>()
+
+export function compileExpressionCached(
+  source: string,
+  variables: ExpressionVariables = SURFACE_VARIABLES
+): CompiledExpression | null {
+  const trimmed = source.trim()
+  if (trimmed === "") return null
+
+  const key = variables.join(",")
+  let cache = caches.get(key)
+  if (!cache) {
+    cache = new Map()
+    caches.set(key, cache)
+  }
+
+  const hit = cache.get(trimmed)
+  if (hit !== undefined) return hit
+
+  let compiled: CompiledExpression | null
+  try {
+    compiled = compileExpression(trimmed, variables)
+  } catch {
+    compiled = null
+  }
+  cache.set(trimmed, compiled)
+  return compiled
+}

package/src/kit/index.ts

@@ -0,0 +1,29 @@
+/**
+ * The parts both graph nodes are built from — the expression language their
+ * tiles are written in, and what a resolved equation list is.
+ *
+ * A kit rather than a base class, for the same reason `view3d-kit` is one: the
+ * two graphs share a *vocabulary*, not a shape. One draws lit meshes through a
+ * 3D pass and the other draws stroked polylines into the 2D scene, and the only
+ * things they genuinely agree on are what an author is allowed to type and what
+ * happens to a list of those when it is animated.
+ */
+
+export {
+  compileExpression,
+  compileExpressionCached,
+  expressionError,
+  expressionVocabulary,
+  CURVE_VARIABLES,
+  CURVE_VOCABULARY,
+  EXPRESSION_VOCABULARY,
+  SURFACE_VARIABLES,
+} from "./expression"
+export type {
+  CompiledExpression,
+  ExpressionVariables,
+  ExpressionVocabulary,
+} from "./expression"
+
+export { lerpGraphEquations } from "./equations"
+export type { BlendSample, GraphEquationResolved } from "./equations"

package/src/nodes.ts

@@ -0,0 +1,19 @@
+import { Graph2D } from "./graph2d";
+import { Graph3D } from "./graph3d";
+
+/**
+ * Every node type this package publishes.
+ *
+ * A host registers these by handing the array to an engine —
+ * `new Engine(platform, { nodes: NODES })` — which reads each class's `@node()`
+ * key. The decorator only *declares* that key: nothing is registered by the mere
+ * act of importing a module, so a registry holds exactly what its owner asked
+ * for and two engines in one process can differ about it.
+ *
+ * Listing class **values** is also what survives bundling. This package declares
+ * `sideEffects: false`, which licenses a bundler to drop a module nothing
+ * imports a value from, and a document names a node type by string — so
+ * `import "./graph2d"` for its side effect is exactly what gets shaken out, where an
+ * array of bindings is a data dependency that cannot be.
+ */
+export const NODES = [Graph2D, Graph3D];

package/README.md

@@ -1,4 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
-If no other versions are published within 30 days, this package and version will be deleted.