@field/cascade 0.2.22 → 0.3.0

package/dist/runtime/geometry/svg.js

@@ -1,4 +1,4 @@
-import { Color, isStringAttribute, } from "cascade/contracts";
+import { Color, isStringAttribute, } from "@field/cascade/contracts";
 import { geometryError, numericAttribute, positionAttribute, readComponent, } from "./attributes.js";
 import { groupNames } from "./groups.js";
 import { bezierSegments, geometryBounds, isBezier, isClosed, loosePointMask, primitivePoints, } from "./primitives.js";

package/dist/runtime/geometry/transform.d.ts

@@ -1,4 +1,4 @@
-import { type Geometry, type Mat3, type Mat4 } from "cascade/contracts";
+import { type Geometry, type Mat3, type Mat4 } from "@field/cascade/contracts";
 /**
  * Transform `P`. Matrices are column-major, as the `mat3` and `mat4` types are
  * already documented to be, so a `mat3`'s third column carries the 2D

package/dist/runtime/geometry/transform.js

@@ -1,4 +1,4 @@
-import { POSITION_ATTRIBUTE, } from "cascade/contracts";
+import { POSITION_ATTRIBUTE, } from "@field/cascade/contracts";
 import { attributeSet, copyAttributeArray, geometryError, positionAttribute, withAttributeSet, } from "./attributes.js";
 /**
  * Transform `P`. Matrices are column-major, as the `mat3` and `mat4` types are

package/dist/runtime/index.d.ts

@@ -1,5 +1,8 @@
 export { CascadeRuntimeError } from "./error.js";
+export * from "./animation/index.js";
+export * from "./expressions/index.js";
 export * from "./geometry/index.js";
-export { createRuntime } from "./runtime.js";
+export * from "./params/index.js";
+export { createRuntime, PREFLIGHT_WARNING_CODES } from "./runtime.js";
 export type * from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.js

@@ -1,4 +1,7 @@
 export { CascadeRuntimeError } from "./error.js";
+export * from "./animation/index.js";
+export * from "./expressions/index.js";
 export * from "./geometry/index.js";
-export { createRuntime } from "./runtime.js";
+export * from "./params/index.js";
+export { createRuntime, PREFLIGHT_WARNING_CODES } from "./runtime.js";
 //# sourceMappingURL=index.js.map

package/dist/runtime/params/animator.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Resolving a graph's bound parameters at a frame.
+ *
+ * `resolvePropBinding` answers "what is this one parameter worth" and owns the
+ * order. This is the layer above it: a graph's worth of parameters, an
+ * expression engine bound to that graph, and the frame they are all resolved
+ * at. The deterministic runtime had neither half — it read `saved.value` and
+ * stopped — so a definition-v1 prop carrying `$T` or a drawn curve rendered as
+ * a constant offline while the same document animated in Studio.
+ *
+ * It is generic over the node rather than importing the runtime's own, so this
+ * file has no dependency on `runtime.ts` and can be exercised on its own.
+ *
+ * Resolution is LAZY and cycle-guarded, which is not a detail: `ch('../a/x')`
+ * may name a parameter that is itself an expression, and resolving in node
+ * order would hand out last frame's value for half the graph depending on
+ * where the reference pointed. Pulling on demand gives the same answer
+ * whatever order the nodes are in, which is the whole promise of the word
+ * deterministic.
+ */
+import type { PropBinding } from "./resolve.js";
+/** The minimum a node must be for its parameters to be resolvable. */
+export interface AnimatableNode {
+    readonly id: string;
+    /** Resolved values, written by `resolveAll`. */
+    readonly props: Record<string, unknown>;
+    readonly inputs: Record<string, unknown>;
+    /** Only the props that carry an expression or a channel. */
+    readonly bindings: Record<string, PropBinding>;
+}
+export interface PropAnimatorTopology<TNode extends AnimatableNode> {
+    readonly nodes: readonly TNode[];
+    node(id: string): TNode | undefined;
+    /** The node feeding `node`'s data input at `index`, for `opinput()`. */
+    inputNode(node: TNode, index: number): TNode | null;
+    /** A failed expression. The parameter has already fallen back to its stored
+     *  value; this is so the host can say so rather than render a wrong number
+     *  in silence. */
+    report?(nodeId: string, propName: string, error: string): void;
+}
+export declare class PropAnimator<TNode extends AnimatableNode> {
+    private readonly topology;
+    private readonly evaluator;
+    private readonly resolving;
+    constructor(topology: PropAnimatorTopology<TNode>);
+    /** True when any parameter in the graph is bound at all — so a host can skip
+     *  the whole pass, and a graph with no animation costs nothing. */
+    get animated(): boolean;
+    setFrame(frame: number): void;
+    setFps(fps: number): void;
+    /** Write every bound parameter's value at the current frame into `props`. */
+    resolveAll(): void;
+    /**
+     * One parameter, at the current frame.
+     *
+     * Re-entry returns the stored value rather than throwing: a parameter whose
+     * expression refers back to itself is an author's mistake, and the render
+     * that names it is more use than the one that dies.
+     */
+    private resolve;
+    /**
+     * The host binding the expression engine reads through.
+     *
+     * A path names a parameter — `./radius`, `../blur1/amount`,
+     * `/root/blur1/amount` — and the last segment is always the parameter, the
+     * one before it the node. Anything a graph does not have resolves to null,
+     * which the engine turns into 0 / '' / [] per accessor rather than an
+     * exception: one broken reference must not take a render down.
+     */
+    private scope;
+    /** The node a path's leading segments name, or `from` when they name none. */
+    private owner;
+}
+//# sourceMappingURL=animator.d.ts.map

package/dist/runtime/params/animator.js

@@ -0,0 +1,137 @@
+/**
+ * Resolving a graph's bound parameters at a frame.
+ *
+ * `resolvePropBinding` answers "what is this one parameter worth" and owns the
+ * order. This is the layer above it: a graph's worth of parameters, an
+ * expression engine bound to that graph, and the frame they are all resolved
+ * at. The deterministic runtime had neither half — it read `saved.value` and
+ * stopped — so a definition-v1 prop carrying `$T` or a drawn curve rendered as
+ * a constant offline while the same document animated in Studio.
+ *
+ * It is generic over the node rather than importing the runtime's own, so this
+ * file has no dependency on `runtime.ts` and can be exercised on its own.
+ *
+ * Resolution is LAZY and cycle-guarded, which is not a detail: `ch('../a/x')`
+ * may name a parameter that is itself an expression, and resolving in node
+ * order would hand out last frame's value for half the graph depending on
+ * where the reference pointed. Pulling on demand gives the same answer
+ * whatever order the nodes are in, which is the whole promise of the word
+ * deterministic.
+ */
+import { ExpressionEvaluator } from "../expressions/evaluator.js";
+import { isBoundProp, resolvePropBinding } from "./resolve.js";
+export class PropAnimator {
+    topology;
+    evaluator;
+    resolving = new Set();
+    constructor(topology) {
+        this.topology = topology;
+        this.evaluator = new ExpressionEvaluator(this.scope());
+    }
+    /** True when any parameter in the graph is bound at all — so a host can skip
+     *  the whole pass, and a graph with no animation costs nothing. */
+    get animated() {
+        return this.topology.nodes.some((node) => Object.values(node.bindings).some((binding) => isBoundProp(binding)));
+    }
+    setFrame(frame) {
+        this.evaluator.setFrame(frame);
+    }
+    setFps(fps) {
+        this.evaluator.setFps(fps);
+    }
+    /** Write every bound parameter's value at the current frame into `props`. */
+    resolveAll() {
+        for (const node of this.topology.nodes)
+            for (const name of Object.keys(node.bindings))
+                this.resolve(node, name);
+    }
+    /**
+     * One parameter, at the current frame.
+     *
+     * Re-entry returns the stored value rather than throwing: a parameter whose
+     * expression refers back to itself is an author's mistake, and the render
+     * that names it is more use than the one that dies.
+     */
+    resolve(node, name) {
+        const binding = node.bindings[name];
+        if (!binding)
+            return node.props[name];
+        const key = `${node.id}.${name}`;
+        if (this.resolving.has(key))
+            return binding.value;
+        this.resolving.add(key);
+        try {
+            const resolved = resolvePropBinding(binding, {
+                frame: this.evaluator.fframe,
+                evaluateExpression: (expression) => this.evaluator.evaluate(expression, node),
+            });
+            if (resolved.error)
+                this.topology.report?.(node.id, name, resolved.error);
+            node.props[name] = resolved.value;
+            return resolved.value;
+        }
+        finally {
+            this.resolving.delete(key);
+        }
+    }
+    /**
+     * The host binding the expression engine reads through.
+     *
+     * A path names a parameter — `./radius`, `../blur1/amount`,
+     * `/root/blur1/amount` — and the last segment is always the parameter, the
+     * one before it the node. Anything a graph does not have resolves to null,
+     * which the engine turns into 0 / '' / [] per accessor rather than an
+     * exception: one broken reference must not take a render down.
+     */
+    scope() {
+        return {
+            resolveParam: (from, path) => {
+                const segments = split(path);
+                if (!segments.length)
+                    return null;
+                const name = segments[segments.length - 1];
+                const owner = this.owner(from, segments.slice(0, -1));
+                if (!owner)
+                    return null;
+                // Through `resolve`, so a reference to a keyed or expressed parameter
+                // reads what it is worth at this frame rather than what it was saved
+                // as. Reading the stored value here is the bug that makes `ch()` look
+                // like it works until somebody keys the parameter it points at.
+                if (owner.bindings[name])
+                    return { value: this.resolve(owner, name) };
+                if (name in owner.props)
+                    return { value: owner.props[name] };
+                if (name in owner.inputs)
+                    return { value: owner.inputs[name] };
+                return null;
+            },
+            nodeExists: (from, path) => {
+                const segments = split(path);
+                if (!segments.length)
+                    return false;
+                const last = segments[segments.length - 1];
+                if (last === "..")
+                    return true;
+                return last === from.id || !!this.topology.node(last);
+            },
+            inputNode: (from, index) => this.topology.inputNode(from, index),
+        };
+    }
+    /** The node a path's leading segments name, or `from` when they name none. */
+    owner(from, segments) {
+        for (let i = segments.length - 1; i >= 0; i--) {
+            if (segments[i] === "..")
+                continue;
+            return this.topology.node(segments[i]);
+        }
+        return from;
+    }
+}
+/** Path segments, with the no-ops (`.`, empty, a trailing root slash) dropped
+ *  but `..` kept, because it is the one that means something. */
+function split(path) {
+    return String(path ?? "")
+        .split("/")
+        .filter((segment) => segment.length > 0 && segment !== ".");
+}
+//# sourceMappingURL=animator.js.map

package/dist/runtime/params/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Parameter resolution: the order in which a parameter becomes a value.
+ *
+ * One module, one order, both hosts. See ./resolve.ts for why evaluation
+ * itself is a callback rather than a dependency.
+ */
+export { PropAnimator } from "./animator.js";
+export type { AnimatableNode, PropAnimatorTopology } from "./animator.js";
+export { isBoundProp, resolvePropBinding, } from "./resolve.js";
+export type { PropBinding, PropBindingSource, PropResolutionContext, ResolvedProp, } from "./resolve.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/params/index.js

@@ -0,0 +1,9 @@
+/**
+ * Parameter resolution: the order in which a parameter becomes a value.
+ *
+ * One module, one order, both hosts. See ./resolve.ts for why evaluation
+ * itself is a callback rather than a dependency.
+ */
+export { PropAnimator } from "./animator.js";
+export { isBoundProp, resolvePropBinding, } from "./resolve.js";
+//# sourceMappingURL=index.js.map

package/dist/runtime/params/resolve.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The one place a parameter becomes a value.
+ *
+ * Three bindings, in one order: a keyframe channel, an expression, the stored
+ * value. That order was implemented once, in Studio's `Node.evalParm`, which
+ * meant the deterministic runtime had no answer at all — a definition-v1 prop
+ * carrying `$T` or a drawn curve rendered as a static number offline. Copying
+ * `evalParm` into the runtime would have produced a second answer to the same
+ * question, which is exactly the two-parameter-stores mistake this codebase
+ * has already paid for once. So the order moved here, into the neutral
+ * runtime, and both hosts call it.
+ *
+ * What it deliberately does NOT own: the expression *engine*. Evaluation is
+ * passed in as a callback, because each host has its own scope (Studio's
+ * `ExpressionEngine` reaches into the compatibility graph; the runtime binds
+ * its own node map) and its own error bookkeeping (Studio stores the message
+ * on the prop for the Inspector to show). Keeping evaluation out is also what
+ * keeps this module dependent on nothing but the channel sampler — no cycle
+ * between `animation` and `expressions`, and no clock anywhere: the frame is a
+ * value the caller hands in, which is what keeps a cook deterministic.
+ */
+import type { Channel } from "../animation/channel.js";
+/**
+ * A parameter and everything bound to it. Structurally what Studio's `Prop`
+ * already is, and what `CascadeSerializedProp` deserialises to, so neither
+ * host has to build an adapter object to ask this question.
+ */
+export interface PropBinding {
+    /** The stored value — what the author typed, and what the file records. */
+    readonly value: unknown;
+    readonly expression?: string | undefined;
+    readonly channel?: Channel | null | undefined;
+}
+/** Which of the three bindings actually produced the value. */
+export type PropBindingSource = "channel" | "expression" | "value";
+export interface ResolvedProp {
+    readonly value: unknown;
+    readonly source: PropBindingSource;
+    /** An expression that failed. The value has fallen back to the stored one. */
+    readonly error?: string;
+}
+export interface PropResolutionContext {
+    /** Fractional frame — a channel is sampled at it, and it is what the host's
+     *  expression engine should already be set to. */
+    readonly frame: number;
+    /**
+     * Evaluate one expression. Omitted by a caller with no engine (a static
+     * inspection), in which case an expression is skipped rather than guessed
+     * at and the stored value stands.
+     */
+    readonly evaluateExpression?: (expression: string) => {
+        value: unknown;
+        error?: string;
+    } | undefined;
+}
+/** True when a parameter carries something beyond its stored value, and so has
+ *  to be resolved per frame rather than read once. */
+export declare function isBoundProp(binding: PropBinding | null | undefined): boolean;
+/**
+ * Resolve a parameter at a frame.
+ *
+ * A parameter may carry both a channel and an expression, and the channel
+ * wins. The expression is kept, inert, and comes back when the channel is
+ * deleted: silently discarding what an author wrote is the worse of the two
+ * failures. `contracts/animation.ts` states the same rule for the document, so
+ * the file format and the resolver agree by construction.
+ *
+ * An empty channel resolves to nothing rather than to zero, so a parameter
+ * whose last key was deleted falls through to its expression or its value
+ * instead of snapping to the origin.
+ */
+export declare function resolvePropBinding(binding: PropBinding, context: PropResolutionContext): ResolvedProp;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/runtime/params/resolve.js

@@ -0,0 +1,62 @@
+/**
+ * The one place a parameter becomes a value.
+ *
+ * Three bindings, in one order: a keyframe channel, an expression, the stored
+ * value. That order was implemented once, in Studio's `Node.evalParm`, which
+ * meant the deterministic runtime had no answer at all — a definition-v1 prop
+ * carrying `$T` or a drawn curve rendered as a static number offline. Copying
+ * `evalParm` into the runtime would have produced a second answer to the same
+ * question, which is exactly the two-parameter-stores mistake this codebase
+ * has already paid for once. So the order moved here, into the neutral
+ * runtime, and both hosts call it.
+ *
+ * What it deliberately does NOT own: the expression *engine*. Evaluation is
+ * passed in as a callback, because each host has its own scope (Studio's
+ * `ExpressionEngine` reaches into the compatibility graph; the runtime binds
+ * its own node map) and its own error bookkeeping (Studio stores the message
+ * on the prop for the Inspector to show). Keeping evaluation out is also what
+ * keeps this module dependent on nothing but the channel sampler — no cycle
+ * between `animation` and `expressions`, and no clock anywhere: the frame is a
+ * value the caller hands in, which is what keeps a cook deterministic.
+ */
+import { isEmptyChannel, sampleChannel } from "../animation/channel.js";
+/** True when a parameter carries something beyond its stored value, and so has
+ *  to be resolved per frame rather than read once. */
+export function isBoundProp(binding) {
+    if (!binding)
+        return false;
+    return !!binding.expression || !isEmptyChannel(binding.channel);
+}
+/**
+ * Resolve a parameter at a frame.
+ *
+ * A parameter may carry both a channel and an expression, and the channel
+ * wins. The expression is kept, inert, and comes back when the channel is
+ * deleted: silently discarding what an author wrote is the worse of the two
+ * failures. `contracts/animation.ts` states the same rule for the document, so
+ * the file format and the resolver agree by construction.
+ *
+ * An empty channel resolves to nothing rather than to zero, so a parameter
+ * whose last key was deleted falls through to its expression or its value
+ * instead of snapping to the origin.
+ */
+export function resolvePropBinding(binding, context) {
+    if (!isEmptyChannel(binding.channel)) {
+        const sampled = sampleChannel(binding.channel, context.frame);
+        if (sampled !== undefined)
+            return { value: sampled, source: "channel" };
+    }
+    if (binding.expression && context.evaluateExpression) {
+        const result = context.evaluateExpression(binding.expression);
+        // A failed expression falls back to the stored value and reports why. The
+        // alternative — a hole in the middle of a render — is the one outcome
+        // nobody can act on.
+        if (result?.error) {
+            return { value: binding.value, source: "value", error: result.error };
+        }
+        if (result)
+            return { value: result.value, source: "expression" };
+    }
+    return { value: binding.value, source: "value" };
+}
+//# sourceMappingURL=resolve.js.map

package/dist/runtime/runtime.d.ts

@@ -1,3 +1,25 @@
 import type { CascadeRuntime, CreateRuntimeOptions } from "./types.js";
+/**
+ * Preflight codes that describe something other than "this graph cannot run
+ * here", so `run` proceeds and a checker reports them as warnings.
+ *
+ * False positives are worse than blindness: a validator that cries wolf gets
+ * ignored, and then it is no better than the one that saw nothing. So the line
+ * is drawn at what the diagnostic is about.
+ *
+ * `preflight-environment` is about the checker's reach — a node saying
+ * `runsOn: 'browser'` claims nothing about the CLI and is not defective
+ * because somebody validated it from a terminal.
+ *
+ * `stray-params` is about the document — values were lost on the way in, which
+ * is worth saying loudly and is not a reason to refuse to run: a graph with a
+ * leftover `params` array runs perfectly well on its defaults, which is
+ * precisely the problem.
+ *
+ * This set lives here rather than in the CLI because the run path and the
+ * check path both need it, and it was a duplicated rule that let `validate`
+ * and `check` pass graphs `run` then rejected.
+ */
+export declare const PREFLIGHT_WARNING_CODES: ReadonlySet<string>;
 export declare function createRuntime(options: CreateRuntimeOptions): CascadeRuntime;
 //# sourceMappingURL=runtime.d.ts.map