@canvas-harness/core 0.1.9 → 0.1.10

package/dist/index.d.cts

@@ -2529,15 +2529,36 @@ type SerializedClipboard = {
  */
 declare const serializeSelection: (store: CanvasStore) => SerializedClipboard;
 type DeserializeOptions = {
-    /** World-space offset applied to all pasted nodes. Default (20, 20). */
+    /**
+     * Relative world-space offset added to every pasted node's `x/y`
+     * (and to free-floating edge endpoints). Takes precedence over
+     * `at` when both are passed. Default `(20, 20)` when neither is
+     * given.
+     */
     offset?: Vec2;
+    /**
+     * Absolute world-space target — the *center* of the pasted bbox
+     * lands here. Used by `paste()` to place the paste at the cursor;
+     * pass directly for programmatic absolute placement. Ignored if
+     * `offset` is also set.
+     */
+    at?: Vec2;
     /** Override the selection on the store after applying. Default true. */
     select?: boolean;
 };
 /**
  * Applies a clipboard payload to the store. New ids are minted; edge
- * endpoints are rewired; offset defaults to `(20, 20)` world units;
- * the resulting nodes + edges become the new selection by default.
+ * endpoints are rewired; the resulting nodes + edges become the new
+ * selection by default. Positioning precedence:
+ *
+ *   1. `opts.offset` (relative) — used as-is.
+ *   2. `opts.at` (absolute) — offset computed so the clip's bbox
+ *      center lands on this point.
+ *   3. Default — relative `(20, 20)` offset.
+ *
+ * Free-floating edge endpoints (`{ worldPoint }`) also receive the
+ * offset so an edge with an unattached end stays connected to the
+ * surrounding nodes after the paste.
  *
  * One `store.batch` — one undo step.
  *
@@ -2577,8 +2598,17 @@ declare const cut: (store: CanvasStore) => Promise<SerializedClipboard>;
 /**
  * Paste from the system clipboard (or a supplied payload). Every node
  * + edge gets a fresh id; edge endpoints rewire to the new ids; the
- * paste is offset by `(+20, +20)` world units so it doesn't overlay
- * the original. Wrapped in one undoable batch.
+ * resulting nodes + edges become the new selection. Wrapped in one
+ * undoable batch.
+ *
+ * Positioning, in precedence order:
+ *   1. `opts.offset` — relative offset, used as-is.
+ *   2. `opts.at` — absolute target; the paste's bbox center lands here.
+ *   3. The store's current cursor (`interactionState.pointer`) — the
+ *      paste lands centered under the cursor. This is the default
+ *      `paste(store)` behavior on a Cmd+V keybind.
+ *   4. Fallback `(20, 20)` relative offset when nothing else is known
+ *      (e.g. fresh session with no pointermove yet).
  *
  * Returns the new node ids on success, or `null` if the clipboard
  * didn't contain a canvas-harness payload.
@@ -2587,8 +2617,8 @@ declare const cut: (store: CanvasStore) => Promise<SerializedClipboard>;
  * <button onClick={() => paste(store)}>Paste</button>
  *
  * @example
- * // Programmatic paste from a saved JSON snippet:
- * paste(store, savedClip, { offset: { x: 0, y: 0 }, select: false })
+ * // Programmatic paste at a specific world point:
+ * paste(store, savedClip, { at: { x: 300, y: 200 }, select: false })
  */
 declare const paste: (store: CanvasStore, payload?: SerializedClipboard, opts?: DeserializeOptions) => Promise<(NodeId | EdgeId)[] | null>;
 

package/dist/index.d.ts

@@ -2529,15 +2529,36 @@ type SerializedClipboard = {
  */
 declare const serializeSelection: (store: CanvasStore) => SerializedClipboard;
 type DeserializeOptions = {
-    /** World-space offset applied to all pasted nodes. Default (20, 20). */
+    /**
+     * Relative world-space offset added to every pasted node's `x/y`
+     * (and to free-floating edge endpoints). Takes precedence over
+     * `at` when both are passed. Default `(20, 20)` when neither is
+     * given.
+     */
     offset?: Vec2;
+    /**
+     * Absolute world-space target — the *center* of the pasted bbox
+     * lands here. Used by `paste()` to place the paste at the cursor;
+     * pass directly for programmatic absolute placement. Ignored if
+     * `offset` is also set.
+     */
+    at?: Vec2;
     /** Override the selection on the store after applying. Default true. */
     select?: boolean;
 };
 /**
  * Applies a clipboard payload to the store. New ids are minted; edge
- * endpoints are rewired; offset defaults to `(20, 20)` world units;
- * the resulting nodes + edges become the new selection by default.
+ * endpoints are rewired; the resulting nodes + edges become the new
+ * selection by default. Positioning precedence:
+ *
+ *   1. `opts.offset` (relative) — used as-is.
+ *   2. `opts.at` (absolute) — offset computed so the clip's bbox
+ *      center lands on this point.
+ *   3. Default — relative `(20, 20)` offset.
+ *
+ * Free-floating edge endpoints (`{ worldPoint }`) also receive the
+ * offset so an edge with an unattached end stays connected to the
+ * surrounding nodes after the paste.
  *
  * One `store.batch` — one undo step.
  *
@@ -2577,8 +2598,17 @@ declare const cut: (store: CanvasStore) => Promise<SerializedClipboard>;
 /**
  * Paste from the system clipboard (or a supplied payload). Every node
  * + edge gets a fresh id; edge endpoints rewire to the new ids; the
- * paste is offset by `(+20, +20)` world units so it doesn't overlay
- * the original. Wrapped in one undoable batch.
+ * resulting nodes + edges become the new selection. Wrapped in one
+ * undoable batch.
+ *
+ * Positioning, in precedence order:
+ *   1. `opts.offset` — relative offset, used as-is.
+ *   2. `opts.at` — absolute target; the paste's bbox center lands here.
+ *   3. The store's current cursor (`interactionState.pointer`) — the
+ *      paste lands centered under the cursor. This is the default
+ *      `paste(store)` behavior on a Cmd+V keybind.
+ *   4. Fallback `(20, 20)` relative offset when nothing else is known
+ *      (e.g. fresh session with no pointermove yet).
  *
  * Returns the new node ids on success, or `null` if the clipboard
  * didn't contain a canvas-harness payload.
@@ -2587,8 +2617,8 @@ declare const cut: (store: CanvasStore) => Promise<SerializedClipboard>;
  * <button onClick={() => paste(store)}>Paste</button>
  *
  * @example
- * // Programmatic paste from a saved JSON snippet:
- * paste(store, savedClip, { offset: { x: 0, y: 0 }, select: false })
+ * // Programmatic paste at a specific world point:
+ * paste(store, savedClip, { at: { x: 300, y: 200 }, select: false })
  */
 declare const paste: (store: CanvasStore, payload?: SerializedClipboard, opts?: DeserializeOptions) => Promise<(NodeId | EdgeId)[] | null>;
 

package/dist/index.js

@@ -5957,8 +5957,30 @@ var endInside = (end, ids) => {
   if (!isAttached(end)) return true;
   return ids.has(end.nodeId);
 };
+var clipBboxCenter = (nodes) => {
+  if (nodes.length === 0) return { x: 0, y: 0 };
+  let minX = Number.POSITIVE_INFINITY;
+  let minY = Number.POSITIVE_INFINITY;
+  let maxX = Number.NEGATIVE_INFINITY;
+  let maxY = Number.NEGATIVE_INFINITY;
+  for (const n of nodes) {
+    if (n.x < minX) minX = n.x;
+    if (n.y < minY) minY = n.y;
+    if (n.x + n.w > maxX) maxX = n.x + n.w;
+    if (n.y + n.h > maxY) maxY = n.y + n.h;
+  }
+  return { x: (minX + maxX) / 2, y: (minY + maxY) / 2 };
+};
 var deserializeClipboard = (store, clip, opts = {}) => {
-  const offset = opts.offset ?? { x: 20, y: 20 };
+  let offset;
+  if (opts.offset) {
+    offset = opts.offset;
+  } else if (opts.at && clip.nodes.length > 0) {
+    const center = clipBboxCenter(clip.nodes);
+    offset = { x: opts.at.x - center.x, y: opts.at.y - center.y };
+  } else {
+    offset = { x: 20, y: 20 };
+  }
   const select = opts.select ?? true;
   const nodeMap = /* @__PURE__ */ new Map();
   const edgeMap = /* @__PURE__ */ new Map();
@@ -5971,7 +5993,9 @@ var deserializeClipboard = (store, clip, opts = {}) => {
     y: n.y + offset.y
   }));
   const remapEnd = (end) => {
-    if (!isAttached(end)) return end;
+    if (!isAttached(end)) {
+      return { worldPoint: { x: end.worldPoint.x + offset.x, y: end.worldPoint.y + offset.y } };
+    }
     const newId = nodeMap.get(end.nodeId);
     return newId ? { nodeId: newId, localOffset: end.localOffset } : end;
   };
@@ -6014,7 +6038,14 @@ var cut = async (store) => {
 var paste = async (store, payload, opts) => {
   const clip = payload ?? await readClipboard();
   if (!clip) return null;
-  const ids = deserializeClipboard(store, clip, opts);
+  let effective = opts;
+  if (!opts?.offset && !opts?.at) {
+    const pointer = store.getInteractionState().pointer;
+    if (pointer) {
+      effective = { ...opts, at: { x: pointer.worldX, y: pointer.worldY } };
+    }
+  }
+  const ids = deserializeClipboard(store, clip, effective);
   return ids;
 };
 var writeClipboard = async (clip) => {