@field/cascade 0.3.1 → 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/camera.d.ts

@@ -0,0 +1,252 @@
+import { type NodeExecutionContext } from "@field/cascade/contracts";
+/**
+ * `cascade.core.Camera` — Houdini's `/obj/cam`, as a node.
+ *
+ * Marcus, 2026-09-08: *"I think it just requires a camera. camera should be a
+ * core node."* So a renderer takes a camera on a port rather than carrying its
+ * own copy of the same eight parameters, which is what `volume-render` was
+ * doing.
+ *
+ * The split between inputs and props is the usual one and it matters here:
+ * **what a camera move animates is an input** — position, orientation, the
+ * look-at target, the lens — and **what defines the frame is a prop**, because
+ * clipping planes, resolution and projection are set once and left. `focal` is
+ * an input for exactly this reason: a focus pull is a camera move.
+ */
+export declare const cameraDefinition: {
+    readonly apiVersion: 1;
+    readonly label: "Camera";
+    readonly description: "A camera, following Houdini's /obj/cam.";
+    readonly icon: "Video";
+    readonly runsOn: "portable";
+    readonly inputs: {
+        readonly translate: {
+            readonly kind: "data";
+            readonly type: "vec3";
+            readonly default: readonly [0, 0, 5];
+            readonly description: "World position.";
+        };
+        readonly rotate: {
+            readonly kind: "data";
+            readonly type: "vec3";
+            readonly default: readonly [0, 0, 0];
+            readonly description: "Degrees, XYZ order. The camera looks down its own -Z.";
+        };
+        readonly focal: {
+            readonly kind: "data";
+            readonly type: "float";
+            readonly default: 50;
+            readonly min: 1;
+            readonly max: 300;
+            readonly description: "Focal length in millimetres.";
+        };
+        readonly lookat: {
+            readonly kind: "data";
+            readonly type: "vec3";
+            readonly default: readonly [0, 0, 0];
+            readonly description: "Point to aim at. Used only when Look At is on, and it replaces Rotate.";
+        };
+        readonly up: {
+            readonly kind: "data";
+            readonly type: "vec3";
+            readonly default: readonly [0, 1, 0];
+            readonly description: "Up vector for Look At.";
+        };
+        readonly spin: {
+            readonly kind: "data";
+            readonly type: "float";
+            readonly default: 0;
+            readonly description: "Degrees added to the Y rotation, after Look At. For turntables.";
+        };
+    };
+    readonly outputs: {
+        readonly camera: {
+            readonly kind: "data";
+            readonly type: "camera";
+        };
+    };
+    readonly props: {
+        readonly lookAt: {
+            readonly type: "bool";
+            readonly default: false;
+            readonly label: "Look At";
+            readonly description: "Aim at the Look At point instead of using Rotate.";
+        };
+        readonly aperture: {
+            readonly type: "float";
+            readonly default: 41.4214;
+            readonly min: 1;
+            readonly max: 200;
+            readonly label: "Aperture";
+            readonly description: "Horizontal aperture in millimetres. With the default focal length this is a 45 degree view.";
+        };
+        readonly resolution: {
+            readonly type: "vec2i";
+            readonly default: readonly [1280, 720];
+            readonly label: "Resolution";
+            readonly description: "Frame size in pixels. The vertical field of view is derived from this.";
+        };
+        readonly aspect: {
+            readonly type: "float";
+            readonly default: 1;
+            readonly min: 0.1;
+            readonly max: 10;
+            readonly label: "Pixel Aspect";
+            readonly description: "The aspect of one pixel, not of the frame.";
+        };
+        readonly projection: {
+            readonly type: "string";
+            readonly default: "perspective";
+            readonly label: "Projection";
+            readonly control: "select";
+            readonly options: readonly [{
+                readonly value: "perspective";
+                readonly label: "Perspective";
+            }, {
+                readonly value: "orthographic";
+                readonly label: "Orthographic";
+            }];
+        };
+        readonly orthowidth: {
+            readonly type: "float";
+            readonly default: 2;
+            readonly min: 0.01;
+            readonly label: "Ortho Width";
+            readonly description: "Width of the orthographic frame in world units.";
+        };
+        readonly near: {
+            readonly type: "float";
+            readonly default: 0.001;
+            readonly min: 0;
+            readonly label: "Near Clip";
+        };
+        readonly far: {
+            readonly type: "float";
+            readonly default: 10000;
+            readonly min: 0;
+            readonly label: "Far Clip";
+        };
+    };
+};
+export declare function executeCamera(context: NodeExecutionContext<typeof cameraDefinition>): void;
+export declare const cameraRegistration: {
+    kind: "definition-v1";
+    moduleId: string;
+    definition: {
+        readonly apiVersion: 1;
+        readonly label: "Camera";
+        readonly description: "A camera, following Houdini's /obj/cam.";
+        readonly icon: "Video";
+        readonly runsOn: "portable";
+        readonly inputs: {
+            readonly translate: {
+                readonly kind: "data";
+                readonly type: "vec3";
+                readonly default: readonly [0, 0, 5];
+                readonly description: "World position.";
+            };
+            readonly rotate: {
+                readonly kind: "data";
+                readonly type: "vec3";
+                readonly default: readonly [0, 0, 0];
+                readonly description: "Degrees, XYZ order. The camera looks down its own -Z.";
+            };
+            readonly focal: {
+                readonly kind: "data";
+                readonly type: "float";
+                readonly default: 50;
+                readonly min: 1;
+                readonly max: 300;
+                readonly description: "Focal length in millimetres.";
+            };
+            readonly lookat: {
+                readonly kind: "data";
+                readonly type: "vec3";
+                readonly default: readonly [0, 0, 0];
+                readonly description: "Point to aim at. Used only when Look At is on, and it replaces Rotate.";
+            };
+            readonly up: {
+                readonly kind: "data";
+                readonly type: "vec3";
+                readonly default: readonly [0, 1, 0];
+                readonly description: "Up vector for Look At.";
+            };
+            readonly spin: {
+                readonly kind: "data";
+                readonly type: "float";
+                readonly default: 0;
+                readonly description: "Degrees added to the Y rotation, after Look At. For turntables.";
+            };
+        };
+        readonly outputs: {
+            readonly camera: {
+                readonly kind: "data";
+                readonly type: "camera";
+            };
+        };
+        readonly props: {
+            readonly lookAt: {
+                readonly type: "bool";
+                readonly default: false;
+                readonly label: "Look At";
+                readonly description: "Aim at the Look At point instead of using Rotate.";
+            };
+            readonly aperture: {
+                readonly type: "float";
+                readonly default: 41.4214;
+                readonly min: 1;
+                readonly max: 200;
+                readonly label: "Aperture";
+                readonly description: "Horizontal aperture in millimetres. With the default focal length this is a 45 degree view.";
+            };
+            readonly resolution: {
+                readonly type: "vec2i";
+                readonly default: readonly [1280, 720];
+                readonly label: "Resolution";
+                readonly description: "Frame size in pixels. The vertical field of view is derived from this.";
+            };
+            readonly aspect: {
+                readonly type: "float";
+                readonly default: 1;
+                readonly min: 0.1;
+                readonly max: 10;
+                readonly label: "Pixel Aspect";
+                readonly description: "The aspect of one pixel, not of the frame.";
+            };
+            readonly projection: {
+                readonly type: "string";
+                readonly default: "perspective";
+                readonly label: "Projection";
+                readonly control: "select";
+                readonly options: readonly [{
+                    readonly value: "perspective";
+                    readonly label: "Perspective";
+                }, {
+                    readonly value: "orthographic";
+                    readonly label: "Orthographic";
+                }];
+            };
+            readonly orthowidth: {
+                readonly type: "float";
+                readonly default: 2;
+                readonly min: 0.01;
+                readonly label: "Ortho Width";
+                readonly description: "Width of the orthographic frame in world units.";
+            };
+            readonly near: {
+                readonly type: "float";
+                readonly default: 0.001;
+                readonly min: 0;
+                readonly label: "Near Clip";
+            };
+            readonly far: {
+                readonly type: "float";
+                readonly default: 10000;
+                readonly min: 0;
+                readonly label: "Far Clip";
+            };
+        };
+    };
+    loadExecute: () => Promise<typeof executeCamera>;
+};
+//# sourceMappingURL=camera.d.ts.map

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

@@ -0,0 +1,149 @@
+import { CAMERA_DEFAULTS } from "@field/cascade/contracts";
+import { lookAtRotation } from "../../camera/index.js";
+/**
+ * `cascade.core.Camera` — Houdini's `/obj/cam`, as a node.
+ *
+ * Marcus, 2026-09-08: *"I think it just requires a camera. camera should be a
+ * core node."* So a renderer takes a camera on a port rather than carrying its
+ * own copy of the same eight parameters, which is what `volume-render` was
+ * doing.
+ *
+ * The split between inputs and props is the usual one and it matters here:
+ * **what a camera move animates is an input** — position, orientation, the
+ * look-at target, the lens — and **what defines the frame is a prop**, because
+ * clipping planes, resolution and projection are set once and left. `focal` is
+ * an input for exactly this reason: a focus pull is a camera move.
+ */
+export const cameraDefinition = {
+    apiVersion: 1,
+    label: "Camera",
+    description: "A camera, following Houdini's /obj/cam.",
+    icon: "Video",
+    runsOn: "portable",
+    inputs: {
+        translate: {
+            kind: "data",
+            type: "vec3",
+            default: [0, 0, 5],
+            description: "World position.",
+        },
+        rotate: {
+            kind: "data",
+            type: "vec3",
+            default: [0, 0, 0],
+            description: "Degrees, XYZ order. The camera looks down its own -Z.",
+        },
+        focal: {
+            kind: "data",
+            type: "float",
+            default: 50,
+            min: 1,
+            max: 300,
+            description: "Focal length in millimetres.",
+        },
+        lookat: {
+            kind: "data",
+            type: "vec3",
+            default: [0, 0, 0],
+            description: "Point to aim at. Used only when Look At is on, and it replaces Rotate.",
+        },
+        up: {
+            kind: "data",
+            type: "vec3",
+            default: [0, 1, 0],
+            description: "Up vector for Look At.",
+        },
+        spin: {
+            kind: "data",
+            type: "float",
+            default: 0,
+            description: "Degrees added to the Y rotation, after Look At. For turntables.",
+        },
+    },
+    outputs: {
+        camera: { kind: "data", type: "camera" },
+    },
+    props: {
+        lookAt: {
+            type: "bool",
+            default: false,
+            label: "Look At",
+            description: "Aim at the Look At point instead of using Rotate.",
+        },
+        aperture: {
+            type: "float",
+            default: 41.4214,
+            min: 1,
+            max: 200,
+            label: "Aperture",
+            description: "Horizontal aperture in millimetres. With the default focal length this is a 45 degree view.",
+        },
+        resolution: {
+            type: "vec2i",
+            default: [1280, 720],
+            label: "Resolution",
+            description: "Frame size in pixels. The vertical field of view is derived from this.",
+        },
+        aspect: {
+            type: "float",
+            default: 1,
+            min: 0.1,
+            max: 10,
+            label: "Pixel Aspect",
+            description: "The aspect of one pixel, not of the frame.",
+        },
+        projection: {
+            type: "string",
+            default: "perspective",
+            label: "Projection",
+            control: "select",
+            options: [
+                { value: "perspective", label: "Perspective" },
+                { value: "orthographic", label: "Orthographic" },
+            ],
+        },
+        orthowidth: {
+            type: "float",
+            default: 2,
+            min: 0.01,
+            label: "Ortho Width",
+            description: "Width of the orthographic frame in world units.",
+        },
+        near: { type: "float", default: 0.001, min: 0, label: "Near Clip" },
+        far: { type: "float", default: 10000, min: 0, label: "Far Clip" },
+    },
+};
+export function executeCamera(context) {
+    const { translate, rotate, focal, lookat, up, spin } = context.inputs;
+    const props = context.props;
+    const aimed = props.lookAt
+        ? lookAtRotation(translate, lookat, up)
+        : rotate;
+    // Spin is applied after look-at rather than folded into it, so a turntable
+    // keeps pointing at its subject while it goes round. Degrees, because
+    // `rotate` is degrees and adding a different unit to it would be a trap.
+    const oriented = spin === 0
+        ? aimed
+        : [aimed[0], aimed[1] + spin, aimed[2]];
+    const camera = {
+        ...CAMERA_DEFAULTS,
+        translate: translate,
+        rotate: oriented,
+        focal,
+        aperture: props.aperture,
+        resolution: props.resolution,
+        aspect: props.aspect,
+        projection: props.projection === "orthographic" ? "orthographic" : "perspective",
+        orthowidth: props.orthowidth,
+        near: props.near,
+        far: props.far,
+    };
+    context.outputs.camera.set(camera);
+}
+export const cameraRegistration = {
+    kind: "definition-v1",
+    moduleId: "cascade.core.Camera",
+    definition: cameraDefinition,
+    loadExecute: async () => executeCamera,
+};
+//# sourceMappingURL=camera.js.map

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

@@ -1,9 +1,11 @@
 import type { DefinitionNodeRegistration } from "../../types.js";
+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 { 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

@@ -1,8 +1,10 @@
+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 { 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,
@@ -13,6 +15,10 @@ export const coreNodeRegistrations = Object.freeze([
     selectRegistration,
     randomRegistration,
     remapRegistration,
+    cameraRegistration,
+    timeRegistration,
+    feedbackRegistration,
+    previousRegistration,
 ]);
 const registrationsById = new Map(coreNodeRegistrations.map((registration) => [registration.moduleId, registration]));
 export function coreNodeRegistration(moduleId) {