@field/cascade 0.2.22 → 0.3.1

package/dist/runtime/types.d.ts

@@ -1,5 +1,5 @@
-import type { AssetCapability, AssetRef, CascadeAbortSignal, CascadeDocument, CascadePreset, Diagnostic, FileCapability, ImageRef, JsonValue, MediaCapability, NodeDefinition, NodeExecute, ProgressReporter, PythonCapability, SerializableValue, ShellCapability, TextureHandle, WebGLCapability } from "cascade/contracts";
-export type { CascadeDocument, CascadeDocumentAnnotation, CascadeDocumentConnection, CascadeDocumentNode, CascadePreset, } from "cascade/contracts";
+import type { AssetCapability, AssetRef, CascadeAbortSignal, CascadeDocument, CascadePreset, Diagnostic, FileCapability, ImageRef, JsonValue, MediaCapability, NodeDefinition, NodeExecute, ProgressReporter, PythonCapability, SerializableValue, ShellCapability, TextureHandle, GpuCapability } from "@field/cascade/contracts";
+export type { CascadeDocument, CascadeDocumentAnnotation, CascadeDocumentConnection, CascadeDocumentNode, CascadePreset, } from "@field/cascade/contracts";
 export interface DefinitionNodeRegistration<D extends NodeDefinition = NodeDefinition> {
     readonly kind: "definition-v1";
     readonly moduleId: string;
@@ -31,7 +31,7 @@ export interface RuntimeCapabilities {
     readonly assets?: AssetCapability;
     readonly media?: MediaCapability;
     readonly python?: PythonCapability;
-    readonly webgl?: WebGLCapability;
+    readonly gpu?: GpuCapability;
     readonly shell?: ShellCapability;
     readonly serverBridge?: ServerBridgeCapability;
 }
@@ -88,6 +88,18 @@ export interface RunOptions {
     readonly target?: RunTarget;
     readonly signal?: CascadeAbortSignal;
     readonly runId?: string;
+    /**
+     * The frame to resolve animated parameters at — a keyframe channel is
+     * sampled here and `$F`/`$FF`/`$T` are derived from it. Fractional frames
+     * are kept. Omitted leaves the graph on the frame it is already on.
+     *
+     * A value the caller states rather than a clock the runtime reads: same
+     * graph plus same frame gives the same output, which is what makes an
+     * offline render reproducible.
+     */
+    readonly frame?: number;
+    /** Frames per second, for `$FPS` and for `$T`. Default 30. */
+    readonly fps?: number;
 }
 export interface RunResult {
     readonly runId: string;
@@ -163,13 +175,13 @@ export type RuntimeEvent = {
     readonly runId: string;
     readonly nodeId: string;
     readonly inputName: string;
-    readonly event: import("cascade/contracts").TriggerEvent;
+    readonly event: import("@field/cascade/contracts").TriggerEvent;
 } | {
     readonly type: "trigger:delivered";
     readonly runId: string;
     readonly nodeId: string;
     readonly inputName: string;
-    readonly event: import("cascade/contracts").TriggerEvent;
+    readonly event: import("@field/cascade/contracts").TriggerEvent;
 } | {
     readonly type: "node:output";
     readonly runId: string;
@@ -203,6 +215,12 @@ export interface CascadeRuntime {
 }
 export interface LoadedCascadeGraph {
     readonly state: GraphState;
+    /**
+     * Host-aware static gate: the diagnostics `run` would raise before executing
+     * anything, collected instead of thrown. This is what lets a validator see a
+     * missing capability, which is a fault it was previously blind to.
+     */
+    preflight(): readonly Diagnostic[];
     inspect(): GraphInspection;
     setInput(nodeId: string, inputName: string, value: unknown): Promise<void>;
     setGraphInput(name: string, value: unknown): Promise<void>;
@@ -213,6 +231,14 @@ export interface LoadedCascadeGraph {
         runId?: string;
     }>): Promise<RunResult>;
     run(options?: RunOptions): Promise<RunResult>;
+    /**
+     * Move the graph's clock without cooking. Animated parameters re-resolve
+     * immediately, so `inspect()` reports them at this frame.
+     */
+    setFrame(frame: number): void;
+    setFps(fps: number): void;
+    getFrame(): number;
+    getFps(): number;
     cancel(reason?: string): void;
     subscribe(listener: (event: RuntimeEvent) => void): () => void;
     getOutput(nodeId: string, outputName: string): unknown;
@@ -220,7 +246,7 @@ export interface LoadedCascadeGraph {
     getOutputs(nodeId: string): ReadonlyMap<string, unknown>;
     dispose(): Promise<void>;
 }
-export interface NodeRuntimeHostOptions extends Omit<RuntimeCapabilities, "webgl"> {
+export interface NodeRuntimeHostOptions extends Omit<RuntimeCapabilities, "gpu"> {
     readonly modules: RuntimeHost["modules"];
     readonly legacyShell?: LegacyShellBindingFactory & Readonly<{
         kind: "server-direct";

package/dist/shell.d.ts

@@ -3,6 +3,6 @@ export {
   type ShellProcessErrorKind,
   type ShellRunOptions,
   type ShellRunResult,
-} from 'cascade/contracts';
-export declare function run(command: string, args?: readonly string[], options?: import('cascade/contracts').ShellRunOptions): Promise<import('cascade/contracts').ShellRunResult>;
-export declare function runJson<T = unknown>(command: string, args?: readonly string[], options?: import('cascade/contracts').ShellRunOptions): Promise<T>;
+} from '@field/cascade/contracts';
+export declare function run(command: string, args?: readonly string[], options?: import('@field/cascade/contracts').ShellRunOptions): Promise<import('@field/cascade/contracts').ShellRunResult>;
+export declare function runJson<T = unknown>(command: string, args?: readonly string[], options?: import('@field/cascade/contracts').ShellRunOptions): Promise<T>;

package/doc/NODE_REFERENCE.md

@@ -0,0 +1,395 @@
+# Node reference
+
+**Generated by `scripts/build-node-reference.mjs`. Do not edit — regenerate it.**
+
+Read this before searching the codebase for what a node does. It exists because
+that search is expensive and this file is not: the whole catalogue below is under
+8,000 characters, and working it out by reading source cost one agent about twenty
+tool calls, two of which were the same 1,676-line file.
+
+For the `.cascade` document format, expressions, and how to write a node, see
+`AGENTS.md`. **Note in particular that anything time-based is an expression
+rather than a node** — `sin($T) * 40` in a parameter — so there is no oscillator
+node and none is needed.
+
+## Deterministic nodes, with full declarations
+
+These are definition-v1: their declarations are literal, so what follows is
+exact rather than a description.
+
+### `cascade.core.Input`
+
+Input — Defines a public graph or subnet input
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `value` | `any` | `null` |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `inputIndex` | `int` | `0` |  |
+| `inputName` | `string` | `""` |  |
+| `dataType` | `string` | `"any"` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `output` | `any` |  |  |
+
+### `cascade.core.Merge`
+
+Merge — Collects inputs into an array
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `inputs` | `any` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `append` | `bool` | `false` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `output` | `array` |  |  |
+
+### `cascade.core.Null`
+
+Null — Passes its input through unchanged
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `input` | `any` | `null` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `output` | `any` |  |  |
+
+### `cascade.core.Output`
+
+Output — Defines a public graph or subnet output
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `input` | `any` | `null` |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `outputIndex` | `int` | `0` |  |
+| `outputName` | `string` | `""` |  |
+| `dataType` | `string` | `"any"` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `output` | `any` |  |  |
+
+### `cascade.core.Random`
+
+Random — Generate a deterministic unit value from an explicit seed.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `seed` | `int` | `0` |  |
+| `sample` | `int` | `0` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `value` | `float` |  |  |
+
+### `cascade.core.Remap`
+
+Remap — Map a number from one range into another.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `value` | `float` | `0` |  |
+| `inMin` | `float` | `0` |  |
+| `inMax` | `float` | `1` |  |
+| `outMin` | `float` | `0` |  |
+| `outMax` | `float` | `1` |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `clamp` | `bool` | `false` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `result` | `float` |  |  |
+
+### `cascade.core.Select`
+
+Select — Selects an array item by index
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `array` | `array` | `[]` |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `index` | `int` | `0` |  |
+| `wrap` | `bool` | `true` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `item` | `any` |  |  |
+| `count` | `int` |  |  |
+
+### `cascade.core.Subnet`
+
+Subnet — Contains a nested deterministic graph
+
+Runs on `portable`.
+
+### `cascade.core.Switch`
+
+Switch — Selects one input by index
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `inputs` | `any` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `index` | `int` | `0` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `output` | `any` |  |  |
+
+### `cascade.geo.Circle`
+
+Circle — A closed circle, as one cubic Bezier chain or as a polygon of divisions segments.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `center` | `vec2` | `[0,0]` |  |
+| `radius` | `vec2` | `[1,1]` |  |
+| `divisions` | `int` | `32` |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `type` | `string` | `"bezier"` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `geometry` | `geometry` |  |  |
+
+### `cascade.geo.CopyToPoints`
+
+Copy to Points — Instance one geometry onto every point of another.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `source` | `geometry` |  |  |
+| `target` | `geometry` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `targetGroup` | `string` | `""` |  |
+| `useTargetOrientations` | `bool` | `true` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `geometry` | `geometry` |  |  |
+
+### `cascade.geo.Merge`
+
+Merge — Concatenate geometries, taking the union of their attributes.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `inputs` | `geometry` |  |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `geometry` | `geometry` |  |  |
+
+### `cascade.geo.Rectangle`
+
+Rectangle — A closed four-point polygon, counter-clockwise from bottom-left.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `size` | `vec2` | `[1,1]` |  |
+| `center` | `vec2` | `[0,0]` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `geometry` | `geometry` |  |  |
+
+### `cascade.geo.SvgExport`
+
+SVG Export — Write geometry as an SVG document, one group element per group.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `geometry` | `geometry` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `filename` | `string` | `"geometry.svg"` |  |
+| `width` | `float` | `0` |  |
+| `height` | `float` | `0` |  |
+| `margin` | `float` | `0` |  |
+| `stroke` | `color` | `[0,0,0,1]` |  |
+| `strokeWidth` | `float` | `1` |  |
+| `opacity` | `float` | `1` | 0…1 |
+| `fillMode` | `string` | `"none"` |  |
+| `fill` | `color` | `[1,1,1,1]` |  |
+| `pointRadius` | `float` | `0.5` |  |
+| `precision` | `int` | `3` | 0…15 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `svg` | `string` |  |  |
+| `asset` | `asset` |  |  |
+
+### `cascade.geo.Transform`
+
+Transform — Translate, rotate and scale geometry about a pivot.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `geometry` | `geometry` |  |  |
+| `translate` | `vec2` | `[0,0]` |  |
+| `rotate` | `float` | `0` |  |
+| `scale` | `vec2` | `[1,1]` |  |
+| `pivot` | `vec2` | `[0,0]` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `geometry` | `geometry` |  |  |
+
+## Studio node libraries
+
+Class-based nodes, available in Studio. Their parameters are declared in the
+class rather than in a literal, so they are listed here by name only — select
+one in Studio and read the **Definition** panel for its ports, or open the class
+under `src/nodes/<library>/nodes/`.
+
+### Core — `cascade.core.*`
+
+**Routing.** `Switch` (Switch between multiple inputs by index), `Merge` (Combine multiple inputs into an array), `Null` (Pass an input through unchanged)
+
+**Utility.** `Random` (Generate a deterministic value from a seed), `Remap` (Map a number from one range into another), `Select` (Pick an item from an array by index), `Freeze` (Capture and lock a value)
+
+**Network.** `Subnet` (Network container for organizing nodes), `Input` (External input to a subnet), `Output` (Defines subnet output)
+
+### Geometry — `cascade.geo.*`
+
+**Geometry.** `cascade.geo.Rectangle` (A closed four-point polygon, counter-clockwise from bottom-left.), `cascade.geo.Circle` (A closed circle, as one cubic Bezier chain or as a polygon of divisions segments.), `cascade.geo.Transform` (Translate, rotate and scale geometry about a pivot.), `cascade.geo.Merge` (Concatenate geometries, taking the union of their attributes.), `cascade.geo.CopyToPoints` (Instance one geometry onto every point of another.), `cascade.geo.SvgExport` (Write geometry as an SVG document, one group element per group.)
+
+### Image — `cascade.image.*`
+
+**Create.** `Image` (Load images from files), `Color` (Create a solid color canvas), `Checkers` (Generate a checkerboard pattern), `Noise` (Generate procedural noise patterns), `Ramp` (Generate color ramps), `Text` (Render text with customizable font and style)
+
+**Filter.** `Blur` (Gaussian blur), `NormalMap` (Compute normal map from height map)
+
+**Transform.** `Transform` (2D rotation, translation, and scaling), `Resize` (Scale or resize an image)
+
+**Composite.** `Composite` (Blend two images together)
+## A project's own nodes
+
+Not listed here, because they belong to the project rather than to Cascade. Ask
+the running server: `GET /api/nodes` returns each module with its `runsOn` and
+icon, and `GET /api/nodes/<name>/index.ts` returns its source.

package/doc/PROJECT_AUTHORING.md

@@ -37,6 +37,7 @@ The portable project shape is:
 my-artwork/
 ├── cascade.json
 ├── index.cascade
+├── AGENTS.md            # written by `cascade new`, for agents working in the project
 ├── nodes/
 ├── panels/              # optional Studio-only extensions
 ├── assets/
@@ -153,6 +154,19 @@ The proxy accepts HTTPS only, refuses undeclared hosts, strips caller-supplied a
 
 ## Add a custom node
 
+Before writing one, check whether you need one. A parameter can hold an expression, so anything time-based is usually a parameter rather than a node. See [Animate a parameter](#animate-a-parameter). A node earns its place when it produces geometry or pixels, or when several parameters share a computation. The built-in library is listed in `NODE_REFERENCE.md`, generated from the definitions themselves; read that before searching for what a node does.
+
+There are two styles. Write **definition-v1** for anything new; the dynamic style is what existing project nodes use and it still cooks everywhere.
+
+| | Cooked by | Checked by |
+| --- | --- | --- |
+| **definition-v1**: a literal `definition` plus `execute(context)` | the deterministic runtime through `cascade run`, and Studio, which builds the ports from the literal | `cascade check`, which requires this style |
+| **dynamic**: `execute(node, graph)` declaring its own ports and parameters | Studio, and `cascade run` including `--frames` | `cascade validate` and a cook |
+
+Studio cooks both, and a Studio graph may mix them. `cascade run` picks one host per document: a graph whose project modules are all definition-v1 runs through the deterministic runtime, and anything else runs through the compatibility engine — which is also why `--frames` is refused on an all-definition-v1 graph, the deterministic runtime owning its own clock. The `AGENTS.md` that `cascade new` writes into a project states which style that project expects, and it is the file to believe over this one for a specific project.
+
+### definition-v1
+
 Create `nodes/Multiply/index.ts`. The directory name defines the module ID `project.Multiply`.
 
 ```ts
@@ -177,7 +191,62 @@ export function execute(context: NodeExecutionContext<typeof definition>) {
 }
 ```
 
-The definition is the complete static interface. Cascade and code agents can inspect it without importing the module, build the node UI, validate graph connections, and type-check `execute`. Do not create ports, props, or types inside `execute`.
+The definition is the complete static interface. Cascade and code agents can inspect it without importing the module, build the node UI, validate graph connections, and type-check `execute`. In this style `execute` computes and nothing else: it does not create ports, props, or types.
+
+Parameters are declared as `props`, beside `inputs` and `outputs`, and each takes a `type` and a `default` plus optional `label`, `description`, `min`, `max`, `step`, `control`, `options`, and `accept`:
+
+```ts
+export const definition = {
+  apiVersion: 1,
+  label: 'Blend',
+  runsOn: 'portable',
+  inputs: { value: { kind: 'data', type: 'float', default: 0 } },
+  props: { blend: { type: 'float', default: 0.5, min: 0, max: 1, label: 'Blend' } },
+  outputs: { result: { kind: 'data', type: 'float' } }
+} as const satisfies NodeDefinition;
+```
+
+#### Prefer the vector types
+
+Anything with an x and a y is **one** `vec2`, not two floats. `vec3` and `vec4` likewise, with `vec2i`, `vec3i` and `vec4i` for integer counts and pixel sizes. Positions, offsets, sizes, scales, resolutions and colours with alpha are single ports.
+
+```ts
+// Two props that are really one value
+props: { offset_x: { type: 'float', default: 0 }, offset_y: { type: 'float', default: 0 } }
+
+// One prop the type system understands
+props: { offset: { type: 'vec2', default: [0, 0] } }
+```
+
+The reason is not tidiness. Two floats cannot connect to a `vec2` output, take two Inspector rows instead of one control, need two keyframes to animate one movement, and allow a graph to carry an x without its y. The type system knows what a `vec2` is; nothing tells it that `offset_x` and `offset_y` belong together.
+
+Keep them separate only when the components differ in kind or in range — a `width` and a `depth` that mean different things are two props, not a `vec2`.
+
+### dynamic
+
+A dynamic module declares its interface imperatively, inside `execute`, which runs once to discover the interface and again on every cook. There is no `definition` export; `runsOn` and `icon` are plain exports.
+
+```ts
+import { saveImage, cachePath } from 'cascade/io';
+
+export const icon = 'Circle';        // a Lucide icon name
+export const runsOn = 'portable';    // 'portable' | 'browser' | 'server'
+
+export async function execute(node: any) {
+  const size = node.param('size', 1024, { min: 16, max: 4096, step: 16, type: 'int' }).value;
+  const input = node.in('value', 0, { type: 'float' }).value;
+  const out = node.out('image', 'param', { type: 'image' });
+
+  const canvas = new OffscreenCanvas(size, size);
+  // ... draw ...
+  const path = await saveImage(canvas, cachePath(node.id, '.png'));
+  out.setValue({ path, size: [size, size], channels: 'rgb', depth: 'u8', space: 'srgb' });
+}
+```
+
+`param()` is a method on the node the engine hands to `execute`, not an import. It is re-declared on every cook, so it never resets a value, an expression, or a keyframe someone set: reading `.value` gives the *resolved* value for the current frame, whichever of the three bindings is in force. Top-level statements outside `execute` do not run, because the loader imports a real ES module and needs the `execute` export.
+
+Prefer `new OffscreenCanvas(width, height)` to `document.createElement('canvas')` when both hosts could run the node, and keep `runsOn: 'browser'` for code that genuinely needs the page. Web technology comes first, meaning Canvas 2D, WebGL and WebGPU. A Python stage is for work that cannot run in a browser at all, such as an exotic ML library. A Python stage costs a process spawn and a round trip per cook, which is invisible on one still frame and fatal to dragging a parameter or playing an animation.
 
 Choose the narrowest execution locus:
 
@@ -231,8 +300,65 @@ Keep implementation nodes behind that boundary so a server or custom frontend
 does not depend on internal IDs. A child Input/Output node's index defines the
 matching `input_N`/`output_N` port on its parent Subnet.
 
-Portable nodes must not read ambient time or randomness. Pass frame/time through
-root inputs and use seeded Random when a procedural stage needs variation.
+Portable nodes must not read ambient time or randomness. Time reaches a node as
+an expression or a keyframe on a parameter, or through a root input; variation
+comes from seeded `Random`.
+
+`NODE_REFERENCE.md` carries the full declarations for these and for the
+`cascade.geo.*` set, generated from the definitions, so the table above is a
+summary rather than the source.
+
+## Animate a parameter
+
+A parameter holds up to three things, and they resolve in one order: a **keyframe channel** first, then an **expression**, then the stored **value**. A channel therefore overrides an expression without erasing it: empty the channel and the expression comes back.
+
+Expressions use Houdini's variables:
+
+| | |
+| --- | --- |
+| `$F` | frame, integer |
+| `$FF` | frame, fractional |
+| `$T` | seconds, zero on the first frame — `($FF - 1) / $FPS` |
+| `$FPS` | rate |
+| `ch("NODE/parm")`, `ch("./parm")` | read another parameter; `chs()` for a string, `chv()` for a vector |
+
+The maths library is in scope bare, so `sin(x)` rather than `Math.sin(x)`, with `PI`, `TAU` and `E`. Note that **angles are radians**; `sind`, `cosd`, `tand`, `radians()` and `degrees()` are there for formulae carried over from Houdini. `fit`, `fit01`, `clamp`, `lerp`, `smooth`, `noise`, `random`, `padzero`, `opexist` and `opinput` are available too.
+
+So "oscillate the angle" is `sin($T) * 40` in the `angle` parameter. There is no oscillator node and none is needed. Only `ch()`, `chs()` and `chv()` create a dependency, so a parameter that reads another one recooks when it changes.
+
+Keyframes are set on a parameter in the Inspector: **alt-click** sets a key at the playhead, **ctrl-click** deletes the key on the current frame, **right-click** opens the Timeline focused on that channel, and the diamond beside the parameter toggles a key for anyone not using a modifier. Interpolation belongs to the key on the left of a segment and is `constant`, `linear`, or `smooth`. Smooth is the default: a Hermite curve with automatic tangents, flat at the first and last key. Outside the keyed range the channel holds its end values.
+
+In the document, a channel sits in the node's `props` next to the value and the expression, and `interpolation` is omitted where it is the `smooth` default:
+
+```json
+"props": {
+  "angle": {
+    "value": 12,
+    "expression": "sin($T) * 40",
+    "channel": { "keys": [{ "frame": 1, "value": 0, "interpolation": "linear" }, { "frame": 48, "value": 360 }] }
+  }
+}
+```
+
+`params` holds plain values; a binding needs the object form under `props`. Playback settings, the frame range and loop, belong to the Timeline panel and are not saved with the document.
+
+## Run a coding agent in the project
+
+Studio can run a coding agent in the project directory, editing the same `nodes/` and `.cascade` files the open graph came from. The document is saved before the prompt is sent, and a watcher reloads the graph in place when the agent rewrites it, so nothing needs a page reload. Studio declines that reload while there are unsaved edits rather than choosing a winner.
+
+The project decides what may be launched, in `cascade.json`, using the same `commands` allowlist as shell aliases. A scaffolded project ships without one, so nothing is launchable until it is added:
+
+```json
+{
+  "name": "My Artwork",
+  "commands": { "claude": "claude" },
+  "agent": { "claude": { "args": ["--permission-mode", "acceptEdits"] } }
+}
+```
+
+An alias maps to an absolute path, a `~`-relative path, or a bare name on `PATH`; project-relative paths are refused. `agent.<alias>.args` adds fixed flags. `claude` defaults to `--permission-mode acceptEdits`, and an explicit empty array launches it bare. The routes are only available on loopback or in an explicitly enabled trusted-host session.
+
+The run belongs to the server rather than the browser: closing the tab leaves the agent working, and reopening the panel replays the buffered transcript and rejoins the stream. Node and parameter names are drag sources carrying their expression address, `TRANSFORM` for a node and `TRANSFORM/tx` for its parameter, so a path can be dragged into the console instead of retyped.
 
 ## Integrate external services and AI
 
@@ -344,6 +470,22 @@ cascade inspect index.cascade
 cascade run index.cascade
 ```
 
+`cascade check` reads definition-v1 modules statically; `cascade validate` checks the document, hierarchy and connections. Neither renders anything, so a green read proves the graph loads and not that it draws. Check a change by running it.
+
+Render frames offline with the same command:
+
+```bash
+cascade run index.cascade --frames 1-100
+cascade run index.cascade --frames 1-100x2 --fps 25 --out frames
+cascade run index.cascade --frames 42 --entry-node logo-1024
+```
+
+`--frames` takes a range, a stepped range, or a single frame, and refuses a range it cannot parse rather than repairing it. Files are written as `<out>/<node id>.<frame>.<ext>`, zero-padded to at least four digits, into `renders/` unless `--out` says otherwise. One rule whether the graph has one output or three. Every image output with nothing connected downstream is saved, or the outputs of `--entry-node` when one is named. Cascade stops at the image sequence; a directory of numbered frames is what an encoder takes.
+
+Offline, drawing goes through Skia: the optional `@napi-rs/canvas` supplies `OffscreenCanvas`, `Image`, `Path2D` and the rest as globals in the Node process, deliberately not `document`, because that is how a node tells which host it is in. This is why a node that draws on an `OffscreenCanvas` needs no second implementation for headless runs, and why the built-in `cascade.image.*` nodes render under `cascade run` as well as in Studio. A graph that draws nothing runs without the renderer installed.
+
+`--frames` renders dynamic graphs. A definition-v1 graph runs through the deterministic runtime, which owns its own clock and has no parameter animation, and the flag is refused rather than silently rendering the first frame repeatedly.
+
 Applications can use `createRuntime()` from `cascade/runtime` directly. Register node modules and host capabilities, load the graph, mutate inputs or presets, run or trigger it, read outputs, then dispose it. This path loads no Svelte or Studio code and works in a backend service or a custom browser application.
 
 Server and browser hosts are deliberately explicit. A graph that uses Python or shell stages belongs on the server or behind an application-defined bridge; the runtime does not silently move computation between environments.
@@ -353,8 +495,8 @@ Server and browser hosts are deliberately explicit. A graph that uses Python or
 Before committing a custom node or graph:
 
 1. Type-check the project with its normal TypeScript command.
-2. Run `cascade validate <graph>` and `cascade check <graph>` to check the document plus static definitions, types, hierarchy, and connections without rendering.
-3. Run the graph headlessly when its capabilities are available.
+2. Run `cascade validate <graph>`, and `cascade check <graph>` for a definition-v1 project, to check the document plus static definitions, types, hierarchy, and connections without rendering.
+3. Run the graph headlessly when its capabilities are available. This is the step that catches a document that loads, reports its nodes, and draws nothing. The characteristic failure here is silent, so a static pass alone proves little.
 4. Open Studio only for visual inspection or authoring that benefits from the graph UI.
 
-Treat warnings about legacy dynamic nodes as migration work. New nodes should always use deterministic definitions.
+Dynamic modules are not deprecated and 0.3.0 stopped calling them legacy: the two styles are cooked by different hosts, and a project's own `AGENTS.md` says which one it expects. Convert a node when you need what the other style gives, static inspection and `cascade check` on one side or Studio cooking and `--frames` on the other, rather than on a schedule.