@field/cascade 0.2.22 → 0.3.1

package/dist/runtime/expressions/time.js

@@ -0,0 +1,71 @@
+/**
+ * Time state for expression evaluation.
+ *
+ * Frames are stored as a real number so sub-frame time exists. `frame` is the
+ * integer frame ($F), `frameFraction` is the exact fractional frame ($FF), and
+ * `time` is seconds ($T). Nothing here reads a clock: time is set by the caller
+ * (a cook request, a frame-range loop, a transport) and the engine only ever
+ * reports what it was told. That is what keeps a cook deterministic.
+ */
+export const DEFAULT_FPS = 30;
+export const MIN_FRAME = 1;
+export class TimeState {
+    /** Exact, possibly fractional frame. Never below MIN_FRAME. */
+    _frame = MIN_FRAME;
+    _fps = DEFAULT_FPS;
+    /**
+     * Set the current frame. Fractional values are preserved; only the lower
+     * bound is enforced. Non-finite input is ignored.
+     */
+    setFrame(frame) {
+        if (!Number.isFinite(frame))
+            return;
+        this._frame = Math.max(MIN_FRAME, frame);
+    }
+    /** Set the current time in seconds, keeping the sub-frame remainder. */
+    setTime(seconds) {
+        if (!Number.isFinite(seconds))
+            return;
+        this.setFrame(seconds * this._fps + MIN_FRAME);
+    }
+    setFps(fps) {
+        if (!Number.isFinite(fps))
+            return;
+        this._fps = Math.max(1, fps);
+    }
+    /** Integer frame — $F. */
+    get frame() {
+        return Math.floor(this._frame);
+    }
+    /** Fractional frame — $FF. */
+    get frameFraction() {
+        return this._frame;
+    }
+    /**
+     * Seconds — $T. Derived from the fractional frame, so it round-trips.
+     *
+     * Zero at the first frame, which is Houdini's convention: $T = ($FF - 1)/$FPS.
+     * The previous definition was frame/fps, making $T equal 1/fps at frame 1 —
+     * so `sin($T)` started part-way through its cycle and an animation's first
+     * frame was never t=0. Changed 2026-09-07 because Marcus named Houdini as the
+     * reference for these variables, and because "time starts at zero" is the
+     * thing anybody writing an expression will assume.
+     */
+    get time() {
+        return (this._frame - MIN_FRAME) / this._fps;
+    }
+    /** Frame rate — $FPS. */
+    get fps() {
+        return this._fps;
+    }
+    /** Immutable snapshot of the four time variables. */
+    snapshot() {
+        return {
+            frame: this.frame,
+            frameFraction: this.frameFraction,
+            time: this.time,
+            fps: this.fps
+        };
+    }
+}
+//# sourceMappingURL=time.js.map

package/dist/runtime/expressions/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Expression types.
+ *
+ * These live in the runtime rather than in contracts because a compiled
+ * expression carries a function, so it is runtime machinery rather than a
+ * serializable DTO. Contracts stays dependency-free and data-only.
+ */
+import type { Node as NodeShape } from "./scope.js";
+/**
+ * The context an expression is evaluated against. Everything an expression can
+ * see is on this object — there is no ambient global, and in particular no
+ * clock: the time variables are values placed here by the caller.
+ */
+export interface ExpressionContext<TNode = NodeShape> {
+    /** seconds — $T */
+    time: number;
+    /** integer frame — $F */
+    frame: number;
+    /** fractional frame — $FF */
+    fframe: number;
+    /** rate — $FPS */
+    fps: number;
+    /** The node whose parameter is being evaluated. */
+    self: TNode;
+    ch: (path: string) => number;
+    chs: (path: string) => string;
+    chv: (path: string) => number[];
+    opexist: (path: string) => 0 | 1;
+    opinput: (index: number) => TNode | null;
+    fit: (value: number, oldMin: number, oldMax: number, newMin: number, newMax: number) => number;
+    fit01: (value: number, newMin: number, newMax: number) => number;
+    clamp: (value: number, min: number, max: number) => number;
+    lerp: (a: number, b: number, t: number) => number;
+    smooth: (value: number, min: number, max: number) => number;
+    noise: (...coords: number[]) => number;
+    random: (seed: number) => number;
+    padzero: (digits: number, value: number) => string;
+    Math: typeof Math;
+}
+/** A compiled, cached expression ready to evaluate against a context. */
+export interface CompiledExpression<TNode = NodeShape> {
+    /** The expression as authored, `$` spellings intact. */
+    source: string;
+    /** The expression after `$` preprocessing — what was actually compiled. */
+    compiledSource: string;
+    evaluate: (context: ExpressionContext<TNode>) => unknown;
+    /** Parameter paths referenced through ch/chs/chv, for dirty tracking. */
+    dependencies: string[];
+    /** True if the expression references any time variable, in either spelling. */
+    isTimeDependent: boolean;
+    error?: string;
+}
+/** Result of evaluating one expression. */
+export interface ExpressionResult {
+    value: unknown;
+    error?: string;
+}
+/** A referenced path that does not resolve. */
+export interface PathWarning {
+    nodeId: string;
+    nodePath: string;
+    propName: string;
+    expression: string;
+    brokenPath: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/runtime/expressions/types.js

@@ -0,0 +1,9 @@
+/**
+ * Expression types.
+ *
+ * These live in the runtime rather than in contracts because a compiled
+ * expression carries a function, so it is runtime machinery rather than a
+ * serializable DTO. Contracts stays dependency-free and data-only.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -1,4 +1,4 @@
-import { type AnyAttribute, type Attribute, type AttributeLevel, type AttributeSet, type AttributeStorage, type DetailValue, type ElementLevel, type Geometry, type StringAttribute } from "cascade/contracts";
+import { type AnyAttribute, type Attribute, type AttributeLevel, type AttributeSet, type AttributeStorage, type DetailValue, type ElementLevel, type Geometry, type StringAttribute } from "@field/cascade/contracts";
 /**
  * Attribute reads and writes. Every write returns a new `Geometry` and shares
  * the arrays it did not touch, which is the whole reason the format is
@@ -61,5 +61,5 @@ export interface AttributeCreateOptions {
  */
 export declare function attributeCreate(geometry: Geometry, options: AttributeCreateOptions): Geometry;
 /** A same-storage copy of an attribute's array, for a write-in-place pass. */
-export declare function copyAttributeArray(attribute: Attribute): import("cascade/contracts").AttributeArray;
+export declare function copyAttributeArray(attribute: Attribute): import("@field/cascade/contracts").AttributeArray;
 //# sourceMappingURL=attributes.d.ts.map

package/dist/runtime/geometry/attributes.js

@@ -1,4 +1,4 @@
-import { attributeArray, attributeArrayFrom, createGeometry, isStringAttribute, levelCount, POSITION_ATTRIBUTE, } from "cascade/contracts";
+import { attributeArray, attributeArrayFrom, createGeometry, isStringAttribute, levelCount, POSITION_ATTRIBUTE, } from "@field/cascade/contracts";
 /**
  * Attribute reads and writes. Every write returns a new `Geometry` and shares
  * the arrays it did not touch, which is the whole reason the format is

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

@@ -1,4 +1,4 @@
-import { emptyGeometry, type AnyAttribute, type AttributeStorage, type DetailValue, type ElementLevel, type Geometry, type PrimitiveKind } from "cascade/contracts";
+import { emptyGeometry, type AnyAttribute, type AttributeStorage, type DetailValue, type ElementLevel, type Geometry, type PrimitiveKind } from "@field/cascade/contracts";
 export { emptyGeometry };
 export interface GeometryBuilderOptions {
     /** 2 by default: the reference workloads are two-component. */

package/dist/runtime/geometry/builder.js

@@ -1,4 +1,4 @@
-import { attributeArrayFrom, createGeometry, emptyGeometry, POSITION_ATTRIBUTE, PRIMITIVE_KINDS, } from "cascade/contracts";
+import { attributeArrayFrom, createGeometry, emptyGeometry, POSITION_ATTRIBUTE, PRIMITIVE_KINDS, } from "@field/cascade/contracts";
 import { createStringAttribute, geometryError } from "./attributes.js";
 export { emptyGeometry };
 /**

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

@@ -1,4 +1,4 @@
-import { type Geometry } from "cascade/contracts";
+import { type Geometry } from "@field/cascade/contracts";
 /**
  * Copy to Points: one geometry instanced onto every point of another.
  *

package/dist/runtime/geometry/copy.js

@@ -1,4 +1,4 @@
-import { emptyGeometry, isStringAttribute, POSITION_ATTRIBUTE, } from "cascade/contracts";
+import { emptyGeometry, isStringAttribute, POSITION_ATTRIBUTE, } from "@field/cascade/contracts";
 import { createAttribute, createStringAttribute, geometryError, getPosition, numericAttribute, positionSize, readComponent, readElement, readString, setAttribute, } from "./attributes.js";
 import { groupIndices, groupMask } from "./groups.js";
 import { transformMatrix } from "./matrix.js";

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

@@ -1,4 +1,4 @@
-import type { Geometry } from "cascade/contracts";
+import type { Geometry } from "@field/cascade/contracts";
 /**
  * The generators. Each returns one primitive in a geometry of its own, so a
  * graph composes them with `Merge` rather than with a multi-shape node.

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

@@ -1,4 +1,4 @@
-import { type Geometry } from "cascade/contracts";
+import { type Geometry } from "@field/cascade/contracts";
 /**
  * Groups are named subsets, stored as one byte per element. A mask is the right
  * shape because membership is tested far more often than it is enumerated, and

package/dist/runtime/geometry/groups.js

@@ -1,4 +1,4 @@
-import { createGeometry, levelCount } from "cascade/contracts";
+import { createGeometry, levelCount } from "@field/cascade/contracts";
 import { geometryError } from "./attributes.js";
 const KEYS = {
     point: "pointGroups",

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

@@ -1,4 +1,4 @@
-import type { Mat3 } from "cascade/contracts";
+import type { Mat3 } from "@field/cascade/contracts";
 /**
  * The `mat3` a transform node or an instancing operation needs, built from the
  * four parameters a Houdini user already knows: translate, rotate, scale and

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

@@ -1,4 +1,4 @@
-import { type AttributeStorage, type Geometry } from "cascade/contracts";
+import { type AttributeStorage, type Geometry } from "@field/cascade/contracts";
 /**
  * Merge concatenates geometries and renumbers points, vertices and primitives.
  *

package/dist/runtime/geometry/merge.js

@@ -1,4 +1,4 @@
-import { attributeArray, createGeometry, emptyGeometry, isStringAttribute, levelCount, } from "cascade/contracts";
+import { attributeArray, createGeometry, emptyGeometry, isStringAttribute, levelCount, } from "@field/cascade/contracts";
 import { createStringAttribute, geometryError, readString } from "./attributes.js";
 /**
  * Merge concatenates geometries and renumbers points, vertices and primitives.

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

@@ -1,4 +1,4 @@
-import type { Geometry, PrimitiveKind } from "cascade/contracts";
+import type { Geometry, PrimitiveKind } from "@field/cascade/contracts";
 /** Topology and measurement reads that the operations share. */
 export declare function primitiveKind(geometry: Geometry, primitive: number): PrimitiveKind;
 export declare function isClosed(geometry: Geometry, primitive: number): boolean;

package/dist/runtime/geometry/primitives.js

@@ -1,4 +1,4 @@
-import { BEZIER_STRIDE, PRIMITIVE_KINDS } from "cascade/contracts";
+import { BEZIER_STRIDE, PRIMITIVE_KINDS } from "@field/cascade/contracts";
 import { geometryError, positionAttribute, positionSize, } from "./attributes.js";
 /** Topology and measurement reads that the operations share. */
 export function primitiveKind(geometry, primitive) {

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

@@ -1,4 +1,4 @@
-import { type AttributeLevel, type ElementLevel, type Geometry } from "cascade/contracts";
+import { type AttributeLevel, type ElementLevel, type Geometry } from "@field/cascade/contracts";
 /**
  * Moving an attribute between levels, and copying one between geometries.
  *

package/dist/runtime/geometry/promote.js

@@ -1,4 +1,4 @@
-import { attributeArray, isStringAttribute, levelCount, POSITION_ATTRIBUTE, } from "cascade/contracts";
+import { attributeArray, isStringAttribute, levelCount, POSITION_ATTRIBUTE, } from "@field/cascade/contracts";
 import { createStringAttribute, geometryError, readString, removeAttribute, removeDetail, setAttribute, setDetail, } from "./attributes.js";
 /**
  * Which source elements feed each target element. This one table is the whole

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

@@ -1,4 +1,4 @@
-import { type Geometry } from "cascade/contracts";
+import { type Geometry } from "@field/cascade/contracts";
 /**
  * Rewrite each primitive at a uniform arc-length spacing, or at a target
  * vertex count. Most curve operations want a uniformly sampled chain, so this

package/dist/runtime/geometry/resample.js

@@ -1,4 +1,4 @@
-import { attributeArray, createGeometry, isStringAttribute, } from "cascade/contracts";
+import { attributeArray, createGeometry, isStringAttribute, } from "@field/cascade/contracts";
 import { createStringAttribute, geometryError, readString, } from "./attributes.js";
 import { groupMask } from "./groups.js";
 import { arcLengths, isBezier, isClosed, loosePointMask, primitivePoints, } from "./primitives.js";

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

@@ -1,4 +1,4 @@
-import { Color, type Geometry } from "cascade/contracts";
+import { Color, type Geometry } from "@field/cascade/contracts";
 /**
  * Geometry to an SVG document. The node that makes the library provably useful,
  * because it produces a file to print or plot rather than an assertion.

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