@field/cascade 0.7.1 → 0.10.0

package/dist/runtime/builtins/core/routing.d.ts

@@ -109,6 +109,33 @@ declare const nullDefinition: {
         };
     };
 };
+/**
+ * `cascade.core.Frozen` — a snapshot standing in for a live data source.
+ *
+ * `cascade export` writes one in place of a node the author froze with
+ * `cascade freeze`: the chosen fields of that node's output, and nothing else.
+ * It has no inputs, so nothing upstream of a frozen source ships.
+ */
+declare const frozenDefinition: {
+    readonly apiVersion: 1;
+    readonly runsOn: "portable";
+    readonly label: "Frozen";
+    readonly description: "Emits a frozen snapshot of a data source's chosen values";
+    readonly icon: "Snowflake";
+    readonly outputs: {
+        readonly value: {
+            readonly kind: "data";
+            readonly type: "any";
+        };
+    };
+    readonly props: {
+        readonly value: {
+            readonly type: "any";
+            readonly default: null;
+        };
+    };
+};
+export declare const frozenRegistration: DefinitionNodeRegistration<typeof frozenDefinition>;
 export declare const switchRegistration: DefinitionNodeRegistration<typeof switchDefinition>;
 export declare const mergeRegistration: DefinitionNodeRegistration<typeof mergeDefinition>;
 export declare const selectRegistration: DefinitionNodeRegistration<typeof selectDefinition>;

package/dist/runtime/builtins/core/routing.js

@@ -61,6 +61,34 @@ const nullDefinition = {
         output: { kind: "data", type: "any" },
     },
 };
+/**
+ * `cascade.core.Frozen` — a snapshot standing in for a live data source.
+ *
+ * `cascade export` writes one in place of a node the author froze with
+ * `cascade freeze`: the chosen fields of that node's output, and nothing else.
+ * It has no inputs, so nothing upstream of a frozen source ships.
+ */
+const frozenDefinition = {
+    apiVersion: 1,
+    runsOn: "portable",
+    label: "Frozen",
+    description: "Emits a frozen snapshot of a data source's chosen values",
+    icon: "Snowflake",
+    outputs: {
+        value: { kind: "data", type: "any" },
+    },
+    props: {
+        value: { type: "any", default: null },
+    },
+};
+export const frozenRegistration = {
+    kind: "definition-v1",
+    moduleId: "cascade.core.Frozen",
+    definition: frozenDefinition,
+    loadExecute: async () => ({ outputs, props }) => {
+        outputs.value.set(props.value);
+    },
+};
 export const switchRegistration = {
     kind: "definition-v1",
     moduleId: "cascade.core.Switch",

package/dist/runtime/edit/document.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The `.cascade` document as plain, mutable JSON — the shape the editor works
+ * on — and the small vocabulary for reading it: wires, ports, positions and
+ * key order.
+ *
+ * The editor deliberately edits the parsed JSON rather than a model built from
+ * it. A model would have to re-serialise every node on save, and every field it
+ * did not know about (a colour, a promotion, a key some other tool wrote) would
+ * either be dropped or reordered. Editing in place means a command touches the
+ * keys it is about and nothing else, which is what makes the diff minimal.
+ */
+import type { NodeDefinition } from "@field/cascade/contracts";
+import type { Point } from "./layout.js";
+export type JsonObject = Record<string, unknown>;
+export interface EditableNode extends JsonObject {
+    id: string;
+    module?: string;
+    type?: string;
+    parent?: string;
+    props?: JsonObject;
+}
+export interface EditableDocument extends JsonObject {
+    nodes: EditableNode[];
+    connections?: unknown[];
+    annotations?: JsonObject[];
+}
+export declare const SUBNET = "cascade.core.Subnet";
+export declare const INPUT = "cascade.core.Input";
+export declare const OUTPUT = "cascade.core.Output";
+/** One end of a wire: a node, a port name, and the port's index on that node. */
+export interface Endpoint {
+    readonly node: string;
+    readonly port: string;
+    readonly index: number;
+}
+export interface Wire {
+    readonly from: Endpoint;
+    readonly to: Endpoint;
+}
+export type WireStyle = "tuple" | "object";
+/**
+ * Read either connection form. Studio writes `[[id, index, name], [id, index,
+ * name]]`; the contracts also allow `{ source, target }`. Anything else is
+ * reported as `null`, never guessed at.
+ */
+export declare function readWire(raw: unknown): Wire | null;
+export declare function writeWire(wire: Wire, style: WireStyle): unknown;
+/** Whichever form the file already uses, so a new wire looks like its neighbours. */
+export declare function wireStyleOf(document: EditableDocument): WireStyle;
+/** `a.out -> b.in`: the same spelling the CLI takes. */
+export declare function wireLabel(wire: Wire): string;
+export declare function sameEndpoint(a: Endpoint, b: Endpoint): boolean;
+export declare function moduleOf(node: EditableNode): string;
+export declare function parentOf(node: EditableNode): string | null;
+export declare function positionOf(node: EditableNode): Point;
+/** Keep whichever shape the node already uses; Studio's `[x, y]` otherwise. */
+export declare function setPosition(node: EditableNode, point: Point): void;
+/**
+ * The key order Studio writes a node in (`Graph.nodeToJSON`). A key the editor
+ * adds goes where Studio would have put it, so a node edited by the CLI and
+ * then saved by Studio does not reorder.
+ */
+export declare const NODE_KEY_ORDER: readonly ["id", "module", "type", "position", "source", "file", "code", "comment", "color", "parent", "params", "promotions", "inputs", "props", "bypass", "cook", "state"];
+/**
+ * Set a key without moving any other. An existing key keeps its place; a new
+ * one is inserted before the first key that Studio writes after it, or at the
+ * end when it is not one Studio knows.
+ */
+export declare function setOrderedKey(target: JsonObject, key: string, value: unknown, order: readonly string[]): void;
+export interface PortInfo {
+    readonly name: string;
+    readonly index: number;
+    readonly kind: "data" | "trigger";
+    readonly type: string;
+    readonly variadic: boolean;
+}
+export interface NodePorts {
+    readonly inputs: readonly PortInfo[];
+    readonly outputs: readonly PortInfo[];
+}
+/** Ports in declaration order, which is the order Studio indexes them in. */
+export declare function portsFromDefinition(definition: NodeDefinition): NodePorts;
+/**
+ * A subnet's ports are not declared anywhere: they are its `Input` and
+ * `Output` children, named `input_<n>` and `output_<n>`. The runtime derives
+ * them the same way (`indexedBoundaryPorts` in runtime.ts); this mirrors it so
+ * the editor and the runtime agree on what a subnet exposes.
+ */
+export declare function subnetPorts(children: readonly EditableNode[]): NodePorts;
+export declare function typesConnect(from: PortInfo | undefined, to: PortInfo | undefined): boolean;
+export declare function integer(value: unknown): number;
+/** Deep equality for JSON values, insensitive to key order. */
+export declare function jsonEqual(a: unknown, b: unknown): boolean;
+//# sourceMappingURL=document.d.ts.map

package/dist/runtime/edit/document.js

@@ -0,0 +1,194 @@
+/**
+ * The `.cascade` document as plain, mutable JSON — the shape the editor works
+ * on — and the small vocabulary for reading it: wires, ports, positions and
+ * key order.
+ *
+ * The editor deliberately edits the parsed JSON rather than a model built from
+ * it. A model would have to re-serialise every node on save, and every field it
+ * did not know about (a colour, a promotion, a key some other tool wrote) would
+ * either be dropped or reordered. Editing in place means a command touches the
+ * keys it is about and nothing else, which is what makes the diff minimal.
+ */
+import { canConnectTypes } from "@field/cascade/contracts";
+export const SUBNET = "cascade.core.Subnet";
+export const INPUT = "cascade.core.Input";
+export const OUTPUT = "cascade.core.Output";
+/**
+ * Read either connection form. Studio writes `[[id, index, name], [id, index,
+ * name]]`; the contracts also allow `{ source, target }`. Anything else is
+ * reported as `null`, never guessed at.
+ */
+export function readWire(raw) {
+    if (Array.isArray(raw) && raw.length === 2 && Array.isArray(raw[0]) && Array.isArray(raw[1])) {
+        const [from, to] = raw;
+        if (typeof from[0] !== "string" || typeof to[0] !== "string")
+            return null;
+        return {
+            from: { node: from[0], index: Number(from[1] ?? 0), port: String(from[2] ?? "") },
+            to: { node: to[0], index: Number(to[1] ?? 0), port: String(to[2] ?? "") },
+        };
+    }
+    if (raw && typeof raw === "object" && "source" in raw && "target" in raw) {
+        const { source, target } = raw;
+        return {
+            from: { node: source.nodeId, port: source.outputName, index: 0 },
+            to: { node: target.nodeId, port: target.inputName, index: 0 },
+        };
+    }
+    return null;
+}
+export function writeWire(wire, style) {
+    if (style === "object") {
+        return {
+            source: { nodeId: wire.from.node, outputName: wire.from.port },
+            target: { nodeId: wire.to.node, inputName: wire.to.port },
+        };
+    }
+    return [
+        [wire.from.node, wire.from.index, wire.from.port],
+        [wire.to.node, wire.to.index, wire.to.port],
+    ];
+}
+/** Whichever form the file already uses, so a new wire looks like its neighbours. */
+export function wireStyleOf(document) {
+    const first = document.connections?.[0];
+    return first && !Array.isArray(first) ? "object" : "tuple";
+}
+/** `a.out -> b.in`: the same spelling the CLI takes. */
+export function wireLabel(wire) {
+    return `${wire.from.node}.${wire.from.port} -> ${wire.to.node}.${wire.to.port}`;
+}
+export function sameEndpoint(a, b) {
+    return a.node === b.node && a.port === b.port;
+}
+export function moduleOf(node) {
+    return String(node.module ?? node.type ?? "");
+}
+export function parentOf(node) {
+    return typeof node.parent === "string" && node.parent ? node.parent : null;
+}
+export function positionOf(node) {
+    const position = node.position;
+    if (Array.isArray(position))
+        return { x: Number(position[0]) || 0, y: Number(position[1]) || 0 };
+    if (position && typeof position === "object") {
+        const { x, y } = position;
+        return { x: Number(x) || 0, y: Number(y) || 0 };
+    }
+    return { x: 0, y: 0 };
+}
+/** Keep whichever shape the node already uses; Studio's `[x, y]` otherwise. */
+export function setPosition(node, point) {
+    const position = node.position;
+    const value = position && typeof position === "object" && !Array.isArray(position)
+        ? { x: point.x, y: point.y }
+        : [point.x, point.y];
+    setOrderedKey(node, "position", value, NODE_KEY_ORDER);
+}
+/**
+ * The key order Studio writes a node in (`Graph.nodeToJSON`). A key the editor
+ * adds goes where Studio would have put it, so a node edited by the CLI and
+ * then saved by Studio does not reorder.
+ */
+export const NODE_KEY_ORDER = [
+    "id", "module", "type", "position", "source", "file", "code", "comment", "color",
+    "parent", "params", "promotions", "inputs", "props", "bypass", "cook", "state",
+];
+/**
+ * Set a key without moving any other. An existing key keeps its place; a new
+ * one is inserted before the first key that Studio writes after it, or at the
+ * end when it is not one Studio knows.
+ */
+export function setOrderedKey(target, key, value, order) {
+    if (key in target) {
+        target[key] = value;
+        return;
+    }
+    const rank = order.indexOf(key);
+    const entries = Object.entries(target);
+    const at = rank === -1 ? -1 : entries.findIndex(([name]) => {
+        const other = order.indexOf(name);
+        return other > rank;
+    });
+    if (at === -1) {
+        target[key] = value;
+        return;
+    }
+    for (const [name] of entries)
+        delete target[name];
+    entries.splice(at, 0, [key, value]);
+    for (const [name, entry] of entries)
+        target[name] = entry;
+}
+/** Ports in declaration order, which is the order Studio indexes them in. */
+export function portsFromDefinition(definition) {
+    const list = (record) => Object.entries(record ?? {}).map(([name, port], index) => {
+        const value = port;
+        return {
+            name,
+            index,
+            kind: value.kind === "trigger" ? "trigger" : "data",
+            type: value.type ?? "any",
+            variadic: value.variadic === true,
+        };
+    });
+    return {
+        inputs: list(definition.inputs),
+        outputs: list(definition.outputs),
+    };
+}
+/**
+ * A subnet's ports are not declared anywhere: they are its `Input` and
+ * `Output` children, named `input_<n>` and `output_<n>`. The runtime derives
+ * them the same way (`indexedBoundaryPorts` in runtime.ts); this mirrors it so
+ * the editor and the runtime agree on what a subnet exposes.
+ */
+export function subnetPorts(children) {
+    const boundary = (module, indexProp, prefix) => {
+        const found = children
+            .filter((child) => moduleOf(child) === module)
+            .map((child) => ({ index: integer(child.props?.[indexProp]), type: String(child.props?.dataType || "any") }))
+            .filter((entry) => entry.index >= 0);
+        const max = found.length ? Math.max(...found.map((entry) => entry.index)) : -1;
+        return Array.from({ length: max + 1 }, (_, index) => ({
+            name: `${prefix}_${index}`,
+            index,
+            kind: "data",
+            type: found.find((entry) => entry.index === index)?.type ?? "any",
+            variadic: false,
+        }));
+    };
+    return {
+        inputs: boundary(INPUT, "inputIndex", "input"),
+        outputs: boundary(OUTPUT, "outputIndex", "output"),
+    };
+}
+export function typesConnect(from, to) {
+    if (!from || !to)
+        return true;
+    if (from.kind !== to.kind)
+        return false;
+    return from.kind === "trigger" || canConnectTypes(from.type, to.type);
+}
+export function integer(value) {
+    const number = Number(value ?? 0);
+    return Number.isInteger(number) ? number : -1;
+}
+/** Deep equality for JSON values, insensitive to key order. */
+export function jsonEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b || a === null || b === null || typeof a !== "object")
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (Array.isArray(a)) {
+        const other = b;
+        return a.length === other.length && a.every((value, index) => jsonEqual(value, other[index]));
+    }
+    const left = a;
+    const right = b;
+    const keys = Object.keys(left);
+    return keys.length === Object.keys(right).length && keys.every((key) => key in right && jsonEqual(left[key], right[key]));
+}
+//# sourceMappingURL=document.js.map

package/dist/runtime/edit/graphEditor.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Editing a `.cascade` document: add and remove nodes, wire and unwire ports,
+ * set parameters, and group nodes into subnets.
+ *
+ * One implementation behind every surface — `cascade node add`, the MCP
+ * server's `node_add`, and anything else that edits a graph without Studio —
+ * so a command and a tool call cannot disagree about what an edit means.
+ *
+ * Three rules hold for every operation, because they are what keeps a graph
+ * an agent edited readable to the person who opens it afterwards:
+ *
+ * - **Minimal diffs.** Only the keys an operation is about change. Node ids are
+ *   stable, untouched nodes keep their place in the file, a new key goes where
+ *   Studio would write it, and a rewired connection is rewritten in place
+ *   rather than removed and appended. An edit followed by its inverse leaves
+ *   the file byte-identical (tests/graph-edit.test.ts).
+ * - **Placed, not piled.** A node the editor creates is positioned next to what
+ *   it is wired to and in line with the graph's existing flow (`layout.ts`).
+ * - **Subnets stay closed.** A wire never crosses a subnet boundary directly;
+ *   moving nodes in or out of a subnet rewires through its `Input` and
+ *   `Output` nodes, creating them when needed and removing them when unused.
+ *
+ * The editor is pure: it edits a parsed document in memory and resolves node
+ * definitions through a callback. Reading, validating and writing files is the
+ * host's job (`src/cli/graphFile.ts`).
+ */
+import type { NodeDefinition } from "@field/cascade/contracts";
+import { type EditableDocument, type EditableNode, type NodePorts } from "./document.js";
+import { type Point } from "./layout.js";
+import { type ParameterChange } from "./parameters.js";
+export interface GraphEditorOptions {
+    /** The definition of a module id, or `undefined` when it has none (a dynamic or missing module). */
+    readonly definitionOf: (moduleId: string) => NodeDefinition | undefined;
+}
+/** A refused edit. The document is left as it was before the operation began. */
+export declare class GraphEditError extends Error {
+    constructor(message: string);
+}
+export interface AddNodeInput {
+    readonly module: string;
+    readonly id?: string;
+    /** The subnet to create the node in. Omitted: the top level. */
+    readonly parent?: string;
+    readonly position?: Point;
+    /** Parameter values, as JSON values or (with `fromText`) command-line text. */
+    readonly props?: Readonly<Record<string, unknown>>;
+    readonly fromText?: boolean;
+    readonly comment?: string;
+}
+export interface NodeSummary {
+    readonly id: string;
+    readonly module: string;
+    readonly parent: string | null;
+    readonly position: Point;
+}
+export declare class GraphEditor {
+    readonly document: EditableDocument;
+    private readonly options;
+    readonly warnings: string[];
+    constructor(document: EditableDocument, options: GraphEditorOptions);
+    addNode(input: AddNodeInput): {
+        node: NodeSummary;
+    };
+    /**
+     * Remove a node and every wire touching it. A subnet with children is
+     * refused unless `recursive`, because removing a container silently would
+     * remove everything in it.
+     */
+    removeNode(id: string, options?: {
+        recursive?: boolean;
+    }): {
+        removed: string[];
+        wires: string[];
+    };
+    /**
+     * Wire `from` (`node.output`) to `to` (`node.input`). A port name may be
+     * left off when the node has exactly one port on that side.
+     *
+     * The two nodes may be in different subnets: the wire is then routed
+     * through the subnets' `Output` and `Input` nodes, which are created (or
+     * reused) as needed, so no wire ever crosses a boundary directly.
+     *
+     * A node wired for the first time is moved next to its new neighbour, so a
+     * node created by `node add` and then connected ends up where a person would
+     * have put it. Pass `layout: false` to leave positions alone.
+     */
+    connect(from: string, to: string, options?: {
+        layout?: boolean;
+    }): {
+        wire: string;
+        replaced?: string;
+        moved?: NodeSummary;
+    };
+    /**
+     * The endpoint on `level`'s canvas that carries `source`: the source itself
+     * when it is already there, otherwise a subnet port reached by passing out
+     * through `Output` nodes to the common ancestor and in through `Input` nodes
+     * to `level`. Existing boundaries carrying the same value are reused.
+     */
+    private routeAcross;
+    /**
+     * Remove wires. `disconnect a.out b.in` removes that wire; `disconnect b.in`
+     * removes whatever feeds that input; `disconnect a.out` removes everything
+     * that output feeds.
+     */
+    disconnect(first: string, second?: string): {
+        removed: string[];
+    };
+    /** Change `node.param`: its value, expression or keyframes. */
+    setParameter(target: string, change: ParameterChange): {
+        node: string;
+        param: string;
+        field: string;
+        before: unknown;
+        after: unknown;
+    };
+    /**
+     * Group sibling nodes into a new subnet. Wires that now cross its boundary
+     * are routed through new `Input` and `Output` nodes, named after the port
+     * they carry, so the subnet's ports read as what flows through them.
+     */
+    createSubnet(input: {
+        nodes: readonly string[];
+        id?: string;
+        label?: string;
+    }): {
+        subnet: NodeSummary;
+        inputs: string[];
+        outputs: string[];
+    };
+    /** The inverse of `createSubnet`: lift the children out and remove the subnet. */
+    dissolveSubnet(id: string): {
+        lifted: string[];
+    };
+    /**
+     * Move sibling nodes to another subnet (`null` for the top level), one level
+     * at a time — out to the common ancestor, then in — rewiring through each
+     * boundary on the way.
+     */
+    moveNodes(ids: readonly string[], to: string | null): {
+        moved: string[];
+        to: string | null;
+        placed: NodeSummary[];
+    };
+    /**
+     * Move sibling nodes from the subnet's parent into the subnet.
+     *
+     * A wire from a member to the subnet's own input collapses (the member is
+     * now inside, so it feeds that input's consumers directly), and a wire from
+     * outside to a member is routed through an `Input` — reusing one that
+     * already carries the same source. The mirror holds for outputs. Wires are
+     * rewritten in place where possible, which is what lets `moveOut` restore
+     * the original file exactly.
+     */
+    private moveIn;
+    /** Move nodes out of a subnet into its parent. The mirror of `moveIn`. */
+    private moveOut;
+    /** An `Output` in the subnet already fed by `source`, or a new one. */
+    private outputFor;
+    /** An `Input` in the subnet whose outside feed is `source`. */
+    private inputCarrying;
+    private createBoundary;
+    /**
+     * Name new boundary nodes after what they carry, readably. A port name is
+     * the natural label (`moment`, `canvas`), but not when it says nothing
+     * (`value`, `output`) or when two ports of the subnet would share it — three
+     * `mask` outputs read as one. Then the producing node's id is the label:
+     * `masks-out-cloud-mask` beside `masks-out-primary-lobe`.
+     */
+    private nameBoundaries;
+    private relabelBoundary;
+    /** What a value is called: its port name, or for a subnet's own port, the name of the boundary behind it. */
+    private labelOf;
+    /**
+     * Remove boundary node k and keep the subnet's ports contiguous: the ports
+     * above it shift down one, and so do the wires that use them. Wires to the
+     * removed port itself are marked in `removed` for the caller to drop.
+     */
+    private removeBoundaryNode;
+    /** `rm` of a boundary node: the subnet loses that port. */
+    private removeBoundary;
+    private boundaryIndex;
+    private boundaryNode;
+    private subnetPort;
+    findNode(id: string): EditableNode | undefined;
+    requireNode(id: string): EditableNode;
+    childrenOf(parent: string | null): EditableNode[];
+    private descendantsOf;
+    private ancestorsOf;
+    private requireContainer;
+    private requireSiblings;
+    /** The ports a node has, or `null` when they are not statically known. */
+    portsOf(node: EditableNode): NodePorts | null;
+    private portInfo;
+    /** `node.port` to a checked endpoint. A missing port name is filled in when only one would fit. */
+    private resolveEndpoint;
+    private indexFromExistingWires;
+    private isWired;
+    private setParameterOn;
+    private connections;
+    /** Every connection with its array index; unreadable ones have `wire: null` and are left alone. */
+    private wires;
+    private appendWire;
+    private replaceWire;
+    private removeWires;
+    /** Insert after the last node of the same subnet, so a subnet's children stay together in the file. */
+    private insertNode;
+    private placeFor;
+    private relayout;
+    /** The flow of one canvas: the median offset along its wires. */
+    private stepIn;
+    private forgetInAnnotations;
+    uniqueId(base: string): string;
+    summary(node: EditableNode): NodeSummary;
+}
+/** `a.b.port` splits at the last dot: node `a.b`, port `port`. No dot: the node alone. */
+export declare function splitEndpoint(text: string): {
+    node: string;
+    port: string;
+};
+/** `project.InkVocabulary` becomes `ink-vocabulary`; `cascade.geo.CopyToPoints`, `copy-to-points`. */
+export declare function defaultIdFor(module: string): string;
+//# sourceMappingURL=graphEditor.d.ts.map