@field/cascade 0.3.1 → 0.4.0

package/dist/runtime/runtime.js

@@ -4,6 +4,7 @@ import { builtinNodeRegistrations } from "./builtins/index.js";
 import { deserializeChannel, isEmptyChannel } from "./animation/channel.js";
 import { PropAnimator, isBoundProp } from "./params/index.js";
 import { DEFAULT_FPS, MIN_FRAME } from "./expressions/time.js";
+import { isGpuHost } from "./gpu.js";
 /**
  * Preflight codes that describe something other than "this graph cannot run
  * here", so `run` proceeds and a checker reports them as warnings.
@@ -48,6 +49,7 @@ import { DEFAULT_FPS, MIN_FRAME } from "./expressions/time.js";
 export const PREFLIGHT_WARNING_CODES = new Set([
     "runtime/preflight-environment",
     "runtime/stray-params",
+    "runtime/unknown-props",
 ]);
 /**
  * The only preflight code that does not stop a run.
@@ -60,6 +62,7 @@ export const PREFLIGHT_WARNING_CODES = new Set([
  */
 const RUN_TOLERATED_CODES = new Set([
     "runtime/stray-params",
+    "runtime/unknown-props",
 ]);
 class MutableAbortSignal {
     report;
@@ -683,12 +686,23 @@ class Graph {
                     set: (value) => pendingData.set(name, runtimeValue(value, definition.type, false, `${node.id}.${name}`)),
                 },
         ]));
-        const capabilities = Object.freeze(Object.fromEntries((node.definition.capabilities ?? []).map((name) => [
-            name,
-            name === "shell"
-                ? bindShellToRun(this.host.capabilities.shell, signal)
-                : this.host.capabilities[name],
-        ])));
+        const capabilityEntries = [];
+        for (const name of node.definition.capabilities ?? []) {
+            const installed = this.host.capabilities[name];
+            if (name === "gpu" && isGpuHost(installed)) {
+                await installed.ensure();
+                capabilityEntries.push([name, installed.forNode(node.id)]);
+            }
+            else {
+                capabilityEntries.push([
+                    name,
+                    name === "shell"
+                        ? bindShellToRun(this.host.capabilities.shell, signal)
+                        : installed,
+                ]);
+            }
+        }
+        const capabilities = Object.freeze(Object.fromEntries(capabilityEntries));
         const props = Object.freeze({ ...node.props });
         const progress = {
             report: (event) => this.emit({ type: "node:progress", runId, nodeId: node.id, ...event }),
@@ -751,6 +765,8 @@ class Graph {
         const diagnostics = [];
         const push = (code, nodeId, message) => diagnostics.push({ phase: "preflight", code, path: nodeId, message });
         for (const node of nodes) {
+            if (node.unknownProps.length)
+                push("runtime/unknown-props", node.id, `${node.moduleId} stores ${node.unknownProps.join(", ")} under "props", and its definition declares no such prop — ${node.unknownProps.length === 1 ? "that value was" : "those values were"} dropped on load. A prop renamed or removed leaves its value behind; a name that never existed is a typo`);
             if (node.strayParams.length)
                 push("runtime/stray-params", node.id, `${node.moduleId} stores ${node.strayParams.join(", ")} under "params", which this runtime does not read — move ${node.strayParams.length === 1 ? "it" : "them"} to "props" or "inputs", whichever the definition declares, or the ${node.strayParams.length === 1 ? "value is" : "values are"} silently the default`);
             const remote = this.isRemote(node);
@@ -1022,6 +1038,25 @@ function materialize(authored, registration) {
         }
     for (const [name, definition] of Object.entries(registration.definition.props ?? {}))
         props[name] = runtimeValue(definition.default, definition.type, false, `${authored.id}.${name}`);
+    /**
+     * `props` is a map and `params` was a list, and a migration that changes the
+     * key without changing the shape leaves an array here.
+     *
+     * Fatal, and the reason is what it costs: `Object.entries` of an array gives
+     * keys `"0"`, `"1"`, which match no declared prop, so **every authored value
+     * is dropped and every signal stays green.** Measured on 2026-09-08 —
+     * preflight empty, the prop back at its default, `cascade run` reporting
+     * `completed`. `cloud-plots` rendered a whole picture against no moment and
+     * was reported as working on the strength of an exit code.
+     *
+     * An error rather than a warning, unlike a leftover under `params`: that is a
+     * real state an unconverted sketch is legitimately in and must keep
+     * validating, whereas `props` as an array is never valid — the schema
+     * declares a record — and nothing passes through it on the way to being
+     * right. Same reasoning as `definition/re-exported`.
+     */
+    if (Array.isArray(authored.props))
+        misuse("runtime/props-not-a-map", `Node ${authored.id} stores props as a list. "props" is a map of name to value; "params" was the list. Every value in it is being dropped, silently, and the graph would run on its defaults`);
     const bindings = {};
     // A declared default expression, applied only where the document stored
     // nothing at all for the prop. The loop below then runs over what *was*
@@ -1079,6 +1114,7 @@ function materialize(authored, registration) {
         props,
         bindings,
         strayParams: strayParams(authored, registration),
+        unknownProps: unknownProps(authored, registration),
         outputs: new Map(),
     };
 }
@@ -1103,6 +1139,27 @@ function materialize(authored, registration) {
  * naming nothing is a different fault, and reporting it would make this fire on
  * documents where no value was lost.
  */
+/**
+ * Names stored under `props` that the definition does not declare.
+ *
+ * The mirror of `strayParams`, and the gap that one had: it asks *is anything
+ * still under the old key*, which is blind to *did what arrived under the new
+ * key arrive in the right form*. One is a leftover, the other is a botched
+ * move, and the second is worse because it looks finished.
+ *
+ * A warning rather than an error, because unlike an array container this is a
+ * state a real document reaches honestly: a prop renamed or removed from a
+ * definition leaves its value behind, and the graph runs on the defaults. Same
+ * class as a leftover under `params`, and the same severity for the same
+ * reason — a sketch mid-conversion must keep validating.
+ */
+function unknownProps(authored, registration) {
+    const props = authored.props;
+    if (!props || Array.isArray(props))
+        return [];
+    const declared = registration.definition.props ?? {};
+    return Object.keys(props).filter((name) => !(name in declared));
+}
 function strayParams(authored, registration) {
     const definition = registration.definition;
     const declared = new Set([

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

@@ -0,0 +1,41 @@
+import type { CascadeAbortSignal, CascadePreset, CascadeSeries, SeriesInstanceResult } from "@field/cascade/contracts";
+import type { LoadedCascadeGraph } from "../types.js";
+/**
+ * The graph's current values for those keys, as a preset.
+ *
+ * Read through `inspect()` rather than from the nodes directly, so the values
+ * are the same snapshots every other reader gets. A key the graph does not
+ * have is left out rather than defaulted: `applyPreset` is the thing that
+ * decides an unknown key is a misuse, and it should keep deciding that.
+ */
+export declare function seriesBaseline(graph: LoadedCascadeGraph, series: CascadeSeries): CascadePreset;
+export interface RunSeriesOptions {
+    readonly signal?: CascadeAbortSignal;
+    readonly frame?: number;
+    readonly fps?: number;
+    /**
+     * The instance to cook first, by id.
+     *
+     * *"Making changes to the underlying network re-renders the current selected
+     * item first then the entire series."* The order of the results is always the
+     * series' own order whatever this says — only the order of the **work**
+     * changes, because the caller is watching one instance and waiting for a
+     * list would defeat the point.
+     */
+    readonly first?: string;
+    /** Called as each instance finishes, in cook order rather than list order,
+     *  so a gallery can fill in as results arrive instead of after all of them. */
+    readonly onInstance?: (result: SeriesInstanceResult) => void;
+}
+export interface SeriesRunResult {
+    /** In the series' own order, whatever order the work ran in. */
+    readonly instances: readonly SeriesInstanceResult[];
+    /** By record id, which is the address everything downstream uses. */
+    readonly byId: ReadonlyMap<string, SeriesInstanceResult>;
+    readonly status: "completed" | "cancelled" | "failed";
+}
+/** Ids must be unique, or an instance has no address at all — and every
+ *  judgement, override and cache key in the plan hangs off that address. */
+export declare function validateSeries(series: CascadeSeries): void;
+export declare function runSeries(graph: LoadedCascadeGraph, series: CascadeSeries, options?: RunSeriesOptions): Promise<SeriesRunResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/series/index.js

@@ -0,0 +1,167 @@
+/**
+ * Cooking a graph once per parameter set.
+ *
+ * Step 1 of `PLAN series.md`, and headless on purpose: it is the foundation the
+ * gallery and the scheduler stand on, and it is verifiable without a picture.
+ *
+ * **The whole difficulty is that a parameter set is sparse.** `applyPreset`
+ * mutates the runtime, and instance 3 overriding `seed` while instance 4 does
+ * not means instance 4 inherits instance 3's seed unless something puts it
+ * back. That is accidental feedback — in the one mechanism specified as having
+ * none — and it would show up as a series where the pictures are subtly wrong
+ * in an order-dependent way, which is close to the worst failure this system
+ * could have: re-run it and the same instance renders differently, so it reads
+ * as a flaky renderer rather than as a bug.
+ *
+ * So every instance is cooked from the same baseline. The baseline is itself a
+ * `CascadePreset`, holding the graph's current value for **every key any
+ * instance touches** — the union, computed once — which means restoring is the
+ * same validated code path as applying, rather than a second one that can
+ * disagree with it.
+ */
+/** Every `node.input` and `node.prop` any instance in the series overrides. */
+function overriddenKeys(series) {
+    const keys = new Map();
+    for (const instance of series.instances) {
+        for (const [nodeId, values] of Object.entries(instance.parameters.nodes)) {
+            let entry = keys.get(nodeId);
+            if (!entry) {
+                entry = { inputs: new Set(), props: new Set() };
+                keys.set(nodeId, entry);
+            }
+            for (const name of Object.keys(values.inputs ?? {}))
+                entry.inputs.add(name);
+            for (const name of Object.keys(values.props ?? {}))
+                entry.props.add(name);
+        }
+    }
+    return keys;
+}
+/**
+ * The graph's current values for those keys, as a preset.
+ *
+ * Read through `inspect()` rather than from the nodes directly, so the values
+ * are the same snapshots every other reader gets. A key the graph does not
+ * have is left out rather than defaulted: `applyPreset` is the thing that
+ * decides an unknown key is a misuse, and it should keep deciding that.
+ */
+export function seriesBaseline(graph, series) {
+    const wanted = overriddenKeys(series);
+    const inspection = graph.inspect();
+    const nodes = {};
+    for (const node of inspection.nodes) {
+        const entry = wanted.get(node.id);
+        if (!entry)
+            continue;
+        const inputs = {};
+        const props = {};
+        for (const name of entry.inputs) {
+            if (node.inputs[name] !== undefined)
+                inputs[name] = node.inputs[name].value;
+        }
+        for (const name of entry.props) {
+            if (node.props[name] !== undefined)
+                props[name] = node.props[name].value;
+        }
+        if (Object.keys(inputs).length > 0 || Object.keys(props).length > 0) {
+            nodes[node.id] = {
+                ...(Object.keys(inputs).length > 0 ? { inputs } : {}),
+                ...(Object.keys(props).length > 0 ? { props } : {}),
+            };
+        }
+    }
+    return { version: 1, nodes };
+}
+/** Ids must be unique, or an instance has no address at all — and every
+ *  judgement, override and cache key in the plan hangs off that address. */
+export function validateSeries(series) {
+    if (series.version !== 1) {
+        throw new Error("Series version must be 1");
+    }
+    const seen = new Set();
+    for (const instance of series.instances) {
+        if (!instance.id)
+            throw new Error("Every series instance needs an id");
+        if (seen.has(instance.id)) {
+            throw new Error(`Duplicate series instance id ${instance.id}`);
+        }
+        seen.add(instance.id);
+    }
+}
+function collect(graph, collection) {
+    return "graphOutput" in collection
+        ? graph.getGraphOutput(collection.graphOutput)
+        : graph.getOutput(collection.nodeId, collection.output);
+}
+/** The cook order: the selected instance, then the rest in the series' order. */
+function cookOrder(series, first) {
+    const order = series.instances.map((_, index) => index);
+    if (first === undefined)
+        return order;
+    const selected = series.instances.findIndex(instance => instance.id === first);
+    if (selected < 0)
+        return order;
+    return [selected, ...order.filter(index => index !== selected)];
+}
+export async function runSeries(graph, series, options = {}) {
+    validateSeries(series);
+    // Before the first `applyPreset` and not after, or the baseline is already
+    // instance one's.
+    const baseline = seriesBaseline(graph, series);
+    const results = new Array(series.instances.length);
+    let cancelled = false;
+    try {
+        for (const index of cookOrder(series, options.first)) {
+            if (options.signal?.aborted) {
+                cancelled = true;
+                break;
+            }
+            const instance = series.instances[index];
+            // Baseline first, every time. A sparse set does not clear what the
+            // previous instance changed, and inheriting it is accidental feedback.
+            await graph.applyPreset(baseline);
+            await graph.applyPreset(instance.parameters);
+            const run = await graph.run({
+                ...(options.signal ? { signal: options.signal } : {}),
+                ...(options.frame === undefined ? {} : { frame: options.frame }),
+                ...(options.fps === undefined ? {} : { fps: options.fps }),
+            });
+            const result = {
+                id: instance.id,
+                index,
+                status: run.status,
+                // A run that did not complete has no value worth collecting, and
+                // reading the port anyway would hand back the previous instance's
+                // picture under this instance's id.
+                value: run.status === "completed" ? collect(graph, series.collect) : undefined,
+                diagnostics: run.diagnostics,
+                durationMs: run.timings.durationMs,
+            };
+            results[index] = result;
+            options.onInstance?.(result);
+            if (run.status === "cancelled") {
+                cancelled = true;
+                break;
+            }
+        }
+    }
+    finally {
+        // Leave the graph as it was found. A series is a way of looking at a graph,
+        // not an edit to it, and a Studio session that ran one and was left on the
+        // last instance's parameters would be indistinguishable from one the author
+        // had changed by hand.
+        await graph.applyPreset(baseline);
+    }
+    const completed = results.filter((result) => Boolean(result));
+    const status = cancelled
+        ? "cancelled"
+        : completed.some(result => result.status === "failed")
+            ? "failed"
+            : "completed";
+    return {
+        instances: completed,
+        byId: new Map(completed.map(result => [result.id, result])),
+        status,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/runtime/types.d.ts

@@ -246,7 +246,7 @@ export interface LoadedCascadeGraph {
     getOutputs(nodeId: string): ReadonlyMap<string, unknown>;
     dispose(): Promise<void>;
 }
-export interface NodeRuntimeHostOptions extends Omit<RuntimeCapabilities, "gpu"> {
+export interface NodeRuntimeHostOptions extends RuntimeCapabilities {
     readonly modules: RuntimeHost["modules"];
     readonly legacyShell?: LegacyShellBindingFactory & Readonly<{
         kind: "server-direct";

package/doc/HEADLESS_GPU.md

@@ -0,0 +1,160 @@
+# Headless WebGPU with Dawn
+
+The CLI can run definition-v1 nodes declaring `runsOn: 'portable'` or
+`'server'` and `capabilities: ['gpu']` through optional `webgpu@0.6.0` (Dawn).
+Studio uses browser WebGPU through the same device/cache lifecycle mechanism.
+Browser-only declarations remain browser-only; installing Dawn does not supply
+DOM, WebGL, canvas presentation, image decoding, or video APIs.
+
+## Decision and release status
+
+Implemented on 2026-09-08 and checked in as source version `0.3.2`; see the
+[changelog](../CHANGELOG.md). Checking in the source does not publish the npm
+package. Use a built checkout or a tarball known to include the feature until
+the corresponding package release is published.
+
+The decision is to use optional native Dawn for browser-independent GPU
+execution and agent image feedback. Browser automation remains useful for
+Studio interaction/presentation tests; Skia remains the Canvas2D renderer.
+Neither is replaced by Dawn. This first slice shares WGSL/rendering logic and
+device/cache ownership without introducing a new graph texture pipeline or
+requiring a browser process for production CLI rendering.
+
+## Render for a test or agent
+
+From a compatible project, using a Cascade build containing this feature:
+
+```sh
+npx --no-install cascade run index.cascade --frames 1 --json --timeout 60000
+npx --no-install cascade run index.cascade --frames 1-24 --fps 24 --out renders --json --timeout 120000
+```
+
+`--json` requires a fully definition-v1 frame render; use `--frames 1` for a
+still. Stdout contains one success manifest with absolute graph path,
+project-relative image `files`, `frames`, actual `fps`, elapsed `durationMs`,
+and Dawn adapter metadata when a GPU was used. Logs and failure diagnostics go
+to stderr; failures exit nonzero and do not emit a success manifest. This is a
+local command contract, not a chat-provider integration or an untrusted-code sandbox.
+
+Illustrative manifest for the `cloud-volumes/dawn.cascade` fixture:
+
+```json
+{
+  "status": "completed",
+  "graph": "/path/to/cloud-volumes/dawn.cascade",
+  "frames": [1, 2],
+  "files": ["renders/dawn/volume.0001.png", "renders/dawn/volume.0002.png"],
+  "aborted": false,
+  "fps": 30,
+  "durationMs": 115.1,
+  "gpu": {
+    "renderer": "dawn",
+    "adapter": {
+      "vendor": "apple",
+      "architecture": "metal-3",
+      "device": "apple-m3-max",
+      "description": "Metal driver on macOS"
+    }
+  }
+}
+```
+
+Resolve `files` relative to the directory containing `graph`. `gpu` is omitted
+if no GPU node executed. `durationMs` measures the frame-rendering section and
+cleanup, excluding CLI startup and module preparation; it is not GPU-pass time.
+
+For agent callers: set a finite timeout, check the exit code, parse stdout only
+on success, then attach the listed images to the conversation. Keep stderr for
+diagnosis. A manifest records outputs, not a complete reproducibility bundle:
+save the graph, code/assets and authored settings separately. The CLI does not
+upload images or contact a model provider.
+
+`--timeout` supervises a separate render process and returns exit 124 when its
+deadline expires. On POSIX, termination covers that process group; on Windows,
+the current supervisor terminates the direct child only. Interrupts are forwarded
+with a short grace period before forced termination. A forced stop can leave
+partial output files; consumers must check the exit code and manifest. Ordinary
+successful runs destroy cached resources and release the native GPU reference.
+
+Dawn loads lazily, only when a GPU node executes. Static `check`/`validate`
+inspect the declared host contract without initializing hardware; they do not
+prove that a native binary, driver, or adapter is usable. Missing native support
+produces an installation diagnostic at execution. Dawn itself may be omitted
+for CPU-only environments; retain the compiler's own platform dependencies.
+Skia remains the independent Canvas2D path.
+
+## Authoring contract
+
+Use `context.capabilities.gpu.device` and `.cache(key, create, destroy)`.
+Cache keys are scoped per node; destroy callbacks release textures and buffers.
+The application owns the host's disposal, not an individual graph sharing it.
+Use `createRenderPipelineAsync` to surface shader/pipeline validation failures.
+`readTexture` captures validation failures within its own operation. Arbitrary
+GPU commands issued before it need their own error scopes or async validation;
+run-aware routing of all uncaptured device errors is not implemented yet.
+
+Render into a single-sample `rgba8unorm` 2D texture with
+`TextureUsage.RENDER_ATTACHMENT | TextureUsage.COPY_SRC`. Then:
+
+```ts
+import { readTexture } from 'cascade/gpu';
+
+const pixels = await readTexture(gpu.device, target, { signal: context.signal });
+// pixels: { data: Uint8Array, width, height }, tightly packed top-left RGBA8
+```
+
+Readback strips the WebGPU buffer row padding and copies bytes before unmapping.
+It releases its staging buffer on success, mapping failure, or cancellation.
+It does not encode PNGs or perform colour conversion. Encode through the existing
+image/IO host and publish an `image` value. Graph-wide texture transport, HDR
+readback, and browser video uploads are outside this first implementation.
+
+## Verification and limits
+
+```sh
+CASCADE_TEST_DAWN=1 npx vitest run tests/dawn-native.test.ts
+CASCADE_TEST_DAWN=1 npm run test:package
+```
+
+These opt-in hardware gates fail if Dawn cannot initialize. The first checks
+repeated creation, rendering, padded readback and natural process exit. The
+second installs a packed tarball into an empty project, renders animated PNGs
+through the CLI and checks decoded pixels and the JSON manifest.
+It also removes Dawn from that temporary installation to verify that a CPU
+graph still runs and a GPU graph fails with an actionable missing-renderer
+diagnostic. No silent CPU or browser fallback is performed.
+
+Recorded implementation verification (2026-09-08):
+
+- Main test suite: 1,322 passed; the opt-in hardware test was skipped there and
+  passed separately with `CASCADE_TEST_DAWN=1`.
+- Typechecking: zero errors, eight existing Svelte warnings.
+- Contracts/runtime package checks and tests, server/Studio/CLI builds, and
+  packed-package imports/types and rendering checks passed.
+- The real `cloud-volumes/dawn.cascade` fixture passed static checks and wrote
+  two distinct animated PNGs with an adapter-bearing JSON manifest.
+
+These are recorded results, not a claim that every future checkout or platform
+passes. Rerun the gates after changes; Windows/Linux hardware has not yet been
+verified. Windows process-tree cancellation remains follow-up work.
+
+Do not require identical pixels across GPUs/drivers. Pin reference environments,
+record adapter information and use measured image tolerances. Agent callers
+should set a timeout, cap dimensions/frame counts, and preserve graph/code,
+assets, seed and frame settings alongside selected outputs.
+
+Initial proof (2026-09-08): the `cloud-volumes` shader at 130 × 96, 32 steps,
+with a fixed opaque 17 × 73 column and 144-byte uniform block produced zero
+changed channels across 49,920 channels for both original browser canvas →
+migrated browser texture and migrated browser → native Dawn. All outputs were
+nonblank. Both hosts used Apple Metal (native: M3 Max). This establishes that
+specific migration's parity, not universal GPU bit-exactness. The sketch's
+`dawn.cascade` additionally exercises the real Aoos input, image IO and animation
+through the CLI at 256 × 320.
+
+Native packaging and GPU/driver support vary by platform. The package chooses
+its default backend; Cascade does not enable unsafe Dawn toggles or silently
+configure software drivers. Software Vulkan requires separate host setup.
+See [Dawn Node bindings](https://github.com/dawn-gpu/node-webgpu),
+[software backend setup](https://dawn.googlesource.com/dawn/+/refs/heads/main/src/dawn/node/README.md),
+and [WGSL floating-point rules](https://gpuweb.github.io/gpuweb/wgsl/#floating-point-evaluation).

package/doc/NODE_REFERENCE.md

@@ -17,6 +17,42 @@ node and none is needed.
 These are definition-v1: their declarations are literal, so what follows is
 exact rather than a description.
 
+### `cascade.core.Camera`
+
+Camera — A camera, following Houdini's /obj/cam.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `translate` | `vec3` | `[0,0,5]` |  |
+| `rotate` | `vec3` | `[0,0,0]` |  |
+| `focal` | `float` | `50` | 1…300 |
+| `lookat` | `vec3` | `[0,0,0]` |  |
+| `up` | `vec3` | `[0,1,0]` |  |
+| `spin` | `float` | `0` |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `lookAt` | `bool` | `false` |  |
+| `aperture` | `float` | `41.4214` | 1…200 |
+| `resolution` | `vec2i` | `[1280,720]` |  |
+| `aspect` | `float` | `1` | 0.1…10 |
+| `projection` | `string` | `"perspective"` |  |
+| `orthowidth` | `float` | `2` |  |
+| `near` | `float` | `0.001` |  |
+| `far` | `float` | `10000` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `camera` | `camera` |  |  |
+
 ### `cascade.core.Input`
 
 Input — Defines a public graph or subnet input