@field/cascade 0.3.1 → 0.5.1

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

@@ -79,8 +79,176 @@ declare const subnetDefinition: {
     readonly description: "Contains a nested deterministic graph";
     readonly icon: "Folder";
 };
+/**
+ * `cascade.core.Feedback` — a container whose contents run once per step, with
+ * the previous step's result carried forward.
+ *
+ * Marcus, 2026-09-09, trying to dive into the particle node: *"how do i jump
+ * into the sim node and see its network of forces."* He could not, and the
+ * reason was structural rather than a missing handler: **a subnet in Cascade is
+ * a grouping, not an evaluation context.** Its children are ordinary nodes in
+ * one flat graph, cooked once each. So "the forces are nodes inside, replayed
+ * per timestep" had nowhere to live.
+ *
+ * This is that place, and it is the one construct a pure DAG cannot express. A
+ * simulation is `state = f(state)` repeated, which is a cycle — and every
+ * dataflow system that supports simulation makes it special somewhere. Houdini's
+ * Solver SOP is a subnet with a `Prev_Frame` input; this is the same shape with
+ * `cascade.core.Previous` in place of that input.
+ *
+ * ## The contract
+ *
+ * - `initial` seeds the first step. Whatever type it carries, the loop carries.
+ * - `steps` is how many times the contents run. **An input rather than a prop**,
+ *   because the whole point is to drive it from `cascade.core.Time` — a frame
+ *   pinned in a prop is exactly the bug that made the timeline do nothing.
+ * - Inside, `cascade.core.Previous` emits the carried value: `initial` on the
+ *   first step, and the previous step's result after that.
+ * - Inside, `cascade.core.Output` at index 0 is the step's result. Without one
+ *   the loop has no result to carry and the container refuses rather than
+ *   quietly returning `initial` — a simulation that silently does not simulate
+ *   is the worst available failure.
+ *
+ * ## What it does not do, deliberately
+ *
+ * **`steps` of zero returns `initial` unchanged.** That is not an error: frame
+ * zero of a simulation is its initial state, and a graph that throws at the
+ * start of the timeline is unusable.
+ *
+ * **There is no per-step caching here.** The container re-runs from `initial`
+ * every cook, which is O(steps) and honest — the same choice `pop.Simulate`
+ * already made, for the same reason: re-simulation from the start is the
+ * definition of correctness, and a cache is an optimisation layered on top of a
+ * thing that is already right.
+ */
+declare const feedbackDefinition: {
+    readonly apiVersion: 1;
+    readonly runsOn: "portable";
+    readonly container: "feedback";
+    readonly label: "Feedback";
+    readonly description: "Runs its contents once per step, carrying the previous result forward.";
+    readonly icon: "Repeat";
+    readonly inputs: {
+        readonly initial: {
+            readonly kind: "data";
+            readonly type: "any";
+            readonly default: null;
+            readonly description: "The state the first step starts from.";
+        };
+        readonly steps: {
+            readonly kind: "data";
+            readonly type: "int";
+            readonly default: 1;
+            readonly min: 0;
+            readonly description: "How many times the contents run. Drive it from a Time node.";
+        };
+    };
+    readonly outputs: {
+        readonly result: {
+            readonly kind: "data";
+            readonly type: "any";
+            readonly description: "The last step's result, or `initial` when steps is zero.";
+        };
+        /**
+         * Every kept step, oldest first.
+         *
+         * This exists because **a trail needs the history, not the final state**,
+         * and nothing outside the loop could reconstruct it: a downstream node sees
+         * one frame, which draws nothing. Houdini's Trail SOP has the same
+         * requirement and solves it the same way, by being given the frames.
+         *
+         * Empty unless `history` is non-zero, because the alternative is a
+         * simulation that quietly holds 120 copies of its own geometry — and at
+         * a few thousand particles that is the difference between a preview and a
+         * tab that runs out of memory.
+         */
+        readonly history: {
+            readonly kind: "data";
+            readonly type: "array";
+            readonly description: "The kept step results, oldest first. Empty unless History is set.";
+        };
+    };
+    readonly props: {
+        /**
+         * How many step results to keep, newest-biased: `0` keeps none, `N` keeps
+         * the last `N`.
+         *
+         * A prop rather than an input because it is structural — how much memory
+         * this loop is allowed — rather than something to animate. It is also a
+         * cap rather than a flag on purpose: "keep everything" is not offered,
+         * because the honest version of that is a number somebody chose.
+         */
+        readonly history: {
+            readonly type: "int";
+            readonly default: 0;
+            readonly min: 0;
+            readonly max: 100000;
+            readonly label: "History";
+            readonly description: "Keep the last N step results on the history output. 0 keeps none.";
+        };
+    };
+};
+/**
+ * `cascade.core.Previous` — the carried state, inside a feedback container.
+ *
+ * The counterpart to `cascade.core.Input`, and it resolves the same way: the
+ * runtime special-cases the module id and supplies the value, because a
+ * boundary node's input comes from its parent rather than from a wire. What it
+ * emits is `initial` on the first step and the previous step's `Output` after
+ * that.
+ *
+ * It also carries the step number, which is what a force needs to evolve noise
+ * or ramp a strength over the run — and having it here rather than as a global
+ * keeps a step-dependent node a pure function of its inputs.
+ *
+ * Outside a feedback container it emits its own `initial` input and a step of
+ * zero. Not an error: a node dragged out of a container should show something
+ * explicable rather than throw, and the alternative is a graph that cannot be
+ * edited without first being valid.
+ */
+declare const previousDefinition: {
+    readonly apiVersion: 1;
+    readonly runsOn: "portable";
+    readonly label: "Previous";
+    readonly description: "The previous step's state, inside a Feedback container. The first step gets the container's initial value.";
+    readonly icon: "Rewind";
+    readonly inputs: {
+        readonly initial: {
+            readonly kind: "data";
+            readonly type: "any";
+            readonly default: null;
+            readonly description: "Used only outside a Feedback container.";
+        };
+    };
+    readonly outputs: {
+        readonly value: {
+            readonly kind: "data";
+            readonly type: "any";
+            readonly description: "The carried state.";
+        };
+        readonly step: {
+            readonly kind: "data";
+            readonly type: "int";
+            readonly description: "Zero-based step index.";
+        };
+    };
+    readonly props: {};
+};
 export declare const inputRegistration: DefinitionNodeRegistration<typeof inputDefinition>;
 export declare const outputRegistration: DefinitionNodeRegistration<typeof outputDefinition>;
 export declare const subnetRegistration: DefinitionNodeRegistration<typeof subnetDefinition>;
+/**
+ * Both of these have an empty `execute`, and that is the design rather than a
+ * stub: the runtime supplies their behaviour because both are *boundaries*, and
+ * a boundary's value comes from its parent's evaluation rather than from its own
+ * inputs. `cascade.core.Subnet` and `cascade.core.Input` already work this way.
+ *
+ * Writing the loop in `Feedback.execute` instead would need the node to reach
+ * the graph, its children and the scheduler — and `NodeExecutionContext` gives
+ * a node its own id and nothing else, deliberately, which is what keeps a
+ * definition-v1 node a pure function of its inputs.
+ */
+export declare const feedbackRegistration: DefinitionNodeRegistration<typeof feedbackDefinition>;
+export declare const previousRegistration: DefinitionNodeRegistration<typeof previousDefinition>;
 export {};
 //# sourceMappingURL=structural.d.ts.map

package/dist/runtime/builtins/core/structural.js

@@ -42,6 +42,153 @@ const subnetDefinition = {
     description: "Contains a nested deterministic graph",
     icon: "Folder",
 };
+/**
+ * `cascade.core.Feedback` — a container whose contents run once per step, with
+ * the previous step's result carried forward.
+ *
+ * Marcus, 2026-09-09, trying to dive into the particle node: *"how do i jump
+ * into the sim node and see its network of forces."* He could not, and the
+ * reason was structural rather than a missing handler: **a subnet in Cascade is
+ * a grouping, not an evaluation context.** Its children are ordinary nodes in
+ * one flat graph, cooked once each. So "the forces are nodes inside, replayed
+ * per timestep" had nowhere to live.
+ *
+ * This is that place, and it is the one construct a pure DAG cannot express. A
+ * simulation is `state = f(state)` repeated, which is a cycle — and every
+ * dataflow system that supports simulation makes it special somewhere. Houdini's
+ * Solver SOP is a subnet with a `Prev_Frame` input; this is the same shape with
+ * `cascade.core.Previous` in place of that input.
+ *
+ * ## The contract
+ *
+ * - `initial` seeds the first step. Whatever type it carries, the loop carries.
+ * - `steps` is how many times the contents run. **An input rather than a prop**,
+ *   because the whole point is to drive it from `cascade.core.Time` — a frame
+ *   pinned in a prop is exactly the bug that made the timeline do nothing.
+ * - Inside, `cascade.core.Previous` emits the carried value: `initial` on the
+ *   first step, and the previous step's result after that.
+ * - Inside, `cascade.core.Output` at index 0 is the step's result. Without one
+ *   the loop has no result to carry and the container refuses rather than
+ *   quietly returning `initial` — a simulation that silently does not simulate
+ *   is the worst available failure.
+ *
+ * ## What it does not do, deliberately
+ *
+ * **`steps` of zero returns `initial` unchanged.** That is not an error: frame
+ * zero of a simulation is its initial state, and a graph that throws at the
+ * start of the timeline is unusable.
+ *
+ * **There is no per-step caching here.** The container re-runs from `initial`
+ * every cook, which is O(steps) and honest — the same choice `pop.Simulate`
+ * already made, for the same reason: re-simulation from the start is the
+ * definition of correctness, and a cache is an optimisation layered on top of a
+ * thing that is already right.
+ */
+const feedbackDefinition = {
+    apiVersion: 1,
+    runsOn: "portable",
+    container: "feedback",
+    label: "Feedback",
+    description: "Runs its contents once per step, carrying the previous result forward.",
+    icon: "Repeat",
+    inputs: {
+        initial: {
+            kind: "data",
+            type: "any",
+            default: null,
+            description: "The state the first step starts from.",
+        },
+        steps: {
+            kind: "data",
+            type: "int",
+            default: 1,
+            min: 0,
+            description: "How many times the contents run. Drive it from a Time node.",
+        },
+    },
+    outputs: {
+        result: {
+            kind: "data",
+            type: "any",
+            description: "The last step's result, or `initial` when steps is zero.",
+        },
+        /**
+         * Every kept step, oldest first.
+         *
+         * This exists because **a trail needs the history, not the final state**,
+         * and nothing outside the loop could reconstruct it: a downstream node sees
+         * one frame, which draws nothing. Houdini's Trail SOP has the same
+         * requirement and solves it the same way, by being given the frames.
+         *
+         * Empty unless `history` is non-zero, because the alternative is a
+         * simulation that quietly holds 120 copies of its own geometry — and at
+         * a few thousand particles that is the difference between a preview and a
+         * tab that runs out of memory.
+         */
+        history: {
+            kind: "data",
+            type: "array",
+            description: "The kept step results, oldest first. Empty unless History is set.",
+        },
+    },
+    props: {
+        /**
+         * How many step results to keep, newest-biased: `0` keeps none, `N` keeps
+         * the last `N`.
+         *
+         * A prop rather than an input because it is structural — how much memory
+         * this loop is allowed — rather than something to animate. It is also a
+         * cap rather than a flag on purpose: "keep everything" is not offered,
+         * because the honest version of that is a number somebody chose.
+         */
+        history: {
+            type: "int",
+            default: 0,
+            min: 0,
+            max: 100000,
+            label: "History",
+            description: "Keep the last N step results on the history output. 0 keeps none.",
+        },
+    },
+};
+/**
+ * `cascade.core.Previous` — the carried state, inside a feedback container.
+ *
+ * The counterpart to `cascade.core.Input`, and it resolves the same way: the
+ * runtime special-cases the module id and supplies the value, because a
+ * boundary node's input comes from its parent rather than from a wire. What it
+ * emits is `initial` on the first step and the previous step's `Output` after
+ * that.
+ *
+ * It also carries the step number, which is what a force needs to evolve noise
+ * or ramp a strength over the run — and having it here rather than as a global
+ * keeps a step-dependent node a pure function of its inputs.
+ *
+ * Outside a feedback container it emits its own `initial` input and a step of
+ * zero. Not an error: a node dragged out of a container should show something
+ * explicable rather than throw, and the alternative is a graph that cannot be
+ * edited without first being valid.
+ */
+const previousDefinition = {
+    apiVersion: 1,
+    runsOn: "portable",
+    label: "Previous",
+    description: "The previous step's state, inside a Feedback container. The first step gets the container's initial value.",
+    icon: "Rewind",
+    inputs: {
+        initial: {
+            kind: "data",
+            type: "any",
+            default: null,
+            description: "Used only outside a Feedback container.",
+        },
+    },
+    outputs: {
+        value: { kind: "data", type: "any", description: "The carried state." },
+        step: { kind: "data", type: "int", description: "Zero-based step index." },
+    },
+    props: {},
+};
 export const inputRegistration = {
     kind: "definition-v1",
     moduleId: "cascade.core.Input",
@@ -60,4 +207,32 @@ export const subnetRegistration = {
     definition: subnetDefinition,
     loadExecute: async () => () => { },
 };
+/**
+ * Both of these have an empty `execute`, and that is the design rather than a
+ * stub: the runtime supplies their behaviour because both are *boundaries*, and
+ * a boundary's value comes from its parent's evaluation rather than from its own
+ * inputs. `cascade.core.Subnet` and `cascade.core.Input` already work this way.
+ *
+ * Writing the loop in `Feedback.execute` instead would need the node to reach
+ * the graph, its children and the scheduler — and `NodeExecutionContext` gives
+ * a node its own id and nothing else, deliberately, which is what keeps a
+ * definition-v1 node a pure function of its inputs.
+ */
+export const feedbackRegistration = {
+    kind: "definition-v1",
+    moduleId: "cascade.core.Feedback",
+    definition: feedbackDefinition,
+    loadExecute: async () => () => { },
+};
+export const previousRegistration = {
+    kind: "definition-v1",
+    moduleId: "cascade.core.Previous",
+    definition: previousDefinition,
+    loadExecute: async () => ({ inputs, outputs }) => {
+        // Outside a container this is what runs. Inside, the runtime overwrites
+        // both outputs before any child reads them.
+        outputs.value.set(inputs.initial);
+        outputs.step.set(0);
+    },
+};
 //# sourceMappingURL=structural.js.map

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

@@ -0,0 +1,165 @@
+import type { NodeExecutionContext } from "@field/cascade/contracts";
+/**
+ * `cascade.core.Time` — the clock, as a value the graph can carry.
+ *
+ * Built 2026-09-09, from Marcus scrubbing the timeline on `particle-type` and
+ * seeing nothing move: *"when i jump to a different time on the timeline i dont
+ * actually see the pop simulation animating in the viewer."*
+ *
+ * The cause was not the viewer. `cascade.pop.Simulate` takes the frame on an
+ * **input**, its own comment says *"drive it with `$F`"*, and **that was not
+ * possible**: expressions attach to props, and an input port has no expression
+ * field. So the sketch had a constant in there and no graph in the system could
+ * read the clock through a port at all.
+ *
+ * ## Why a node rather than an expression on the input
+ *
+ * Making inputs expression-bearing is the other fix, and it is the wrong one.
+ * An input is a *wire*, and a wire that is sometimes a formula means every
+ * consumer of every input has two ways to get a value — which is the shape that
+ * made props themselves complicated (a value, an expression, a channel, and a
+ * resolution order between them). Doing it again on the input side doubles that
+ * surface for one use.
+ *
+ * The node is also the more honest picture. Time is an input to the graph in
+ * the same way a camera is, and a graph that shows where the clock enters can
+ * be read; one where any of two hundred ports might secretly be `$F` cannot.
+ *
+ * ## Why the props carry the expressions
+ *
+ * `frame` and `time` are props with declared default expressions — `$F` and
+ * `$T` — which is the one mechanism that already reads the clock and updates a
+ * node's time dependency. Nothing here calls a clock: the node is a pure
+ * function of its props, and the props are where the binding lives. That keeps
+ * `execute` deterministic and testable, which a node reading a global clock
+ * would not be.
+ *
+ * They are props rather than fixed values so you can override one: pinning
+ * `frame` to a constant is exactly what a still render wants, and it is a
+ * one-field edit rather than a rewire.
+ */
+export declare const timeDefinition: {
+    readonly apiVersion: 1;
+    readonly label: "Time";
+    readonly description: "The current frame and time, as values the graph can read.";
+    readonly icon: "Clock";
+    readonly runsOn: "portable";
+    readonly inputs: {};
+    readonly outputs: {
+        /**
+         * The whole frame, as an integer — Houdini's `$F`.
+         *
+         * An `int` rather than a `float`, and that is the point of having two
+         * outputs. Anything that **counts** frames needs an integer: a feedback
+         * container's step count, a sequence index, a modulo. Narrowing is never
+         * implicit in Cascade, so a float frame simply could not be wired to a step
+         * count, and the alternative — truncating silently somewhere downstream —
+         * is a simulation running 3 steps when the graph said 3.7.
+         */
+        readonly frame: {
+            readonly kind: "data";
+            readonly type: "int";
+            readonly description: "The whole frame. Houdini's $F.";
+        };
+        /** The fractional frame — Houdini's `$FF`. For anything that moves. */
+        readonly fframe: {
+            readonly kind: "data";
+            readonly type: "float";
+            readonly description: "The fractional frame, for sub-frame motion. Houdini's $FF.";
+        };
+        readonly time: {
+            readonly kind: "data";
+            readonly type: "float";
+            readonly description: "The playhead in seconds.";
+        };
+    };
+    readonly props: {
+        readonly frame: {
+            readonly type: "int";
+            readonly default: 1;
+            readonly expression: "$F";
+            readonly label: "Frame";
+            readonly description: "Bound to $F. Replace with a number to pin a still, or with any expression.";
+        };
+        readonly fframe: {
+            readonly type: "float";
+            readonly default: 1;
+            readonly expression: "$FF";
+            readonly label: "Fractional Frame";
+            readonly description: "Bound to $FF.";
+        };
+        readonly time: {
+            readonly type: "float";
+            readonly default: 0;
+            readonly expression: "$T";
+            readonly label: "Time";
+            readonly description: "Bound to $T, in seconds.";
+        };
+    };
+};
+export declare function executeTime(context: NodeExecutionContext<typeof timeDefinition>): void;
+export declare const timeRegistration: {
+    kind: "definition-v1";
+    moduleId: string;
+    definition: {
+        readonly apiVersion: 1;
+        readonly label: "Time";
+        readonly description: "The current frame and time, as values the graph can read.";
+        readonly icon: "Clock";
+        readonly runsOn: "portable";
+        readonly inputs: {};
+        readonly outputs: {
+            /**
+             * The whole frame, as an integer — Houdini's `$F`.
+             *
+             * An `int` rather than a `float`, and that is the point of having two
+             * outputs. Anything that **counts** frames needs an integer: a feedback
+             * container's step count, a sequence index, a modulo. Narrowing is never
+             * implicit in Cascade, so a float frame simply could not be wired to a step
+             * count, and the alternative — truncating silently somewhere downstream —
+             * is a simulation running 3 steps when the graph said 3.7.
+             */
+            readonly frame: {
+                readonly kind: "data";
+                readonly type: "int";
+                readonly description: "The whole frame. Houdini's $F.";
+            };
+            /** The fractional frame — Houdini's `$FF`. For anything that moves. */
+            readonly fframe: {
+                readonly kind: "data";
+                readonly type: "float";
+                readonly description: "The fractional frame, for sub-frame motion. Houdini's $FF.";
+            };
+            readonly time: {
+                readonly kind: "data";
+                readonly type: "float";
+                readonly description: "The playhead in seconds.";
+            };
+        };
+        readonly props: {
+            readonly frame: {
+                readonly type: "int";
+                readonly default: 1;
+                readonly expression: "$F";
+                readonly label: "Frame";
+                readonly description: "Bound to $F. Replace with a number to pin a still, or with any expression.";
+            };
+            readonly fframe: {
+                readonly type: "float";
+                readonly default: 1;
+                readonly expression: "$FF";
+                readonly label: "Fractional Frame";
+                readonly description: "Bound to $FF.";
+            };
+            readonly time: {
+                readonly type: "float";
+                readonly default: 0;
+                readonly expression: "$T";
+                readonly label: "Time";
+                readonly description: "Bound to $T, in seconds.";
+            };
+        };
+    };
+    loadExecute: () => Promise<typeof executeTime>;
+};
+//# sourceMappingURL=time.d.ts.map

package/dist/runtime/builtins/core/time.js

@@ -0,0 +1,110 @@
+/**
+ * `cascade.core.Time` — the clock, as a value the graph can carry.
+ *
+ * Built 2026-09-09, from Marcus scrubbing the timeline on `particle-type` and
+ * seeing nothing move: *"when i jump to a different time on the timeline i dont
+ * actually see the pop simulation animating in the viewer."*
+ *
+ * The cause was not the viewer. `cascade.pop.Simulate` takes the frame on an
+ * **input**, its own comment says *"drive it with `$F`"*, and **that was not
+ * possible**: expressions attach to props, and an input port has no expression
+ * field. So the sketch had a constant in there and no graph in the system could
+ * read the clock through a port at all.
+ *
+ * ## Why a node rather than an expression on the input
+ *
+ * Making inputs expression-bearing is the other fix, and it is the wrong one.
+ * An input is a *wire*, and a wire that is sometimes a formula means every
+ * consumer of every input has two ways to get a value — which is the shape that
+ * made props themselves complicated (a value, an expression, a channel, and a
+ * resolution order between them). Doing it again on the input side doubles that
+ * surface for one use.
+ *
+ * The node is also the more honest picture. Time is an input to the graph in
+ * the same way a camera is, and a graph that shows where the clock enters can
+ * be read; one where any of two hundred ports might secretly be `$F` cannot.
+ *
+ * ## Why the props carry the expressions
+ *
+ * `frame` and `time` are props with declared default expressions — `$F` and
+ * `$T` — which is the one mechanism that already reads the clock and updates a
+ * node's time dependency. Nothing here calls a clock: the node is a pure
+ * function of its props, and the props are where the binding lives. That keeps
+ * `execute` deterministic and testable, which a node reading a global clock
+ * would not be.
+ *
+ * They are props rather than fixed values so you can override one: pinning
+ * `frame` to a constant is exactly what a still render wants, and it is a
+ * one-field edit rather than a rewire.
+ */
+export const timeDefinition = {
+    apiVersion: 1,
+    label: "Time",
+    description: "The current frame and time, as values the graph can read.",
+    icon: "Clock",
+    runsOn: "portable",
+    inputs: {},
+    outputs: {
+        /**
+         * The whole frame, as an integer — Houdini's `$F`.
+         *
+         * An `int` rather than a `float`, and that is the point of having two
+         * outputs. Anything that **counts** frames needs an integer: a feedback
+         * container's step count, a sequence index, a modulo. Narrowing is never
+         * implicit in Cascade, so a float frame simply could not be wired to a step
+         * count, and the alternative — truncating silently somewhere downstream —
+         * is a simulation running 3 steps when the graph said 3.7.
+         */
+        frame: {
+            kind: "data",
+            type: "int",
+            description: "The whole frame. Houdini's $F.",
+        },
+        /** The fractional frame — Houdini's `$FF`. For anything that moves. */
+        fframe: {
+            kind: "data",
+            type: "float",
+            description: "The fractional frame, for sub-frame motion. Houdini's $FF.",
+        },
+        time: {
+            kind: "data",
+            type: "float",
+            description: "The playhead in seconds.",
+        },
+    },
+    props: {
+        frame: {
+            type: "int",
+            default: 1,
+            expression: "$F",
+            label: "Frame",
+            description: "Bound to $F. Replace with a number to pin a still, or with any expression.",
+        },
+        fframe: {
+            type: "float",
+            default: 1,
+            expression: "$FF",
+            label: "Fractional Frame",
+            description: "Bound to $FF.",
+        },
+        time: {
+            type: "float",
+            default: 0,
+            expression: "$T",
+            label: "Time",
+            description: "Bound to $T, in seconds.",
+        },
+    },
+};
+export function executeTime(context) {
+    context.outputs.frame.set(context.props.frame);
+    context.outputs.fframe.set(context.props.fframe);
+    context.outputs.time.set(context.props.time);
+}
+export const timeRegistration = {
+    kind: "definition-v1",
+    moduleId: "cascade.core.Time",
+    definition: timeDefinition,
+    loadExecute: async () => executeTime,
+};
+//# sourceMappingURL=time.js.map