@pixerate/editor-svelte 0.15.3 → 0.16.1

package/README.md

@@ -0,0 +1,83 @@
+# @pixerate/editor-svelte
+
+Svelte 5 bindings for [`@pixerate/editor`](https://www.npmjs.com/package/@pixerate/editor): a rich-text editor component, bubble menu, read-only token renderer, plus spreadsheet and image editor components and rune-based node-graph canvas helpers.
+
+```bash
+npm install @pixerate/editor-svelte @pixerate/editor svelte
+# only if you use @pixerate/editor-svelte/canvas:
+npm install @xyflow/svelte
+```
+
+Requires **Svelte 5** (the components use runes). Components ship as `.svelte` sources, so they are compiled by your bundler and work with SvelteKit SSR.
+
+## Rich text editor
+
+```svelte
+<script lang="ts">
+  import type { Editor } from "@tiptap/core";
+  import { EditableTextNodeEditor, BubbleMenu } from "@pixerate/editor-svelte";
+
+  let editor = $state<Editor>();
+  let html = $state("<p>Start editing…</p>");
+</script>
+
+<EditableTextNodeEditor
+  bind:editor
+  content={html}
+  placeholder="Type anything…"
+  onUpdate={() => (html = editor?.getHTML() ?? html)}
+/>
+
+{#if editor}
+  <BubbleMenu {editor}><!-- your formatting buttons --></BubbleMenu>
+{/if}
+```
+
+`content` sets the initial document. Read later changes from the bound `editor` (for example in `onUpdate`), as above. The editor is preloaded with `createRichTextPreset()`. Pass `markdown`, `image`, `uploadImage`, `extensions` or `richTextOptions` to configure it.
+
+## Read-only token renderer
+
+```svelte
+<script lang="ts">
+  import { TemplateRenderer } from "@pixerate/editor-svelte";
+  const templates = [{ name: "golden_hour", body: "warm 35mm volumetric lighting" }];
+</script>
+
+<TemplateRenderer content={"A photo of {subject} in {{golden_hour}}"} {templates} resolve />
+```
+
+## More exports
+
+| Import | Exports |
+| :--- | :--- |
+| `@pixerate/editor-svelte` | `EditableTextNodeEditor`, `BubbleMenu`, `TemplateRenderer`, `initiateEditor`, `createReactiveEditor`, `createHistory`, `createHistoryShortcuts`, `navigationGuard` (action), `createNavigationGuard`, `SpreadsheetEditor`, `FormulaBar`, `createReactiveSpreadsheet`, `DirtyTracker` |
+| `@pixerate/editor-svelte/image-editor` | `ImageEditor`, `createReactiveImageEditor`: crop, rotate/flip, adjustments, annotations, depth masks, and `onInpaint` / `onRemoveBackground` AI hooks |
+| `@pixerate/editor-svelte/canvas` | Runes for `@xyflow/svelte`: `createCanvasGraph`, `createCanvasClipboard`, `createCanvasDocking`, `createCanvasShortcuts`, `createCanvasInteractions`, `createCanvasExplosion`, `createCanvasNodeSync`, `createCanvasMultiDrag`, `createStreamingCanvas`, `AgentPresenceLayer`, `FloatingHorizontalScrollbar`, plus layout helpers |
+
+Prop types are exported alongside each component, for example `EditableTextNodeEditorProps`, `BubbleMenuProps`, `ImageEditorProps` and `SpreadsheetEditorProps`.
+
+## Styling (Tailwind CSS required)
+
+The components are styled with [Tailwind CSS](https://tailwindcss.com) utility classes and ship no global stylesheet. To style them:
+
+1. **Let Tailwind scan the package**, or the classes will be purged.
+
+   Tailwind v4, in your CSS:
+
+   ```css
+   @source "../node_modules/@pixerate/editor-svelte/dist";
+   ```
+
+   Tailwind v3, in `tailwind.config.js`:
+
+   ```js
+   content: ["./src/**/*.{svelte,ts}", "./node_modules/@pixerate/editor-svelte/dist/**/*.{svelte,js}"],
+   ```
+
+2. **Define the theme colors.** `SpreadsheetEditor`, `FormulaBar`, `TemplateRenderer` and the editor use [shadcn-svelte](https://www.shadcn-svelte.com)-style tokens: `background`, `foreground`, `muted`, `muted-foreground`, `border`, `input`, `primary`, `popover`, `popover-foreground` and `destructive`. Projects already using shadcn-svelte have these. Otherwise, define them as colors in your Tailwind theme.
+
+`ImageEditor` uses a fixed dark (slate) palette and only needs step 1. Component-scoped styles, such as the editor placeholder, are included automatically.
+
+## License
+
+MIT

package/dist/BubbleMenu.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { Editor } from "@tiptap/core";
+interface Props {
+    editor?: Editor;
+    class?: string;
+    pluginKey?: any;
+    shouldShow?: ((props: any) => boolean) | null;
+    updateDelay?: number;
+    tippyOptions?: Record<string, any>;
+    children?: import("svelte").Snippet;
+}
+declare const BubbleMenu: import("svelte").Component<Props, {}, "">;
+type BubbleMenu = ReturnType<typeof BubbleMenu>;
+export default BubbleMenu;
+//# sourceMappingURL=BubbleMenu.svelte.d.ts.map

package/dist/BubbleMenu.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BubbleMenu.svelte.d.ts","sourceRoot":"","sources":["../src/BubbleMenu.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAIzC,UAAU,KAAK;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,GAAG,CAAC;IAChB,UAAU,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,IAAI,CAAC;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC,QAAQ,CAAC,EAAE,OAAO,QAAQ,EAAE,OAAO,CAAC;CACrC;AAkDH,QAAA,MAAM,UAAU,2CAAwC,CAAC;AACzD,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAChD,eAAe,UAAU,CAAC"}

package/{src → dist}/EditableTextNodeEditor.svelte

@@ -2,7 +2,7 @@
   import type { Editor, Content, Extensions, FocusPosition } from "@tiptap/core";
   import type { RichTextPresetOptions, MarkdownOptions, ImageOptions } from "@pixerate/editor";
   import { onDestroy, onMount } from "svelte";
-  import { initiateEditor } from "./editor.svelte";
+  import { initiateEditor } from "./editor.svelte.js";
 
   interface EditorProps {
     class?: string;

package/dist/EditableTextNodeEditor.svelte.d.ts

@@ -0,0 +1,26 @@
+import type { Editor, Content, Extensions, FocusPosition } from "@tiptap/core";
+import type { RichTextPresetOptions, MarkdownOptions, ImageOptions } from "@pixerate/editor";
+interface EditorProps {
+    class?: string;
+    editorClass?: string;
+    content?: Content;
+    showMenu?: boolean;
+    editable?: boolean;
+    editor?: Editor;
+    extensions?: Extensions;
+    onUpdate?: () => void;
+    onFocus?: () => void;
+    onBlur?: () => void;
+    onCreate?: () => void;
+    placeholder?: string;
+    markdown?: boolean | MarkdownOptions;
+    richTextOptions?: RichTextPresetOptions;
+    autofocus?: FocusPosition | boolean;
+    image?: ImageOptions | boolean;
+    uploadImage?: (file: File) => Promise<string> | string;
+    onUploadError?: (error: Error, file: File) => void;
+}
+declare const EditableTextNodeEditor: import("svelte").Component<EditorProps, {}, "editor">;
+type EditableTextNodeEditor = ReturnType<typeof EditableTextNodeEditor>;
+export default EditableTextNodeEditor;
+//# sourceMappingURL=EditableTextNodeEditor.svelte.d.ts.map

package/dist/EditableTextNodeEditor.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EditableTextNodeEditor.svelte.d.ts","sourceRoot":"","sources":["../src/EditableTextNodeEditor.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,KAAK,EAAE,qBAAqB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAK3F,UAAU,WAAW;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,GAAG,eAAe,CAAC;IACrC,eAAe,CAAC,EAAE,qBAAqB,CAAC;IACxC,SAAS,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC;IACpC,KAAK,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC;IAC/B,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;IACvD,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC;CACpD;AA8FH,QAAA,MAAM,sBAAsB,uDAAwC,CAAC;AACrE,KAAK,sBAAsB,GAAG,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACxE,eAAe,sBAAsB,CAAC"}

package/dist/TemplateRenderer.svelte.d.ts

@@ -0,0 +1,14 @@
+import { type Template, type ColorGradient } from "@pixerate/editor";
+interface Props {
+    content: string;
+    templates?: Template[];
+    templateColorMap?: Map<string, ColorGradient>;
+    resolve?: boolean;
+    class?: string;
+    onTemplateClick?: (templateName: string) => void;
+    onVariableClick?: (variableName: string) => void;
+}
+declare const TemplateRenderer: import("svelte").Component<Props, {}, "">;
+type TemplateRenderer = ReturnType<typeof TemplateRenderer>;
+export default TemplateRenderer;
+//# sourceMappingURL=TemplateRenderer.svelte.d.ts.map

package/dist/TemplateRenderer.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TemplateRenderer.svelte.d.ts","sourceRoot":"","sources":["../src/TemplateRenderer.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,EAGH,KAAK,QAAQ,EACb,KAAK,aAAa,EACnB,MAAM,kBAAkB,CAAC;AAG1B,UAAU,KAAK;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;IACvB,gBAAgB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC9C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,eAAe,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,IAAI,CAAC;CAClD;AAiDH,QAAA,MAAM,gBAAgB,2CAAwC,CAAC;AAC/D,KAAK,gBAAgB,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC5D,eAAe,gBAAgB,CAAC"}

package/dist/canvas/AgentPresenceLayer.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { AgentPresence } from '@pixerate/editor/agent';
+interface Props {
+    presences: AgentPresence[];
+    class?: string;
+}
+declare const AgentPresenceLayer: import("svelte").Component<Props, {}, "">;
+type AgentPresenceLayer = ReturnType<typeof AgentPresenceLayer>;
+export default AgentPresenceLayer;
+//# sourceMappingURL=AgentPresenceLayer.svelte.d.ts.map

package/dist/canvas/AgentPresenceLayer.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentPresenceLayer.svelte.d.ts","sourceRoot":"","sources":["../../src/canvas/AgentPresenceLayer.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAG3D,UAAU,KAAK;IACd,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAwCF,QAAA,MAAM,kBAAkB,2CAAwC,CAAC;AACjE,KAAK,kBAAkB,GAAG,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAChE,eAAe,kBAAkB,CAAC"}

package/dist/canvas/FloatingHorizontalScrollbar.svelte.d.ts

@@ -0,0 +1,9 @@
+type $$ComponentProps = {
+    targetElement?: HTMLDivElement | null;
+    totalWidth?: number;
+    minHeightAboveFold?: number;
+};
+declare const FloatingHorizontalScrollbar: import("svelte").Component<$$ComponentProps, {}, "">;
+type FloatingHorizontalScrollbar = ReturnType<typeof FloatingHorizontalScrollbar>;
+export default FloatingHorizontalScrollbar;
+//# sourceMappingURL=FloatingHorizontalScrollbar.svelte.d.ts.map

package/dist/canvas/FloatingHorizontalScrollbar.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FloatingHorizontalScrollbar.svelte.d.ts","sourceRoot":"","sources":["../../src/canvas/FloatingHorizontalScrollbar.svelte.ts"],"names":[],"mappings":"AAKC,KAAK,gBAAgB,GAAI;IACxB,aAAa,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAmGH,QAAA,MAAM,2BAA2B,sDAAwC,CAAC;AAC1E,KAAK,2BAA2B,GAAG,UAAU,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAClF,eAAe,2BAA2B,CAAC"}

package/dist/canvas/createCanvasClipboard.svelte.d.ts

@@ -0,0 +1,32 @@
+import type { XYPosition } from '@xyflow/svelte';
+import type { CanvasNode, CanvasEdge } from './types.js';
+/**
+ * Checks if an event originated from a text input, textarea, contenteditable element, or rich editor.
+ */
+export declare function isEventFromTextInput(event: Event | {
+    target: EventTarget | null;
+}): boolean;
+/**
+ * Validates that an object conforms to minimal CanvasNode shape.
+ */
+export declare function isValidCanvasNode(obj: unknown): obj is CanvasNode;
+/**
+ * Checks if a string is a valid HTTP/HTTPS URL.
+ */
+export declare function isValidUrl(url: string): boolean;
+export interface CreateCanvasClipboardOptions<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge> {
+    onPasteNodes?: (nodes: TNode[], edges?: TEdge[]) => void | Promise<void>;
+    onPasteUrl?: (url: string, position?: XYPosition) => void;
+    onPasteText?: (text: string, position?: XYPosition) => void;
+    onPasteImage?: (blob: File) => void | Promise<void>;
+    screenToFlowPosition?: (position: XYPosition) => XYPosition;
+}
+/**
+ * Headless Svelte 5 rune managing canvas copy, cut, and paste interactions.
+ */
+export declare function createCanvasClipboard<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge>(options?: CreateCanvasClipboardOptions<TNode, TEdge>): {
+    copySelectedNodes: (selectedNodes: TNode[], connectedEdges?: TEdge[], event?: ClipboardEvent) => boolean;
+    cutSelectedNodes: (selectedNodes: TNode[], connectedEdges?: TEdge[], onRemove?: (nodes: TNode[]) => void, event?: ClipboardEvent) => boolean;
+    handlePasteEvent: (event: ClipboardEvent) => Promise<boolean>;
+};
+//# sourceMappingURL=createCanvasClipboard.svelte.d.ts.map

package/dist/canvas/createCanvasClipboard.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createCanvasClipboard.svelte.d.ts","sourceRoot":"","sources":["../../src/canvas/createCanvasClipboard.svelte.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAA0B,MAAM,YAAY,CAAC;AAEjF;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,KAAK,GAAG;IAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CAAA;CAAE,GAAG,OAAO,CAc3F;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,UAAU,CAYjE;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAO/C;AAED,MAAM,WAAW,4BAA4B,CAC5C,KAAK,SAAS,UAAU,GAAG,UAAU,EACrC,KAAK,SAAS,UAAU,GAAG,UAAU;IAErC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzE,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC;IAC1D,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC;IAC5D,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,oBAAoB,CAAC,EAAE,CAAC,QAAQ,EAAE,UAAU,KAAK,UAAU,CAAC;CAC5D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACpC,KAAK,SAAS,UAAU,GAAG,UAAU,EACrC,KAAK,SAAS,UAAU,GAAG,UAAU,EACpC,OAAO,GAAE,4BAA4B,CAAC,KAAK,EAAE,KAAK,CAAM;uCAEzC,KAAK,EAAE,mBACL,KAAK,EAAE,UAChB,cAAc,KACpB,OAAO;sCA2BM,KAAK,EAAE,mBACL,KAAK,EAAE,aACb,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,IAAI,UAC3B,cAAc,KACpB,OAAO;8BAY6B,cAAc,KAAG,OAAO,CAAC,OAAO,CAAC;EAqGxE"}

package/dist/canvas/createCanvasClipboard.svelte.js

@@ -0,0 +1,171 @@
+import { tick } from 'svelte';
+/**
+ * Checks if an event originated from a text input, textarea, contenteditable element, or rich editor.
+ */
+export function isEventFromTextInput(event) {
+    const target = event.target;
+    if (!target)
+        return false;
+    if (target.tagName === 'INPUT' ||
+        target.tagName === 'TEXTAREA' ||
+        target.tagName === 'SELECT' ||
+        target.isContentEditable ||
+        target.closest?.('[contenteditable="true"]') ||
+        target.closest?.('.ProseMirror')) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Validates that an object conforms to minimal CanvasNode shape.
+ */
+export function isValidCanvasNode(obj) {
+    return (typeof obj === 'object' &&
+        obj !== null &&
+        'id' in obj &&
+        typeof obj.id === 'string' &&
+        'position' in obj &&
+        typeof obj.position === 'object' &&
+        obj.position !== null &&
+        'x' in obj.position &&
+        'y' in obj.position);
+}
+/**
+ * Checks if a string is a valid HTTP/HTTPS URL.
+ */
+export function isValidUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Headless Svelte 5 rune managing canvas copy, cut, and paste interactions.
+ */
+export function createCanvasClipboard(options = {}) {
+    function copySelectedNodes(selectedNodes, connectedEdges, event) {
+        if (event && isEventFromTextInput(event)) {
+            return false;
+        }
+        if (selectedNodes.length === 0)
+            return false;
+        const payload = {
+            version: 1,
+            nodes: selectedNodes,
+            edges: connectedEdges
+        };
+        const serialized = JSON.stringify(payload);
+        if (event?.clipboardData) {
+            event.clipboardData.setData('application/json', serialized);
+            event.clipboardData.setData('text/plain', serialized);
+            event.preventDefault();
+        }
+        else if (typeof navigator !== 'undefined' && navigator.clipboard) {
+            navigator.clipboard.writeText(serialized).catch(() => { });
+        }
+        return true;
+    }
+    function cutSelectedNodes(selectedNodes, connectedEdges, onRemove, event) {
+        if (event && isEventFromTextInput(event)) {
+            return false;
+        }
+        const copied = copySelectedNodes(selectedNodes, connectedEdges, event);
+        if (copied && onRemove) {
+            onRemove(selectedNodes);
+        }
+        return copied;
+    }
+    async function handlePasteEvent(event) {
+        if (isEventFromTextInput(event)) {
+            return false;
+        }
+        const clipboardData = event.clipboardData;
+        if (!clipboardData)
+            return false;
+        // 1. Check for files (images)
+        const files = clipboardData.files;
+        if (files && files.length > 0) {
+            const imageFile = Array.from(files).find((f) => f.type.startsWith('image/'));
+            if (imageFile && options.onPasteImage) {
+                event.preventDefault();
+                await options.onPasteImage(imageFile);
+                return true;
+            }
+        }
+        // 2. Check for serialized nodes (application/json or json in text/plain)
+        const rawJson = clipboardData.getData('application/json') || clipboardData.getData('text/plain');
+        if (rawJson) {
+            try {
+                const parsed = JSON.parse(rawJson);
+                let rawNodes;
+                let rawEdges;
+                if (Array.isArray(parsed) && parsed.every(isValidCanvasNode)) {
+                    rawNodes = parsed;
+                }
+                else if (typeof parsed === 'object' &&
+                    parsed !== null &&
+                    Array.isArray(parsed.nodes) &&
+                    parsed.nodes.every(isValidCanvasNode)) {
+                    rawNodes = parsed.nodes;
+                    rawEdges = parsed.edges;
+                }
+                if (rawNodes && rawNodes.length > 0) {
+                    event.preventDefault();
+                    // Create ID mapping for cloned nodes
+                    const idMap = new Map();
+                    const newNodes = rawNodes.map((node) => {
+                        const newId = crypto.randomUUID();
+                        idMap.set(node.id, newId);
+                        return {
+                            ...node,
+                            id: newId,
+                            selected: true,
+                            position: {
+                                x: node.position.x + 40,
+                                y: node.position.y + 40
+                            }
+                        };
+                    });
+                    // Clone edges mapping them to the newly generated node IDs
+                    const newEdges = rawEdges?.map((edge) => ({
+                        ...edge,
+                        id: crypto.randomUUID(),
+                        source: idMap.get(edge.source) ?? edge.source,
+                        target: idMap.get(edge.target) ?? edge.target
+                    }));
+                    if (options.onPasteNodes) {
+                        await options.onPasteNodes(newNodes, newEdges);
+                        await tick();
+                    }
+                    return true;
+                }
+            }
+            catch {
+                // Not JSON, fall through to text/URL processing
+            }
+        }
+        // 3. Check for URLs or plain text
+        const text = clipboardData.getData('text/plain')?.trim();
+        if (text) {
+            if (isValidUrl(text) && options.onPasteUrl) {
+                event.preventDefault();
+                options.onPasteUrl(text);
+                return true;
+            }
+            else if (options.onPasteText) {
+                event.preventDefault();
+                options.onPasteText(text);
+                return true;
+            }
+        }
+        return false;
+    }
+    return {
+        copySelectedNodes,
+        cutSelectedNodes,
+        handlePasteEvent
+    };
+}

package/dist/canvas/createCanvasDisplacement.d.ts

@@ -0,0 +1,32 @@
+import type { Rect, XYPosition } from '@xyflow/svelte';
+import type { CanvasEdge, CanvasLayoutOptions, CanvasNode, DirectionalDisplacementOptions } 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;
+/**
+ * Pure directional displacement calculation.
+ * Shifts downstream or surrounding nodes along an axis to clear space for newly inserted child nodes.
+ */
+export declare function calculateDirectionalDisplacement<TNode extends CanvasNode = CanvasNode>(params: {
+    existingNodes: TNode[];
+    originNode: TNode;
+    childNodes: TNode[];
+    getNodesBounds?: (nodes: TNode[]) => Rect;
+    options?: DirectionalDisplacementOptions;
+}): Map<string, XYPosition>;
+/**
+ * Pure hierarchical Dagre reflow displacement calculation.
+ * Calculates new coordinates for surrounding nodes using Dagre hierarchical layout,
+ * anchoring the origin node at its current position to eliminate layout jumping.
+ */
+export declare function calculateReflowDisplacement<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge>(params: {
+    existingNodes: TNode[];
+    existingEdges: TEdge[];
+    originNode: TNode;
+    childNodes: TNode[];
+    childEdges?: TEdge[];
+    getNodesBounds?: (nodes: TNode[]) => Rect;
+    options?: CanvasLayoutOptions;
+}): Map<string, XYPosition>;
+//# sourceMappingURL=createCanvasDisplacement.d.ts.map

package/dist/canvas/createCanvasDisplacement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createCanvasDisplacement.d.ts","sourceRoot":"","sources":["../../src/canvas/createCanvasDisplacement.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EACX,UAAU,EACV,mBAAmB,EACnB,UAAU,EACV,8BAA8B,EAC9B,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,SAAS,UAAU,GAAG,UAAU,EAC5E,KAAK,EAAE,KAAK,EAAE,EACd,YAAY,SAAM,EAClB,aAAa,SAAK,GAChB,IAAI,CA0BN;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,CAAC,KAAK,SAAS,UAAU,GAAG,UAAU,EAAE,MAAM,EAAE;IAC/F,aAAa,EAAE,KAAK,EAAE,CAAC;IACvB,UAAU,EAAE,KAAK,CAAC;IAClB,UAAU,EAAE,KAAK,EAAE,CAAC;IACpB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,IAAI,CAAC;IAC1C,OAAO,CAAC,EAAE,8BAA8B,CAAC;CACzC,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CA2G1B;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAC1C,KAAK,SAAS,UAAU,GAAG,UAAU,EACrC,KAAK,SAAS,UAAU,GAAG,UAAU,EACpC,MAAM,EAAE;IACT,aAAa,EAAE,KAAK,EAAE,CAAC;IACvB,aAAa,EAAE,KAAK,EAAE,CAAC;IACvB,UAAU,EAAE,KAAK,CAAC;IAClB,UAAU,EAAE,KAAK,EAAE,CAAC;IACpB,UAAU,CAAC,EAAE,KAAK,EAAE,CAAC;IACrB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,IAAI,CAAC;IAC1C,OAAO,CAAC,EAAE,mBAAmB,CAAC;CAC9B,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAyE1B"}

package/dist/canvas/createCanvasDisplacement.js

@@ -0,0 +1,170 @@
+import dagre from '@dagrejs/dagre';
+/**
+ * Calculates a bounding rectangle for a set of nodes if not provided by getNodesBounds.
+ */
+export function computeNodesBoundingBox(nodes, defaultWidth = 200, defaultHeight = 60) {
+    if (nodes.length === 0) {
+        return { x: 0, y: 0, width: 0, height: 0 };
+    }
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (const node of nodes) {
+        const width = node.measured?.width ?? node.width ?? defaultWidth;
+        const height = node.measured?.height ?? node.height ?? defaultHeight;
+        minX = Math.min(minX, node.position.x);
+        minY = Math.min(minY, node.position.y);
+        maxX = Math.max(maxX, node.position.x + width);
+        maxY = Math.max(maxY, node.position.y + height);
+    }
+    return {
+        x: minX,
+        y: minY,
+        width: maxX - minX,
+        height: maxY - minY
+    };
+}
+/**
+ * Pure directional displacement calculation.
+ * Shifts downstream or surrounding nodes along an axis to clear space for newly inserted child nodes.
+ */
+export function calculateDirectionalDisplacement(params) {
+    const { existingNodes, originNode, childNodes, getNodesBounds, options = {} } = params;
+    const { direction = 'right', gap = 40, spreadSiblingLanes = false, siblingTolerance = 50, minY } = options;
+    const displacedMap = 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;
+    // The delta space required along primary axis
+    const deltaPrimary = (direction === 'right' || direction === 'left')
+        ? childBounds.width + gap
+        : childBounds.height + gap;
+    // Vertical displacement parameters: upward and downward row clearance
+    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);
+    // Both above and below displace equally so the row expands symmetrically
+    const equalDelta = Math.max(deltaUp, deltaDown);
+    for (const node of existingNodes) {
+        if (node.id === originNode.id)
+            continue;
+        let newX = node.position.x;
+        let newY = node.position.y;
+        let moved = false;
+        if (direction === 'right') {
+            // Downstream nodes strictly to the right of the origin
+            if (node.position.x >= originNode.position.x + originWidth * 0.5) {
+                newX += deltaPrimary;
+                moved = true;
+            }
+            else if (spreadSiblingLanes) {
+                // Sibling nodes occupying the same vertical space as the exploded cluster
+                const isVerticallyOverlapping = node.position.y + (node.height ?? 60) >= childBounds.y - gap &&
+                    node.position.y <= childBounds.y + childBounds.height + gap;
+                if (isVerticallyOverlapping && Math.abs(node.position.x - originNode.position.x) <= siblingTolerance) {
+                    const pushDirection = node.position.y >= originNode.position.y ? 1 : -1;
+                    newY += pushDirection * (childBounds.height * 0.5 + gap);
+                    moved = true;
+                }
+            }
+        }
+        else if (direction === 'left') {
+            if (node.position.x <= originNode.position.x) {
+                newX -= deltaPrimary;
+                moved = true;
+            }
+        }
+        else if (direction === 'down') {
+            if (node.position.y >= originNode.position.y + originHeight * 0.5) {
+                newY += deltaPrimary;
+                moved = true;
+            }
+        }
+        else if (direction === 'up') {
+            if (node.position.y <= originNode.position.y) {
+                newY -= deltaPrimary;
+                moved = true;
+            }
+        }
+        else if (direction === 'vertical') {
+            // Row grows vertically:
+            // Nodes strictly above the origin node move up by equalDelta
+            // Nodes strictly below the origin node move down by equalDelta
+            // Both above and below displace equally; horizontal position (x) is strictly preserved
+            if (node.position.y < originNode.position.y) {
+                if (equalDelta > 0) {
+                    newY -= equalDelta;
+                    moved = true;
+                }
+            }
+            else if (node.position.y >= originNode.position.y + originHeight * 0.5) {
+                if (equalDelta > 0) {
+                    newY += equalDelta;
+                    moved = true;
+                }
+            }
+        }
+        if (moved) {
+            displacedMap.set(node.id, { x: newX, y: newY });
+        }
+    }
+    return displacedMap;
+}
+/**
+ * Pure hierarchical Dagre reflow displacement calculation.
+ * Calculates new coordinates for surrounding nodes using Dagre hierarchical layout,
+ * anchoring the origin node at its current position to eliminate layout jumping.
+ */
+export 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 = new Map();
+    if (existingNodes.length === 0)
+        return displacedMap;
+    const allNodes = [...existingNodes, ...childNodes];
+    const allEdges = [...existingEdges, ...childEdges];
+    const dagreGraph = new dagre.graphlib.Graph();
+    dagreGraph.setDefaultEdgeLabel(() => ({}));
+    dagreGraph.setGraph({ rankdir: direction, ranksep, nodesep });
+    const allNodeIds = new Set(allNodes.map((n) => n.id));
+    allNodes.forEach((node) => {
+        const nodeWidth = node.measured?.width ?? node.width ?? defaultNodeWidth;
+        const nodeHeight = node.measured?.height ?? node.height ?? defaultNodeHeight;
+        dagreGraph.setNode(node.id, { width: nodeWidth, height: nodeHeight });
+    });
+    allEdges.forEach((edge) => {
+        if (allNodeIds.has(edge.source) && allNodeIds.has(edge.target)) {
+            dagreGraph.setEdge(edge.source, edge.target);
+        }
+    });
+    dagre.layout(dagreGraph);
+    const dagreOrigin = dagreGraph.node(originNode.id);
+    if (!dagreOrigin)
+        return displacedMap;
+    const originWidth = originNode.measured?.width ?? originNode.width ?? defaultNodeWidth;
+    const originHeight = originNode.measured?.height ?? originNode.height ?? defaultNodeHeight;
+    // Calculate offset so origin node remains anchored at its exact initial coordinates
+    const anchorOffsetX = originNode.position.x - (dagreOrigin.x - originWidth / 2);
+    const anchorOffsetY = originNode.position.y - (dagreOrigin.y - originHeight / 2);
+    existingNodes.forEach((node) => {
+        if (node.id === originNode.id)
+            return;
+        const dagreNode = dagreGraph.node(node.id);
+        if (!dagreNode)
+            return;
+        const nodeWidth = node.measured?.width ?? node.width ?? defaultNodeWidth;
+        const nodeHeight = node.measured?.height ?? node.height ?? defaultNodeHeight;
+        const targetX = dagreNode.x - nodeWidth / 2 + anchorOffsetX;
+        const targetY = dagreNode.y - nodeHeight / 2 + anchorOffsetY;
+        // Only include if position actually shifted
+        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;
+}