@field/cascade 0.8.0 → 0.11.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,29 @@ 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 })
+    // `cook`: a node's cook is a pure function of its inputs, so the server's
+    // default stage cache may serve it (see StageCachePolicy). A panel posts
+    // through its own api.runStage, without this, and is never cached unasked.
+    body: JSON.stringify({ stage, args, caller: "cook" }),
+    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 +86,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,171 @@
+# 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. Running, rendering, exporting and locks are listed under [The other commands](#the-other-commands); see also `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. Skips `renders/`, `out/`, `dist/` and `node_modules/` below it. |
+| `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`.
+
+## The other commands
+
+Running, sharing, locks and Studio. `cascade --help` has their options; `cascade render --help` and `cascade lock --help` have their own.
+
+| Command | What it does |
+| --- | --- |
+| `cascade [project-directory \| graph-file]` | Open Studio on a project or graph. |
+| `cascade new <name>` | Create a Cascade project. |
+| `cascade node <Name> [project-directory]` | Create a deterministic custom node. |
+| `cascade projects [directory]` | Show or set the default projects directory. |
+| `cascade serve start\|stop\|restart\|status\|logs\|install` | Run Studio as a managed background service. |
+| `cascade run <graph-file> [options]` | Cook a graph headlessly; `--frames` renders a sequence. |
+| `cascade render <graph-file>` | Render an animation across worker processes, then a preview video. |
+| `cascade validate <graph-file>` | Validate a graph file without executing. |
+| `cascade check <graph-file>` | Statically check node definitions, types and graph structure. |
+| `cascade inspect <graph-file>` | Every node with its classification and full definition. |
+| `cascade parity <graph-file>` | Cook headless twice and through Studio's path; report per-node differences. |
+| `cascade build <graph-file> --out <new-directory>` | A standalone browser player ([WEB_PLAYER.md](WEB_PLAYER.md)). |
+| `cascade export <graph-file> (--plan \| --out <dir>)` | The graph's published editor as a static site ([EDITOR_EXPORT.md](EDITOR_EXPORT.md)). |
+| `cascade publish <graph-file> <node>.<prop>` | Publish a node prop as an editor parameter. |
+| `cascade freeze <graph-file> <node> --fields <a,b>` | Snapshot chosen fields of a live data source for export. |
+| `cascade scene <graph-file> <scene.json> --out <new-graph-file>` | Apply a scene file to a copy of the graph. |
+| `cascade mcp [project-directory]` | Serve these commands as MCP tools over stdio ([MCP.md](MCP.md)). |
+| `cascade lock <graph-file> <node> --name <name>` | Record a render (graph, params, seeds, inputs, code) in `locks/<id>.json`. |
+| `cascade lock verify [<lock-id>...]` | Replay locks and report which still match. |
+| `cascade replay <lock-id>` | Re-render a lock from its stored code and compare fingerprints. |
+| `cascade locks` | List the project's locks. |
+| `cascade ladder <graph-file> <node> --name <name> --vary <node.prop>=<a,b,c> \| --seeds <a,b,c>` | Cook 3 to 5 variants (values zipped across params, or graph seeds) from the stored code; write `ladders/<id>/<n>.png`, a labelled contact sheet `ladders/<id>/sheet.png` and the record `ladders/<id>.json` (per variant: graph, params, seed, inputs, fingerprint; the code and git commit once). |
+| `cascade pick <ladder-id> <n> [--name <lock name>]` | At approval, write `locks/<id>.json` for variant `n` from the ladder's record, without cooking again; `cascade replay` reproduces that image pixel for pixel. |
+| `cascade help node [<type>] [--project <dir>]` | A node type's inputs, props and outputs (type, default, range, description), where it runs and its capabilities, read from the installed package or the project's `nodes/`; without a type, every node type. No repository checkout needed. |
+| `cascade doctor [project-directory] [--fix]` | What a headless run here will find: the declared Python environment, the stage interpreter, ffmpeg, the canvas. `--fix` builds the environment. See [Python for stages](#python-for-stages-cascadejson-python). |
+
+Every verb is one row in `src/cli/verbs.ts`: its usage and summary for `--help`, the handler that runs it, how it treats `--json`, and the MCP tools that call it. A new verb is a row there, its handler, and its line here (`tests/cli-verbs.test.ts` checks both this page and [MCP.md](MCP.md)).
+
+## `--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.
+
+## Outputs as files (`run --out`)
+
+`cascade run <graph> --out <dir>` copies each image output to `<dir>/<node>.<ext>`, or `<dir>/<node>.<port>.<ext>` for a node with more than one image output. With `--frames` the same names carry the frame: `<node>[.<port>].<frame>.<ext>`. Which outputs: every image output nothing downstream consumes (a `cascade.core.Null` passing an image counts), or those of `--node`; `--out-node <id>` (repeatable) adds a mid-graph node's. `--out` may be project-relative or absolute; `files` in the result is spelled the same way. `run --json` lists every image output as `data.images: [{ node, port, source, file? }]`, with or without `--out`. The MCP `cook` and `render` tools take `out` and `outNodes`.
+
+## Checks that fail a run (`cascade.assert.*`)
+
+Put the check in the graph instead of a script beside it:
+
+```sh
+cascade node add index.cascade NotBlank --name poster-not-blank --set 'message="the poster rendered empty"'
+cascade connect index.cascade render.image poster-not-blank.image
+cascade node add index.cascade cascade.assert.Range --name density-ok --set min=0.2 --set max=0.8
+cascade connect index.cascade stats.density density-ok.value
+cascade run index.cascade --json      # exit 1: { "ok": false, "error": { "message": "Assertion failed in \"density-ok\" (cascade.assert.Range): value 0.93 is outside [0.2, 0.8]." } }
+```
+
+`Range` (a finite number in `[min, max]`), `Equals` (JSON-equal to `expected`, numbers within `tolerance`), `True`, and `NotBlank` (a PNG or PPM that is not one flat colour within `tolerance`, nor fully transparent). Each passes its input through and runs when the graph runs whole, or when the `--node` you name is downstream of it. An image wired only into assertions is still saved by `--out`. Headless only for now; see `doc/NODE_REFERENCE.md`.
+
+## Debug output and environment (`.cascade/runs/`, `--env`)
+
+Every run's trace in `.cascade/runs/<time>-<graph>.json` holds, per node, what it printed while it cooked: `console.log/info/warn/error/debug` from the node, and its Python stages' stderr, as `logs: [{ level, text }]` (500 lines per node, the rest counted in `logsDropped`). `run --json` gives the same lines as `data.logs: [{ node, level, text }]`. A failed run writes its trace too, and the error ends with `Run trace: <path>`.
+
+`--env NAME=value` (repeatable) sets a variable for the run: Python stages, the warm stage worker and `cascade render`'s worker processes see it, so `CLOUD_ANALYST_ONLINE=1` no longer needs a shell prefix. The trace records the names under `env`, never the values. The MCP `cook` and `render` tools take `env: { NAME: "value" }`.
+
+## Python for stages (`cascade.json` `python`)
+
+A project whose stages import numpy or Pillow declares them, and Cascade keeps a virtual environment for it in `.cascade-cache/python/venv` (inside the project, never system-wide):
+
+```json
+{
+  "exec": { "stages": { "entrypoint": "runtime/node_cli.py" } },
+  "python": { "requirements": ["numpy", "Pillow>=10"] }
+}
+```
+
+`requirements` is a list of pip specifiers or a project-relative requirements file; `interpreter` (default `python3`) is what creates the venv. `cascade doctor` reports it as `current`, `missing` or `stale` (cascade.json changed since it was built); `cascade doctor --fix` creates or rebuilds it, moving an old one to `.cascade-cache/python/_archive/`. While one is declared, stages run under its interpreter instead of a bare `python`/`python3` in `exec.stages.python` (a project-relative executable there still wins), and a stage call with the environment missing or stale fails with the command that fixes it, rather than later on an `ImportError`. MCP: `doctor { "fix": true }`.

package/doc/EDITOR_EXPORT.md

@@ -0,0 +1,235 @@
+# 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. Add `--public` when the editor is meant to be open to
+   anyone: a readable site is then reported as intended instead of failing.
+
+## 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"],
+  "fonts": [{ "family": "DM Mono", "file": "assets/fonts/DMMono-Regular.woff2", "license": "OFL-1.1", "weight": 400 }],
+  "freeze": [{ "node": "moment", "output": "moment", "snapshot": "frozen/moment.json" }],
+  "panel": { "module": "editor/panel.ts", "placement": "extend" },
+  "inspect": true
+}
+```
+
+`fonts` ships open-licensed fonts with the site and loads them in the page
+(`@font-face`) and in the engine worker (`FontFace`), so a panel or a canvas
+that names the family draws with it. Each entry must say `"license": "OFL-1.1"`;
+anything else, or a file under `licensed/`, is refused.
+
+- **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. A node that draws ships when it uses `cascade/image`
+  (PROJECT_AUTHORING.md, "Draw an image in any host"); fonts and images it
+  reads must be shipped files (`editor.assets`, `editor.fonts`, frozen files).
+- 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