@pixerate/editor 0.162.1 → 0.164.0

package/README.md

@@ -473,7 +473,7 @@ Each module is also available as a subpath import:
 | `@pixerate/editor/spreadsheet` | `SpreadsheetController`, formula parser/evaluator and dependency graph, formula function registry (`registerFormulaFunction`, `listFormulaFunctions`, `searchFormulaFunctions`, `getFormulaSignature`) and autocomplete helpers (`getFormulaHints`, `applyFormulaSuggestion`) |
 | `@pixerate/editor/image-editor` | `ImageEditorController` and Canvas 2D renderer: crop, adjustments, annotations, depth masks, selections and layer masks, and AI hooks. Needs a DOM/canvas environment (the selection algorithms themselves are pure). |
 | `@pixerate/editor/animation` | The keyframe model without canvas nodes: `AnimationTrack` / `AnimationKeyframe`, easing (`resolveEasing`, `evaluateEasing`, `cubicBezierAt`, `springAt`, presets, `parseCssEasing`, `easingToCss`), `evaluateTrack`, `interpolateAnimationValue`, `normalizeKeyframes`, OKLab colour mixing, `AnimationPlayer` and the `Clock` / `ManualClock` / `realClock` time sources (no third-party imports) |
-| `@pixerate/editor/canvas` | Node-graph layout (needs the optional `@dagrejs/dagre` peer), placement, trajectories, displacement, clipboard and streaming layout helpers, and node keyframe animation (re-exports everything in `/animation`) |
+| `@pixerate/editor/canvas` | Node-graph layout (needs the optional `@dagrejs/dagre` peer), placement, trajectories, displacement, node explosion (pure layout, headless explode / collapse state and agent tools), clipboard and streaming layout helpers, and node keyframe animation (re-exports everything in `/animation`) |
 | `@pixerate/editor/agent` | MCP tool schemas, a planner for agent-driven canvas edits, and the dynamic `ToolRegistry` with editor/spreadsheet tool providers |
 | `@pixerate/editor/tools` | `ToolRegistry`, tool types, `validateJsonSchema` and the static MCP tool definitions, without TipTap or dagre (no third-party imports) |
 | `@pixerate/editor/commands` | `CommandRegistry`, `ShortcutMap`, palette ranking, `createCommandToolProvider` and built-in history / arrange / spreadsheet commands (no third-party imports) |

package/dist/agent/index.cjs

@@ -2,7 +2,7 @@
 
 
 
-var _chunk4NGVHHJBcjs = require('../chunk-4NGVHHJB.cjs');
+var _chunkNZD2MZJCcjs = require('../chunk-NZD2MZJC.cjs');
 
 
 var _chunkGLQQ2VILcjs = require('../chunk-GLQQ2VIL.cjs');
@@ -115,15 +115,15 @@ var _chunkN2FGYZ4Qcjs = require('../chunk-N2FGYZ4Q.cjs');
 
 
 
-var _chunkEY22AY6Rcjs = require('../chunk-EY22AY6R.cjs');
+var _chunkYSAGBIRWcjs = require('../chunk-YSAGBIRW.cjs');
 
 
-var _chunk3IHNXRUVcjs = require('../chunk-3IHNXRUV.cjs');
-require('../chunk-HDGBM7EA.cjs');
+var _chunkGKNEJ6ENcjs = require('../chunk-GKNEJ6EN.cjs');
+require('../chunk-SBQVEBSU.cjs');
 
 
 
-var _chunkLL3H5XUHcjs = require('../chunk-LL3H5XUH.cjs');
+var _chunkR3P2M7HUcjs = require('../chunk-R3P2M7HU.cjs');
 
 
 
@@ -624,14 +624,14 @@ var SIZE_WIDTH = {
 };
 var SIZE_HEIGHT = { type: "number", minimum: 50, maximum: 4096, description: "Height in pixels (default 320)." };
 var SPEC_PROPERTIES = {
-  ..._chunk4NGVHHJBcjs.CHART_UPDATE_PROPERTIES,
+  ..._chunkNZD2MZJCcjs.CHART_UPDATE_PROPERTIES,
   categories: { type: "array", items: { type: "string" }, description: "Category labels in order (x axis labels, or pie slices)." },
   series: {
     type: "array",
     description: "The series, each with one value per category (padded with gaps).",
     items: {
       type: "object",
-      properties: { id: { type: "string", description: "Stable id (default: from the name)." }, ..._chunk4NGVHHJBcjs.SERIES_PROPS },
+      properties: { id: { type: "string", description: "Stable id (default: from the name)." }, ..._chunkNZD2MZJCcjs.SERIES_PROPS },
       required: ["name", "values"],
       additionalProperties: false
     }
@@ -642,7 +642,7 @@ function cleanSeries(series) {
   return series.map((s) => s && typeof s === "object" ? Object.fromEntries(Object.entries(s).filter(([, v]) => v !== null)) : s);
 }
 function checkedSpec(input) {
-  const { spec, issues } = _chunkLL3H5XUHcjs.normalizeChartSpec.call(void 0, { ...input, ...input.series !== void 0 ? { series: cleanSeries(input.series) } : {} });
+  const { spec, issues } = _chunkR3P2M7HUcjs.normalizeChartSpec.call(void 0, { ...input, ...input.series !== void 0 ? { series: cleanSeries(input.series) } : {} });
   if (issues.length) throw new Error(`The chart was not changed: ${issues.map((i) => i.message).join(" ")}`);
   return spec;
 }
@@ -657,14 +657,14 @@ function describe(chart, includeSpec) {
     series: spec.series.map((s) => ({ id: s.id, name: s.name })),
     width: _nullishCoalesce(node.attrs.width, () => ( null)),
     height: node.attrs.height,
-    description: _chunk3IHNXRUVcjs.describeChart.call(void 0, spec),
+    description: _chunkGKNEJ6ENcjs.describeChart.call(void 0, spec),
     ...includeSpec ? { spec } : {}
   };
 }
 function sparklines(doc) {
   const found = [];
   doc.descendants((node, pos) => {
-    if (node.type.name === "sparkline") found.push({ pos, kind: node.attrs.kind, values: node.attrs.values, label: _chunkEY22AY6Rcjs.sparklineLabel.call(void 0, node) });
+    if (node.type.name === "sparkline") found.push({ pos, kind: node.attrs.kind, values: node.attrs.values, label: _chunkYSAGBIRWcjs.sparklineLabel.call(void 0, node) });
   });
   return found;
 }
@@ -675,7 +675,7 @@ function checkPosition(editor, at) {
 function createDocumentChartTools(editor) {
   const chartType = () => editor().schema.nodes.chart;
   const findChart = (args) => {
-    const charts = _chunkEY22AY6Rcjs.getDocumentCharts.call(void 0, editor().state.doc);
+    const charts = _chunkYSAGBIRWcjs.getDocumentCharts.call(void 0, editor().state.doc);
     const list = charts.map((c) => `"${c.id}" at ${c.pos}`).join(", ") || "none; add one with insert_chart";
     if (args.chartId !== void 0) {
       const chart = charts.find((c) => c.id === args.chartId);
@@ -702,7 +702,7 @@ function createDocumentChartTools(editor) {
     annotations: { title: "List charts in the document", ...READ },
     handler: ({ includeSpec = false }) => {
       const doc = editor().state.doc;
-      return { charts: _chunkEY22AY6Rcjs.getDocumentCharts.call(void 0, doc).map((c) => describe(c, includeSpec)), sparklines: editor().schema.nodes.sparkline ? sparklines(doc) : [] };
+      return { charts: _chunkYSAGBIRWcjs.getDocumentCharts.call(void 0, doc).map((c) => describe(c, includeSpec)), sparklines: editor().schema.nodes.sparkline ? sparklines(doc) : [] };
     }
   };
   const insertChart = {
@@ -729,7 +729,7 @@ function createDocumentChartTools(editor) {
       const node = { type: "chart", attrs: { id, spec, width, ...height !== void 0 ? { height } : {} } };
       const chain = ed.chain().command(({ tr }) => (_history.closeHistory.call(void 0, tr), true));
       const ok = (at !== void 0 ? chain.insertContentAt(at, node) : chain.insertContent(node)).run();
-      const chart = _chunkEY22AY6Rcjs.getDocumentCharts.call(void 0, ed.state.doc).find((c) => c.id === id);
+      const chart = _chunkYSAGBIRWcjs.getDocumentCharts.call(void 0, ed.state.doc).find((c) => c.id === id);
       if (!ok || !chart) throw new Error(`A chart cannot go at ${_nullishCoalesce(at, () => ( ed.state.selection.from))}; pass a position between blocks or inside a paragraph.`);
       return { id: chart.id, pos: chart.pos, spec: chart.spec, width: chart.node.attrs.width, height: chart.node.attrs.height };
     }
@@ -776,8 +776,8 @@ function createDocumentChartTools(editor) {
     inputSchema: {
       type: "object",
       properties: {
-        values: { type: "array", items: _chunk4NGVHHJBcjs.VALUE, minItems: 1, maxItems: _chunkEY22AY6Rcjs.MAX_SPARKLINE_VALUES, description: "Values in order (null for a gap)." },
-        kind: { type: "string", enum: [..._chunkEY22AY6Rcjs.SPARKLINE_KINDS], description: "line (default), column, or win-loss (sign only)." },
+        values: { type: "array", items: _chunkNZD2MZJCcjs.VALUE, minItems: 1, maxItems: _chunkYSAGBIRWcjs.MAX_SPARKLINE_VALUES, description: "Values in order (null for a gap)." },
+        kind: { type: "string", enum: [..._chunkYSAGBIRWcjs.SPARKLINE_KINDS], description: "line (default), column, or win-loss (sign only)." },
         at: { type: "integer", minimum: 0, description: "Document position inside a paragraph (default: the selection)." },
         width: { type: "number", minimum: 4, maximum: 1e3, description: "Width in pixels (default 80)." },
         height: { type: "number", minimum: 4, maximum: 200, description: "Height in pixels (default 18)." },
@@ -791,12 +791,12 @@ function createDocumentChartTools(editor) {
     handler: ({ values, kind = "line", at, width = 80, height = 18, color = null, label = null }) => {
       const ed = editor();
       checkPosition(ed, at);
-      const parsed = values.map((v) => _chunkLL3H5XUHcjs.parseChartValue.call(void 0, v));
+      const parsed = values.map((v) => _chunkR3P2M7HUcjs.parseChartValue.call(void 0, v));
       const bad = parsed.findIndex((v) => v === void 0);
       if (bad >= 0) throw new Error(`values[${bad}] ("${String(values[bad])}") is not a number; pass numbers, numeric text or null. Nothing was inserted.`);
       const pos = _nullishCoalesce(at, () => ( ed.state.selection.from));
       if (!ed.state.doc.resolve(pos).parent.inlineContent) throw new Error(`Position ${pos} is between blocks; a sparkline goes inside a paragraph (use a position from get_text {blocks: true}).`);
-      const stored = _chunkEY22AY6Rcjs.normalizeSparklineValues.call(void 0, parsed);
+      const stored = _chunkYSAGBIRWcjs.normalizeSparklineValues.call(void 0, parsed);
       ed.chain().command(({ tr }) => (_history.closeHistory.call(void 0, tr), true)).insertContentAt(pos, { type: "sparkline", attrs: { values: stored, kind, width, height, color, label } }).run();
       return { pos, kind, values: stored };
     }
@@ -1134,8 +1134,8 @@ function createTextPresence(editor, providerId, option) {
   const config = option === false ? null : option === true || option === void 0 ? {} : option;
   const caret = {
     id: _nullishCoalesce(_optionalChain([config, 'optionalAccess', _43 => _43.id]), () => ( providerId)),
-    name: _nullishCoalesce(_optionalChain([config, 'optionalAccess', _44 => _44.name]), () => ( _chunkEY22AY6Rcjs.DEFAULT_AGENT_CARET_NAME)),
-    color: _nullishCoalesce(_optionalChain([config, 'optionalAccess', _45 => _45.color]), () => ( _chunkEY22AY6Rcjs.DEFAULT_AGENT_CARET_COLOR))
+    name: _nullishCoalesce(_optionalChain([config, 'optionalAccess', _44 => _44.name]), () => ( _chunkYSAGBIRWcjs.DEFAULT_AGENT_CARET_NAME)),
+    color: _nullishCoalesce(_optionalChain([config, 'optionalAccess', _45 => _45.color]), () => ( _chunkYSAGBIRWcjs.DEFAULT_AGENT_CARET_COLOR))
   };
   const typing = !_optionalChain([config, 'optionalAccess', _46 => _46.typing]) ? null : config.typing === true ? {} : config.typing;
   const idleMs = _nullishCoalesce(_optionalChain([config, 'optionalAccess', _47 => _47.idleMs]), () => ( 12e3));
@@ -1148,19 +1148,19 @@ function createTextPresence(editor, providerId, option) {
   };
   const touch = () => {
     clearTimeout(idleTimer);
-    if (idleMs > 0) idleTimer = setTimeout(() => live() && _chunkEY22AY6Rcjs.clearAgentCaret.call(void 0, live(), caret.id), idleMs);
+    if (idleMs > 0) idleTimer = setTimeout(() => live() && _chunkYSAGBIRWcjs.clearAgentCaret.call(void 0, live(), caret.id), idleMs);
   };
   const tint = (ed, ranges) => {
     clearTimeout(tintTimer);
-    _chunkEY22AY6Rcjs.markAgentChanges.call(void 0, ed, caret.id, ranges);
-    if (changedMs > 0 && ranges.length) tintTimer = setTimeout(() => live() && _chunkEY22AY6Rcjs.markAgentChanges.call(void 0, live(), caret.id, []), changedMs);
+    _chunkYSAGBIRWcjs.markAgentChanges.call(void 0, ed, caret.id, ranges);
+    if (changedMs > 0 && ranges.length) tintTimer = setTimeout(() => live() && _chunkYSAGBIRWcjs.markAgentChanges.call(void 0, live(), caret.id, []), changedMs);
   };
   return {
     /** Puts the caret at `head`, selecting from `anchor`. */
     show(anchor, head = anchor) {
       const ed = live();
       if (!ed) return;
-      _chunkEY22AY6Rcjs.setAgentCaret.call(void 0, ed, { ...caret, from: anchor, to: head });
+      _chunkYSAGBIRWcjs.setAgentCaret.call(void 0, ed, { ...caret, from: anchor, to: head });
       touch();
     },
     /** Shows the caret after ranges just changed by a tool, tinting them. */
@@ -1168,7 +1168,7 @@ function createTextPresence(editor, providerId, option) {
       const ed = live();
       if (!ed || !ranges.length) return;
       const last = ranges[ranges.length - 1];
-      _chunkEY22AY6Rcjs.setAgentCaret.call(void 0, ed, { ...caret, from: last.to });
+      _chunkYSAGBIRWcjs.setAgentCaret.call(void 0, ed, { ...caret, from: last.to });
       tint(ed, ranges);
       touch();
     },
@@ -1176,12 +1176,12 @@ function createTextPresence(editor, providerId, option) {
     async write(ed, from, to, text, signal) {
       if (live() && typing) {
         clearTimeout(tintTimer);
-        const range2 = await _chunkEY22AY6Rcjs.typeAgentText.call(void 0, ed, { ...typing, from, to, text, caret, signal });
-        if (changedMs > 0) tintTimer = setTimeout(() => live() && _chunkEY22AY6Rcjs.markAgentChanges.call(void 0, live(), caret.id, []), changedMs);
+        const range2 = await _chunkYSAGBIRWcjs.typeAgentText.call(void 0, ed, { ...typing, from, to, text, caret, signal });
+        if (changedMs > 0) tintTimer = setTimeout(() => live() && _chunkYSAGBIRWcjs.markAgentChanges.call(void 0, live(), caret.id, []), changedMs);
         touch();
         return range2;
       }
-      const tr = _history.closeHistory.call(void 0, _chunkEY22AY6Rcjs.replaceWithTextTransaction.call(void 0, ed.state, from, to, text));
+      const tr = _history.closeHistory.call(void 0, _chunkYSAGBIRWcjs.replaceWithTextTransaction.call(void 0, ed.state, from, to, text));
       const end = tr.mapping.map(to, 1);
       const range = { from: Math.min(tr.mapping.map(from, -1), end), to: end };
       ed.view.dispatch(tr.scrollIntoView());
@@ -1210,7 +1210,7 @@ function findMatches(editor, query, args, replacement) {
     wholeWord: !!args.wholeWord,
     ...args.regex ? { regex: true } : { literal: true }
   };
-  const result = _chunkEY22AY6Rcjs.searchDocument.call(void 0, editor.state.doc, query, options, replacement !== void 0 ? { replacement } : {});
+  const result = _chunkYSAGBIRWcjs.searchDocument.call(void 0, editor.state.doc, query, options, replacement !== void 0 ? { replacement } : {});
   if (result.error) throw new Error(`Invalid search pattern: ${result.error.message}`);
   return { matches: result.matches, truncated: result.truncated };
 }
@@ -1372,7 +1372,7 @@ function createRichTextToolProvider(target, options) {
         replacement: String(replace).replace(/\r\n?|\n/g, "\r")
       }));
       const tr = _history.closeHistory.call(void 0, ed.state.tr);
-      const ends = _chunkEY22AY6Rcjs.applyReplacements.call(void 0, tr, chosen);
+      const ends = _chunkYSAGBIRWcjs.applyReplacements.call(void 0, tr, chosen);
       ed.view.dispatch(tr.scrollIntoView());
       const ranges = chosen.map((m, i) => ({ from: tr.mapping.map(m.from, -1), to: ends[i] }));
       presence.changed(ranges.filter((r) => r.from < r.to));
@@ -1473,7 +1473,7 @@ function createRichTextToolProvider(target, options) {
     inputSchema: {
       type: "object",
       properties: {
-        operation: { type: "string", enum: _chunkEY22AY6Rcjs.TABLE_ACTIONS.map((a) => a.action), description: "Table operation." },
+        operation: { type: "string", enum: _chunkYSAGBIRWcjs.TABLE_ACTIONS.map((a) => a.action), description: "Table operation." },
         at: { type: "integer", minimum: 0, description: "Document position to place the cursor first (e.g. inside a cell)." },
         rows: { type: "integer", minimum: 1, maximum: 100, description: "insertTable: rows (default 3)." },
         cols: { type: "integer", minimum: 1, maximum: 50, description: "insertTable: columns (default 3)." },
@@ -1503,10 +1503,10 @@ function createRichTextToolProvider(target, options) {
         ed.view.dispatch(ed.state.tr.setSelection(_state.TextSelection.near(ed.state.doc.resolve(at))));
       }
       const action = operation;
-      const state = _chunkEY22AY6Rcjs.getTableActionState.call(void 0, ed, action, params);
+      const state = _chunkYSAGBIRWcjs.getTableActionState.call(void 0, ed, action, params);
       if (state !== true) throw new Error(state);
-      _chunkEY22AY6Rcjs.runTableAction.call(void 0, ed, action, params);
-      const table = _chunkEY22AY6Rcjs.getTableState.call(void 0, ed);
+      _chunkYSAGBIRWcjs.runTableAction.call(void 0, ed, action, params);
+      const table = _chunkYSAGBIRWcjs.getTableState.call(void 0, ed);
       return {
         operation,
         table: table.inTable ? { rows: table.rows, columns: table.columns, row: table.row, column: table.column } : null,
@@ -1525,7 +1525,7 @@ function createRichTextToolProvider(target, options) {
       if (!ed || ed.isDestroyed) return [];
       if (!ed.isEditable) return [getText, findText, ...charts.read()];
       const tools = [getText, findText, insertText, replaceText, replaceRange, replaceSelection, setSelection, ...formatting.tools(ed)];
-      return [...tools, ..._chunkEY22AY6Rcjs.isTableEnabled.call(void 0, ed) ? [editTable] : [], ...charts.read(), ...charts.write().map(withCaret)];
+      return [...tools, ..._chunkYSAGBIRWcjs.isTableEnabled.call(void 0, ed) ? [editTable] : [], ...charts.read(), ...charts.write().map(withCaret)];
     },
     subscribe: (notify) => {
       const ed = editor();

package/dist/agent/index.js

@@ -2,7 +2,7 @@ import {
   CHART_UPDATE_PROPERTIES,
   SERIES_PROPS,
   VALUE
-} from "../chunk-EVPZ5IKN.js";
+} from "../chunk-5FNGLV2D.js";
 import {
   hasVariantCommands
 } from "../chunk-3TNA7JKI.js";
@@ -115,15 +115,15 @@ import {
   setAgentCaret,
   sparklineLabel,
   typeAgentText
-} from "../chunk-CX6JLDFC.js";
+} from "../chunk-OXERWBKE.js";
 import {
   describeChart
-} from "../chunk-XDCFJEU7.js";
-import "../chunk-DTSTNRPH.js";
+} from "../chunk-SZA42R4N.js";
+import "../chunk-Z4P2RBMJ.js";
 import {
   normalizeChartSpec,
   parseChartValue
-} from "../chunk-HLOKB7WW.js";
+} from "../chunk-3NEZJCBY.js";
 import {
   getEditorMarkdown,
   getEditorText

package/dist/canvas/displacement.d.cts

@@ -1,11 +1,30 @@
-import type { CanvasEdge, CanvasNode, DirectionalDisplacementOptions, Rect, ReflowDisplacementOptions, XYPosition } from './types.cjs';
+import type { CanvasEdge, CanvasLayoutOptions, CanvasNode, DirectionalDisplacementOptions, Rect, ReflowDisplacementOptions, XYPosition } from './types.cjs';
 /**
  * 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/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;