@lupinum/board-core 0.1.0 → 1.0.0-beta.2

package/dist/index.js

@@ -5,8 +5,15 @@ import {
   BoardInputError,
   BoardNotFoundError,
   assertInternalBoardPlugin,
-  registerBoardInteractionAdapter
-} from "./chunk-5JZXHZWR.js";
+  collectJsonObjectExtras,
+  createJsonValueBudget,
+  freezeClone,
+  freezeJsonObject,
+  readonlyMapView,
+  readonlySetView,
+  registerBoardInteractionAdapter,
+  sameArray
+} from "./chunk-A7SXOVDB.js";
 
 // src/math.ts
 function clamp(value, min, max) {
@@ -528,112 +535,6 @@ function snapPositionToEdges(bounds, otherEdges, threshold, excludeIds) {
   return { dx, dy, guides };
 }
 
-// src/helpers/clone.ts
-function freezeClone(value) {
-  if (Array.isArray(value)) {
-    for (const entry of value) {
-      freezeClone(entry);
-    }
-    return Object.freeze(value);
-  }
-  if (value && typeof value === "object") {
-    for (const child of Object.values(value)) {
-      freezeClone(child);
-    }
-    return Object.freeze(value);
-  }
-  return value;
-}
-function sameArray(a, b) {
-  if (a.length !== b.length) {
-    return false;
-  }
-  return a.every((value, index) => value === b[index]);
-}
-function readonlyMapView(source) {
-  let view;
-  view = Object.freeze({
-    get size() {
-      return source.size;
-    },
-    get: (key) => source.get(key),
-    has: (key) => source.has(key),
-    entries: () => source.entries(),
-    keys: () => source.keys(),
-    values: () => source.values(),
-    forEach: (callback, thisArg) => {
-      source.forEach((value, key) => callback.call(thisArg, value, key, view));
-    },
-    [Symbol.iterator]: () => source[Symbol.iterator]()
-  });
-  return view;
-}
-function readonlySetView(source) {
-  let view;
-  view = Object.freeze({
-    get size() {
-      return source.size;
-    },
-    has: (value) => source.has(value),
-    entries: () => source.entries(),
-    keys: () => source.keys(),
-    values: () => source.values(),
-    forEach: (callback, thisArg) => {
-      source.forEach((value) => callback.call(thisArg, value, value, view));
-    },
-    [Symbol.iterator]: () => source[Symbol.iterator](),
-    union: (other) => {
-      const result = new Set(source);
-      for (const value of iteratorValues(other.keys())) result.add(value);
-      return result;
-    },
-    intersection: (other) => {
-      const result = /* @__PURE__ */ new Set();
-      for (const value of source) {
-        if (other.has(value)) result.add(value);
-      }
-      return result;
-    },
-    difference: (other) => {
-      const result = /* @__PURE__ */ new Set();
-      for (const value of source) {
-        if (!other.has(value)) result.add(value);
-      }
-      return result;
-    },
-    symmetricDifference: (other) => {
-      const result = new Set(source);
-      for (const value of iteratorValues(other.keys())) {
-        if (source.has(value)) result.delete(value);
-        else result.add(value);
-      }
-      return result;
-    },
-    isSubsetOf: (other) => {
-      for (const value of source) if (!other.has(value)) return false;
-      return true;
-    },
-    isSupersetOf: (other) => {
-      for (const value of iteratorValues(other.keys())) {
-        if (!source.has(value)) return false;
-      }
-      return true;
-    },
-    isDisjointFrom: (other) => {
-      for (const value of source) if (other.has(value)) return false;
-      return true;
-    }
-  });
-  return view;
-}
-function* iteratorValues(iterator) {
-  while (true) {
-    const result = iterator.next();
-    if (result.done) return;
-    yield result.value;
-  }
-}
-
 // src/helpers/ids.ts
 function createNodeId() {
   return crypto.randomUUID();
@@ -799,6 +700,7 @@ function validateState(state, grid, context) {
     }
     zIndexes.add(node.zIndex);
   }
+  validateParentCycles(state, push);
   for (const id of state.selection.values()) {
     if (!state.nodes.has(id)) {
       push("selection.exists", `Selected node ${id} does not exist.`);
@@ -855,28 +757,26 @@ function validateNodeParent(node, state, push) {
       `Node ${node.id} parent must be type "group", got "${parent.type}".`
     );
   }
-  let walk = parent;
-  const seen = /* @__PURE__ */ new Set();
-  while (walk) {
-    if (seen.has(walk.id)) {
-      push(
-        "node.parentId",
-        `Cycle detected in parent chain for node ${node.id}.`
-      );
-      return;
-    }
-    seen.add(walk.id);
-    if (walk.id === node.id) {
-      push(
-        "node.parentId",
-        `Node ${node.id} would create a cycle in the parent chain.`
-      );
-      return;
-    }
-    if (!walk.parentId) {
-      break;
+}
+function validateParentCycles(state, push) {
+  const complete = /* @__PURE__ */ new Set();
+  for (const start of state.nodes.keys()) {
+    if (complete.has(start)) continue;
+    const path = [];
+    const pathIndexes = /* @__PURE__ */ new Map();
+    let current = start;
+    while (current !== void 0 && !complete.has(current)) {
+      const cycleStart = pathIndexes.get(current);
+      if (cycleStart !== void 0) {
+        const cycle = [...path.slice(cycleStart), current].join(" -> ");
+        push("node.parentId", `Cycle detected in parent chain: ${cycle}.`);
+        break;
+      }
+      pathIndexes.set(current, path.length);
+      path.push(current);
+      current = state.nodes.get(current)?.parentId;
     }
-    walk = state.nodes.get(walk.parentId);
+    for (const id of path) complete.add(id);
   }
 }
 
@@ -1593,7 +1493,11 @@ function stagePersistentRoots(roots) {
       selection: new Set(roots.state.selection),
       interaction: cloneInteraction(roots.state.interaction),
       snapGuides: roots.state.snapGuides.map((guide) => ({ ...guide })),
-      nextZIndex: roots.state.nextZIndex
+      nextZIndex: roots.state.nextZIndex,
+      jsonCanvas: {
+        document: roots.state.jsonCanvas.document,
+        nodes: new Map(roots.state.jsonCanvas.nodes)
+      }
     },
     grid: { ...roots.grid },
     pluginStates: new Map(
@@ -1639,6 +1543,32 @@ var JSON_CANVAS_SIDES = /* @__PURE__ */ new Set([
 ]);
 var JSON_CANVAS_EDGE_ENDS = /* @__PURE__ */ new Set(["none", "arrow"]);
 var JSON_CANVAS_BACKGROUND_STYLES = /* @__PURE__ */ new Set(["cover", "ratio", "repeat"]);
+var MAX_DOCUMENT_NODES = 1e4;
+var MAX_DOCUMENT_EDGES = 2e4;
+var MAX_DOCUMENT_SELECTION = 1e4;
+var LEGACY_BOARD_METADATA_KEY = "x-vue-board";
+var DOCUMENT_FIELDS = /* @__PURE__ */ new Set([
+  "nodes",
+  "edges",
+  "x-lupinum-board",
+  LEGACY_BOARD_METADATA_KEY
+]);
+var NODE_FIELDS = /* @__PURE__ */ new Set([
+  "id",
+  "type",
+  "x",
+  "y",
+  "width",
+  "height",
+  "color",
+  "text",
+  "file",
+  "subpath",
+  "url",
+  "label",
+  "background",
+  "backgroundStyle"
+]);
 function isJsonCanvasNodeType(value) {
   return typeof value === "string" && JSON_CANVAS_NODE_TYPES.has(value);
 }
@@ -1716,8 +1646,9 @@ function jsonNodeToBoardNode(node, meta, index) {
   };
   return withNodeFields(base, node);
 }
-function boardNodeToJsonNode(node) {
+function boardNodeToJsonNode(node, extras) {
   const base = {
+    ...extras ?? {},
     id: node.id,
     type: node.type,
     x: node.x,
@@ -1759,9 +1690,10 @@ function mergeMetadata(base, patch) {
   };
 }
 function getDocumentMetadata(document) {
-  return document["x-vue-board"];
+  const record = document;
+  return document["x-lupinum-board"] ?? record[LEGACY_BOARD_METADATA_KEY];
 }
-function toPersistedDocument(snapshot, featureDocuments) {
+function toPersistedDocument(snapshot, featureDocuments, passthrough) {
   let metadata = {
     camera: snapshot.camera,
     grid: snapshot.grid,
@@ -1787,13 +1719,18 @@ function toPersistedDocument(snapshot, featureDocuments) {
     metadata = mergeMetadata(metadata, getDocumentMetadata(featureDocument));
   }
   return {
-    nodes: snapshot.nodes.map((node) => boardNodeToJsonNode(node)),
+    ...passthrough.document,
+    nodes: snapshot.nodes.map(
+      (node) => boardNodeToJsonNode(node, passthrough.nodes.get(node.id))
+    ),
     ...edges !== void 0 ? { edges } : {},
-    "x-vue-board": metadata
+    "x-lupinum-board": metadata
   };
 }
 function isRecord(value) {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
 }
 function assertRecord(value, message) {
   if (!isRecord(value)) {
@@ -1925,13 +1862,27 @@ function validateDocumentMetadata(metadata) {
   }
 }
 function normalizeDocumentForImport(raw) {
-  const parsed = assertRecord(
+  const parsedRecord = assertRecord(
     raw,
     "Invalid board document: document must be an object."
   );
+  const parsed = parsedRecord;
   if (!Array.isArray(parsed.nodes)) {
     throw new BoardInputError("Invalid board document: missing nodes array.");
   }
+  if (parsed.nodes.length > MAX_DOCUMENT_NODES) {
+    throw new BoardInputError(
+      `Invalid board document: nodes exceed the supported limit of ${MAX_DOCUMENT_NODES}.`
+    );
+  }
+  if (parsed.edges !== void 0 && !Array.isArray(parsed.edges)) {
+    throw new BoardInputError("Invalid board document: edges must be an array.");
+  }
+  if (parsed.edges && parsed.edges.length > MAX_DOCUMENT_EDGES) {
+    throw new BoardInputError(
+      `Invalid board document: edges exceed the supported limit of ${MAX_DOCUMENT_EDGES}.`
+    );
+  }
   for (const key of [
     "camera",
     "grid",
@@ -1942,11 +1893,35 @@ function normalizeDocumentForImport(raw) {
   ]) {
     if (key in parsed) {
       throw new BoardInputError(
-        `Invalid board document: runtime field "${key}" belongs under x-vue-board.`
+        `Invalid board document: runtime field "${key}" belongs under x-lupinum-board.`
       );
     }
   }
-  validateDocumentMetadata(getDocumentMetadata(parsed));
+  const rawMetadata = getDocumentMetadata(parsed);
+  if (isRecord(rawMetadata)) {
+    if (Array.isArray(rawMetadata.selection) && rawMetadata.selection.length > MAX_DOCUMENT_SELECTION) {
+      throw new BoardInputError(
+        `Invalid board document: selection exceeds the supported limit of ${MAX_DOCUMENT_SELECTION}.`
+      );
+    }
+    if (isRecord(rawMetadata.nodes) && Reflect.ownKeys(rawMetadata.nodes).length > MAX_DOCUMENT_NODES) {
+      throw new BoardInputError(
+        `Invalid board document: node metadata exceeds the supported limit of ${MAX_DOCUMENT_NODES}.`
+      );
+    }
+    if (isRecord(rawMetadata.edges) && Reflect.ownKeys(rawMetadata.edges).length > MAX_DOCUMENT_EDGES) {
+      throw new BoardInputError(
+        `Invalid board document: edge metadata exceeds the supported limit of ${MAX_DOCUMENT_EDGES}.`
+      );
+    }
+  }
+  validateDocumentMetadata(rawMetadata);
+  const jsonBudget = createJsonValueBudget();
+  const metadata = rawMetadata === void 0 ? void 0 : freezeJsonObject(
+    rawMetadata,
+    "Invalid board document: board metadata",
+    jsonBudget
+  );
   const seenNodes = /* @__PURE__ */ new Set();
   const nodes = parsed.nodes.map((node) => {
     if (!isRecord(node)) {
@@ -1969,7 +1944,11 @@ function normalizeDocumentForImport(raw) {
         `Invalid board document: node "${String(node.id)}" has unsupported backgroundStyle "${String(node.backgroundStyle)}".`
       );
     }
-    const normalized = { ...node };
+    const normalized = freezeJsonObject(
+      node,
+      `Invalid board document: node "${String(node.id ?? "?")}"`,
+      jsonBudget
+    );
     validateJsonCanvasNodeFields(normalized);
     if (seenNodes.has(normalized.id)) {
       throw new BoardInputError(
@@ -1981,11 +1960,6 @@ function normalizeDocumentForImport(raw) {
   });
   let edges;
   if (parsed.edges !== void 0) {
-    if (!Array.isArray(parsed.edges)) {
-      throw new BoardInputError(
-        "Invalid board document: edges must be an array."
-      );
-    }
     const seenEdges = /* @__PURE__ */ new Set();
     edges = parsed.edges.map((edge) => {
       if (!isRecord(edge)) {
@@ -2037,13 +2011,43 @@ function normalizeDocumentForImport(raw) {
           `Invalid board document: edge "${id}" has invalid label.`
         );
       }
-      return { ...edge, id, fromNode, toNode };
+      return freezeJsonObject(
+        { ...edge, id, fromNode, toNode },
+        `Invalid board document: edge "${id}"`,
+        jsonBudget
+      );
     });
   }
   return {
+    ...collectJsonObjectExtras(
+      parsedRecord,
+      DOCUMENT_FIELDS,
+      "Invalid board document",
+      jsonBudget
+    ),
     nodes,
     ...edges !== void 0 ? { edges } : {},
-    ...getDocumentMetadata(parsed) !== void 0 ? { "x-vue-board": getDocumentMetadata(parsed) } : {}
+    ...metadata !== void 0 ? { "x-lupinum-board": metadata } : {}
+  };
+}
+function extractJsonCanvasPassthrough(document) {
+  const record = document;
+  return {
+    document: collectJsonObjectExtras(
+      record,
+      DOCUMENT_FIELDS,
+      "Invalid board document"
+    ),
+    nodes: new Map(
+      document.nodes.map((node) => [
+        node.id,
+        collectJsonObjectExtras(
+          node,
+          NODE_FIELDS,
+          `Invalid board document: node "${node.id}"`
+        )
+      ])
+    )
   };
 }
 function materializeSnapshotNodes(snapshot) {
@@ -2056,12 +2060,13 @@ function documentToSnapshot(document) {
       jsonNodeToBoardNode(node, metadata?.nodes?.[node.id], index)
     )
   );
+  const nodeIds = new Set(nodes.map((node) => node.id));
   const gridSettings = {
     ...DEFAULT_GRID,
     ...metadata?.grid ?? {}
   };
   const selection = Array.isArray(metadata?.selection) ? metadata.selection.filter(
-    (id) => typeof id === "string" && nodes.some((node) => node.id === id)
+    (id) => typeof id === "string" && nodeIds.has(id)
   ).map((id) => id) : [];
   const nextZIndex = metadata?.nextZIndex ?? nodes.reduce((max, node) => Math.max(max, node.zIndex), 0) + 1;
   const camera = { ...DEFAULT_CAMERA, ...metadata?.camera ?? {} };
@@ -2163,6 +2168,110 @@ function createCameraSession(deps) {
   return { animateTo, cancelAnimations, computeFit };
 }
 
+// src/engine/public-engine.ts
+function createPublicEngine(engine) {
+  return {
+    plugins: engine.plugins,
+    $camera: engine.$camera,
+    $grid: engine.$grid,
+    $nodes: engine.$nodes,
+    $selection: engine.$selection,
+    $interaction: engine.$interaction,
+    $snapGuides: engine.$snapGuides,
+    destroy: engine.destroy,
+    batch: engine.batch,
+    getState: engine.getState,
+    getGridSettings: engine.getGridSettings,
+    getViewportSize: engine.getViewportSize,
+    updateGridSettings: engine.updateGridSettings,
+    setViewportSize: engine.setViewportSize,
+    on: engine.on,
+    once: engine.once,
+    off: engine.off,
+    exportTrace: engine.exportTrace,
+    addCommandGuard: engine.addCommandGuard,
+    screenToWorld: engine.screenToWorld,
+    worldToScreen: engine.worldToScreen,
+    getVisibleBounds: engine.getVisibleBounds,
+    getNode: engine.getNode,
+    findNode: engine.findNode,
+    hasNode: engine.hasNode,
+    getNodeAt: engine.getNodeAt,
+    getNodesInBounds: engine.getNodesInBounds,
+    panBy: engine.panBy,
+    panTo: engine.panTo,
+    zoomAt: engine.zoomAt,
+    zoomTo: engine.zoomTo,
+    zoomToFit: engine.zoomToFit,
+    zoomToNodes: engine.zoomToNodes,
+    createNode: engine.createNode,
+    updateNode: engine.updateNode,
+    deleteNode: engine.deleteNode,
+    moveNode: engine.moveNode,
+    translateSelectedNodes: engine.translateSelectedNodes,
+    resizeNode: engine.resizeNode,
+    bringToFront: engine.bringToFront,
+    sendToBack: engine.sendToBack,
+    lockNode: engine.lockNode,
+    unlockNode: engine.unlockNode,
+    duplicateNodes: engine.duplicateNodes,
+    copySelected: engine.copySelected,
+    pasteClipboard: engine.pasteClipboard,
+    pasteData: engine.pasteData,
+    select: engine.select,
+    selectAll: engine.selectAll,
+    clearSelection: engine.clearSelection,
+    deleteSelected: engine.deleteSelected,
+    getSelection: engine.getSelection,
+    beginTextEdit: engine.beginTextEdit,
+    commitTextEdit: engine.commitTextEdit,
+    cancelTextEdit: engine.cancelTextEdit,
+    exportDocument: engine.exportDocument,
+    loadDocument: engine.loadDocument
+  };
+}
+
+// src/engine/json-canvas-extras.ts
+function removeNodeExtras(current, id) {
+  if (!current.nodes.has(id)) return current;
+  const nodes = new Map(current.nodes);
+  nodes.delete(id);
+  return { ...current, nodes };
+}
+function copyNodeExtras(current, idMap, source = current.nodes) {
+  const nodes = new Map(current.nodes);
+  for (const [sourceId, targetId] of idMap) {
+    const extras = source.get(sourceId);
+    if (extras) nodes.set(targetId, extras);
+  }
+  return { ...current, nodes };
+}
+function replaceJsonCanvasExtras(incoming) {
+  return {
+    document: incoming.document,
+    nodes: new Map(incoming.nodes)
+  };
+}
+function mergeJsonCanvasExtras(current, incoming, idMap) {
+  const document = Object.freeze({
+    ...current.document,
+    ...incoming.document
+  });
+  const nodes = new Map(current.nodes);
+  for (const [id, extras] of incoming.nodes) {
+    nodes.set(idMap.get(id) ?? id, extras);
+  }
+  return { document, nodes };
+}
+function selectNodeExtras(source, ids) {
+  const selected = /* @__PURE__ */ new Map();
+  for (const id of ids) {
+    const extras = source.get(id);
+    if (extras) selected.set(id, extras);
+  }
+  return selected;
+}
+
 // src/engine/node-shape.ts
 function assertValidNodeGeometry(id, geometry) {
   if (!Number.isFinite(geometry.x) || !Number.isFinite(geometry.y) || !Number.isFinite(geometry.width) || !Number.isFinite(geometry.height) || geometry.width <= 0 || geometry.height <= 0) {
@@ -2368,6 +2477,7 @@ function createBoardEngine(options = {}) {
   const { emit, emitImmediate, on, once, off, reportUnhandledError } = eventBus;
   const commandGuards = createCommandGuardRegistry();
   const commitProjectors = /* @__PURE__ */ new Set();
+  const projectedSubscribables = /* @__PURE__ */ new Set();
   const nodeDeletedHooks = /* @__PURE__ */ new Set();
   const pluginCleanups = /* @__PURE__ */ new Map();
   let pluginStates = /* @__PURE__ */ new Map();
@@ -2376,6 +2486,7 @@ function createBoardEngine(options = {}) {
     for (const hook of nodeDeletedHooks) hook(nodeId);
   }
   const clipboard = [];
+  const clipboardPassthrough = /* @__PURE__ */ new Map();
   const plugins = {};
   let viewportSize = { ...DEFAULT_VIEWPORT_SIZE };
   let destroyed = false;
@@ -2414,11 +2525,13 @@ function createBoardEngine(options = {}) {
     selection: /* @__PURE__ */ new Set(),
     interaction: { mode: "idle" },
     snapGuides: [],
-    nextZIndex: 1
+    nextZIndex: 1,
+    jsonCanvas: { document: Object.freeze({}), nodes: /* @__PURE__ */ new Map() }
   };
   const initialDocument = options.initialDocument ? normalizeDocumentForImport(options.initialDocument) : null;
   if (initialDocument) {
     const initial = documentToSnapshot(initialDocument);
+    state.jsonCanvas = extractJsonCanvasPassthrough(initialDocument);
     state.camera = { ...initial.camera };
     state.selection = /* @__PURE__ */ new Set();
     state.nextZIndex = initial.nextZIndex;
@@ -2518,6 +2631,7 @@ function createBoardEngine(options = {}) {
     const checkpoint = {
       roots,
       clipboard: [...clipboard],
+      clipboardPassthrough: new Map(clipboardPassthrough),
       nodeOverrides: new Map(nodeOverrides),
       activeGestureHistoryRoot,
       activeBoxSelectionBefore
@@ -2533,6 +2647,10 @@ function createBoardEngine(options = {}) {
     grid = checkpoint.roots.grid;
     pluginStates = checkpoint.roots.pluginStates;
     clipboard.splice(0, clipboard.length, ...checkpoint.clipboard);
+    clipboardPassthrough.clear();
+    for (const [id, extras] of checkpoint.clipboardPassthrough) {
+      clipboardPassthrough.set(id, extras);
+    }
     nodeOverrides.clear();
     for (const [id, node] of checkpoint.nodeOverrides) {
       nodeOverrides.set(id, node);
@@ -2547,6 +2665,7 @@ function createBoardEngine(options = {}) {
       grid: freezeClone({ ...grid }),
       selection: state.selection,
       nextZIndex: state.nextZIndex,
+      jsonCanvas: state.jsonCanvas,
       pluginSlices: new Map(
         Array.from(pluginStates, ([name, pluginState]) => [
           name,
@@ -2557,6 +2676,11 @@ function createBoardEngine(options = {}) {
   }
   function sameHistoryRoot(left, right) {
     if (left.nextZIndex !== right.nextZIndex) return false;
+    if (left.jsonCanvas.document !== right.jsonCanvas.document) return false;
+    if (left.jsonCanvas.nodes.size !== right.jsonCanvas.nodes.size) return false;
+    for (const [id, extras] of left.jsonCanvas.nodes) {
+      if (right.jsonCanvas.nodes.get(id) !== extras) return false;
+    }
     if (left.grid.size !== right.grid.size || left.grid.majorEvery !== right.grid.majorEvery || left.grid.snap !== right.grid.snap || left.grid.edgeSnap !== right.grid.edgeSnap || left.grid.edgeSnapThreshold !== right.grid.edgeSnapThreshold || left.grid.pattern !== right.grid.pattern) {
       return false;
     }
@@ -2863,7 +2987,13 @@ function createBoardEngine(options = {}) {
       Array.from(state.selection.values()).filter((id) => state.nodes.has(id))
     );
   }
-  function restoreSnapshot(snapshot, mode) {
+  function deleteNodePassthrough(id) {
+    state.jsonCanvas = removeNodeExtras(state.jsonCanvas, id);
+  }
+  function copyNodePassthrough(idMap, source = state.jsonCanvas.nodes) {
+    state.jsonCanvas = copyNodeExtras(state.jsonCanvas, idMap, source);
+  }
+  function restoreSnapshot(snapshot, mode, passthrough) {
     const snapshotNodes = materializeSnapshotNodes(snapshot);
     const idMap = /* @__PURE__ */ new Map();
     if (mode === "replace") {
@@ -2874,6 +3004,7 @@ function createBoardEngine(options = {}) {
           continue;
         }
         state.nodes.delete(id);
+        deleteNodePassthrough(id);
         notifyNodeDeletedPlugins(prevNode.id);
         emit("node:deleted", id, materializeNode2(prevNode));
       }
@@ -2884,6 +3015,7 @@ function createBoardEngine(options = {}) {
         idMap.set(rawNode.id, node.id);
         emit("node:created", materializeNode2(node));
       }
+      state.jsonCanvas = replaceJsonCanvasExtras(passthrough);
       state.selection = new Set(
         snapshot.selection.filter((id) => state.nodes.has(id))
       );
@@ -2898,12 +3030,29 @@ function createBoardEngine(options = {}) {
       notifySnapGuidesChanged();
       return idMap;
     }
+    const reservedIds = new Set(state.nodes.keys());
+    for (const rawNode of snapshotNodes) {
+      let id = rawNode.id;
+      while (reservedIds.has(id)) id = createNodeId();
+      reservedIds.add(id);
+      idMap.set(rawNode.id, id);
+    }
     for (const rawNode of snapshotNodes) {
       const node = normalizeExistingNode(rawNode);
-      const id = state.nodes.has(node.id) ? createNodeId() : node.id;
-      state.nodes.set(id, { ...node, id, zIndex: state.nextZIndex++ });
-      idMap.set(node.id, id);
+      const id = idMap.get(node.id);
+      const parentId = node.parentId ? idMap.get(node.parentId) ?? node.parentId : void 0;
+      state.nodes.set(id, {
+        ...node,
+        id,
+        parentId,
+        zIndex: state.nextZIndex++
+      });
     }
+    state.jsonCanvas = mergeJsonCanvasExtras(
+      state.jsonCanvas,
+      passthrough,
+      idMap
+    );
     notifyNodesChanged();
     return idMap;
   }
@@ -2998,6 +3147,8 @@ function createBoardEngine(options = {}) {
       pluginStates.clear();
       pluginPersistence.clear();
       commitProjectors.clear();
+      for (const projection of projectedSubscribables) projection.destroy();
+      projectedSubscribables.clear();
       nodeDeletedHooks.clear();
       commandGuards.clear();
       eventBus.clear();
@@ -3011,7 +3162,7 @@ function createBoardEngine(options = {}) {
     },
     extend(key, value) {
       assertMutationAllowed();
-      plugins[key] = value;
+      Reflect.set(plugins, key, value);
     },
     batch(fn) {
       assertCommandReady();
@@ -3120,6 +3271,27 @@ function createBoardEngine(options = {}) {
       commitProjectors.add(projector);
       return () => commitProjectors.delete(projector);
     },
+    createCommitSubscribable(select, channel) {
+      assertAlive();
+      assertMutationAllowed();
+      let selected = select();
+      const projection = createSubscribable(
+        selected,
+        createBatchController(),
+        (error) => reportUnhandledError(error, { source: "subscriber", channel })
+      );
+      const projector = () => {
+        const next = select();
+        if (Object.is(next, selected)) return () => void 0;
+        return () => {
+          selected = next;
+          projection.set(next);
+        };
+      };
+      commitProjectors.add(projector);
+      projectedSubscribables.add(projection);
+      return projection;
+    },
     restoreHistoryRoot(root) {
       runCommand(
         "history:restore",
@@ -3132,6 +3304,10 @@ function createBoardEngine(options = {}) {
             Array.from(root.selection).filter((id) => state.nodes.has(id))
           );
           state.nextZIndex = root.nextZIndex;
+          state.jsonCanvas = {
+            document: root.jsonCanvas.document,
+            nodes: new Map(root.jsonCanvas.nodes)
+          };
           Object.assign(grid, root.grid);
           for (const [name, pluginState] of pluginStates) {
             if (root.pluginSlices.has(name)) {
@@ -3147,16 +3323,6 @@ function createBoardEngine(options = {}) {
         IGNORE_COMMAND
       );
     },
-    getPluginState() {
-      throw new Error(
-        "getPluginState is only available inside an internal plugin install() context."
-      );
-    },
-    updatePluginState(_update) {
-      throw new Error(
-        "updatePluginState is only available inside an internal plugin install() context."
-      );
-    },
     screenToWorld(point) {
       assertAlive();
       return screenToWorld(point, state.camera);
@@ -3344,6 +3510,7 @@ function createBoardEngine(options = {}) {
             continue;
           }
           state.nodes.delete(deleteId);
+          deleteNodePassthrough(deleteId);
           notifyNodeDeletedPlugins(prevNode.id);
           emit("node:deleted", deleteId, materializeNode2(prevNode));
         }
@@ -3501,6 +3668,7 @@ function createBoardEngine(options = {}) {
         const forest = forestIdsFromSeeds(ids);
         const source = Array.from(forest).map((id) => state.nodes.get(id)).filter((node) => Boolean(node)).sort((a, b) => a.zIndex - b.zIndex);
         const duplicated = duplicateForest2(source, offset);
+        copyNodePassthrough(duplicated.idMap);
         const created = duplicated.nodes;
         for (const node of created) {
           state.nodes.set(node.id, node);
@@ -3517,15 +3685,59 @@ function createBoardEngine(options = {}) {
     copySelected() {
       return runCommand("copySelected", [], () => {
         clipboard.length = 0;
-        for (const node of getCopyClosureNodes2()) {
+        clipboardPassthrough.clear();
+        const copied = getCopyClosureNodes2();
+        for (const node of copied) {
           clipboard.push({ ...node });
         }
+        for (const [id, extras] of selectNodeExtras(
+          state.jsonCanvas.nodes,
+          copied.map((node) => node.id)
+        )) {
+          clipboardPassthrough.set(id, extras);
+        }
         return clipboard.map((node) => materializeNode2(node));
       });
     },
     pasteClipboard(offset = { x: grid.size, y: grid.size }) {
       return runCommand("pasteClipboard", [offset], () => {
-        const created = duplicateForest2(clipboard, offset).nodes;
+        const duplicated = duplicateForest2(clipboard, offset);
+        copyNodePassthrough(duplicated.idMap, clipboardPassthrough);
+        const created = duplicated.nodes;
+        for (const node of created) {
+          state.nodes.set(node.id, node);
+          emit("node:created", materializeNode2(node));
+        }
+        notifyNodesChanged();
+        setSelection(created.map((node) => node.id));
+        return created.map((node) => materializeNode2(node));
+      });
+    },
+    pasteData(payload, offset = { x: grid.size, y: grid.size }) {
+      return runCommand("pasteData", [payload, offset], () => {
+        const inputs = options.clipboard?.deserialize(payload) ?? null;
+        if (!inputs || inputs.length === 0) return null;
+        const stagedNodes = new Map(state.nodes);
+        let nextZIndex = state.nextZIndex;
+        const created = inputs.map((input) => {
+          const normalized = normalizeNodeInput(
+            {
+              ...input,
+              x: input.x ?? offset.x,
+              y: input.y ?? offset.y
+            },
+            {
+              nodes: stagedNodes,
+              grid,
+              constraints: nodeConstraints,
+              nextZIndex
+            }
+          );
+          nextZIndex = normalized.nextZIndex;
+          stagedNodes.set(normalized.node.id, normalized.node);
+          return normalized.node;
+        });
+        state.nextZIndex = nextZIndex;
         for (const node of created) {
           state.nodes.set(node.id, node);
           emit("node:created", materializeNode2(node));
@@ -3600,6 +3812,7 @@ function createBoardEngine(options = {}) {
             continue;
           }
           state.nodes.delete(deleteId);
+          deleteNodePassthrough(deleteId);
           notifyNodeDeletedPlugins(prevNode.id);
           emit("node:deleted", deleteId, materializeNode2(prevNode));
         }
@@ -4038,7 +4251,8 @@ function createBoardEngine(options = {}) {
       );
       return toPersistedDocument(
         buildSnapshot(state, grid, buildPublicNodeMap(state)),
-        pluginDocuments
+        pluginDocuments,
+        state.jsonCanvas
       );
     },
     loadDocument(document, options2 = {}) {
@@ -4050,10 +4264,11 @@ function createBoardEngine(options = {}) {
           const normalized = normalizeDocumentForImport(document);
           assertCanRestoreDocument(normalized);
           const snapshot = documentToSnapshot(normalized);
+          const passthrough = extractJsonCanvasPassthrough(normalized);
           nodeOverrides.clear();
           activeGestureHistoryRoot = null;
           activeBoxSelectionBefore = null;
-          const idMap = restoreSnapshot(snapshot, mode);
+          const idMap = restoreSnapshot(snapshot, mode, passthrough);
           restorePluginDocuments(normalized, mode, idMap);
         },
         IGNORE_COMMAND
@@ -4075,29 +4290,7 @@ function createBoardEngine(options = {}) {
     );
   }
   validate("createBoardEngine");
-  const internalKeys = /* @__PURE__ */ new Set([
-    "emit",
-    "assertActive",
-    "isBatching",
-    "extend",
-    "runCommand",
-    "projectCommit",
-    "restoreHistoryRoot",
-    "getPluginState",
-    "updatePluginState",
-    "beginPan",
-    "beginNodeDrag",
-    "beginResize",
-    "beginBoxSelect",
-    "updatePointer",
-    "endInteraction",
-    "cancelInteraction",
-    "getUniformTranslationTargets",
-    "syncGroupZOrder"
-  ]);
-  const publicEngine = Object.fromEntries(
-    Object.entries(engine).filter(([key]) => !internalKeys.has(key))
-  );
+  const publicEngine = createPublicEngine(engine);
   registerBoardInteractionAdapter(publicEngine, engine);
   return publicEngine;
 }