entangle-ui 0.8.2 → 0.10.0

package/dist/types/components/editor/NodeGraph/NodeGraphNodeSection.d.ts

@@ -0,0 +1,47 @@
+import React from 'react';
+
+interface NodeGraphNodeSectionProps {
+    /** Header label shown next to the collapse toggle. */
+    title?: React.ReactNode;
+    /**
+     * Whether the header toggles the section. When false the section is a
+     * static labelled group (no chevron, always shown). @default true
+     */
+    collapsible?: boolean;
+    /** Controlled collapsed state. Pair with `onCollapsedChange`. */
+    collapsed?: boolean;
+    /** Initial collapsed state when uncontrolled. @default false */
+    defaultCollapsed?: boolean;
+    /** Fires when the user toggles the section. */
+    onCollapsedChange?: (collapsed: boolean) => void;
+    className?: string;
+    style?: React.CSSProperties;
+    /** Section body — typically a `<NodeGraph.PinList>` of the extra pins. */
+    children?: React.ReactNode;
+}
+/**
+ * A collapsible section inside a node body — the place to tuck "advanced" /
+ * overflow pins so the node stays compact. The collapse is **purely visual**:
+ * the children never unmount, so their state is preserved and there's no
+ * remount cost. `<NodeGraph.Port>` slots inside a collapsed section
+ * unregister their position while hidden, so the pins' edges hide with them
+ * and reappear on expand — no dangling wires, no manual re-anchoring.
+ *
+ * @example
+ * ```tsx
+ * <NodeGraph.NodeBody>
+ *   <NodeGraph.NodeHeader title="Make Transform" />
+ *   <NodeGraph.PinList>{mainPins}</NodeGraph.PinList>
+ *   <NodeGraph.NodeSection title="Advanced" defaultCollapsed>
+ *     <NodeGraph.PinList>{advancedPins}</NodeGraph.PinList>
+ *   </NodeGraph.NodeSection>
+ * </NodeGraph.NodeBody>
+ * ```
+ */
+declare function NodeGraphNodeSection({ title, collapsible, collapsed: collapsedProp, defaultCollapsed, onCollapsedChange, className, style, children, }: NodeGraphNodeSectionProps): React.ReactElement;
+declare namespace NodeGraphNodeSection {
+    var displayName: string;
+}
+
+export { NodeGraphNodeSection };
+export type { NodeGraphNodeSectionProps };

package/dist/types/components/editor/NodeGraph/NodeGraphPin.d.ts

@@ -0,0 +1,57 @@
+import React from 'react';
+import { NodeGraphPortSide, NodeGraphPortShape } from './NodeGraph.types.js';
+
+interface NodeGraphPinProps {
+    /** Port id — referenced by `NodeGraphEdge.source` / `.target`. */
+    id: string;
+    /** Which side the pin anchors to. Drives row layout and edge tangent. */
+    side: NodeGraphPortSide;
+    /** Opaque type token forwarded to `isValidConnection` and edge styling. */
+    dataType?: string;
+    /** Row label shown next to the handle. */
+    label?: React.ReactNode;
+    /** Handle colour (any CSS colour). Defaults to the theme focus colour. */
+    color?: string;
+    /** Built-in handle shape. @default 'circle' */
+    shape?: NodeGraphPortShape;
+    /**
+     * Force the handle filled / hollow. When omitted, the handle fills
+     * automatically while the pin is connected to an edge.
+     */
+    filled?: boolean;
+    /** Row height in CSS px. @default 22 */
+    height?: number;
+    /** Accessible label for the port handle. Falls back to the port default. */
+    portLabel?: string;
+    /** Class applied to the row wrapper. */
+    className?: string;
+    /** Inline style applied to the row wrapper. */
+    style?: React.CSSProperties;
+    /** Class applied to the label span. */
+    labelClassName?: string;
+    /** Inline style applied to the label span. */
+    labelStyle?: React.CSSProperties;
+}
+/**
+ * `<NodeGraph.Pin>` — the one-liner for the common "handle + label" row.
+ * Renders a `<NodeGraph.PinRow>` containing a `<NodeGraph.Port>` and a
+ * label, ordered so the handle always sits flush against the node edge
+ * (port → label on the left/top, label → port on the right). Reach for
+ * `<NodeGraph.PinRow>` + `<NodeGraph.Port>` directly only when you need a
+ * layout this doesn't cover (multiple controls in a row, inline editors).
+ *
+ * @example
+ * ```tsx
+ * <NodeGraph.PinList>
+ *   <NodeGraph.Pin id="exec" side="left" shape="triangle" color="#fff" />
+ *   <NodeGraph.Pin id="value" side="right" dataType="float" color="#9ee65a" label="Value" />
+ * </NodeGraph.PinList>
+ * ```
+ */
+declare function NodeGraphPin({ id, side, dataType, label, color, shape, filled, height, portLabel, className, style, labelClassName, labelStyle, }: NodeGraphPinProps): React.ReactElement;
+declare namespace NodeGraphPin {
+    var displayName: string;
+}
+
+export { NodeGraphPin };
+export type { NodeGraphPinProps };

package/dist/types/components/editor/NodeGraph/NodeGraphPort.d.ts

@@ -0,0 +1,30 @@
+import React from 'react';
+import { NodeGraphPortSlotProps } from './NodeGraph.types.js';
+
+/**
+ * `<NodeGraph.Port>` — compound slot that declares a connection endpoint
+ * for the current node. Render it anywhere inside `renderNode`; the
+ * library measures its DOM position, registers it as the anchor for any
+ * edge that references this port id, and wires pointer events so the
+ * user can drag from it to start a connection.
+ *
+ * The slot renders a single `<span>` with `display: inline-flex` — drop
+ * it inline next to a label and it will sit beside the text. The wrapper
+ * carries the default UE-style circle / exec-triangle visual; pass
+ * `children` to replace the chrome entirely (state for theming is
+ * exposed via `data-port-*` attributes).
+ *
+ * @example
+ * ```tsx
+ * <NodeGraph.Port id="in" side="left" dataType="exec" />
+ * ```
+ *
+ * Wrapped in `React.memo` — ports re-mount on every consumer `renderNode`
+ * call by default, so memoization only helps consumers who memoize their
+ * own node body. When they do, ports skip re-renders on unrelated store
+ * updates entirely.
+ */
+declare function NodeGraphPortImpl({ id, side, dataType, shape, color, filled, children, label, className, style, }: NodeGraphPortSlotProps): React.ReactElement;
+declare const NodeGraphPort: React.MemoExoticComponent<typeof NodeGraphPortImpl>;
+
+export { NodeGraphPort };

package/dist/types/components/editor/NodeGraph/NodeGraphPortVisual.d.ts

@@ -0,0 +1,46 @@
+import React from 'react';
+import { NodeGraphPortShape } from './NodeGraph.types.js';
+
+interface NodeGraphPortVisualProps {
+    /**
+     * Handle shape. @default 'circle'
+     */
+    shape?: NodeGraphPortShape;
+    /**
+     * Stroke / fill colour. Defaults to `currentColor` so the parent
+     * `<NodeGraph.Port>` can route its colour prop and interaction-state
+     * colours (source / candidate / invalid) into the shape via the CSS
+     * `color` cascade. Pass an explicit colour when using the visual
+     * standalone (outside a port slot).
+     */
+    color?: string;
+    /**
+     * Filled (`true`) paints the interior; hollow (`false`) draws an outline
+     * only — the standard "wired vs unwired pin" convention.
+     * @default false
+     */
+    filled?: boolean;
+    /**
+     * Box size in CSS pixels. @default 14
+     */
+    size?: number;
+    className?: string;
+    style?: React.CSSProperties;
+}
+/**
+ * Presentational handle shape for a node-graph port. Rendered by
+ * `<NodeGraph.Port>` when no `children` are supplied, and exported so
+ * consumers can reuse the exact handle look inside fully custom port
+ * visuals (e.g. a coloured ring beside a typed label).
+ *
+ * The shape paints with `currentColor` unless `color` is set, which lets
+ * the port slot drive the colour from its `color` prop and override it on
+ * the connection-drag states without this component knowing about them.
+ */
+declare function NodeGraphPortVisual({ shape, color, filled, size, className, style, }: NodeGraphPortVisualProps): React.ReactElement;
+declare namespace NodeGraphPortVisual {
+    var displayName: string;
+}
+
+export { NodeGraphPortVisual };
+export type { NodeGraphPortVisualProps };

package/dist/types/components/editor/NodeGraph/NodeGraphSlots.d.ts

@@ -0,0 +1,16 @@
+import { NodeGraphMinimapSlotProps, NodeGraphSlotMarker, NodeGraphBackgroundSlotProps, NodeGraphToolbarSlotProps, NodeGraphSpawnPaletteSlotProps } from './NodeGraph.types.js';
+
+declare const NodeGraphMinimap: ((props: NodeGraphMinimapSlotProps) => null) & NodeGraphSlotMarker & {
+    displayName: string;
+};
+declare const NodeGraphBackground: ((props: NodeGraphBackgroundSlotProps) => null) & NodeGraphSlotMarker & {
+    displayName: string;
+};
+declare const NodeGraphToolbar: ((props: NodeGraphToolbarSlotProps) => null) & NodeGraphSlotMarker & {
+    displayName: string;
+};
+declare const NodeGraphSpawnPalette: ((props: NodeGraphSpawnPaletteSlotProps) => null) & NodeGraphSlotMarker & {
+    displayName: string;
+};
+
+export { NodeGraphBackground, NodeGraphMinimap, NodeGraphSpawnPalette, NodeGraphToolbar };

package/dist/types/components/editor/NodeGraph/NodeGraphStore.d.ts

@@ -0,0 +1,256 @@
+import { NodeGraphNode, NodeGraphEdge, NodeGraphGroup, NodeGraphPortRef, NodeGraphPortSide, NodeGraphSelection } from './NodeGraph.types.js';
+import { Point2D } from '../../primitives/canvas/canvas.types.js';
+
+/** Snapshot of the data slice — the canonical graph contents. */
+interface NodeGraphDataState {
+    nodes: ReadonlyArray<NodeGraphNode>;
+    edges: ReadonlyArray<NodeGraphEdge>;
+    groups: ReadonlyArray<NodeGraphGroup>;
+    defaultNodeSize: {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * A port's measured position registered by a `<NodeGraph.Port>` slot.
+ * Coordinates are in **node-local pixels** (relative to the node wrapper's
+ * top-left). Because the wrapper is positioned in world space but rendered
+ * in CSS pixels at zoom = 1 (zoom is applied by the parent `<ViewportWorld>`
+ * transform), these pixels are equivalent to node-local world units.
+ */
+interface NodeGraphPortPosition {
+    x: number;
+    y: number;
+    side: NodeGraphPortSide;
+    dataType?: string;
+}
+/** Measured DOM size of a node wrapper, in node-local world units. */
+interface NodeGraphMeasuredSize {
+    width: number;
+    height: number;
+}
+/**
+ * Snapshot of the interaction slice — the active gesture (if any) and its
+ * scratch data. Designed so the edge/preview drawing layer can read everything
+ * it needs in one slice subscription.
+ */
+/** Eight points along a rectangle that can be grabbed to resize a group. */
+type NodeGraphGroupResizeHandle = 'nw' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w';
+type NodeGraphInteractionState = {
+    kind: 'idle';
+} | {
+    kind: 'drag-nodes';
+    /**
+     * Ids of nodes being dragged together. Set (not Array) so per-node
+     * subscribers can do O(1) membership checks in the hot per-frame
+     * selector path — a Cartesian `Array.includes` was a measurable cost
+     * at high node counts when the user dragged the whole selection.
+     */
+    nodeIds: ReadonlySet<string>;
+    /** Pointer-down world position (start of the drag). */
+    startWorld: Point2D;
+    /** Cumulative drag delta in world units (snapped if grid active). */
+    delta: Point2D;
+} | {
+    kind: 'drag-groups';
+    /** Ids of groups being dragged together. See {@link nodeIds} for why Set. */
+    groupIds: ReadonlySet<string>;
+    /**
+     * Ids of nodes that were fully contained inside one of the dragged
+     * groups at gesture start. They ride along with the group(s) and
+     * receive the same drag delta — see `rectContains` in `nodeGraphMath`.
+     */
+    containedNodeIds: ReadonlySet<string>;
+    /** Pointer-down world position. */
+    startWorld: Point2D;
+    /** Cumulative drag delta (snapped if grid active). */
+    delta: Point2D;
+    /**
+     * True when the projected positions of the dragged groups would
+     * overlap any other (non-dragged) group. The HTML overlay paints a
+     * rejection state and the pointerup handler refuses to commit when
+     * this is set.
+     */
+    blocked: boolean;
+} | {
+    kind: 'resize-group';
+    groupId: string;
+    handle: NodeGraphGroupResizeHandle;
+    /** Original bounds at the start of the resize. */
+    startBounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Cumulative pointer delta in world units (snapped). */
+    delta: Point2D;
+    /** Set when the resized bounds would overlap another group. */
+    blocked: boolean;
+} | {
+    kind: 'connect';
+    /**
+     * Fixed endpoint the preview draws from. For a new connection this is
+     * the port the drag started on; for a reconnect it's the *other* end
+     * of the edge being edited (the one staying put).
+     */
+    source: NodeGraphPortRef;
+    /** Current pointer position in world coordinates. */
+    currentWorld: Point2D;
+    /** Hovered candidate target port, or null when none. */
+    candidate: NodeGraphPortRef | null;
+    /** Whether the candidate is currently rejected by `isValidConnection`. */
+    invalid: boolean;
+    /**
+     * Set while re-dragging an existing edge's endpoint. The edge is hidden
+     * from the edge layer for the duration so only the preview shows, and
+     * the drop either moves the endpoint, deletes the edge (detach), or —
+     * on a click with no drag — selects it.
+     */
+    reconnectEdgeId?: string;
+    /** Which end of `reconnectEdgeId` is being dragged. */
+    reconnectEnd?: 'source' | 'target';
+} | {
+    kind: 'marquee';
+    /** Marquee start in world coordinates. */
+    startWorld: Point2D;
+    /** Current pointer position in world coordinates. */
+    currentWorld: Point2D;
+    /** Whether the additive modifier was held at gesture start. */
+    additive: boolean;
+};
+/** Snapshot of the hover slice. */
+interface NodeGraphHoverState {
+    hoveredNodeId: string | null;
+    hoveredEdgeId: string | null;
+    hoveredPort: NodeGraphPortRef | null;
+}
+/**
+ * Hot-path runtime state for `<NodeGraph>` — graph data, selection,
+ * interaction, hover. Each slice carries its own subscribe/get pair so
+ * subscribers re-render only on relevant changes (e.g. the edge canvas
+ * subscribes to data + interaction, individual node bodies subscribe only
+ * to selection + drag delta for their own id).
+ *
+ * Mirrors `ViewportStore` / `MinimapStore` in structure.
+ */
+declare class NodeGraphStore {
+    private data;
+    private selection;
+    private interaction;
+    private hover;
+    private nodeIndex;
+    private connectedPorts;
+    private portPositions;
+    private measuredSizes;
+    private dataListeners;
+    private connectedPortsListeners;
+    private selectionListeners;
+    private interactionListeners;
+    private nodeInteractionListeners;
+    private hoverListeners;
+    private portPositionListeners;
+    private measuredSizeListeners;
+    private portPositionsVersion;
+    private measuredSizesVersion;
+    private spawnRequestListeners;
+    getData: () => NodeGraphDataState;
+    getSelection: () => NodeGraphSelection;
+    getInteraction: () => NodeGraphInteractionState;
+    getHover: () => NodeGraphHoverState;
+    /**
+     * The set of `"${node}\0${port}"` keys that are referenced by at least
+     * one edge endpoint. Reference is stable until the membership actually
+     * changes, so it can back a `useSyncExternalStore` snapshot directly.
+     */
+    getConnectedPorts: () => ReadonlySet<string>;
+    /** True when the given port is referenced by at least one edge endpoint. */
+    isPortConnected: (nodeId: string, portId: string) => boolean;
+    /**
+     * O(1) node lookup by id, backed by an internal Map rebuilt on each
+     * `setData`. Use this from hot paths instead of `data.nodes.find(...)`.
+     */
+    getNodeById: (id: string) => NodeGraphNode | undefined;
+    /**
+     * Read the registered position of a single port. Returns `null` when the
+     * port hasn't yet been measured (e.g. on first paint before
+     * `useLayoutEffect` has run, or after the slot unmounted).
+     */
+    getPortPosition: (nodeId: string, portId: string) => NodeGraphPortPosition | null;
+    /** Read the measured DOM size of a node wrapper. */
+    getMeasuredSize: (nodeId: string) => NodeGraphMeasuredSize | null;
+    /**
+     * Monotonic snapshot of the port-positions channel — pass to
+     * `useSyncExternalStore` alongside `subscribePortPositions` so React
+     * actually re-renders consumers on every real change. Incremented
+     * whenever a port position is added, updated, removed, or GC'd by
+     * `setData`. Skipped on no-op writes.
+     */
+    getPortPositionsVersion: () => number;
+    /**
+     * Monotonic snapshot of the measured-sizes channel — same role as
+     * `getPortPositionsVersion`, for `subscribeMeasuredSizes`.
+     */
+    getMeasuredSizesVersion: () => number;
+    subscribeData: (cb: () => void) => (() => void);
+    /**
+     * Subscribe to the connected-ports channel — fires only when the set of
+     * edge-referenced ports actually changes membership (not on every node
+     * move). Backs the auto-`connected` state on `<NodeGraph.Port>`.
+     */
+    subscribeConnectedPorts: (cb: () => void) => (() => void);
+    subscribeSelection: (cb: () => void) => (() => void);
+    subscribeInteraction: (cb: () => void) => (() => void);
+    /**
+     * Subscribe to interaction changes that affect a specific node id. The
+     * callback fires only when the node enters or leaves the active drag set
+     * (drag-nodes `nodeIds`, drag-groups `containedNodeIds`) — every other
+     * tick where the drag set is unchanged for this id is filtered out at the
+     * store layer instead of waking the subscriber for a no-op compare.
+     *
+     * Use this from per-node React subscribers; the global
+     * {@link subscribeInteraction} channel stays in place for canvas layers
+     * and other consumers that care about every interaction change.
+     */
+    subscribeNodeInteraction: (nodeId: string, cb: () => void) => (() => void);
+    subscribeHover: (cb: () => void) => (() => void);
+    subscribePortPositions: (cb: () => void) => (() => void);
+    subscribeMeasuredSizes: (cb: () => void) => (() => void);
+    subscribeSpawnRequest: (cb: (info: {
+        worldPoint: Point2D;
+        screenPoint: Point2D;
+    }) => void) => (() => void);
+    requestSpawn(info: {
+        worldPoint: Point2D;
+        screenPoint: Point2D;
+    }): void;
+    setData(next: NodeGraphDataState): void;
+    setSelection(next: NodeGraphSelection): void;
+    setInteraction(next: NodeGraphInteractionState): void;
+    setHover(next: NodeGraphHoverState): void;
+    /**
+     * Register a port's measured position. Called by `<NodeGraph.Port>` from
+     * a `useLayoutEffect` + `ResizeObserver`. No-ops when the incoming
+     * position is identical to the cached one — protects edge layer from
+     * redraw storms when nodes resize without porting any pin movement.
+     */
+    setPortPosition(nodeId: string, portId: string, next: NodeGraphPortPosition): void;
+    /** Remove a port registration. Called by `<NodeGraph.Port>` cleanup. */
+    removePortPosition(nodeId: string, portId: string): void;
+    /**
+     * Register / refresh the measured DOM size of a node wrapper. No-ops on
+     * identical width+height.
+     */
+    setMeasuredSize(nodeId: string, next: NodeGraphMeasuredSize): void;
+    /** Clear the measured size of a node (called on unmount). */
+    clearMeasuredSize(nodeId: string): void;
+    /** True when a node id is currently selected. */
+    isNodeSelected(id: string): boolean;
+    /** True when an edge id is currently selected. */
+    isEdgeSelected(id: string): boolean;
+    /** True when a group id is currently selected. */
+    isGroupSelected(id: string): boolean;
+}
+
+export { NodeGraphStore };
+export type { NodeGraphDataState, NodeGraphGroupResizeHandle, NodeGraphHoverState, NodeGraphInteractionState, NodeGraphMeasuredSize, NodeGraphPortPosition };

package/dist/types/components/editor/NodeGraph/NodeGraphToolbar.d.ts

@@ -0,0 +1,54 @@
+import React from 'react';
+
+/**
+ * Visual separator for grouping toolbar buttons. Just a 1 px line; pass
+ * `orientation="vertical"` (default) inside a horizontal toolbar.
+ */
+interface NodeGraphToolbarSeparatorProps {
+    orientation?: 'horizontal' | 'vertical';
+    className?: string;
+}
+declare function NodeGraphToolbarSeparator({ orientation, className, }: NodeGraphToolbarSeparatorProps): React.ReactElement;
+interface CommonButtonProps {
+    /** Override the label text. */
+    label?: React.ReactNode;
+    /** Override the icon (replaces the default). */
+    icon?: React.ReactNode;
+    /** Pass-through to the underlying `<Button>`. */
+    size?: 'sm' | 'md' | 'lg';
+    /** Pass-through variant. */
+    variant?: 'default' | 'ghost' | 'filled';
+    /** Extra class on the button. */
+    className?: string;
+    /** Inline style override. */
+    style?: React.CSSProperties;
+    /** Override the title / tooltip. */
+    title?: string;
+}
+/** Fit all nodes inside the viewport. Calls the same code path as `ref.fitToContent`. */
+interface NodeGraphFitContentButtonProps extends CommonButtonProps {
+    /** World-unit padding around the fitted bounds. @default 32 */
+    padding?: number;
+}
+declare function NodeGraphFitContentButton({ padding, label, icon, size, variant, className, style, title, }: NodeGraphFitContentButtonProps): React.ReactElement;
+/**
+ * Fit the currently-selected nodes inside the viewport. Disabled when
+ * the selection contains no nodes — reads the live selection slice so
+ * the button's disabled state updates without consumer plumbing.
+ */
+interface NodeGraphFitSelectionButtonProps extends CommonButtonProps {
+    padding?: number;
+}
+declare function NodeGraphFitSelectionButton({ padding, label, icon, size, variant, className, style, title, }: NodeGraphFitSelectionButtonProps): React.ReactElement;
+/** Zoom in by a fixed factor (default 1.25×). */
+interface NodeGraphZoomButtonProps extends CommonButtonProps {
+    /** Multiplier applied to the current zoom. @default 1.25 */
+    factor?: number;
+}
+declare function NodeGraphZoomInButton({ factor, label, icon, size, variant, className, style, title, }: NodeGraphZoomButtonProps): React.ReactElement;
+declare function NodeGraphZoomOutButton({ factor, label, icon, size, variant, className, style, title, }: NodeGraphZoomButtonProps): React.ReactElement;
+/** Reset zoom to 1× centred on the world origin. */
+declare function NodeGraphResetZoomButton({ label, icon, size, variant, className, style, title, }: CommonButtonProps): React.ReactElement;
+
+export { NodeGraphFitContentButton, NodeGraphFitSelectionButton, NodeGraphResetZoomButton, NodeGraphToolbarSeparator, NodeGraphZoomInButton, NodeGraphZoomOutButton };
+export type { NodeGraphFitContentButtonProps, NodeGraphFitSelectionButtonProps, NodeGraphToolbarSeparatorProps, NodeGraphZoomButtonProps };

package/dist/types/components/editor/NodeGraph/createTypeMatchValidator.d.ts

@@ -0,0 +1,43 @@
+import { NodeGraphPortRef, NodeGraphConnectionValidationInfo } from './NodeGraph.types.js';
+
+interface TypeMatchValidatorOptions {
+    /**
+     * Allowed `info.sideCombo` values (e.g. `'right->left'`). Defaults to both
+     * horizontal directions so the user can start the drag from either end of
+     * a wire. Pass `['right->left']` to force output→input only.
+     * @default ['right->left', 'left->right']
+     */
+    directions?: ReadonlyArray<string>;
+    /**
+     * `dataType` token that connects to anything. @default 'any'
+     */
+    anyType?: string;
+    /**
+     * Allow connecting two ports on the same node. @default false
+     */
+    allowSameNode?: boolean;
+    /**
+     * Custom type comparison, replacing the default (equality + `anyType` +
+     * "untyped ports accept anything"). Receives the resolved `dataType`s,
+     * either of which may be `undefined` when the port declared none.
+     */
+    match?: (sourceDataType: string | undefined, targetDataType: string | undefined) => boolean;
+}
+/**
+ * Build an `isValidConnection` validator for the common "connect ports of
+ * matching `dataType`, in an allowed direction" rule — the logic most node
+ * editors hand-write. Drop the result straight onto `<NodeGraph>`:
+ *
+ * ```tsx
+ * const isValidConnection = useMemo(() => createTypeMatchValidator(), []);
+ * <NodeGraph isValidConnection={isValidConnection} />
+ * ```
+ *
+ * The default `match` accepts a connection when either port is untyped, the
+ * two `dataType`s are equal, or one side is the `anyType` token. Override
+ * `match` for richer rules (subtype graphs, numeric coercion, etc.).
+ */
+declare function createTypeMatchValidator(options?: TypeMatchValidatorOptions): (source: NodeGraphPortRef, target: NodeGraphPortRef, info: NodeGraphConnectionValidationInfo) => boolean;
+
+export { createTypeMatchValidator };
+export type { TypeMatchValidatorOptions };

package/dist/types/components/editor/NodeGraph/nodeGraphActions.d.ts

@@ -0,0 +1,39 @@
+import { NodeGraphNode, NodeGraphEdge, NodeGraphPortRef } from './NodeGraph.types.js';
+import { Point2D } from '../../primitives/canvas/canvas.types.js';
+
+/**
+ * Ids of every edge with an endpoint on the given port — i.e. all wires
+ * connected to one socket. Use it to "detach all" or select a socket's wires
+ * without maintaining a parallel index.
+ */
+declare function edgesConnectedToPort(edges: ReadonlyArray<NodeGraphEdge>, ref: NodeGraphPortRef): string[];
+interface DuplicateNodesOptions {
+    /**
+     * World-unit offset applied to each clone so it doesn't sit exactly on
+     * top of its source. @default { x: 32, y: 32 }
+     */
+    offset?: Point2D;
+    /**
+     * Build the id for a clone from its source id. Defaults to a unique id
+     * derived from `${sourceId}-copy`. Override to keep your own id scheme.
+     */
+    idFactory?: (sourceId: string) => string;
+}
+/**
+ * Clone the nodes whose ids are listed in `ids`, offsetting each copy.
+ * Pure — returns only the new node objects (not merged into the source
+ * list), so callers stay in control of ordering and selection:
+ *
+ * ```ts
+ * const copies = duplicateNodes(nodes, selection.nodes);
+ * setNodes(prev => [...prev, ...copies]);
+ * setSelection({ nodes: copies.map(n => n.id), edges: [], groups: [] });
+ * ```
+ *
+ * Edges between duplicated nodes are intentionally not copied — wire that
+ * in at the call site if your editor needs it.
+ */
+declare function duplicateNodes(nodes: ReadonlyArray<NodeGraphNode>, ids: ReadonlyArray<string>, options?: DuplicateNodesOptions): NodeGraphNode[];
+
+export { duplicateNodes, edgesConnectedToPort };
+export type { DuplicateNodesOptions };

package/dist/types/components/editor/NodeGraph/nodeGraphIds.d.ts

@@ -0,0 +1,16 @@
+import { NodeGraphPortRef } from './NodeGraph.types.js';
+
+/**
+ * Generate a unique-enough id for a freshly-spawned node from a template.
+ * Format: `${templateId}-${timestamp36}-${counter36}-${random36}`.
+ */
+declare function generateNodeId(templateId: string): string;
+/**
+ * Generate a unique edge id from its endpoints. Includes source/target
+ * port refs in the id so it's somewhat readable in devtools, plus the
+ * standard timestamp + counter + random tail to guarantee uniqueness
+ * across rapid back-to-back connections.
+ */
+declare function generateEdgeId(source: NodeGraphPortRef, target: NodeGraphPortRef): string;
+
+export { generateEdgeId, generateNodeId };