@field/cascade 0.4.0 → 0.5.2

package/dist/cli/runtime/io.ts

@@ -1,19 +1,5 @@
-/**
- * `cascade/io` — the runtime a BROWSER-side node imports.
- *
- * The interop rests on one rule: an image port carries a project-relative PATH,
- * never pixels. A Python node writes a file and emits its path; a WebGL node
- * reads that path as a texture, renders, writes its result back, and emits a
- * path of the same kind. Neither knows or cares which side produced its input,
- * which is what makes the two interchangeable — and it lets the heavy stages
- * stay in Python while the interactive ones run in the page.
- *
- * The counterpart on the server side is the project's own exec bridge
- * (`runStage`), which is per-project because the stages are.
- *
- * This file is compiled into any node module that imports 'cascade/io'; it is
- * not published to npm and has no dependencies.
- */
+/** Shared `cascade/io` helpers. Studio uses project HTTP routes; other hosts
+ * install a bridge. Image ports carry paths rather than ambient pixel buffers. */
 
 export interface MediaOptions {
   /** Ask for a resized copy. Never upscales past the file's own resolution. */
@@ -30,6 +16,8 @@ export interface MediaOptions {
 /** Build the URL that serves a project file to the page. */
 export function mediaUrl(path: string, options: MediaOptions = {}): string {
   if (/^(https?:|data:|blob:)/.test(path)) return path;
+  const bridge = localIo();
+  if (bridge?.url) return bridge.url(path, options);
   const clean = path.replace(/^\.?\//, '');
   const encoded = clean.split('/').map(encodeURIComponent).join('/');
   const params = new URLSearchParams();
@@ -61,6 +49,8 @@ export interface IoBridge {
   read(path: string, options?: MediaOptions): Promise<Uint8Array>;
   /** Write bytes into the project cache. Returns the stored project-relative path. */
   write(path: string, data: Uint8Array): Promise<string>;
+  /** Host-owned display URL, valid until the host releases its stored asset. */
+  url?(path: string, options?: MediaOptions): string;
 }
 
 const IO_BRIDGE_KEY = '__cascadeIoBridge';
@@ -108,20 +98,36 @@ export async function loadBytes(path: string, options: MediaOptions = { raw: tru
 export async function loadImage(path: string, options: MediaOptions = { raw: true }): Promise<HTMLImageElement> {
   const image = new Image();
   const bridge = localIo();
-  if (bridge) {
-    // No origin to resolve a URL against; hand the decoder the bytes.
-    (image as unknown as { src: unknown }).src = new Uint8Array(await loadBytes(path, options));
-  } else {
-    image.crossOrigin = 'anonymous';
-    image.src = mediaUrl(path, options);
+  let temporaryUrl: string | undefined;
+  try {
+    if (bridge?.url) {
+      image.crossOrigin = 'anonymous';
+      image.src = bridge.url(path, options);
+    } else if (bridge) {
+      const bytes = await loadBytes(path, options);
+      if (typeof document === 'undefined') {
+        // The Node canvas Image decoder accepts bytes, not browser Blob URLs.
+        (image as unknown as { src: unknown }).src = new Uint8Array(bytes);
+      } else {
+        temporaryUrl = URL.createObjectURL(new Blob([bytes]));
+        image.src = temporaryUrl;
+      }
+    } else {
+      image.crossOrigin = 'anonymous';
+      image.src = mediaUrl(path, options);
+    }
+    await image.decode();
+    return image;
+  } finally {
+    if (temporaryUrl) URL.revokeObjectURL(temporaryUrl);
   }
-  await image.decode();
-  return image;
 }
 
 /** Same, as an ImageBitmap — the right input for `texImage2D`. */
 export async function loadBitmap(path: string, options: MediaOptions = { raw: true }): Promise<ImageBitmap> {
-  if (localIo()) return createImageBitmap(new Blob([await loadBytes(path, options)]));
+  const bridge = localIo();
+  if (bridge?.url) return createImageBitmap(await loadImage(path, options));
+  if (bridge) return createImageBitmap(new Blob([await loadBytes(path, options)]));
   const response = await fetch(mediaUrl(path, options));
   if (!response.ok) throw new Error(`cascade/io: cannot load ${path} (${response.status})`);
   return createImageBitmap(await response.blob());

package/dist/contracts/definition.d.ts

@@ -146,8 +146,27 @@ export type AnyPropDefinition = {
 export interface NodeDefinitionForEnvironment<E extends RuntimeEnvironment> {
     readonly apiVersion: 1;
     readonly runsOn: E;
-    /** Declares that authored nodes may use this node as their parent. */
-    readonly container?: "subnet";
+    /**
+     * Declares that authored nodes may use this node as their parent.
+     *
+     * `subnet` is a **grouping**: the children are ordinary nodes in the one flat
+     * graph, cooked once each in the usual dependency order, and the container is
+     * a boundary for display and for `cascade.core.Input`/`Output` to bind to.
+     *
+     * `feedback` is an **evaluation construct**: the children are removed from the
+     * main order and re-run once per step by the container, with the previous
+     * step's result entering through `cascade.core.Previous`. It exists because a
+     * simulation is the one thing a pure DAG cannot express — which is why Houdini
+     * made its Solver SOP special too — and Marcus asked for it on 2026-09-09,
+     * wanting to dive into a particle node and see its forces as nodes.
+     *
+     * The distinction is load-bearing for correctness, not just for scheduling: a
+     * `subnet` child's output is read once and is a function of the graph, while a
+     * `feedback` child's output is read N times and is a function of the graph
+     * *and* the step. Anything that caches on a node's inputs has to know which
+     * kind it is looking at.
+     */
+    readonly container?: "subnet" | "feedback";
     readonly capabilities?: readonly CapabilityForEnvironment<E>[];
     readonly label?: string;
     readonly description?: string;

package/dist/contracts/index.d.ts

@@ -5,6 +5,8 @@ export * from "./color.js";
 export * from "./definition.js";
 export * from "./document.js";
 export * from "./geometry.js";
+export * from "./particles.js";
+export * from "./scene.js";
 export * from "./series.js";
 export * from "./validate.js";
 export * from "./values.js";

package/dist/contracts/index.js

@@ -5,6 +5,8 @@ export * from "./color.js";
 export * from "./definition.js";
 export * from "./document.js";
 export * from "./geometry.js";
+export * from "./particles.js";
+export * from "./scene.js";
 export * from "./series.js";
 export * from "./validate.js";
 export * from "./values.js";

package/dist/contracts/particles.d.ts

@@ -0,0 +1,54 @@
+import { type AttributeLevel, type AttributeStorage, type Geometry } from "./geometry.js";
+/**
+ * The attribute contract a particle system reads and writes.
+ *
+ * Step 1 of `PLAN particles.md`, and it is deliberately first: **renaming an
+ * attribute after three operators read it is the expensive change.** So the
+ * names, levels and storage are fixed before any node exists, and nothing here
+ * is a node — this file declares a vocabulary and the checks that hold it.
+ *
+ * Houdini's names throughout, per the standing rule. Where Houdini and Cascade
+ * disagree the reason is written down beside the entry rather than left as a
+ * preference.
+ *
+ * **A particle system is geometry.** There is no particle type: points with
+ * these attributes on them are what a solver reads and what `CopyToPoints`,
+ * `SvgExport` and every other geometry node already understand. That is the
+ * whole reason `PLAN geometry` retires `points` to an alias — four names for
+ * one concept, and a fifth for particles would be worse.
+ */
+export interface ParticleAttributeSpec {
+    readonly name: string;
+    readonly level: AttributeLevel;
+    readonly storage: AttributeStorage;
+    /** Components. `P` is 2 or 3, so it is stated as a range rather than a size. */
+    readonly size: number | readonly [number, number];
+    /** Whether a solver may run without it. */
+    readonly required: boolean;
+    readonly units?: "seconds" | "turns";
+    readonly note: string;
+}
+export declare const PARTICLE_ATTRIBUTES: readonly ParticleAttributeSpec[];
+export declare function particleAttribute(name: string): ParticleAttributeSpec | undefined;
+/** The attributes a solver cannot run without. */
+export declare function requiredParticleAttributes(): readonly ParticleAttributeSpec[];
+export interface ParticleContractViolation {
+    readonly attribute: string;
+    readonly reason: string;
+}
+/**
+ * Whether a geometry carries the attributes a solver reads, in the shapes it
+ * reads them in.
+ *
+ * Returns every violation rather than the first, because the answer a caller
+ * wants is *what is wrong with this geometry* and not *what is the first thing
+ * wrong with it* — a source node missing three attributes should say so once.
+ *
+ * Deliberately not a throw: `cascade check` wants to report this statically
+ * alongside its other findings, and a solver wants to fail with a sentence. The
+ * shared thing between them is the list.
+ */
+export declare function checkParticleContract(geometry: Geometry): readonly ParticleContractViolation[];
+/** True when this geometry could be stepped by a solver. */
+export declare function isParticleGeometry(geometry: Geometry): boolean;
+//# sourceMappingURL=particles.d.ts.map

package/dist/contracts/particles.js

@@ -0,0 +1,167 @@
+import { POSITION_ATTRIBUTE, } from "./geometry.js";
+/**
+ * Position. Already `POSITION_ATTRIBUTE`, and `f64` because the Python bridge
+ * writes points as float64 and narrowing would add a lossy step to a boundary
+ * that is lossless today.
+ */
+const P = {
+    name: POSITION_ATTRIBUTE,
+    level: "point",
+    storage: "f64",
+    size: [2, 3],
+    required: true,
+    note: "Position. Shared with every other geometry node, not a particle attribute.",
+};
+export const PARTICLE_ATTRIBUTES = Object.freeze([
+    P,
+    {
+        name: "v",
+        level: "point",
+        storage: "f32",
+        size: [2, 3],
+        required: true,
+        note: "Velocity, in units per second. f32 rather than f64: a velocity is not a coordinate, so the precision argument for P does not carry over.",
+    },
+    {
+        name: "age",
+        level: "point",
+        storage: "f32",
+        size: 1,
+        required: true,
+        units: "seconds",
+        // The one place this departs from the sketch it is modelled on.
+        note: "Seconds, not frames. A frame count changes meaning with fps, and a graph whose particles die at a different point when rendered at 60 is not deterministic in any useful sense.",
+    },
+    {
+        name: "life",
+        level: "point",
+        storage: "f32",
+        size: 1,
+        required: true,
+        units: "seconds",
+        note: "Life expectancy in seconds. A particle dies when age >= life.",
+    },
+    {
+        name: "id",
+        level: "point",
+        storage: "i32",
+        size: 1,
+        required: true,
+        note: "Stable across frames and across kills. Mandatory: a particle array reorders on every kill, so anything durable and per-particle must key on this rather than on an index.",
+    },
+    {
+        name: "nextid",
+        level: "detail",
+        storage: "i32",
+        size: 1,
+        required: true,
+        note: "The next id to hand out. Houdini's own mechanism for keeping id monotonic, and what stops an id being reused after a kill.",
+    },
+    {
+        name: "Cd",
+        level: "point",
+        storage: "f32",
+        size: 4,
+        required: false,
+        note: "Colour. Owned by the style vocabulary in PLAN geometry, which refuses a Cd that is a string or numeric with any size but four.",
+    },
+    {
+        name: "pscale",
+        level: "point",
+        storage: "f32",
+        size: 1,
+        required: false,
+        note: "Not a POP attribute in Houdini's sense. Writing it is what makes CopyToPoints scale its instances, which is how oriented marks get drawn without a new node.",
+    },
+    {
+        name: "N",
+        level: "point",
+        storage: "f32",
+        size: [2, 3],
+        required: false,
+        note: "Orientation, read by CopyToPoints alongside pscale.",
+    },
+]);
+const BY_NAME = new Map(PARTICLE_ATTRIBUTES.map((spec) => [spec.name, spec]));
+export function particleAttribute(name) {
+    return BY_NAME.get(name);
+}
+/** The attributes a solver cannot run without. */
+export function requiredParticleAttributes() {
+    return PARTICLE_ATTRIBUTES.filter((spec) => spec.required);
+}
+function sizeMatches(spec, size) {
+    return typeof spec.size === "number"
+        ? size === spec.size
+        : size >= spec.size[0] && size <= spec.size[1];
+}
+function describeSize(spec) {
+    return typeof spec.size === "number" ? String(spec.size) : `${spec.size[0]} or ${spec.size[1]}`;
+}
+/**
+ * Whether a geometry carries the attributes a solver reads, in the shapes it
+ * reads them in.
+ *
+ * Returns every violation rather than the first, because the answer a caller
+ * wants is *what is wrong with this geometry* and not *what is the first thing
+ * wrong with it* — a source node missing three attributes should say so once.
+ *
+ * Deliberately not a throw: `cascade check` wants to report this statically
+ * alongside its other findings, and a solver wants to fail with a sentence. The
+ * shared thing between them is the list.
+ */
+export function checkParticleContract(geometry) {
+    const violations = [];
+    for (const spec of PARTICLE_ATTRIBUTES) {
+        if (spec.level === "detail") {
+            const value = geometry.detail[spec.name];
+            if (value === undefined) {
+                if (spec.required) {
+                    violations.push({
+                        attribute: spec.name,
+                        reason: `missing detail attribute ${spec.name} — ${spec.note}`,
+                    });
+                }
+                continue;
+            }
+            if (typeof value !== "number") {
+                violations.push({
+                    attribute: spec.name,
+                    reason: `detail ${spec.name} must be a number, not ${typeof value}`,
+                });
+            }
+            continue;
+        }
+        const attribute = geometry.point[spec.name];
+        if (attribute === undefined) {
+            if (spec.required) {
+                violations.push({
+                    attribute: spec.name,
+                    reason: `missing point attribute ${spec.name} — ${spec.note}`,
+                });
+            }
+            continue;
+        }
+        // A string where a number belongs is the failure that would otherwise
+        // reach arithmetic and produce NaN silently.
+        if (attribute.storage === "string") {
+            violations.push({
+                attribute: spec.name,
+                reason: `${spec.name} is a string attribute; a solver reads it as ${spec.storage}`,
+            });
+            continue;
+        }
+        if (!sizeMatches(spec, attribute.size)) {
+            violations.push({
+                attribute: spec.name,
+                reason: `${spec.name} has size ${attribute.size}; expected ${describeSize(spec)}`,
+            });
+        }
+    }
+    return violations;
+}
+/** True when this geometry could be stepped by a solver. */
+export function isParticleGeometry(geometry) {
+    return checkParticleContract(geometry).length === 0;
+}
+//# sourceMappingURL=particles.js.map

package/dist/contracts/scene.d.ts

@@ -0,0 +1,129 @@
+import type { Camera } from "./camera.js";
+import type { Geometry } from "./geometry.js";
+import type { Vec3, Vec4 } from "./values.js";
+/**
+ * A scene: geometry, an optional camera, and lights.
+ *
+ * Marcus asked for this on 2026-09-09, and it arrived as a correction to a
+ * worse design. The plan before it proposed a separate `scene` panel beside the
+ * Viewer, and then — once that was corrected — a Viewer 3D mode that special
+ * cased `geometry`. His version:
+ *
+ * > *"If we want a 'scene' we could just create a merge node with a 3D viewer,
+ * > or perhaps a 'scene' root node with a variadic input? … a 'scene' node with
+ * > a camera, lights and geometry attached becomes a '3d scene'."*
+ *
+ * What that buys is not a feature, it is the removal of a branch. **The Viewer's
+ * 3D mode renders exactly one type.** A bare `geometry` output is a scene
+ * carrying a default camera and a default light, which is what Houdini itself
+ * does — the viewport camera and the headlight exist until you make real ones —
+ * so "geometry displays in 3D" is a promotion (`sceneFromGeometry`) rather than
+ * a second code path. Every branch that special-cases geometry against scene is
+ * a place the two can disagree about framing.
+ *
+ * The same promotion is why `cascade.geo.Render` can take a scene without
+ * breaking a single existing sketch: `geometry` widens to `scene`, so the old
+ * wire is still legal and lands on `asScene`.
+ *
+ * ## Why this is not `cascade.geo.Merge`
+ *
+ * Merge concatenates points, vertices and primitives and renumbers them, and a
+ * camera is not a primitive — `mergeGeometries`' collision rules have nothing
+ * to say about one. Two operations that both take N inputs are not the same
+ * operation.
+ *
+ * ## Why the camera is nullable rather than defaulted here
+ *
+ * A scene with no camera means *"use the viewport's own navigated camera"*, and
+ * that is a different statement from *"use a 50 mm camera at the origin"*. It
+ * is also Houdini's behaviour, which Marcus confirmed on 2026-09-09 — *"yes to
+ * copying the Houdini camera"*: unwired, you fly around freely; wire a
+ * `cascade.core.Camera` and the view locks to it and navigation writes back
+ * into its parameters. A defaulted camera here would make that distinction
+ * unrepresentable, and the viewport would have no way to know whether the
+ * camera it was handed was a decision or a fallback.
+ *
+ * `CAMERA_DEFAULTS` is still where the fallback numbers live; a consumer that
+ * genuinely needs a camera object asks for one there, and the null stays
+ * meaningful.
+ */
+export interface Scene {
+    /**
+     * Every geometry in the scene, in input order.
+     *
+     * A list rather than one merged geometry, because merging is lossy in the way
+     * that matters to a viewport: two geometries with different point counts and
+     * different style attributes become one after `mergeGeometries`, and the
+     * viewport can then no longer draw them with separate styles, report which
+     * one is over the item cap, or let one be soloed. Merge is available as a
+     * node when someone wants it.
+     */
+    readonly geometry: readonly Geometry[];
+    /** `null` means the viewport's own navigated camera. See above. */
+    readonly camera: Camera | null;
+    readonly lights: readonly Light[];
+}
+/**
+ * A light, following Houdini's `/obj/hlight` where it has an equivalent.
+ *
+ * Houdini's parameters are `light_type`, `light_color` and `light_intensity`;
+ * the names here drop the redundant prefix a Cascade node does not need, since
+ * the type already says it is a light. `type` keeps Houdini's own vocabulary,
+ * including **`distant`** for what most renderers call a directional light.
+ *
+ * Nothing consumes lights yet — every piece in the vault is lines, and there is
+ * no surface to shade. They are in the type from the start anyway, because
+ * adding a field to `Scene` later means every serialized scene and every node
+ * that constructs one changes, and the whole point of landing the type first is
+ * that it stops changing.
+ */
+export interface Light {
+    /** Houdini `light_type`. `ambient` ignores `translate` and `direction`. */
+    readonly type: "point" | "distant" | "ambient" | "spot";
+    /** World position. Ignored for `distant` and `ambient`. */
+    readonly translate: Vec3;
+    /** Direction the light points. Used by `distant` and `spot`. */
+    readonly direction: Vec3;
+    /** Houdini `light_color`, as a `vec4` — colour is four components, always. */
+    readonly color: Vec4;
+    /** Houdini `light_intensity`. */
+    readonly intensity: number;
+    /** Cone angle in degrees, `spot` only. Houdini `coneangle`. */
+    readonly coneangle: number;
+}
+export declare const LIGHT_DEFAULTS: Light;
+/** A scene with nothing in it. Not a failure — an empty graph produces one. */
+export declare const EMPTY_SCENE: Scene;
+export declare function isLight(value: unknown): value is Light;
+/**
+ * Structural, and deliberately not a brand.
+ *
+ * A scene crosses the host boundary as JSON — Studio panel to worker, project
+ * module to runtime — and a branded type would not survive the round trip, so
+ * the check has to be answerable from the shape alone. It tests `geometry` and
+ * `lights` are arrays and that `camera` is present-and-nullable rather than
+ * merely absent, which is what distinguishes a scene from an arbitrary object
+ * that happens to carry a `geometry` field.
+ */
+export declare function isScene(value: unknown): value is Scene;
+/** The promotion: a geometry is a scene with the viewport's camera and no lights. */
+export declare function sceneFromGeometry(geometry: Geometry): Scene;
+/**
+ * Read a `scene` input, which may have received a `geometry`.
+ *
+ * `geometry` widens to `scene` in `IMPLICIT_TYPE_CONVERSIONS`, so a node
+ * declaring a `scene` input can be handed either. **Every consumer of a scene
+ * input must go through this**, and that is the whole contract: the alternative
+ * is each consumer testing `isScene` and getting the fallback subtly different,
+ * which is how a viewport and a render node end up framing the same graph two
+ * ways.
+ *
+ * Returns `EMPTY_SCENE` for a missing input rather than throwing, because an
+ * unwired viewport is a normal state and not an error — and for anything that
+ * is neither a scene nor a geometry, because a viewport that throws on a
+ * surprising value is a viewport that goes black while the graph is fine. The
+ * connection rules are what stop a wrong type arriving; this is the floor under
+ * them, not the check.
+ */
+export declare function asScene(value: unknown): Scene;
+//# sourceMappingURL=scene.d.ts.map

package/dist/contracts/scene.js

@@ -0,0 +1,73 @@
+export const LIGHT_DEFAULTS = {
+    type: "point",
+    translate: [0, 0, 0],
+    direction: [0, 0, -1],
+    color: [1, 1, 1, 1],
+    intensity: 1,
+    coneangle: 45,
+};
+/** A scene with nothing in it. Not a failure — an empty graph produces one. */
+export const EMPTY_SCENE = { geometry: [], camera: null, lights: [] };
+export function isLight(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const light = value;
+    return ((light.type === "point" ||
+        light.type === "distant" ||
+        light.type === "ambient" ||
+        light.type === "spot") &&
+        Array.isArray(light.translate) &&
+        Array.isArray(light.direction) &&
+        Array.isArray(light.color) &&
+        typeof light.intensity === "number");
+}
+/**
+ * Structural, and deliberately not a brand.
+ *
+ * A scene crosses the host boundary as JSON — Studio panel to worker, project
+ * module to runtime — and a branded type would not survive the round trip, so
+ * the check has to be answerable from the shape alone. It tests `geometry` and
+ * `lights` are arrays and that `camera` is present-and-nullable rather than
+ * merely absent, which is what distinguishes a scene from an arbitrary object
+ * that happens to carry a `geometry` field.
+ */
+export function isScene(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const scene = value;
+    return (Array.isArray(scene.geometry) &&
+        Array.isArray(scene.lights) &&
+        "camera" in scene &&
+        (scene.camera === null || typeof scene.camera === "object"));
+}
+/** The promotion: a geometry is a scene with the viewport's camera and no lights. */
+export function sceneFromGeometry(geometry) {
+    return { geometry: [geometry], camera: null, lights: [] };
+}
+/**
+ * Read a `scene` input, which may have received a `geometry`.
+ *
+ * `geometry` widens to `scene` in `IMPLICIT_TYPE_CONVERSIONS`, so a node
+ * declaring a `scene` input can be handed either. **Every consumer of a scene
+ * input must go through this**, and that is the whole contract: the alternative
+ * is each consumer testing `isScene` and getting the fallback subtly different,
+ * which is how a viewport and a render node end up framing the same graph two
+ * ways.
+ *
+ * Returns `EMPTY_SCENE` for a missing input rather than throwing, because an
+ * unwired viewport is a normal state and not an error — and for anything that
+ * is neither a scene nor a geometry, because a viewport that throws on a
+ * surprising value is a viewport that goes black while the graph is fine. The
+ * connection rules are what stop a wrong type arriving; this is the floor under
+ * them, not the check.
+ */
+export function asScene(value) {
+    if (value === undefined || value === null)
+        return EMPTY_SCENE;
+    if (isScene(value))
+        return value;
+    if (typeof value === "object" && value.kind === "geometry")
+        return sceneFromGeometry(value);
+    return EMPTY_SCENE;
+}
+//# sourceMappingURL=scene.js.map

package/dist/contracts/schema.js

@@ -82,7 +82,7 @@ export const nodeDefinitionSchema = {
     ...object({
         apiVersion: { const: 1 },
         runsOn: { enum: ["portable", "browser", "server"] },
-        container: { const: "subnet" },
+        container: { enum: ["subnet", "feedback"] },
         capabilities: {
             type: "array",
             items: { type: "string" },

package/dist/contracts/validate.js

@@ -90,8 +90,10 @@ export function validateNodeDefinition(value) {
         add("api-version", "apiVersion must be 1", "apiVersion");
     if (!Object.prototype.hasOwnProperty.call(ALLOWED, String(environment)))
         add("environment", "runsOn must be portable, browser, or server", "runsOn");
-    if (value.container !== undefined && value.container !== "subnet")
-        add("invalid-container", "container must be subnet", "container");
+    if (value.container !== undefined &&
+        value.container !== "subnet" &&
+        value.container !== "feedback")
+        add("invalid-container", "container must be subnet or feedback", "container");
     const allowed = ALLOWED[environment] ?? [];
     if (value.capabilities !== undefined && !Array.isArray(value.capabilities))
         add("invalid-capabilities", "capabilities must be an array", "capabilities");

package/dist/contracts/values.d.ts

@@ -1,7 +1,8 @@
 import type { Camera } from "./camera.js";
 import type { Color } from "./color.js";
+import type { Light, Scene } from "./scene.js";
 import type { Geometry, GeometryFileRef, GeometryJson, GeometrySerialized } from "./geometry.js";
-export declare const CORE_TYPES: readonly ["float", "int", "bool", "string", "vec2", "vec3", "vec4", "vec2i", "vec3i", "vec4i", "mat2", "mat3", "mat4", "image", "texture", "geometry", "points", "lines", "polyline", "mesh", "rects", "color", "camera", "asset", "array", "object", "any"];
+export declare const CORE_TYPES: readonly ["float", "int", "bool", "string", "vec2", "vec3", "vec4", "vec2i", "vec3i", "vec4i", "mat2", "mat3", "mat4", "image", "texture", "geometry", "points", "lines", "polyline", "mesh", "rects", "color", "camera", "scene", "light", "asset", "array", "object", "any"];
 export type CoreType = (typeof CORE_TYPES)[number];
 export type NamespacedType = `${string}.${string}`;
 export type CascadeType = CoreType | NamespacedType;
@@ -95,7 +96,7 @@ export interface AssetRef {
     readonly mediaType?: string;
 }
 export type SerializableValue = JsonValue | AssetRef | ImageRef | GeometryJson | GeometryFileRef;
-export type ValueForType<T extends CascadeType> = T extends "float" | "int" ? number : T extends "bool" ? boolean : T extends "string" ? string : T extends "vec2" ? Vec2 : T extends "vec3" ? Vec3 : T extends "vec4" ? Vec4 : T extends "vec2i" ? Vec2i : T extends "vec3i" ? Vec3i : T extends "vec4i" ? Vec4i : T extends "mat2" ? Mat2 : T extends "mat3" ? Mat3 : T extends "mat4" ? Mat4 : T extends "color" ? Color : T extends "camera" ? Camera : T extends "image" ? ImageRef : T extends "texture" ? TextureHandle : T extends "geometry" ? Geometry : T extends "points" ? PointSet : T extends "lines" ? LineSegments : T extends "polyline" ? Polyline : T extends "mesh" ? Mesh : T extends "rects" ? Rects : T extends "asset" ? AssetRef : T extends "array" ? readonly unknown[] : T extends "object" ? Readonly<Record<string, unknown>> : unknown;
+export type ValueForType<T extends CascadeType> = T extends "float" | "int" ? number : T extends "bool" ? boolean : T extends "string" ? string : T extends "vec2" ? Vec2 : T extends "vec3" ? Vec3 : T extends "vec4" ? Vec4 : T extends "vec2i" ? Vec2i : T extends "vec3i" ? Vec3i : T extends "vec4i" ? Vec4i : T extends "mat2" ? Mat2 : T extends "mat3" ? Mat3 : T extends "mat4" ? Mat4 : T extends "color" ? Color : T extends "camera" ? Camera : T extends "scene" ? Scene : T extends "light" ? Light : T extends "image" ? ImageRef : T extends "texture" ? TextureHandle : T extends "geometry" ? Geometry : T extends "points" ? PointSet : T extends "lines" ? LineSegments : T extends "polyline" ? Polyline : T extends "mesh" ? Mesh : T extends "rects" ? Rects : T extends "asset" ? AssetRef : T extends "array" ? readonly unknown[] : T extends "object" ? Readonly<Record<string, unknown>> : unknown;
 export type SerializableValueForType<T extends CascadeType> = T extends "texture" ? never : T extends "geometry" ? GeometrySerialized : T extends "array" ? readonly JsonValue[] : T extends "object" ? Readonly<Record<string, JsonValue>> : T extends "any" | NamespacedType ? JsonValue : ValueForType<T>;
 export {};
 //# sourceMappingURL=values.d.ts.map

package/dist/contracts/values.js

@@ -22,6 +22,8 @@ export const CORE_TYPES = [
     "rects",
     "color",
     "camera",
+    "scene",
+    "light",
     "asset",
     "array",
     "object",
@@ -39,6 +41,13 @@ export const IMPLICIT_TYPE_CONVERSIONS = {
     vec2i: ["vec2"],
     vec3i: ["vec3"],
     vec4i: ["vec4"],
+    /**
+     * A geometry *is* a scene — one with the viewport's own camera and no lights.
+     * So the wire is legal and nothing is lost, which is the widening rule this
+     * table already follows. Every consumer of a `scene` input reads it through
+     * `asScene`, which performs the promotion; see `scene.ts`.
+     */
+    geometry: ["scene"],
     vec4: ["color"],
     color: ["vec4"],
 };

package/dist/index.html

@@ -4,11 +4,11 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Cascade</title>
-  <script type="module" crossorigin src="/assets/index-CC6YQw2n.js"></script>
+  <script type="module" crossorigin src="/assets/index-CeqTfMbr.js"></script>
   <link rel="modulepreload" crossorigin href="/assets/legacy-CAj2_7QE.js">
   <link rel="modulepreload" crossorigin href="/assets/index-client-BoJgsN9M.js">
-  <link rel="modulepreload" crossorigin href="/assets/nodeTypeUtils-BBA1JqHx.js">
-  <link rel="stylesheet" crossorigin href="/assets/index-Y2ock1cw.css">
+  <link rel="modulepreload" crossorigin href="/assets/nodeTypeUtils-BDJsc2Ks.js">
+  <link rel="stylesheet" crossorigin href="/assets/index-ilgbOu6G.css">
 </head>
 <body>
   <div id="app"></div>