@field/cascade 0.4.0 → 0.5.1

package/dist/runtime/runtime.js

@@ -556,7 +556,15 @@ class Graph {
                 queue.push({ nodeId, inputName, event });
                 this.emit({ type: "trigger:queued", runId, nodeId, inputName, event });
             };
-            const ordered = topological(this.nodes, this.connections).filter((node) => initial.includes(node));
+            /**
+             * Feedback descendants are removed from the main order: their container
+             * runs them, once per step. Leaving them here would cook each of them a
+             * second time, out of the loop and with whatever state the last step
+             * happened to leave behind — which reads as a simulation that is one step
+             * wrong rather than as a scheduling bug.
+             */
+            const insideFeedback = this.feedbackDescendants();
+            const ordered = topological(this.nodes, this.connections).filter((node) => initial.includes(node) && !insideFeedback.has(node.id));
             for (const node of ordered) {
                 if (signal.aborted)
                     break;
@@ -601,6 +609,24 @@ class Graph {
     }
     async executeNode(node, runId, signal, triggers, enqueue) {
         this.emit({ type: "node:start", runId, nodeId: node.id });
+        /**
+         * `cascade.core.Previous` reads the carried state off its container, the
+         * same way `cascade.core.Input` reads the parent's wired input: a boundary's
+         * value comes from the parent's evaluation, not from a wire of its own.
+         *
+         * Outside a container it falls through to its own `initial`, which is what
+         * makes a node dragged out of a loop explicable rather than an error.
+         */
+        if (node.moduleId === "cascade.core.Previous") {
+            const container = this.enclosingFeedback(node);
+            const state = container ? this.feedbackState.get(container) : undefined;
+            if (state) {
+                node.outputs.set("value", state.value);
+                node.outputs.set("step", state.step);
+                this.emit({ type: "node:complete", runId, nodeId: node.id });
+                return;
+            }
+        }
         const inputs = Object.fromEntries(Object.entries(node.definition.inputs ?? {}).map(([name, definition]) => {
             if (definition.kind === "trigger")
                 return [name, triggers[name]];
@@ -718,6 +744,15 @@ class Graph {
         });
         if (signal.aborted)
             return;
+        if (node.definition.container === "feedback") {
+            // Resolved here rather than in the node's own execute, because the loop
+            // needs the graph and a definition-v1 node is given only its own id.
+            const feedback = await this.runFeedback(node, runId, signal, enqueue);
+            if (signal.aborted)
+                return;
+            pendingData.set("result", feedback.result);
+            pendingData.set("history", feedback.history);
+        }
         if (node.moduleId === "cascade.core.Subnet") {
             for (const child of this.nodes) {
                 if (child.parent !== node.id ||
@@ -958,6 +993,128 @@ class Graph {
     isDisposed() {
         return this.graphState === "disposed";
     }
+    /**
+     * The state a feedback container is carrying, while it is running.
+     *
+     * Runtime state on the instance rather than on the node, because it is alive
+     * only during one container's loop and a node's `outputs` map is the graph's
+     * result — putting a half-finished step in there would make a partially
+     * simulated value readable by anything that inspects outputs mid-run.
+     *
+     * Keyed by container id so nested feedback works: an outer loop's carried
+     * state survives an inner loop running to completion inside one of its steps.
+     */
+    feedbackState = new Map();
+    /**
+     * Every node under a feedback container, transitively.
+     *
+     * These are excluded from the main cook order — the container runs them, once
+     * 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.
+     */
+    feedbackDescendants() {
+        const containers = new Set(this.nodes
+            .filter((node) => node.definition.container === "feedback")
+            .map((node) => node.id));
+        if (!containers.size)
+            return new Set();
+        const inside = new Set();
+        for (const node of this.nodes) {
+            let parent = node.parent;
+            const seen = new Set();
+            while (parent && !seen.has(parent)) {
+                seen.add(parent);
+                if (containers.has(parent)) {
+                    inside.add(node.id);
+                    break;
+                }
+                parent = this.byId.get(parent)?.parent;
+            }
+        }
+        return inside;
+    }
+    /**
+     * Run a feedback container's contents `steps` times and return the last
+     * result.
+     *
+     * The order the children run in is the graph's own topological order
+     * restricted to this container's descendants, which is what makes the forces
+     * inside behave like nodes rather than like a list: wiring one into another
+     * changes the order they apply in.
+     */
+    async runFeedback(node, runId, signal, enqueue) {
+        const initial = this.dataInputValue(node, "initial");
+        const requested = this.dataInputValue(node, "steps");
+        const steps = Math.max(0, Math.trunc(Number(requested ?? 0)));
+        if (!Number.isFinite(steps))
+            throw runtimeError("runtime/feedback-steps", `${node.id}.steps is not a finite number`);
+        const children = topological(this.nodes, this.connections).filter((child) => this.enclosingFeedback(child) === node.id);
+        // The step's result comes from the Output boundary at index 0, the same
+        // convention a subnet uses. Resolved before the loop so that a container
+        // with no Output fails immediately rather than after simulating everything
+        // and finding nothing to return.
+        const sink = children.find((child) => child.parent === node.id &&
+            child.moduleId === "cascade.core.Output" &&
+            integerProp(child.props.outputIndex) === 0);
+        if (steps > 0 && !sink)
+            throw runtimeError("runtime/feedback-no-output", `${node.id} has no cascade.core.Output inside it, so a step has no result to carry. Add one and wire the step's result into it.`);
+        /**
+         * How many step results to keep for the `history` output.
+         *
+         * Zero by default and read once, before the loop: a simulation that
+         * quietly held every frame of its own geometry would be the difference
+         * between a preview and a tab that runs out of memory, so keeping history
+         * is something a graph asks for and bounds.
+         */
+        const keep = Math.max(0, integerProp(node.props.history));
+        const history = [];
+        // Zero steps is the initial state, not a failure: frame zero of a
+        // simulation is where it starts, and a graph that throws at the beginning
+        // of the timeline is unusable.
+        let carried = initial;
+        try {
+            for (let step = 0; step < steps; step += 1) {
+                if (signal.aborted)
+                    break;
+                this.feedbackState.set(node.id, { value: carried, step });
+                for (const child of children) {
+                    if (signal.aborted)
+                        break;
+                    await this.executeNode(child, runId, signal, {}, enqueue);
+                }
+                if (signal.aborted)
+                    break;
+                carried = sink.outputs.get("output");
+                if (keep > 0) {
+                    history.push(carried);
+                    // Trimmed inside the loop rather than after it, so the peak memory is
+                    // the cap and not the step count.
+                    if (history.length > keep)
+                        history.shift();
+                }
+            }
+            return Object.freeze({
+                result: carried,
+                history: Object.freeze(history),
+            });
+        }
+        finally {
+            this.feedbackState.delete(node.id);
+        }
+    }
+    /** The nearest ancestor that is a feedback container, or undefined. */
+    enclosingFeedback(node) {
+        let parent = node.parent;
+        const seen = new Set();
+        while (parent && !seen.has(parent)) {
+            seen.add(parent);
+            const candidate = this.byId.get(parent);
+            if (candidate?.definition.container === "feedback")
+                return candidate.id;
+            parent = candidate?.parent;
+        }
+        return undefined;
+    }
     requireNode(id) {
         const node = this.byId.get(id);
         if (!node)
@@ -1351,8 +1508,9 @@ function validateHierarchy(nodes, byId) {
         const parent = byId.get(node.parent);
         if (!parent)
             misuse("runtime/parent-not-found", `Node ${node.id} references missing parent ${node.parent}`);
-        if (parent.definition.container !== "subnet")
-            misuse("runtime/parent-not-container", `Node ${node.id} parent ${node.parent} is not a subnet container`);
+        if (parent.definition.container !== "subnet" &&
+            parent.definition.container !== "feedback")
+            misuse("runtime/parent-not-container", `Node ${node.id} parent ${node.parent} is not a container`);
     }
     for (const node of nodes) {
         const visited = new Set([node.id]);
@@ -1482,6 +1640,66 @@ function dataDependencies(nodes, connections) {
             dependencies.set(`${dependency.sourceId}\0${dependency.targetId}`, dependency);
         }
     }
+    /**
+     * Project data dependencies across every Feedback boundary they cross.
+     *
+     * Feedback descendants are removed from the main execution order because
+     * their container runs them. Therefore an outside source wired to a child
+     * must delay every enclosing container, and a child wired to an outside
+     * consumer must make that consumer wait for the container. Nested or sibling
+     * loops need the same projection between their scheduled containers.
+     *
+     * Shared ancestors are excluded: a wire whose endpoints are already inside
+     * the same loop orders the children only. Projecting it onto that shared
+     * container would create a false container-to-itself cycle.
+     */
+    const parents = new Map(nodes.map((node) => [node.id, node.parent]));
+    const feedbackContainers = new Set(nodes
+        .filter((node) => node.definition.container === "feedback")
+        .map((node) => node.id));
+    if (feedbackContainers.size) {
+        const feedbackLineage = (id) => {
+            const lineage = [];
+            const seen = new Set();
+            let current = id;
+            while (current && !seen.has(current)) {
+                seen.add(current);
+                if (feedbackContainers.has(current))
+                    lineage.push(current);
+                current = parents.get(current);
+            }
+            return lineage;
+        };
+        const add = (sourceId, targetId) => {
+            if (sourceId === targetId)
+                return;
+            const dependency = { sourceId, targetId };
+            dependencies.set(`${sourceId}\0${targetId}`, dependency);
+        };
+        for (const connection of connections) {
+            if (connection.kind !== "data")
+                continue;
+            const sourceLineage = feedbackLineage(connection.source.nodeId);
+            const targetLineage = feedbackLineage(connection.target.nodeId);
+            const sourceSet = new Set(sourceLineage);
+            const targetSet = new Set(targetLineage);
+            const crossedFrom = sourceLineage.filter((id) => !targetSet.has(id));
+            const crossedInto = targetLineage.filter((id) => !sourceSet.has(id));
+            if (crossedFrom.length > 0 && crossedInto.length > 0) {
+                for (const sourceId of crossedFrom)
+                    for (const targetId of crossedInto)
+                        add(sourceId, targetId);
+            }
+            else if (crossedFrom.length > 0) {
+                for (const sourceId of crossedFrom)
+                    add(sourceId, connection.target.nodeId);
+            }
+            else {
+                for (const targetId of crossedInto)
+                    add(connection.source.nodeId, targetId);
+            }
+        }
+    }
     return [...dependencies.values()];
 }
 function runtimeError(code, message) {

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

@@ -0,0 +1,50 @@
+import type { Scene } from "@field/cascade/contracts";
+import { type Bounds } from "../geometry/primitives.js";
+export type { Bounds };
+/**
+ * Axis-aligned bounds over every geometry in the scene, or `undefined` when
+ * there is nothing in it.
+ *
+ * Always three components, even when every geometry inside is 2D — a 2D
+ * geometry's `P` has a `size` of 2 and `geometryBounds` returns two components
+ * for it, and a viewport doing arithmetic on `min[2]` needs it to be `0` rather
+ * than `undefined`. Padding here rather than at each caller is the whole reason
+ * this function exists instead of callers mapping `geometryBounds`.
+ */
+export declare function sceneBounds(scene: Scene): Bounds | undefined;
+export interface SceneDimensionality {
+    readonly is2d: boolean;
+    /** Why. Shown in the viewport's mode control, so it is never a mystery. */
+    readonly reason: "camera" | "normals" | "depth" | "flat" | "empty";
+}
+/**
+ * Is this scene flat enough to look at as a drawing?
+ *
+ * Marcus, 2026-09-09: *"i want the viewer to detect if our geometry is 2D or 3D
+ * and adapt the viewport accordingly … unless our geometry / camera wants a 3D
+ * view."*
+ *
+ * Three conditions, and every one of them is a **fact about the cooked output**
+ * rather than a guess about intent, which is the property that makes this
+ * safe to act on:
+ *
+ * 1. A wired camera forces 3D whatever the bounds say. That is the *"unless the
+ *    camera wants a 3D view"* clause, and it is also the escape hatch for a
+ *    deliberately flat 3D scene — somebody who wires a camera has said which
+ *    way they are looking at it.
+ * 2. A point `N` attribute forces 3D. Normals only mean something on a surface.
+ * 3. Otherwise, flat iff the Z extent is below a relative epsilon.
+ *
+ * ## This may only ever set the *initial* mode
+ *
+ * A particle simulation can be planar at frame 1 and gain depth by frame 20.
+ * Re-running this on every cook would flip the viewport mid-playback, which is
+ * worse than either mode would have been. So the Viewer calls this **once**,
+ * when a node has no remembered view, and never again — which is why the
+ * per-node view memory is not a separate feature but the thing that makes
+ * detect-once implementable at all. Without somewhere to keep the answer the
+ * only options are re-detecting, which flips, and never detecting, which is
+ * useless.
+ */
+export declare function sceneDimensionality(scene: Scene): SceneDimensionality;
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/scene/index.js

@@ -0,0 +1,94 @@
+import { geometryBounds } from "../geometry/primitives.js";
+/**
+ * Axis-aligned bounds over every geometry in the scene, or `undefined` when
+ * there is nothing in it.
+ *
+ * Always three components, even when every geometry inside is 2D — a 2D
+ * geometry's `P` has a `size` of 2 and `geometryBounds` returns two components
+ * for it, and a viewport doing arithmetic on `min[2]` needs it to be `0` rather
+ * than `undefined`. Padding here rather than at each caller is the whole reason
+ * this function exists instead of callers mapping `geometryBounds`.
+ */
+export function sceneBounds(scene) {
+    const min = [
+        Number.POSITIVE_INFINITY,
+        Number.POSITIVE_INFINITY,
+        Number.POSITIVE_INFINITY,
+    ];
+    const max = [
+        Number.NEGATIVE_INFINITY,
+        Number.NEGATIVE_INFINITY,
+        Number.NEGATIVE_INFINITY,
+    ];
+    let found = false;
+    for (const geometry of scene.geometry) {
+        const bounds = geometryBounds(geometry);
+        if (bounds === undefined)
+            continue;
+        found = true;
+        for (let axis = 0; axis < 3; axis += 1) {
+            const low = bounds.min[axis] ?? 0;
+            const high = bounds.max[axis] ?? 0;
+            if (low < min[axis])
+                min[axis] = low;
+            if (high > max[axis])
+                max[axis] = high;
+        }
+    }
+    return found ? { min, max } : undefined;
+}
+/**
+ * Relative epsilon for the flatness test.
+ *
+ * Absolute would be wrong in both directions: a scene in millimetres is
+ * legitimately 0.4 deep, and a scene in metres can carry 0.4 of floating-point
+ * noise on a plane that was meant to be flat. So the test is against the scene's
+ * own size.
+ */
+const FLATNESS_EPSILON = 1e-6;
+/**
+ * Is this scene flat enough to look at as a drawing?
+ *
+ * Marcus, 2026-09-09: *"i want the viewer to detect if our geometry is 2D or 3D
+ * and adapt the viewport accordingly … unless our geometry / camera wants a 3D
+ * view."*
+ *
+ * Three conditions, and every one of them is a **fact about the cooked output**
+ * rather than a guess about intent, which is the property that makes this
+ * safe to act on:
+ *
+ * 1. A wired camera forces 3D whatever the bounds say. That is the *"unless the
+ *    camera wants a 3D view"* clause, and it is also the escape hatch for a
+ *    deliberately flat 3D scene — somebody who wires a camera has said which
+ *    way they are looking at it.
+ * 2. A point `N` attribute forces 3D. Normals only mean something on a surface.
+ * 3. Otherwise, flat iff the Z extent is below a relative epsilon.
+ *
+ * ## This may only ever set the *initial* mode
+ *
+ * A particle simulation can be planar at frame 1 and gain depth by frame 20.
+ * Re-running this on every cook would flip the viewport mid-playback, which is
+ * worse than either mode would have been. So the Viewer calls this **once**,
+ * when a node has no remembered view, and never again — which is why the
+ * per-node view memory is not a separate feature but the thing that makes
+ * detect-once implementable at all. Without somewhere to keep the answer the
+ * only options are re-detecting, which flips, and never detecting, which is
+ * useless.
+ */
+export function sceneDimensionality(scene) {
+    if (scene.camera !== null)
+        return { is2d: false, reason: "camera" };
+    for (const geometry of scene.geometry)
+        if (geometry.point.N !== undefined)
+            return { is2d: false, reason: "normals" };
+    const bounds = sceneBounds(scene);
+    if (bounds === undefined)
+        return { is2d: true, reason: "empty" };
+    const depth = (bounds.max[2] ?? 0) - (bounds.min[2] ?? 0);
+    const size = Math.max((bounds.max[0] ?? 0) - (bounds.min[0] ?? 0), (bounds.max[1] ?? 0) - (bounds.min[1] ?? 0), Math.abs(bounds.max[2] ?? 0), Math.abs(bounds.min[2] ?? 0));
+    const tolerance = Math.max(size, 1) * FLATNESS_EPSILON;
+    return depth <= tolerance
+        ? { is2d: true, reason: "flat" }
+        : { is2d: false, reason: "depth" };
+}
+//# sourceMappingURL=index.js.map

package/dist/studio/panel.d.ts

@@ -8,9 +8,76 @@ export interface ProjectPanelMeta {
 
 export interface ProjectPanelApi {
   runStage<T = unknown>(stage: string, args: Record<string, unknown>): Promise<T>;
-  mediaUrl(path: string, options?: { width?: number; raw?: boolean }): string;
+  /** `version` busts a cache when a re-render reuses a path. It existed in
+   *  core and not in this type, so a panel could not reach it. */
+  mediaUrl(path: string, options?: { width?: number; raw?: boolean; version?: string | number }): string;
+  /**
+   * A parameter's RESOLVED value — a keyframe channel first, then an
+   * expression, then the stored value. What the node's `execute` sees.
+   *
+   * Which means it is **not** the inverse of `setParam` when the parameter
+   * carries a binding. Use `getRawParam` to read back a write.
+   */
   getParam<T = unknown>(nodeId: string, name: string): T | undefined;
+  /**
+   * A parameter's STORED value, before a channel or an expression resolves it.
+   *
+   * This is what `setParam` writes, so it is the one to read back after a
+   * write. Added 2026-09-09: a panel that wrote a value and re-read it with
+   * `getParam` got the resolved value, concluded its write had failed, and
+   * re-rendered a whole series at the parameter it had just replaced. Nothing
+   * threw and nothing logged.
+   */
+  getRawParam<T = unknown>(nodeId: string, name: string): T | undefined;
+  /**
+   * Write a parameter's stored value.
+   *
+   * Clears a *declared default* expression, because a default expression is a
+   * default and the written value wins. **Throws when a channel or an
+   * author-written expression would shadow the write**, naming which — those
+   * legitimately win, and silently storing a value nobody will ever read is
+   * how a panel comes to believe a parameter is broken. Clear the binding
+   * first if the write is meant to take effect.
+   */
   setParam(nodeId: string, name: string, value: unknown): void;
+  /**
+   * A node's output value, read-only.
+   *
+   * Added 2026-09-09, and it is the one whose absence distorted a whole
+   * sketch. A panel could set parameters and not read results, so the series
+   * panel reached its own outputs through **two extra nodes and a stage**: a
+   * node whose only purpose was to write a value to disk, and a Python stage
+   * that cooked a graph so the panel could fetch it back. Both delete with
+   * this. A panel that can write and not read is half a surface.
+   *
+   * A snapshot rather than a live handle, and read-only on purpose: a panel
+   * that could mutate an output would be writing into the middle of the
+   * dependency graph, where nothing downstream would know.
+   */
+  getOutput<T = unknown>(nodeId: string, outputName: string): T | undefined;
+  /** Every output of a node, by name. For a panel that does not know the
+   *  shape of what it is looking at. */
+  getOutputs(nodeId: string): Readonly<Record<string, unknown>>;
+  /**
+   * Cook the graph, or one node's subtree, and resolve when it settles.
+   *
+   * A panel could ignore work through `api.signal` and could not start or stop
+   * any, so `PLAN series`' cancellable queue was not implementable from a panel
+   * at all.
+   *
+   * **There is deliberately no `background` option**, and finding out why cost
+   * an hour: cooking *the graph* in the background is incoherent, because the
+   * graph has one state. A background cook either merges with interactive work
+   * or fights it — and concretely, routing one through `scheduler.flush` made
+   * it cancel itself, since `flush` preempts the background lane by design.
+   * Measured, not reasoned: every such call returned `'preempted'`.
+   *
+   * The background lane is for cooking a *different parameter set*, which means
+   * driving nodes directly rather than through the shared queue. That belongs
+   * to the series mechanism rather than to a panel, and a panel will reach it
+   * through the series API instead.
+   */
+  cook(options?: { readonly nodeId?: string }): Promise<void>;
   selectedNodeId(): string | null;
   readonly sourceNodeId: string | null;
   readonly signal: AbortSignal;

package/doc/HEADLESS_GPU.md

@@ -8,10 +8,10 @@ DOM, WebGL, canvas presentation, image decoding, or video APIs.
 
 ## Decision and release status
 
-Implemented on 2026-09-08 and checked in as source version `0.3.2`; see the
-[changelog](../CHANGELOG.md). Checking in the source does not publish the npm
-package. Use a built checkout or a tarball known to include the feature until
-the corresponding package release is published.
+Implemented on 2026-09-08 as source version `0.3.2` and included in the 0.5
+release; see the [changelog](../CHANGELOG.md). Use the project-local CLI and
+record its version when comparing renders. A source checkout may contain
+changes beyond the installed npm package.
 
 The decision is to use optional native Dawn for browser-independent GPU
 execution and agent image feedback. Browser automation remains useful for