@pixerate/editor 0.19.0 → 0.21.0

package/dist/canvas/index.d.ts

@@ -1,5 +1,6 @@
-import { R as Rect, C as CanvasNode, X as XYPosition, a as CanvasEdge, I as IncrementalLayoutOptions, S as Side, b as CanvasLayoutOptions, P as PlaceBesideOptions, T as TrajectoryFunction, F as FanOutTrajectoryOptions, N as NodeTransition, c as CanvasNodeStyle, d as ReflowDisplacementOptions, D as DirectionalDisplacementOptions, e as CanvasClipboardPayload } from '../types-JV3S8VeR.js';
-export { f as CanvasDockingCallbacks, g as CollapseNodeOptions, h as DisplacementDirection, i as DockStrategy, E as ExplodeNodeOptions, j as ExplosionSnapshot, G as GraphDifferences, k as Point, l as Position, m as TrajectoryPoint } from '../types-JV3S8VeR.js';
+import { R as Rect, C as CanvasNode, X as XYPosition, a as CanvasEdge, I as IncrementalLayoutOptions, S as Side, b as CanvasLayoutOptions, P as PlaceBesideOptions, T as TrajectoryFunction, F as FanOutTrajectoryOptions, N as NodeTransition, c as CanvasNodeStyle, d as ReflowDisplacementOptions, D as DirectionalDisplacementOptions, e as CanvasClipboardPayload, f as Position } from '../types-DMe0vFB1.js';
+export { g as CanvasDockingCallbacks, h as CollapseNodeOptions, i as DisplacementDirection, j as DockStrategy, E as ExplodeNodeOptions, k as ExplosionSnapshot, G as GraphDifferences, l as Point, m as TrajectoryPoint } from '../types-DMe0vFB1.js';
+import { C as Command } from '../types-BZgcDsC5.js';
 
 declare const DEFAULT_NODE_WIDTH = 200;
 declare const DEFAULT_NODE_HEIGHT = 60;
@@ -327,4 +328,515 @@ declare function blendLayout<TNode extends CanvasNode = CanvasNode>(from: TNode[
  */
 declare function connectedOnly<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge>(nodes: TNode[], edges: TEdge[]): TNode[];
 
-export { CanvasClipboardPayload, CanvasEdge, type CanvasHeightOptions, CanvasLayoutOptions, CanvasNode, CanvasNodeStyle, type Clock, DEFAULT_NODE_HEIGHT, DEFAULT_NODE_WIDTH, DEFAULT_PLACEMENT_GAP, DirectionalDisplacementOptions, FanOutTrajectoryOptions, IncrementalLayoutOptions, ManualClock, type MultiNodeTransitionOptions, NodeTransition, PlaceBesideOptions, Rect, ReflowDisplacementOptions, Side, StreamingLayoutManager, type StreamingLayoutManagerOptions, TrajectoryFunction, XYPosition, blendLayout, boundsOf, calculateDagreReflowDisplacement, calculateDirectionalDisplacement, canvasHeight, centerNodes, centre, computeNodesBoundingBox, connectedOnly, createBezierTrajectory, createFanOutTrajectory, defaultEasing, ensureLayout, estimateCanvasHeight, estimateNodeSize, flowSide, getCenteredNodePosition, getLayoutedNodes, isEventFromTextInput, isValidCanvasEdge, isValidCanvasNode, isValidUrl, layoutBounds, linearPositionTrajectory, linearTrajectory, overlaps, pageHidden, parseCanvasClipboardData, placeBeside, realClock, remapPastedNodes, repositionNodesTo, runMultiNodeTransition, serializeCanvasNodes, withStyleOpacity };
+/**
+ * Edge (or centre line) used by `alignNodes`.
+ * `center` aligns horizontal centres (a vertical line); `middle` aligns vertical centres.
+ */
+type AlignEdge = 'left' | 'center' | 'right' | 'top' | 'middle' | 'bottom';
+/** Axis used by `distributeNodes`. `both` distributes horizontally and vertically. */
+type DistributeAxis = 'horizontal' | 'vertical' | 'both';
+/**
+ * `gaps` leaves equal space between neighbouring nodes, `centres` spaces their centres equally.
+ */
+type DistributeMode = 'gaps' | 'centres';
+/** Dimension(s) copied by `matchSize`. */
+type SizeDimension = 'width' | 'height' | 'both';
+/**
+ * Partial node change produced by the arrange helpers. `position` is in the node's own
+ * coordinate space (relative to its `parentId` parent when it has one).
+ */
+interface CanvasNodeUpdate {
+    id: string;
+    position?: XYPosition;
+    width?: number;
+    height?: number;
+    zIndex?: number;
+}
+interface NodeRectOptions {
+    /** Width used when a node has no measured, explicit or style size and estimation is off. */
+    defaultWidth?: number;
+    /** Height used when a node has no measured, explicit or style size and estimation is off. */
+    defaultHeight?: number;
+    /** Estimate unmeasured node sizes from their label via `estimateNodeSize` (default `true`). */
+    estimate?: boolean;
+}
+/** Data key marking a node as locked. See `lockNodes`. */
+declare const LOCKED_DATA_KEY = "locked";
+/** Data key holding the interaction flags a node had before it was locked. */
+declare const LOCKED_PREVIOUS_FLAGS_KEY = "lockedPrevious";
+/**
+ * Reads a pixel `width` / `height` from a node style, which may be a CSS string (SvelteFlow)
+ * or a style object (React Flow). Non-pixel values (`%`, `auto`, ...) are ignored.
+ */
+declare function readStyleSize(style: CanvasNodeStyle | undefined | null): {
+    width?: number;
+    height?: number;
+};
+/**
+ * Returns `style` with its pixel `width` / `height` replaced, keeping its representation
+ * (string or object). Only dimensions already present in the style are rewritten, because
+ * xyflow applies the node's own `width` / `height` props otherwise.
+ */
+declare function withStyleSize(style: CanvasNodeStyle | undefined | null, size: {
+    width?: number;
+    height?: number;
+}): CanvasNodeStyle | undefined;
+/**
+ * Resolves a node's size: measured DOM size, then explicit `width` / `height`, then a pixel
+ * size in `style`, then a label-based estimate (or the defaults when `estimate` is `false`).
+ */
+declare function getNodeSize(node: CanvasNode, options?: NodeRectOptions): {
+    width: number;
+    height: number;
+};
+/**
+ * Absolute (flow-space) position of a node, following its `parentId` chain.
+ * Cycles and missing parents are tolerated.
+ */
+declare function getAbsolutePosition(node: CanvasNode, lookup: ReadonlyMap<string, CanvasNode>): XYPosition;
+/** Builds an id lookup for a node array. */
+declare function createNodeLookup<TNode extends CanvasNode>(nodes: TNode[]): Map<string, TNode>;
+/** Absolute flow-space rectangle of a node. */
+declare function getNodeRect(node: CanvasNode, lookup?: ReadonlyMap<string, CanvasNode>, options?: NodeRectOptions): Rect;
+/**
+ * Whether a node has been locked with `lockNodes`.
+ */
+declare function isLocked(node: CanvasNode | undefined | null): boolean;
+/**
+ * Locks nodes: marks `data.locked = true` and sets `draggable: false` and `deletable: false`
+ * so both SvelteFlow and React Flow stop dragging and deleting them. Nodes stay `selectable`
+ * so they can be unlocked again. The previous flags are kept in `data.lockedPrevious` and
+ * restored by `unlockNodes`. Returns a new array; untouched nodes keep their identity.
+ */
+declare function lockNodes<TNode extends CanvasNode>(nodes: TNode[], ids: Iterable<string>): TNode[];
+/**
+ * Reverses `lockNodes`, restoring the `draggable` / `deletable` flags the node had before.
+ */
+declare function unlockNodes<TNode extends CanvasNode>(nodes: TNode[], ids: Iterable<string>): TNode[];
+/** Locks the given nodes if any of them is unlocked, otherwise unlocks them all. */
+declare function toggleLockNodes<TNode extends CanvasNode>(nodes: TNode[], ids: Iterable<string>): TNode[];
+interface AlignNodesOptions extends NodeRectOptions {
+    /**
+     * What to align to: the selection bounding box (default) or a fixed rectangle.
+     * Locked nodes never move but still count towards the selection bounds, so they act as anchors.
+     */
+    to?: 'selection' | Rect;
+}
+/**
+ * Aligns nodes to a shared edge or centre line of their bounding box (Freeform's
+ * Align Left / Center / Right / Top / Middle / Bottom). Needs at least two nodes unless
+ * `options.to` is a rectangle. Locked nodes are not moved.
+ */
+declare function alignNodes(nodes: CanvasNode[], ids: Iterable<string>, edge: AlignEdge, options?: AlignNodesOptions): CanvasNodeUpdate[];
+interface DistributeNodesOptions extends NodeRectOptions {
+    /** Explicit gap between neighbours for `gaps` mode. Default: spread evenly between the outer nodes. */
+    gap?: number;
+}
+/**
+ * Distributes nodes along an axis (Freeform's Distribute Horizontally / Vertically / Evenly).
+ * The outermost nodes stay put and the others are spaced with equal gaps (`gaps`, default)
+ * or equally spaced centres (`centres`). Needs at least three nodes (two with an explicit
+ * `gap`). Locked nodes keep their place in the order but are not moved.
+ */
+declare function distributeNodes(nodes: CanvasNode[], ids: Iterable<string>, axis: DistributeAxis, mode?: DistributeMode, options?: DistributeNodesOptions): CanvasNodeUpdate[];
+interface MatchSizeOptions extends NodeRectOptions {
+    /**
+     * Size source: the `largest` (default) or `smallest` node, the `first` id given,
+     * or a specific node id.
+     */
+    reference?: 'largest' | 'smallest' | 'first' | {
+        id: string;
+    };
+    /** Keep each node's centre in place instead of its top-left corner (default `false`). */
+    keepCentre?: boolean;
+}
+/**
+ * Makes nodes the same width, height or both (Freeform's Make Same Size). Returns size
+ * updates (plus position updates with `keepCentre`). Locked nodes are not resized but can
+ * be the reference.
+ */
+declare function matchSize(nodes: CanvasNode[], ids: Iterable<string>, dimension: SizeDimension, options?: MatchSizeOptions): CanvasNodeUpdate[];
+/** Z-order operation. */
+type ZOrderOperation = 'bringForward' | 'sendBackward' | 'bringToFront' | 'sendToBack';
+/**
+ * Restacks nodes (Bring Forward / Send Backward / Bring to Front / Send to Back).
+ *
+ * Both SvelteFlow and React Flow stack nodes by `zIndex` (missing = 0) and, for equal
+ * `zIndex`, by array order. This computes that effective order for the siblings that share
+ * the targets' parent, applies the operation, and returns `zIndex` updates assigning each
+ * sibling its new rank. The array order is left alone, because xyflow requires parents to
+ * precede their children. Locked nodes are not restacked. "Forward" moves past the next
+ * sibling the node overlaps, falling back to the next sibling when nothing overlaps.
+ */
+declare function reorderNodes(nodes: CanvasNode[], ids: Iterable<string>, operation: ZOrderOperation, options?: NodeRectOptions): CanvasNodeUpdate[];
+/**
+ * Applies `CanvasNodeUpdate`s to a node array, returning a new array. Unchanged nodes keep
+ * their identity. Size updates set `width` / `height` and rewrite pixel sizes already present
+ * in `style` (string or object). An existing `measured` size is updated too, so geometry
+ * helpers see the new size before xyflow re-measures the node.
+ */
+declare function applyNodeUpdates<TNode extends CanvasNode>(nodes: TNode[], updates: CanvasNodeUpdate[]): TNode[];
+/**
+ * Inverse of a set of updates against the current nodes, for undo. Restores the previous
+ * position / size / zIndex of every node an update touches.
+ */
+declare function invertNodeUpdates(nodes: CanvasNode[], updates: CanvasNodeUpdate[]): CanvasNodeUpdate[];
+
+/**
+ * A guide line to render while dragging, in flow coordinates.
+ * `edge` and `centre` guides are alignment lines; `spacing` guides mark equal gaps.
+ */
+interface GuideLine {
+    orientation: 'vertical' | 'horizontal';
+    kind: 'edge' | 'centre' | 'spacing';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+interface SnapGuidesOptions {
+    /** Current viewport zoom; the threshold is in screen pixels and divided by it (default 1). */
+    zoom?: number;
+    /** Snap distance in screen pixels (default 6). */
+    threshold?: number;
+    /** Snap edges to other shapes' edges (default `true`). */
+    edges?: boolean;
+    /** Snap centres to other shapes' centres (default `true`). */
+    centres?: boolean;
+    /** Snap to equal spacing between neighbouring shapes in the same row / column (default `true`). */
+    spacing?: boolean;
+}
+interface SnapResult {
+    /** Snapped top-left of the moving rectangle. */
+    position: XYPosition;
+    /** Offset applied to the input rectangle (`position - rect`). */
+    offset: XYPosition;
+    /** Guide segments to draw for the snap that was applied. */
+    guides: GuideLine[];
+    snappedX: boolean;
+    snappedY: boolean;
+}
+interface AxisEntries {
+    values: Float64Array;
+    rects: Rect[];
+}
+/**
+ * Pre-sorted snap targets for a set of static rectangles. Build it once when a drag starts
+ * and reuse it on every pointer move; each query is a binary search, so snapping stays
+ * cheap with hundreds or thousands of shapes.
+ */
+interface GuideIndex {
+    rects: Rect[];
+    edgeX: AxisEntries;
+    centreX: AxisEntries;
+    edgeY: AxisEntries;
+    centreY: AxisEntries;
+}
+/** Builds a `GuideIndex` from the rectangles the moving shape may snap to. */
+declare function createGuideIndex(rects: Rect[]): GuideIndex;
+/**
+ * Computes smart-guide snapping for a moving rectangle (a dragged node or a selection's
+ * bounding box) against other shapes. Edges snap to edges and centres to centres within
+ * `threshold` screen pixels (converted to flow units via `zoom`). Each axis snaps
+ * independently to its nearest candidate. Returns the snapped position and the guides to draw.
+ */
+declare function computeSnapGuides(moving: Rect, targets: Rect[] | GuideIndex, options?: SnapGuidesOptions): SnapResult;
+/** Ids of the given nodes plus every descendant (children move with their parent). */
+declare function collectDescendantIds(nodes: CanvasNode[], ids: Iterable<string>): Set<string>;
+/**
+ * Builds a `GuideIndex` of every node except the dragged ones and their descendants.
+ * Call once at drag start and pass it to `snapNodeDrag` on every move.
+ */
+declare function createNodeGuideIndex(nodes: CanvasNode[], draggingIds: Iterable<string>, options?: NodeRectOptions & {
+    filter?: (node: CanvasNode) => boolean;
+}): GuideIndex;
+interface SnapNodeDragOptions extends SnapGuidesOptions, NodeRectOptions {
+    /** Index from `createNodeGuideIndex`, reused across drag frames. Built on demand when omitted. */
+    index?: GuideIndex;
+}
+interface SnapNodeDragResult extends SnapResult {
+    /** Position updates moving every dragged node by `offset` (node-relative coordinates). */
+    updates: CanvasNodeUpdate[];
+}
+/**
+ * Snaps a drag of one or more nodes. The dragged nodes' bounding box is snapped against all
+ * other nodes; the resulting offset is applied to each dragged node. Dragged nodes whose
+ * parent is also dragged are skipped, because they move with the parent.
+ */
+declare function snapNodeDrag(nodes: CanvasNode[], draggingIds: Iterable<string>, options?: SnapNodeDragOptions): SnapNodeDragResult;
+
+/**
+ * Connection line styles supported by both SvelteFlow and React Flow
+ * (`connectionLineType` / edge `type`).
+ */
+type CanvasConnectionLineType = 'default' | 'straight' | 'step' | 'smoothstep' | 'simplebezier';
+declare const CONNECTION_LINE_TYPES: readonly CanvasConnectionLineType[];
+/** Maps a handle `Position` to the placement `Side` vocabulary used by `placeBeside`. */
+declare function positionToSide(position: Position): Side;
+/** Maps a placement `Side` to the handle `Position` vocabulary used by xyflow. */
+declare function sideToPosition(side: Side): Position;
+/** The handle position facing the other way. */
+declare function oppositePosition(position: Position): Position;
+/** Midpoint of a rectangle's side, where a centred handle sits. */
+declare function handlePoint(rect: Rect, position: Position): XYPosition;
+interface ConnectorSnapTarget {
+    id: string;
+    rect: Rect;
+    /** Sides that can accept a connection (default: all four). */
+    positions?: Position[];
+}
+interface ConnectorSnapOptions {
+    /** Viewport zoom; `radius` is in screen pixels and divided by it (default 1). */
+    zoom?: number;
+    /** How far outside a shape the pointer may be and still attach, in screen pixels (default 24). */
+    radius?: number;
+    /** Node ids that cannot be attached to, e.g. the connection's source node. */
+    excludeIds?: Iterable<string>;
+    /**
+     * `handle` snaps to the side's midpoint (a centred handle, default). `edge` snaps to the
+     * closest point along that side, for floating edges.
+     */
+    mode?: 'handle' | 'edge';
+}
+interface ConnectorSnap {
+    nodeId: string;
+    position: Position;
+    side: Side;
+    /** Attachment point in flow coordinates. */
+    point: XYPosition;
+    /** Distance from the pointer to `point`, in flow units. */
+    distance: number;
+}
+/**
+ * Finds the shape side a connection line should attach to for a pointer (flow coordinates).
+ * Shapes the pointer is inside win over shapes it is merely near; among those, the closest
+ * allowed side wins. Returns `null` when nothing is within `radius`.
+ */
+declare function findConnectorSnap(pointer: XYPosition, targets: ConnectorSnapTarget[], options?: ConnectorSnapOptions): ConnectorSnap | null;
+/**
+ * Picks the facing sides for a connection between two shapes, the way Freeform attaches
+ * connection lines: along the axis with the larger centre offset.
+ */
+declare function nearestHandlePositions(source: Rect, target: Rect): {
+    source: Position;
+    target: Position;
+};
+
+/**
+ * Viewport transform in xyflow's convention: `screen = flow * zoom + (x, y)`.
+ */
+interface CanvasViewport {
+    x: number;
+    y: number;
+    zoom: number;
+}
+/**
+ * A named, saved view of the canvas (Freeform "Scenes").
+ */
+interface CanvasScene {
+    id: string;
+    name: string;
+    viewport: CanvasViewport;
+    /** Optional nodes the scene is about, e.g. to re-fit the scene after they move. */
+    nodeIds?: string[];
+}
+interface CanvasScenesState {
+    scenes: readonly CanvasScene[];
+    /** Id of the scene last shown, or `null`. */
+    currentId: string | null;
+    /** Index of the current scene, or `-1`. */
+    currentIndex: number;
+}
+interface CanvasScenesOptions {
+    initialScenes?: CanvasScene[];
+    /** Id generator for new scenes (default: `crypto.randomUUID` with a counter fallback). */
+    createId?: () => string;
+    /** Whether `next` / `previous` wrap around at the ends (default `false`). */
+    wrap?: boolean;
+    onChange?: (state: CanvasScenesState) => void;
+}
+interface SerializedCanvasScenes {
+    version: 1;
+    scenes: CanvasScene[];
+}
+/** Validates the shape of a scene. */
+declare function isValidCanvasScene(value: unknown): value is CanvasScene;
+/**
+ * Parses serialized scenes (a JSON string, a `{ version, scenes }` object or a bare array).
+ * Invalid entries and duplicate ids are dropped.
+ */
+declare function parseCanvasScenes(input: string | unknown): CanvasScene[];
+/**
+ * Headless, framework-agnostic store of named viewports. Snapshots returned by `getState()`
+ * are cached and only replaced on change, so it can back React's `useSyncExternalStore`.
+ */
+declare class CanvasScenesStore {
+    private scenes;
+    private currentId;
+    private cached;
+    private listeners;
+    private readonly createId;
+    private readonly onChange?;
+    wrap: boolean;
+    constructor(options?: CanvasScenesOptions);
+    private snapshot;
+    private commit;
+    getState(): CanvasScenesState;
+    getScene(id: string): CanvasScene | undefined;
+    subscribe(listener: (state: CanvasScenesState) => void): () => void;
+    /** First unused "Scene N" name. */
+    nextDefaultName(): string;
+    /**
+     * Adds a scene (appended, or inserted at `index`) and makes it current.
+     */
+    add(input: {
+        viewport: CanvasViewport;
+        name?: string;
+        nodeIds?: string[];
+        id?: string;
+    }, index?: number): CanvasScene;
+    /** Patches a scene's name, viewport or node ids. Returns the updated scene. */
+    update(id: string, patch: Partial<Omit<CanvasScene, 'id'>>): CanvasScene | undefined;
+    rename(id: string, name: string): CanvasScene | undefined;
+    /** Moves a scene to `toIndex` (clamped). */
+    move(id: string, toIndex: number): void;
+    /** Reorders scenes to match `ids`; unknown ids are ignored and missing scenes keep their relative order at the end. */
+    reorder(ids: string[]): void;
+    remove(id: string): void;
+    clear(): void;
+    /** Marks a scene as current and returns it. */
+    goTo(id: string): CanvasScene | undefined;
+    private step;
+    /** Shows the next scene. Returns `undefined` at the end unless `wrap` is on. */
+    next(): CanvasScene | undefined;
+    /** Shows the previous scene. Returns `undefined` at the start unless `wrap` is on. */
+    previous(): CanvasScene | undefined;
+    toJSON(): SerializedCanvasScenes;
+    serialize(): string;
+    /** Replaces all scenes from serialized data (see `parseCanvasScenes`). */
+    load(input: string | unknown): void;
+}
+declare function createCanvasScenesStore(options?: CanvasScenesOptions): CanvasScenesStore;
+interface FitViewportOptions {
+    /** Padding around the content as a fraction of the content size per side (default 0.1, like xyflow). */
+    padding?: number;
+    minZoom?: number;
+    maxZoom?: number;
+}
+/**
+ * Viewport that fits `rect` into a container of `size`, centred (xyflow `fitView` maths).
+ */
+declare function fitViewportToRect(rect: Rect, size: {
+    width: number;
+    height: number;
+}, options?: FitViewportOptions): CanvasViewport;
+/**
+ * Viewport that fits the given nodes (all nodes when `ids` is omitted), or `null` when none match.
+ */
+declare function fitViewportToNodes(nodes: CanvasNode[], size: {
+    width: number;
+    height: number;
+}, ids?: Iterable<string>, options?: FitViewportOptions & NodeRectOptions): CanvasViewport | null;
+
+/**
+ * Canvas arrangement actions that have keyboard shortcuts.
+ */
+type CanvasArrangeAction = 'alignLeft' | 'alignCenter' | 'alignRight' | 'alignTop' | 'alignMiddle' | 'alignBottom' | 'distributeHorizontal' | 'distributeVertical' | 'lock' | 'unlock' | 'bringForward' | 'sendBackward' | 'bringToFront' | 'sendToBack' | 'nextScene' | 'previousScene';
+interface ArrangeShortcutBinding {
+    action: CanvasArrangeAction;
+    /** `KeyboardEvent.code` (layout- and Option-independent, e.g. `KeyA`, `BracketRight`). */
+    code: string;
+    mod?: boolean;
+    alt?: boolean;
+    shift?: boolean;
+    /** Human readable label, e.g. for menus. `Mod` is ⌘ on macOS and Ctrl elsewhere. */
+    label: string;
+}
+/**
+ * Default bindings. Align/distribute follow Figma (Option/Alt + letter), layer order follows
+ * the common `Mod+]` / `Mod+[` convention, lock follows Keynote/Freeform (`Mod+L`,
+ * `Mod+Alt+L` to unlock) and scenes step with PageDown / PageUp.
+ */
+declare const DEFAULT_ARRANGE_SHORTCUTS: readonly ArrangeShortcutBinding[];
+/**
+ * Resolves a keydown event to an arrange action, or `null`. Events from text inputs,
+ * textareas, selects, contenteditable and ProseMirror are ignored (see `isEventFromTextInput`).
+ * `Mod` is ⌘ or Ctrl.
+ */
+declare function matchArrangeShortcut(event: KeyboardEvent, bindings?: readonly ArrangeShortcutBinding[]): CanvasArrangeAction | null;
+
+/** Minimal history surface (`HistoryManager` satisfies it). */
+interface ArrangeHistoryTarget {
+    execute(command: Command): void;
+}
+interface CanvasArrangeControllerOptions<TNode extends CanvasNode = CanvasNode> {
+    getNodes: () => TNode[];
+    setNodes: (nodes: TNode[]) => void;
+    /** Ids acted on when a method is called without ids (default: nodes with `selected: true`). */
+    getSelectedIds?: () => string[];
+    /** When set, every arrange action is recorded as one undoable command. */
+    history?: ArrangeHistoryTarget;
+    /** Current zoom, used to convert the guide threshold from screen pixels (default 1). */
+    getZoom?: () => number;
+    /** Smart-guide options (threshold in screen px, edges / centres / spacing toggles). */
+    guides?: Omit<SnapGuidesOptions, 'zoom'>;
+    /** Turns drag snapping off while keeping the arrange actions (default `true`). */
+    snapping?: boolean;
+    /** Size resolution for unmeasured nodes. */
+    rectOptions?: NodeRectOptions;
+    /** Called whenever the guide segments change (set while dragging, cleared on drop). */
+    onGuidesChange?: (guides: GuideLine[]) => void;
+}
+/** A React Flow / SvelteFlow style node change; only `position` changes are inspected. */
+interface PositionChangeLike {
+    type: string;
+    id: string;
+    position?: XYPosition;
+    dragging?: boolean;
+    [key: string]: any;
+}
+/**
+ * Framework-agnostic arrange controller shared by the Svelte rune and the React hook:
+ * align / distribute / match size / lock / z-order actions on the selection (optionally
+ * undoable through a `HistoryManager`) and smart-guide snapping during drags.
+ */
+declare function createCanvasArrangeController<TNode extends CanvasNode = CanvasNode>(options: CanvasArrangeControllerOptions<TNode>): {
+    readonly guides: GuideLine[];
+    apply: (name: string, updates: CanvasNodeUpdate[]) => CanvasNodeUpdate[];
+    align(edge: AlignEdge, ids?: Iterable<string>, alignOptions?: AlignNodesOptions): CanvasNodeUpdate[];
+    distribute(axis: DistributeAxis, mode?: DistributeMode, ids?: Iterable<string>, distributeOptions?: DistributeNodesOptions): CanvasNodeUpdate[];
+    matchSize(dimension: SizeDimension, ids?: Iterable<string>, sizeOptions?: MatchSizeOptions): CanvasNodeUpdate[];
+    reorder(operation: ZOrderOperation, ids?: Iterable<string>): CanvasNodeUpdate[];
+    bringForward: (ids?: Iterable<string>) => CanvasNodeUpdate[];
+    sendBackward: (ids?: Iterable<string>) => CanvasNodeUpdate[];
+    bringToFront: (ids?: Iterable<string>) => CanvasNodeUpdate[];
+    sendToBack: (ids?: Iterable<string>) => CanvasNodeUpdate[];
+    lock: (ids?: Iterable<string>) => string[];
+    unlock: (ids?: Iterable<string>) => string[];
+    toggleLock(ids?: Iterable<string>): string[];
+    isLocked: (id: string) => boolean;
+    /**
+     * Runs a shortcut action. Scene actions are not handled here (see the scenes store);
+     * returns `false` for them and for unknown actions.
+     */
+    runAction(action: CanvasArrangeAction): boolean;
+    /** Caches the snap targets for a drag. Optional: `drag` builds them lazily. */
+    beginDrag(ids?: Iterable<string>): void;
+    /**
+     * Snaps the dragged nodes (as currently positioned in `getNodes()`) to the other
+     * nodes, writes the snapped positions back through `setNodes` (not recorded in
+     * history) and updates `guides`.
+     */
+    drag(ids?: Iterable<string>): SnapNodeDragResult | null;
+    /**
+     * React Flow style: adjusts dragging `position` changes in an `onNodesChange` batch so
+     * the dragged nodes snap, and updates `guides`. Returns the (possibly new) changes array.
+     * A batch without a dragging position change ends the drag and clears the guides.
+     */
+    snapPositionChanges<TChange extends PositionChangeLike>(changes: TChange[]): TChange[];
+    /** Clears guides and the cached snap targets. */
+    endDrag(): void;
+};
+type CanvasArrangeController<TNode extends CanvasNode = CanvasNode> = ReturnType<typeof createCanvasArrangeController<TNode>>;
+
+export { type AlignEdge, type AlignNodesOptions, type ArrangeHistoryTarget, type ArrangeShortcutBinding, CONNECTION_LINE_TYPES, type CanvasArrangeAction, type CanvasArrangeController, type CanvasArrangeControllerOptions, CanvasClipboardPayload, type CanvasConnectionLineType, CanvasEdge, type CanvasHeightOptions, CanvasLayoutOptions, CanvasNode, CanvasNodeStyle, type CanvasNodeUpdate, type CanvasScene, type CanvasScenesOptions, type CanvasScenesState, CanvasScenesStore, type CanvasViewport, type Clock, type ConnectorSnap, type ConnectorSnapOptions, type ConnectorSnapTarget, DEFAULT_ARRANGE_SHORTCUTS, DEFAULT_NODE_HEIGHT, DEFAULT_NODE_WIDTH, DEFAULT_PLACEMENT_GAP, DirectionalDisplacementOptions, type DistributeAxis, type DistributeMode, type DistributeNodesOptions, FanOutTrajectoryOptions, type FitViewportOptions, type GuideIndex, type GuideLine, IncrementalLayoutOptions, LOCKED_DATA_KEY, LOCKED_PREVIOUS_FLAGS_KEY, ManualClock, type MatchSizeOptions, type MultiNodeTransitionOptions, type NodeRectOptions, NodeTransition, PlaceBesideOptions, Position, type PositionChangeLike, Rect, ReflowDisplacementOptions, type SerializedCanvasScenes, Side, type SizeDimension, type SnapGuidesOptions, type SnapNodeDragOptions, type SnapNodeDragResult, type SnapResult, StreamingLayoutManager, type StreamingLayoutManagerOptions, TrajectoryFunction, XYPosition, type ZOrderOperation, alignNodes, applyNodeUpdates, blendLayout, boundsOf, calculateDagreReflowDisplacement, calculateDirectionalDisplacement, canvasHeight, centerNodes, centre, collectDescendantIds, computeNodesBoundingBox, computeSnapGuides, connectedOnly, createBezierTrajectory, createCanvasArrangeController, createCanvasScenesStore, createFanOutTrajectory, createGuideIndex, createNodeGuideIndex, createNodeLookup, defaultEasing, distributeNodes, ensureLayout, estimateCanvasHeight, estimateNodeSize, findConnectorSnap, fitViewportToNodes, fitViewportToRect, flowSide, getAbsolutePosition, getCenteredNodePosition, getLayoutedNodes, getNodeRect, getNodeSize, handlePoint, invertNodeUpdates, isEventFromTextInput, isLocked, isValidCanvasEdge, isValidCanvasNode, isValidCanvasScene, isValidUrl, layoutBounds, linearPositionTrajectory, linearTrajectory, lockNodes, matchArrangeShortcut, matchSize, nearestHandlePositions, oppositePosition, overlaps, pageHidden, parseCanvasClipboardData, parseCanvasScenes, placeBeside, positionToSide, readStyleSize, realClock, remapPastedNodes, reorderNodes, repositionNodesTo, runMultiNodeTransition, serializeCanvasNodes, sideToPosition, snapNodeDrag, toggleLockNodes, unlockNodes, withStyleOpacity, withStyleSize };