@field/cascade 0.2.22 → 0.3.0

package/dist/runtime/runtime.js

@@ -1,6 +1,34 @@
-import { canConnectTypes, validateNodeDefinition, } from "cascade/contracts";
+import { canConnectTypes, validateNodeDefinition, } from "@field/cascade/contracts";
 import { CascadeRuntimeError } from "./error.js";
 import { builtinNodeRegistrations } from "./builtins/index.js";
+import { deserializeChannel, isEmptyChannel } from "./animation/channel.js";
+import { PropAnimator, isBoundProp } from "./params/index.js";
+import { DEFAULT_FPS, MIN_FRAME } from "./expressions/time.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 const PREFLIGHT_WARNING_CODES = new Set([
+    "runtime/preflight-environment",
+    "runtime/stray-params",
+]);
 class MutableAbortSignal {
     report;
     aborted = false;
@@ -129,6 +157,16 @@ class Graph {
     authoredAnnotations;
     graphInputs;
     graphOutputs;
+    /**
+     * The graph's animated parameters, and the clock they resolve against.
+     *
+     * The clock is a value the caller sets per run (`run({ frame })`), never one
+     * this graph reads: same graph plus same frame gives the same output, which
+     * is the only reason a headless render can be trusted.
+     */
+    animator;
+    frame = MIN_FRAME;
+    fps = DEFAULT_FPS;
     constructor(host, nodes, connections, onDispose, annotations = []) {
         this.host = host;
         this.nodes = nodes;
@@ -138,10 +176,47 @@ class Graph {
         this.graphInputs = graphBoundaries(nodes, "cascade.core.Input", "inputName");
         this.graphOutputs = graphBoundaries(nodes, "cascade.core.Output", "outputName");
         this.authoredAnnotations = Object.freeze(annotations.map((annotation) => snapshot(annotation)));
+        this.animator = new PropAnimator({
+            nodes,
+            node: (id) => this.byId.get(id),
+            inputNode: (node, index) => {
+                const feeding = this.connections
+                    .filter((connection) => connection.kind === "data" &&
+                    connection.target.nodeId === node.id)
+                    .sort((a, b) => a.order - b.order);
+                const source = feeding[index]?.source.nodeId;
+                return (source ? this.byId.get(source) : undefined) ?? null;
+            },
+            // A failed expression has already fallen back to the stored value, so it
+            // is a diagnostic rather than a stopped run — but it is never silent: a
+            // parameter that quietly reverts is the hardest fault to see in a
+            // hundred rendered frames.
+            report: (nodeId, propName, error) => this.reportDiagnostic({
+                phase: "run",
+                code: "runtime/expression-failed",
+                message: `${nodeId}.${propName}: ${error}`,
+                path: `${nodeId}.${propName}`,
+            }),
+        });
+        this.animator.setFps(this.fps);
+        this.animator.setFrame(this.frame);
+        // Resolve once at load, so `inspect()` and a preset applied before any run
+        // both see the parameter at the graph's own first frame rather than the
+        // number that was last saved.
+        this.animator.resolveAll();
     }
     get state() {
         return this.graphState;
     }
+    /**
+     * Everything that would stop this host running the graph, without running
+     * it: a node whose environment this host is not, a bridged node that cannot
+     * be bridged, a declared capability this host does not install. Empty means
+     * the graph clears the same gate `run` puts it through.
+     */
+    preflight() {
+        return this.preflightDiagnostics(this.nodes);
+    }
     inspect() {
         const nodes = this.nodes.map((node) => ({
             id: node.id,
@@ -212,7 +287,26 @@ class Graph {
             misuse("runtime/structural-prop", `${nodeId}.${propName} is structural and requires a graph reload`);
         if (!node.definition.props?.[propName])
             misuse("runtime/invalid-prop", `${nodeId}.${propName} is not a prop`);
-        node.props[propName] = runtimeValue(value, node.definition.props[propName].type, false, `${nodeId}.${propName}`);
+        const resolved = runtimeValue(value, node.definition.props[propName].type, false, `${nodeId}.${propName}`);
+        node.props[propName] = resolved;
+        this.rebind(node, propName, resolved);
+    }
+    /**
+     * Keep a bound prop's STORED value in step with a direct write.
+     *
+     * A channel or an expression still wins on the next resolve — setting a
+     * keyed parameter's value does not delete its keys, in Studio or here — but
+     * the value written is the one the parameter falls back to, so dropping it
+     * would make a later `clearChannel` reinstate a number nobody chose.
+     */
+    rebind(node, propName, value) {
+        const binding = node.bindings[propName];
+        if (binding)
+            node.bindings[propName] = { ...binding, value };
+    }
+    reportDiagnostic(diagnostic) {
+        this.diagnostics.push(diagnostic);
+        this.emit({ type: "diagnostic", diagnostic });
     }
     async applyPreset(preset) {
         this.requireReady();
@@ -247,10 +341,50 @@ class Graph {
         }
         for (const [node, name, value] of inputDrafts)
             node.inputs[name] = value;
-        for (const [node, name, value] of propDrafts)
+        for (const [node, name, value] of propDrafts) {
             node.props[name] = value;
+            this.rebind(node, name, value);
+        }
+    }
+    /**
+     * The frame this graph is cooking at, and the rate frames are counted in.
+     *
+     * Separate from `run` so a caller can scrub without cooking — and so that
+     * `setFrame` then `inspect()` reports a keyed parameter at that frame, which
+     * is what a panel needs and what `run` alone cannot give it.
+     */
+    setFrame(frame) {
+        if (!Number.isFinite(frame))
+            return;
+        this.frame = Math.max(MIN_FRAME, frame);
+        this.animator.setFrame(this.frame);
+        this.animator.resolveAll();
+    }
+    setFps(fps) {
+        if (!Number.isFinite(fps))
+            return;
+        this.fps = Math.max(1, fps);
+        this.animator.setFps(this.fps);
+        this.animator.resolveAll();
+    }
+    getFrame() {
+        return this.frame;
+    }
+    getFps() {
+        return this.fps;
     }
     run(options = {}) {
+        // The frame belongs to the run, not to the graph's history: a render loop
+        // states which frame it wants and gets exactly that, with no dependence on
+        // what the previous run left behind.
+        if (options.fps !== undefined)
+            this.setFps(options.fps);
+        if (options.frame !== undefined)
+            this.setFrame(options.frame);
+        // Every bound parameter, resolved before any node executes — so a node
+        // still receives a plain number and never reads a clock.
+        else
+            this.animator.resolveAll();
         return this.trackRun(options.target ?? { kind: "all" }, options.signal, options.runId);
     }
     trigger(nodeId, inputName, payload, options = {}) {
@@ -339,7 +473,7 @@ class Graph {
                 }
                 : this.runSelection(target);
             const { reachable, initial } = selection;
-            this.preflight(reachable);
+            this.assertPreflight(reachable);
             if (!signal.aborted)
                 await Promise.all(reachable
                     .filter((node) => !this.isRemote(node))
@@ -504,6 +638,7 @@ class Graph {
             report: (event) => this.emit({ type: "node:progress", runId, nodeId: node.id, ...event }),
         };
         await node.execute({
+            nodeId: node.id,
             inputs,
             outputs,
             props,
@@ -544,33 +679,70 @@ class Graph {
             }
         this.emit({ type: "node:complete", runId, nodeId: node.id });
     }
-    preflight(nodes) {
+    /**
+     * Every reason this host cannot run these nodes, collected rather than
+     * thrown. `assertPreflight` is the run path and raises the first of them;
+     * `preflight()` is the static path and hands the whole list to a caller that
+     * is not executing anything.
+     *
+     * There is deliberately one implementation. `validate` and `check` used to
+     * answer "will this graph run?" without ever consulting a host, so a node
+     * declaring a capability nobody installs passed both and then failed here —
+     * the two commands could not see the fault they exist to report. Any second
+     * copy of these rules would drift back into that.
+     */
+    preflightDiagnostics(nodes) {
+        const diagnostics = [];
+        const push = (code, nodeId, message) => diagnostics.push({ phase: "preflight", code, path: nodeId, message });
         for (const node of nodes) {
+            if (node.strayParams.length)
+                push("runtime/stray-params", node.id, `${node.moduleId} stores ${node.strayParams.join(", ")} under "params", which this runtime does not read — move ${node.strayParams.length === 1 ? "it" : "them"} to "props" or "inputs", whichever the definition declares, or the ${node.strayParams.length === 1 ? "value is" : "values are"} silently the default`);
             const remote = this.isRemote(node);
             const locationWorks = node.definition.runsOn === "portable" ||
                 node.definition.runsOn === this.host.environment ||
                 remote;
-            if (!locationWorks)
-                throw runtimeError("runtime/preflight-environment", `${node.moduleId} requires ${node.definition.runsOn}`);
+            if (!locationWorks) {
+                push("runtime/preflight-environment", node.id, `${node.moduleId} requires ${node.definition.runsOn}`);
+                continue;
+            }
             if (remote) {
                 const hasTriggers = [
                     ...Object.values(node.definition.inputs ?? {}),
                     ...Object.values(node.definition.outputs ?? {}),
                 ].some((port) => port.kind === "trigger");
                 if (hasTriggers)
-                    throw runtimeError("runtime/preflight-bridge-trigger", `${node.moduleId} cannot send triggers over the server bridge`);
+                    push("runtime/preflight-bridge-trigger", node.id, `${node.moduleId} cannot send triggers over the server bridge`);
                 const hasTexture = [
                     ...Object.values(node.definition.inputs ?? {}),
                     ...Object.values(node.definition.outputs ?? {}),
                 ].some((port) => port.kind === "data" && port.type === "texture");
                 if (hasTexture)
-                    throw runtimeError("runtime/preflight-bridge-texture", `${node.moduleId} cannot send textures over the server bridge`);
+                    push("runtime/preflight-bridge-texture", node.id, `${node.moduleId} cannot send textures over the server bridge`);
             }
             else
                 for (const capability of node.definition.capabilities ?? [])
                     if (!this.host.capabilities[capability])
-                        throw runtimeError("runtime/missing-capability", `Missing capability ${capability} for ${node.moduleId}`);
+                        push("runtime/missing-capability", node.id, `Missing capability ${capability} for ${node.moduleId} (node ${node.id}) — the ${this.host.environment} host ${this.hostProvides()}`);
         }
+        return diagnostics;
+    }
+    /**
+     * What the host actually installed, asked of the host rather than written
+     * down. `serverBridge` is left out: it is how a node runs somewhere else,
+     * not a capability a definition can declare.
+     */
+    hostProvides() {
+        const supplied = Object.keys(this.host.capabilities)
+            .filter((name) => name !== "serverBridge" && !!this.host.capabilities[name])
+            .sort();
+        return supplied.length
+            ? `provides ${supplied.join(", ")}`
+            : `provides no capabilities`;
+    }
+    assertPreflight(nodes) {
+        const [first] = this.preflightDiagnostics(nodes).filter((diagnostic) => !PREFLIGHT_WARNING_CODES.has(diagnostic.code));
+        if (first)
+            throw new CascadeRuntimeError(first.code, [first]);
     }
     isRemote(node) {
         return (this.host.environment === "browser" &&
@@ -776,12 +948,34 @@ function materialize(authored, registration) {
         }
     for (const [name, definition] of Object.entries(registration.definition.props ?? {}))
         props[name] = runtimeValue(definition.default, definition.type, false, `${authored.id}.${name}`);
+    const bindings = {};
     for (const [name, saved] of Object.entries(authored.props ?? {})) {
         const definition = registration.definition.props?.[name];
-        if (definition)
-            props[name] = runtimeValue(saved && typeof saved === "object" && "value" in saved
-                ? saved.value
-                : saved, definition.type, false, `${authored.id}.${name}`);
+        if (!definition)
+            continue;
+        // `{ value, expression?, channel? }` — the object form declared in
+        // contracts/animation.ts. A bare value is the same prop with nothing more
+        // to say, which is what every older file on disk contains.
+        const object = saved && typeof saved === "object" && "value" in saved
+            ? saved
+            : null;
+        const value = runtimeValue(object ? object.value : saved, definition.type, false, `${authored.id}.${name}`);
+        props[name] = value;
+        if (!object)
+            continue;
+        const channel = deserializeChannel(object.channel);
+        const expression = typeof object.expression === "string" && object.expression
+            ? object.expression
+            : undefined;
+        const binding = {
+            value,
+            ...(expression ? { expression } : {}),
+            ...(isEmptyChannel(channel) ? {} : { channel }),
+        };
+        // Only a prop that actually carries something, so `animated` stays a real
+        // question and an unanimated graph pays nothing for this.
+        if (isBoundProp(binding))
+            bindings[name] = binding;
     }
     return {
         id: authored.id,
@@ -791,9 +985,43 @@ function materialize(authored, registration) {
         definition: registration.definition,
         inputs,
         props,
+        bindings,
+        strayParams: strayParams(authored, registration),
         outputs: new Map(),
     };
 }
+/**
+ * The names a document stored under `params` that this runtime will not read.
+ *
+ * Nothing above consults `params`: the loops that fill `inputs` and `props`
+ * read the definition and then the document's own `inputs` and `props`, so a
+ * value left in `params` is dropped without a word and the parameter keeps its
+ * default. That is not a hypothetical — on `cascade-logo` it put a seed back to
+ * 7 and two rasterizers back to 1024, so three nodes wrote one file and the
+ * drawing changed, with every command still reporting success.
+ *
+ * **Inputs count, not just props.** The first version of this checked props
+ * alone and so was blind to exactly the case the conversions produce most: a
+ * parameter another node drives has to be declared as an `inputs` entry,
+ * because a v1 prop cannot be promoted to a pin. `field-logo`'s `angle` is one,
+ * and a negative control over the pre-migration document named five nodes and
+ * missed that one.
+ *
+ * Only names the definition actually declares are reported. A leftover key
+ * naming nothing is a different fault, and reporting it would make this fire on
+ * documents where no value was lost.
+ */
+function strayParams(authored, registration) {
+    const definition = registration.definition;
+    const declared = new Set([
+        ...Object.keys(definition.props ?? {}),
+        ...Object.keys(definition.inputs ?? {}),
+    ]);
+    const names = Array.isArray(authored.params)
+        ? authored.params.map((saved) => saved?.name)
+        : Object.keys(authored.params ?? {});
+    return names.filter((name) => typeof name === "string" && declared.has(name));
+}
 function specializeCoreRegistration(registration, authored, nodes) {
     if (registration.moduleId === "cascade.core.Input" ||
         registration.moduleId === "cascade.core.Output") {

package/dist/runtime/types.d.ts

@@ -1,5 +1,5 @@
-import type { AssetCapability, AssetRef, CascadeAbortSignal, CascadeDocument, CascadePreset, Diagnostic, FileCapability, ImageRef, JsonValue, MediaCapability, NodeDefinition, NodeExecute, ProgressReporter, PythonCapability, SerializableValue, ShellCapability, TextureHandle, WebGLCapability } from "cascade/contracts";
-export type { CascadeDocument, CascadeDocumentAnnotation, CascadeDocumentConnection, CascadeDocumentNode, CascadePreset, } from "cascade/contracts";
+import type { AssetCapability, AssetRef, CascadeAbortSignal, CascadeDocument, CascadePreset, Diagnostic, FileCapability, ImageRef, JsonValue, MediaCapability, NodeDefinition, NodeExecute, ProgressReporter, PythonCapability, SerializableValue, ShellCapability, TextureHandle, WebGLCapability } from "@field/cascade/contracts";
+export type { CascadeDocument, CascadeDocumentAnnotation, CascadeDocumentConnection, CascadeDocumentNode, CascadePreset, } from "@field/cascade/contracts";
 export interface DefinitionNodeRegistration<D extends NodeDefinition = NodeDefinition> {
     readonly kind: "definition-v1";
     readonly moduleId: string;
@@ -88,6 +88,18 @@ export interface RunOptions {
     readonly target?: RunTarget;
     readonly signal?: CascadeAbortSignal;
     readonly runId?: string;
+    /**
+     * The frame to resolve animated parameters at — a keyframe channel is
+     * sampled here and `$F`/`$FF`/`$T` are derived from it. Fractional frames
+     * are kept. Omitted leaves the graph on the frame it is already on.
+     *
+     * A value the caller states rather than a clock the runtime reads: same
+     * graph plus same frame gives the same output, which is what makes an
+     * offline render reproducible.
+     */
+    readonly frame?: number;
+    /** Frames per second, for `$FPS` and for `$T`. Default 30. */
+    readonly fps?: number;
 }
 export interface RunResult {
     readonly runId: string;
@@ -163,13 +175,13 @@ export type RuntimeEvent = {
     readonly runId: string;
     readonly nodeId: string;
     readonly inputName: string;
-    readonly event: import("cascade/contracts").TriggerEvent;
+    readonly event: import("@field/cascade/contracts").TriggerEvent;
 } | {
     readonly type: "trigger:delivered";
     readonly runId: string;
     readonly nodeId: string;
     readonly inputName: string;
-    readonly event: import("cascade/contracts").TriggerEvent;
+    readonly event: import("@field/cascade/contracts").TriggerEvent;
 } | {
     readonly type: "node:output";
     readonly runId: string;
@@ -203,6 +215,12 @@ export interface CascadeRuntime {
 }
 export interface LoadedCascadeGraph {
     readonly state: GraphState;
+    /**
+     * Host-aware static gate: the diagnostics `run` would raise before executing
+     * anything, collected instead of thrown. This is what lets a validator see a
+     * missing capability, which is a fault it was previously blind to.
+     */
+    preflight(): readonly Diagnostic[];
     inspect(): GraphInspection;
     setInput(nodeId: string, inputName: string, value: unknown): Promise<void>;
     setGraphInput(name: string, value: unknown): Promise<void>;
@@ -213,6 +231,14 @@ export interface LoadedCascadeGraph {
         runId?: string;
     }>): Promise<RunResult>;
     run(options?: RunOptions): Promise<RunResult>;
+    /**
+     * Move the graph's clock without cooking. Animated parameters re-resolve
+     * immediately, so `inspect()` reports them at this frame.
+     */
+    setFrame(frame: number): void;
+    setFps(fps: number): void;
+    getFrame(): number;
+    getFps(): number;
     cancel(reason?: string): void;
     subscribe(listener: (event: RuntimeEvent) => void): () => void;
     getOutput(nodeId: string, outputName: string): unknown;

package/dist/shell.d.ts

@@ -3,6 +3,6 @@ export {
   type ShellProcessErrorKind,
   type ShellRunOptions,
   type ShellRunResult,
-} from 'cascade/contracts';
-export declare function run(command: string, args?: readonly string[], options?: import('cascade/contracts').ShellRunOptions): Promise<import('cascade/contracts').ShellRunResult>;
-export declare function runJson<T = unknown>(command: string, args?: readonly string[], options?: import('cascade/contracts').ShellRunOptions): Promise<T>;
+} from '@field/cascade/contracts';
+export declare function run(command: string, args?: readonly string[], options?: import('@field/cascade/contracts').ShellRunOptions): Promise<import('@field/cascade/contracts').ShellRunResult>;
+export declare function runJson<T = unknown>(command: string, args?: readonly string[], options?: import('@field/cascade/contracts').ShellRunOptions): Promise<T>;