@pixerate/editor 0.162.1 → 0.164.0

package/dist/canvas/index.d.cts

@@ -37,3 +37,6 @@ export * from './effects.cjs';
 export * from './effect-player.cjs';
 export * from './effect-tools.cjs';
 export * from './editorDocument.cjs';
+export * from './explosionLayout.cjs';
+export * from './explosionState.cjs';
+export * from './explosion-tools.cjs';

package/dist/canvas/index.d.ts

@@ -37,3 +37,6 @@ export * from './effects.js';
 export * from './effect-player.js';
 export * from './effect-tools.js';
 export * from './editorDocument.js';
+export * from './explosionLayout.js';
+export * from './explosionState.js';
+export * from './explosion-tools.js';

package/dist/canvas/index.js

@@ -113,10 +113,10 @@ import {
 } from "../chunk-5ED73EC6.js";
 import {
   layoutChart
-} from "../chunk-DTSTNRPH.js";
+} from "../chunk-Z4P2RBMJ.js";
 import {
   createChartSpec
-} from "../chunk-HLOKB7WW.js";
+} from "../chunk-3NEZJCBY.js";
 import "../chunk-II2WIF5Z.js";
 import {
   PathOpsError,
@@ -428,109 +428,162 @@ function computeNodesBoundingBox(nodes, defaultWidth = 200, defaultHeight = 60)
     height: maxY - minY
   };
 }
+function nodeSizeOf(node, defaultWidth = 200, defaultHeight = 60) {
+  return {
+    width: node.measured?.width ?? node.width ?? defaultWidth,
+    height: node.measured?.height ?? node.height ?? defaultHeight
+  };
+}
 function calculateDirectionalDisplacement(params) {
-  const {
-    existingNodes,
-    originNode,
-    childNodes,
-    getNodesBounds,
-    options = {}
-  } = params;
+  const { existingNodes, originNode, childNodes, getNodesBounds, options = {} } = params;
   const {
     direction = "right",
     gap = 40,
     spreadSiblingLanes = false,
     siblingTolerance = 50,
-    minY
+    minY,
+    maxY,
+    layoutMode = "freeform",
+    rowSpacing
   } = options;
+  const finite2 = (name, value) => {
+    if (value !== void 0 && !Number.isFinite(value)) {
+      throw new RangeError(`${name} must be a finite number (got ${value}).`);
+    }
+  };
+  finite2("gap", gap);
+  finite2("minY", minY);
+  finite2("maxY", maxY);
+  finite2("rowSpacing", rowSpacing);
+  if (rowSpacing !== void 0 && rowSpacing <= 0) {
+    throw new RangeError(`rowSpacing must be greater than 0 (got ${rowSpacing}).`);
+  }
+  if (minY !== void 0 && maxY !== void 0 && minY > maxY) {
+    throw new RangeError(`minY (${minY}) must not be greater than maxY (${maxY}).`);
+  }
   const displacedMap = /* @__PURE__ */ new Map();
   if (childNodes.length === 0 || existingNodes.length === 0) {
     return displacedMap;
   }
   const childBounds = getNodesBounds ? getNodesBounds(childNodes) : computeNodesBoundingBox(childNodes);
-  const originWidth = originNode.measured?.width ?? originNode.width ?? 200;
-  const originHeight = originNode.measured?.height ?? originNode.height ?? 60;
-  const deltaPrimary = direction === "right" || direction === "left" ? childBounds.width + gap : childBounds.height + gap;
+  const { width: originWidth, height: originHeight } = nodeSizeOf(originNode);
+  const rowLane = layoutMode === "row-lane";
+  const lane = rowSpacing ?? originHeight;
+  const quantize = (delta) => rowLane && delta > 0 && lane > 0 ? Math.ceil(delta / lane) * lane : delta;
+  const laneOf = (node) => lane > 0 ? Math.round((node.position.y - originNode.position.y) / lane) : 0;
+  const isAbove = (node) => rowLane ? laneOf(node) < 0 : node.position.y < originNode.position.y;
+  const isBelow = (node) => rowLane ? laneOf(node) > 0 : node.position.y >= originNode.position.y + originHeight * 0.5;
+  const horizontal = direction === "right" || direction === "left";
+  const deltaPrimary = horizontal ? childBounds.width + gap : quantize(childBounds.height + gap);
   const deltaUp = Math.max(0, originNode.position.y - childBounds.y + gap);
-  const deltaDown = Math.max(
-    0,
-    childBounds.y + childBounds.height - (originNode.position.y + originHeight) + gap
-  );
-  const equalDelta = Math.max(deltaUp, deltaDown);
+  const deltaDown = Math.max(0, childBounds.y + childBounds.height - (originNode.position.y + originHeight) + gap);
+  const equalDelta = quantize(Math.max(deltaUp, deltaDown));
   for (const node of existingNodes) {
     if (node.id === originNode.id) continue;
-    const isSiblingRow = Math.abs(node.position.y - originNode.position.y) < siblingTolerance;
-    switch (direction) {
-      case "right": {
-        if (node.position.x > originNode.position.x) {
-          displacedMap.set(node.id, {
-            x: node.position.x + deltaPrimary,
-            y: node.position.y
-          });
-        }
-        break;
-      }
-      case "left": {
-        if (node.position.x < originNode.position.x) {
-          displacedMap.set(node.id, {
-            x: node.position.x - deltaPrimary,
-            y: node.position.y
-          });
+    let newX = node.position.x;
+    let newY = node.position.y;
+    if (direction === "right") {
+      if (node.position.x >= originNode.position.x + originWidth * 0.5) {
+        newX += deltaPrimary;
+      } else if (spreadSiblingLanes) {
+        const { height } = nodeSizeOf(node);
+        const overlapsCluster = node.position.y + height >= childBounds.y - gap && node.position.y <= childBounds.y + childBounds.height + gap;
+        if (overlapsCluster && Math.abs(node.position.x - originNode.position.x) <= siblingTolerance) {
+          const push2 = node.position.y >= originNode.position.y ? 1 : -1;
+          newY += push2 * (childBounds.height * 0.5 + gap);
         }
-        break;
       }
-      case "down": {
-        if (node.position.y > originNode.position.y) {
-          displacedMap.set(node.id, {
-            x: node.position.x,
-            y: node.position.y + deltaPrimary
-          });
-        }
-        break;
-      }
-      case "up": {
-        if (node.position.y < originNode.position.y) {
-          displacedMap.set(node.id, {
-            x: node.position.x,
-            y: node.position.y - deltaPrimary
-          });
-        }
-        break;
+    } else if (direction === "left") {
+      if (node.position.x < originNode.position.x) newX -= deltaPrimary;
+    } else if (direction === "down") {
+      if (isBelow(node)) newY += deltaPrimary;
+    } else if (direction === "up") {
+      if (isAbove(node)) newY -= deltaPrimary;
+    } else if (direction === "vertical") {
+      if (isAbove(node)) newY -= equalDelta;
+      else if (isBelow(node)) newY += equalDelta;
+    }
+    if (newX !== node.position.x || newY !== node.position.y) {
+      displacedMap.set(node.id, { x: newX, y: newY });
+    }
+  }
+  if (minY !== void 0 || maxY !== void 0) {
+    const byId = new Map(existingNodes.map((n3) => [n3.id, n3]));
+    const rowsOf = (moved2) => {
+      const rows = /* @__PURE__ */ new Map();
+      for (const node of moved2) {
+        const key = rowLane ? laneOf(node) : node.position.y;
+        rows.set(key, [...rows.get(key) ?? [], node]);
       }
-      case "vertical": {
-        if (isSiblingRow) break;
-        if (node.position.y < originNode.position.y) {
-          displacedMap.set(node.id, {
-            x: node.position.x,
-            y: node.position.y - equalDelta
-          });
-        } else if (node.position.y > originNode.position.y) {
-          displacedMap.set(node.id, {
-            x: node.position.x,
-            y: node.position.y + equalDelta
-          });
-        }
-        break;
+      return [...rows.entries()].sort((a, b) => a[0] - b[0]).map(([, nodes]) => nodes);
+    };
+    const spacingFor = (nodes) => rowSpacing ?? Math.max(...nodes.map((n3) => nodeSizeOf(n3).height));
+    const moved = (sign) => [...displacedMap.entries()].filter(([id, pos]) => Math.sign(pos.y - byId.get(id).position.y) === sign).map(([id]) => byId.get(id));
+    if (minY !== void 0) {
+      const up = moved(-1);
+      if (up.length > 0) {
+        const spacing = spacingFor(up);
+        rowsOf(up).forEach((row, index) => {
+          const floor = minY + index * spacing;
+          for (const node of row) {
+            const pos = displacedMap.get(node.id);
+            displacedMap.set(node.id, { x: pos.x, y: Math.min(node.position.y, Math.max(floor, pos.y)) });
+          }
+        });
       }
     }
-  }
-  if (spreadSiblingLanes && (direction === "right" || direction === "left")) {
-    for (const [nodeId, pos] of displacedMap.entries()) {
-      const node = existingNodes.find((n3) => n3.id === nodeId);
-      if (node && Math.abs(node.position.y - originNode.position.y) < siblingTolerance) {
-        const isAbove = node.position.y < originNode.position.y;
-        displacedMap.set(nodeId, {
-          x: pos.x,
-          y: pos.y + (isAbove ? -deltaUp : deltaDown)
+    if (maxY !== void 0) {
+      const down = moved(1);
+      if (down.length > 0) {
+        const spacing = spacingFor(down);
+        rowsOf(down).reverse().forEach((row, index) => {
+          for (const node of row) {
+            const pos = displacedMap.get(node.id);
+            const ceiling = maxY - index * spacing - nodeSizeOf(node).height;
+            displacedMap.set(node.id, { x: pos.x, y: Math.max(node.position.y, Math.min(ceiling, pos.y)) });
+          }
         });
       }
     }
+    for (const [id, pos] of [...displacedMap.entries()]) {
+      const node = byId.get(id);
+      if (pos.x === node.position.x && pos.y === node.position.y) displacedMap.delete(id);
+    }
   }
-  if (minY !== void 0) {
-    for (const [nodeId, pos] of displacedMap.entries()) {
-      if (pos.y < minY) {
-        displacedMap.set(nodeId, { x: pos.x, y: minY });
-      }
+  return displacedMap;
+}
+function calculateReflowDisplacement(params) {
+  const { existingNodes, existingEdges, originNode, childNodes, childEdges = [], options = {} } = params;
+  const { direction = "LR", ranksep = 80, nodesep = 30, defaultNodeWidth = 200, defaultNodeHeight = 60 } = options;
+  const displacedMap = /* @__PURE__ */ new Map();
+  if (existingNodes.length === 0) return displacedMap;
+  const allNodes = [...existingNodes, ...childNodes];
+  const allEdges = [...existingEdges, ...childEdges];
+  const g = new dagre.graphlib.Graph();
+  g.setDefaultEdgeLabel(() => ({}));
+  g.setGraph({ rankdir: direction, ranksep, nodesep });
+  const allNodeIds = new Set(allNodes.map((n3) => n3.id));
+  for (const node of allNodes) {
+    g.setNode(node.id, nodeSizeOf(node, defaultNodeWidth, defaultNodeHeight));
+  }
+  for (const edge of allEdges) {
+    if (allNodeIds.has(edge.source) && allNodeIds.has(edge.target)) g.setEdge(edge.source, edge.target);
+  }
+  dagre.layout(g);
+  const dagreOrigin = g.node(originNode.id);
+  if (!dagreOrigin) return displacedMap;
+  const origin = nodeSizeOf(originNode, defaultNodeWidth, defaultNodeHeight);
+  const anchorOffsetX = originNode.position.x - (dagreOrigin.x - origin.width / 2);
+  const anchorOffsetY = originNode.position.y - (dagreOrigin.y - origin.height / 2);
+  for (const node of existingNodes) {
+    if (node.id === originNode.id) continue;
+    const laidOut = g.node(node.id);
+    if (!laidOut) continue;
+    const { width, height } = nodeSizeOf(node, defaultNodeWidth, defaultNodeHeight);
+    const targetX = laidOut.x - width / 2 + anchorOffsetX;
+    const targetY = laidOut.y - height / 2 + anchorOffsetY;
+    if (Math.abs(targetX - node.position.x) > 0.5 || Math.abs(targetY - node.position.y) > 0.5) {
+      displacedMap.set(node.id, { x: targetX, y: targetY });
     }
   }
   return displacedMap;
@@ -5142,7 +5195,7 @@ var defaultLabel = (node) => typeof node.data?.label === "string" && node.data.l
 function getTimelineRows(nodes, ids, options = {}) {
   const byId = new Map(nodes.map((n3) => [n3.id, n3]));
   const selection = options.selection ?? [];
-  const labelOf = options.labelOf ?? defaultLabel;
+  const labelOf2 = options.labelOf ?? defaultLabel;
   const rows = [];
   for (const id of new Set(ids)) {
     const node = byId.get(id);
@@ -5153,7 +5206,7 @@ function getTimelineRows(nodes, ids, options = {}) {
       rows.push({
         id: `${id}:${property}`,
         nodeId: id,
-        nodeLabel: labelOf(node),
+        nodeLabel: labelOf2(node),
         property,
         label,
         enabled: track.enabled !== false,
@@ -11801,6 +11854,288 @@ function createCanvasGestureRecorder(options) {
     }
   };
 }
+
+// src/canvas/explosionLayout.ts
+var explosionEdgeId = (sourceId, targetId) => `explode:${sourceId}:${targetId}`;
+function computeCanvasExplosionLayout(params) {
+  const {
+    existingNodes,
+    existingEdges = [],
+    originNode,
+    childNodes,
+    childEdges = [],
+    strategy = "directional",
+    options,
+    reflowOptions,
+    connectParentToChildren = false,
+    createEdge,
+    getNodesBounds
+  } = params;
+  const existingIds = new Set(existingNodes.map((n3) => n3.id));
+  if (!existingIds.has(originNode.id)) {
+    throw new Error(`The origin node "${originNode.id}" is not in existingNodes; pass the canvas nodes including the origin.`);
+  }
+  const childIds = /* @__PURE__ */ new Set();
+  for (const child of childNodes) {
+    if (existingIds.has(child.id)) {
+      throw new Error(`Child node id "${child.id}" is already on the canvas; give exploded children unique ids.`);
+    }
+    if (childIds.has(child.id)) throw new Error(`Child node id "${child.id}" is repeated; give exploded children unique ids.`);
+    childIds.add(child.id);
+  }
+  const children = childNodes.map((child) => ({ ...child, position: { ...child.position } }));
+  const edges = [...childEdges];
+  const makeEdge = createEdge ?? ((source, target) => ({ id: explosionEdgeId(source, target), type: "default", source, target }));
+  const connect = (child) => {
+    if (!edges.some((e) => e.source === originNode.id && e.target === child.id)) edges.push(makeEdge(originNode.id, child.id));
+  };
+  if (connectParentToChildren === true || connectParentToChildren === "all") children.forEach(connect);
+  else if (connectParentToChildren === "first" && children.length > 0) connect(children[0]);
+  let displacedPositions;
+  if (children.length === 0 || strategy === "none") {
+    displacedPositions = /* @__PURE__ */ new Map();
+  } else if (strategy === "dagre") {
+    displacedPositions = calculateReflowDisplacement({
+      existingNodes,
+      existingEdges,
+      originNode,
+      childNodes: children,
+      childEdges: edges,
+      options: reflowOptions
+    });
+  } else {
+    displacedPositions = calculateDirectionalDisplacement({
+      existingNodes,
+      originNode,
+      childNodes: children,
+      getNodesBounds,
+      options
+    });
+  }
+  const byId = new Map(existingNodes.map((n3) => [n3.id, n3]));
+  const originalPositions = /* @__PURE__ */ new Map();
+  let totalDisplacementDelta = 0;
+  for (const [id, to] of displacedPositions) {
+    const from = byId.get(id).position;
+    originalPositions.set(id, { ...from });
+    totalDisplacementDelta = Math.max(totalDisplacementDelta, Math.abs(to.x - from.x), Math.abs(to.y - from.y));
+  }
+  return {
+    displacedPositions,
+    originalPositions,
+    childNodes: children,
+    childEdges: edges,
+    childBounds: getNodesBounds ? getNodesBounds(children) : computeNodesBoundingBox(children),
+    totalDisplacementDelta
+  };
+}
+
+// src/canvas/explosionState.ts
+function createCanvasExplosionStateController(options = {}) {
+  const duration = options.collapseDurationMs ?? 380;
+  if (!Number.isFinite(duration) || duration < 0) {
+    throw new RangeError(`collapseDurationMs must be a finite number >= 0 (got ${duration}).`);
+  }
+  let snapshot = { activeId: options.initialActiveId ?? null, collapsingId: null };
+  let timer = null;
+  let destroyed = false;
+  const listeners = /* @__PURE__ */ new Set();
+  const clearTimer = () => {
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+  };
+  const set = (next) => {
+    if (next.activeId === snapshot.activeId && next.collapsingId === snapshot.collapsingId) return;
+    snapshot = next;
+    for (const listener of [...listeners]) listener();
+  };
+  const finishCollapse = () => {
+    clearTimer();
+    if (snapshot.collapsingId !== null) set({ activeId: snapshot.activeId, collapsingId: null });
+  };
+  const explode = (nodeId) => {
+    if (destroyed) return false;
+    if (typeof nodeId !== "string" || nodeId === "") throw new TypeError("explode needs a node id.");
+    if (snapshot.activeId === nodeId) return false;
+    clearTimer();
+    const previous = snapshot.activeId;
+    set({ activeId: nodeId, collapsingId: null });
+    if (previous !== null) options.onCollapse?.(previous);
+    options.onExplode?.(nodeId);
+    return true;
+  };
+  const collapse = (nodeId) => {
+    if (destroyed) return false;
+    const active = snapshot.activeId;
+    if (active === null || nodeId !== void 0 && nodeId !== active) return false;
+    clearTimer();
+    set({ activeId: null, collapsingId: active });
+    options.onCollapse?.(active);
+    if (duration === 0) finishCollapse();
+    else timer = setTimeout(() => {
+      timer = null;
+      finishCollapse();
+    }, duration);
+    return true;
+  };
+  return {
+    get activeId() {
+      return snapshot.activeId;
+    },
+    get collapsingId() {
+      return snapshot.collapsingId;
+    },
+    get isExplodingOrCollapsing() {
+      return snapshot.activeId !== null || snapshot.collapsingId !== null;
+    },
+    get destroyed() {
+      return destroyed;
+    },
+    getSnapshot: () => snapshot,
+    subscribe(listener) {
+      if (destroyed) return () => {
+      };
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    isExploded: (nodeId) => snapshot.activeId === nodeId,
+    isCollapsing: (nodeId) => snapshot.collapsingId === nodeId,
+    shouldRenderChildren: (nodeId) => snapshot.activeId === nodeId || snapshot.collapsingId === nodeId,
+    explode,
+    collapse,
+    toggle: (nodeId) => snapshot.activeId === nodeId ? (collapse(nodeId), false) : explode(nodeId),
+    finishCollapse: () => {
+      if (!destroyed) finishCollapse();
+    },
+    destroy() {
+      clearTimer();
+      destroyed = true;
+      listeners.clear();
+    }
+  };
+}
+
+// src/canvas/explosion-tools.ts
+function canvasExplosionToolTarget(state, options) {
+  return {
+    getNodes: options.getNodes,
+    canExplode: options.canExplode,
+    exploded: () => state.activeId ? [state.activeId] : [],
+    collapsing: () => state.collapsingId ? [state.collapsingId] : [],
+    explode: (id) => {
+      state.explode(id);
+    },
+    collapse: (id) => state.collapse(id)
+  };
+}
+var READ = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+var WRITE_IDEMPOTENT = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+var labelOf = (node) => {
+  const label = node.data?.label ?? node.data?.name;
+  return typeof label === "string" && label !== "" ? label : void 0;
+};
+function createCanvasExplosionToolProvider(target, options = {}) {
+  const readOnlyReason = () => {
+    const ro = typeof options.readOnly === "function" ? options.readOnly() : options.readOnly;
+    return ro ? typeof ro === "string" ? ro : "Exploding nodes is disabled on this canvas." : null;
+  };
+  const reasonNotExplodable = (node) => {
+    const ok = target.canExplode ? target.canExplode(node) : true;
+    if (ok === true) return null;
+    return typeof ok === "string" && ok ? ok : `Node "${node.id}" has nothing to explode into.`;
+  };
+  const state = () => ({ exploded: [...target.exploded()], collapsing: [...target.collapsing?.() ?? []] });
+  const findNode = (id) => {
+    const node = target.getNodes().find((n3) => n3.id === id);
+    if (!node) throw new Error(`No node "${id}" on the canvas. Call list_explodable_nodes for node ids.`);
+    return node;
+  };
+  const refuseIfReadOnly = () => {
+    const reason = readOnlyReason();
+    if (reason) throw new Error(reason);
+  };
+  const listTool = {
+    name: "list_explodable_nodes",
+    title: "List explodable nodes",
+    description: "Lists the canvas nodes that can explode into child nodes (id, label, exploded, collapsing), plus the ids currently exploded and collapsing, and whether exploding is read-only. Call before explode_node or collapse_node.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { title: "List explodable nodes", ...READ },
+    handler: () => {
+      const { exploded, collapsing } = state();
+      const nodes = target.getNodes().filter((n3) => exploded.includes(n3.id) || reasonNotExplodable(n3) === null).map((n3) => ({
+        id: n3.id,
+        ...labelOf(n3) ? { label: labelOf(n3) } : {},
+        exploded: exploded.includes(n3.id),
+        collapsing: collapsing.includes(n3.id)
+      }));
+      return { nodes, exploded, collapsing, multiple: target.multiple === true, readOnly: readOnlyReason() };
+    }
+  };
+  const explodeTool = {
+    name: "explode_node",
+    title: "Explode a node",
+    description: "Expands a node into its child nodes (subtasks, steps, details), moving surrounding nodes to make room. Unless several can be open at once, the node exploded before collapses. Exploding an exploded node changes nothing. Returns the node, the ids now exploded, and the ids that collapsed.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        node: { type: "string", minLength: 1, description: "Id of the node to explode, from list_explodable_nodes." }
+      },
+      required: ["node"],
+      additionalProperties: false
+    },
+    annotations: { title: "Explode a node", ...WRITE_IDEMPOTENT },
+    handler: async (args) => {
+      refuseIfReadOnly();
+      const node = findNode(args.node);
+      const before = state().exploded;
+      if (before.includes(node.id)) return { node: node.id, changed: false, exploded: before, collapsed: [] };
+      const reason = reasonNotExplodable(node);
+      if (reason) throw new Error(reason);
+      if (await target.explode(node.id) === false) {
+        throw new Error(`Node "${node.id}" could not explode (the canvas refused, e.g. an animation is running). Try again or call list_explodable_nodes.`);
+      }
+      const after = state().exploded;
+      return { node: node.id, changed: true, exploded: after, collapsed: before.filter((id) => !after.includes(id)) };
+    }
+  };
+  const collapseTool = {
+    name: "collapse_node",
+    title: "Collapse a node",
+    description: "Collapses an exploded node: its child nodes are removed (after the collapse animation) and moved nodes return to where they were. Returns the node and the ids still exploded.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        node: { type: "string", minLength: 1, description: "Id of an exploded node, from list_explodable_nodes (exploded: true)." }
+      },
+      required: ["node"],
+      additionalProperties: false
+    },
+    annotations: { title: "Collapse a node", ...WRITE_IDEMPOTENT },
+    handler: async (args) => {
+      refuseIfReadOnly();
+      const before = state().exploded;
+      if (!before.includes(args.node)) {
+        findNode(args.node);
+        throw new Error(
+          `Node "${args.node}" is not exploded${before.length ? ` (exploded: ${before.join(", ")})` : " (nothing is exploded)"}. Call list_explodable_nodes.`
+        );
+      }
+      if (await target.collapse(args.node) === false) {
+        throw new Error(`Node "${args.node}" could not collapse (the canvas refused). Try again or call list_explodable_nodes.`);
+      }
+      return { node: args.node, exploded: state().exploded, collapsing: state().collapsing };
+    }
+  };
+  return {
+    id: options.id ?? "canvas-explosion",
+    namespace: options.namespace,
+    title: "Canvas explosion",
+    description: "Explode canvas nodes into their child nodes and collapse them again.",
+    skill: "pixerate-canvas",
+    tools: () => readOnlyReason() ? [listTool] : [listTool, explodeTool, collapseTool],
+    subscribe: options.subscribe
+  };
+}
 export {
   ANIMATABLE_PROPERTIES,
   ANIMATION_DATA_KEY,
@@ -11896,10 +12231,12 @@ export {
   calculateCurvedPath,
   calculateDagreReflowDisplacement,
   calculateDirectionalDisplacement,
+  calculateReflowDisplacement,
   canCombineShapeNodes,
   canOffsetShapeNodes,
   canOutlineShapeNodeStrokes,
   canvasEffectsPool,
+  canvasExplosionToolTarget,
   canvasHeight,
   canvasNodeCaptureRect,
   canvasNodeEffect,
@@ -11912,6 +12249,7 @@ export {
   collectDescendantIds,
   combineCanvasComponentsAsVariants,
   combineShapeNodes,
+  computeCanvasExplosionLayout,
   computeDragBounds,
   computeDragBoundsFromPoints,
   computeNodesBoundingBox,
@@ -11936,6 +12274,8 @@ export {
   createCanvasEditorDocument,
   createCanvasEffectsController,
   createCanvasEffectsToolProvider,
+  createCanvasExplosionStateController,
+  createCanvasExplosionToolProvider,
   createCanvasGestureRecorder,
   createCanvasInstance,
   createCanvasPlaybackLocator,
@@ -11986,6 +12326,7 @@ export {
   evaluateEasing,
   evaluateTrack,
   excludePaths,
+  explosionEdgeId,
   exportCssAnimation,
   familySceneFromLayout,
   findConnectorSnap,
@@ -12145,6 +12486,7 @@ export {
   multiPolygonArea,
   multiPolygonBounds,
   nearestHandlePositions,
+  nodeSizeOf,
   normalizeBezierPath,
   normalizeKeyframes,
   offsetPath,

package/dist/canvas/types.d.cts

@@ -149,12 +149,38 @@ export type DisplacementDirection = 'right' | 'left' | 'down' | 'up' | 'vertical
  * Options for directional displacement calculation.
  */
 export interface DirectionalDisplacementOptions {
+    /** Which nodes move and where: `right` / `left` / `up` / `down` push one side; `vertical` opens the row up and down. Default `right`. */
     direction?: DisplacementDirection;
+    /** Clearance between the child cluster and displaced nodes, in canvas units. Default 40. */
     gap?: number;
+    /** With `right`, also push nodes in the origin's column that overlap the cluster up or down. Default false. */
     spreadSiblingLanes?: boolean;
+    /** Distance in canvas units within which a node counts as a sibling (same column for `right`, same row for `row-lane`). Default 50. */
     siblingTolerance?: number;
+    /**
+     * Floor for the top edge of nodes moved upward (e.g. below a pinned header). Rows pushed into it
+     * stack from `minY` down by `rowSpacing` so they never overlap, and never move below where they started.
+     */
     minY?: number;
+    /**
+     * Ceiling for the bottom edge of nodes moved downward. Rows pushed into it stack from `maxY` up by
+     * `rowSpacing`, and never move above where they started.
+     */
+    maxY?: number;
+    /**
+     * `freeform` (default) moves nodes by the exact clearance. `row-lane` treats the canvas as rows
+     * `rowSpacing` apart: nodes are bucketed into lanes relative to the origin row, the origin's lane
+     * stays put, and vertical deltas are rounded up to whole lanes so rows glide apart by exact lane heights.
+     */
+    layoutMode?: 'freeform' | 'row-lane';
+    /**
+     * Lane height in canvas units. Required for `row-lane` (default: the origin's height); also the
+     * spacing between rows stacked against `minY` / `maxY` (default: the tallest node in those rows).
+     */
+    rowSpacing?: number;
 }
+/** How existing nodes make room when a node explodes. */
+export type ExplosionDisplacementStrategy = 'directional' | 'dagre' | 'none';
 /**
  * Options for Dagre reflow displacement calculation.
  */
@@ -181,8 +207,7 @@ export interface ExplodeNodeOptions<TNode extends CanvasNode = CanvasNode, TEdge
     childNodes: TNode[];
     childEdges?: TEdge[];
     connectParentToChildren?: boolean | 'first' | 'all';
-    connectChildrenToDownstream?: boolean;
-    displacementStrategy?: 'directional' | 'dagre' | 'none';
+    displacementStrategy?: ExplosionDisplacementStrategy;
     directionalOptions?: DirectionalDisplacementOptions;
     reflowOptions?: Partial<ReflowDisplacementOptions>;
     trajectory?: TrajectoryFunction;