@field/cascade 0.2.22 → 0.3.1

package/dist/runtime/animation/channel.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Keyframe channels, neutral runtime.
+ *
+ * A channel is the third way a parameter becomes a value, beside a literal and
+ * an expression. It is an ordered list of keys and a rule for what happens
+ * between them, and it is sampled — never pushed. The host asks for the value
+ * at a frame; nothing here holds a clock, a graph or a node, which is what
+ * keeps the whole thing deterministic and testable on its own.
+ *
+ * `sin($T)` and a drawn curve are the same shape: one written, one drawn.
+ *
+ * Every function here is pure. A channel is treated as immutable — `setKey`
+ * and `deleteKey` return a new channel rather than editing one in place — so a
+ * caller can hold a channel across a cook without it changing underneath.
+ */
+/**
+ * What happens between a key and the next one. The mode belongs to the key on
+ * the LEFT of a segment: it describes how the value leaves that key.
+ *
+ *   constant — hold the left value until the next key. Steps, not motion
+ *   linear   — straight line. Constant velocity, visible corners at the keys
+ *   smooth   — Hermite with automatic tangents. The default, because linear
+ *              everywhere is how animation looks when nobody chose
+ */
+export type Interpolation = "constant" | "linear" | "smooth";
+/** Smooth, deliberately: an unset default of `linear` animates like a robot. */
+export declare const DEFAULT_INTERPOLATION: Interpolation;
+export declare function isInterpolation(value: unknown): value is Interpolation;
+/** One key. `frame` may be fractional; `value` is a plain number. */
+export interface Keyframe {
+    readonly frame: number;
+    readonly value: number;
+    readonly interpolation: Interpolation;
+}
+/** A key as a caller may hand it in — interpolation optional. */
+export interface KeyframeInput {
+    readonly frame: number;
+    readonly value: number;
+    readonly interpolation?: Interpolation | string;
+}
+/**
+ * An animated parameter. `keys` is always sorted by frame and holds at most
+ * one key per frame — `createChannel` is the only way that invariant is
+ * established, and every other function here preserves it.
+ */
+export interface Channel {
+    readonly keys: readonly Keyframe[];
+}
+/** The empty channel. Sampling it returns undefined, so a caller falls back. */
+export declare const EMPTY_CHANNEL: Channel;
+/**
+ * Build a channel from keys in any order, with anything unusable dropped.
+ *
+ * Unordered input is sorted rather than rejected — a file edited by hand and a
+ * UI that appends are both legitimate sources. A duplicate frame keeps the
+ * LAST key given, which is what "set this key again" means.
+ */
+export declare function createChannel(keys?: readonly KeyframeInput[]): Channel;
+export declare function isChannel(value: unknown): value is Channel;
+/** A channel with no keys resolves to nothing, so the raw value still applies. */
+export declare function isEmptyChannel(channel: Channel | null | undefined): boolean;
+export declare function keyAt(channel: Channel, frame: number): Keyframe | undefined;
+/**
+ * Set a key, replacing any key already on that frame.
+ *
+ * Re-keying an existing frame keeps that key's interpolation unless a new one
+ * is given: dragging a value should not silently change its easing.
+ */
+export declare function setKey(channel: Channel | null | undefined, frame: number, value: number, interpolation?: Interpolation): Channel;
+/** Remove the key on that frame. Removing the last key leaves an empty channel. */
+export declare function deleteKey(channel: Channel | null | undefined, frame: number): Channel;
+/** Change one key's outgoing interpolation without touching its value. */
+export declare function setKeyInterpolation(channel: Channel | null | undefined, frame: number, interpolation: Interpolation): Channel;
+/**
+ * The value at any frame, fractional included.
+ *
+ * Returns undefined for a channel with no keys — that is the signal to fall
+ * back to the parameter's raw value rather than to invent a zero.
+ *
+ * Outside the key range the end values are HELD, in both directions. No
+ * extrapolation: a curve that keeps climbing past its last key is never what
+ * anyone meant, and it is the failure that is hardest to see in a render.
+ */
+export declare function sampleChannel(channel: Channel | null | undefined, frame: number): number | undefined;
+/**
+ * The on-disk form. Interpolation is omitted when it is the default, so a
+ * plain channel reads as `{ "keys": [{ "frame": 1, "value": 0 }] }` and a diff
+ * shows easing changes rather than noise.
+ *
+ * Structurally identical to `CascadeSerializedChannel` in the contracts
+ * package, which is where the document shape is declared. It is restated here
+ * so this module keeps depending on nothing.
+ */
+export interface SerializedKeyframe {
+    frame: number;
+    value: number;
+    interpolation?: Interpolation;
+}
+export interface SerializedChannel {
+    keys: SerializedKeyframe[];
+}
+export declare function serializeChannel(channel: Channel | null | undefined): SerializedChannel | undefined;
+/**
+ * Read a channel back. Anything unrecognised yields the empty channel rather
+ * than an exception — a bad channel in one parameter must not fail a load.
+ */
+export declare function deserializeChannel(data: unknown): Channel;
+//# sourceMappingURL=channel.d.ts.map

package/dist/runtime/animation/channel.js

@@ -0,0 +1,204 @@
+/**
+ * Keyframe channels, neutral runtime.
+ *
+ * A channel is the third way a parameter becomes a value, beside a literal and
+ * an expression. It is an ordered list of keys and a rule for what happens
+ * between them, and it is sampled — never pushed. The host asks for the value
+ * at a frame; nothing here holds a clock, a graph or a node, which is what
+ * keeps the whole thing deterministic and testable on its own.
+ *
+ * `sin($T)` and a drawn curve are the same shape: one written, one drawn.
+ *
+ * Every function here is pure. A channel is treated as immutable — `setKey`
+ * and `deleteKey` return a new channel rather than editing one in place — so a
+ * caller can hold a channel across a cook without it changing underneath.
+ */
+/** Smooth, deliberately: an unset default of `linear` animates like a robot. */
+export const DEFAULT_INTERPOLATION = "smooth";
+const INTERPOLATIONS = ["constant", "linear", "smooth"];
+export function isInterpolation(value) {
+    return typeof value === "string" && INTERPOLATIONS.includes(value);
+}
+/** The empty channel. Sampling it returns undefined, so a caller falls back. */
+export const EMPTY_CHANNEL = Object.freeze({ keys: Object.freeze([]) });
+/**
+ * Build a channel from keys in any order, with anything unusable dropped.
+ *
+ * Unordered input is sorted rather than rejected — a file edited by hand and a
+ * UI that appends are both legitimate sources. A duplicate frame keeps the
+ * LAST key given, which is what "set this key again" means.
+ */
+export function createChannel(keys = []) {
+    const byFrame = new Map();
+    for (const key of keys) {
+        if (!key)
+            continue;
+        const frame = Number(key.frame);
+        const value = Number(key.value);
+        if (!Number.isFinite(frame) || !Number.isFinite(value))
+            continue;
+        byFrame.set(frame, {
+            frame,
+            value,
+            interpolation: isInterpolation(key.interpolation) ? key.interpolation : DEFAULT_INTERPOLATION
+        });
+    }
+    const sorted = [...byFrame.values()].sort((a, b) => a.frame - b.frame);
+    return { keys: sorted };
+}
+export function isChannel(value) {
+    return !!value && typeof value === "object" && Array.isArray(value.keys);
+}
+/** A channel with no keys resolves to nothing, so the raw value still applies. */
+export function isEmptyChannel(channel) {
+    return !channel || channel.keys.length === 0;
+}
+export function keyAt(channel, frame) {
+    return channel.keys.find(key => key.frame === frame);
+}
+/**
+ * Set a key, replacing any key already on that frame.
+ *
+ * Re-keying an existing frame keeps that key's interpolation unless a new one
+ * is given: dragging a value should not silently change its easing.
+ */
+export function setKey(channel, frame, value, interpolation) {
+    const base = channel ?? EMPTY_CHANNEL;
+    if (!Number.isFinite(frame) || !Number.isFinite(value))
+        return createChannel(base.keys);
+    const existing = keyAt(base, frame);
+    const mode = interpolation ?? existing?.interpolation ?? DEFAULT_INTERPOLATION;
+    const kept = base.keys.filter(key => key.frame !== frame);
+    return createChannel([...kept, { frame, value, interpolation: mode }]);
+}
+/** Remove the key on that frame. Removing the last key leaves an empty channel. */
+export function deleteKey(channel, frame) {
+    const base = channel ?? EMPTY_CHANNEL;
+    return createChannel(base.keys.filter(key => key.frame !== frame));
+}
+/** Change one key's outgoing interpolation without touching its value. */
+export function setKeyInterpolation(channel, frame, interpolation) {
+    const base = channel ?? EMPTY_CHANNEL;
+    const existing = keyAt(base, frame);
+    if (!existing)
+        return createChannel(base.keys);
+    return setKey(base, frame, existing.value, interpolation);
+}
+/**
+ * The value at any frame, fractional included.
+ *
+ * Returns undefined for a channel with no keys — that is the signal to fall
+ * back to the parameter's raw value rather than to invent a zero.
+ *
+ * Outside the key range the end values are HELD, in both directions. No
+ * extrapolation: a curve that keeps climbing past its last key is never what
+ * anyone meant, and it is the failure that is hardest to see in a render.
+ */
+export function sampleChannel(channel, frame) {
+    if (!channel || channel.keys.length === 0)
+        return undefined;
+    const keys = channel.keys;
+    if (!Number.isFinite(frame))
+        return keys[0].value;
+    if (keys.length === 1)
+        return keys[0].value;
+    if (frame <= keys[0].frame)
+        return keys[0].value;
+    if (frame >= keys[keys.length - 1].frame)
+        return keys[keys.length - 1].value;
+    const i = segmentIndex(keys, frame);
+    const k0 = keys[i];
+    const k1 = keys[i + 1];
+    const span = k1.frame - k0.frame;
+    if (span <= 0)
+        return k1.value;
+    const t = (frame - k0.frame) / span;
+    switch (k0.interpolation) {
+        case "constant":
+            return k0.value;
+        case "linear":
+            return k0.value + (k1.value - k0.value) * t;
+        case "smooth":
+        default:
+            return hermite(keys, i, t, span);
+    }
+}
+/** Index of the key at or before `frame`, binary searched. */
+function segmentIndex(keys, frame) {
+    let lo = 0;
+    let hi = keys.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (keys[mid].frame <= frame)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return Math.min(lo, keys.length - 2);
+}
+/**
+ * Cubic Hermite across segment `i`, with tangents derived from the neighbours.
+ *
+ * There are no tangent handles yet — that is the curve editor, and it is the
+ * largest single piece of UI in the plan. Until it exists the tangents are
+ * automatic, in the way both Houdini and After Effects pick them by default:
+ *
+ *   - a key with a neighbour on each side takes the central difference, which
+ *     is what makes velocity continuous through a key rather than kinked
+ *   - the first and last key are FLAT, so a two-key smooth channel eases in
+ *     and out. This is the behaviour people mean by "smooth"; a straight line
+ *     between two keys would be indistinguishable from linear
+ *   - a constant segment next door flattens the tangent it touches, so a hold
+ *     does not make the neighbouring curve bulge to reach it
+ */
+function hermite(keys, i, t, span) {
+    const k0 = keys[i];
+    const k1 = keys[i + 1];
+    const m0 = tangent(keys, i, "out");
+    const m1 = tangent(keys, i + 1, "in");
+    const t2 = t * t;
+    const t3 = t2 * t;
+    const h00 = 2 * t3 - 3 * t2 + 1;
+    const h10 = t3 - 2 * t2 + t;
+    const h01 = -2 * t3 + 3 * t2;
+    const h11 = t3 - t2;
+    return h00 * k0.value + h10 * span * m0 + h01 * k1.value + h11 * span * m1;
+}
+/** Value change per frame at key `i`, seen from the segment on `side`. */
+function tangent(keys, i, side) {
+    const prev = keys[i - 1];
+    const next = keys[i + 1];
+    if (!prev || !next)
+        return 0;
+    // A hold on either side means the curve arrives, or leaves, level.
+    if (side === "out" && prev.interpolation === "constant")
+        return 0;
+    if (side === "in" && keys[i].interpolation === "constant")
+        return 0;
+    const span = next.frame - prev.frame;
+    if (span <= 0)
+        return 0;
+    return (next.value - prev.value) / span;
+}
+export function serializeChannel(channel) {
+    if (isEmptyChannel(channel))
+        return undefined;
+    return {
+        keys: channel.keys.map(key => (key.interpolation === DEFAULT_INTERPOLATION
+            ? { frame: key.frame, value: key.value }
+            : { frame: key.frame, value: key.value, interpolation: key.interpolation }))
+    };
+}
+/**
+ * Read a channel back. Anything unrecognised yields the empty channel rather
+ * than an exception — a bad channel in one parameter must not fail a load.
+ */
+export function deserializeChannel(data) {
+    if (!data || typeof data !== "object")
+        return EMPTY_CHANNEL;
+    const keys = data.keys;
+    if (!Array.isArray(keys))
+        return EMPTY_CHANNEL;
+    return createChannel(keys);
+}
+//# sourceMappingURL=channel.js.map

package/dist/runtime/animation/frameRange.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Frame-range evaluation, neutral runtime.
+ *
+ * The loop the engine has always been missing: set the frame, mark the
+ * time-dependent nodes dirty, hand the frame to a caller, repeat. It writes no
+ * files and spawns no encoder — frames are produced where the canvas is, so
+ * what the caller does with each frame is the caller's business.
+ *
+ * The loop owns no graph and no clock of its own. It drives a `FrameClock`,
+ * which a host binds to its own engine state.
+ */
+export interface FrameClock {
+    /** Set the current frame. Fractional frames must be preserved. */
+    setFrame(frame: number): void;
+    /** Dirty every node whose parameters depend on time. */
+    markTimeDependentDirty(): void;
+    /** Integer frame — $F */
+    getFrame(): number;
+    /** Fractional frame — $FF */
+    getFrameFraction(): number;
+    /** Seconds — $T */
+    getTime(): number;
+    /** Rate — $FPS */
+    getFps(): number;
+}
+/** What a caller is told about the frame it has been handed. */
+export interface FrameInfo {
+    /** 0-based position in the range. */
+    index: number;
+    /** Total frames in the range. */
+    total: number;
+    /** Integer frame — $F */
+    frame: number;
+    /** Fractional frame — $FF */
+    fframe: number;
+    /** Seconds — $T */
+    time: number;
+    /** Rate — $FPS */
+    fps: number;
+}
+export interface FrameRangeOptions {
+    /** First frame, inclusive. */
+    start: number;
+    /** Last frame, inclusive when the step lands on it. */
+    end: number;
+    /** Frame increment. Must be > 0; may be fractional for sub-frame stepping. */
+    step?: number;
+    /** Called once per frame, after the frame is set and dirt is marked. */
+    onFrame: (info: FrameInfo) => void | Promise<void>;
+    /** Cooperative cancellation, checked before each frame. */
+    signal?: {
+        readonly aborted: boolean;
+    };
+    /** Restore the clock's frame when the loop finishes. Default true. */
+    restoreFrame?: boolean;
+}
+export interface FrameRangeResult {
+    /** The fractional frames visited, in order. */
+    frames: number[];
+    frameCount: number;
+    /** True if a signal cut the loop short. */
+    aborted: boolean;
+}
+/**
+ * The frames a range visits. Pure — no clock, no side effects — so a caller can
+ * size a progress bar or a sequence without running anything.
+ */
+export declare function frameRange(start: number, end: number, step?: number): number[];
+/**
+ * Walk a frame range against a clock, calling back once per frame.
+ *
+ * Per frame, in this order: set the frame, mark time-dependent nodes dirty,
+ * then call `onFrame`. The callback is where a cook happens — the loop does not
+ * assume one, which is what lets the same loop serve a render, a test, or a
+ * headless evaluation.
+ */
+export declare function runFrameRange(clock: FrameClock, options: FrameRangeOptions): Promise<FrameRangeResult>;
+//# sourceMappingURL=frameRange.d.ts.map

package/dist/runtime/animation/frameRange.js

@@ -0,0 +1,76 @@
+/**
+ * Frame-range evaluation, neutral runtime.
+ *
+ * The loop the engine has always been missing: set the frame, mark the
+ * time-dependent nodes dirty, hand the frame to a caller, repeat. It writes no
+ * files and spawns no encoder — frames are produced where the canvas is, so
+ * what the caller does with each frame is the caller's business.
+ *
+ * The loop owns no graph and no clock of its own. It drives a `FrameClock`,
+ * which a host binds to its own engine state.
+ */
+/**
+ * The frames a range visits. Pure — no clock, no side effects — so a caller can
+ * size a progress bar or a sequence without running anything.
+ */
+export function frameRange(start, end, step = 1) {
+    if (!Number.isFinite(start) || !Number.isFinite(end)) {
+        throw new Error(`frameRange: start and end must be finite (got ${start}, ${end})`);
+    }
+    if (!Number.isFinite(step) || step <= 0) {
+        throw new Error(`frameRange: step must be a finite number greater than 0 (got ${step})`);
+    }
+    if (end < start) {
+        throw new Error(`frameRange: end (${end}) must not be before start (${start})`);
+    }
+    // Count from the span rather than accumulating, so a fractional step does not
+    // drift and an inclusive end lands exactly.
+    const span = end - start;
+    const count = Math.floor(span / step + 1e-9) + 1;
+    const frames = new Array(count);
+    for (let i = 0; i < count; i++)
+        frames[i] = start + i * step;
+    return frames;
+}
+/**
+ * Walk a frame range against a clock, calling back once per frame.
+ *
+ * Per frame, in this order: set the frame, mark time-dependent nodes dirty,
+ * then call `onFrame`. The callback is where a cook happens — the loop does not
+ * assume one, which is what lets the same loop serve a render, a test, or a
+ * headless evaluation.
+ */
+export async function runFrameRange(clock, options) {
+    const { start, end, step = 1, onFrame, signal, restoreFrame = true } = options;
+    const frames = frameRange(start, end, step);
+    const previousFrame = clock.getFrameFraction();
+    const visited = [];
+    let aborted = false;
+    try {
+        for (let index = 0; index < frames.length; index++) {
+            if (signal?.aborted) {
+                aborted = true;
+                break;
+            }
+            clock.setFrame(frames[index]);
+            clock.markTimeDependentDirty();
+            await onFrame({
+                index,
+                total: frames.length,
+                frame: clock.getFrame(),
+                fframe: clock.getFrameFraction(),
+                time: clock.getTime(),
+                fps: clock.getFps()
+            });
+            visited.push(clock.getFrameFraction());
+        }
+    }
+    finally {
+        if (restoreFrame) {
+            clock.setFrame(previousFrame);
+            clock.markTimeDependentDirty();
+        }
+    }
+    return { frames: visited, frameCount: visited.length, aborted };
+}
+//# sourceMappingURL=frameRange.js.map

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

@@ -0,0 +1,10 @@
+/**
+ * Animation: keyframe channels, and frame-range evaluation over a host-bound
+ * clock. Neither holds a clock of its own — the host owns time, which is what
+ * keeps a cook deterministic.
+ */
+export { DEFAULT_INTERPOLATION, EMPTY_CHANNEL, createChannel, deleteKey, deserializeChannel, isChannel, isEmptyChannel, isInterpolation, keyAt, sampleChannel, serializeChannel, setKey, setKeyInterpolation } from "./channel.js";
+export type { Channel, Interpolation, Keyframe, KeyframeInput, SerializedChannel, SerializedKeyframe } from "./channel.js";
+export { frameRange, runFrameRange } from "./frameRange.js";
+export type { FrameClock, FrameInfo, FrameRangeOptions, FrameRangeResult } from "./frameRange.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/animation/index.js

@@ -0,0 +1,8 @@
+/**
+ * Animation: keyframe channels, and frame-range evaluation over a host-bound
+ * clock. Neither holds a clock of its own — the host owns time, which is what
+ * keeps a cook deterministic.
+ */
+export { DEFAULT_INTERPOLATION, EMPTY_CHANNEL, createChannel, deleteKey, deserializeChannel, isChannel, isEmptyChannel, isInterpolation, keyAt, sampleChannel, serializeChannel, setKey, setKeyInterpolation } from "./channel.js";
+export { frameRange, runFrameRange } from "./frameRange.js";
+//# sourceMappingURL=index.js.map

package/dist/runtime/builtins/core/random.d.ts

@@ -1,4 +1,4 @@
-import type { NodeExecutionContext } from "cascade/contracts";
+import type { NodeExecutionContext } from "@field/cascade/contracts";
 export declare const randomDefinition: {
     readonly apiVersion: 1;
     readonly label: "Random";

package/dist/runtime/builtins/core/remap.d.ts

@@ -1,4 +1,4 @@
-import type { NodeExecutionContext } from "cascade/contracts";
+import type { NodeExecutionContext } from "@field/cascade/contracts";
 export declare const remapDefinition: {
     readonly apiVersion: 1;
     readonly label: "Remap";

package/dist/runtime/builtins/geo/copyToPoints.d.ts

@@ -1,4 +1,4 @@
-import type { NodeExecutionContext } from "cascade/contracts";
+import type { NodeExecutionContext } from "@field/cascade/contracts";
 import { copyToPointsDefinition } from "./definitions.js";
 /**
  * Copy to Points SOP: the source instanced onto every point of the target.

package/dist/runtime/builtins/geo/copyToPoints.js

@@ -1,4 +1,4 @@
-import { emptyGeometry } from "cascade/contracts";
+import { emptyGeometry } from "@field/cascade/contracts";
 import { copyToPoints } from "../../geometry/copy.js";
 import { copyToPointsDefinition } from "./definitions.js";
 import { geoModuleId } from "./namespace.js";

package/dist/runtime/builtins/geo/generators.d.ts

@@ -1,4 +1,4 @@
-import type { NodeExecutionContext } from "cascade/contracts";
+import type { NodeExecutionContext } from "@field/cascade/contracts";
 import { circleDefinition, rectangleDefinition } from "./definitions.js";
 /**
  * The two generators. Houdini has no Rectangle and its Grid with two rows does

package/dist/runtime/builtins/geo/merge.d.ts

@@ -1,4 +1,4 @@
-import type { NodeExecutionContext } from "cascade/contracts";
+import type { NodeExecutionContext } from "@field/cascade/contracts";
 import { mergeDefinition } from "./definitions.js";
 /**
  * Merge SOP: N geometries concatenated, with points, vertices and primitives

package/dist/runtime/builtins/geo/svgExport.d.ts

@@ -1,4 +1,4 @@
-import type { NodeExecutionContext } from "cascade/contracts";
+import type { NodeExecutionContext } from "@field/cascade/contracts";
 import { svgExportDefinition } from "./definitions.js";
 /**
  * The output end: an SVG document, as a string and as a written asset.

package/dist/runtime/builtins/geo/svgExport.js

@@ -1,4 +1,4 @@
-import { emptyGeometry } from "cascade/contracts";
+import { emptyGeometry } from "@field/cascade/contracts";
 import { geometryToSvg, utf8Bytes } from "../../geometry/svg.js";
 import { svgExportDefinition } from "./definitions.js";
 import { geoModuleId } from "./namespace.js";

package/dist/runtime/builtins/geo/transform.d.ts

@@ -1,4 +1,4 @@
-import type { NodeExecutionContext } from "cascade/contracts";
+import type { NodeExecutionContext } from "@field/cascade/contracts";
 import { transformDefinition } from "./definitions.js";
 /**
  * Transform SOP's parameters, by its names: translate, rotate, scale, pivot,

package/dist/runtime/builtins/geo/transform.js

@@ -1,4 +1,4 @@
-import { emptyGeometry } from "cascade/contracts";
+import { emptyGeometry } from "@field/cascade/contracts";
 import { transformMatrix } from "../../geometry/matrix.js";
 import { transformGeometry } from "../../geometry/transform.js";
 import { transformDefinition } from "./definitions.js";

package/dist/runtime/definition/architecture.d.ts

@@ -1,5 +1,5 @@
 import type * as TypeScript from "typescript";
-import type { Diagnostic } from "cascade/contracts";
+import type { Diagnostic } from "@field/cascade/contracts";
 /**
  * Enforces the statically inspectable node-module boundary. This is an
  * architecture check for trusted project code, not a security sandbox.

package/dist/runtime/definition/extract.d.ts

@@ -1,5 +1,5 @@
 import type * as TypeScript from "typescript";
-import { type Diagnostic, type NodeDefinition } from "cascade/contracts";
+import { type Diagnostic, type NodeDefinition } from "@field/cascade/contracts";
 export type DefinitionExtractionResult = {
     readonly ok: true;
     readonly definition: NodeDefinition;

package/dist/runtime/definition/extract.js

@@ -1,4 +1,4 @@
-import { validateNodeDefinition, } from "cascade/contracts";
+import { validateNodeDefinition, } from "@field/cascade/contracts";
 const MAX_DEPTH = 32;
 const MAX_NODES = 10_000;
 export function extractNodeDefinition(source, fileName, ts) {

package/dist/runtime/error.d.ts

@@ -1,4 +1,4 @@
-import type { Diagnostic } from "cascade/contracts";
+import type { Diagnostic } from "@field/cascade/contracts";
 export declare class CascadeRuntimeError extends Error {
     readonly code: string;
     readonly diagnostics: readonly Diagnostic[];

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

@@ -0,0 +1,53 @@
+/**
+ * The neutral expression evaluator.
+ *
+ * Compiles parameter expressions and evaluates them against a time state and a
+ * host-supplied scope. It imports nothing from Studio and touches no platform
+ * API, so a headless cook can resolve `sin($T)` on a parameter exactly as the
+ * editor does.
+ *
+ * Determinism: an expression is a parameter resolved *before* execute runs, so
+ * the node receives a plain number and stays pure. Same graph plus same frame
+ * gives the same output.
+ */
+import type { ExpressionScope, Node as NodeShape } from "./scope.js";
+import { TimeState } from "./time.js";
+import type { CompiledExpression, ExpressionContext, ExpressionResult } from "./types.js";
+export declare class ExpressionEvaluator<TNode extends NodeShape = NodeShape> {
+    protected readonly timeState: TimeState;
+    private readonly compiledCache;
+    private scope;
+    constructor(scope?: ExpressionScope<TNode> | null);
+    /** Bind (or rebind) the host scope. Clears nothing: compilation is scope-free. */
+    setScope(scope: ExpressionScope<TNode> | null): void;
+    getScope(): ExpressionScope<TNode> | null;
+    /** Set the current frame. Fractional frames are preserved. */
+    setFrame(frame: number): void;
+    /** Set the current time in seconds, keeping the sub-frame remainder. */
+    setTime(seconds: number): void;
+    setFps(fps: number): void;
+    /** seconds — $T */
+    get time(): number;
+    /** integer frame — $F */
+    get frame(): number;
+    /** fractional frame — $FF */
+    get fframe(): number;
+    /** rate — $FPS */
+    get fps(): number;
+    compile(expression: string): CompiledExpression<TNode>;
+    evaluate(expression: string, node: TNode): ExpressionResult;
+    /** Build the context an expression sees. */
+    createContext(node: TNode): ExpressionContext<TNode>;
+    ch(node: TNode, path: string): number;
+    chs(node: TNode, path: string): string;
+    chv(node: TNode, path: string): number[];
+    private resolveParam;
+    /** True if a referenced path resolves from this node. */
+    validatePath(fromNode: TNode, path: string): boolean;
+    /** Parameter paths referenced through ch/chs/chv. */
+    extractDependencies(expression: string): string[];
+    /** True if the expression references time, in either the bare or `$` spelling. */
+    hasTimeReference(expression: string): boolean;
+    clearCache(): void;
+}
+//# sourceMappingURL=evaluator.d.ts.map