@field/cascade 0.8.0 → 0.11.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/builtins/headless.d.ts

@@ -0,0 +1,19 @@
+import type { DefinitionNodeRegistration } from "../types.js";
+/**
+ * Built-ins the headless host knows and Studio does not yet: today only
+ * `cascade.image.ContactSheet`.
+ *
+ * A separate list rather than a line in `builtinNodeRegistrations` because
+ * that list is in Studio's first-paint bundle (the runtime and the Definition
+ * panel both import it), and the bundle budget has no room for a node Studio
+ * does not register. The CLI passes these to the runtime as ordinary
+ * registrations. When Studio registers the image nodes, they move into
+ * `index.ts` and this file goes.
+ */
+export declare const headlessOnlyNodeRegistrations: readonly DefinitionNodeRegistration[];
+/** Every built-in the headless host can run. */
+export declare const headlessNodeRegistrations: readonly DefinitionNodeRegistration[];
+/** A headless-only built-in, which the runtime does not know unless it is passed in. */
+export declare function headlessOnlyNodeRegistration(moduleId: string): DefinitionNodeRegistration | undefined;
+export declare function headlessNodeRegistration(moduleId: string): DefinitionNodeRegistration | undefined;
+//# sourceMappingURL=headless.d.ts.map

package/dist/runtime/builtins/headless.js

@@ -0,0 +1,25 @@
+import { builtinNodeRegistration, builtinNodeRegistrations } from "./index.js";
+import { imageNodeRegistrations } from "./image/index.js";
+/**
+ * Built-ins the headless host knows and Studio does not yet: today only
+ * `cascade.image.ContactSheet`.
+ *
+ * A separate list rather than a line in `builtinNodeRegistrations` because
+ * that list is in Studio's first-paint bundle (the runtime and the Definition
+ * panel both import it), and the bundle budget has no room for a node Studio
+ * does not register. The CLI passes these to the runtime as ordinary
+ * registrations. When Studio registers the image nodes, they move into
+ * `index.ts` and this file goes.
+ */
+export const headlessOnlyNodeRegistrations = Object.freeze([...imageNodeRegistrations]);
+/** Every built-in the headless host can run. */
+export const headlessNodeRegistrations = Object.freeze([...builtinNodeRegistrations, ...headlessOnlyNodeRegistrations]);
+const headlessOnlyById = new Map(headlessOnlyNodeRegistrations.map((registration) => [registration.moduleId, registration]));
+/** A headless-only built-in, which the runtime does not know unless it is passed in. */
+export function headlessOnlyNodeRegistration(moduleId) {
+    return headlessOnlyById.get(moduleId);
+}
+export function headlessNodeRegistration(moduleId) {
+    return builtinNodeRegistration(moduleId) ?? headlessOnlyById.get(moduleId);
+}
+//# sourceMappingURL=headless.js.map

package/dist/runtime/builtins/image/contactSheet.d.ts

@@ -0,0 +1,226 @@
+import type { NodeExecutionContext } from "@field/cascade/contracts";
+/**
+ * `cascade.image.ContactSheet` — several images as one labelled grid.
+ *
+ * The selection loop is a ladder of three to five options and a pick, and the
+ * pick is made by looking at them side by side. So the sheet is a node rather
+ * than a script beside the graph: a graph can end in one, and `cascade ladder`
+ * lays out its variants with the same layout and drawing code below.
+ *
+ * `portable` with `assets`, like `cascade.geo.Render`: it reads each image
+ * through the asset capability, decodes it with `createImageBitmap` and draws
+ * on an `OffscreenCanvas`, which both hosts supply (the headless one through
+ * @napi-rs/canvas). It lives in `cascade.image.*` beside Studio's image
+ * library, as the first definition-v1 node there; Studio does not register it
+ * yet, so today it runs headless and is listed in `../headless.ts` rather
+ * than in the built-ins Studio bundles.
+ */
+export declare const contactSheetDefinition: {
+    readonly apiVersion: 1;
+    readonly label: "Contact Sheet";
+    readonly description: "Lay images out as one labelled grid.";
+    readonly icon: "LayoutGrid";
+    readonly runsOn: "portable";
+    readonly capabilities: readonly ["assets"];
+    readonly inputs: {
+        readonly images: {
+            readonly kind: "data";
+            readonly type: "image";
+            readonly variadic: true;
+        };
+        /** More images after the wired ones: image values or project-relative paths. */
+        readonly list: {
+            readonly kind: "data";
+            readonly type: "array";
+        };
+    };
+    readonly outputs: {
+        readonly image: {
+            readonly kind: "data";
+            readonly type: "image";
+        };
+        readonly asset: {
+            readonly kind: "data";
+            readonly type: "asset";
+        };
+    };
+    readonly props: {
+        readonly columns: {
+            readonly type: "int";
+            readonly default: 0;
+            readonly min: 0;
+            readonly max: 64;
+            readonly description: "0: as square as the count allows.";
+        };
+        readonly gap: {
+            readonly type: "int";
+            readonly default: 16;
+            readonly min: 0;
+            readonly max: 512;
+        };
+        readonly background: {
+            readonly type: "color";
+            readonly default: readonly [1, 1, 1, 1];
+            readonly label: "Background";
+        };
+        readonly cellWidth: {
+            readonly type: "int";
+            readonly default: 0;
+            readonly min: 0;
+            readonly max: 8192;
+            readonly description: "0: images at their own size. Otherwise each is scaled to fit this width.";
+        };
+        readonly labels: {
+            readonly type: "string";
+            readonly default: "";
+            readonly description: "One label per line, in image order.";
+        };
+        readonly labelSize: {
+            readonly type: "int";
+            readonly default: 14;
+            readonly min: 6;
+            readonly max: 128;
+        };
+        readonly labelColor: {
+            readonly type: "color";
+            readonly default: readonly [0.1, 0.1, 0.1, 1];
+            readonly label: "Label Colour";
+        };
+        readonly filename: {
+            readonly type: "string";
+            readonly default: "contact-sheet.png";
+            readonly label: "Filename";
+        };
+    };
+};
+export interface ContactSheetOptions {
+    readonly columns?: number;
+    readonly gap?: number;
+    readonly cellWidth?: number;
+    readonly labels?: readonly string[];
+    readonly labelSize?: number;
+    /** RGBA, 0 to 1. */
+    readonly background?: readonly number[];
+    readonly labelColor?: readonly number[];
+}
+export interface SheetCell {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    /** Top-left of the label line. */
+    readonly labelX: number;
+    readonly labelY: number;
+}
+export interface SheetLayout {
+    readonly width: number;
+    readonly height: number;
+    readonly columns: number;
+    readonly rows: number;
+    readonly cell: readonly [number, number];
+    readonly labelHeight: number;
+    readonly cells: readonly SheetCell[];
+}
+/**
+ * Where each image goes. By default every cell is as wide as the widest image
+ * and as tall as the tallest, and images keep their size. With `cellWidth`,
+ * cells are that wide and as tall as the tallest image needs at that width,
+ * and each image is scaled to fit. Either way an image is centred in its cell
+ * and never cropped, in whole pixels, so a sheet is the same bytes every run.
+ */
+export declare function contactSheetLayout(sizes: readonly (readonly [number, number])[], options?: {
+    columns?: number;
+    gap?: number;
+    cellWidth?: number;
+    labelHeight?: number;
+}): SheetLayout;
+/** Encoded images (PNG, JPEG, WebP) in, one PNG sheet out. */
+export declare function composeContactSheet(images: readonly Uint8Array[], options?: ContactSheetOptions): Promise<{
+    bytes: Uint8Array;
+    layout: SheetLayout;
+}>;
+export declare function executeContactSheet(context: NodeExecutionContext<typeof contactSheetDefinition>): Promise<void>;
+export declare const contactSheetRegistration: {
+    kind: "definition-v1";
+    moduleId: string;
+    definition: {
+        readonly apiVersion: 1;
+        readonly label: "Contact Sheet";
+        readonly description: "Lay images out as one labelled grid.";
+        readonly icon: "LayoutGrid";
+        readonly runsOn: "portable";
+        readonly capabilities: readonly ["assets"];
+        readonly inputs: {
+            readonly images: {
+                readonly kind: "data";
+                readonly type: "image";
+                readonly variadic: true;
+            };
+            /** More images after the wired ones: image values or project-relative paths. */
+            readonly list: {
+                readonly kind: "data";
+                readonly type: "array";
+            };
+        };
+        readonly outputs: {
+            readonly image: {
+                readonly kind: "data";
+                readonly type: "image";
+            };
+            readonly asset: {
+                readonly kind: "data";
+                readonly type: "asset";
+            };
+        };
+        readonly props: {
+            readonly columns: {
+                readonly type: "int";
+                readonly default: 0;
+                readonly min: 0;
+                readonly max: 64;
+                readonly description: "0: as square as the count allows.";
+            };
+            readonly gap: {
+                readonly type: "int";
+                readonly default: 16;
+                readonly min: 0;
+                readonly max: 512;
+            };
+            readonly background: {
+                readonly type: "color";
+                readonly default: readonly [1, 1, 1, 1];
+                readonly label: "Background";
+            };
+            readonly cellWidth: {
+                readonly type: "int";
+                readonly default: 0;
+                readonly min: 0;
+                readonly max: 8192;
+                readonly description: "0: images at their own size. Otherwise each is scaled to fit this width.";
+            };
+            readonly labels: {
+                readonly type: "string";
+                readonly default: "";
+                readonly description: "One label per line, in image order.";
+            };
+            readonly labelSize: {
+                readonly type: "int";
+                readonly default: 14;
+                readonly min: 6;
+                readonly max: 128;
+            };
+            readonly labelColor: {
+                readonly type: "color";
+                readonly default: readonly [0.1, 0.1, 0.1, 1];
+                readonly label: "Label Colour";
+            };
+            readonly filename: {
+                readonly type: "string";
+                readonly default: "contact-sheet.png";
+                readonly label: "Filename";
+            };
+        };
+    };
+    loadExecute: () => Promise<typeof executeContactSheet>;
+};
+//# sourceMappingURL=contactSheet.d.ts.map

package/dist/runtime/builtins/image/contactSheet.js

@@ -0,0 +1,199 @@
+/**
+ * `cascade.image.ContactSheet` — several images as one labelled grid.
+ *
+ * The selection loop is a ladder of three to five options and a pick, and the
+ * pick is made by looking at them side by side. So the sheet is a node rather
+ * than a script beside the graph: a graph can end in one, and `cascade ladder`
+ * lays out its variants with the same layout and drawing code below.
+ *
+ * `portable` with `assets`, like `cascade.geo.Render`: it reads each image
+ * through the asset capability, decodes it with `createImageBitmap` and draws
+ * on an `OffscreenCanvas`, which both hosts supply (the headless one through
+ * @napi-rs/canvas). It lives in `cascade.image.*` beside Studio's image
+ * library, as the first definition-v1 node there; Studio does not register it
+ * yet, so today it runs headless and is listed in `../headless.ts` rather
+ * than in the built-ins Studio bundles.
+ */
+export const contactSheetDefinition = {
+    apiVersion: 1,
+    label: "Contact Sheet",
+    description: "Lay images out as one labelled grid.",
+    icon: "LayoutGrid",
+    runsOn: "portable",
+    capabilities: ["assets"],
+    inputs: {
+        images: { kind: "data", type: "image", variadic: true },
+        /** More images after the wired ones: image values or project-relative paths. */
+        list: { kind: "data", type: "array" },
+    },
+    outputs: {
+        image: { kind: "data", type: "image" },
+        asset: { kind: "data", type: "asset" },
+    },
+    props: {
+        columns: { type: "int", default: 0, min: 0, max: 64, description: "0: as square as the count allows." },
+        gap: { type: "int", default: 16, min: 0, max: 512 },
+        background: { type: "color", default: [1, 1, 1, 1], label: "Background" },
+        cellWidth: { type: "int", default: 0, min: 0, max: 8192, description: "0: images at their own size. Otherwise each is scaled to fit this width." },
+        labels: { type: "string", default: "", description: "One label per line, in image order." },
+        labelSize: { type: "int", default: 14, min: 6, max: 128 },
+        labelColor: { type: "color", default: [0.1, 0.1, 0.1, 1], label: "Label Colour" },
+        filename: { type: "string", default: "contact-sheet.png", label: "Filename" },
+    },
+};
+/**
+ * Where each image goes. By default every cell is as wide as the widest image
+ * and as tall as the tallest, and images keep their size. With `cellWidth`,
+ * cells are that wide and as tall as the tallest image needs at that width,
+ * and each image is scaled to fit. Either way an image is centred in its cell
+ * and never cropped, in whole pixels, so a sheet is the same bytes every run.
+ */
+export function contactSheetLayout(sizes, options = {}) {
+    const count = sizes.length;
+    if (!count)
+        throw new Error("cascade.image.ContactSheet needs at least one image");
+    for (const [width, height] of sizes) {
+        if (!(width > 0 && height > 0))
+            throw new Error(`cascade.image.ContactSheet: an image is ${width}x${height}`);
+    }
+    const gap = Math.max(0, Math.round(options.gap ?? 16));
+    const columns = Math.min(count, options.columns && options.columns > 0 ? Math.round(options.columns) : Math.ceil(Math.sqrt(count)));
+    const rows = Math.ceil(count / columns);
+    const scaled = Boolean(options.cellWidth && options.cellWidth > 0);
+    const cellWidth = scaled ? Math.round(options.cellWidth) : Math.max(...sizes.map(([width]) => width));
+    const cellHeight = scaled
+        ? Math.max(...sizes.map(([width, height]) => Math.round((height * cellWidth) / width)))
+        : Math.max(...sizes.map(([, height]) => height));
+    const labelHeight = Math.max(0, Math.round(options.labelHeight ?? 0));
+    const cells = sizes.map(([width, height], index) => {
+        const column = index % columns;
+        const row = Math.floor(index / columns);
+        // Native size unless a cell width was asked for; never cropped.
+        const fit = Math.min(cellWidth / width, cellHeight / height);
+        const scale = scaled ? fit : Math.min(1, fit);
+        const drawnWidth = Math.max(1, Math.round(width * scale));
+        const drawnHeight = Math.max(1, Math.round(height * scale));
+        const left = gap + column * (cellWidth + gap);
+        const top = gap + row * (cellHeight + labelHeight + gap);
+        return {
+            x: left + Math.floor((cellWidth - drawnWidth) / 2),
+            y: top + Math.floor((cellHeight - drawnHeight) / 2),
+            width: drawnWidth,
+            height: drawnHeight,
+            labelX: left,
+            labelY: top + cellHeight,
+        };
+    });
+    return {
+        width: gap + columns * (cellWidth + gap),
+        height: gap + rows * (cellHeight + labelHeight + gap),
+        columns,
+        rows,
+        cell: [cellWidth, cellHeight],
+        labelHeight,
+        cells,
+    };
+}
+/** The host's canvas, read here and nowhere else (see `cascade.geo.Render`). */
+function host() {
+    const globals = globalThis;
+    const Canvas = globals.OffscreenCanvas;
+    const createBitmap = globals.createImageBitmap;
+    if (!Canvas || !createBitmap || !globals.Blob) {
+        throw new Error("cascade.image.ContactSheet needs OffscreenCanvas and createImageBitmap, which this host does not provide");
+    }
+    const BlobType = globals.Blob;
+    return {
+        surface: (width, height) => new Canvas(width, height),
+        decode: (bytes) => createBitmap(new BlobType([bytes])),
+    };
+}
+function css(colour, fallback) {
+    const [r = 0, g = 0, b = 0, a = 1] = colour ?? fallback;
+    return `rgba(${Math.round(r * 255)}, ${Math.round(g * 255)}, ${Math.round(b * 255)}, ${a})`;
+}
+/** Encoded images (PNG, JPEG, WebP) in, one PNG sheet out. */
+export async function composeContactSheet(images, options = {}) {
+    const canvas = host();
+    const bitmaps = [];
+    try {
+        for (const bytes of images)
+            bitmaps.push(await canvas.decode(bytes));
+        const labels = options.labels ?? [];
+        const labelSize = Math.round(options.labelSize ?? 14);
+        const labelled = labels.some((label) => label.trim().length > 0);
+        const layout = contactSheetLayout(bitmaps.map((bitmap) => [bitmap.width, bitmap.height]), {
+            columns: options.columns,
+            gap: options.gap,
+            cellWidth: options.cellWidth,
+            labelHeight: labelled ? Math.round(labelSize * 1.8) : 0,
+        });
+        const surface = canvas.surface(layout.width, layout.height);
+        const context = surface.getContext("2d");
+        if (!context)
+            throw new Error("cascade.image.ContactSheet: no 2D context");
+        context.fillStyle = css(options.background, [1, 1, 1, 1]);
+        context.fillRect(0, 0, layout.width, layout.height);
+        context.imageSmoothingEnabled = true;
+        context.imageSmoothingQuality = "high";
+        layout.cells.forEach((cell, index) => context.drawImage(bitmaps[index], cell.x, cell.y, cell.width, cell.height));
+        if (labelled) {
+            context.fillStyle = css(options.labelColor, [0.1, 0.1, 0.1, 1]);
+            context.font = `${labelSize}px sans-serif`;
+            context.textBaseline = "top";
+            layout.cells.forEach((cell, index) => {
+                const label = labels[index];
+                if (label)
+                    context.fillText(label, cell.labelX, cell.labelY + Math.round((layout.labelHeight - labelSize) / 2), layout.cell[0]);
+            });
+        }
+        const blob = await surface.convertToBlob({ type: "image/png" });
+        return { bytes: new Uint8Array(await blob.arrayBuffer()), layout };
+    }
+    finally {
+        for (const bitmap of bitmaps)
+            bitmap.close?.();
+    }
+}
+/** An image value or a path, as the asset reference to read it by. */
+function imageReference(value) {
+    if (typeof value === "string" && value)
+        return { path: value };
+    const candidate = value?.path;
+    return typeof candidate === "string" && candidate ? { path: candidate } : undefined;
+}
+export async function executeContactSheet(context) {
+    const { props } = context;
+    const references = [...context.inputs.images, ...(context.inputs.list ?? [])]
+        .map(imageReference)
+        .filter((reference) => reference !== undefined);
+    const bytes = [];
+    for (const reference of references) {
+        bytes.push(await context.capabilities.assets.read(reference, { signal: context.signal }));
+    }
+    const { bytes: sheet, layout } = await composeContactSheet(bytes, {
+        columns: props.columns,
+        gap: props.gap,
+        cellWidth: props.cellWidth,
+        labels: props.labels ? props.labels.split("\n") : [],
+        labelSize: props.labelSize,
+        background: props.background,
+        labelColor: props.labelColor,
+    });
+    const asset = await context.capabilities.assets.write(sheet, { mediaType: "image/png", suggestedName: props.filename }, { signal: context.signal });
+    context.outputs.asset.set(asset);
+    context.outputs.image.set({
+        path: asset.path ?? props.filename,
+        size: [layout.width, layout.height],
+        channels: "rgba",
+        depth: "u8",
+        space: "srgb",
+    });
+}
+export const contactSheetRegistration = {
+    kind: "definition-v1",
+    moduleId: "cascade.image.ContactSheet",
+    definition: contactSheetDefinition,
+    loadExecute: async () => executeContactSheet,
+};
+//# sourceMappingURL=contactSheet.js.map

package/dist/runtime/builtins/image/index.d.ts

@@ -0,0 +1,9 @@
+import type { DefinitionNodeRegistration } from "../../types.js";
+/**
+ * The definition-v1 image nodes. One so far: the contact sheet a ladder of
+ * variants is judged on. Studio's `cascade.image.*` library (src/nodes/image)
+ * is the compatibility engine's and is not listed here.
+ */
+export { composeContactSheet, contactSheetDefinition, contactSheetLayout, contactSheetRegistration, executeContactSheet, type ContactSheetOptions, type SheetLayout, } from "./contactSheet.js";
+export declare const imageNodeRegistrations: readonly DefinitionNodeRegistration[];
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/builtins/image/index.js

@@ -0,0 +1,9 @@
+import { contactSheetRegistration } from "./contactSheet.js";
+/**
+ * The definition-v1 image nodes. One so far: the contact sheet a ladder of
+ * variants is judged on. Studio's `cascade.image.*` library (src/nodes/image)
+ * is the compatibility engine's and is not listed here.
+ */
+export { composeContactSheet, contactSheetDefinition, contactSheetLayout, contactSheetRegistration, executeContactSheet, } from "./contactSheet.js";
+export const imageNodeRegistrations = Object.freeze([contactSheetRegistration]);
+//# sourceMappingURL=index.js.map

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