@theclearsky/react-blender-nodes 0.0.10 → 0.0.13

package/dist/contract.d.ts

@@ -0,0 +1,1119 @@
+import { ComponentProps } from 'react';
+import { ControlLinePosition } from '@xyflow/react';
+import { ControlPosition } from '@xyflow/react';
+import { Edge } from '@xyflow/react';
+import { HTMLAttributes } from 'react';
+import { Node as Node_2 } from '@xyflow/react';
+import { NodeProps } from '@xyflow/react';
+import { NodeResizeControl } from '@xyflow/react';
+import { NodeResizerProps } from '@xyflow/react';
+import { Patch } from 'immer';
+import { ReactNode } from 'react';
+import { Viewport } from '@xyflow/react';
+import { XYPosition } from '@xyflow/react';
+import { z } from 'zod';
+
+/**
+ * Currently open drawer. UI-only state — stripped during export.
+ * Managed by OPEN_DRAWER / CLOSE_DRAWER actions.
+ */
+declare type ActiveDrawer = {
+    type: 'editLoop';
+    nodeId: string;
+} | {
+    type: 'editNodeType';
+    nodeTypeId: string;
+} | {
+    type: 'editSwitch';
+    nodeId: string;
+} | {
+    type: 'editGraphInput';
+    nodeId: string;
+} | {
+    type: 'editGraphOutput';
+    nodeId: string;
+} | null;
+
+/**
+ * Mapping of allowed conversions between data types
+ *
+ * @template DataTypeUniqueId - Unique identifier type for data types
+ */
+declare type AllowedConversionsBetweenDataTypes<DataTypeUniqueId extends string = string> = Partial<Record<DataTypeUniqueId, Partial<Record<DataTypeUniqueId, boolean>>>>;
+
+/** Context for `artifact` targets: the read-only base data only. */
+export declare type ArtifactRunContext<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never> = RunTargetContextBase<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>;
+
+/** An `artifact` target: returns / downloads a file or string; no timeline. */
+export declare type ArtifactRunTarget<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never> = RunTargetIdentity & {
+    mode: 'artifact';
+    run: (context: ArtifactRunContext<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>) => Promise<void>;
+};
+
+/**
+ * Per-edge data carried on a configurable edge.
+ *
+ * `order` is the connection's rank WITHIN its target input handle's fan-in group
+ * — a contiguous `0..n-1` written across the group's sibling edges when the user
+ * reorders the connections (`REORDER_INPUT_CONNECTIONS`). It is absent on edges
+ * that have never been reordered; the compiler then falls back to the
+ * edges-array order, so existing graphs and the common single-connection case are
+ * unchanged. It is the only field the library itself persists on an edge today.
+ *
+ * The `& Record<string, unknown>` keeps the data bag OPEN — a consumer may still
+ * stash their own arbitrary keys on `edge.data` (as the prior
+ * `Record<string, unknown>` typing allowed), so adding the typed `order` is a
+ * purely additive, non-breaking change to the (internal) `ConfigurableEdgeState`.
+ */
+declare type ConfigurableEdgeData = {
+    order?: number;
+} & Record<string, unknown>;
+
+/** State type for configurable edges */
+declare type ConfigurableEdgeState = Edge<ConfigurableEdgeData, 'configurableEdge'>;
+
+/**
+ * Configuration for a node input
+ *
+ * Defines an input socket on a node with optional interactive input component.
+ * Supports both string and number types with type-specific onChange handlers.
+ */
+declare type ConfigurableNodeInput<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never, DataTypeUniqueId extends string = string> = {
+    /** Unique identifier for the input */
+    id: string;
+    /** Display name for the input */
+    name: string;
+    /** Color of the input handle/socket */
+    handleColor?: string;
+    /** Shape of the input handle (circle, square, diamond, etc.) */
+    handleShape?: HandleShape;
+    /** Whether to show an interactive input component when not connected */
+    allowInput?: boolean;
+    /** Maximum number of connections for this input */
+    maxConnections?: number;
+    /** Data type of the input, used by full graph */
+    dataType?: {
+        dataTypeObject: DataType<UnderlyingType, ComplexSchemaType>;
+        dataTypeUniqueId: DataTypeUniqueId;
+    };
+    /** Inferred data type of the input (only when type inference is enabled and datatype is inferredFromConnection and connected), used by full graph */
+    inferredDataType?: {
+        dataTypeObject: DataType<UnderlyingType, ComplexSchemaType>;
+        dataTypeUniqueId: DataTypeUniqueId;
+    } | null;
+} & ({
+    /** String input type */
+    type: 'string';
+    /** Current value of the input */
+    value?: string;
+    /** Callback when the input value changes */
+    onChange?: (value: string) => void;
+    /** When set, renders a select dropdown instead of a free-text input */
+    allowedStrings?: readonly string[];
+} | {
+    /** Number input type */
+    type: 'number';
+    /** Current value of the input */
+    value?: number;
+    /** Callback when the input value changes */
+    onChange?: (value: number) => void;
+} | {
+    /**  */
+    type: 'boolean';
+    /** Current value of the input */
+    value?: boolean;
+    /** Callback when the input value changes */
+    onChange?: (value: boolean) => void;
+} | {
+    /** Unsupported input type */
+    type: 'unsupportedDirectly';
+    /** Current value of the input */
+    value?: unknown;
+    /** Callback when the input value changes */
+    onChange?: (value: unknown) => void;
+});
+
+/**
+ * Configuration for a collapsible input panel
+ *
+ * Groups multiple inputs together in a collapsible panel for better organization.
+ */
+declare type ConfigurableNodeInputPanel<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never, DataTypeUniqueId extends string = string> = {
+    /** Unique identifier for the panel */
+    id: string;
+    /** Display name for the panel */
+    name: string;
+    /** Array of inputs contained in this panel */
+    inputs: ConfigurableNodeInput<UnderlyingType, ComplexSchemaType, DataTypeUniqueId>[];
+};
+
+/**
+ * Configuration for a node output
+ *
+ * Defines an output socket on a node that can be connected to inputs.
+ */
+declare type ConfigurableNodeOutput<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never, DataTypeUniqueId extends string = string> = {
+    /** Unique identifier for the output */
+    id: string;
+    /** Display name for the output */
+    name: string;
+    /** Color of the output handle/socket */
+    handleColor?: string;
+    /** Shape of the output handle (circle, square, diamond, etc.) */
+    handleShape?: HandleShape;
+    /** Maximum number of connections for this output */
+    maxConnections?: number;
+    /** Data type of the output, used by full graph */
+    dataType?: {
+        dataTypeObject: DataType<UnderlyingType, ComplexSchemaType>;
+        dataTypeUniqueId: DataTypeUniqueId;
+    };
+    /** Inferred data type of the output (only when type inference is enabled and datatype is inferredFromConnection and connected), used by full graph */
+    inferredDataType?: {
+        dataTypeObject: DataType<UnderlyingType, ComplexSchemaType>;
+        dataTypeUniqueId: DataTypeUniqueId;
+    } | null;
+} & ({
+    /** String output type */
+    type: 'string';
+} | {
+    /** Number output type */
+    type: 'number';
+} | {
+    /** Boolean output type */
+    type: 'boolean';
+} | {
+    /** Unsupported output type */
+    type: 'unsupportedDirectly';
+});
+
+/**
+ * Props for the ConfigurableNode component
+ *
+ * Defines the complete configuration for a customizable node with inputs, outputs,
+ * and optional panels. Supports both standalone usage and ReactFlow integration.
+ */
+declare type ConfigurableNodeProps<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, NodeTypeUniqueId extends string = string, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never, DataTypeUniqueId extends string = string> = {
+    /** Unique identifier for the node, for debugging when enableDebugMode is true and inside react flow */
+    id?: string;
+    /** Display name of the node */
+    name?: string;
+    /** Optional user-chosen instance name shown over the type name (standard nodes
+     *  only; absent = show the type name). */
+    customName?: string;
+    /** Whether this node instance's preview panel is collapsed (persisted on
+     *  `node.data`; absent = expanded). Only rendered when a `nodePreviews`
+     *  component is registered for this node type. */
+    previewCollapsed?: boolean;
+    /** Background color of the node header */
+    headerColor?: string;
+    /** Array of inputs and input panels */
+    inputs?: (ConfigurableNodeInput<UnderlyingType, ComplexSchemaType, DataTypeUniqueId> | ConfigurableNodeInputPanel<UnderlyingType, ComplexSchemaType, DataTypeUniqueId>)[];
+    /** Array of output sockets */
+    outputs?: ConfigurableNodeOutput<UnderlyingType, ComplexSchemaType, DataTypeUniqueId>[];
+    /** Whether the node is currently inside a ReactFlow context */
+    isCurrentlyInsideReactFlow?: boolean;
+    /** Props for the node resizer component */
+    nodeResizerProps?: NodeResizerWithMoreControlsProps;
+    /** Node type unique id */
+    nodeTypeUniqueId?: NodeTypeUniqueId;
+    /** Runner visual state for this node (undefined = no runner overlay) */
+    runnerVisualState?: NodeVisualState;
+    /** Errors from the runner for this node */
+    runnerErrors?: ReadonlyArray<GraphError>;
+    /** Warnings from the runner for this node (e.g., missing implementation) */
+    runnerWarnings?: ReadonlyArray<string>;
+} & HTMLAttributes<HTMLDivElement>;
+
+/** Props for the ConfigurableNodeReactFlowWrapper component */
+declare type ConfigurableNodeReactFlowWrapperProps<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, NodeTypeUniqueId extends string = string, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never, DataTypeUniqueId extends string = string> = NodeProps<ConfigurableNodeState<UnderlyingType, NodeTypeUniqueId, ComplexSchemaType, DataTypeUniqueId>> & {
+    position: XYPosition;
+};
+
+/** State type for configurable nodes in ReactFlow */
+declare type ConfigurableNodeState<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, NodeTypeUniqueId extends string = string, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never, DataTypeUniqueId extends string = string> = Node_2<Omit<ConfigurableNodeProps<UnderlyingType, NodeTypeUniqueId, ComplexSchemaType, DataTypeUniqueId>, 'isCurrentlyInsideReactFlow'>, 'configurableNode'>;
+
+/**
+ * Definition of a data type in the graph system
+ *
+ * @template UnderlyingType - The underlying type of the data
+ * @template ComplexSchemaType - Zod schema type for complex data types
+ */
+declare type DataType<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never> = UnderlyingType extends 'complex' ? {
+    /** Display name of the data type */
+    name: string;
+    /** The underlying type of the data */
+    underlyingType: UnderlyingType;
+    /** Zod schema for complex data validation */
+    complexSchema: ComplexSchemaType;
+    /** Color used for visual representation */
+    color: string;
+    /** Shape of the handle */
+    shape?: HandleShape;
+    /** Whether this input allows direct user input */
+    allowInput?: boolean;
+    /** Maximum number of connections for this data type */
+    maxConnections?: number;
+} : {
+    /** Display name of the data type */
+    name: string;
+    /** The underlying type of the data */
+    underlyingType: UnderlyingType;
+    /** Complex schema is not used for non-complex types */
+    complexSchema?: undefined;
+    /** Color used for visual representation */
+    color: string;
+    /** Shape of the handle */
+    shape?: HandleShape;
+    /** Whether this input allows direct user input */
+    allowInput?: boolean;
+    /** Maximum number of connections for this data type */
+    maxConnections?: number;
+    /** When set on a string type, renders a select dropdown instead of a free-text input. */
+    allowedStrings?: readonly string[];
+};
+
+/**
+ * Trigger a browser download of `text` as a file named `filename`.
+ *
+ * A tiny, library-free DOM helper that the built-in artifact run targets
+ * (`json-ir`, `codegen-js`) use to deliver their output. It is part of the
+ * public run-targets surface so a custom artifact target can reuse it instead of
+ * re-implementing blob/anchor plumbing — though a target is equally free to
+ * deliver its artifact another way (a callback, a network upload, …) inside its
+ * own `run`.
+ *
+ * No-op when there is no DOM (SSR / unit tests, or a browser without
+ * `URL.createObjectURL`) so invoking an artifact target's `run` never throws
+ * outside the browser.
+ */
+export declare function downloadTextArtifact(filename: string, text: string, mimeType?: string): void;
+
+/**
+ * Array of configurable edges in the graph
+ */
+declare type Edges = ConfigurableEdgeState[];
+
+/**
+ * The compiled execution plan — an intermediate representation
+ * of the graph ready for execution. Produced by the compiler,
+ * consumed by the executor.
+ *
+ * Steps are grouped into concurrency levels: all steps within
+ * a level have no data dependencies on each other and can
+ * execute concurrently via Promise.allSettled.
+ */
+export declare type ExecutionPlan = {
+    /**
+     * Steps grouped by concurrency level.
+     * levels[0] runs first, levels[1] after all of levels[0] complete, etc.
+     * Steps within the same level run concurrently.
+     */
+    levels: ReadonlyArray<ReadonlyArray<ExecutionStep>>;
+    /**
+     * Maps "nodeId:handleId" to the list of edges that feed into that input handle.
+     * Used by the executor to resolve input values from the ValueStore.
+     */
+    inputResolutionMap: ReadonlyMap<string, ReadonlyArray<InputResolutionEntry>>;
+    /**
+     * Maps "nodeId:handleId" to the list of edges that consume from that output handle.
+     * Used for building OutputHandleInfo for function implementations.
+     */
+    outputDistributionMap: ReadonlyMap<string, ReadonlyArray<OutputDistributionEntry>>;
+    /** Total number of executable nodes in the plan */
+    nodeCount: number;
+    /** Warnings generated during compilation (e.g., missing implementations) */
+    warnings: ReadonlyArray<string>;
+    /** Root-level Graph Input node id, when the graph declares its own inputs. Its
+     *  output handles are the program's parameters (fed by the executor's
+     *  `rootInputs` / codegen's `runGraph` params). Absent ⇒ no declared inputs. */
+    rootInputNodeId?: string;
+    /** Root-level Graph Output node id, when the graph declares its own outputs. Its
+     *  input handles are the program's return (collected as `rootOutputs` / codegen's
+     *  `runGraph` return). Absent ⇒ the whole value store is returned (compat). */
+    rootOutputNodeId?: string;
+};
+
+/**
+ * Discriminated union of all execution step types.
+ * Used in the ExecutionPlan's levels array.
+ */
+export declare type ExecutionStep = StandardExecutionStep | LoopExecutionBlock | SwitchExecutionBlock | GroupExecutionScope;
+
+/** Find the condition input handle on Loop Stop (the one with dataType 'condition'). */
+export declare function findConditionInputId(handles: ReadonlyArray<{
+    id?: string;
+    dataType?: {
+        dataTypeUniqueId?: string;
+    };
+    inferredDataType?: {
+        dataTypeUniqueId?: string;
+    } | null;
+}>): string | undefined;
+
+/**
+ * Flattens inputs (which may contain panels) into a flat array of
+ * individual input handles, preserving index order.
+ */
+export declare function flattenInputs(inputs: ReadonlyArray<MinimalInput | MinimalInputPanel> | undefined): MinimalInput[];
+
+/** Extract handle IDs for user data handles (not bindLoopNodes, loopInfer, or condition). */
+export declare function getDataHandleIds(handles: ReadonlyArray<{
+    id?: string;
+    dataType?: {
+        dataTypeUniqueId?: string;
+    };
+    inferredDataType?: {
+        dataTypeUniqueId?: string;
+    } | null;
+}>): string[];
+
+/**
+ * A rich error type capturing the full context of where and
+ * how an error occurred during graph execution.
+ *
+ * Includes the error message, the node that errored, the full
+ * execution path leading to it, and optional loop/group context.
+ */
+declare type GraphError = {
+    /** Human-readable error message */
+    message: string;
+    /** ID of the node where the error occurred */
+    nodeId: string;
+    /** Node type ID */
+    nodeTypeId: string;
+    /** Display name of the node type */
+    nodeTypeName: string;
+    /** Optional user-given custom display name (standard nodes only) */
+    customName?: string;
+    /** Handle ID where the error manifested (if applicable) */
+    handleId?: string;
+    /** Ordered list of nodes in the execution path leading to this error */
+    path: ReadonlyArray<GraphErrorPathEntry>;
+    /** Loop context (if the error occurred inside a loop) */
+    loopContext?: {
+        loopStructureId: string;
+        iteration: number;
+        maxIterations: number;
+    };
+    /** Group context (if the error occurred inside a node group) */
+    groupContext?: {
+        groupNodeId: string;
+        groupNodeTypeId: string;
+        depth: number;
+    };
+    /** Timestamp when the error occurred (performance.now() relative to run start) */
+    timestamp: number;
+    /** Duration of the step before the error (ms) */
+    duration: number;
+    /** The original thrown error value */
+    originalError: unknown;
+};
+
+/**
+ * One entry in the error's execution path trace,
+ * showing the chain of nodes that led to the error.
+ */
+declare type GraphErrorPathEntry = {
+    nodeId: string;
+    nodeTypeId: string;
+    nodeTypeName: string;
+    customName?: string;
+    handleId?: string;
+    concurrencyLevel: number;
+};
+
+/**
+ * A compiled node group scope containing the recursive inner execution plan
+ * and the handle mappings between outer and inner boundaries.
+ */
+export declare type GroupExecutionScope = {
+    kind: 'group';
+    /** The group node instance ID in the outer graph */
+    groupNodeId: string;
+    /** The group's node type ID (key in typeOfNodes) */
+    groupNodeTypeId: string;
+    /** Display name of the group node type */
+    groupNodeTypeName: string;
+    /** Recursively compiled execution plan for the subtree */
+    innerPlan: ExecutionPlan;
+    /** Map of outer input handle IDs to inner GroupInput output handle IDs */
+    inputMapping: ReadonlyMap<string, string>;
+    /** Map of inner GroupOutput input handle IDs to outer output handle IDs */
+    outputMapping: ReadonlyMap<string, string>;
+    concurrencyLevel: number;
+};
+
+/** Type representing all available handle shapes */
+declare type HandleShape = (typeof handleShapesMap)[keyof typeof handleShapesMap];
+
+/** Map of handle shapes for type-safe access */
+declare const handleShapesMap: {
+    readonly circle: "circle";
+    readonly square: "square";
+    readonly rectangle: "rectangle";
+    readonly list: "list";
+    readonly grid: "grid";
+    readonly diamond: "diamond";
+    readonly trapezium: "trapezium";
+    readonly hexagon: "hexagon";
+    readonly star: "star";
+    readonly cross: "cross";
+    readonly zigzag: "zigzag";
+    readonly sparkle: "sparkle";
+    readonly parallelogram: "parallelogram";
+};
+
+/**
+ * Configuration for the undo/redo history subsystem.
+ *
+ * @example
+ * ```ts
+ * const initialState = makeStateWithAutoInfer({
+ *   ...myState,
+ *   history: {
+ *     undoStack: [],
+ *     redoStack: [],
+ *     config: { maxSize: 100 },
+ *     activeBatch: null,
+ *   },
+ * });
+ * ```
+ */
+declare type HistoryConfig = {
+    /** Maximum number of undo entries. Undefined means unlimited. */
+    maxSize?: number;
+};
+
+/**
+ * A single entry in the undo/redo history.
+ *
+ * Stores the Immer patches that transition state forward (for redo)
+ * and backward (for undo). The actionType is stored for debugging
+ * and optional UI labeling (e.g., tooltip: "Undo Add Node").
+ *
+ * @example
+ * ```ts
+ * const entry: HistoryEntry = {
+ *   patches: [{ op: 'add', path: ['nodes', 5], value: newNode }],
+ *   inversePatches: [{ op: 'remove', path: ['nodes', 5] }],
+ *   actionType: 'ADD_NODE',
+ *   timestamp: 1716825600000,
+ * };
+ * ```
+ */
+declare type HistoryEntry = {
+    /** Patches to move state forward (apply on redo). */
+    patches: Patch[];
+    /** Patches to move state backward (apply on undo). */
+    inversePatches: Patch[];
+    /** The action type(s) that produced this entry, for debugging/display. */
+    actionType: string;
+    /** Timestamp of when this entry was created. */
+    timestamp: number;
+};
+
+/**
+ * Describes one edge feeding into a specific input handle.
+ * Multiple entries for the same handle indicate fan-in.
+ */
+declare type InputResolutionEntry = {
+    edgeId: string;
+    sourceNodeId: string;
+    sourceHandleId: string;
+    /**
+     * Position of this edge in `state.edges` at compile time — the deterministic
+     * tiebreak when two connections in the same fan-in group share (or both lack) a
+     * `data.order`. Mirrors the reorder popover's `reactFlow.getEdges()` index (both
+     * derive from the same edges array), so on-screen order ≡ compiled order without
+     * relying on `Array.prototype.sort` stability. Also surfaced (additive) in the
+     * `json-ir` run target. `compile()` ALWAYS sets it; optional in the type only so
+     * hand-built test fixtures (codegen tests that never read it) needn't supply it.
+     */
+    edgesArrayIndex?: number;
+};
+
+/**
+ * A compiled loop structure containing the loop triplet node IDs
+ * and the topologically sorted body steps.
+ */
+export declare type LoopExecutionBlock = {
+    kind: 'loop';
+    loopStartNodeId: string;
+    loopStopNodeId: string;
+    loopEndNodeId: string;
+    /** Topologically sorted body steps (nodes between loopStart and loopStop) */
+    preStopSteps: ReadonlyArray<ExecutionStep>;
+    /** Topologically sorted body steps (nodes between loopStop and loopEnd) */
+    postStopSteps: ReadonlyArray<ExecutionStep>;
+    /** Maximum iterations before erroring (configurable, default 100) */
+    maxIterations: number;
+    concurrencyLevel: number;
+};
+
+/**
+ * Minimal structural types for reading node handle data without
+ * importing the full generic ConfigurableNode types (avoids variance issues).
+ */
+export declare type MinimalInput = {
+    id?: string;
+    name?: string;
+    allowInput?: boolean;
+    value?: unknown;
+    dataType?: {
+        dataTypeUniqueId?: string;
+    };
+    inferredDataType?: {
+        dataTypeUniqueId?: string;
+    } | null;
+};
+
+export declare type MinimalInputPanel = {
+    id?: string;
+    name?: string;
+    inputs: ReadonlyArray<MinimalInput>;
+};
+
+export declare type MinimalNodeData = {
+    inputs?: ReadonlyArray<MinimalInput | MinimalInputPanel>;
+    outputs?: ReadonlyArray<MinimalOutput>;
+    nodeTypeUniqueId?: string;
+    /** Optional user custom name (standard nodes only) — for the inspector's
+     *  "coming from" source label. */
+    customName?: string;
+};
+
+export declare type MinimalOutput = {
+    id?: string;
+    name?: string;
+    dataType?: {
+        dataTypeUniqueId?: string;
+    };
+    inferredDataType?: {
+        dataTypeUniqueId?: string;
+    } | null;
+};
+
+/**
+ * Constraints on how many nodes of each type may exist in different scopes.
+ *
+ * - If undefined on State: no constraints at all
+ * - If a node type has no entry: no constraints for that type
+ * - Each field is optional; only provided fields are enforced (AND-ed together)
+ * - Only checked during ADD_NODE (max) and node deletion (min)
+ *
+ * @template NodeTypeUniqueId - Unique identifier type for node types
+ */
+declare type NodeCountConstraints<NodeTypeUniqueId extends string = string> = Partial<Record<NodeTypeUniqueId, {
+    /** Minimum count across root + all group subtrees combined */
+    minAcrossAllNodes?: number;
+    /** Maximum count across root + all group subtrees combined */
+    maxAcrossAllNodes?: number;
+    /** Minimum count within each individual group subtree (checked per-group) */
+    minWithinANodeGroup?: number;
+    /** Maximum count within each individual group subtree (checked per-group) */
+    maxWithinANodeGroup?: number;
+    /** Minimum count in the root scope only */
+    minInRoot?: number;
+    /** Maximum count in the root scope only */
+    maxInRoot?: number;
+}>>;
+
+declare type NodeOptionalKeys = 'draggable' | 'zIndex' | 'selectable' | 'deletable' | 'dragging' | 'selected' | 'isConnectable' | 'positionAbsoluteX' | 'positionAbsoluteY';
+
+/**
+ * Props for the NodeResizerWithMoreControls component
+ */
+declare type NodeResizerWithMoreControlsProps = NodeResizerProps & {
+    /** Array of line positions for resize controls */
+    linePosition?: ControlLinePosition[];
+    /** Array of handle positions for resize controls */
+    handlePosition?: ControlPosition[];
+    /** Direction of resize operation */
+    resizeDirection?: ResizeControlDirection;
+};
+
+/**
+ * Array of configurable nodes in the graph
+ */
+declare type Nodes<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, NodeTypeUniqueId extends string = string, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never, DataTypeUniqueId extends string = string> = Optional<ConfigurableNodeReactFlowWrapperProps<UnderlyingType, NodeTypeUniqueId, ComplexSchemaType, DataTypeUniqueId>, NodeOptionalKeys>[];
+
+declare type NodeVisualState = (typeof nodeVisualStates)[number];
+
+declare const nodeVisualStates: readonly ["idle", "running", "completed", "errored", "skipped", "warning"];
+
+declare type Optional<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>;
+
+/**
+ * Describes one edge consuming from a specific output handle.
+ * Multiple entries for the same handle indicate fan-out.
+ */
+declare type OutputDistributionEntry = {
+    edgeId: string;
+    targetNodeId: string;
+    targetHandleId: string;
+};
+
+/**
+ * Builds the qualified handle ID used as a key in the ValueStore.
+ * Format: "nodeId:handleId"
+ *
+ * **Important:** `nodeId` and `handleId` must NOT contain `:` or `>`
+ * characters. `:` is the internal separator between node and handle IDs,
+ * and `>` is the scope separator used by {@link ValueStore.createScope}.
+ * Using these characters in IDs will cause data corruption in the runner.
+ */
+export declare function qualifiedId(nodeId: string, handleId: string): string;
+
+/** Minimal structural shape of one input handle's value (matches the runner). */
+export declare type ReadableInputHandle = {
+    connections: ReadonlyArray<{
+        value: unknown;
+    }>;
+    defaultValue?: unknown;
+};
+
+/**
+ * Read a node input by handle name.
+ *
+ * @param inputs - The implementation's input map (handle name → value).
+ * @param name - The input handle name.
+ * @returns Every connected value (fan-in), or `[bakedDefault]` when unconnected.
+ */
+export declare function readInput(inputs: ReadonlyMap<string, ReadableInputHandle>, name: string): unknown[];
+
+/**
+ * Resize direction, derived from the ReactFlow control's own prop type so it
+ * stays in lockstep with the underlying control instead of reaching into
+ * `@xyflow/system` internals for a single prop type.
+ */
+declare type ResizeControlDirection = NonNullable<ComponentProps<typeof NodeResizeControl>['resizeDirection']>;
+
+/**
+ * Runner-panel view preferences — document-level, PERSISTED runner UI preferences
+ * that live on the graph `State` (distinct from the per-recording
+ * `RecordingViewState`).
+ *
+ * - `autoScroll` — auto-scroll the timeline and canvas to follow the selected step.
+ * - `followIntoGroups` — open/close group scopes so the canvas follows the scrub
+ *   head into the executing group instance.
+ *
+ * Both are toggled through the `UPDATE_RUNNER_VIEW_PREFERENCE` reducer action,
+ * persisted on state export (like `userZones`), and defaulted per-field on read.
+ *
+ * This module imports NOTHING (a pure leaf) so it can be imported from anywhere
+ * without a cycle; the accessor takes a STRUCTURAL parameter (not `State<…>`), which
+ * also sidesteps the 4-parameter generic-widening trap at concretely-typed call
+ * sites.
+ */
+declare type RunnerViewPreferences = {
+    autoScroll: boolean;
+    followIntoGroups: boolean;
+};
+
+/**
+ * Read-only data EVERY target receives. NOTE: `functionImplementations` is NOT
+ * here — no artifact target needs the impl closures (json-ir serializes the
+ * plan; codegen emits a function that TAKES impls as a parameter), so it lives
+ * on `ExecuteRunContext` only (Interface Segregation).
+ */
+declare type RunTargetContextBase<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never> = {
+    /** Raw graph state — escape hatch for targets that re-derive their own IR. */
+    state: Readonly<State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>>;
+    /** The compiled stable IR — the default input a target consumes. */
+    executionPlan: ExecutionPlan;
+    options: {
+        maxLoopIterations: number;
+    };
+    abortSignal: AbortSignal;
+    /**
+     * Values for the graph's declared root inputs, keyed by Graph Input handle
+     * NAME. The in-process executor seeds these into the root Graph Input node's
+     * output handles (mirroring codegen's `runGraph(a, b)` parameters); other
+     * targets may forward them however they model parameters. Absent / `undefined`
+     * when the graph declares no root inputs or the host supplies no values.
+     */
+    rootInputs?: Record<string, unknown>;
+};
+
+declare type RunTargetIdentity = {
+    /** Stable unique id (used for selection + dedupe). */
+    id: string;
+    /** Human-facing label for the run-target dropdown. */
+    label: string;
+    /** Optional icon shown in the dropdown / on the Run button. */
+    icon?: ReactNode;
+};
+
+/**
+ * A standard node execution step — call the function implementation,
+ * pass inputs, store outputs.
+ */
+export declare type StandardExecutionStep = {
+    kind: 'standard';
+    nodeId: string;
+    nodeTypeId: string;
+    nodeTypeName: string;
+    /** Optional user custom name for this node instance (standard nodes only). */
+    customName?: string;
+    concurrencyLevel: number;
+};
+
+/**
+ * Complete state definition for the graph system
+ *
+ * @template DataTypeUniqueId - Unique identifier type for data types
+ * @template NodeTypeUniqueId - Unique identifier type for node types
+ * @template UnderlyingType - Supported underlying data types ('string' | 'number' | 'complex')
+ * @template ComplexSchemaType - Zod schema type for complex data types
+ */
+export declare type State<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never> = {
+    openedNodeGroupStack?: ({
+        nodeType: NodeTypeUniqueId;
+        previousViewport?: Viewport;
+    } | {
+        nodeType: NodeTypeUniqueId;
+        /**
+         * If not provided, it means that this node group isn't instantiated yet and we are editing the original node group
+         */
+        nodeId: string;
+        previousViewport?: Viewport;
+    })[];
+    /** Map of data type definitions */
+    dataTypes: Record<DataTypeUniqueId, DataType<UnderlyingType, ComplexSchemaType>>;
+    /** Current viewport of the graph */
+    viewport?: Viewport;
+    /** Map of node type definitions */
+    typeOfNodes: Record<NodeTypeUniqueId, TypeOfNode<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>>;
+    /** Array of nodes in the graph */
+    nodes: Nodes<UnderlyingType, NodeTypeUniqueId, ComplexSchemaType, DataTypeUniqueId>;
+    /** Array of edges in the graph */
+    edges: Edges;
+    /**
+     * Optional mapping of allowed conversions between data types
+     * - When not provided, all conversions are allowed
+     * - If provided, only the conversions that are explicitly allowed will be allowed (happens even with empty object)
+     * - By default, it will not allow conversion between complex types unless explicitly allowed here (even if complex type checking is enabled)
+     * - If you want to allow conversion between complex types unless disallowed by complex type checking, you can set `allowConversionBetweenComplexTypesUnlessDisallowedByComplexTypeChecking` to true
+     *
+     * @default undefined
+     */
+    allowedConversionsBetweenDataTypes?: AllowedConversionsBetweenDataTypes<DataTypeUniqueId>;
+    /**
+     * Whether to allow conversion between complex types unless disallowed by complex type checking
+     * - If not provided, is considered disabled
+     * - Only takes effect if complex type checking is enabled (`allowedConversionsBetweenDataTypes` is provided)
+     * - If enabled, it will allow conversion between complex types unless disallowed by complex type checking
+     * - If disabled, it will not allow conversion between complex types unless explicitly allowed by `allowedConversionsBetweenDataTypes`, even if complex type checking is enabled
+     *
+     * @default undefined
+     */
+    allowConversionBetweenComplexTypesUnlessDisallowedByComplexTypeChecking?: boolean;
+    /**
+     * Whether to enable type inference
+     * - If not provided, is considered disabled
+     * - When disabled, the types of the nodes are not inferred from the connections
+     * - When enabled, the types of the nodes are inferred from the connections and reset when edges are removed
+     *
+     * @default undefined
+     */
+    enableTypeInference?: boolean;
+    /**
+     * Whether to enable complex type checking
+     * - If not provided, is considered disabled
+     * - When disabled, the complex types are not checked for compatibility, all connections are allowed
+     * - When enabled, the complex types are checked for compatibility, and connections are not allowed if the complex types are not compatible
+     * - Complex types are compatible if they are the same type or if they have exactly the same schema
+     *
+     * @default undefined
+     */
+    enableComplexTypeChecking?: boolean;
+    /**
+     * Whether to enable cycle checking
+     * - If not provided, is considered disabled
+     * - When disabled, the cycles are not checked, all connections are allowed
+     * - When enabled, the cycles are checked, and connections are not allowed if they create a cycle
+     *
+     * @default undefined
+     */
+    enableCycleChecking?: boolean;
+    /**
+     * Whether to enable recursion checking
+     * - If not provided, is considered disabled
+     * - When disabled, the recursion is not checked, all nesting of node groups is allowed
+     * - When enabled, the recursion is checked, and nesting of node groups is not allowed if it creates a recursion
+     *
+     * @default undefined
+     */
+    enableRecursionChecking?: boolean;
+    /**
+     * Optional constraints on how many nodes of each type may exist.
+     * If not provided, no constraints are enforced.
+     * Only checked during ADD_NODE (max) and node deletion (min).
+     *
+     * @default undefined
+     */
+    nodeCountConstraints?: NodeCountConstraints<NodeTypeUniqueId>;
+    /**
+     * Node types to hide from the "Add Node" context menu.
+     * If not provided, all node types are shown.
+     * Use `standardHiddenNodeTypesInContextMenu` from standardNodes for the default set.
+     *
+     * @default undefined
+     */
+    hiddenNodeTypesInContextMenu?: Partial<Record<NodeTypeUniqueId, true>>;
+    /**
+     * Whether to enable debugging mode
+     * - If not provided, is considered disabled
+     * - When disabled, no debug information is displayed in the graph
+     * - When enabled, debug information is displayed in the graph
+     *
+     * @default undefined
+     */
+    enableDebugMode?: boolean;
+    /**
+     * Currently open drawer. UI-only state — stripped during export.
+     * Managed by OPEN_DRAWER / CLOSE_DRAWER actions.
+     * @default undefined
+     */
+    activeDrawer?: ActiveDrawer;
+    /**
+     * Root-level zone definitions for structures at the top scope.
+     * Each zone defines a region with boundary handles, visual frame, and
+     * optional connection enforcement. UI-only — stripped on export,
+     * rehydrated on import via REPLACE_STATE.
+     * @default undefined
+     */
+    zones?: Record<string, Zone>;
+    /**
+     * Reverse index from boundary handle IDs to zone IDs for O(1)
+     * lookups during connection validation. Rebuilt whenever zones change.
+     * UI-only — stripped on export.
+     * @default undefined
+     */
+    zoneIndex?: ZoneIndex;
+    /**
+     * Root-level USER-AUTHORED zones (named/colored visual frames the user creates
+     * around selected nodes). Unlike `zones` (derived from loop/switch structures,
+     * recomputed/stripped/rehydrated), these are AUTHORED: membership is an explicit
+     * `nodeIds` set, never recomputed. Persisted in export (NOT stripped) and forwarded
+     * on import (NOT rehydrated). Visual-only — `enforced: false`, no
+     * boundaryHandles/structureLink. Scope-local like `zones` (root vs subtree).
+     * @default undefined
+     */
+    userZones?: Record<string, Zone>;
+    /**
+     * Document-level runner-panel view preferences: `autoScroll` (auto-scroll the
+     * timeline/canvas to the selected step) and `followIntoGroups` (follow the scrub
+     * head into executing group instances). Toggled by UPDATE_RUNNER_VIEW_PREFERENCE.
+     * Persisted on export and forwarded on import (NOT stripped, NOT rehydrated) like
+     * `userZones`; GLOBAL (root-only, not scope-local — no subtree copy). The
+     * per-recording snapshot lives in `RecordingViewState`; `autoScroll` is mirrored
+     * there with graph state authoritative and NOT restored on load. Inner fields
+     * REQUIRED — read via `getRunnerViewPreferences`, which defaults per-field.
+     * @default undefined → read as { autoScroll: true, followIntoGroups: true }
+     */
+    runnerViewPreferences?: RunnerViewPreferences;
+    /**
+     * Undo/redo history. Stores Immer patches for each undoable action.
+     * Managed by UNDO, REDO, BEGIN_BATCH, END_BATCH, CLEAR_HISTORY actions.
+     * Stripped on export by default; optionally preserved via "Export with History".
+     * @default undefined
+     */
+    history?: {
+        undoStack: HistoryEntry[];
+        redoStack: HistoryEntry[];
+        config: HistoryConfig;
+        activeBatch: {
+            patches: Patch[];
+            inversePatches: Patch[];
+            actionTypes: string[];
+            startTimestamp: number;
+        } | null;
+    };
+};
+
+/**
+ * Union type of all supported underlying data types
+ */
+export declare type SupportedUnderlyingTypes = (typeof supportedUnderlyingTypes)[number];
+
+/**
+ * Array of supported underlying data types
+ */
+declare const supportedUnderlyingTypes: readonly ["string", "number", "boolean", "complex", "noEquivalent", "inferFromConnection"];
+
+export declare type SwitchExecutionBlock = {
+    kind: 'switch';
+    switchStartNodeId: string;
+    switchEndNodeId: string;
+    trueBranchSteps: ReadonlyArray<ExecutionStep>;
+    falseBranchSteps: ReadonlyArray<ExecutionStep>;
+    concurrencyLevel: number;
+};
+
+/**
+ * Definition of an input type in a node
+ *
+ * @template DataTypeUniqueId - Unique identifier type for data types
+ */
+declare type TypeOfInput<DataTypeUniqueId extends string = string> = {
+    /** Display name of the input */
+    name: string;
+    /** The data type identifier this input uses */
+    dataType: DataTypeUniqueId;
+    /** Whether this input allows direct user input */
+    allowInput?: boolean;
+    /** Maximum number of connections for this input */
+    maxConnections?: number;
+    /**
+     * Initial value seeded onto a freshly-constructed node's input handle
+     * (`node.data.inputs[].value`). Copied at construction only for
+     * `number`/`string`/`boolean` underlying types whose runtime value matches;
+     * ignored for `complex`/`inferFromConnection`/`noEquivalent`. Lets a node
+     * type declare its own defaults instead of the consumer seeding them via
+     * `UPDATE_INPUT_VALUE` after every add.
+     */
+    defaultValue?: string | number | boolean;
+};
+
+/**
+ * Definition of an input panel type in a node
+ *
+ * @template DataTypeUniqueId - Unique identifier type for data types
+ */
+declare type TypeOfInputPanel<DataTypeUniqueId extends string = string> = {
+    /** Display name of the input panel */
+    name: string;
+    /** Array of inputs within this panel */
+    inputs: TypeOfInput<DataTypeUniqueId>[];
+};
+
+/**
+ * Definition of a node type in the graph system
+ *
+ * @template DataTypeUniqueId - Unique identifier type for data types
+ */
+declare type TypeOfNode<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never> = {
+    /** Display name of the node type */
+    name: string;
+    /** Color used for the node header */
+    headerColor?: string;
+    /** Array of inputs (can be regular inputs or input panels) */
+    inputs: (TypeOfInput<DataTypeUniqueId> | TypeOfInputPanel<DataTypeUniqueId>)[];
+    /** Array of outputs */
+    outputs: TypeOfInput<DataTypeUniqueId>[];
+    /** Path in the "Add Node" context menu. e.g. ["Math", "Trig"] nests under Math > Trig.
+     * Omit to place at root level of "Add Node". */
+    locationInContextMenu?: string[];
+    /** Ordering priority in the context menu. Higher values appear first. Default: 0. */
+    priorityInContextMenu?: number;
+    /** Subtree of the node type (if this exists, this is a node group) */
+    subtree?: {
+        nodes: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>['nodes'];
+        edges: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>['edges'];
+        /**
+         * Number of references to this node group
+         * This subtree can only be edited or deleted if there are no references to it
+         */
+        numberOfReferences: number;
+        /**
+         * Input node id of the node group
+         * - It is used to connect the node group to the rest of the graph
+         * - Not allowed to be deleted or duplicated, must always be one
+         */
+        inputNodeId: string;
+        /**
+         * Output node id of the node group
+         * - It is used to connect the node group to the rest of the graph
+         * - Not allowed to be deleted or duplicated, must always be one
+         */
+        outputNodeId: string;
+        /** Scope-local zone definitions for structures inside this subtree. UI-only — stripped on export. */
+        zones?: Record<string, Zone>;
+        /** Reverse index from boundary handle IDs to zone IDs for this subtree. UI-only — stripped on export. */
+        zoneIndex?: ZoneIndex;
+        /**
+         * Scope-local USER-AUTHORED zones for this subtree (named/colored visual frames
+         * the user wraps around selected nodes). Unlike `zones` (derived from loop/switch
+         * structures, recomputed/stripped/rehydrated), these are AUTHORED: membership is an
+         * explicit `nodeIds` set, never recomputed. Persisted (NOT stripped on export, NOT
+         * rehydrated on import). Visual-only — `enforced: false`, no boundaryHandles/structureLink.
+         */
+        userZones?: Record<string, Zone>;
+    };
+};
+
+/**
+ * A first-class region of the graph, visually rendered as a frame polygon
+ * and optionally enforcing connection boundary rules.
+ *
+ * System zones (switches, loops) are created/updated automatically when
+ * structures are added or edges change. User zones are authored (named/colored
+ * frames the user wraps around selected nodes) and visual-only — `enforced: false`,
+ * no `structureLink`/`boundaryHandles`, no boundary enforcement.
+ *
+ * Zones are scope-local: root-level zones live on `state.zones`, subtree
+ * zones live on `subtree.zones` inside their node group.
+ */
+declare type Zone = {
+    /** Opaque unique identifier (UUID, not derived from node IDs). */
+    id: string;
+    /** Display name shown on the zone frame label. */
+    name: string;
+    /** CSS color for the zone frame polygon and label. */
+    color: string;
+    /**
+     * Member node IDs. For SYSTEM zones this is recomputed on every edge change;
+     * for USER zones it is AUTHORED (never recomputed).
+     */
+    nodeIds: string[];
+    /**
+     * Per-boundary-node handle definitions. Keys are boundary node IDs.
+     * The BFS zone discovery starts from edges connected to these handles
+     * and stops at boundary nodes.
+     *
+     * Undefined for user-created zones (no boundaries, visual only).
+     */
+    boundaryHandles?: Record<string, ZoneBoundaryHandle>;
+    /** Present for system-controlled zones; absent for user-created zones. */
+    structureLink?: ZoneStructureLink;
+    /** Whether connections crossing this zone's boundary are blocked. */
+    enforced: boolean;
+};
+
+/**
+ * Describes the boundary handles on a single boundary node that define
+ * one edge of a zone. The direction indicates which side of the boundary
+ * node the zone's body nodes connect to.
+ */
+declare type ZoneBoundaryHandle = {
+    /** Handle IDs on this boundary node that belong to this zone. */
+    handleIds: string[];
+    /** Whether these handles are inputs or outputs on the boundary node. */
+    direction: 'inputs' | 'outputs';
+};
+
+/**
+ * Reverse index from handle IDs to zone IDs for O(1) lookups
+ * during connection validation. Rebuilt whenever zones change.
+ */
+declare type ZoneIndex = {
+    /** Maps each boundary handle ID to the zone it belongs to. */
+    handleToZone: Record<string, string>;
+};
+
+/**
+ * Links a system-controlled zone to the structural node pair that owns it.
+ * Used to find zones by their parent structure without relying on zone IDs.
+ */
+declare type ZoneStructureLink = {
+    /** The kind of structure that owns this zone. */
+    structureType: 'switch' | 'loop';
+    /** The anchor node ID of the structure (switchStartId or loopStartId). */
+    structureId: string;
+    /** Which region of the structure this zone represents (e.g. 'trueBranch', 'preStop'). */
+    zoneRole: string;
+};
+
+export { }