@field/cascade 0.4.0 → 0.5.1

package/dist/player/embed.d.ts

@@ -0,0 +1,4 @@
+import type { MountPlayerOptions, PlayerController } from './types.js';
+export type { MountPlayerOptions, PlayerController, PlayerEvent, PlayerListener, PlayerOutputSelection, } from './types.js';
+/** Mount a built player in a realm-isolated same-origin iframe. */
+export declare function mountPlayer(container: HTMLElement, options: MountPlayerOptions): Promise<PlayerController>;

package/dist/player/embed.js

@@ -0,0 +1,77 @@
+// src/player/embed.ts
+async function mountPlayer(container, options) {
+  const hostDocument = container.ownerDocument;
+  const hostWindow = hostDocument.defaultView;
+  if (!hostWindow) throw new Error("Cascade player mount requires a browser window");
+  const url = new URL(String(options.url), hostDocument.baseURI);
+  if (url.origin !== hostWindow.location.origin) {
+    throw new Error(
+      "Programmatic Cascade player mounts must be same-origin; use ordinary iframe markup for cross-origin embeds"
+    );
+  }
+  setQueryOption(url, "frame", options.frame ?? 1);
+  setQueryOption(url, "fps", options.fps ?? 30);
+  url.searchParams.set("autoplay", options.autoplay ? "1" : "0");
+  if (options.output) {
+    url.searchParams.set("outputNode", options.output.nodeId);
+    url.searchParams.set("outputPort", options.output.port);
+  } else {
+    url.searchParams.delete("outputNode");
+    url.searchParams.delete("outputPort");
+  }
+  const iframe = hostDocument.createElement("iframe");
+  iframe.src = url.href;
+  iframe.title = "Cascade player";
+  iframe.loading = "eager";
+  Object.assign(iframe.style, { display: "block", width: "100%", height: "100%", border: "0" });
+  iframe.setAttribute("allow", "fullscreen");
+  container.append(iframe);
+  try {
+    await iframeLoaded(iframe);
+    const child = iframe.contentWindow;
+    const ready = child?.cascadePlayerReady;
+    if (!ready) throw new Error("Cascade player did not expose cascadePlayerReady");
+    const controller = await ready;
+    let disposed = false;
+    return {
+      play: () => controller.play(),
+      pause: () => controller.pause(),
+      seek: (frame) => controller.seek(frame),
+      setInput: (nodeId, name, value) => controller.setInput(nodeId, name, value),
+      setProp: (nodeId, name, value) => controller.setProp(nodeId, name, value),
+      getOutput: (nodeId, port) => controller.getOutput(nodeId, port),
+      selectOutput: (nodeId, port) => controller.selectOutput(nodeId, port),
+      downloadOutput: () => controller.downloadOutput(),
+      resize: (width, height) => controller.resize(width, height),
+      subscribe: (listener) => controller.subscribe(listener),
+      async dispose() {
+        if (disposed) return;
+        disposed = true;
+        try {
+          await controller.dispose();
+        } finally {
+          iframe.remove();
+        }
+      }
+    };
+  } catch (error) {
+    iframe.remove();
+    throw error;
+  }
+}
+function setQueryOption(url, name, value) {
+  if (value === void 0) return;
+  if (!Number.isFinite(value)) throw new TypeError(`${name} must be finite`);
+  url.searchParams.set(name, String(value));
+}
+function iframeLoaded(iframe) {
+  return new Promise((resolve, reject) => {
+    iframe.addEventListener("load", () => resolve(), { once: true });
+    iframe.addEventListener("error", () => reject(new Error(`Could not load Cascade player ${iframe.src}`)), {
+      once: true
+    });
+  });
+}
+export {
+  mountPlayer
+};

package/dist/player/types.d.ts

@@ -0,0 +1,35 @@
+export interface PlayerOutputSelection {
+    readonly nodeId: string;
+    readonly port: string;
+}
+export type PlayerEvent = {
+    readonly type: 'frame';
+    readonly frame: number;
+} | {
+    readonly type: 'playing';
+    readonly playing: boolean;
+} | {
+    readonly type: 'error';
+    readonly error: Error;
+};
+export type PlayerListener = (event: PlayerEvent) => void;
+export interface PlayerController {
+    play(): void;
+    pause(): void;
+    seek(frame: number): Promise<void>;
+    setInput(nodeId: string, name: string, value: unknown): Promise<void>;
+    setProp(nodeId: string, name: string, value: unknown): Promise<void>;
+    getOutput(nodeId: string, port: string): unknown;
+    selectOutput(nodeId: string, port: string): Promise<void>;
+    downloadOutput(): Promise<Blob>;
+    resize(width: number, height: number): void;
+    subscribe(listener: PlayerListener): () => void;
+    dispose(): Promise<void>;
+}
+export interface MountPlayerOptions {
+    readonly url: string | URL;
+    readonly frame?: number;
+    readonly fps?: number;
+    readonly autoplay?: boolean;
+    readonly output?: PlayerOutputSelection;
+}

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

@@ -3,8 +3,9 @@ import { cameraRegistration } from "./camera.js";
 import { randomRegistration } from "./random.js";
 import { remapRegistration } from "./remap.js";
 import { mergeRegistration, nullRegistration, selectRegistration, switchRegistration } from "./routing.js";
-import { inputRegistration, outputRegistration, subnetRegistration } from "./structural.js";
-export { cameraRegistration, inputRegistration, mergeRegistration, nullRegistration, outputRegistration, randomRegistration, remapRegistration, selectRegistration, subnetRegistration, switchRegistration, };
+import { feedbackRegistration, inputRegistration, outputRegistration, previousRegistration, subnetRegistration } from "./structural.js";
+import { timeRegistration } from "./time.js";
+export { cameraRegistration, feedbackRegistration, previousRegistration, inputRegistration, mergeRegistration, nullRegistration, outputRegistration, randomRegistration, remapRegistration, selectRegistration, subnetRegistration, switchRegistration, timeRegistration, };
 export declare const coreNodeRegistrations: readonly DefinitionNodeRegistration[];
 export declare function coreNodeRegistration(moduleId: string): DefinitionNodeRegistration | undefined;
 //# sourceMappingURL=index.d.ts.map

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

@@ -2,8 +2,9 @@ import { cameraRegistration } from "./camera.js";
 import { randomRegistration } from "./random.js";
 import { remapRegistration } from "./remap.js";
 import { mergeRegistration, nullRegistration, selectRegistration, switchRegistration } from "./routing.js";
-import { inputRegistration, outputRegistration, subnetRegistration } from "./structural.js";
-export { cameraRegistration, inputRegistration, mergeRegistration, nullRegistration, outputRegistration, randomRegistration, remapRegistration, selectRegistration, subnetRegistration, switchRegistration, };
+import { feedbackRegistration, inputRegistration, outputRegistration, previousRegistration, subnetRegistration, } from "./structural.js";
+import { timeRegistration } from "./time.js";
+export { cameraRegistration, feedbackRegistration, previousRegistration, inputRegistration, mergeRegistration, nullRegistration, outputRegistration, randomRegistration, remapRegistration, selectRegistration, subnetRegistration, switchRegistration, timeRegistration, };
 export const coreNodeRegistrations = Object.freeze([
     subnetRegistration,
     inputRegistration,
@@ -15,6 +16,9 @@ export const coreNodeRegistrations = Object.freeze([
     randomRegistration,
     remapRegistration,
     cameraRegistration,
+    timeRegistration,
+    feedbackRegistration,
+    previousRegistration,
 ]);
 const registrationsById = new Map(coreNodeRegistrations.map((registration) => [registration.moduleId, registration]));
 export function coreNodeRegistration(moduleId) {

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