@field/cascade 0.8.0 → 0.10.0

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

@@ -0,0 +1,37 @@
+/**
+ * Bundle field references in expressions.
+ *
+ * `ch("format.dpi")` reads field `dpi` of the bundle wired into this node's
+ * `format` input. The path names an input, not another node's output, on
+ * purpose: the wire is the dependency, so the scheduler orders the producer
+ * first and an edit upstream reaches this parameter. Reading another node's
+ * output by absolute path would be a dependency no wire records, cooked in
+ * whatever order the graph happened to be in.
+ *
+ * Port and parameter names are identifiers, so a dot can only mean a field.
+ */
+export interface BundleFieldReference {
+    /** The input port, on the node whose parameter this is. */
+    readonly port: string;
+    readonly field: string;
+    /** The path as written. */
+    readonly path: string;
+}
+/** `format.dpi` or `./format.dpi` as port and field; null for anything else. */
+export declare function parseBundleFieldPath(path: string): {
+    port: string;
+    field: string;
+} | null;
+/** Every relative bundle field an expression reads, in source order. */
+export declare function bundleFieldReferences(expression: string): BundleFieldReference[];
+/**
+ * An absolute or parent path whose last segment looks like `port.field`:
+ * an attempt to read another node's bundle without a wire. Returned so a
+ * checker can say what to do instead.
+ */
+export declare function remoteBundlePath(path: string): {
+    node: string;
+    port: string;
+    field: string;
+} | null;
+//# sourceMappingURL=bundlePaths.d.ts.map

package/dist/runtime/expressions/bundlePaths.js

@@ -0,0 +1,55 @@
+/**
+ * Bundle field references in expressions.
+ *
+ * `ch("format.dpi")` reads field `dpi` of the bundle wired into this node's
+ * `format` input. The path names an input, not another node's output, on
+ * purpose: the wire is the dependency, so the scheduler orders the producer
+ * first and an edit upstream reaches this parameter. Reading another node's
+ * output by absolute path would be a dependency no wire records, cooked in
+ * whatever order the graph happened to be in.
+ *
+ * Port and parameter names are identifiers, so a dot can only mean a field.
+ */
+const REFERENCE = /\b(?:ch|chs|chv)\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+/** `format.dpi` or `./format.dpi` as port and field; null for anything else. */
+export function parseBundleFieldPath(path) {
+    const local = path.startsWith("./") ? path.slice(2) : path;
+    if (local.includes("/"))
+        return null;
+    const dot = local.indexOf(".");
+    if (dot <= 0 || dot === local.length - 1)
+        return null;
+    return { port: local.slice(0, dot), field: local.slice(dot + 1) };
+}
+/** Every relative bundle field an expression reads, in source order. */
+export function bundleFieldReferences(expression) {
+    const references = [];
+    REFERENCE.lastIndex = 0;
+    let match;
+    while ((match = REFERENCE.exec(expression)) !== null) {
+        const parsed = parseBundleFieldPath(match[1]);
+        if (parsed)
+            references.push({ ...parsed, path: match[1] });
+    }
+    return references;
+}
+/**
+ * An absolute or parent path whose last segment looks like `port.field`:
+ * an attempt to read another node's bundle without a wire. Returned so a
+ * checker can say what to do instead.
+ */
+export function remoteBundlePath(path) {
+    const local = path.startsWith("./") ? path.slice(2) : path;
+    const slash = local.lastIndexOf("/");
+    if (slash === -1)
+        return null;
+    const last = local.slice(slash + 1);
+    const dot = last.indexOf(".");
+    if (dot <= 0 || dot === last.length - 1)
+        return null;
+    const node = local.slice(0, slash).split("/").filter((part) => part && part !== "." && part !== "..").pop();
+    if (!node)
+        return null;
+    return { node, port: last.slice(0, dot), field: last.slice(dot + 1) };
+}
+//# sourceMappingURL=bundlePaths.js.map

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

@@ -6,6 +6,8 @@
  * evaluate parameters with the same engine.
  */
 export { ExpressionEvaluator } from "./evaluator.js";
+export { bundleFieldReferences, parseBundleFieldPath, remoteBundlePath } from "./bundlePaths.js";
+export type { BundleFieldReference } from "./bundlePaths.js";
 export { clamp, fit, fit01, lerp, noise, padzero, random, smooth } from "./math.js";
 export { TIME_IDENTIFIERS, TIME_TOKENS, hasTimeReference, preprocessExpression } from "./preprocess.js";
 export { DEFAULT_FPS, MIN_FRAME, TimeState } from "./time.js";

package/dist/runtime/expressions/index.js

@@ -6,6 +6,7 @@
  * evaluate parameters with the same engine.
  */
 export { ExpressionEvaluator } from "./evaluator.js";
+export { bundleFieldReferences, parseBundleFieldPath, remoteBundlePath } from "./bundlePaths.js";
 export { clamp, fit, fit01, lerp, noise, padzero, random, smooth } from "./math.js";
 export { TIME_IDENTIFIERS, TIME_TOKENS, hasTimeReference, preprocessExpression } from "./preprocess.js";
 export { DEFAULT_FPS, MIN_FRAME, TimeState } from "./time.js";

package/dist/runtime/index.d.ts

@@ -7,6 +7,8 @@ export * from "./geometry/index.js";
 export * from "./gpu.js";
 export * from "./params/index.js";
 export * from "./scene/index.js";
+export * from "./seed.js";
 export { createRuntime, PREFLIGHT_WARNING_CODES } from "./runtime.js";
 export type * from "./types.js";
+export * from "./edit/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.js

@@ -7,5 +7,7 @@ export * from "./geometry/index.js";
 export * from "./gpu.js";
 export * from "./params/index.js";
 export * from "./scene/index.js";
+export * from "./seed.js";
 export { createRuntime, PREFLIGHT_WARNING_CODES } from "./runtime.js";
+export * from "./edit/index.js";
 //# sourceMappingURL=index.js.map

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

@@ -33,6 +33,9 @@ export interface PropAnimatorTopology<TNode extends AnimatableNode> {
     node(id: string): TNode | undefined;
     /** The node feeding `node`'s data input at `index`, for `opinput()`. */
     inputNode(node: TNode, index: number): TNode | null;
+    /** The value wired into `node`'s input `name`, for bundle field reads
+     *  (`ch("format.dpi")`). Optional: a host without it reads none. */
+    inputValue?(node: TNode, name: string): unknown;
     /** 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. */
@@ -50,6 +53,8 @@ export declare class PropAnimator<TNode extends AnimatableNode> {
     setFps(fps: number): void;
     /** Write every bound parameter's value at the current frame into `props`. */
     resolveAll(): void;
+    /** Re-resolve one node's bound parameters, e.g. once its inputs exist. */
+    resolveNode(node: TNode): void;
     /**
      * One parameter, at the current frame.
      *

package/dist/runtime/params/animator.js

@@ -19,6 +19,7 @@
  * deterministic.
  */
 import { ExpressionEvaluator } from "../expressions/evaluator.js";
+import { parseBundleFieldPath } from "../expressions/bundlePaths.js";
 import { isBoundProp, resolvePropBinding } from "./resolve.js";
 export class PropAnimator {
     topology;
@@ -45,6 +46,11 @@ export class PropAnimator {
             for (const name of Object.keys(node.bindings))
                 this.resolve(node, name);
     }
+    /** Re-resolve one node's bound parameters, e.g. once its inputs exist. */
+    resolveNode(node) {
+        for (const name of Object.keys(node.bindings))
+            this.resolve(node, name);
+    }
     /**
      * One parameter, at the current frame.
      *
@@ -99,6 +105,16 @@ export class PropAnimator {
                 // like it works until somebody keys the parameter it points at.
                 if (owner.bindings[name])
                     return { value: this.resolve(owner, name) };
+                // `format.dpi`: a field of the bundle wired into input `format`.
+                const field = parseBundleFieldPath(name);
+                if (field && this.topology.inputValue) {
+                    const bundle = this.topology.inputValue(owner, field.port);
+                    if (bundle === null || typeof bundle !== "object")
+                        return null;
+                    if (!Object.prototype.hasOwnProperty.call(bundle, field.field))
+                        return null;
+                    return { value: bundle[field.field] };
+                }
                 if (name in owner.props)
                     return { value: owner.props[name] };
                 if (name in owner.inputs)

package/dist/runtime/runtime.js

@@ -1,10 +1,12 @@
-import { canConnectTypes, validateNodeDefinition, } from "@field/cascade/contracts";
+import { bundleFieldType, bundleSchemasCompatible, bundleValueProblem, canConnectTypes, isBundleValue, selectBundleFields, suggestName, unknownFieldMessage, 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 { bundleFieldReferences, parseBundleFieldPath, remoteBundlePath, } from "./expressions/bundlePaths.js";
 import { DEFAULT_FPS, MIN_FRAME } from "./expressions/time.js";
 import { isGpuHost } from "./gpu.js";
+import { DEFAULT_GRAPH_SEED, graphSeed, nodeSeed, seededRandom } from "./seed.js";
 /**
  * Preflight codes that describe something other than "this graph cannot run
  * here", so `run` proceeds and a checker reports them as warnings.
@@ -164,7 +166,11 @@ class Runtime {
         const connections = (document.connections ?? []).map((connection, index) => materializeConnection(connection, index, byId));
         validateCardinality(byId, connections);
         validateTopology(nodes, connections);
-        const graph = new Graph(this.host, nodes, connections, () => this.graphs.delete(graph), document.annotations);
+        const graph = new Graph(this.host, nodes, connections, () => this.graphs.delete(graph), document.annotations, graphSeed(document));
+        // The graph's own frame rate, saved with it; a run's `fps` still overrides.
+        const fps = document.timeline?.fps;
+        if (typeof fps === "number" && Number.isFinite(fps) && fps > 0)
+            graph.setFps(fps);
         this.graphs.add(graph);
         return graph;
     }
@@ -181,6 +187,7 @@ class Graph {
     nodes;
     connections;
     onDispose;
+    seed;
     graphState = "ready";
     byId;
     dataConnectionsByInput;
@@ -206,11 +213,14 @@ class Graph {
     animator;
     frame = MIN_FRAME;
     fps = DEFAULT_FPS;
-    constructor(host, nodes, connections, onDispose, annotations = []) {
+    constructor(host, nodes, connections, onDispose, annotations = [], 
+    /** The document's seed; each node's `context.seed` derives from it. */
+    seed = DEFAULT_GRAPH_SEED) {
         this.host = host;
         this.nodes = nodes;
         this.connections = connections;
         this.onDispose = onDispose;
+        this.seed = seed;
         this.byId = new Map(nodes.map((node) => [node.id, node]));
         const byInput = new Map();
         const byNode = new Map();
@@ -251,6 +261,7 @@ class Graph {
                 const source = feeding[index]?.source.nodeId;
                 return (source ? this.byId.get(source) : undefined) ?? null;
             },
+            inputValue: (node, name) => this.dataInputValue(node, name),
             // 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
@@ -447,7 +458,7 @@ class Graph {
         // 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);
+        return this.trackRun(options.target ?? { kind: "all" }, options.signal, options.runId, undefined, options.reuse === true || options.reuse === "strict" ? options.reuse : false);
     }
     trigger(nodeId, inputName, payload, options = {}) {
         const node = this.requireNode(nodeId);
@@ -486,8 +497,8 @@ class Graph {
         this.disposal ??= this.performDispose();
         return this.disposal;
     }
-    trackRun(target, signal, runId, injection) {
-        const running = this.executeRun(target, signal, runId, injection);
+    trackRun(target, signal, runId, injection, reuse = false) {
+        const running = this.executeRun(target, signal, runId, injection, reuse);
         this.activeRun = running;
         const clear = () => {
             if (this.activeRun === running)
@@ -510,7 +521,7 @@ class Graph {
         this.listeners.clear();
         this.onDispose();
     }
-    async executeRun(target, externalSignal, requestedId, injection) {
+    async executeRun(target, externalSignal, requestedId, injection, reuse = false) {
         this.requireReady();
         const runId = requestedId ?? `run-${this.runCounter++}`;
         const signal = new MutableAbortSignal((diagnostic) => this.host.report(diagnostic));
@@ -565,10 +576,20 @@ class Graph {
              */
             const insideFeedback = this.feedbackDescendants();
             const ordered = topological(this.nodes, this.connections).filter((node) => initial.includes(node) && !insideFeedback.has(node.id));
+            /** Nodes that cooked in this run, for `reuse: "strict"`. */
+            const cooked = new Set();
             for (const node of ordered) {
                 if (signal.aborted)
                     break;
+                if (reuse && this.reusable(node) && !(reuse === "strict" && this.feedsFrom(node, cooked))) {
+                    this.emit({ type: "node:start", runId, nodeId: node.id });
+                    this.emit({ type: "node:complete", runId, nodeId: node.id });
+                    continue;
+                }
                 await this.executeNode(node, runId, signal, {}, enqueue);
+                cooked.add(node.id);
+                if (!signal.aborted)
+                    node.lastCook = this.cookKey(node);
             }
             if (injection && !signal.aborted)
                 enqueue(injection.nodeId, injection.inputName, injection.payload, {
@@ -645,14 +666,23 @@ class Graph {
                 return [name, Object.freeze(values)];
             }
             const connection = connections[0];
+            const value = connection
+                ? this.requireNode(connection.source.nodeId).outputs.get(connection.source.outputName)
+                : node.inputs[name];
+            // A consumer that declares the fields it reads sees only those, so
+            // the declaration is the dependency rather than a comment about it.
             return [
                 name,
-                connection
-                    ? this.requireNode(connection.source.nodeId).outputs.get(connection.source.outputName)
-                    : node.inputs[name],
+                definition.type === "bundle" && definition.fields
+                    ? selectBundleFields(value, definition.fields)
+                    : value,
             ];
         }));
         Object.freeze(inputs);
+        // A parameter whose expression reads a wired bundle field resolves now,
+        // when the bundle has been cooked, not at the start of the run.
+        if (readsBundleFields(node))
+            this.animator.resolveNode(node);
         if (this.isRemote(node)) {
             const bridge = this.host.capabilities.serverBridge;
             if (!bridge)
@@ -680,7 +710,7 @@ class Graph {
                     const definition = node.definition.outputs?.[name];
                     if (!definition || definition.kind !== "data")
                         continue;
-                    const value = runtimeValue(response.outputs[name], definition.type, false, `${node.id}.${name}`);
+                    const value = outputValue(response.outputs[name], definition, `${node.id}.${name}`);
                     node.outputs.set(name, value);
                     this.emit({
                         type: "node:output",
@@ -709,7 +739,7 @@ class Graph {
                     }),
                 }
                 : {
-                    set: (value) => pendingData.set(name, runtimeValue(value, definition.type, false, `${node.id}.${name}`)),
+                    set: (value) => pendingData.set(name, outputValue(value, definition, `${node.id}.${name}`)),
                 },
         ]));
         const capabilityEntries = [];
@@ -733,6 +763,7 @@ class Graph {
         const progress = {
             report: (event) => this.emit({ type: "node:progress", runId, nodeId: node.id, ...event }),
         };
+        const seed = nodeSeed(this.seed, node.id);
         await node.execute({
             nodeId: node.id,
             inputs,
@@ -741,6 +772,9 @@ class Graph {
             capabilities,
             signal,
             progress,
+            seed,
+            // Fresh per cook: a node that draws N numbers draws the same N each time.
+            random: seededRandom(seed),
         });
         if (signal.aborted)
             return;
@@ -831,6 +865,79 @@ class Graph {
                     if (!this.host.capabilities[capability])
                         push("runtime/missing-capability", node.id, `Missing capability ${capability} for ${node.moduleId} (node ${node.id}) — the ${this.host.environment} host ${this.hostProvides()}`);
         }
+        diagnostics.push(...this.bundleDiagnostics(nodes));
+        return diagnostics;
+    }
+    /**
+     * Bundle fields read by name, checked against what the producer declares:
+     * a consumer's declared `fields`, an expression's `ch("format.dpi")`, and a
+     * Pick's `field`. A producer that declares no fields (Pack, a subnet Input,
+     * a project node that left them out) cannot be checked and is not. Reading
+     * another node's bundle by absolute path is refused with what to do instead.
+     */
+    bundleDiagnostics(nodes) {
+        const diagnostics = [];
+        const push = (nodeId, code, message, at = nodeId) => diagnostics.push({ phase: "preflight", code, path: at, message });
+        const producerFields = (node, input) => {
+            const connection = this.dataConnectionsByInput.get(`${node.id}\0${input}`)?.[0];
+            if (!connection)
+                return null;
+            const output = this.byId.get(connection.source.nodeId)?.definition.outputs?.[connection.source.outputName];
+            if (output?.kind !== "data" || output.type !== "bundle" || !output.fields)
+                return null;
+            return Object.keys(output.fields);
+        };
+        for (const node of nodes) {
+            for (const [name, input] of Object.entries(node.definition.inputs ?? {})) {
+                if (input.kind !== "data" || input.type !== "bundle" || !input.fields)
+                    continue;
+                const known = producerFields(node, name);
+                if (!known)
+                    continue;
+                for (const field of input.fields)
+                    if (!known.includes(field))
+                        push(node.id, "runtime/bundle-unknown-field", unknownFieldMessage(field, known, `${node.id}.${name} (declared fields)`), `${node.id}.${name}`);
+            }
+            if (node.moduleId === "cascade.core.Pick") {
+                const field = String(node.props.field ?? "").trim();
+                const known = producerFields(node, "bundle");
+                if (field && known && !known.includes(field))
+                    push(node.id, "runtime/bundle-unknown-field", unknownFieldMessage(field, known, `${node.id}.field`), `${node.id}.field`);
+            }
+            for (const [prop, binding] of Object.entries(node.bindings)) {
+                if (!binding.expression)
+                    continue;
+                for (const path of expressionPaths(binding.expression)) {
+                    const remote = remoteBundlePath(path);
+                    if (remote) {
+                        const owner = this.byId.get(remote.node);
+                        const output = owner?.definition.outputs?.[remote.port];
+                        if (output?.kind === "data" && output.type === "bundle")
+                            push(node.id, "runtime/bundle-remote-read", `${node.id}.${prop} reads "${path}", another node's bundle, without a wire. `
+                                + `Wire ${remote.node}.${remote.port} into a bundle input on ${node.id} and read "${remote.port}.${remote.field}" instead`, `${node.id}.${prop}`);
+                        continue;
+                    }
+                    const reference = parseBundleFieldPath(path);
+                    if (!reference)
+                        continue;
+                    const input = node.definition.inputs?.[reference.port];
+                    if (!input) {
+                        const ports = Object.entries(node.definition.inputs ?? {})
+                            .filter(([, item]) => item.kind === "data" && item.type === "bundle")
+                            .map(([portName]) => portName);
+                        const suggestion = suggestName(reference.port, ports);
+                        push(node.id, "runtime/bundle-unknown-port", `${node.id}.${prop} reads "${path}", but ${node.moduleId} has no input "${reference.port}"`
+                            + (suggestion ? ` — did you mean "${suggestion}.${reference.field}"?` : ""), `${node.id}.${prop}`);
+                        continue;
+                    }
+                    if (input.kind !== "data" || input.type !== "bundle")
+                        continue;
+                    const known = producerFields(node, reference.port);
+                    if (known && !known.includes(reference.field))
+                        push(node.id, "runtime/bundle-unknown-field", unknownFieldMessage(reference.field, known, `${node.id}.${prop}`), `${node.id}.${prop}`);
+                }
+            }
+        }
         return diagnostics;
     }
     /**
@@ -1012,6 +1119,66 @@ class Graph {
      * per step. Computed once per run rather than per step: the hierarchy cannot
      * change mid-run, and this is walked for every node in the order.
      */
+    /**
+     * Early cutoff for `run({ reuse: true })`: a node whose wired inputs are the
+     * very same values and whose resolved props are equal keeps its outputs.
+     *
+     * Sound because a definition-v1 node may observe only its inputs, its props
+     * and declared capabilities, and time reaches it through props. Upstream
+     * reuse keeps output identity, so one unchanged stage skips everything below
+     * it that is unchanged too. Trigger-driven, feedback and remote nodes always
+     * cook. Off by default: a host opts in when it re-runs a graph on every edit.
+     */
+    /** Whether any data input of `node` (or, for a subnet, any inner output)
+     *  comes from a node in `cooked`. */
+    feedsFrom(node, cooked) {
+        for (const name of Object.keys(node.definition.inputs ?? {})) {
+            for (const connection of this.dataConnectionsByInput.get(`${node.id}\0${name}`) ?? [])
+                if (cooked.has(connection.source.nodeId))
+                    return true;
+        }
+        if (node.moduleId === "cascade.core.Input" && node.parent && cooked.size)
+            return true;
+        if (node.moduleId === "cascade.core.Subnet")
+            for (const child of this.nodes)
+                if (child.parent === node.id && cooked.has(child.id))
+                    return true;
+        return false;
+    }
+    reusable(node) {
+        const last = node.lastCook;
+        if (!last || this.isRemote(node) || node.definition.container === "feedback")
+            return false;
+        if (Object.values(node.definition.inputs ?? {}).some((input) => input.kind === "trigger"))
+            return false;
+        if (Object.values(node.definition.outputs ?? {}).some((output) => output.kind === "trigger"))
+            return false;
+        const next = this.cookKey(node);
+        return sameValues(last.inputs, next.inputs, Object.is) && sameValues(last.props, next.props, sameJson);
+    }
+    cookKey(node) {
+        const inputs = [];
+        for (const [name, definition] of Object.entries(node.definition.inputs ?? {})) {
+            if (definition.kind !== "data")
+                continue;
+            if (node.moduleId === "cascade.core.Input" && name === "value" && node.parent) {
+                const parent = this.requireNode(node.parent);
+                inputs.push(this.dataInputValue(parent, `input_${integerProp(node.props.inputIndex)}`));
+                continue;
+            }
+            const connections = this.dataConnectionsByInput.get(`${node.id}\0${name}`) ?? [];
+            if (!connections.length)
+                inputs.push(node.inputs[name]);
+            for (const connection of connections)
+                inputs.push(this.requireNode(connection.source.nodeId).outputs.get(connection.source.outputName));
+        }
+        // A subnet's outputs are its inner Output nodes' values, which are inputs in all but name.
+        if (node.moduleId === "cascade.core.Subnet")
+            for (const child of this.nodes)
+                if (child.parent === node.id && child.moduleId === "cascade.core.Output")
+                    inputs.push(child.outputs.get("output"));
+        return { inputs, props: Object.keys(node.definition.props ?? {}).map((name) => node.props[name]) };
+    }
     feedbackDescendants() {
         const containers = new Set(this.nodes
             .filter((node) => node.definition.container === "feedback")
@@ -1480,6 +1647,12 @@ function materializeConnection(connection, index, nodes) {
         input.kind === "data" &&
         !canConnectTypes(output.type, input.type))
         misuse("runtime/connection-type", `Connection ${index} has incompatible types ${output.type} and ${input.type}`);
+    if (output.kind === "data" &&
+        input.kind === "data" &&
+        output.type === "bundle" &&
+        input.type === "bundle" &&
+        !bundleSchemasCompatible(output.schema, input.schema))
+        misuse("runtime/connection-schema", `Connection ${index} wires a ${output.schema} bundle into an input that takes ${input.schema}`);
     return Object.freeze({
         source: Object.freeze(endpoints.source),
         target: Object.freeze(endpoints.target),
@@ -1766,6 +1939,42 @@ const TUPLE_LENGTHS = {
     mat4: 16,
     color: 4,
 };
+/**
+ * An output value, checked against its declaration. A bundle with declared
+ * fields may only set those, and each one must be a valid value of its type.
+ */
+function outputValue(value, definition, path) {
+    if (definition.type !== "bundle" || !definition.fields)
+        return runtimeValue(value, definition.type, false, path);
+    const fields = definition.fields;
+    const problem = bundleValueProblem(value, fields);
+    if (problem)
+        misuse("runtime/value-type", `${path} ${problem}`);
+    if (isBundleValue(value))
+        for (const [field, item] of Object.entries(value))
+            runtimeValue(item, bundleFieldType(fields[field]), true, `${path}.${field}`);
+    return runtimeValue(value, "bundle", false, path);
+}
+/** Every path an expression names through ch/chs/chv. */
+function expressionPaths(expression) {
+    const paths = [];
+    const pattern = /\b(?:ch|chs|chv)\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+    let match;
+    while ((match = pattern.exec(expression)) !== null)
+        paths.push(match[1]);
+    return paths;
+}
+/** Whether any of a node's bound parameters reads a wired bundle field. */
+function readsBundleFields(node) {
+    for (const binding of Object.values(node.bindings))
+        if (binding.expression)
+            for (const reference of bundleFieldReferences(binding.expression)) {
+                const input = node.definition.inputs?.[reference.port];
+                if (input?.kind === "data" && input.type === "bundle")
+                    return true;
+            }
+    return false;
+}
 function runtimeValue(value, type, allowUndefined, path) {
     if (value === undefined) {
         if (allowUndefined)
@@ -1783,7 +1992,9 @@ function runtimeValue(value, type, allowUndefined, path) {
             value.every((item) => type.endsWith("i")
                 ? typeof item === "number" && Number.isInteger(item)
                 : typeof item === "number" && Number.isFinite(item))) ||
+        (type === "bundle" && isBundleValue(value)) ||
         (!tupleLength &&
+            type !== "bundle" &&
             type !== "float" &&
             type !== "int" &&
             type !== "bool" &&
@@ -1792,4 +2003,19 @@ function runtimeValue(value, type, allowUndefined, path) {
         misuse("runtime/value-type", `${path} is not a valid ${type}`);
     return snapshot(value);
 }
+function sameValues(a, b, equal) {
+    return a.length === b.length && a.every((value, index) => equal(value, b[index]));
+}
+function sameJson(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== "object" || typeof b !== "object" || a === null || b === null)
+        return false;
+    try {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    catch {
+        return false;
+    }
+}
 //# sourceMappingURL=runtime.js.map

package/dist/runtime/seed.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Seeds: one number per graph, one derived number per node, the same in every
+ * host.
+ *
+ * A node that wants randomness gets `context.seed` and `context.random` from
+ * whichever host cooks it — the headless runtime here, Studio through its
+ * definition adapter — and both compute them with these functions. So the
+ * same graph draws the same dots headless and in Studio, and changing the
+ * graph's `seed` reshuffles every node at once while each keeps its own
+ * stream (doc/PRODUCTION_READINESS.md, item 5).
+ *
+ * The node id is part of the derivation, not its position: ids are stable
+ * across edits, so adding a node never reshuffles its neighbours.
+ */
+/** The graph seed when a document does not state one. */
+export declare const DEFAULT_GRAPH_SEED = 0;
+/** A document's `seed`, as an unsigned 32-bit integer; the default when absent
+ *  or not an integer. */
+export declare function graphSeed(document: Readonly<{
+    seed?: unknown;
+}> | null | undefined): number;
+/**
+ * A node's seed: FNV-1a over `<graph seed>:<node id>`, finished with
+ * MurmurHash3's avalanche so neighbouring ids give unrelated seeds.
+ */
+export declare function nodeSeed(seedOfGraph: number, nodeId: string): number;
+/** Mulberry32: a small, fast stream of floats in [0, 1) from one seed. */
+export declare function seededRandom(seed: number): () => number;
+//# sourceMappingURL=seed.d.ts.map