@field/cascade 0.3.0 → 0.4.0

package/dist/cli/runtime/gpu.ts

@@ -0,0 +1,147 @@
+/**
+ * `cascade/gpu` — WebGPU's flag namespaces as plain values.
+ *
+ * Small, and it was load-bearing. TypeScript's DOM library declares the WebGPU
+ * *interfaces* but not the constant objects, so the only way to reach
+ * `GPUTextureUsage.RENDER_ATTACHMENT` was off `globalThis` — which
+ * `architecture/ambient-state` correctly forbids inside a node module, because
+ * an ambient read makes a node's inputs invisible to the static reader that
+ * lets `cascade check` say anything without cooking.
+ *
+ * So a sketch had to choose between a rule and a working shader, and it chose
+ * a project library file to hide the read in. Both stay honest now: the rule
+ * keeps its teeth and a node imports these instead. That is the whole reason
+ * this file exists, and it is why it had to land with the capability rather
+ * than after it — a rule whose only workaround is removed at the same moment
+ * is a rule; one enforced a release earlier is a nuisance.
+ *
+ * The values are fixed by the WebGPU specification, not by an implementation,
+ * which is what makes writing them down safe rather than a guess. They are
+ * checked against a real browser's own globals in `tests/gpu-usage-flags.test.ts`
+ * — the numbers below were verified against Chrome rather than recalled.
+ */
+
+/** `GPUBufferUsage`. */
+export const BufferUsage = {
+  MAP_READ: 0x0001,
+  MAP_WRITE: 0x0002,
+  COPY_SRC: 0x0004,
+  COPY_DST: 0x0008,
+  INDEX: 0x0010,
+  VERTEX: 0x0020,
+  UNIFORM: 0x0040,
+  STORAGE: 0x0080,
+  INDIRECT: 0x0100,
+  QUERY_RESOLVE: 0x0200,
+} as const;
+
+/** `GPUTextureUsage`. */
+export const TextureUsage = {
+  COPY_SRC: 0x01,
+  COPY_DST: 0x02,
+  TEXTURE_BINDING: 0x04,
+  STORAGE_BINDING: 0x08,
+  RENDER_ATTACHMENT: 0x10,
+  /**
+   * Chrome 147 has this and it is newer than the rest — verified present
+   * 2026-09-08 alongside the others, but do not assume every implementation
+   * carries it. Included rather than omitted deliberately: leaving it out
+   * would send a node that wants it back to `globalThis`, which is the exact
+   * ambient read this file exists to remove, so an honest constant with a
+   * caveat beats an omission that forces a rule violation.
+   */
+  TRANSIENT_ATTACHMENT: 0x20,
+} as const;
+
+/** `GPUShaderStage`, for a bind group layout entry's `visibility`. */
+export const ShaderStage = {
+  VERTEX: 0x1,
+  FRAGMENT: 0x2,
+  COMPUTE: 0x4,
+} as const;
+
+/** `GPUMapMode`, for `buffer.mapAsync`. */
+export const MapMode = {
+  READ: 0x1,
+  WRITE: 0x2,
+} as const;
+
+/** `GPUColorWrite`, for a colour target's `writeMask`. */
+export const ColorWrite = {
+  RED: 0x1,
+  GREEN: 0x2,
+  BLUE: 0x4,
+  ALPHA: 0x8,
+  ALL: 0xf,
+} as const;
+
+/** Read one single-sample rgba8unorm 2D texture into owned, tightly packed
+ * top-left RGBA bytes. No colour conversion, PNG encoding or graph transport.
+ * The caller owns the source texture and must give it COPY_SRC usage.
+ */
+export async function readTexture(
+  device: GPUDevice,
+  texture: GPUTexture,
+  options: { signal?: {
+    readonly aborted: boolean;
+    addEventListener(type: 'abort', listener: () => void, options?: { once?: boolean }): void;
+    removeEventListener(type: 'abort', listener: () => void): void;
+  } } = {},
+): Promise<{ data: Uint8Array<ArrayBuffer>; width: number; height: number }> {
+  const { signal } = options;
+  if (signal?.aborted) throw new Error('GPU readback aborted');
+  if (texture.format !== 'rgba8unorm' || texture.dimension !== '2d'
+    || texture.depthOrArrayLayers !== 1 || texture.sampleCount !== 1
+    || !(texture.usage & TextureUsage.COPY_SRC)) {
+    throw new Error('GPU readback requires a single-sample rgba8unorm 2D texture with COPY_SRC usage');
+  }
+  const { width, height } = texture;
+  const rowBytes = width * 4;
+  const bytesPerRow = Math.ceil(rowBytes / 256) * 256;
+  let buffer: GPUBuffer | undefined;
+  let mapped = false;
+  let abort: (() => void) | undefined;
+  let errorScopeOpen = false;
+  try {
+    device.pushErrorScope('validation');
+    errorScopeOpen = true;
+    buffer = device.createBuffer({
+      label: 'Cascade RGBA readback', size: bytesPerRow * height,
+      usage: BufferUsage.COPY_DST | BufferUsage.MAP_READ,
+    });
+    const encoder = device.createCommandEncoder();
+    encoder.copyTextureToBuffer({ texture }, { buffer, bytesPerRow }, [width, height]);
+    device.queue.submit([encoder.finish()]);
+    const validation = device.popErrorScope();
+    errorScopeOpen = false;
+    const completion = Promise.allSettled([buffer.mapAsync(MapMode.READ), validation]);
+    let completed: Awaited<typeof completion>;
+    if (signal) {
+      completed = await Promise.race([completion, new Promise<never>((_, reject) => {
+        abort = () => reject(new Error('GPU readback aborted'));
+        signal.addEventListener('abort', abort, { once: true });
+        if (signal.aborted) abort();
+      })]);
+    } else completed = await completion;
+    const mappingResult = completed[0];
+    const validationResult = completed[1];
+    if (validationResult.status === 'rejected') throw validationResult.reason;
+    const validationError = validationResult.value;
+    if (validationError) throw new Error(`GPU readback validation failed: ${validationError.message}`);
+    if (mappingResult.status === 'rejected') throw mappingResult.reason;
+    mapped = true;
+    if (signal?.aborted) throw new Error('GPU readback aborted');
+    const source = new Uint8Array(buffer.getMappedRange());
+    const data = new Uint8Array(rowBytes * height);
+    for (let y = 0; y < height; y++) data.set(source.subarray(y * bytesPerRow, y * bytesPerRow + rowBytes), y * rowBytes);
+    return { data, width, height };
+  } finally {
+    if (abort) signal?.removeEventListener('abort', abort);
+    if (errorScopeOpen) {
+      try { await device.popErrorScope(); }
+      catch { /* Preserve the operation's original failure. */ }
+    }
+    if (mapped) buffer?.unmap();
+    buffer?.destroy();
+  }
+}

package/dist/contracts/camera.d.ts

@@ -0,0 +1,70 @@
+import type { Vec2i, Vec3 } from "./values.js";
+/**
+ * A camera, following Houdini's `/obj/cam`.
+ *
+ * `AGENTS.md` already required following Houdini's parameter names where
+ * Houdini has an equivalent node, and Marcus restated it for this type
+ * specifically on 2026-09-08. It is worth writing down what that costs, because
+ * the obvious design is not the Houdini one and it was proposed first here:
+ *
+ * **There is no field of view.** Houdini has `focal` (a focal length in
+ * millimetres) and `aperture` (the horizontal aperture, also in millimetres),
+ * and the angle is derived from the two. The defaults — 50 mm on a 41.4214 mm
+ * aperture — are a 45° horizontal field of view, which is where that odd
+ * aperture number comes from. Carrying an `fov` instead would be one number
+ * rather than two, and it would also make every lens value a photographer knows
+ * untypeable.
+ *
+ * **The orientation is `translate` and `rotate`, not eye-and-target.** A
+ * Houdini camera is an object with an ordinary transform, looking down its own
+ * **-Z** with **+Y** up, and look-at is a second mechanism layered on top
+ * (`lookatpath` and `upvector`) rather than the primitive. So `lookat` and `up`
+ * are here as the optional override they are in Houdini, and `rotate` is what
+ * the type actually carries.
+ *
+ * **Rotation is degrees, XYZ order** — Houdini's convention, and already the
+ * one `cascade.geo.Transform` uses for its own `rotate`. Note that this is
+ * deliberately unlike expressions, where bare trigonometry is radians; that
+ * divergence is recorded in `AGENTS.md` and is not new here.
+ *
+ * The one place this departs from Houdini's names is **`resolution` in place of
+ * `resx` and `resy`**, because the vault's more specific rule wins: anything
+ * with an x and a y is one `vec2`, and resolutions are named in that rule
+ * explicitly. Two floats that are really one vector cost two Inspector rows and
+ * two keyframes and let a graph carry a width without its height.
+ *
+ * Resolution belongs to the camera rather than to the render target for a
+ * Houdini reason that is easy to miss: the **vertical** aperture is not stored,
+ * it is derived from the horizontal one and the resolution ratio. So the frame
+ * shape participates in the projection, and a camera that did not know it could
+ * not produce a vertical angle at all.
+ */
+export interface Camera {
+    /** World position. Houdini `t`. */
+    readonly translate: Vec3;
+    /** Degrees, XYZ order. Houdini `r`. The camera looks down its own -Z. */
+    readonly rotate: Vec3;
+    /** Focal length in millimetres. Houdini `focal`, default 50. */
+    readonly focal: number;
+    /** Horizontal aperture in millimetres. Houdini `aperture`, default 41.4214. */
+    readonly aperture: number;
+    /** Near clipping plane. Houdini `near`, default 0.001. */
+    readonly near: number;
+    /** Far clipping plane. Houdini `far`, default 10000. */
+    readonly far: number;
+    /** Frame size in pixels. Houdini `resx`/`resy` as one `vec2i`. */
+    readonly resolution: Vec2i;
+    /** PIXEL aspect ratio, not the frame's. Houdini `aspect`, default 1. */
+    readonly aspect: number;
+    /** Houdini `projection`. */
+    readonly projection: "perspective" | "orthographic";
+    /** Width of the orthographic frame in world units. Houdini `orthowidth`. */
+    readonly orthowidth: number;
+}
+/** Houdini's own defaults, so a camera with nothing set matches a fresh
+ *  `/obj/cam` rather than something invented here. */
+export declare const CAMERA_DEFAULTS: Camera;
+/** True for any object carrying the fields this type is identified by. Used at
+ *  the document boundary, where a value arrives as parsed JSON. */
+export declare function isCamera(value: unknown): value is Camera;
+//# sourceMappingURL=camera.d.ts.map

package/dist/contracts/camera.js

@@ -0,0 +1,27 @@
+/** Houdini's own defaults, so a camera with nothing set matches a fresh
+ *  `/obj/cam` rather than something invented here. */
+export const CAMERA_DEFAULTS = Object.freeze({
+    translate: [0, 0, 0],
+    rotate: [0, 0, 0],
+    focal: 50,
+    aperture: 41.4214,
+    near: 0.001,
+    far: 10000,
+    resolution: [1280, 720],
+    aspect: 1,
+    projection: "perspective",
+    orthowidth: 2,
+});
+/** True for any object carrying the fields this type is identified by. Used at
+ *  the document boundary, where a value arrives as parsed JSON. */
+export function isCamera(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const candidate = value;
+    return (Array.isArray(candidate.translate) &&
+        Array.isArray(candidate.rotate) &&
+        typeof candidate.focal === "number" &&
+        typeof candidate.aperture === "number");
+}
+//# sourceMappingURL=camera.js.map

package/dist/contracts/capabilities.d.ts

@@ -1,4 +1,4 @@
-import type { AssetRef, ImageRef, JsonValue, TextureHandle } from "./values.js";
+import type { AssetRef, ImageRef, JsonValue } from "./values.js";
 export interface CascadeAbortSignal {
     readonly aborted: boolean;
     readonly reason?: unknown;
@@ -66,10 +66,73 @@ export interface PythonCapability {
         progress: ProgressReporter;
     }): Promise<JsonValue | AssetRef | ImageRef>;
 }
-export interface WebGLCapability {
-    createTexture(descriptor: JsonValue, options: {
-        signal: CascadeAbortSignal;
-    }): Promise<ResourceLease<TextureHandle>>;
+/**
+ * A GPU a node can compute on, and the state that has to outlive one cook.
+ *
+ * This replaces `WebGLCapability`, which nothing implemented, nothing declared
+ * and no host installed — its one method was WebGL2-shaped, and keeping both
+ * names would have meant two devices in one page. Two devices cannot exchange
+ * a texture: an allocation made on one is not bindable, sampleable or copyable
+ * on the other, and the failure is a validation error at bind time rather than
+ * anything a graph author would recognise. So a shared device is not a
+ * preference, it is the precondition for a chain of GPU nodes at all.
+ *
+ * **The capability carries a device/cache contract, not graph textures.** Ports
+ * still pass `image`; what this buys is
+ * one device instead of one per node module, an owner for `device.lost`, and
+ * somewhere legitimate to keep a pipeline — which is what lets the
+ * `architecture/ambient-state` rule stay strict. The texture store, the
+ * generation-stamped handles remain future work. Explicit RGBA8 readback is a
+ * helper in `cascade/gpu`, shared by browser and native hosts without encoding.
+ *
+ * The `GPUDevice` type comes from `@webgpu/types`, added to this package's
+ * `tsconfig.json` as its only `types` entry. Contracts compiles with
+ * `lib: ["ES2022"]` and no DOM on purpose — it is the vocabulary both hosts
+ * share, so pulling in the whole browser would let a browser-only type reach a
+ * portable definition by accident. A hand-written stub was the alternative and
+ * would have been worse than a dependency: it would shadow the genuine
+ * `GPUDevice` at the node's own call site, so every real method call would
+ * stop typechecking.
+ *
+ * The device is raw on purpose. A wrapped pipeline API would be a second thing
+ * to learn, would lag the spec, and would fight the reason to reach for WebGPU
+ * at all, which is that you write WGSL and encode passes. The capability wraps
+ * only what carries lifetime or identity, because those are the parts a host
+ * has to be able to account for.
+ */
+export interface GpuCapability {
+    /**
+     * The one device for this host. Shared by every node declaring `gpu`, which
+     * is the whole point — see the note above on why two would be useless.
+     */
+    readonly device: GPUDevice;
+    /**
+     * Who is actually rendering, recorded so a difference between two runs of
+     * the same graph is attributable rather than a mystery. WebGPU output can
+     * differ across adapters, and today there is no way to answer "which one".
+     */
+    readonly adapterInfo: Readonly<{
+        vendor: string;
+        architecture: string;
+        device: string;
+        description: string;
+    }>;
+    /** What this adapter will actually allow — `maxTextureDimension3D` and the
+     *  rest. Read at runtime rather than assumed; the 3D default is far below
+     *  the 2D one and a hard-coded guess would be wrong on some machines. */
+    readonly limits: Readonly<Record<string, number>>;
+    /**
+     * A resource that outlives one cook — a compiled pipeline, a sampler, a
+     * bind group layout. Keyed per node by the host, so two instances of one
+     * module do not share a cache entry and a module-level `Map` is never the
+     * right answer again.
+     *
+     * `create` runs once per key. `destroy` is called when the entry is dropped:
+     * when the device is lost, or when the owning host disposes. This is the member
+     * that makes `architecture/module-state` keepable — it was previously
+     * forbidding the only available way to hold a pipeline.
+     */
+    cache<T>(key: string, create: (device: GPUDevice) => T, destroy?: (value: T) => void): T;
 }
 export interface ShellRunResult {
     readonly stdout: string;
@@ -102,7 +165,7 @@ export interface CapabilityMap {
     readonly assets: AssetCapability;
     readonly media: MediaCapability;
     readonly python: PythonCapability;
-    readonly webgl: WebGLCapability;
+    readonly gpu: GpuCapability;
     readonly shell: ShellCapability;
 }
 export type NodeCapabilityName = keyof CapabilityMap;

package/dist/contracts/definition.d.ts

@@ -1,7 +1,7 @@
 import type { CapabilityMap, CascadeAbortSignal, NodeCapabilityName, ProgressReporter } from "./capabilities.js";
 import type { CascadeType, CoreType, JsonValue, NamespacedType, SerializableValueForType, ValueForType } from "./values.js";
 export type RuntimeEnvironment = "portable" | "browser" | "server";
-export type CapabilityForEnvironment<E extends RuntimeEnvironment> = E extends "portable" ? "assets" | "media" : E extends "browser" ? "assets" | "media" | "webgl" : "files" | "assets" | "media" | "python" | "shell";
+export type CapabilityForEnvironment<E extends RuntimeEnvironment> = E extends "portable" ? "assets" | "media" | "gpu" : E extends "browser" ? "assets" | "media" | "gpu" : "files" | "assets" | "media" | "python" | "shell" | "gpu";
 export type DataTypeForEnvironment<E extends RuntimeEnvironment> = E extends "browser" ? CascadeType : Exclude<CascadeType, "texture">;
 type ControlFor<T extends CascadeType> = T extends "float" ? "number" | "slider" | "range" : T extends "int" ? "int" | "slider" | "range" : T extends "bool" ? "boolean" : T extends "string" ? "text" | "textarea" | "select" : T extends "vec2" | "vec3" | "vec4" | "vec2i" | "vec3i" | "vec4i" ? "vector" : T extends "mat2" | "mat3" | "mat4" ? "matrix" : T extends "color" ? "color" : T extends "image" ? "image" : T extends "asset" ? "asset" | "select" : T extends "texture" ? never : "select";
 /**
@@ -41,12 +41,34 @@ type AcceptMetadata<T extends CascadeType> = T extends "image" | "asset" ? {
 } : {
     readonly accept?: never;
 };
+/**
+ * One choice on a select control: the bare value, or the value with the words
+ * a person reads.
+ *
+ * The labelled form exists because losing it cost something real. Converting
+ * `image-superres` turned *"Off (pass through) / Local — Real-ESRGAN /
+ * Magnific — costs money"* into `off` / `local` / `magnific`, and that third
+ * label carried **the only warning that one of the three engines spends money
+ * per call**. A lost display name is a papercut; a lost cost warning is a
+ * bill. Six props across the sketches had lost their labels by the time this
+ * landed, and that one is why it was not deferred any longer.
+ *
+ * A bare value stays legal, and reads as "the value is the label" — which is
+ * true of most enums and is what every existing definition means.
+ */
+export type SelectOption<T extends CascadeType> = SerializableValueForType<T> | Readonly<{
+    value: SerializableValueForType<T>;
+    label: string;
+    /** Greyed out but visible: an option that exists and cannot be picked
+     *  here, which is more informative than one that is simply absent. */
+    disabled?: boolean;
+}>;
 type SelectMetadata<T extends CascadeType> = {
     readonly control?: Exclude<ControlFor<T>, "select">;
     readonly options?: never;
 } | {
     readonly control: Extract<ControlFor<T>, "select">;
-    readonly options?: readonly SerializableValueForType<T>[];
+    readonly options?: readonly SelectOption<T>[];
 };
 export interface TriggerInputDefinition {
     readonly kind: "trigger";
@@ -80,6 +102,43 @@ export type PropDefinition<T extends PropDataType> = {
     readonly default: SerializableValueForType<T>;
     readonly label?: string;
     readonly description?: string;
+    /**
+     * An expression the prop starts with, so a node can come out of the box
+     * already moving — `sine-oscillator` and `ripple` baked in `$T` as dynamic
+     * nodes and shipped a static 0 once converted, which is what this restores.
+     * Marcus's decision, 2026-09-08, asked as a taste question about his own
+     * tool: a node like that should self-animate when dropped.
+     *
+     * **It is a default, so it loses to a stored value like any other.** A
+     * document that saved a plain number for this prop keeps that number and
+     * does not silently start animating on load. That is the mirror of the
+     * dropped-`params` fault: whatever the author set has to win, and the test
+     * for this asserts the losing case rather than the winning one.
+     *
+     * Applied only when the document stored nothing at all for the prop. It is a
+     * real expression once applied, not a hidden fallback — visible in the
+     * Inspector, editable, and deletable, which is how a stored expression
+     * already reads and the only version that does not lie about where the
+     * number came from.
+     */
+    readonly expression?: string;
+    /**
+     * Render this prop as a button that fires a named action, rather than as an
+     * editable field.
+     *
+     * It exists because converting a node removed a button. `observatory-moment`
+     * declared `action: 'panel:observatory-moments'` as a dynamic node, which the
+     * Inspector renders from `parameter.options.action`; the v1 adapter built its
+     * options from `label`, `min`, `max`, `step` and `options` only, so the
+     * Moment picker quietly became a two-step job through the panel menu instead
+     * of one click on the node. Nothing broke — the panel falls back to the
+     * selected node and reads the same prop — which is exactly why nobody would
+     * have noticed from a test.
+     *
+     * The value is the action name the host dispatches. Cascade does not
+     * interpret it; a `panel:` prefix is a Studio convention, not a contract.
+     */
+    readonly action?: string;
 } & NumericMetadata<T> & AcceptMetadata<T> & SelectMetadata<T>;
 export type AnyPropDefinition = {
     [T in PropDataType]: PropDefinition<T>;

package/dist/contracts/index.d.ts

@@ -1,9 +1,11 @@
 export * from "./animation.js";
+export * from "./camera.js";
 export * from "./capabilities.js";
 export * from "./color.js";
 export * from "./definition.js";
 export * from "./document.js";
 export * from "./geometry.js";
+export * from "./series.js";
 export * from "./validate.js";
 export * from "./values.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/contracts/index.js

@@ -1,9 +1,11 @@
 export * from "./animation.js";
+export * from "./camera.js";
 export * from "./capabilities.js";
 export * from "./color.js";
 export * from "./definition.js";
 export * from "./document.js";
 export * from "./geometry.js";
+export * from "./series.js";
 export * from "./validate.js";
 export * from "./values.js";
 //# sourceMappingURL=index.js.map

package/dist/contracts/schema.js

@@ -36,15 +36,40 @@ const dataProperties = {
     step: { type: "number", exclusiveMinimum: 0 },
     accept: { type: "array", items: { type: "string", minLength: 1 } },
     control,
-    options: { type: "array" },
+    // A bare value, or `{ value, label, disabled? }`. Both forms, because a
+    // bare value means "the value is its own label" and is what every
+    // definition written before the labelled form meant.
+    options: {
+        type: "array",
+        items: {
+            anyOf: [
+                { not: { type: "object" } },
+                {
+                    type: "object",
+                    properties: {
+                        value: {},
+                        label: { type: "string", minLength: 1 },
+                        disabled: { type: "boolean" },
+                    },
+                    required: ["value", "label"],
+                    additionalProperties: false,
+                },
+            ],
+        },
+    },
 };
 const data = object(dataProperties, ["kind", "type"]);
 const output = object({ kind: dataProperties.kind, type: dataProperties.type, description }, ["kind", "type"]);
 const { kind: _kind, variadic: _variadic, ...propProperties } = dataProperties;
-const prop = object({ ...propProperties, label: { type: "string" } }, [
-    "type",
-    "default",
-]);
+const prop = object({
+    ...propProperties,
+    label: { type: "string" },
+    // Props only, not inputs: an input's value comes from whatever is wired to
+    // it, so a default expression there would be describing the wrong thing.
+    expression: { type: "string", minLength: 1 },
+    // A button that fires a named host action instead of an editable field.
+    action: { type: "string", minLength: 1 },
+}, ["type", "default"]);
 function environmentCapabilities(runsOn, capabilities) {
     return {
         if: { properties: { runsOn: { const: runsOn } } },
@@ -71,14 +96,15 @@ export const nodeDefinitionSchema = {
         props: record(prop),
     }, ["apiVersion", "runsOn"]),
     allOf: [
-        environmentCapabilities("portable", ["assets", "media"]),
-        environmentCapabilities("browser", ["assets", "media", "webgl"]),
+        environmentCapabilities("portable", ["assets", "media", "gpu"]),
+        environmentCapabilities("browser", ["assets", "media", "gpu"]),
         environmentCapabilities("server", [
             "files",
             "assets",
             "media",
             "python",
             "shell",
+            "gpu",
         ]),
     ],
 };

package/dist/contracts/series.d.ts

@@ -0,0 +1,75 @@
+import type { CascadePreset } from "./document.js";
+/**
+ * A series: one system, many instances.
+ *
+ * **A series is a graph plus an ordered list of parameter sets, and nothing
+ * else.** Plan: `Work/Projects/Cascade/plans/PLAN series.md`. The definition is
+ * deliberately this thin, because the alternative is the trap the plan names —
+ * *the series must not become a second document format.* If it grows its own
+ * copy of node state it forks from the graph and the two disagree.
+ *
+ * So there is no boundary in it. Houdini marks a region because the varying
+ * thing flows through the region as geometry; here the varying thing is a
+ * sparse map of parameter overrides keyed by node id, so the affected subgraph
+ * is **derived** from those overrides by the dependency graph that already
+ * exists. Nothing is marked, so nothing can be marked wrongly. That is also
+ * why `Block Begin`/`Block End` are not copied: they exist to serve feedback,
+ * a series has none, and the form without the feedback is all cost.
+ */
+export interface CascadeSeries {
+    readonly version: 1;
+    /**
+     * Ordered, and ordered on purpose.
+     *
+     * Independent instances do not need an order, which makes a bag tempting.
+     * But feedback — instance N reading N-1 — needs a sequence, and retrofitting
+     * order onto something built unordered is the expensive kind of change.
+     * Ordered costs nothing today. Marcus, 2026-09-08: *"feedback will at some
+     * point be useful but maybe not this series."*
+     */
+    readonly instances: readonly CascadeSeriesInstance[];
+    /** Which output the series collects, one value per instance. */
+    readonly collect: SeriesCollection;
+}
+export interface CascadeSeriesInstance {
+    /**
+     * **The record's own id, never its index in the array.**
+     *
+     * The decision the plan says to make before anything is built. A set reorders
+     * the moment a filter changes or data arrives, so a judgement pinned to a
+     * position — a favourite, an override, a note — silently becomes a different
+     * picture. For the Observatory this is the moment's id; for a wedge, the
+     * parameter tuple; for a hand-written list, whatever the author typed.
+     */
+    readonly id: string;
+    /** This instance's overrides. `CascadePreset` already is a parameter set. */
+    readonly parameters: CascadePreset;
+    /** For display. Never an address — see `id`. */
+    readonly label?: string;
+}
+/**
+ * Either a graph output by name, or any node's output port.
+ *
+ * Both, for the same reason subnets stay an ordinary tool rather than the
+ * mechanism: requiring a `cascade.core.Output` node would mean restructuring an
+ * existing graph before it could be a series, and `cloud-volumes` is exactly
+ * that case.
+ */
+export type SeriesCollection = {
+    readonly graphOutput: string;
+} | {
+    readonly nodeId: string;
+    readonly output: string;
+};
+/** One instance's result. `status` is the run's, so a failed instance is
+ *  reported rather than dropped — a series that silently renders 9,998 of
+ *  10,000 is worse than one that says which two failed. */
+export interface SeriesInstanceResult {
+    readonly id: string;
+    readonly index: number;
+    readonly status: "completed" | "cancelled" | "failed";
+    readonly value: unknown;
+    readonly diagnostics: readonly unknown[];
+    readonly durationMs: number;
+}
+//# sourceMappingURL=series.d.ts.map

package/dist/contracts/series.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=series.js.map

package/dist/contracts/validate.js

@@ -13,16 +13,16 @@ const CONTROLS = new Set(["number", "slider", "range", "int", "boolean", "text",
  * capability belongs to.
  */
 export const CAPABILITIES_BY_ENVIRONMENT = {
-    portable: ["assets", "media"],
-    browser: ["assets", "media", "webgl"],
-    server: ["files", "assets", "media", "python", "shell"],
+    portable: ["assets", "media", "gpu"],
+    browser: ["assets", "media", "gpu"],
+    server: ["files", "assets", "media", "python", "shell", "gpu"],
 };
 const ALLOWED = CAPABILITIES_BY_ENVIRONMENT;
 const fields = (names) => new Set(names.split(" "));
 const TOP_FIELDS = fields("apiVersion runsOn container capabilities label description icon inputs outputs props");
 const DATA_FIELDS = fields("kind type default description variadic min max step accept control options");
 const OUTPUT_FIELDS = fields("kind type description");
-const PROP_FIELDS = fields("type default label description min max step accept control options");
+const PROP_FIELDS = fields("type default label description min max step accept control options expression action");
 function diagnostic(code, message, path) {
     return { phase: "definition", code: `definition/${code}`, message, path };
 }
@@ -170,6 +170,22 @@ export function validateNodeDefinition(value) {
                 add("invalid-control", `${String(raw.control)} is not a Cascade control`, `${path}.control`);
             if ("options" in raw && raw.control !== "select")
                 add("options-without-select", "options require the select control", `${path}.options`);
+            // A labelled option is `{ value, label }`. Checked because the failure
+            // is cosmetic and silent: a malformed entry reaches the control and
+            // renders as "[object Object]" rather than erroring, and the labelled
+            // form exists precisely because a lost label lost a cost warning.
+            if (Array.isArray(raw.options))
+                for (const [index, option] of raw.options.entries()) {
+                    if (option === null || typeof option !== "object")
+                        continue;
+                    const entry = option;
+                    if (!("value" in entry))
+                        add("invalid-option", "a labelled option needs a value", `${path}.options[${index}]`);
+                    if (typeof entry.label !== "string" || !entry.label)
+                        add("invalid-option", "a labelled option needs a non-empty label", `${path}.options[${index}].label`);
+                    if ("disabled" in entry && typeof entry.disabled !== "boolean")
+                        add("invalid-option", "disabled must be a boolean", `${path}.options[${index}].disabled`);
+                }
             const type = raw.type;
             if (!validType(type)) {
                 add("invalid-type", `${String(type)} is not a Cascade type`, `${path}.type`);
@@ -194,6 +210,15 @@ export function validateNodeDefinition(value) {
                     !Number.isFinite(raw.step) ||
                     raw.step <= 0))
                 add("invalid-step", "step must be greater than zero", `${path}.step`);
+            if (section === "props" &&
+                "expression" in raw &&
+                (typeof raw.expression !== "string" || raw.expression.length === 0))
+                add("invalid-expression", "expression must be a non-empty string", `${path}.expression`);
+            for (const field of ["min", "max"]) {
+                if (field in raw &&
+                    (typeof raw[field] !== "number" || !Number.isFinite(raw[field])))
+                    add(`invalid-${field}`, `${field} must be a finite number`, `${path}.${field}`);
+            }
             if (typeof raw.min === "number" &&
                 typeof raw.max === "number" &&
                 raw.min > raw.max)