@field/cascade 0.3.1 → 0.5.1

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/dist/studio/panel.d.ts

@@ -8,9 +8,76 @@ export interface ProjectPanelMeta {
 
 export interface ProjectPanelApi {
   runStage<T = unknown>(stage: string, args: Record<string, unknown>): Promise<T>;
-  mediaUrl(path: string, options?: { width?: number; raw?: boolean }): string;
+  /** `version` busts a cache when a re-render reuses a path. It existed in
+   *  core and not in this type, so a panel could not reach it. */
+  mediaUrl(path: string, options?: { width?: number; raw?: boolean; version?: string | number }): string;
+  /**
+   * A parameter's RESOLVED value — a keyframe channel first, then an
+   * expression, then the stored value. What the node's `execute` sees.
+   *
+   * Which means it is **not** the inverse of `setParam` when the parameter
+   * carries a binding. Use `getRawParam` to read back a write.
+   */
   getParam<T = unknown>(nodeId: string, name: string): T | undefined;
+  /**
+   * A parameter's STORED value, before a channel or an expression resolves it.
+   *
+   * This is what `setParam` writes, so it is the one to read back after a
+   * write. Added 2026-09-09: a panel that wrote a value and re-read it with
+   * `getParam` got the resolved value, concluded its write had failed, and
+   * re-rendered a whole series at the parameter it had just replaced. Nothing
+   * threw and nothing logged.
+   */
+  getRawParam<T = unknown>(nodeId: string, name: string): T | undefined;
+  /**
+   * Write a parameter's stored value.
+   *
+   * Clears a *declared default* expression, because a default expression is a
+   * default and the written value wins. **Throws when a channel or an
+   * author-written expression would shadow the write**, naming which — those
+   * legitimately win, and silently storing a value nobody will ever read is
+   * how a panel comes to believe a parameter is broken. Clear the binding
+   * first if the write is meant to take effect.
+   */
   setParam(nodeId: string, name: string, value: unknown): void;
+  /**
+   * A node's output value, read-only.
+   *
+   * Added 2026-09-09, and it is the one whose absence distorted a whole
+   * sketch. A panel could set parameters and not read results, so the series
+   * panel reached its own outputs through **two extra nodes and a stage**: a
+   * node whose only purpose was to write a value to disk, and a Python stage
+   * that cooked a graph so the panel could fetch it back. Both delete with
+   * this. A panel that can write and not read is half a surface.
+   *
+   * A snapshot rather than a live handle, and read-only on purpose: a panel
+   * that could mutate an output would be writing into the middle of the
+   * dependency graph, where nothing downstream would know.
+   */
+  getOutput<T = unknown>(nodeId: string, outputName: string): T | undefined;
+  /** Every output of a node, by name. For a panel that does not know the
+   *  shape of what it is looking at. */
+  getOutputs(nodeId: string): Readonly<Record<string, unknown>>;
+  /**
+   * Cook the graph, or one node's subtree, and resolve when it settles.
+   *
+   * A panel could ignore work through `api.signal` and could not start or stop
+   * any, so `PLAN series`' cancellable queue was not implementable from a panel
+   * at all.
+   *
+   * **There is deliberately no `background` option**, and finding out why cost
+   * an hour: cooking *the graph* in the background is incoherent, because the
+   * graph has one state. A background cook either merges with interactive work
+   * or fights it — and concretely, routing one through `scheduler.flush` made
+   * it cancel itself, since `flush` preempts the background lane by design.
+   * Measured, not reasoned: every such call returned `'preempted'`.
+   *
+   * The background lane is for cooking a *different parameter set*, which means
+   * driving nodes directly rather than through the shared queue. That belongs
+   * to the series mechanism rather than to a panel, and a panel will reach it
+   * through the series API instead.
+   */
+  cook(options?: { readonly nodeId?: string }): Promise<void>;
   selectedNodeId(): string | null;
   readonly sourceNodeId: string | null;
   readonly signal: AbortSignal;

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 as source version `0.3.2` and included in the 0.5
+release; see the [changelog](../CHANGELOG.md). Use the project-local CLI and
+record its version when comparing renders. A source checkout may contain
+changes beyond the installed npm package.
+
+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).