@pixerate/editor 0.163.0 → 0.165.0

package/dist/canvas/displacement.d.ts

@@ -1,11 +1,30 @@
-import type { CanvasEdge, CanvasNode, DirectionalDisplacementOptions, Rect, ReflowDisplacementOptions, XYPosition } from './types.js';
+import type { CanvasEdge, CanvasLayoutOptions, CanvasNode, DirectionalDisplacementOptions, Rect, ReflowDisplacementOptions, XYPosition } from './types.js';
 /**
  * Calculates a bounding rectangle for a set of nodes if not provided by getNodesBounds.
  */
 export declare function computeNodesBoundingBox<TNode extends CanvasNode = CanvasNode>(nodes: TNode[], defaultWidth?: number, defaultHeight?: number): Rect;
+/** A node's size: measured, then explicit, then the defaults. */
+export declare function nodeSizeOf<TNode extends CanvasNode = CanvasNode>(node: TNode, defaultWidth?: number, defaultHeight?: number): {
+    width: number;
+    height: number;
+};
 /**
  * Pure directional displacement calculation.
- * Shifts downstream or surrounding nodes along an axis to clear space for newly inserted child nodes.
+ *
+ * Shifts surrounding nodes along an axis to clear space for a cluster of child nodes inserted
+ * next to `originNode`, and returns the new positions of the nodes that move (nothing is mutated).
+ *
+ * - `right` / `left` push nodes on that side by the cluster's width plus `gap`; Y is preserved
+ *   (except for `spreadSiblingLanes` with `right`).
+ * - `up` / `down` push nodes on that side by the cluster's height plus `gap`; X is preserved.
+ * - `vertical` opens the origin's row: nodes above move up and nodes below move down by the same
+ *   amount (the larger of the two clearances); X is preserved and the origin's row stays put.
+ * - `layoutMode: 'row-lane'` buckets nodes into lanes `rowSpacing` apart and rounds vertical
+ *   deltas up to whole lanes.
+ * - `minY` / `maxY` keep moved rows inside a band, stacking clamped rows `rowSpacing` apart.
+ *
+ * @throws RangeError when `gap`, `rowSpacing`, `minY` or `maxY` are not finite, `rowSpacing <= 0`,
+ *   or `minY > maxY`.
  */
 export declare function calculateDirectionalDisplacement<TNode extends CanvasNode = CanvasNode>(params: {
     existingNodes: TNode[];
@@ -14,6 +33,19 @@ export declare function calculateDirectionalDisplacement<TNode extends CanvasNod
     getNodesBounds?: (nodes: TNode[]) => Rect;
     options?: DirectionalDisplacementOptions;
 }): Map<string, XYPosition>;
+/**
+ * Hierarchical Dagre reflow displacement for an explosion: lays out the existing graph plus the
+ * child cluster, anchoring the origin node at its current position so the layout does not jump,
+ * and returns the new positions of existing nodes that move.
+ */
+export declare function calculateReflowDisplacement<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge>(params: {
+    existingNodes: TNode[];
+    existingEdges: TEdge[];
+    originNode: TNode;
+    childNodes: TNode[];
+    childEdges?: TEdge[];
+    options?: CanvasLayoutOptions;
+}): Map<string, XYPosition>;
 /**
  * Calculates Dagre reflow displacement preserving the position of an anchor node.
  */

package/dist/canvas/explosion-tools.d.cts

@@ -0,0 +1,43 @@
+/**
+ * Agent tools for canvas node explosion: `list_explodable_nodes`, `explode_node` and
+ * `collapse_node`. They drive a {@link CanvasExplosionToolTarget}, which a host adapts from the
+ * declarative state (`canvasExplosionToolTarget`) or from an imperative explosion coordinator
+ * (`createCanvasExplosion` / `useCanvasExplosion`, whose `explodeNode` needs the host's children).
+ */
+import type { AgentToolProvider } from '../tools/registry.cjs';
+import type { CanvasExplosionState } from './explosionState.cjs';
+import type { CanvasNode } from './types.cjs';
+/** What the explosion tools drive. */
+export interface CanvasExplosionToolTarget<TNode extends CanvasNode = CanvasNode> {
+    /** The nodes on the canvas (exploded children included or not; they are only listed when explodable). */
+    getNodes: () => readonly TNode[];
+    /** Ids of the exploded nodes. */
+    exploded: () => readonly string[];
+    /** Ids of nodes whose collapse is still animating. Default none. */
+    collapsing?: () => readonly string[];
+    /** `true` when the node can explode, otherwise false or the reason it cannot. Default: every node. */
+    canExplode?: (node: TNode) => boolean | string;
+    /** Explodes a node. Return false (or throw) to refuse. */
+    explode: (nodeId: string) => void | boolean | Promise<void | boolean>;
+    /** Collapses an exploded node. Return false (or throw) to refuse. */
+    collapse: (nodeId: string) => void | boolean | Promise<void | boolean>;
+    /** Several nodes can be exploded at once. Default false: exploding one collapses the other. */
+    multiple?: boolean;
+}
+/** Adapts the declarative explosion state (`createCanvasExplosionState`, `useCanvasExplosionState`) for the tools. */
+export declare function canvasExplosionToolTarget<TNode extends CanvasNode = CanvasNode>(state: CanvasExplosionState, options: {
+    getNodes: () => readonly TNode[];
+    canExplode?: (node: TNode) => boolean | string;
+}): CanvasExplosionToolTarget<TNode>;
+export interface CanvasExplosionToolProviderOptions {
+    /** Provider id (unique per registry). Default `canvas-explosion`. */
+    id?: string;
+    /** Tool-name prefix (`<namespace>__<name>`); defaults to the provider id, `''` for bare names. */
+    namespace?: string;
+    /** Exploding is not allowed: `explode_node` and `collapse_node` are hidden. A string is the reason. */
+    readOnly?: boolean | string | (() => boolean | string);
+    /** Lets the tool list follow changes (e.g. the state's `subscribe`). */
+    subscribe?: (notify: () => void) => () => void;
+}
+/** The explosion tools for a canvas (see the module comment). */
+export declare function createCanvasExplosionToolProvider<TNode extends CanvasNode = CanvasNode>(target: CanvasExplosionToolTarget<TNode>, options?: CanvasExplosionToolProviderOptions): AgentToolProvider;

package/dist/canvas/explosion-tools.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Agent tools for canvas node explosion: `list_explodable_nodes`, `explode_node` and
+ * `collapse_node`. They drive a {@link CanvasExplosionToolTarget}, which a host adapts from the
+ * declarative state (`canvasExplosionToolTarget`) or from an imperative explosion coordinator
+ * (`createCanvasExplosion` / `useCanvasExplosion`, whose `explodeNode` needs the host's children).
+ */
+import type { AgentToolProvider } from '../tools/registry.js';
+import type { CanvasExplosionState } from './explosionState.js';
+import type { CanvasNode } from './types.js';
+/** What the explosion tools drive. */
+export interface CanvasExplosionToolTarget<TNode extends CanvasNode = CanvasNode> {
+    /** The nodes on the canvas (exploded children included or not; they are only listed when explodable). */
+    getNodes: () => readonly TNode[];
+    /** Ids of the exploded nodes. */
+    exploded: () => readonly string[];
+    /** Ids of nodes whose collapse is still animating. Default none. */
+    collapsing?: () => readonly string[];
+    /** `true` when the node can explode, otherwise false or the reason it cannot. Default: every node. */
+    canExplode?: (node: TNode) => boolean | string;
+    /** Explodes a node. Return false (or throw) to refuse. */
+    explode: (nodeId: string) => void | boolean | Promise<void | boolean>;
+    /** Collapses an exploded node. Return false (or throw) to refuse. */
+    collapse: (nodeId: string) => void | boolean | Promise<void | boolean>;
+    /** Several nodes can be exploded at once. Default false: exploding one collapses the other. */
+    multiple?: boolean;
+}
+/** Adapts the declarative explosion state (`createCanvasExplosionState`, `useCanvasExplosionState`) for the tools. */
+export declare function canvasExplosionToolTarget<TNode extends CanvasNode = CanvasNode>(state: CanvasExplosionState, options: {
+    getNodes: () => readonly TNode[];
+    canExplode?: (node: TNode) => boolean | string;
+}): CanvasExplosionToolTarget<TNode>;
+export interface CanvasExplosionToolProviderOptions {
+    /** Provider id (unique per registry). Default `canvas-explosion`. */
+    id?: string;
+    /** Tool-name prefix (`<namespace>__<name>`); defaults to the provider id, `''` for bare names. */
+    namespace?: string;
+    /** Exploding is not allowed: `explode_node` and `collapse_node` are hidden. A string is the reason. */
+    readOnly?: boolean | string | (() => boolean | string);
+    /** Lets the tool list follow changes (e.g. the state's `subscribe`). */
+    subscribe?: (notify: () => void) => () => void;
+}
+/** The explosion tools for a canvas (see the module comment). */
+export declare function createCanvasExplosionToolProvider<TNode extends CanvasNode = CanvasNode>(target: CanvasExplosionToolTarget<TNode>, options?: CanvasExplosionToolProviderOptions): AgentToolProvider;

package/dist/canvas/explosionLayout.d.cts

@@ -0,0 +1,50 @@
+import type { CanvasEdge, CanvasLayoutOptions, CanvasNode, DirectionalDisplacementOptions, ExplosionDisplacementStrategy, Rect, XYPosition } from './types.cjs';
+export interface ComputeCanvasExplosionLayoutParams<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge> {
+    /** Every node on the canvas, including the origin. Never mutated. */
+    existingNodes: TNode[];
+    /** Every edge on the canvas (only read by the `dagre` strategy). */
+    existingEdges?: TEdge[];
+    /** The node that explodes. */
+    originNode: TNode;
+    /** The child nodes at their final positions. Never mutated: the result holds copies. */
+    childNodes: TNode[];
+    /** Edges between children (or from children to existing nodes). */
+    childEdges?: TEdge[];
+    /** How existing nodes make room. Default `directional`. */
+    strategy?: ExplosionDisplacementStrategy;
+    /** Options for the `directional` strategy. */
+    options?: DirectionalDisplacementOptions;
+    /** Options for the `dagre` strategy. */
+    reflowOptions?: CanvasLayoutOptions;
+    /** Add parent-to-child edges: every child (`true` / `'all'`), the first child only, or none. Default `false`. */
+    connectParentToChildren?: boolean | 'first' | 'all';
+    /** Builds a parent-to-child edge. Default `{ id: 'explode:<parent>:<child>', source, target, type: 'default' }`. */
+    createEdge?: (sourceId: string, targetId: string) => TEdge;
+    /** Bounds of a set of nodes (e.g. the flow instance's `getNodesBounds`). Default: measured sizes. */
+    getNodesBounds?: (nodes: TNode[]) => Rect;
+}
+export interface CanvasExplosionLayoutResult<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge> {
+    /** New positions of the existing nodes that move to make room, by id. */
+    displacedPositions: Map<string, XYPosition>;
+    /** Where each displaced node was before, by id (what a collapse restores). */
+    originalPositions: Map<string, XYPosition>;
+    /** Copies of the child nodes at their final positions. */
+    childNodes: TNode[];
+    /** The child edges plus any parent-to-child edges (deduplicated). */
+    childEdges: TEdge[];
+    /** Bounds of the child cluster. */
+    childBounds: Rect;
+    /** The largest distance any displaced node moves along either axis (0 when nothing moves). */
+    totalDisplacementDelta: number;
+}
+/** The default id of a parent-to-child edge added by an explosion. */
+export declare const explosionEdgeId: (sourceId: string, targetId: string) => string;
+/**
+ * Pure explosion layout: works out where existing nodes move to make room for a child cluster
+ * and which edges the explosion adds, without touching the inputs. Feed the result to a
+ * declarative derivation (`$derived`, `useMemo`) or to an imperative graph coordinator.
+ *
+ * @throws Error when the origin is not in `existingNodes`, or a child id is already on the canvas
+ *   or repeated.
+ */
+export declare function computeCanvasExplosionLayout<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge>(params: ComputeCanvasExplosionLayoutParams<TNode, TEdge>): CanvasExplosionLayoutResult<TNode, TEdge>;

package/dist/canvas/explosionLayout.d.ts

@@ -0,0 +1,50 @@
+import type { CanvasEdge, CanvasLayoutOptions, CanvasNode, DirectionalDisplacementOptions, ExplosionDisplacementStrategy, Rect, XYPosition } from './types.js';
+export interface ComputeCanvasExplosionLayoutParams<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge> {
+    /** Every node on the canvas, including the origin. Never mutated. */
+    existingNodes: TNode[];
+    /** Every edge on the canvas (only read by the `dagre` strategy). */
+    existingEdges?: TEdge[];
+    /** The node that explodes. */
+    originNode: TNode;
+    /** The child nodes at their final positions. Never mutated: the result holds copies. */
+    childNodes: TNode[];
+    /** Edges between children (or from children to existing nodes). */
+    childEdges?: TEdge[];
+    /** How existing nodes make room. Default `directional`. */
+    strategy?: ExplosionDisplacementStrategy;
+    /** Options for the `directional` strategy. */
+    options?: DirectionalDisplacementOptions;
+    /** Options for the `dagre` strategy. */
+    reflowOptions?: CanvasLayoutOptions;
+    /** Add parent-to-child edges: every child (`true` / `'all'`), the first child only, or none. Default `false`. */
+    connectParentToChildren?: boolean | 'first' | 'all';
+    /** Builds a parent-to-child edge. Default `{ id: 'explode:<parent>:<child>', source, target, type: 'default' }`. */
+    createEdge?: (sourceId: string, targetId: string) => TEdge;
+    /** Bounds of a set of nodes (e.g. the flow instance's `getNodesBounds`). Default: measured sizes. */
+    getNodesBounds?: (nodes: TNode[]) => Rect;
+}
+export interface CanvasExplosionLayoutResult<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge> {
+    /** New positions of the existing nodes that move to make room, by id. */
+    displacedPositions: Map<string, XYPosition>;
+    /** Where each displaced node was before, by id (what a collapse restores). */
+    originalPositions: Map<string, XYPosition>;
+    /** Copies of the child nodes at their final positions. */
+    childNodes: TNode[];
+    /** The child edges plus any parent-to-child edges (deduplicated). */
+    childEdges: TEdge[];
+    /** Bounds of the child cluster. */
+    childBounds: Rect;
+    /** The largest distance any displaced node moves along either axis (0 when nothing moves). */
+    totalDisplacementDelta: number;
+}
+/** The default id of a parent-to-child edge added by an explosion. */
+export declare const explosionEdgeId: (sourceId: string, targetId: string) => string;
+/**
+ * Pure explosion layout: works out where existing nodes move to make room for a child cluster
+ * and which edges the explosion adds, without touching the inputs. Feed the result to a
+ * declarative derivation (`$derived`, `useMemo`) or to an imperative graph coordinator.
+ *
+ * @throws Error when the origin is not in `existingNodes`, or a child id is already on the canvas
+ *   or repeated.
+ */
+export declare function computeCanvasExplosionLayout<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge>(params: ComputeCanvasExplosionLayoutParams<TNode, TEdge>): CanvasExplosionLayoutResult<TNode, TEdge>;

package/dist/canvas/explosionState.d.cts

@@ -0,0 +1,52 @@
+/**
+ * Headless, framework-free state machine for canvas node explosion: which node is exploded,
+ * which is collapsing (children still mounted while a collapse animation plays), and the timer
+ * that ends the collapse. It never touches a graph or the DOM, so a declarative canvas can derive
+ * its nodes from it. The Svelte rune `createCanvasExplosionState` and the React hook
+ * `useCanvasExplosionState` wrap it.
+ */
+export interface CanvasExplosionStateOptions {
+    /** How long children stay rendered after a collapse starts, in ms. Default 380. `0` ends the collapse at once. */
+    collapseDurationMs?: number;
+    /** The node exploded at creation. Default none. */
+    initialActiveId?: string | null;
+    /** Called after a node explodes. */
+    onExplode?: (nodeId: string) => void;
+    /** Called when a node starts collapsing (including when exploding another node replaces it). */
+    onCollapse?: (nodeId: string) => void;
+}
+/** The state at one moment. A new object each time it changes, so it can be compared by identity. */
+export interface CanvasExplosionStateSnapshot {
+    /** The exploded node, or null. */
+    readonly activeId: string | null;
+    /** The node whose collapse animation is playing, or null. */
+    readonly collapsingId: string | null;
+}
+export interface CanvasExplosionState extends CanvasExplosionStateSnapshot {
+    /** True while a node is exploded or collapsing (children are on screen). */
+    readonly isExplodingOrCollapsing: boolean;
+    isExploded: (nodeId: string) => boolean;
+    isCollapsing: (nodeId: string) => boolean;
+    /** True when the node's children should be rendered: it is exploded or still collapsing. */
+    shouldRenderChildren: (nodeId: string) => boolean;
+    /** Explodes a node, replacing (collapsing) any other exploded node. Returns false when it already was. */
+    explode: (nodeId: string) => boolean;
+    /** Collapses the exploded node (only if it is `nodeId`, when given). Returns false when nothing collapsed. */
+    collapse: (nodeId?: string) => boolean;
+    /** Collapses the node when it is exploded, otherwise explodes it. Returns true when it is now exploded. */
+    toggle: (nodeId: string) => boolean;
+    /** Ends a running collapse now (e.g. from an `animationend` handler) instead of waiting for the timer. */
+    finishCollapse: () => void;
+    /** Clears the collapse timer and listeners; later calls do nothing. */
+    destroy: () => void;
+}
+export interface CanvasExplosionStateController extends CanvasExplosionState {
+    /** The current state; the same object until something changes. */
+    getSnapshot: () => CanvasExplosionStateSnapshot;
+    /** Calls `listener` after every change; returns an unsubscribe function. */
+    subscribe: (listener: () => void) => () => void;
+    /** True after `destroy()`. */
+    readonly destroyed: boolean;
+}
+/** Creates the headless explosion state machine (see the module comment). */
+export declare function createCanvasExplosionStateController(options?: CanvasExplosionStateOptions): CanvasExplosionStateController;

package/dist/canvas/explosionState.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Headless, framework-free state machine for canvas node explosion: which node is exploded,
+ * which is collapsing (children still mounted while a collapse animation plays), and the timer
+ * that ends the collapse. It never touches a graph or the DOM, so a declarative canvas can derive
+ * its nodes from it. The Svelte rune `createCanvasExplosionState` and the React hook
+ * `useCanvasExplosionState` wrap it.
+ */
+export interface CanvasExplosionStateOptions {
+    /** How long children stay rendered after a collapse starts, in ms. Default 380. `0` ends the collapse at once. */
+    collapseDurationMs?: number;
+    /** The node exploded at creation. Default none. */
+    initialActiveId?: string | null;
+    /** Called after a node explodes. */
+    onExplode?: (nodeId: string) => void;
+    /** Called when a node starts collapsing (including when exploding another node replaces it). */
+    onCollapse?: (nodeId: string) => void;
+}
+/** The state at one moment. A new object each time it changes, so it can be compared by identity. */
+export interface CanvasExplosionStateSnapshot {
+    /** The exploded node, or null. */
+    readonly activeId: string | null;
+    /** The node whose collapse animation is playing, or null. */
+    readonly collapsingId: string | null;
+}
+export interface CanvasExplosionState extends CanvasExplosionStateSnapshot {
+    /** True while a node is exploded or collapsing (children are on screen). */
+    readonly isExplodingOrCollapsing: boolean;
+    isExploded: (nodeId: string) => boolean;
+    isCollapsing: (nodeId: string) => boolean;
+    /** True when the node's children should be rendered: it is exploded or still collapsing. */
+    shouldRenderChildren: (nodeId: string) => boolean;
+    /** Explodes a node, replacing (collapsing) any other exploded node. Returns false when it already was. */
+    explode: (nodeId: string) => boolean;
+    /** Collapses the exploded node (only if it is `nodeId`, when given). Returns false when nothing collapsed. */
+    collapse: (nodeId?: string) => boolean;
+    /** Collapses the node when it is exploded, otherwise explodes it. Returns true when it is now exploded. */
+    toggle: (nodeId: string) => boolean;
+    /** Ends a running collapse now (e.g. from an `animationend` handler) instead of waiting for the timer. */
+    finishCollapse: () => void;
+    /** Clears the collapse timer and listeners; later calls do nothing. */
+    destroy: () => void;
+}
+export interface CanvasExplosionStateController extends CanvasExplosionState {
+    /** The current state; the same object until something changes. */
+    getSnapshot: () => CanvasExplosionStateSnapshot;
+    /** Calls `listener` after every change; returns an unsubscribe function. */
+    subscribe: (listener: () => void) => () => void;
+    /** True after `destroy()`. */
+    readonly destroyed: boolean;
+}
+/** Creates the headless explosion state machine (see the module comment). */
+export declare function createCanvasExplosionStateController(options?: CanvasExplosionStateOptions): CanvasExplosionStateController;