@field/cascade 0.3.1 → 0.5.1

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

@@ -0,0 +1,2 @@
+export * from "./definitions.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,2 @@
+export * from "./definitions.js";
+//# sourceMappingURL=index.js.map

package/dist/runtime/builtins/scene/definitions.d.ts

@@ -0,0 +1,356 @@
+import { type NodeExecutionContext, type Scene } from "@field/cascade/contracts";
+import type { DefinitionNodeRegistration } from "../../types.js";
+/**
+ * The one place the scene built-in namespace is written down.
+ *
+ * `cascade.scene.*` rather than `cascade.geo.*`, and that is a real distinction
+ * rather than tidiness: `cascade.geo` is a *medium* — points, primitives,
+ * attributes, operations that take geometry and return geometry. A scene is not
+ * geometry. It is an assembly of geometry with a viewpoint and lights, and it is
+ * the thing you look at rather than the thing you make.
+ *
+ * The counter-argument, and it is the one this codebase has already accepted
+ * once: a namespace with two nodes in it is a promise rather than a structure.
+ * `PLAN viewport` says exactly that about `cascade.render.*`, and prefers
+ * `cascade.geo.Render` for the render node on those grounds. The difference is
+ * that this namespace has a **type** behind it — `scene`, in the core type list
+ * — and a type is the thing a namespace is allowed to be named after.
+ */
+export declare const SCENE_NAMESPACE = "cascade.scene";
+export declare function sceneModuleId(name: string): string;
+/**
+ * `cascade.scene.Scene` — geometry, a camera and lights, assembled.
+ *
+ * Marcus's design, 2026-09-09: *"a 'scene' root node with a variadic input …
+ * a 'scene' node with a camera, lights and geometry attached becomes a '3d
+ * scene'."*
+ *
+ * ## Why one variadic `any` input rather than three typed ones
+ *
+ * Three inputs — a variadic `geometry`, a single `camera`, a variadic `light` —
+ * would be better typed, and the connection rules would then refuse a wrong
+ * wire before the node ever ran. That is a real loss and it is taken
+ * deliberately, because the gesture Marcus described is *attach things to it*,
+ * and a single port is the difference between dropping a camera on the node and
+ * hunting for which of three stacked ports accepts it. Houdini's own `/obj`
+ * network works the same way: everything in it is in the scene by being there,
+ * not by being wired to the right socket.
+ *
+ * What that costs is paid back at execute time rather than ignored. Every input
+ * is classified, and **anything unclassifiable throws** naming the port and the
+ * value's shape — the alternative is a scene that silently omits what you
+ * attached, which is the failure mode this codebase keeps writing rules about.
+ * Two cameras throw for the same reason: picking one is a guess, and a guess
+ * about which way the camera is pointing is not recoverable by looking at the
+ * result.
+ *
+ * A nested scene is flattened. That makes `Scene` associative — assembling two
+ * sub-scenes gives the same result as assembling their contents — and it is
+ * what lets a big graph build a scene in parts.
+ */
+export declare const sceneDefinition: {
+    readonly apiVersion: 1;
+    readonly label: "Scene";
+    readonly description: "Geometry, a camera and lights, assembled into a scene. Attach anything to the input.";
+    readonly icon: "Box";
+    readonly runsOn: "portable";
+    readonly inputs: {
+        readonly inputs: {
+            readonly kind: "data";
+            readonly type: "any";
+            readonly variadic: true;
+            readonly description: "Geometry, one camera, and lights, in any order. Scenes are flattened.";
+        };
+    };
+    readonly outputs: {
+        readonly scene: {
+            readonly kind: "data";
+            readonly type: "scene";
+        };
+    };
+    readonly props: {};
+};
+export declare function executeScene(context: NodeExecutionContext<typeof sceneDefinition>): void;
+/**
+ * `cascade.scene.Light` — Houdini's `/obj/hlight`, as a node.
+ *
+ * **Nothing shades with these yet**, and that is stated in the description so
+ * that a light which appears to do nothing is understood rather than reported
+ * as broken. Every piece in the vault today is lines — `cloud-volumes` is a
+ * volume, `particle-type` is trails, `cloud-plots` is marks — so there is no
+ * surface to light, and inventing a shading model before something needs one is
+ * how you get a shading model nobody wants.
+ *
+ * It exists now because `Scene` accepts lights now. A type that gains a field
+ * later invalidates every serialized scene and every node that builds one; the
+ * node is the cheap half of a decision already taken in the type.
+ */
+export declare const lightDefinition: {
+    readonly apiVersion: 1;
+    readonly label: "Light";
+    readonly description: "A light, following Houdini's /obj/hlight. Nothing shades with lights yet — the viewport draws wireframe and points.";
+    readonly icon: "Lightbulb";
+    readonly runsOn: "portable";
+    readonly inputs: {
+        readonly translate: {
+            readonly kind: "data";
+            readonly type: "vec3";
+            readonly default: readonly [0, 0, 5];
+            readonly description: "World position. Ignored for a distant or ambient light.";
+        };
+        readonly direction: {
+            readonly kind: "data";
+            readonly type: "vec3";
+            readonly default: readonly [0, 0, -1];
+            readonly description: "Direction the light points. Used by distant and spot.";
+        };
+        readonly color: {
+            readonly kind: "data";
+            readonly type: "color";
+            readonly default: readonly [1, 1, 1, 1];
+            readonly description: "Houdini light_color.";
+        };
+        readonly intensity: {
+            readonly kind: "data";
+            readonly type: "float";
+            readonly default: 1;
+            readonly min: 0;
+            readonly description: "Houdini light_intensity.";
+        };
+    };
+    readonly outputs: {
+        readonly light: {
+            readonly kind: "data";
+            readonly type: "light";
+        };
+    };
+    readonly props: {
+        readonly type: {
+            readonly type: "string";
+            readonly default: "point";
+            readonly label: "Light Type";
+            readonly control: "select";
+            readonly options: readonly [{
+                readonly value: "point";
+                readonly label: "Point";
+            }, {
+                readonly value: "distant";
+                readonly label: "Distant - directional";
+            }, {
+                readonly value: "ambient";
+                readonly label: "Ambient";
+            }, {
+                readonly value: "spot";
+                readonly label: "Spot";
+            }];
+            readonly description: "Houdini light_type. Distant is what other renderers call directional.";
+        };
+        readonly coneangle: {
+            readonly type: "float";
+            readonly default: 45;
+            readonly min: 0;
+            readonly max: 180;
+            readonly label: "Cone Angle";
+            readonly description: "Degrees. Spot only.";
+        };
+    };
+};
+export declare function executeLight(context: NodeExecutionContext<typeof lightDefinition>): void;
+export declare const sceneRegistration: {
+    kind: "definition-v1";
+    moduleId: string;
+    definition: {
+        readonly apiVersion: 1;
+        readonly label: "Scene";
+        readonly description: "Geometry, a camera and lights, assembled into a scene. Attach anything to the input.";
+        readonly icon: "Box";
+        readonly runsOn: "portable";
+        readonly inputs: {
+            readonly inputs: {
+                readonly kind: "data";
+                readonly type: "any";
+                readonly variadic: true;
+                readonly description: "Geometry, one camera, and lights, in any order. Scenes are flattened.";
+            };
+        };
+        readonly outputs: {
+            readonly scene: {
+                readonly kind: "data";
+                readonly type: "scene";
+            };
+        };
+        readonly props: {};
+    };
+    loadExecute: () => Promise<typeof executeScene>;
+};
+export declare const lightRegistration: {
+    kind: "definition-v1";
+    moduleId: string;
+    definition: {
+        readonly apiVersion: 1;
+        readonly label: "Light";
+        readonly description: "A light, following Houdini's /obj/hlight. Nothing shades with lights yet — the viewport draws wireframe and points.";
+        readonly icon: "Lightbulb";
+        readonly runsOn: "portable";
+        readonly inputs: {
+            readonly translate: {
+                readonly kind: "data";
+                readonly type: "vec3";
+                readonly default: readonly [0, 0, 5];
+                readonly description: "World position. Ignored for a distant or ambient light.";
+            };
+            readonly direction: {
+                readonly kind: "data";
+                readonly type: "vec3";
+                readonly default: readonly [0, 0, -1];
+                readonly description: "Direction the light points. Used by distant and spot.";
+            };
+            readonly color: {
+                readonly kind: "data";
+                readonly type: "color";
+                readonly default: readonly [1, 1, 1, 1];
+                readonly description: "Houdini light_color.";
+            };
+            readonly intensity: {
+                readonly kind: "data";
+                readonly type: "float";
+                readonly default: 1;
+                readonly min: 0;
+                readonly description: "Houdini light_intensity.";
+            };
+        };
+        readonly outputs: {
+            readonly light: {
+                readonly kind: "data";
+                readonly type: "light";
+            };
+        };
+        readonly props: {
+            readonly type: {
+                readonly type: "string";
+                readonly default: "point";
+                readonly label: "Light Type";
+                readonly control: "select";
+                readonly options: readonly [{
+                    readonly value: "point";
+                    readonly label: "Point";
+                }, {
+                    readonly value: "distant";
+                    readonly label: "Distant - directional";
+                }, {
+                    readonly value: "ambient";
+                    readonly label: "Ambient";
+                }, {
+                    readonly value: "spot";
+                    readonly label: "Spot";
+                }];
+                readonly description: "Houdini light_type. Distant is what other renderers call directional.";
+            };
+            readonly coneangle: {
+                readonly type: "float";
+                readonly default: 45;
+                readonly min: 0;
+                readonly max: 180;
+                readonly label: "Cone Angle";
+                readonly description: "Degrees. Spot only.";
+            };
+        };
+    };
+    loadExecute: () => Promise<typeof executeLight>;
+};
+export declare const sceneNodeRegistrations: readonly DefinitionNodeRegistration[];
+/** `[moduleId, definition]` pairs, for a host building a node palette. The same
+ *  shape `geoNodeDefinitions` and `popNodeDefinitions` have. */
+export declare const sceneNodeDefinitions: readonly [readonly [string, {
+    readonly apiVersion: 1;
+    readonly label: "Scene";
+    readonly description: "Geometry, a camera and lights, assembled into a scene. Attach anything to the input.";
+    readonly icon: "Box";
+    readonly runsOn: "portable";
+    readonly inputs: {
+        readonly inputs: {
+            readonly kind: "data";
+            readonly type: "any";
+            readonly variadic: true;
+            readonly description: "Geometry, one camera, and lights, in any order. Scenes are flattened.";
+        };
+    };
+    readonly outputs: {
+        readonly scene: {
+            readonly kind: "data";
+            readonly type: "scene";
+        };
+    };
+    readonly props: {};
+}], readonly [string, {
+    readonly apiVersion: 1;
+    readonly label: "Light";
+    readonly description: "A light, following Houdini's /obj/hlight. Nothing shades with lights yet — the viewport draws wireframe and points.";
+    readonly icon: "Lightbulb";
+    readonly runsOn: "portable";
+    readonly inputs: {
+        readonly translate: {
+            readonly kind: "data";
+            readonly type: "vec3";
+            readonly default: readonly [0, 0, 5];
+            readonly description: "World position. Ignored for a distant or ambient light.";
+        };
+        readonly direction: {
+            readonly kind: "data";
+            readonly type: "vec3";
+            readonly default: readonly [0, 0, -1];
+            readonly description: "Direction the light points. Used by distant and spot.";
+        };
+        readonly color: {
+            readonly kind: "data";
+            readonly type: "color";
+            readonly default: readonly [1, 1, 1, 1];
+            readonly description: "Houdini light_color.";
+        };
+        readonly intensity: {
+            readonly kind: "data";
+            readonly type: "float";
+            readonly default: 1;
+            readonly min: 0;
+            readonly description: "Houdini light_intensity.";
+        };
+    };
+    readonly outputs: {
+        readonly light: {
+            readonly kind: "data";
+            readonly type: "light";
+        };
+    };
+    readonly props: {
+        readonly type: {
+            readonly type: "string";
+            readonly default: "point";
+            readonly label: "Light Type";
+            readonly control: "select";
+            readonly options: readonly [{
+                readonly value: "point";
+                readonly label: "Point";
+            }, {
+                readonly value: "distant";
+                readonly label: "Distant - directional";
+            }, {
+                readonly value: "ambient";
+                readonly label: "Ambient";
+            }, {
+                readonly value: "spot";
+                readonly label: "Spot";
+            }];
+            readonly description: "Houdini light_type. Distant is what other renderers call directional.";
+        };
+        readonly coneangle: {
+            readonly type: "float";
+            readonly default: 45;
+            readonly min: 0;
+            readonly max: 180;
+            readonly label: "Cone Angle";
+            readonly description: "Degrees. Spot only.";
+        };
+    };
+}]];
+export type { Scene };
+//# sourceMappingURL=definitions.d.ts.map

package/dist/runtime/builtins/scene/definitions.js

@@ -0,0 +1,224 @@
+import { LIGHT_DEFAULTS, isCamera, isLight, isScene, } from "@field/cascade/contracts";
+/**
+ * The one place the scene built-in namespace is written down.
+ *
+ * `cascade.scene.*` rather than `cascade.geo.*`, and that is a real distinction
+ * rather than tidiness: `cascade.geo` is a *medium* — points, primitives,
+ * attributes, operations that take geometry and return geometry. A scene is not
+ * geometry. It is an assembly of geometry with a viewpoint and lights, and it is
+ * the thing you look at rather than the thing you make.
+ *
+ * The counter-argument, and it is the one this codebase has already accepted
+ * once: a namespace with two nodes in it is a promise rather than a structure.
+ * `PLAN viewport` says exactly that about `cascade.render.*`, and prefers
+ * `cascade.geo.Render` for the render node on those grounds. The difference is
+ * that this namespace has a **type** behind it — `scene`, in the core type list
+ * — and a type is the thing a namespace is allowed to be named after.
+ */
+export const SCENE_NAMESPACE = "cascade.scene";
+export function sceneModuleId(name) {
+    return `${SCENE_NAMESPACE}.${name}`;
+}
+/**
+ * `cascade.scene.Scene` — geometry, a camera and lights, assembled.
+ *
+ * Marcus's design, 2026-09-09: *"a 'scene' root node with a variadic input …
+ * a 'scene' node with a camera, lights and geometry attached becomes a '3d
+ * scene'."*
+ *
+ * ## Why one variadic `any` input rather than three typed ones
+ *
+ * Three inputs — a variadic `geometry`, a single `camera`, a variadic `light` —
+ * would be better typed, and the connection rules would then refuse a wrong
+ * wire before the node ever ran. That is a real loss and it is taken
+ * deliberately, because the gesture Marcus described is *attach things to it*,
+ * and a single port is the difference between dropping a camera on the node and
+ * hunting for which of three stacked ports accepts it. Houdini's own `/obj`
+ * network works the same way: everything in it is in the scene by being there,
+ * not by being wired to the right socket.
+ *
+ * What that costs is paid back at execute time rather than ignored. Every input
+ * is classified, and **anything unclassifiable throws** naming the port and the
+ * value's shape — the alternative is a scene that silently omits what you
+ * attached, which is the failure mode this codebase keeps writing rules about.
+ * Two cameras throw for the same reason: picking one is a guess, and a guess
+ * about which way the camera is pointing is not recoverable by looking at the
+ * result.
+ *
+ * A nested scene is flattened. That makes `Scene` associative — assembling two
+ * sub-scenes gives the same result as assembling their contents — and it is
+ * what lets a big graph build a scene in parts.
+ */
+export const sceneDefinition = {
+    apiVersion: 1,
+    label: "Scene",
+    description: "Geometry, a camera and lights, assembled into a scene. Attach anything to the input.",
+    icon: "Box",
+    runsOn: "portable",
+    inputs: {
+        inputs: {
+            kind: "data",
+            type: "any",
+            variadic: true,
+            description: "Geometry, one camera, and lights, in any order. Scenes are flattened.",
+        },
+    },
+    outputs: {
+        scene: { kind: "data", type: "scene" },
+    },
+    props: {},
+};
+export function executeScene(context) {
+    const geometry = [];
+    const lights = [];
+    let camera = null;
+    let cameraFrom = -1;
+    context.inputs.inputs.forEach((value, index) => {
+        if (value === undefined || value === null)
+            return;
+        if (isScene(value)) {
+            geometry.push(...value.geometry);
+            lights.push(...value.lights);
+            if (value.camera !== null) {
+                if (camera !== null)
+                    throw new Error(`cascade.scene.Scene has two cameras, on inputs ${cameraFrom} and ${index}. A scene has one viewpoint; remove one or use a Switch to choose between them.`);
+                camera = value.camera;
+                cameraFrom = index;
+            }
+            return;
+        }
+        if (isCamera(value)) {
+            if (camera !== null)
+                throw new Error(`cascade.scene.Scene has two cameras, on inputs ${cameraFrom} and ${index}. A scene has one viewpoint; remove one or use a Switch to choose between them.`);
+            camera = value;
+            cameraFrom = index;
+            return;
+        }
+        if (isLight(value)) {
+            lights.push(value);
+            return;
+        }
+        if (typeof value === "object" && value.kind === "geometry") {
+            geometry.push(value);
+            return;
+        }
+        throw new Error(`cascade.scene.Scene input ${index} is not geometry, a camera, a light or a scene (received ${describe(value)}). A scene can only hold those.`);
+    });
+    context.outputs.scene.set({ geometry, camera, lights });
+}
+function describe(value) {
+    if (Array.isArray(value))
+        return `an array of ${value.length}`;
+    if (typeof value === "object" && value !== null) {
+        const kind = value.kind;
+        return typeof kind === "string" ? `an object of kind "${kind}"` : "an object";
+    }
+    return `a ${typeof value}`;
+}
+/**
+ * `cascade.scene.Light` — Houdini's `/obj/hlight`, as a node.
+ *
+ * **Nothing shades with these yet**, and that is stated in the description so
+ * that a light which appears to do nothing is understood rather than reported
+ * as broken. Every piece in the vault today is lines — `cloud-volumes` is a
+ * volume, `particle-type` is trails, `cloud-plots` is marks — so there is no
+ * surface to light, and inventing a shading model before something needs one is
+ * how you get a shading model nobody wants.
+ *
+ * It exists now because `Scene` accepts lights now. A type that gains a field
+ * later invalidates every serialized scene and every node that builds one; the
+ * node is the cheap half of a decision already taken in the type.
+ */
+export const lightDefinition = {
+    apiVersion: 1,
+    label: "Light",
+    description: "A light, following Houdini's /obj/hlight. Nothing shades with lights yet — the viewport draws wireframe and points.",
+    icon: "Lightbulb",
+    runsOn: "portable",
+    inputs: {
+        translate: {
+            kind: "data",
+            type: "vec3",
+            default: [0, 0, 5],
+            description: "World position. Ignored for a distant or ambient light.",
+        },
+        direction: {
+            kind: "data",
+            type: "vec3",
+            default: [0, 0, -1],
+            description: "Direction the light points. Used by distant and spot.",
+        },
+        color: {
+            kind: "data",
+            type: "color",
+            default: [1, 1, 1, 1],
+            description: "Houdini light_color.",
+        },
+        intensity: {
+            kind: "data",
+            type: "float",
+            default: 1,
+            min: 0,
+            description: "Houdini light_intensity.",
+        },
+    },
+    outputs: {
+        light: { kind: "data", type: "light" },
+    },
+    props: {
+        type: {
+            type: "string",
+            default: "point",
+            label: "Light Type",
+            control: "select",
+            options: [
+                { value: "point", label: "Point" },
+                { value: "distant", label: "Distant - directional" },
+                { value: "ambient", label: "Ambient" },
+                { value: "spot", label: "Spot" },
+            ],
+            description: "Houdini light_type. Distant is what other renderers call directional.",
+        },
+        coneangle: {
+            type: "float",
+            default: 45,
+            min: 0,
+            max: 180,
+            label: "Cone Angle",
+            description: "Degrees. Spot only.",
+        },
+    },
+};
+export function executeLight(context) {
+    const type = context.props.type;
+    context.outputs.light.set({
+        type: type === "distant" || type === "ambient" || type === "spot"
+            ? type
+            : LIGHT_DEFAULTS.type,
+        translate: context.inputs.translate ?? LIGHT_DEFAULTS.translate,
+        direction: context.inputs.direction ?? LIGHT_DEFAULTS.direction,
+        color: context.inputs.color ?? LIGHT_DEFAULTS.color,
+        intensity: context.inputs.intensity ?? LIGHT_DEFAULTS.intensity,
+        coneangle: context.props.coneangle,
+    });
+}
+export const sceneRegistration = {
+    kind: "definition-v1",
+    moduleId: sceneModuleId("Scene"),
+    definition: sceneDefinition,
+    loadExecute: async () => executeScene,
+};
+export const lightRegistration = {
+    kind: "definition-v1",
+    moduleId: sceneModuleId("Light"),
+    definition: lightDefinition,
+    loadExecute: async () => executeLight,
+};
+export const sceneNodeRegistrations = Object.freeze([sceneRegistration, lightRegistration]);
+/** `[moduleId, definition]` pairs, for a host building a node palette. The same
+ *  shape `geoNodeDefinitions` and `popNodeDefinitions` have. */
+export const sceneNodeDefinitions = Object.freeze([
+    [sceneModuleId("Scene"), sceneDefinition],
+    [sceneModuleId("Light"), lightDefinition],
+]);
+//# sourceMappingURL=definitions.js.map

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

@@ -0,0 +1,2 @@
+export * from "./definitions.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,2 @@
+export * from "./definitions.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,60 @@
+import type { Camera, Mat4, Vec3 } from "@field/cascade/contracts";
+/** The camera's own axes in world space. */
+export interface CameraBasis {
+    /** Where the camera is. */
+    readonly eye: Vec3;
+    /** Unit vector the camera looks along — its own -Z. */
+    readonly forward: Vec3;
+    /** Unit vector to the camera's right — its own +X. */
+    readonly right: Vec3;
+    /** Unit vector for the camera's up — its own +Y. */
+    readonly up: Vec3;
+}
+/**
+ * The rotation the camera needs to look at a point, as Houdini's look-at does.
+ *
+ * Returned as degrees in XYZ order so it can be written straight into
+ * `camera.rotate` — which is what makes look-at an override of the transform
+ * rather than a second, parallel way to orient a camera.
+ *
+ * **`up` chooses the roll, and only the roll.** Yaw and pitch are fixed the
+ * moment a direction is given; all an up vector can still decide is the
+ * rotation about that direction. The default `[0, 1, 0]` is Houdini's own
+ * `upvector` default and gives roll zero for any horizontal up, which is why
+ * every ordinary orbit never needs to think about it.
+ *
+ * Written first with `roll = 0` and the parameter ignored, which was wrong in
+ * the way this codebase keeps finding: the node exposes `up` as an input, so a
+ * value set there did nothing at all and nothing said so.
+ */
+export declare function lookAtRotation(from: Vec3, to: Vec3, up?: Vec3): Vec3;
+/** The camera's axes, applying Houdini's XYZ rotation order to a camera that
+ *  looks down -Z at rest. */
+export declare function cameraBasis(camera: Camera): CameraBasis;
+/**
+ * The horizontal field of view in degrees, from the lens rather than stored.
+ *
+ * Houdini's defaults of 50 mm and 41.4214 mm are exactly 45°, which is the
+ * check worth having in a test: it is the one value that proves the formula and
+ * the defaults agree.
+ */
+export declare function horizontalFov(camera: Camera): number;
+/**
+ * The VERTICAL field of view in degrees.
+ *
+ * Houdini does not store a vertical aperture; it derives one from the
+ * horizontal aperture, the resolution ratio and the pixel aspect. Which is why
+ * `resolution` is on the camera at all — without it there is no vertical angle
+ * to be had.
+ */
+export declare function verticalFov(camera: Camera): number;
+/** Frame aspect — the shape of the picture, pixel aspect included. Distinct
+ *  from `camera.aspect`, which is the aspect of one pixel. */
+export declare function frameAspect(camera: Camera): number;
+/** Column-major, GLSL convention, matching `MATRIX_TYPES` in Studio: element 0
+ *  starts the first COLUMN. */
+export declare function viewMatrix(camera: Camera): Mat4;
+/** Column-major, and orthographic when the camera says so — `orthowidth` is a
+ *  width in world units, so the height comes from the frame aspect. */
+export declare function projectionMatrix(camera: Camera): Mat4;
+//# sourceMappingURL=index.d.ts.map