@field/cascade 0.11.0 → 0.12.0

package/dist/runtime/runtime.js

@@ -1,11 +1,11 @@
-import { bundleFieldType, bundleSchemasCompatible, bundleValueProblem, canConnectTypes, isBundleValue, selectBundleFields, suggestName, unknownFieldMessage, validateNodeDefinition, } from "@field/cascade/contracts";
+import { bundleFieldType, bundleSchemasCompatible, bundleValueProblem, canConnectTypes, Color, isBundleValue, selectBundleFields, suggestName, unknownFieldMessage, validateNodeDefinition, } from "@field/cascade/contracts";
 import { CascadeRuntimeError } from "./error.js";
 import { builtinNodeRegistrations } from "./builtins/index.js";
 import { deserializeChannel, isEmptyChannel } from "./animation/channel.js";
 import { PropAnimator, isBoundProp } from "./params/index.js";
 import { bundleFieldReferences, parseBundleFieldPath, remoteBundlePath, } from "./expressions/bundlePaths.js";
 import { DEFAULT_FPS, MIN_FRAME } from "./expressions/time.js";
-import { isGpuHost } from "./gpu.js";
+import { gpuLimitShortfall, isGpuHost } from "./gpu.js";
 import { DEFAULT_GRAPH_SEED, graphSeed, nodeSeed, seededRandom } from "./seed.js";
 /**
  * Preflight codes that describe something other than "this graph cannot run
@@ -113,16 +113,23 @@ class MutableAbortSignal {
     }
 }
 export function createRuntime(options) {
-    return new Runtime(options.host, [...builtinNodeRegistrations, ...(options.nodes ?? [])]);
+    return new Runtime(options.host, [...builtinNodeRegistrations, ...(options.nodes ?? [])], {
+        values: options.values === "trust" ? "trust" : "freeze",
+        concurrency: Math.max(1, Math.floor(Number(options.concurrency ?? 1)) || 1),
+        ...(options.nodeScope ? { nodeScope: options.nodeScope } : {}),
+    });
 }
+const SERIAL_EXECUTION = { values: "freeze", concurrency: 1 };
 class Runtime {
     host;
+    execution;
     registrations = new Map();
     graphs = new Set();
     sealed = false;
     disposed = false;
-    constructor(host, registrations) {
+    constructor(host, registrations, execution = SERIAL_EXECUTION) {
         this.host = host;
+        this.execution = execution;
         for (const registration of registrations)
             this.registerNode(registration);
     }
@@ -166,7 +173,7 @@ class Runtime {
         const connections = (document.connections ?? []).map((connection, index) => materializeConnection(connection, index, byId));
         validateCardinality(byId, connections);
         validateTopology(nodes, connections);
-        const graph = new Graph(this.host, nodes, connections, () => this.graphs.delete(graph), document.annotations, graphSeed(document));
+        const graph = new Graph(this.host, nodes, connections, () => this.graphs.delete(graph), document.annotations, graphSeed(document), this.execution);
         // The graph's own frame rate, saved with it; a run's `fps` still overrides.
         const fps = document.timeline?.fps;
         if (typeof fps === "number" && Number.isFinite(fps) && fps > 0)
@@ -188,6 +195,7 @@ class Graph {
     connections;
     onDispose;
     seed;
+    execution;
     graphState = "ready";
     byId;
     dataConnectionsByInput;
@@ -213,14 +221,20 @@ class Graph {
     animator;
     frame = MIN_FRAME;
     fps = DEFAULT_FPS;
+    /** What happens to a value a node hands over; see `RuntimeValuePolicy`. */
+    values;
     constructor(host, nodes, connections, onDispose, annotations = [], 
     /** The document's seed; each node's `context.seed` derives from it. */
-    seed = DEFAULT_GRAPH_SEED) {
+    seed = DEFAULT_GRAPH_SEED, 
+    /** Value policy, concurrency, node scope; see `CreateRuntimeOptions`. */
+    execution = SERIAL_EXECUTION) {
         this.host = host;
         this.nodes = nodes;
         this.connections = connections;
         this.onDispose = onDispose;
         this.seed = seed;
+        this.execution = execution;
+        this.values = execution.values;
         this.byId = new Map(nodes.map((node) => [node.id, node]));
         const byInput = new Map();
         const byNode = new Map();
@@ -316,7 +330,7 @@ class Graph {
                     type: definition.kind === "trigger" ? "trigger" : definition.type,
                     connected: this.connectedOutputs.has(`${node.id}\0${name}`),
                     ...(definition.kind === "data" && node.outputs.has(name)
-                        ? { value: snapshot(node.outputs.get(name)) }
+                        ? { value: this.expose(node.outputs.get(name)) }
                         : {}),
                 },
             ])),
@@ -479,7 +493,15 @@ class Graph {
         return () => this.listeners.delete(listener);
     }
     getOutput(nodeId, outputName) {
-        return snapshot(this.requireNode(nodeId).outputs.get(outputName));
+        return this.expose(this.requireNode(nodeId).outputs.get(outputName));
+    }
+    /**
+     * An output value as callers see it. Under `"freeze"` every output was
+     * deep-frozen when it was set, so this is the value itself (the snapshot is
+     * a lookup); under `"trust"` it is handed out as the producer made it.
+     */
+    expose(value) {
+        return this.values === "trust" ? value : snapshot(value);
     }
     getGraphOutput(name) {
         const node = this.graphOutputs.get(name);
@@ -490,7 +512,7 @@ class Graph {
     getOutputs(nodeId) {
         return immutableMap([...this.requireNode(nodeId).outputs].map(([name, value]) => [
             name,
-            snapshot(value),
+            this.expose(value),
         ]));
     }
     dispose() {
@@ -578,19 +600,23 @@ class Graph {
             const ordered = topological(this.nodes, this.connections).filter((node) => initial.includes(node) && !insideFeedback.has(node.id));
             /** Nodes that cooked in this run, for `reuse: "strict"`. */
             const cooked = new Set();
-            for (const node of ordered) {
-                if (signal.aborted)
-                    break;
-                if (reuse && this.reusable(node) && !(reuse === "strict" && this.feedsFrom(node, cooked))) {
-                    this.emit({ type: "node:start", runId, nodeId: node.id });
-                    this.emit({ type: "node:complete", runId, nodeId: node.id });
-                    continue;
+            const skip = (node) => !!reuse && this.reusable(node) && !(reuse === "strict" && this.feedsFrom(node, cooked));
+            if (this.execution.concurrency > 1)
+                await this.cookConcurrently(ordered, runId, signal, enqueue, skip, cooked);
+            else
+                for (const node of ordered) {
+                    if (signal.aborted)
+                        break;
+                    if (skip(node)) {
+                        this.emit({ type: "node:start", runId, nodeId: node.id });
+                        this.emit({ type: "node:complete", runId, nodeId: node.id });
+                        continue;
+                    }
+                    await this.executeNode(node, runId, signal, {}, enqueue);
+                    cooked.add(node.id);
+                    if (!signal.aborted)
+                        node.lastCook = this.cookKey(node);
                 }
-                await this.executeNode(node, runId, signal, {}, enqueue);
-                cooked.add(node.id);
-                if (!signal.aborted)
-                    node.lastCook = this.cookKey(node);
-            }
             if (injection && !signal.aborted)
                 enqueue(injection.nodeId, injection.inputName, injection.payload, {
                     kind: "external",
@@ -628,7 +654,90 @@ class Graph {
             this.active = undefined;
         }
     }
+    /**
+     * The run's main order with up to `concurrency` nodes cooking at once.
+     *
+     * Nodes START strictly in topological order: the next node starts once
+     * everything it reads has completed and a slot is free, and nothing later
+     * in the order overtakes it. So the `node:start` events — and a run trace
+     * built from them — come in the same order as a serial run on every run;
+     * only completions interleave. A Kahn order puts siblings side by side (the
+     * morph's four renders are adjacent), which is where the overlap is.
+     *
+     * A feedback container, a node with trigger ports and a GPU node cook
+     * alone: their state (the carried step, the trigger queue's sequence, one
+     * device) is ordered by the serial loop and not worth sharing.
+     *
+     * On a failure nothing new starts, the nodes already cooking finish, and
+     * the failure earliest in the order is the run's, so the message does not
+     * depend on which stage happened to answer first.
+     */
+    async cookConcurrently(ordered, runId, signal, enqueue, skip, cooked) {
+        const position = new Map(ordered.map((node, index) => [node.id, index]));
+        const needs = new Map();
+        for (const dependency of graphDependencies(this.nodes, this.connections)) {
+            if (!position.has(dependency.sourceId) || !position.has(dependency.targetId))
+                continue;
+            const list = needs.get(dependency.targetId) ?? [];
+            list.push(dependency.sourceId);
+            needs.set(dependency.targetId, list);
+        }
+        const done = new Set();
+        const running = new Map();
+        let exclusiveRunning = false;
+        let failure;
+        let next = 0;
+        for (;;) {
+            while (!failure &&
+                !signal.aborted &&
+                !exclusiveRunning &&
+                next < ordered.length &&
+                running.size < this.execution.concurrency) {
+                const node = ordered[next];
+                if (!(needs.get(node.id) ?? []).every((id) => done.has(id)))
+                    break;
+                const alone = cooksAlone(node);
+                if (alone && running.size)
+                    break;
+                next++;
+                if (skip(node)) {
+                    this.emit({ type: "node:start", runId, nodeId: node.id });
+                    this.emit({ type: "node:complete", runId, nodeId: node.id });
+                    done.add(node.id);
+                    continue;
+                }
+                if (alone)
+                    exclusiveRunning = true;
+                const index = position.get(node.id);
+                const task = this.executeNode(node, runId, signal, {}, enqueue).then(() => {
+                    cooked.add(node.id);
+                    if (!signal.aborted)
+                        node.lastCook = this.cookKey(node);
+                    done.add(node.id);
+                }, (error) => {
+                    if (!failure || index < failure.index)
+                        failure = { index, error };
+                }).finally(() => {
+                    running.delete(node.id);
+                    if (alone)
+                        exclusiveRunning = false;
+                });
+                running.set(node.id, task);
+            }
+            if (!running.size)
+                break;
+            await Promise.race(running.values());
+        }
+        if (failure)
+            throw failure.error;
+    }
     async executeNode(node, runId, signal, triggers, enqueue) {
+        const scope = this.execution.nodeScope;
+        if (!scope)
+            return this.cookNode(node, runId, signal, triggers, enqueue);
+        return scope(node.id, () => this.cookNode(node, runId, signal, triggers, enqueue));
+    }
+    async cookNode(node, runId, signal, triggers, enqueue) {
         this.emit({ type: "node:start", runId, nodeId: node.id });
         /**
          * `cascade.core.Previous` reads the carried state off its container, the
@@ -710,7 +819,7 @@ class Graph {
                     const definition = node.definition.outputs?.[name];
                     if (!definition || definition.kind !== "data")
                         continue;
-                    const value = outputValue(response.outputs[name], definition, `${node.id}.${name}`);
+                    const value = outputValue(response.outputs[name], definition, `${node.id}.${name}`, this.values);
                     node.outputs.set(name, value);
                     this.emit({
                         type: "node:output",
@@ -739,7 +848,7 @@ class Graph {
                     }),
                 }
                 : {
-                    set: (value) => pendingData.set(name, outputValue(value, definition, `${node.id}.${name}`)),
+                    set: (value) => pendingData.set(name, outputValue(value, definition, `${node.id}.${name}`, this.values)),
                 },
         ]));
         const capabilityEntries = [];
@@ -747,7 +856,11 @@ class Graph {
             const installed = this.host.capabilities[name];
             if (name === "gpu" && isGpuHost(installed)) {
                 await installed.ensure();
-                capabilityEntries.push([name, installed.forNode(node.id)]);
+                const gpu = installed.forNode(node.id);
+                const shortfall = gpuLimitShortfall(node.id, node.definition.gpuLimits, gpu);
+                if (shortfall)
+                    throw new Error(shortfall);
+                capabilityEntries.push([name, gpu]);
             }
             else {
                 capabilityEntries.push([
@@ -801,12 +914,14 @@ class Graph {
             if (pendingData.has(name)) {
                 const value = pendingData.get(name);
                 node.outputs.set(name, value);
+                // The stored value is already frozen (or trusted), so the event
+                // carries it as is rather than a fresh copy nobody may read.
                 this.emit({
                     type: "node:output",
                     runId,
                     nodeId: node.id,
                     outputName: name,
-                    value: snapshot(value),
+                    value: this.expose(value),
                 });
             }
         for (const emitted of pendingTriggers)
@@ -1262,7 +1377,8 @@ class Graph {
             }
             return Object.freeze({
                 result: carried,
-                history: Object.freeze(history),
+                // Recorded as settled, so reading `history` back is not a copy.
+                history: settle(history),
             });
         }
         finally {
@@ -1406,7 +1522,10 @@ function materialize(authored, registration) {
         const object = saved && typeof saved === "object" && "value" in saved
             ? saved
             : null;
-        const value = runtimeValue(object ? object.value : saved, definition.type, false, `${authored.id}.${name}`);
+        const stored = object ? object.value : saved;
+        const value = runtimeValue(
+        // A colour saved as `{ r, g, b }` by the class image nodes reads as one.
+        definition.type === "color" ? Color.upgrade(stored) : stored, definition.type, false, `${authored.id}.${name}`);
         props[name] = value;
         // A stored plain value is an author's decision and beats the declared
         // default expression, so any binding seeded above has to go.
@@ -1702,6 +1821,18 @@ function snapshotRegistration(registration) {
     const definition = snapshot(registration.definition);
     return Object.freeze({ ...registration, definition });
 }
+/** A node `cookConcurrently` never overlaps with another; see there. */
+function cooksAlone(node) {
+    if (node.definition.container === "feedback")
+        return true;
+    if (node.definition.capabilities?.includes("gpu"))
+        return true;
+    const ports = [
+        ...Object.values(node.definition.inputs ?? {}),
+        ...Object.values(node.definition.outputs ?? {}),
+    ];
+    return ports.some((port) => port.kind === "trigger");
+}
 function isGated(node) {
     return Object.values(node.definition.inputs ?? {}).some((input) => input.kind === "trigger");
 }
@@ -1882,7 +2013,103 @@ function misuse(code, message) {
     throw runtimeError(code, message);
 }
 function snapshot(value) {
-    return cloneValue(value, new WeakSet());
+    const clone = cloneValue(value, new WeakSet());
+    if (clone !== null && typeof clone === "object")
+        settled.add(clone);
+    return clone;
+}
+/**
+ * Plain arrays and objects already checked and deep-frozen — by `cloneValue`
+ * or `settle` — so a second snapshot of the same value is a lookup, not a
+ * copy. A runtime value is read far more often than it is made: the producer
+ * sets it once, then the event, `getOutputs`, `finish` and `inspect` each
+ * used to clone it again (a 1M-point array four times a frame).
+ *
+ * Only roots and containers of objects are recorded; a leaf of primitives
+ * (a `[x, y]` point) is cheaper to re-walk than to record a million times.
+ */
+const settled = new WeakSet();
+/** Plain containers copied by `cloneValue`, for the copy-count tests. */
+let copiedContainers = 0;
+/** How many plain arrays/objects the runtime has copied in this process. */
+export function runtimeValueCopies() {
+    return copiedContainers;
+}
+function isPlainContainer(value) {
+    if (Array.isArray(value))
+        return true;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function checkScalar(value) {
+    if (typeof value === "number" && !Number.isFinite(value))
+        misuse("runtime/non-serializable-value", "Runtime numbers must be finite");
+    if (typeof value === "function" ||
+        typeof value === "symbol" ||
+        typeof value === "bigint")
+        misuse("runtime/non-serializable-value", `Runtime values cannot contain ${typeof value}`);
+}
+/**
+ * Check a value a node handed over and deep-freeze it where it stands: the
+ * same rules as `cloneValue` (finite numbers, no functions, no cycles, class
+ * instances and typed arrays passed through untouched), without allocating.
+ * The producer gave it away with `set()`; freezing is what keeps the
+ * consumers' view of it from changing under them.
+ */
+function settle(value) {
+    if (value === null || typeof value !== "object") {
+        checkScalar(value);
+        return value;
+    }
+    if (!settled.has(value) && isPlainContainer(value)) {
+        settleContainer(value, new WeakSet());
+        settled.add(value);
+    }
+    return value;
+}
+/** Returns whether `value` held any plain container (and so was recorded). */
+function settleContainer(value, ancestors) {
+    let nested = false;
+    const visit = (item) => {
+        if (item === null || typeof item !== "object") {
+            checkScalar(item);
+            return;
+        }
+        if (settled.has(item) || !isPlainContainer(item))
+            return;
+        if (ancestors.has(item))
+            misuse("runtime/non-serializable-value", "Runtime values cannot contain cycles");
+        if (!nested) {
+            nested = true;
+            ancestors.add(value);
+        }
+        if (settleContainer(item, ancestors))
+            settled.add(item);
+    };
+    if (Array.isArray(value))
+        for (let index = 0; index < value.length; index++)
+            visit(value[index]);
+    else
+        for (const key of Object.keys(value))
+            visit(value[key]);
+    if (nested)
+        ancestors.delete(value);
+    Object.freeze(value);
+    return nested;
+}
+/**
+ * `"trust"`: the top level is checked by `runtimeValue`'s type test and
+ * frozen shallowly, so `push` or `sort` on a handed-over array still throws;
+ * nested contents are not walked.
+ */
+function trust(value) {
+    if (value === null || typeof value !== "object") {
+        checkScalar(value);
+        return value;
+    }
+    if (isPlainContainer(value))
+        Object.freeze(value);
+    return value;
 }
 function immutableMap(entries) {
     const source = new Map(entries);
@@ -1902,22 +2129,15 @@ function immutableMap(entries) {
     return view;
 }
 function cloneValue(value, ancestors) {
-    if (typeof value === "number" && !Number.isFinite(value))
-        misuse("runtime/non-serializable-value", "Runtime numbers must be finite");
-    if (typeof value === "function" ||
-        typeof value === "symbol" ||
-        typeof value === "bigint")
-        misuse("runtime/non-serializable-value", `Runtime values cannot contain ${typeof value}`);
+    checkScalar(value);
     if (value === undefined || value === null || typeof value !== "object")
         return value;
-    const prototype = Object.getPrototypeOf(value);
-    if (!Array.isArray(value) &&
-        prototype !== Object.prototype &&
-        prototype !== null)
+    if (settled.has(value) || !isPlainContainer(value))
         return value;
     if (ancestors.has(value))
         misuse("runtime/non-serializable-value", "Runtime values cannot contain cycles");
     ancestors.add(value);
+    copiedContainers++;
     const clone = Array.isArray(value)
         ? value.map((item) => cloneValue(item, ancestors))
         : Object.fromEntries(Object.entries(value).map(([key, item]) => [
@@ -1943,17 +2163,19 @@ const TUPLE_LENGTHS = {
  * An output value, checked against its declaration. A bundle with declared
  * fields may only set those, and each one must be a valid value of its type.
  */
-function outputValue(value, definition, path) {
+function outputValue(value, definition, path, policy) {
+    // Handed over by the producer, so adopted (frozen where it stands), not copied.
+    const adopt = policy === "trust" ? trust : settle;
     if (definition.type !== "bundle" || !definition.fields)
-        return runtimeValue(value, definition.type, false, path);
+        return runtimeValue(value, definition.type, false, path, adopt);
     const fields = definition.fields;
     const problem = bundleValueProblem(value, fields);
     if (problem)
         misuse("runtime/value-type", `${path} ${problem}`);
     if (isBundleValue(value))
         for (const [field, item] of Object.entries(value))
-            runtimeValue(item, bundleFieldType(fields[field]), true, `${path}.${field}`);
-    return runtimeValue(value, "bundle", false, path);
+            runtimeValue(item, bundleFieldType(fields[field]), true, `${path}.${field}`, (checked) => checked);
+    return runtimeValue(value, "bundle", false, path, adopt);
 }
 /** Every path an expression names through ch/chs/chv. */
 function expressionPaths(expression) {
@@ -1975,7 +2197,9 @@ function readsBundleFields(node) {
             }
     return false;
 }
-function runtimeValue(value, type, allowUndefined, path) {
+function runtimeValue(value, type, allowUndefined, path, 
+/** How a checked value is kept: copied (a caller's value) by default. */
+keep = snapshot) {
     if (value === undefined) {
         if (allowUndefined)
             return undefined;
@@ -2001,7 +2225,7 @@ function runtimeValue(value, type, allowUndefined, path) {
             type !== "string");
     if (!valid)
         misuse("runtime/value-type", `${path} is not a valid ${type}`);
-    return snapshot(value);
+    return keep(value);
 }
 function sameValues(a, b, equal) {
     return a.length === b.length && a.every((value, index) => equal(value, b[index]));

package/dist/runtime/types.d.ts

@@ -216,9 +216,39 @@ export type RuntimeEvent = {
     readonly type: "run:complete";
     readonly result: RunResult;
 };
+/**
+ * What the runtime does with a value a node hands to `outputs.x.set()`.
+ *
+ * - `"freeze"` (default): checked and deep-frozen in place, never copied. A
+ *   node that mutates its output after handing it over, or mutates an input,
+ *   throws instead of corrupting another node's view.
+ * - `"trust"`: checked at the top level only and shallow-frozen; nested
+ *   contents are the producer's word. For headless runs (`cascade run`), where
+ *   a 1M-point array walked every frame was most of the frame.
+ *
+ * Either way nothing is cloned on the way through: reading an output back
+ * (`getOutputs`, `inspect`, `node:output`) hands out the same frozen value.
+ */
+export type RuntimeValuePolicy = "freeze" | "trust";
 export interface CreateRuntimeOptions {
     readonly host: RuntimeHost;
     readonly nodes?: readonly NodeRegistration[];
+    /** See `RuntimeValuePolicy`. Default `"freeze"`. */
+    readonly values?: RuntimeValuePolicy;
+    /**
+     * How many nodes one run may cook at once (default 1: one after another).
+     * Nodes still START in topological order, a node only once everything it
+     * reads has completed, so the `node:start` sequence and the outputs are the
+     * same as a serial run; only completions interleave. Feedback containers,
+     * trigger-wired and GPU nodes always cook alone.
+     */
+    readonly concurrency?: number;
+    /**
+     * Wraps each node's execute. A Node host uses it to carry the node id
+     * through the cook's async work (AsyncLocalStorage), so a stage call or a
+     * log line is attributed to its node when several cook at once.
+     */
+    readonly nodeScope?: <T>(nodeId: string, run: () => T) => T;
 }
 export interface CascadeRuntime {
     registerNode(registration: NodeRegistration): void;

package/doc/CLI_REFERENCE.md

@@ -50,6 +50,7 @@ Running, sharing, locks and Studio. `cascade --help` has their options; `cascade
 | `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 share <graph-file \| site-directory> [--name <slug>] [--scope <team>] [--protected]` | One link for the team: export the editor (or take a static directory with an `index.html`), deploy it to the Vercel project `cascade-<slug>` (team `field-io`), print the production URL (`data.url` with `--json`) and record it in the project's `shares.json`. Public unless `--protected` ([EDITOR_EXPORT.md](EDITOR_EXPORT.md#share-as-a-link)). |
 | `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. |
@@ -58,7 +59,7 @@ Running, sharing, locks and Studio. `cascade --help` has their options; `cascade
 | `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 ladder <graph-file> <node> --name <name> --vary <node.prop>=<a,b,c> \| --seeds <a,b,c> [--cairn <vault dir> [--vault <dir>]]` | 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). `--cairn` copies each variant to `<dir>/<id>-<nn>.png` and prints a `cairn:choice` card (`--json`: `data.cairnChoice`) to post in the Cairn chat; see [Picking on the phone](#picking-a-ladder-variant-in-cairn). |
 | `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). |
@@ -137,6 +138,23 @@ Opened in Studio, the top level reads `motif → transform → render`, with the
 
 `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`.
 
+## Picking a ladder variant in Cairn
+
+Marcus picks on his phone, in the Cairn web chat, by tapping a picture; the tap locks it. The loop for an agent:
+
+1. `cascade ladder <graph> <node> --name <name> --seeds 1,2,3 --cairn <vault>/<space>/_attachments/ladders/<id> --json` (`<id>` is the name lower-cased with dashes). Each variant is copied to `<dir>/<id>-<nn>.png`, and `data.cairnChoice` is the card. At most 8 variants.
+2. Post `data.cairnChoice` in the reply exactly as returned:
+
+   ````text
+   ```cairn:choice
+   {"prompt":"Dial: which one? (ladder dial, index.cascade render)","options":[{"label":"seed 1","value":"pick:dial:1","image":"Work/Projects/Cascade/_attachments/ladders/dial/dial-01.png"}, …]}
+   ```
+   ````
+
+   `label` says what the variant changed (`seed 1`, `hue=0.3`); `image` is relative to the vault, the nearest `.obsidian` (then `.git`) above `--cairn`, or `--vault`.
+3. A tap comes back as `Picked: seed 1 (pick:dial:1)`. Run `cascade pick dial 1 --project <project>` (MCP: `pick { "ladder": "dial", "variant": 1 }`).
+4. Reply with the locked image, `![[<that option's image>]]`, and the lock id.
+
 ## Checks that fail a run (`cascade.assert.*`)
 
 Put the check in the graph instead of a script beside it:
@@ -153,7 +171,7 @@ cascade run index.cascade --json      # exit 1: { "ok": false, "error": { "messa
 
 ## 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>`.
+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>`. Each run (one per frame with `--frames`) carries `ms`, the cook; `frameMs`, the whole frame to its outputs on disk; and `saveMs`, the difference (collecting and writing the outputs), beside each node's own `ms`.
 
 `--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" }`.
 
@@ -168,4 +186,4 @@ A project whose stages import numpy or Pillow declares them, and Cascade keeps a
 }
 ```
 
-`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 }`.
+`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/`. With none declared, doctor fails when a stage source imports numpy and the stage interpreter cannot (`stage imports`), which is how a project on the system Python renders nothing. 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

@@ -95,6 +95,32 @@ prints the same manifest without building anything.
    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.
 
+## Share as a link
+
+`cascade share` is the one step from a graph to a URL for the team:
+
+```sh
+cascade share plotter-social.cascade               # https://cascade-plotter-social.vercel.app
+cascade share renders/shelf --name commons-shelf   # any static directory with an index.html
+```
+
+It exports the editor into a scratch directory with the same allowlist and
+leak scan as `cascade export` (a directory is copied without dotfiles or
+`licensed/` and scanned the same way), deploys it to production in the Vercel
+project `cascade-<slug>` (team `field-io`, `--scope` for another), and prints
+the project's production URL. The slug is `--name`, else the editor id or the
+directory name. `--json` gives `data.url`, `data.deployment` and `data.shares`.
+
+Each share is recorded in the project's `shares.json` (the directory holding
+the graph, or the nearest `cascade.json` above a shared directory), one entry
+per source with its `name`, `project`, `url` and `sharedAt`. Sharing again
+replaces the entry and redeploys to the same URL.
+
+A share is public: that is what a link someone can open is. The export
+boundary above is the gate, so review `cascade export --plan` first.
+`--protected` instead requires Vercel Authentication on the project, as
+`cascade export --deploy vercel` does without `--public`.
+
 ## The `editor` section
 
 It sits beside `nodes` in the `.cascade` file. The runtime ignores it, and

package/doc/MCP.md

@@ -36,8 +36,9 @@ With a global install (`npm i -g @field/cascade`), use `"command": "cascade", "a
 | `cook` | `cascade run <graph> [--node <id>]` |
 | `render` | `cascade run <graph> --frames … [--fps] [--out] [--node]… [--scene]` |
 | `export` | `cascade export <graph> --plan \| --out <dir>` |
+| `share` | `cascade share <graph \| directory> [--name] [--scope] [--protected]` (deploys; `data.url` is the link) |
 | `lock`, `replay`, `locks` | `cascade lock <graph> <node> --name`, `cascade replay <id> [--live]`, `cascade locks` |
-| `ladder`, `pick` | `cascade ladder <graph> <node> --name --vary node.prop=a,b,c \| --seeds a,b,c` (`vary` is `{ "node.prop": [a, b, c] }`), `cascade pick <ladder> <n>` |
+| `ladder`, `pick` | `cascade ladder <graph> <node> --name --vary node.prop=a,b,c \| --seeds a,b,c` (`vary` is `{ "node.prop": [a, b, c] }`; `cairn`, an absolute vault directory, returns `data.cairnChoice`, a tap-to-pick card for the Cairn chat: see [Picking in Cairn](CLI_REFERENCE.md#picking-a-ladder-variant-in-cairn)), `cascade pick <ladder> <n>` (on "Picked: … (pick:<id>:<n>)", `ladder` <id>, `variant` <n>) |
 | `node_help` | `cascade help node [<type>]` (a node type's declaration; every type without one) |
 | `doctor` | `cascade doctor [--fix]` (Python environment, stage interpreter, ffmpeg, canvas; `fix` builds the environment) |