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

package/dist/graph3d/shared.js

@@ -0,0 +1,101 @@
+/**
+ * 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/core";
+import { lerpGraphEquations, } from "../kit/equations.js";
+export { lerpColor3D, lerpCount, lerpFinite, cameraOrbit, resolveColor3D, snapFlag, } from "@motionscript/core/component";
+// --- 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, maxHeight) {
+    if (!Number.isFinite(value))
+        return 0;
+    return clamp(value, -maxHeight, maxHeight);
+}
+/**
+ * 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, to, t) {
+    return lerpGraphEquations(from, to, t, blendSurface);
+}
+/** How two surfaces' heights blend mid-tween. */
+function blendSurface(a, b, t) {
+    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();
+let nextExpressionId = 1;
+function expressionId(sample) {
+    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, domain, maxHeight) {
+    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;
+}
+//# sourceMappingURL=shared.js.map

package/dist/graph3d/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../src/graph3d/shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAE1C,OAAO,EACL,kBAAkB,GAEnB,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EACL,WAAW,EACX,SAAS,EACT,UAAU,EACV,WAAW,EACX,cAAc,EACd,QAAQ,GAET,MAAM,8BAA8B,CAAA;AAIrC,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa,EAAE,SAAiB;IAC7D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,CAAA;IACrC,OAAO,KAAK,CAAC,KAAK,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,CAAA;AAC5C,CAAC;AAWD;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAwB,EACxB,EAAsB,EACtB,CAAS;IAET,OAAO,kBAAkB,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,EAAE,YAAY,CAAC,CAAA;AACtD,CAAC;AAED,iDAAiD;AACjD,SAAS,YAAY,CACnB,CAAqB,EACrB,CAAqB,EACrB,CAAS;IAET,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACd,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;QACrB,OAAO,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAA;IACtC,CAAC,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,aAAa,GAAG,IAAI,OAAO,EAA8B,CAAA;AAC/D,IAAI,gBAAgB,GAAG,CAAC,CAAA;AAExB,SAAS,YAAY,CAAC,MAA0B;IAC9C,IAAI,EAAE,GAAG,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IAClC,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;QACrB,EAAE,GAAG,gBAAgB,EAAE,CAAA;QACvB,aAAa,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IAC/B,CAAC;IACD,OAAO,EAAE,CAAA;AACX,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe,CAC7B,MAA0B,EAC1B,MAAc,EACd,SAAiB;IAEjB,MAAM,GAAG,GAAG,GAAG,YAAY,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,SAAS,EAAE,CAAA;IAC5D,IAAI,IAAI,GAAG,UAAU,CAAA;IACrB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,IAAI,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAA;QACzB,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAA;IACpC,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,CAAA;AACnB,CAAC","sourcesContent":["/**\n * The mappers, tweens and small maths the {@link Graph3D} node is built from.\n *\n * These exist because a `@property` is only as good as the `mapper`/`tween` it\n * is declared with: the mapper turns a loose authored value (a CSS colour, a\n * partly-filled options bag) into one canonical internal shape, and the tween is\n * what makes `node.to({ … })` *interpolate* that shape instead of holding the\n * old value and snapping at the end. Core's own attributes are built the same\n * way — see `cornerRadiusOps` behind `Rect.cornerRadius`.\n *\n * The colour, number and camera helpers this used to define now live in\n * `nodes/view3d-kit`, because the Protein node needs the same six and none of\n * them were ever about graphs. The equation list's shape and its tween moved the\n * same way, into `nodes/graph-kit`, once the 2D graph needed both. They are\n * re-exported here so this stays the one import a graph3d module reaches for.\n */\n\nimport { clamp } from \"@motionscript/core\"\n\nimport {\n  lerpGraphEquations,\n  type GraphEquationResolved,\n} from \"../kit/equations\"\n\nexport {\n  lerpColor3D,\n  lerpCount,\n  lerpFinite,\n  cameraOrbit,\n  resolveColor3D,\n  snapFlag,\n  type Orbit,\n} from \"@motionscript/core/component\"\n\nimport type { CompiledExpression } from \"./expression\"\n\n// --- Sampling --------------------------------------------------------------\n\n/**\n * Makes a sampled height safe to put in a vertex buffer.\n *\n * `NaN` (from `sqrt` of a negative, `log` of zero) poisons a whole triangle and\n * leaves a hole; an asymptote (`1/x`, `tan`) produces values large enough to\n * stretch the mesh off screen and wreck the camera framing. Both are flattened\n * rather than dropped, so the surface stays continuous.\n */\nexport function sanitizeHeight(value: number, maxHeight: number): number {\n  if (!Number.isFinite(value)) return 0\n  return clamp(value, -maxHeight, maxHeight)\n}\n\n// --- Equations -------------------------------------------------------------\n\n/**\n * One surface after {@link Graph3D}'s mapper has run: compiled, resolved and\n * fully defaulted, so the per-frame builder never re-derives anything and the\n * tween never tests for an absent field.\n */\nexport type EquationResolved = GraphEquationResolved<CompiledExpression>\n\n/**\n * Tween for the equation list — the shared match-by-id walk, with the one thing\n * a surface does differently: mid-morph its *height* is sampled from both\n * functions and blended, so it deforms into the new one rather than popping.\n *\n * The blend deliberately returns a **fresh closure** per frame, which is what\n * {@link surfaceRevision} reads as \"re-evaluate this mesh\".\n */\nexport function lerpEquations(\n  from: EquationResolved[],\n  to: EquationResolved[],\n  t: number\n): EquationResolved[] {\n  return lerpGraphEquations(from, to, t, blendSurface)\n}\n\n/** How two surfaces' heights blend mid-tween. */\nfunction blendSurface(\n  a: CompiledExpression,\n  b: CompiledExpression,\n  t: number\n): CompiledExpression {\n  return (x, y) => {\n    const start = a(x, y)\n    return start + (b(x, y) - start) * t\n  }\n}\n\n/**\n * A small integer standing for a compiled expression's *identity*.\n *\n * `Geo.parametric`'s `revision` is a number, and what a surface's vertex callback\n * actually depends on includes a function — so the function has to be reduced to\n * something numeric. Identity is the right comparison here rather than the source\n * text: `compileExpressionCached` memoises by source, so two equal sources are\n * already `===`, and a mid-morph blend (see {@link blendEquation}) deliberately\n * builds a *fresh* closure each frame, which is exactly when the surface must be\n * re-evaluated.\n *\n * A `WeakMap` so retiring an expression doesn't pin it, and ids are never reused\n * — a recycled id could make a changed surface look unchanged.\n */\nconst expressionIds = new WeakMap<CompiledExpression, number>()\nlet nextExpressionId = 1\n\nfunction expressionId(sample: CompiledExpression): number {\n  let id = expressionIds.get(sample)\n  if (id === undefined) {\n    id = nextExpressionId++\n    expressionIds.set(sample, id)\n  }\n  return id\n}\n\n/**\n * The `revision` for one surface: a value that changes exactly when its vertex\n * callback would return something different.\n *\n * The callback in `Graph3D.addSurface` closes over three things — the compiled\n * expression, the domain (as `span`/`domain`) and `maxHeight` — so those three\n * are what this covers, and nothing else. `segments` is deliberately absent: it\n * is plain data on the descriptor that the renderer already compares itself.\n *\n * Mixed by FNV-1a over the three values' text rather than by arithmetic, because\n * `domain` and `maxHeight` are tweenable floats and there is no cheap numeric\n * combination of two floats and an int that doesn't collide somewhere. A\n * collision here would show as a surface that refuses to update, which is a\n * miserable bug to find; the string is a few dozen characters per surface per\n * frame, against the ~6.6k vertex evaluations it exists to avoid.\n */\nexport function surfaceRevision(\n  sample: CompiledExpression,\n  domain: number,\n  maxHeight: number\n): number {\n  const key = `${expressionId(sample)}|${domain}|${maxHeight}`\n  let hash = 0x811c9dc5\n  for (let i = 0; i < key.length; i++) {\n    hash ^= key.charCodeAt(i)\n    hash = Math.imul(hash, 0x01000193)\n  }\n  return hash >>> 0\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./graph2d/index.js";
+export * from "./graph3d/index.js";
+export { NODES } from "./nodes.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./graph2d/index.js";
+export * from "./graph3d/index.js";
+export { NODES } from "./nodes.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC","sourcesContent":["export * from \"./graph2d\";\nexport * from \"./graph3d\";\nexport { NODES } from \"./nodes\";\n"]}

package/dist/kit/equations.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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 { type NormalizedColor } from "@motionscript/core";
+/**
+ * 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 declare function lerpGraphEquations<Sample>(from: GraphEquationResolved<Sample>[], to: GraphEquationResolved<Sample>[], t: number, blendSample: BlendSample<Sample>): GraphEquationResolved<Sample>[];
+//# sourceMappingURL=equations.d.ts.map

package/dist/kit/equations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"equations.d.ts","sourceRoot":"","sources":["../../src/kit/equations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAIrE;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB,CAAC,MAAM;IAC3C,EAAE,EAAE,MAAM,CAAA;IACV,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,eAAe,CAAA;IACtB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,CAAC,MAAM,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;AAE7E;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EACvC,IAAI,EAAE,qBAAqB,CAAC,MAAM,CAAC,EAAE,EACrC,EAAE,EAAE,qBAAqB,CAAC,MAAM,CAAC,EAAE,EACnC,CAAC,EAAE,MAAM,EACT,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,GAC/B,qBAAqB,CAAC,MAAM,CAAC,EAAE,CAiBjC"}

package/dist/kit/equations.js

@@ -0,0 +1,63 @@
+/**
+ * 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 } from "@motionscript/core";
+import { lerpColor3D } from "@motionscript/core/component";
+/**
+ * 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(from, to, t, blendSample) {
+    if (t <= 0)
+        return from;
+    if (t >= 1)
+        return to;
+    const arriving = new Map(to.map((equation) => [equation.id, equation]));
+    const out = 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(a, b, t, blendSample) {
+    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),
+    };
+}
+//# sourceMappingURL=equations.js.map

package/dist/kit/equations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"equations.js","sourceRoot":"","sources":["../../src/kit/equations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,UAAU,EAAwB,MAAM,oBAAoB,CAAA;AAErE,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAA;AA6B1D;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAqC,EACrC,EAAmC,EACnC,CAAS,EACT,WAAgC;IAEhC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAA;IACvB,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAA;IAErB,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAA;IACvE,MAAM,GAAG,GAAoC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC1D,MAAM,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;QAC5B,OAAO,CAAC;YACN,CAAC,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,WAAW,CAAC;YACrC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAA;IAC5C,CAAC,CAAC,CAAA;IAEF,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAA;IACzD,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;QACnB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC,CAAA;IACjE,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,wEAAwE;AACxE,SAAS,aAAa,CACpB,CAAgC,EAChC,CAAgC,EAChC,CAAS,EACT,WAAgC;IAEhC,OAAO;QACL,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,mEAAmE;QACnE,qEAAqE;QACrE,2EAA2E;QAC3E,oCAAoC;QACpC,MAAM,EAAE,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QAC7E,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;QACvC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;KAC7C,CAAA;AACH,CAAC","sourcesContent":["/**\n * What a resolved equation is, and how a list of them interpolates — shared by\n * both graph nodes because the answer doesn't depend on how many dimensions the\n * marks are drawn in.\n *\n * The tween is the part worth sharing. Matching two lists by `id` is what makes\n * an equation that stays *morph* rather than pop, one that leaves fade out as\n * itself, and one that arrives fade in; getting that wrong is invisible until\n * somebody animates an equation list, at which point every surface deforms into\n * its neighbour. One implementation, one set of tests.\n *\n * What is *not* shared is how two sampled functions blend into one — a surface\n * blends `f(x, y)` and a curve blends `f(x)` — so that is the one thing a caller\n * passes in. See `graph3d/impl/shared` and `graph2d/impl/shared`, which are each\n * three lines because of it.\n */\n\nimport { lerpNumber, type NormalizedColor } from \"@motionscript/core\"\n\nimport { lerpColor3D } from \"@motionscript/core/component\"\n\n/**\n * One equation after a node's mapper has run: compiled, resolved and fully\n * defaulted, so the per-frame builder never re-derives anything and the tween\n * never tests for an absent field.\n *\n * Generic in the sampled function because that is the only part that differs:\n * `(x, y) => z` for a surface, `(x) => y` for a curve.\n */\nexport interface GraphEquationResolved<Sample> {\n  id: string\n  /** The compiled expression — compiled once at *write* time, not per sample. */\n  sample: Sample\n  color: NormalizedColor\n  /** `enabled: false` is folded in here as 0, so hiding is a fade. */\n  opacity: number\n}\n\n/**\n * How two sampled functions blend mid-tween.\n *\n * Handed in rather than inferred, and it must return a **fresh closure per\n * call** when the two differ: that freshness is what a node keyed on the\n * function's identity reads as \"this needs re-evaluating\" (see\n * `surfaceRevision`).\n */\nexport type BlendSample<Sample> = (a: Sample, b: Sample, t: number) => Sample\n\n/**\n * Tween for an equation list: match by `id`, then morph / fade in / fade out.\n *\n * Three outcomes, and each is the one that reads correctly:\n *\n * - present in both → the mark **morphs**, because its value is sampled from\n *   both functions and blended, so it deforms into the new one rather than\n *   popping;\n * - only in the old list → it fades out *still sampling its own expression*, so\n *   it leaves as itself;\n * - only in the new list → it fades in.\n */\nexport function lerpGraphEquations<Sample>(\n  from: GraphEquationResolved<Sample>[],\n  to: GraphEquationResolved<Sample>[],\n  t: number,\n  blendSample: BlendSample<Sample>\n): GraphEquationResolved<Sample>[] {\n  if (t <= 0) return from\n  if (t >= 1) return to\n\n  const arriving = new Map(to.map((equation) => [equation.id, equation]))\n  const out: GraphEquationResolved<Sample>[] = from.map((a) => {\n    const b = arriving.get(a.id)\n    return b\n      ? blendEquation(a, b, t, blendSample)\n      : { ...a, opacity: a.opacity * (1 - t) }\n  })\n\n  const held = new Set(from.map((equation) => equation.id))\n  for (const b of to) {\n    if (!held.has(b.id)) out.push({ ...b, opacity: b.opacity * t })\n  }\n  return out\n}\n\n/** Interpolates one equation that exists on both sides of the tween. */\nfunction blendEquation<Sample>(\n  a: GraphEquationResolved<Sample>,\n  b: GraphEquationResolved<Sample>,\n  t: number,\n  blendSample: BlendSample<Sample>\n): GraphEquationResolved<Sample> {\n  return {\n    id: b.id,\n    // Same id, different expression → morph the *geometry*. The double\n    // evaluation is only paid mid-tween, and the identity check skips it\n    // entirely when the source didn't change: the expression cache memoises by\n    // source, so equal source is `===`.\n    sample: a.sample === b.sample ? b.sample : blendSample(a.sample, b.sample, t),\n    color: lerpColor3D(a.color, b.color, t),\n    opacity: lerpNumber(a.opacity, b.opacity, t),\n  }\n}\n"]}

package/dist/kit/expression.d.ts

@@ -0,0 +1,60 @@
+import type { ExpressionDialect } from "@motionscript/core";
+/**
+ * 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 declare const SURFACE_VARIABLES: readonly ["x", "y"];
+/** The one free variable a `y = f(x)` curve is sampled over. */
+export declare const CURVE_VARIABLES: readonly ["x"];
+/**
+ * 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[];
+/** The equation language, as a dialect of the shared grammar. */
+export declare const PLOT_DIALECT: ExpressionDialect;
+/** 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 declare function expressionVocabulary(variables: ExpressionVariables): ExpressionVocabulary;
+/** {@link expressionVocabulary} for the 3D graph's `z = f(x, y)` surfaces. */
+export declare const EXPRESSION_VOCABULARY: ExpressionVocabulary;
+/** {@link expressionVocabulary} for the 2D graph's `y = f(x)` curves. */
+export declare const CURVE_VOCABULARY: ExpressionVocabulary;
+/**
+ * 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 declare function compileExpression(source: string, variables?: ExpressionVariables): CompiledExpression;
+/**
+ * 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 declare function expressionError(source: string, variables?: ExpressionVariables): string | null;
+export declare function compileExpressionCached(source: string, variables?: ExpressionVariables): CompiledExpression | null;
+//# sourceMappingURL=expression.d.ts.map

package/dist/kit/expression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expression.d.ts","sourceRoot":"","sources":["../../src/kit/expression.ts"],"names":[],"mappings":"AAsCA,OAAO,KAAK,EAAE,iBAAiB,EAAkB,MAAM,oBAAoB,CAAA;AAE3E;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;AAEjE,sEAAsE;AACtE,eAAO,MAAM,iBAAiB,qBAAsB,CAAA;AAEpD,gEAAgE;AAChE,eAAO,MAAM,eAAe,gBAAiB,CAAA;AAE7C;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,SAAS,MAAM,EAAE,CAAA;AAkEnD,iEAAiE;AACjE,eAAO,MAAM,YAAY,EAAE,iBAY1B,CAAA;AASD,8EAA8E;AAC9E,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;CAC7B;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,mBAAmB,GAC7B,oBAAoB,CAEtB;AAED,8EAA8E;AAC9E,eAAO,MAAM,qBAAqB,sBAA0C,CAAA;AAE5E,yEAAyE;AACzE,eAAO,MAAM,gBAAgB,sBAAwC,CAAA;AAErE;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,mBAAuC,GACjD,kBAAkB,CASpB;AA0DD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,mBAAuC,GACjD,MAAM,GAAG,IAAI,CAWf;AAsBD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,mBAAuC,GACjD,kBAAkB,GAAG,IAAI,CAsB3B"}

package/dist/kit/expression.js

@@ -0,0 +1,268 @@
+/**
+ * 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 `expressionOps.parse` in
+ * `@motionscript/core`, 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/core";
+/** The two free variables a `z = f(x, y)` surface is sampled over. */
+export const SURFACE_VARIABLES = ["x", "y"];
+/** The one free variable a `y = f(x)` curve is sampled over. */
+export const CURVE_VARIABLES = ["x"];
+/** Single-argument functions available to an expression. */
+const UNARY_FNS = {
+    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 = {
+    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 = {
+    atan2: [2, 2],
+    pow: [2, 2],
+    mod: [2, 2],
+    hypot: [1, Infinity],
+    min: [1, Infinity],
+    max: [1, Infinity],
+};
+const CONSTANTS = {
+    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 = {
+    functions: {
+        ...Object.fromEntries(Object.keys(UNARY_FNS).map((name) => [name, { arity: [1, 1] }])),
+        ...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"],
+};
+/**
+ * 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) {
+    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, variables = SURFACE_VARIABLES) {
+    // 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, variables) {
+    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, variables = SURFACE_VARIABLES) {
+    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();
+export function compileExpressionCached(source, variables = SURFACE_VARIABLES) {
+    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;
+    try {
+        compiled = compileExpression(trimmed, variables);
+    }
+    catch {
+        compiled = null;
+    }
+    cache.set(trimmed, compiled);
+    return compiled;
+}
+//# sourceMappingURL=expression.js.map