@field/cascade 0.7.1 → 0.10.0

package/dist/runtime/seed.js

@@ -0,0 +1,52 @@
+/**
+ * Seeds: one number per graph, one derived number per node, the same in every
+ * host.
+ *
+ * A node that wants randomness gets `context.seed` and `context.random` from
+ * whichever host cooks it — the headless runtime here, Studio through its
+ * definition adapter — and both compute them with these functions. So the
+ * same graph draws the same dots headless and in Studio, and changing the
+ * graph's `seed` reshuffles every node at once while each keeps its own
+ * stream (doc/PRODUCTION_READINESS.md, item 5).
+ *
+ * The node id is part of the derivation, not its position: ids are stable
+ * across edits, so adding a node never reshuffles its neighbours.
+ */
+/** The graph seed when a document does not state one. */
+export const DEFAULT_GRAPH_SEED = 0;
+/** A document's `seed`, as an unsigned 32-bit integer; the default when absent
+ *  or not an integer. */
+export function graphSeed(document) {
+    const value = document?.seed;
+    return typeof value === "number" && Number.isInteger(value) ? value >>> 0 : DEFAULT_GRAPH_SEED;
+}
+/**
+ * A node's seed: FNV-1a over `<graph seed>:<node id>`, finished with
+ * MurmurHash3's avalanche so neighbouring ids give unrelated seeds.
+ */
+export function nodeSeed(seedOfGraph, nodeId) {
+    const text = `${seedOfGraph >>> 0}:${nodeId}`;
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < text.length; index++) {
+        hash ^= text.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    hash ^= hash >>> 16;
+    hash = Math.imul(hash, 0x85ebca6b);
+    hash ^= hash >>> 13;
+    hash = Math.imul(hash, 0xc2b2ae35);
+    hash ^= hash >>> 16;
+    return hash >>> 0;
+}
+/** Mulberry32: a small, fast stream of floats in [0, 1) from one seed. */
+export function seededRandom(seed) {
+    let state = seed >>> 0;
+    return () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let value = state;
+        value = Math.imul(value ^ (value >>> 15), value | 1);
+        value ^= value + Math.imul(value ^ (value >>> 7), value | 61);
+        return ((value ^ (value >>> 14)) >>> 0) / 0x1_0000_0000;
+    };
+}
+//# sourceMappingURL=seed.js.map

package/dist/runtime/types.d.ts

@@ -100,6 +100,18 @@ export interface RunOptions {
     readonly frame?: number;
     /** Frames per second, for `$FPS` and for `$T`. Default 30. */
     readonly fps?: number;
+    /**
+     * Keep the outputs of nodes whose inputs and props did not change since
+     * their last cook, instead of cooking the whole selection again. For hosts
+     * that re-run on every edit, such as an exported editor.
+     *
+     * `"strict"` also cooks every node downstream of one that cooked: equal
+     * inputs are not trusted when they come from a node that just ran, because
+     * a node that writes a fixed path and outputs the same path string would
+     * otherwise leave its consumers on the previous file. `cascade run
+     * --frames` uses it, so a frame re-cooks only what that frame changed.
+     */
+    readonly reuse?: boolean | "strict";
 }
 export interface RunResult {
     readonly runId: string;

package/dist/stage.js

@@ -1,5 +1,18 @@
 // server/src/runtime/stage.ts
 var BRIDGE_KEY = "__cascadeStageBridge";
+var COOK_SIGNAL_KEY = "__cascadeCookSignal";
+function ambientCookSignal() {
+  const read = globalThis[COOK_SIGNAL_KEY];
+  if (typeof read !== "function") return void 0;
+  const signal = read();
+  return signal ?? void 0;
+}
+function cancelledError(stage, signal) {
+  const reason = signal.reason instanceof Error ? signal.reason.message : "superseded";
+  const error = new Error(`stage "${stage}" was cancelled: ${reason}`);
+  error.name = "AbortError";
+  return error;
+}
 function installStageBridge(bridge) {
   const globals = globalThis;
   const previous = globals[BRIDGE_KEY];
@@ -36,18 +49,26 @@ async function capability() {
   if (token === null) throw new Error("Cascade exec capability is unavailable (404)");
   return token;
 }
-async function overHttp(stage, args) {
+async function overHttp(stage, args, signal) {
   const postStage = async () => fetch("/api/exec", {
     method: "POST",
     headers: { "Content-Type": "application/json", "X-Cascade-Exec-Capability": await capability() },
-    body: JSON.stringify({ stage, args })
+    body: JSON.stringify({ stage, args }),
+    signal
   });
-  let response = await postStage();
-  if (response.status === 403) {
-    capabilityPromise = void 0;
+  let response;
+  let body;
+  try {
     response = await postStage();
+    if (response.status === 403) {
+      capabilityPromise = void 0;
+      response = await postStage();
+    }
+    body = await response.json();
+  } catch (error) {
+    if (signal?.aborted) throw cancelledError(stage, signal);
+    throw error;
   }
-  const body = await response.json();
   if (!response.ok || !body.ok) {
     throw new Error(`stage "${stage}" failed: ${body.stderr || body.error || "unknown error"}`);
   }
@@ -62,20 +83,30 @@ async function stageAvailable() {
   if (typeof document === "undefined") return false;
   return await discoverCapability() !== null;
 }
-async function runStage(stage, args = {}) {
+async function runStage(stage, args = {}, options = {}) {
+  const signal = options.signal ?? ambientCookSignal();
+  if (signal?.aborted) throw cancelledError(stage, signal);
   const bridge = localBridge();
-  if (bridge) return await bridge(stage, args);
+  if (bridge) {
+    try {
+      return await bridge(stage, args, signal ? { signal } : void 0);
+    } catch (error) {
+      if (signal?.aborted) throw cancelledError(stage, signal);
+      throw error;
+    }
+  }
   if (typeof document === "undefined") {
     throw new Error(
       `Cannot run stage "${stage}": no host bridge is installed and there is no page to post from. A headless host must call installStageBridge() from cascade/stage before executing the graph.`
     );
   }
-  return overHttp(stage, args);
+  return overHttp(stage, args, signal);
 }
 function cachePath(nodeId, suffix) {
   return `.cascade-cache/${nodeId.replace(/[^a-zA-Z0-9_-]/g, "_")}${suffix}`;
 }
 export {
+  COOK_SIGNAL_KEY,
   cachePath,
   installStageBridge,
   runStage,

package/dist/studio/panel.d.ts

@@ -78,6 +78,8 @@ export interface ProjectPanelApi {
    * through the series API instead.
    */
   cook(options?: { readonly nodeId?: string }): Promise<void>;
+  /** Open the Agent panel with a draft for the user to review and send. */
+  openAgent(prompt: string): void;
   selectedNodeId(): string | null;
   readonly sourceNodeId: string | null;
   readonly signal: AbortSignal;

package/doc/CLI_REFERENCE.md

@@ -0,0 +1,100 @@
+# CLI reference: editing graphs
+
+Everything an agent needs to build or change a `.cascade` graph without hand-editing JSON. Each command is one graph concept (node, wire, parameter, subnet), checks the edit with the same code as `cascade check`, and writes the file atomically. For running, rendering and exporting, see `cascade --help`, `doc/EDITOR_EXPORT.md` and `doc/WEB_PLAYER.md`.
+
+## The guarantees
+
+- **Minimal diffs.** Only the keys an edit is about change. Node ids are stable, untouched nodes keep their place, a new key goes where Studio would write it, and the file keeps its own formatting: Studio's compact arrays, or plain `json.dump` indentation with `1.0` and `—` left as they were. An edit followed by its inverse leaves the file byte-identical (`tests/graph-edit.test.ts`).
+- **Tidy placement.** A new node waits in a lane beside the graph until it is wired; the first `connect` moves it one step along the existing flow from its neighbour, beside anything already there. Studio flows top to bottom, and a graph laid out some other way (cloud-plots' diagonal stages) is followed instead. `--no-layout` leaves positions alone; `--at x,y` places a node exactly.
+- **Closed subnets.** No wire crosses a subnet boundary directly. Connecting across one, moving nodes in or out, or grouping nodes routes the wire through the subnet's `Input` and `Output` nodes, named after what they carry (`motif-out-geometry`), reusing one that already carries the same value and removing one that is no longer used.
+- **Refused, not broken.** An edit that would make `cascade check` fail (a cycle, a wrong type, a misspelt parameter, a value of the wrong type) is refused and nothing is written. A graph that already failed can still be repaired one edit at a time: only new failures count. A file that changed on disk while the edit ran (Studio saved, another agent wrote) is not overwritten.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `cascade graph create <graph> [--name <title>]` | A new empty graph. Never overwrites. |
+| `cascade graph read <graph> [--in <subnet>]` | Nodes with stored parameters, subnets with their ports, wires as `a.out -> b.in`. |
+| `cascade graph list [dir]` | Every `.cascade` under a directory, with node and wire counts. |
+| `cascade node add <graph> <type> [--name <id>] [--in <subnet>] [--set k=v]... [--at x,y] [--comment <text>]` | Add a node. `<type>` is a module id or a short name: `Circle` is `cascade.geo.Circle`, `InkVocabulary` is `project.InkVocabulary`. The id defaults to the type in kebab case (`copy-to-points`, then `copy-to-points-2`). |
+| `cascade node rm <graph> <node> [--recursive]` | Remove a node and its wires. A subnet with children needs `--recursive`. |
+| `cascade connect <graph> <node.output> <node.input> [--no-layout]` | Wire two ports. A port can be left off when the node has one on that side. An input that was fed is rewired, and the old wire is reported. |
+| `cascade disconnect <graph> <node.output> <node.input>` | Remove that wire. With one argument, `<node.input>` removes whatever feeds it, `<node.output>` everything it feeds. |
+| `cascade set <graph> <node.param> <value>` | Store a value, read by the parameter's declared type: `0.5`, `true`, `640,480`, `#f4f1ea`, `"300"`. A value equal to the default is not stored. |
+| `cascade set <graph> <node.param> --expr '<e>'` / `--clear-expr` | Bind or remove an expression (`$T * 0.1`). Props only. |
+| `cascade set <graph> <node.param> --key 0=1 --key 120=1.4 [--interp linear]` / `--remove-key 120` | Set or remove keyframes on the prop's channel. Interpolation is `constant`, `linear` or `smooth` (the default). |
+| `cascade set <graph> <node.param> --unset` | Forget the stored value and its bindings. |
+| `cascade subnet create <graph> <node>... [--name <id>] [--label <text>]` | Group sibling nodes. The subnet takes the place of the first of them in the flow. |
+| `cascade subnet move <graph> <node>... --to <subnet\|root>` | Move sibling nodes into a subnet or out to the top level, rewiring at each boundary. |
+| `cascade subnet dissolve <graph> <subnet>` | Lift the nodes back out and remove the subnet. The inverse of `create`. |
+| `cascade edit <graph> <operations.json \| ->` | A batch, all or nothing. Each operation is the JSON below. |
+
+Every edit takes `--dry-run` (check, write nothing) and `--json`.
+
+## `--json`, on every command
+
+Every command, not only the editing ones, prints one envelope on stdout and nothing else:
+
+```json
+{ "ok": true, "data": { "file": "/…/index.cascade", "changed": true, "results": [
+  { "op": "set", "node": "render", "param": "strokeWidth", "field": "props", "before": 2, "after": 3 } ] },
+  "warnings": [] }
+{ "ok": false, "error": { "message": "render has no parameter \"strokewidth\"; props: size, filename, …" }, "warnings": [] }
+```
+
+`data` is the command's structured result where it has one (the editing commands, `inspect`, `run`, `parity`), and `{ "output": [lines] }` for a command that only prints. What a command warns becomes `warnings`. The exit code is 0 for `ok` and 1 otherwise. `run --json` puts its manifest in `data`: the status, the seed, the path of the run trace in `.cascade/runs/`, the frames and files with `--frames`, and `stages`, one entry per Python stage call with its node, key and cache state (`hit`, `miss`, `off` and why). `parity --json` puts its report in `data`, with `data.ok` false when outputs differ; see [Seeds and parity](PROJECT_AUTHORING.md#seeds-and-parity).
+
+## Operations, for `cascade edit` and the MCP server
+
+```json
+[
+  { "op": "node.add", "module": "Circle", "id": "dot", "in": "motif", "set": { "radius": [0.2, 0.2] } },
+  { "op": "connect", "from": "dot.geometry", "to": "copy.source" },
+  { "op": "disconnect", "from": "a.out", "to": "b.in" },
+  { "op": "set", "target": "render.opacity", "keys": [{ "frame": 0, "value": 0 }, { "frame": 48, "value": 1 }], "interpolation": "linear" },
+  { "op": "set", "target": "render.strokeWidth", "expression": "1 + $T * 0.1" },
+  { "op": "node.remove", "id": "old", "recursive": false },
+  { "op": "subnet.create", "nodes": ["a", "b"], "label": "Motif" },
+  { "op": "subnet.move", "nodes": ["c"], "to": "root" },
+  { "op": "subnet.dissolve", "id": "motif" }
+]
+```
+
+Values in operations are JSON values, used as given and checked against the declared type.
+
+## The TypeScript API
+
+The CLI and the MCP server are thin layers over one API, so a script can use it directly:
+
+```ts
+import { GraphFile } from './src/cli/graphFile.js';
+
+const graph = await GraphFile.open('index.cascade');
+await graph.apply({ op: 'node.add', module: 'Circle', id: 'dot' });
+await graph.apply({ op: 'connect', from: 'dot.geometry', to: 'render.scene' });
+const { results, warnings } = await graph.save();
+```
+
+The editor itself (`GraphEditor`, `readGraph`, the operation types) is environment-neutral and exported from `@field/cascade/runtime`: it edits a parsed document in memory and asks a callback for node definitions, so a browser host can use the same code.
+
+## A graph built from nothing
+
+```sh
+cascade graph create index.cascade --name "Built from the CLI"
+cascade node add index.cascade Circle --set radius=0.18,0.18 --set divisions=6
+cascade node add index.cascade Rectangle --set size=2,2
+cascade node add index.cascade CopyToPoints
+cascade connect index.cascade circle copy-to-points.source
+cascade connect index.cascade rectangle copy-to-points.target
+cascade subnet create index.cascade circle rectangle copy-to-points --label Motif
+cascade node add index.cascade Transform --set rotate=0.4
+cascade connect index.cascade copy-to-points transform.geometry     # routed out through motif-out-geometry
+cascade node add index.cascade Camera
+cascade node add index.cascade Render --set size=800,800 --set strokeWidth=3 --set 'background=#f4f1ea'
+cascade connect index.cascade transform render.scene
+cascade connect index.cascade camera render.camera
+cascade set index.cascade render.opacity --key 1=0.25 --key 48=1 --interp linear
+cascade check index.cascade && cascade run index.cascade --frames 1 --json
+```
+
+Opened in Studio, the top level reads `motif → transform → render`, with the camera beside `transform`, and `motif` holds the circle and rectangle side by side above `copy-to-points` and its output.

package/doc/EDITOR_EXPORT.md

@@ -0,0 +1,226 @@
+# Shareable editors
+
+`cascade export` turns a graph into a small static website: a viewer, the
+parameters you chose to publish, presets, scene files and export buttons. Send
+the link to someone and they can change your scene, make new ones and send them
+back, without Studio, an account or a server.
+
+## The boundary: what leaves the project
+
+An export is an allowlist. Read this before sharing anything.
+
+- **Only the selected subgraph ships.** That is the nodes your published
+  outputs and parameters depend on. Every other node, all annotations and
+  comments, and the graph's metadata stay home. `--plan` lists both sides.
+- **Only selected assets ship.** These are the files in `editor.assets`, the
+  literal files a shipped prop points at, and the files of frozen snapshots.
+  Nothing else is copied: not the project directory, `.cascade-cache`,
+  credentials or Python environments.
+- **Live data sources never ship.** A node that reads Observatory, a CLI, a
+  cache, body data, the filesystem or a network is live. That means a
+  `runsOn: 'server'` node, a node declaring `files`, `python` or `shell`, or a
+  node declaring `source: 'live'`. Freeze it with `cascade freeze` into a
+  snapshot of exactly the fields you name (one photo and a title, say). The
+  export ships the snapshot in place of the node and drops everything upstream.
+  If a live source is still wired in, the export fails and names it.
+- **Personal fields are flagged.** Field names that look like notes,
+  transcripts, calendar, body or health data, locations or contacts are marked
+  PERSONAL in the plan, and so is any field you pass to `--personal`. Nothing is
+  frozen unless you name it, so the default is the minimum.
+- **Licensed, hidden and ignored files are refused.** These are anything under
+  a `licensed/` directory, dotfiles such as `.env`, and anything git ignores.
+  Licensed fonts are dropped into the editor by the person using it. They are
+  read in their browser and never uploaded or bundled.
+- **The built site is scanned before it is written.** The export stops if the
+  site contains Turso/libSQL URLs, tokens, API keys, private keys, JWTs,
+  `/Users/…`, `/home/…` or `~/` paths, Observatory endpoints, your home
+  directory, or the value of any secret-looking environment variable or
+  project `.env` entry.
+- **The site makes no external calls.** It has no analytics. Its
+  `vercel.json` sets a Content Security Policy that only allows its own
+  origin, and it is marked noindex.
+- **Scenes carry values, not project data.** A scene holds published parameter
+  values and the files the person dropped. A file parameter marked
+  `embed: "never"` (a licensed font) records only its name, size and SHA-256.
+
+Every export writes `export-manifest.json`, listing each file, its size and
+its source, each frozen field, and every PERSONAL flag. `cascade export --plan`
+prints the same manifest without building anything.
+
+## Make a graph shareable in 5 steps
+
+1. **Publish the parameters** someone else may change:
+
+   ```sh
+   cascade publish index.cascade spec.capMm --label "Cap height" --group Type --min 3 --max 60 --unit mm
+   ```
+
+   This adds an entry to the graph's `editor.parameters`. In Studio, the
+   `share` toggle beside a parameter in the Inspector does the same, with
+   label, group and range fields. You can also edit the JSON directly (see the
+   format below).
+
+2. **Declare the outputs.** Add them to `editor.outputs`: one with `view: true`
+   is shown in the viewer, and each one gets an export button (`png`, `svg`,
+   `json` or `text`). Name the parameters that belong beside a button (dpi,
+   ground) in its `parameters`.
+
+3. **Freeze any live source** on the published path. Name exactly the fields to
+   keep:
+
+   ```sh
+   cascade freeze index.cascade moment --output moment --fields photos[0],instant --personal instant
+   ```
+
+   This writes `frozen/moment.json` plus any files those fields refer to.
+   Review them and commit them.
+
+4. **Review the plan.** Check the nodes, files and PERSONAL flags:
+
+   ```sh
+   cascade export index.cascade --plan
+   ```
+
+5. **Build, and deploy if you want to:**
+
+   ```sh
+   cascade export index.cascade --out export/site
+   cascade export index.cascade --out export/site --deploy vercel --project my-editor --scope field-io
+   ```
+
+   `--out` replaces only a previous export. `--deploy vercel` links in a scratch
+   directory, so no `.env.local` can land in the site. It deploys to
+   production, then checks that an anonymous request to
+   `https://<project>.vercel.app` is refused. If it is not, it says to turn on
+   Vercel Authentication.
+
+## The `editor` section
+
+It sits beside `nodes` in the `.cascade` file. The runtime ignores it, and
+Studio keeps it verbatim when it saves. The types are in
+`packages/contracts/src/editor.ts`.
+
+```json
+"editor": {
+  "id": "cloud-type",
+  "title": "Cloud Type",
+  "groups": ["Input", "Focus", "Export"],
+  "parameters": [
+    { "id": "text", "node": "type-set", "prop": "text", "label": "Text", "group": "Input", "control": "textarea" },
+    { "id": "font", "node": "type-set", "prop": "font", "control": "file", "accept": [".otf", ".ttf"], "embed": "never",
+      "help": "Drop your licensed font. It stays in your browser." },
+    { "id": "angle", "node": "focus", "prop": "angle", "control": "slider", "min": -90, "max": 90, "unit": "°",
+      "visibleWhen": { "param": "field", "equals": "tilt" } },
+    { "id": "seed", "node": "spec", "prop": "seed", "control": "seed" }
+  ],
+  "outputs": [
+    { "id": "preview", "node": "preview-svg", "port": "svg", "format": "svg", "view": true },
+    { "id": "png", "node": "png", "port": "image", "format": "png", "parameters": ["dpi", "pngGround"] }
+  ],
+  "presets": [
+    { "id": "soft", "label": "Soft", "values": { "strength": 1 }, "keep": ["colour", "font"] }
+  ],
+  "assets": ["assets/fonts/InterDisplay-Medium.otf"],
+  "freeze": [{ "node": "moment", "output": "moment", "snapshot": "frozen/moment.json" }],
+  "panel": { "module": "editor/panel.ts", "placement": "extend" },
+  "inspect": true
+}
+```
+
+- **Parameter `id`** is the key a scene uses. It survives renaming the node
+  or the prop, so keep it stable.
+- **`control`** is one of `number`, `slider`, `int`, `bool`, `select`
+  (`options`, bare or `{ value, label }`), `text`, `textarea`, `color`, `file`
+  (`accept`, `embed`), `seed` (with a Reroll button) and `vec2`. If omitted,
+  it comes from the prop's type.
+- **`visibleWhen`** takes `{ param, equals | in | not }`, or a list of them
+  that must all hold.
+- **Presets** set the values they name and reset everything else to the graph's
+  value, except the ids listed in `keep`. The editor also offers "Graph
+  defaults".
+- **`panel`** is optional project code for the editor. It exports
+  `mount(target, api)` and may return a disposer. The `api` has `get`, `set`,
+  `values`, `subscribe` and `output`. A Svelte component works if the project
+  has `svelte` installed, because the export compiles `.svelte` imports with
+  the project's own compiler. `replace` hides the generated parameters.
+- **Inspect** shows every stage and each of its outputs, read-only: geometry
+  drawn, images and SVG shown, and anything else as JSON.
+- **`peek`** lists the parameter ids a phone keeps in reach at the bottom
+  sheet's lowest snap point, such as `["text", "seed"]`. By default these are
+  the first text and seed parameters.
+- **`draft`** sets values that are cooked while someone drags a slider on a
+  phone, such as `{ "density": 0.5 }`. The preview is quicker during the drag,
+  and the real values cook again on release. Draft values never reach a scene
+  or an export.
+
+## On a phone
+
+The same export works on a phone without any extra setup. The preview fills the
+top of the screen. Pinch to zoom, drag to pan, and double-tap to fit. The
+controls sit in a bottom sheet with a handle and three snap points (peek, half
+and full), and the groups start folded. Every control is at least 44 px with
+16 px text, and numbers have − and + steppers. The header shrinks to the title
+and a ⋯ menu, which holds the presets, the scene buttons, Inspect stages, the
+exports and the last cook time. A pulsing dot shows the graph is cooking. Exports and
+saved scenes open the share sheet (Save to Files, Photos, AirDrop) and fall back to a
+download. File controls open the file picker. In landscape, the controls move to a side
+panel. Desktop is unchanged.
+
+## Scene files
+
+A scene is what someone saved in an editor (`*.scene.json`):
+
+```json
+{
+  "format": "cascade.scene",
+  "version": 1,
+  "graph": { "id": "cloud-type", "version": "h77d97e88f213c05d" },
+  "name": "Derya, cover v2",
+  "values": { "text": "CLOUD\nOBSERVATORY", "strength": 0.3, "seed": 11 },
+  "files": {
+    "font":  { "name": "HelveticaNowDisplay-Md.otf", "size": 81234, "sha256": "…" },
+    "image": { "name": "sky.png", "mediaType": "image/png", "size": 50211, "sha256": "…", "data": "<base64>" }
+  },
+  "savedAt": "2026-10-11T15:00:00Z"
+}
+```
+
+- **`graph.version`** is a hash of the editor id, the parameter interface and
+  the structure of the exported subgraph. Tuning a value in Studio leaves it
+  unchanged. Rewiring the graph or renaming a published parameter changes it.
+- **A mismatch degrades rather than failing.** Another version or editor id is
+  a warning. Unknown parameters are ignored with a warning. A value of the
+  wrong kind is skipped with a warning. Missing parameters take the graph's
+  values.
+- **Files:** a file up to 2 MB is embedded unless its parameter says
+  `embed: "never"`. A referenced file is matched by name and hash. In the
+  editor, that is a file the person dropped before in the same browser. In
+  Studio or the CLI, it is a file of that name under `assets/` (including
+  `assets/fonts/licensed/`) or `licensed/`. If no match is found, the graph's
+  file is kept and the person is told what to supply.
+
+**Where scenes open:**
+
+- **Exported editor:** "Open scene…" and "Save scene", or drop a
+  `.json` file on the viewer.
+- **Studio:** File › Open Scene… applies a scene to the open graph as an
+  unsaved edit. Embedded files go into the project's `assets/`. File › Save
+  Scene… writes one.
+- **CLI:**
+  - `cascade scene index.cascade s.scene.json --out new.cascade` writes a copy of the graph with the scene applied.
+  - `cascade run index.cascade --scene s.scene.json --write preview-svg.svg=out.svg` renders with a scene and writes a chosen output.
+
+The same scene gives byte-identical output in the editor and under `cascade run`.
+
+## Limits
+
+- Only browser-runnable definition-v1 nodes ship. Python, shell and dynamic
+  nodes are listed together as "not exportable". Port them to TypeScript, or
+  freeze their output.
+- The editor cooks in a module worker. Unchanged stages are reused
+  (`run({ reuse: true })`), so only the stages after an edit re-cook, and the
+  page stays responsive while they do. Values cross to the page by structured
+  clone; a value that cannot be cloned is shown as a description.
+- In Studio, a parameter's `share` toggle in the Inspector publishes it, with
+  label, group and range fields. Presets, outputs, `visibleWhen` and help text
+  are still edited with `cascade publish` or in the JSON.

package/doc/HEADLESS_GPU.md

@@ -109,6 +109,33 @@ It does not encode PNGs or perform colour conversion. Encode through the existin
 image/IO host and publish an `image` value. Graph-wide texture transport, HDR
 readback, and browser video uploads are outside this first implementation.
 
+## Determinism
+
+A render pass is repeatable on one adapter: draws, and the blending between
+them, are applied in submission order. `cascade parity` checks it
+(`tests/parity-gpu.test.ts` draws 400 alpha-blended triangles and gets the same
+bytes headless twice and through Studio's executor on Dawn). Three things break
+it, and each has a fix:
+
+- **Unordered float accumulation.** WGSL has integer atomics only, so a
+  Cascade compute shader cannot add floats atomically; accumulate in fixed
+  point (`atomicAdd` on `u32`/`i32` of a scaled value), which adds the same in
+  any order. The same hazard outside WGSL is the one that hit cloud-plots:
+  PyTorch's `index_add` on MPS adds floats with atomics, and on 12 Oct a
+  colliding scatter gave 40 different sums in 40 runs while fixed point gave
+  one. The fix there is the same (`src/cloud_plots/detsplat.py` in cloud-plots, opt-in per graph with
+  the `deterministic` prop).
+- **Unsynchronised writes.** Two invocations writing one texel or buffer
+  element without a barrier or atomic leave whichever lands last.
+- **A different adapter.** Rasterisation rules, `fma` contraction and
+  transcendental precision differ between GPUs and between Dawn and a browser's
+  WebGPU. Studio in a browser is a different adapter from headless Dawn, so
+  compare those with a tolerance: `cascade parity --tolerance <0-255>` counts a
+  channel difference up to that value as the same and still reports it.
+
+Render into `rgba8unorm`, state the blend state on every pipeline rather than
+relying on a default, and seed anything random from `context.seed`.
+
 ## Verification and limits
 
 ```sh

package/doc/MCP.md

@@ -0,0 +1,53 @@
+# MCP server
+
+`cascade mcp [project-directory]` serves the CLI as MCP tools over stdio, so an agent calls `set` instead of shelling out and parsing text. The tools are the CLI's commands under the same names, and every result is the same `--json` envelope (`{ ok, data, warnings }`, or `{ ok: false, error, warnings }` with `isError` set). Graph paths are relative to the project directory and may not leave it.
+
+## Set it up in Claude Code
+
+From the project directory:
+
+```sh
+claude mcp add cascade -- npx --no-install cascade mcp .
+```
+
+Or in the project's `.mcp.json`, so every session in the project has it:
+
+```json
+{
+  "mcpServers": {
+    "cascade": { "command": "npx", "args": ["--no-install", "cascade", "mcp", "."] }
+  }
+}
+```
+
+With a global install (`npm i -g @field/cascade`), use `"command": "cascade", "args": ["mcp", "."]`. The tools then appear as `mcp__cascade__set`, `mcp__cascade__render` and so on.
+
+## Tools
+
+| Tool | CLI equivalent |
+| --- | --- |
+| `graph_list`, `graph_read`, `graph_create` | `cascade graph list \| read \| create` |
+| `node_add`, `node_remove` | `cascade node add \| rm` |
+| `connect`, `disconnect` | `cascade connect \| disconnect` |
+| `set` | `cascade set` (value, `expression`, `keys`, `removeKeys`, `interpolation`, `unset`) |
+| `subnet_create`, `subnet_move`, `subnet_dissolve` | `cascade subnet create \| move \| dissolve` |
+| `edit` | `cascade edit` (a batch of operations, all or nothing) |
+| `check`, `inspect` | `cascade check \| inspect` |
+| `cook` | `cascade run <graph> [--node <id>]` |
+| `render` | `cascade run <graph> --frames … [--fps] [--out] [--node]… [--scene]` |
+| `export` | `cascade export <graph> --plan \| --out <dir>` |
+| `lock`, `replay`, `locks` | `cascade lock <graph> <node> --name`, `cascade replay <id> [--live]`, `cascade locks` |
+
+The editing tools take `dryRun`. Reads and edits run inside the server through the same functions the CLI commands call. Cooking, rendering, checking and exporting run `cascade <command> --json` as a child process, so a long render leaves nothing behind in the server and returns exactly what the CLI would print. Calls run one at a time, so two edits to one file never interleave.
+
+## A session
+
+```text
+graph_read   { "graph": "index.cascade" }
+node_add     { "graph": "index.cascade", "type": "Transform", "set": { "rotate": 0.4 } }
+connect      { "graph": "index.cascade", "from": "motif.output_0", "to": "transform.geometry" }
+set          { "graph": "index.cascade", "target": "render.opacity", "keys": [{ "frame": 1, "value": 0.25 }, { "frame": 48, "value": 1 }] }
+render       { "graph": "index.cascade", "frames": "1-48", "out": "renders/check" }
+```
+
+See `doc/CLI_REFERENCE.md` for what each operation guarantees about diffs, placement and subnet boundaries.

package/doc/NODE_REFERENCE.md

@@ -79,6 +79,24 @@ Runs on `portable`.
 | `result` | `any` |  |  |
 | `history` | `array` |  |  |
 
+### `cascade.core.Frozen`
+
+Frozen — Emits a frozen snapshot of a data source's chosen values
+
+Runs on `portable`.
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `value` | `any` | `null` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `value` | `any` |  |  |
+
 ### `cascade.core.Input`
 
 Input — Defines a public graph or subnet input
@@ -173,6 +191,54 @@ Runs on `portable`.
 | --- | --- | --- | --- |
 | `output` | `any` |  |  |
 
+### `cascade.core.Pack`
+
+Pack — Collects inputs into a bundle, one named field each
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `inputs` | `any` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `names` | `string` | `""` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `bundle` | `bundle` |  |  |
+
+### `cascade.core.Pick`
+
+Pick — Reads one field of a bundle
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `bundle` | `bundle` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `field` | `string` | `""` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `value` | `any` |  |  |
+
 ### `cascade.core.Previous`
 
 Previous — The previous step's state, inside a Feedback container. The first step gets the container's initial value.