@field/cascade 0.8.0 → 0.11.0

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

@@ -0,0 +1,12 @@
+export { GraphEditor, GraphEditError, defaultIdFor, splitEndpoint } from "./graphEditor.js";
+export type { AddNodeInput, GraphEditorOptions, NodeSummary } from "./graphEditor.js";
+export { applyOperation, GRAPH_EDIT_OPERATIONS } from "./operations.js";
+export type { GraphEditOperation } from "./operations.js";
+export { readGraph } from "./read.js";
+export type { GraphRead, GraphReadNode } from "./read.js";
+export { flowStep, placeNode } from "./layout.js";
+export type { Point } from "./layout.js";
+export { readWire, wireLabel } from "./document.js";
+export type { EditableDocument, EditableNode, Wire, Endpoint } from "./document.js";
+export type { ParameterChange } from "./parameters.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/edit/index.js

@@ -0,0 +1,6 @@
+export { GraphEditor, GraphEditError, defaultIdFor, splitEndpoint } from "./graphEditor.js";
+export { applyOperation, GRAPH_EDIT_OPERATIONS } from "./operations.js";
+export { readGraph } from "./read.js";
+export { flowStep, placeNode } from "./layout.js";
+export { readWire, wireLabel } from "./document.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,50 @@
+/**
+ * Where an agent-created node goes on the canvas.
+ *
+ * Not a graph layout. Studio has one (`src/utils/autoLayout.ts`) and running it
+ * on every agent edit would move every node the author placed by hand, which
+ * is the opposite of a minimal diff. This places ONE node, among siblings that
+ * stay where they are, so that opening Studio after an agent session shows the
+ * new node next to what it is wired to and in line with the existing flow.
+ *
+ * The flow is read from the graph rather than assumed. Studio draws inputs on
+ * top and outputs on the bottom, so a fresh graph flows down; but a graph
+ * whose stages step diagonally (cloud-plots' top level) should get its next
+ * stage on the same diagonal. The step is the median offset between wired
+ * siblings, so one odd wire does not set the direction.
+ */
+export interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+/** Studio's own spacing (`autoLayout.ts`): rows 190 apart, columns 260. */
+export declare const DEFAULT_STEP: Point;
+/**
+ * The direction and distance from a node to the one it feeds, measured as the
+ * component-wise median over the given wires. Falls back to Studio's downward
+ * flow when nothing is wired yet, and ignores steps too short to be a layout
+ * decision (two nodes stacked by accident).
+ */
+export declare function flowStep(wires: readonly {
+    from: Point;
+    to: Point;
+}[]): Point;
+export interface PlacementRequest {
+    /** Where the other nodes on the same canvas already are. */
+    readonly siblings: readonly Point[];
+    /** Positions of the nodes wired into the new node. */
+    readonly upstream: readonly Point[];
+    /** Positions of the nodes the new node feeds. */
+    readonly downstream: readonly Point[];
+    readonly step: Point;
+}
+/**
+ * One free position: a step past what feeds the node, or a step before what it
+ * feeds, or a staging lane beside the graph when it is wired to nothing yet. If that spot
+ * is taken it moves sideways across the flow, alternating sides, until it is
+ * clear — so a second consumer of the same node lands beside the first.
+ */
+export declare function placeNode({ siblings, upstream, downstream, step }: PlacementRequest): Point;
+/** True when a node at `point` would sit on top of an existing one. */
+export declare function isOccupied(siblings: readonly Point[], point: Point): boolean;
+//# sourceMappingURL=layout.d.ts.map

package/dist/runtime/edit/layout.js

@@ -0,0 +1,126 @@
+/**
+ * Where an agent-created node goes on the canvas.
+ *
+ * Not a graph layout. Studio has one (`src/utils/autoLayout.ts`) and running it
+ * on every agent edit would move every node the author placed by hand, which
+ * is the opposite of a minimal diff. This places ONE node, among siblings that
+ * stay where they are, so that opening Studio after an agent session shows the
+ * new node next to what it is wired to and in line with the existing flow.
+ *
+ * The flow is read from the graph rather than assumed. Studio draws inputs on
+ * top and outputs on the bottom, so a fresh graph flows down; but a graph
+ * whose stages step diagonally (cloud-plots' top level) should get its next
+ * stage on the same diagonal. The step is the median offset between wired
+ * siblings, so one odd wire does not set the direction.
+ */
+/** Studio's own spacing (`autoLayout.ts`): rows 190 apart, columns 260. */
+export const DEFAULT_STEP = Object.freeze({ x: 0, y: 190 });
+const COLUMN_GAP = 260;
+const ROW_GAP = 190;
+/** Where Studio's layout starts an empty canvas. */
+const ORIGIN = Object.freeze({ x: 40, y: 40 });
+/** Two nodes closer than this overlap on screen. A node is about 200 x 100. */
+const CLEARANCE = Object.freeze({ x: 210, y: 120 });
+const MAX_LANES = 24;
+/**
+ * The direction and distance from a node to the one it feeds, measured as the
+ * component-wise median over the given wires. Falls back to Studio's downward
+ * flow when nothing is wired yet, and ignores steps too short to be a layout
+ * decision (two nodes stacked by accident).
+ */
+export function flowStep(wires) {
+    const deltas = wires
+        .map(({ from, to }) => ({ x: to.x - from.x, y: to.y - from.y }))
+        .filter((delta) => Math.hypot(delta.x, delta.y) >= 60);
+    if (!deltas.length)
+        return DEFAULT_STEP;
+    const step = { x: median(deltas.map((d) => d.x)), y: median(deltas.map((d) => d.y)) };
+    // The sideways part of the step is kept only when every wire agrees on it,
+    // as on a staircase of stages. A fan-in (two sources side by side feeding
+    // one node) has sideways parts of both signs, and averaging them would tilt
+    // the whole flow for no reason.
+    const down = Math.abs(step.y) >= Math.abs(step.x);
+    const across = deltas.map((d) => (down ? d.x : d.y));
+    const agree = across.every((value) => Math.sign(value) === Math.sign(across[0]) && Math.abs(value - median(across)) <= Math.abs(median(across)) * 0.25);
+    if (agree)
+        return step;
+    return down ? { x: 0, y: step.y } : { x: step.x, y: 0 };
+}
+/**
+ * One free position: a step past what feeds the node, or a step before what it
+ * feeds, or a staging lane beside the graph when it is wired to nothing yet. If that spot
+ * is taken it moves sideways across the flow, alternating sides, until it is
+ * clear — so a second consumer of the same node lands beside the first.
+ */
+export function placeNode({ siblings, upstream, downstream, step }) {
+    const anchor = anchorFor(siblings, upstream, downstream, step);
+    const lane = laneStep(step);
+    for (let attempt = 0; attempt <= MAX_LANES * 2; attempt += 1) {
+        const offset = attempt === 0 ? 0 : (attempt % 2 === 1 ? 1 : -1) * Math.ceil(attempt / 2);
+        const candidate = round({ x: anchor.x + lane.x * offset, y: anchor.y + lane.y * offset });
+        if (!siblings.some((other) => overlaps(other, candidate)))
+            return candidate;
+    }
+    return round(anchor);
+}
+/** True when a node at `point` would sit on top of an existing one. */
+export function isOccupied(siblings, point) {
+    return siblings.some((other) => overlaps(other, point));
+}
+function anchorFor(siblings, upstream, downstream, step) {
+    const unit = normalise(step);
+    if (upstream.length) {
+        // Beside the average of its inputs, but past the furthest of them, so a
+        // node fed from two rows never lands between them.
+        return add(alongFlow(mean(upstream), unit, Math.max(...upstream.map((p) => dot(p, unit)))), step);
+    }
+    if (downstream.length) {
+        return subtract(alongFlow(mean(downstream), unit, Math.min(...downstream.map((p) => dot(p, unit)))), step);
+    }
+    if (!siblings.length)
+        return ORIGIN;
+    // Wired to nothing yet: a staging lane beside the graph, at the start of the
+    // flow. Parking it in the flow would take the very slot the next wire wants;
+    // here it waits until `connect` moves it into place, and anything left in
+    // the lane reads as not wired yet.
+    const lane = laneStep(step);
+    const across = normalise(lane);
+    const furthest = Math.max(...siblings.map((p) => dot(p, across)));
+    const start = Math.min(...siblings.map((p) => dot(p, unit)));
+    return {
+        x: across.x * furthest + unit.x * start + lane.x,
+        y: across.y * furthest + unit.y * start + lane.y,
+    };
+}
+/** Across the flow: columns for a downward graph, rows for a sideways one. */
+function laneStep(step) {
+    return Math.abs(step.y) >= Math.abs(step.x) ? { x: COLUMN_GAP, y: 0 } : { x: 0, y: ROW_GAP };
+}
+/** Move `point` along `unit` until its projection onto `unit` equals `target`. */
+function alongFlow(point, unit, target) {
+    const shift = target - dot(point, unit);
+    return { x: point.x + unit.x * shift, y: point.y + unit.y * shift };
+}
+function overlaps(a, b) {
+    return Math.abs(a.x - b.x) < CLEARANCE.x && Math.abs(a.y - b.y) < CLEARANCE.y;
+}
+function median(values) {
+    const sorted = [...values].sort((a, b) => a - b);
+    const middle = Math.floor(sorted.length / 2);
+    return sorted.length % 2 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2;
+}
+function mean(points) {
+    return {
+        x: points.reduce((sum, p) => sum + p.x, 0) / points.length,
+        y: points.reduce((sum, p) => sum + p.y, 0) / points.length,
+    };
+}
+function normalise(p) {
+    const length = Math.hypot(p.x, p.y) || 1;
+    return { x: p.x / length, y: p.y / length };
+}
+const dot = (a, b) => a.x * b.x + a.y * b.y;
+const add = (a, b) => ({ x: a.x + b.x, y: a.y + b.y });
+const subtract = (a, b) => ({ x: a.x - b.x, y: a.y - b.y });
+const round = (p) => ({ x: Math.round(p.x), y: Math.round(p.y) });
+//# sourceMappingURL=layout.js.map

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

@@ -0,0 +1,65 @@
+/**
+ * The edit vocabulary as data.
+ *
+ * Every CLI editing command parses to one of these and every MCP editing tool
+ * takes one, so the two surfaces share names, fields and behaviour. The names
+ * are the graph's own (node, connect, set, subnet), not a second vocabulary.
+ */
+import type { GraphEditor } from "./graphEditor.js";
+import type { Point } from "./layout.js";
+import type { Interpolation } from "./parameters.js";
+export type GraphEditOperation = {
+    readonly op: "node.add";
+    readonly module: string;
+    readonly id?: string;
+    /** Subnet to create the node in. */
+    readonly in?: string;
+    readonly position?: Point;
+    readonly set?: Readonly<Record<string, unknown>>;
+    /** `set` values are command-line text, read by each parameter's type. */
+    readonly fromText?: boolean;
+    readonly comment?: string;
+} | {
+    readonly op: "node.remove";
+    readonly id: string;
+    readonly recursive?: boolean;
+} | {
+    readonly op: "connect";
+    readonly from: string;
+    readonly to: string;
+    readonly layout?: boolean;
+} | {
+    readonly op: "disconnect";
+    readonly from?: string;
+    readonly to: string;
+} | {
+    readonly op: "set";
+    /** `node.param` */
+    readonly target: string;
+    readonly value?: unknown;
+    readonly fromText?: boolean;
+    readonly expression?: string | null;
+    readonly keys?: readonly {
+        frame: number;
+        value: number;
+    }[];
+    readonly removeKeys?: readonly number[];
+    readonly interpolation?: Interpolation;
+    readonly unset?: boolean;
+} | {
+    readonly op: "subnet.create";
+    readonly nodes: readonly string[];
+    readonly id?: string;
+    readonly label?: string;
+} | {
+    readonly op: "subnet.move";
+    readonly nodes: readonly string[];
+    readonly to: string | null;
+} | {
+    readonly op: "subnet.dissolve";
+    readonly id: string;
+};
+export declare const GRAPH_EDIT_OPERATIONS: readonly ["node.add", "node.remove", "connect", "disconnect", "set", "subnet.create", "subnet.move", "subnet.dissolve"];
+/** Apply one operation and return what it changed, in JSON-ready form. */
+export declare function applyOperation(editor: GraphEditor, operation: GraphEditOperation): Record<string, unknown>;
+//# sourceMappingURL=operations.d.ts.map

package/dist/runtime/edit/operations.js

@@ -0,0 +1,57 @@
+/**
+ * The edit vocabulary as data.
+ *
+ * Every CLI editing command parses to one of these and every MCP editing tool
+ * takes one, so the two surfaces share names, fields and behaviour. The names
+ * are the graph's own (node, connect, set, subnet), not a second vocabulary.
+ */
+export const GRAPH_EDIT_OPERATIONS = [
+    "node.add",
+    "node.remove",
+    "connect",
+    "disconnect",
+    "set",
+    "subnet.create",
+    "subnet.move",
+    "subnet.dissolve",
+];
+/** Apply one operation and return what it changed, in JSON-ready form. */
+export function applyOperation(editor, operation) {
+    switch (operation.op) {
+        case "node.add":
+            return editor.addNode({
+                module: operation.module,
+                ...(operation.id ? { id: operation.id } : {}),
+                ...(operation.in ? { parent: operation.in } : {}),
+                ...(operation.position ? { position: operation.position } : {}),
+                ...(operation.set ? { props: operation.set } : {}),
+                ...(operation.fromText ? { fromText: true } : {}),
+                ...(operation.comment ? { comment: operation.comment } : {}),
+            });
+        case "node.remove":
+            return editor.removeNode(operation.id, { recursive: operation.recursive === true });
+        case "connect":
+            return editor.connect(operation.from, operation.to, { layout: operation.layout !== false });
+        case "disconnect":
+            return operation.from ? editor.disconnect(operation.from, operation.to) : editor.disconnect(operation.to);
+        case "set": {
+            const { op: _op, target, ...change } = operation;
+            return editor.setParameter(target, change);
+        }
+        case "subnet.create":
+            return editor.createSubnet({
+                nodes: operation.nodes,
+                ...(operation.id ? { id: operation.id } : {}),
+                ...(operation.label ? { label: operation.label } : {}),
+            });
+        case "subnet.move":
+            return editor.moveNodes(operation.nodes, operation.to === "root" ? null : operation.to);
+        case "subnet.dissolve":
+            return editor.dissolveSubnet(operation.id);
+        default: {
+            const unknown = operation.op;
+            throw new Error(`Unknown edit operation ${JSON.stringify(unknown)}; expected one of ${GRAPH_EDIT_OPERATIONS.join(", ")}`);
+        }
+    }
+}
+//# sourceMappingURL=operations.js.map

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

@@ -0,0 +1,75 @@
+/**
+ * Setting one parameter: where its value lives in the document, what a typed
+ * value looks like, and how a value, an expression and a keyframe channel sit
+ * together on one prop.
+ *
+ * The stored shapes are the ones Studio writes and the runtime reads, nothing
+ * new: a plain value, or `{ value, expression?, channel? }` when the prop is
+ * bound (`Node.serializePropValue`, `contracts/animation.ts`). A data input's
+ * value goes in the node's `inputs`, as `{ name, defaultValue, dataType }`.
+ */
+import type { NodeDefinition } from "@field/cascade/contracts";
+import { type EditableNode } from "./document.js";
+import type { Interpolation } from "../animation/channel.js";
+export type { Interpolation };
+/** What `cascade set` can change on one parameter. Every field is optional. */
+export interface ParameterChange {
+    /**
+     * The new stored value. With `fromText`, a string as typed on a command line,
+     * read according to the parameter's declared type (`0.5`, `true`, `1,2`,
+     * `#ff8800`); otherwise a JSON value used as given.
+     */
+    readonly value?: unknown;
+    readonly fromText?: boolean;
+    /** An expression to bind, or `null` to remove the one there. */
+    readonly expression?: string | null;
+    /** Keyframes to set, replacing any key already at the same frame. */
+    readonly keys?: readonly {
+        frame: number;
+        value: number;
+    }[];
+    /** Frames whose keys are removed. */
+    readonly removeKeys?: readonly number[];
+    /** Interpolation for the keys being set. Studio's default is `smooth`. */
+    readonly interpolation?: Interpolation;
+    /** Forget the stored value and every binding: the parameter is back on its default. */
+    readonly unset?: boolean;
+}
+export type ParameterField = "props" | "inputs";
+export interface ParameterSlot {
+    readonly field: ParameterField;
+    readonly type: string | undefined;
+    /** The declared default, `undefined` when there is none or the node is undeclared. */
+    readonly default: unknown;
+    readonly hasDefault: boolean;
+    /** Declared with a default expression, so storing a plain value is a decision even when it equals the default. */
+    readonly defaultExpression: boolean;
+    readonly options: readonly unknown[] | undefined;
+}
+/**
+ * Where a parameter is stored, from the node's definition. Props first, then
+ * data inputs. Unknown names are an error with the list of real ones, because
+ * a typo stored under a name nothing declares is dropped on load — the
+ * `runtime/unknown-props` failure, which renders on defaults and reports success.
+ */
+export declare function parameterSlot(definition: NodeDefinition | undefined, name: string): ParameterSlot | {
+    error: string;
+};
+/**
+ * Apply a change to one parameter of `node`. Returns what was stored before
+ * and after (`undefined` = nothing stored, the default applies), so a caller
+ * can report the change and undo it.
+ */
+export declare function applyParameterChange(node: EditableNode, name: string, slot: ParameterSlot, change: ParameterChange): {
+    before: unknown;
+    after: unknown;
+};
+/** The value as stored in the document, or `undefined` when nothing is. */
+export declare function readStored(node: EditableNode, name: string, field: ParameterField): unknown;
+/**
+ * A value of the declared type, or an error naming what was expected. Text
+ * from a command line is read by type, so `cascade set g text.content 300`
+ * stores the string "300" while `scale 300` stores a number.
+ */
+export declare function coerceValue(raw: unknown, slot: ParameterSlot, fromText: boolean, where: string): unknown;
+//# sourceMappingURL=parameters.d.ts.map

package/dist/runtime/edit/parameters.js

@@ -0,0 +1,284 @@
+/**
+ * Setting one parameter: where its value lives in the document, what a typed
+ * value looks like, and how a value, an expression and a keyframe channel sit
+ * together on one prop.
+ *
+ * The stored shapes are the ones Studio writes and the runtime reads, nothing
+ * new: a plain value, or `{ value, expression?, channel? }` when the prop is
+ * bound (`Node.serializePropValue`, `contracts/animation.ts`). A data input's
+ * value goes in the node's `inputs`, as `{ name, defaultValue, dataType }`.
+ */
+import { jsonEqual, setOrderedKey, NODE_KEY_ORDER } from "./document.js";
+/**
+ * Where a parameter is stored, from the node's definition. Props first, then
+ * data inputs. Unknown names are an error with the list of real ones, because
+ * a typo stored under a name nothing declares is dropped on load — the
+ * `runtime/unknown-props` failure, which renders on defaults and reports success.
+ */
+export function parameterSlot(definition, name) {
+    if (!definition) {
+        return { field: "props", type: undefined, default: undefined, hasDefault: false, defaultExpression: false, options: undefined };
+    }
+    const prop = definition.props?.[name];
+    if (prop) {
+        return {
+            field: "props",
+            type: String(prop.type),
+            default: prop.default,
+            hasDefault: "default" in prop,
+            defaultExpression: typeof prop.expression === "string",
+            options: Array.isArray(prop.options) ? prop.options.map(optionValue) : undefined,
+        };
+    }
+    const input = definition.inputs?.[name];
+    if (input && input.kind === "data") {
+        return {
+            field: "inputs",
+            type: String(input.type),
+            default: input.default,
+            hasDefault: "default" in input,
+            defaultExpression: false,
+            options: Array.isArray(input.options) ? input.options.map(optionValue) : undefined,
+        };
+    }
+    const props = Object.keys(definition.props ?? {});
+    const inputs = Object.entries(definition.inputs ?? {})
+        .filter(([, port]) => port.kind === "data")
+        .map(([portName]) => portName);
+    return {
+        error: `has no parameter "${name}"` +
+            (props.length ? `; props: ${props.join(", ")}` : "") +
+            (inputs.length ? `; inputs: ${inputs.join(", ")}` : ""),
+    };
+}
+/**
+ * Apply a change to one parameter of `node`. Returns what was stored before
+ * and after (`undefined` = nothing stored, the default applies), so a caller
+ * can report the change and undo it.
+ */
+export function applyParameterChange(node, name, slot, change) {
+    if (slot.field === "inputs" && (change.expression !== undefined || change.keys?.length || change.removeKeys?.length)) {
+        throw new Error(`${node.id}.${name} is an input; expressions and keyframes bind props only. Wire a node into it instead.`);
+    }
+    const before = readStored(node, name, slot.field);
+    if (change.unset) {
+        writeStored(node, name, slot.field, undefined, slot);
+        return { before, after: undefined };
+    }
+    let binding = toBinding(before, slot);
+    if (change.value !== undefined) {
+        binding = { ...binding, value: coerceValue(change.value, slot, change.fromText === true, `${node.id}.${name}`) };
+    }
+    if (change.expression !== undefined) {
+        binding = { ...binding, expression: change.expression || undefined };
+    }
+    if (change.keys?.length || change.removeKeys?.length) {
+        binding = { ...binding, keys: updateKeys(binding.keys, change) };
+    }
+    const after = fromBinding(binding, slot);
+    writeStored(node, name, slot.field, after, slot);
+    return { before, after: readStored(node, name, slot.field) };
+}
+/** The value as stored in the document, or `undefined` when nothing is. */
+export function readStored(node, name, field) {
+    if (field === "props")
+        return node.props?.[name];
+    const inputs = node.inputs;
+    if (Array.isArray(inputs)) {
+        const entry = inputs.find((item) => item?.name === name);
+        return entry ? ("defaultValue" in entry ? entry.defaultValue : entry.value) : undefined;
+    }
+    return inputs && typeof inputs === "object" ? inputs[name] : undefined;
+}
+function isBoundValue(stored) {
+    return !!stored && typeof stored === "object" && !Array.isArray(stored) &&
+        "value" in stored && ("expression" in stored || "channel" in stored);
+}
+function toBinding(stored, slot) {
+    if (isBoundValue(stored)) {
+        return {
+            value: stored.value,
+            expression: stored.expression,
+            keys: Array.isArray(stored.channel?.keys) ? stored.channel.keys : [],
+        };
+    }
+    return { value: stored === undefined ? slot.default : stored, keys: [] };
+}
+/**
+ * The stored form of a binding, or `undefined` when there is nothing worth
+ * storing: a plain value equal to the declared default is not written, the way
+ * Studio writes only the parameters that differ. The exception is a prop
+ * declared with a default expression, where a stored plain value is what turns
+ * that expression off.
+ */
+function fromBinding(binding, slot) {
+    if (binding.expression || binding.keys.length) {
+        return {
+            value: binding.value,
+            ...(binding.expression ? { expression: binding.expression } : {}),
+            ...(binding.keys.length ? { channel: { keys: binding.keys } } : {}),
+        };
+    }
+    if (binding.value === undefined)
+        return undefined;
+    if (slot.hasDefault && !slot.defaultExpression && jsonEqual(binding.value, slot.default))
+        return undefined;
+    return binding.value;
+}
+function updateKeys(keys, change) {
+    const byFrame = new Map(keys.map((key) => [key.frame, key]));
+    for (const frame of change.removeKeys ?? [])
+        byFrame.delete(frame);
+    for (const key of change.keys ?? []) {
+        if (!Number.isFinite(key.frame) || !Number.isFinite(key.value)) {
+            throw new Error(`A keyframe needs a numeric frame and value (got ${key.frame}=${key.value})`);
+        }
+        const interpolation = change.interpolation ?? byFrame.get(key.frame)?.interpolation;
+        byFrame.set(key.frame, interpolation && interpolation !== "smooth"
+            ? { frame: key.frame, value: key.value, interpolation }
+            : { frame: key.frame, value: key.value });
+    }
+    return [...byFrame.values()].sort((a, b) => a.frame - b.frame);
+}
+function writeStored(node, name, field, value, slot) {
+    if (field === "props") {
+        const props = node.props ?? {};
+        if (value === undefined)
+            delete props[name];
+        else
+            props[name] = value;
+        if (Object.keys(props).length)
+            setOrderedKey(node, "props", props, NODE_KEY_ORDER);
+        else
+            delete node.props;
+        return;
+    }
+    const inputs = node.inputs;
+    if (inputs && typeof inputs === "object" && !Array.isArray(inputs)) {
+        const record = inputs;
+        if (value === undefined)
+            delete record[name];
+        else
+            record[name] = value;
+        if (!Object.keys(record).length)
+            delete node.inputs;
+        return;
+    }
+    // Studio's array form, `{ name, defaultValue, dataType }`.
+    const list = Array.isArray(inputs) ? inputs : [];
+    const at = list.findIndex((item) => item?.name === name);
+    if (value === undefined) {
+        if (at !== -1)
+            list.splice(at, 1);
+    }
+    else if (at !== -1) {
+        const entry = list[at];
+        const key = "value" in entry && !("defaultValue" in entry) ? "value" : "defaultValue";
+        list[at] = { ...entry, [key]: value };
+    }
+    else {
+        list.push({ name, defaultValue: value, ...(slot.type ? { dataType: slot.type } : {}) });
+    }
+    if (list.length)
+        setOrderedKey(node, "inputs", list, NODE_KEY_ORDER);
+    else
+        delete node.inputs;
+}
+/**
+ * A value of the declared type, or an error naming what was expected. Text
+ * from a command line is read by type, so `cascade set g text.content 300`
+ * stores the string "300" while `scale 300` stores a number.
+ */
+export function coerceValue(raw, slot, fromText, where) {
+    const type = slot.type;
+    let value = raw;
+    if (fromText && typeof raw === "string") {
+        value = type === "string" ? unquote(raw) : parseText(raw, type);
+    }
+    if (!type)
+        return value;
+    const fail = (expected) => {
+        throw new Error(`${where} expects ${expected} (got ${JSON.stringify(value)})`);
+    };
+    switch (type) {
+        case "float":
+            if (typeof value !== "number" || !Number.isFinite(value))
+                fail("a number");
+            break;
+        case "int":
+            if (typeof value !== "number" || !Number.isInteger(value))
+                fail("an integer");
+            break;
+        case "bool":
+            if (typeof value !== "boolean")
+                fail("true or false");
+            break;
+        case "string":
+            if (typeof value !== "string")
+                value = String(value);
+            break;
+        case "color":
+            value = colorValue(value) ?? fail("a colour: #rrggbb, #rrggbbaa or [r, g, b, a] in 0..1");
+            break;
+        default: {
+            const size = /^(?:vec|mat)(\d)i?$/.exec(type);
+            if (size) {
+                const length = type.startsWith("mat") ? Number(size[1]) ** 2 : Number(size[1]);
+                if (!Array.isArray(value) || value.length !== length || !value.every((n) => typeof n === "number" && Number.isFinite(n))) {
+                    fail(`${length} numbers, e.g. ${Array.from({ length }, () => "0").join(",")}`);
+                }
+                if (type.endsWith("i") && !value.every(Number.isInteger))
+                    fail(`${length} integers`);
+            }
+        }
+    }
+    if (slot.options && !slot.options.some((option) => jsonEqual(option, value))) {
+        fail(`one of ${slot.options.map((option) => JSON.stringify(option)).join(", ")}`);
+    }
+    return value;
+}
+function parseText(text, type) {
+    const trimmed = text.trim();
+    if (type && /^(?:vec|mat)\d/.test(type) && !trimmed.startsWith("[")) {
+        return trimmed.split(",").map((part) => Number(part.trim()));
+    }
+    if (type === "color" && trimmed.startsWith("#"))
+        return trimmed;
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return trimmed;
+    }
+}
+function unquote(text) {
+    if (text.length >= 2 && text.startsWith('"') && text.endsWith('"')) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    return text;
+}
+/** `[r, g, b, a]` in 0..1, Studio's stored colour. Hex is converted, rounded to four places. */
+function colorValue(value) {
+    if (typeof value === "string") {
+        const hex = /^#([0-9a-f]{6})([0-9a-f]{2})?$/i.exec(value.trim());
+        if (!hex)
+            return null;
+        const digits = hex[1] + (hex[2] ?? "ff");
+        return [0, 2, 4, 6].map((at) => Math.round((parseInt(digits.slice(at, at + 2), 16) / 255) * 10000) / 10000);
+    }
+    if (Array.isArray(value) && (value.length === 3 || value.length === 4) && value.every((n) => typeof n === "number")) {
+        return value.length === 3 ? [...value, 1] : [...value];
+    }
+    return null;
+}
+function optionValue(option) {
+    return option && typeof option === "object" && !Array.isArray(option) && "value" in option
+        ? option.value
+        : option;
+}
+//# sourceMappingURL=parameters.js.map