y-mxgraph 0.8.6 → 0.9.1

package/y-mxgraph.js

@@ -1,4 +1,4 @@
-import { g as getMap, b as backgroundKey, k as key, a as key$1, c as key$2, d as diagramOrderKey, m as mxCellOrderKey, e as key$3, p as parse, f as parse$1, h as serializer, s as serialize, x as xml2ydoc, y as ydoc2xml } from "./index-BhW4J2Zt.js";
+import { g as getMap, b as backgroundKey, k as key, a as key$1, c as key$2, d as diagramOrderKey, m as mxCellOrderKey, e as key$3, p as parse, f as parse$1, s as serializer, h as serialize, y as ydoc2xml, x as xml2ydoc } from "./index-CN7tFgEG.js";
 import * as Y from "yjs";
 import { colord } from "colord";
 function patchValueToXmlAttr(value) {
@@ -74,9 +74,15 @@ const DIFF_UPDATE = "u";
 const docSnapshots = /* @__PURE__ */ new WeakMap();
 function insertAfterUnique(orderArr, id, previous, fallbackToEnd = false) {
   const currentIds = orderArr.toArray();
-  let anchorPos = previous ? currentIds.indexOf(previous) : -1;
+  let anchorPos = previous != null ? currentIds.indexOf(previous) : -1;
   if (anchorPos === -1 && fallbackToEnd) anchorPos = currentIds.length - 1;
   let targetIndex = anchorPos + 1;
+  if (previous === "" && id !== "0" && id !== "1") {
+    const layerIndex = currentIds.indexOf("1");
+    if (layerIndex >= 0) {
+      targetIndex = layerIndex + 1;
+    }
+  }
   const existingIndex = currentIds.indexOf(id);
   if (existingIndex === -1) {
     orderArr.insert(targetIndex, [id]);
@@ -131,34 +137,41 @@ function pruneEmptyPatch(patch) {
 }
 function applyFilePatch(doc, patch, options) {
   doc.transact(() => {
+    var _a, _b;
     const mxfile = doc.getMap(key$1);
     if (patch[DIFF_REMOVE]) {
       const diagramsMap = mxfile.get(key$2);
-      const orderArr = mxfile.get(
-        diagramOrderKey
-      );
-      ensureUniqueOrder(orderArr);
-      const orderList = orderArr.toArray();
+      const orderArr = mxfile.get(diagramOrderKey);
+      if (orderArr) ensureUniqueOrder(orderArr);
       const removeIds = patch[DIFF_REMOVE];
       if (removeIds && removeIds.length) {
-        const indexList = removeIds.map((id) => orderList.indexOf(id)).filter((i) => i !== -1).sort((a, b) => b - a);
-        indexList.forEach((idx) => orderArr.delete(idx, 1));
-        removeIds.forEach((id) => diagramsMap.delete(id));
+        if (orderArr) {
+          const orderList = orderArr.toArray();
+          const indexList = removeIds.map((id) => orderList.indexOf(id)).filter((i) => i !== -1).sort((a, b) => b - a);
+          indexList.forEach((idx) => orderArr.delete(idx, 1));
+        }
+        if (diagramsMap) {
+          removeIds.forEach((id) => {
+            if (diagramsMap.has(id)) {
+              diagramsMap.delete(id);
+            }
+          });
+        }
       }
     }
     if (patch[DIFF_INSERT]) {
       const diagramsMap = mxfile.get(key$2);
-      const orderArr = mxfile.get(
-        diagramOrderKey
-      );
-      ensureUniqueOrder(orderArr);
-      const currentOrder = orderArr.toArray();
-      if (currentOrder.length === 0 && diagramsMap && diagramsMap.size > 0) {
-        const allIds = Array.from(diagramsMap.keys());
-        orderArr.push(allIds);
+      const orderArr = mxfile.get(diagramOrderKey);
+      if (orderArr) {
+        ensureUniqueOrder(orderArr);
+        const currentOrder = orderArr.toArray();
+        if (currentOrder.length === 0 && diagramsMap && diagramsMap.size > 0) {
+          const allIds = Array.from(diagramsMap.keys());
+          orderArr.push(allIds);
+        }
+        ensureUniqueOrder(orderArr);
       }
-      ensureUniqueOrder(orderArr);
-      const existingIds = orderArr.toArray();
+      const existingIds = (_a = orderArr == null ? void 0 : orderArr.toArray()) != null ? _a : [];
       const existingIndex = /* @__PURE__ */ new Map();
       existingIds.forEach((id, idx) => existingIndex.set(id, idx));
       const inserts = patch[DIFF_INSERT].map((item, order) => {
@@ -169,7 +182,7 @@ function applyFilePatch(doc, patch, options) {
         );
         return {
           id: item.id,
-          previous: item.previous || "",
+          previous: item.previous === void 0 ? null : item.previous,
           diagramElement,
           order
         };
@@ -211,16 +224,19 @@ function applyFilePatch(doc, patch, options) {
         return b.order - a.order;
       });
       for (const item of enriched) {
-        diagramsMap.set(item.id, item.diagramElement);
-        insertAfterUnique(orderArr, item.id, item.anchorId || null);
+        if (diagramsMap) {
+          diagramsMap.set(item.id, item.diagramElement);
+        }
+        if (orderArr) {
+          const anchorArg = item.anchorId === "" ? "" : (_b = item.anchorId) != null ? _b : null;
+          insertAfterUnique(orderArr, item.id, anchorArg);
+        }
       }
     }
     if (patch[DIFF_UPDATE]) {
       Object.keys(patch[DIFF_UPDATE]).forEach((id) => {
-        const diagramsMap = mxfile.get(
-          key$2
-        );
-        const diagram = diagramsMap.get(id);
+        const diagramsMap = mxfile.get(key$2);
+        const diagram = diagramsMap == null ? void 0 : diagramsMap.get(id);
         if (diagram) {
           const update = patch[DIFF_UPDATE][id];
           if ("name" in update) {
@@ -234,132 +250,151 @@ function applyFilePatch(doc, patch, options) {
           }
           if (update.cells) {
             const yMxGraphModel = diagram.get(key);
-            if (!yMxGraphModel) return;
+            if (!yMxGraphModel) {
+              console.warn(
+                "[y-mxgraph] applyFilePatch: yMxGraphModel not found for diagram, skipping cells update"
+              );
+              return;
+            }
             const cellsMap = yMxGraphModel.get(key$3);
             const orderArr = yMxGraphModel.get(mxCellOrderKey);
-            if (!cellsMap || !orderArr) return;
-            ensureUniqueOrder(orderArr);
+            if (!cellsMap && !orderArr) {
+              console.warn(
+                "[y-mxgraph] applyFilePatch: both cellsMap and orderArr missing, skipping cells update"
+              );
+              return;
+            }
+            if (orderArr) ensureUniqueOrder(orderArr);
             if (update.cells[DIFF_REMOVE] && update.cells[DIFF_REMOVE].length) {
-              const orderIds = orderArr.toArray();
-              const removeIndexList = update.cells[DIFF_REMOVE].map(
-                (cid) => orderIds.indexOf(cid)
-              ).filter((i) => i !== -1).sort((a, b) => b - a);
-              removeIndexList.forEach((idx) => orderArr.delete(idx, 1));
-              update.cells[DIFF_REMOVE].forEach((cid) => cellsMap.delete(cid));
+              if (orderArr) {
+                const orderIds = orderArr.toArray();
+                const removeIndexList = update.cells[DIFF_REMOVE].map(
+                  (cid) => orderIds.indexOf(cid)
+                ).filter((i) => i !== -1).sort((a, b) => b - a);
+                removeIndexList.forEach((idx) => orderArr.delete(idx, 1));
+              }
+              if (cellsMap) {
+                update.cells[DIFF_REMOVE].forEach((cid) => {
+                  if (cellsMap.has(cid)) {
+                    cellsMap.delete(cid);
+                  }
+                });
+              }
             }
             if (update.cells[DIFF_INSERT] && update.cells[DIFF_INSERT].length) {
               for (const item of update.cells[DIFF_INSERT]) {
                 const id2 = item["id"];
                 if (!id2) continue;
-                const xmlElement = new Y.XmlElement("mxCell");
-                Object.keys(item).forEach((key2) => {
-                  if (key2 === "previous") return;
-                  xmlElement.setAttribute(key2, item[key2]);
-                });
-                cellsMap.set(id2, xmlElement);
-                const previous = item["previous"];
-                const parent = item["parent"];
-                let anchorId = null;
-                let fallbackToEnd = true;
-                if (typeof previous !== "undefined") {
-                  if (previous === "") {
-                    if (parent) {
-                      anchorId = parent;
-                      fallbackToEnd = true;
-                    } else {
-                      anchorId = null;
+                if (cellsMap) {
+                  const xmlElement = new Y.XmlElement("mxCell");
+                  Object.keys(item).forEach((key2) => {
+                    if (key2 === "previous") return;
+                    xmlElement.setAttribute(key2, item[key2]);
+                  });
+                  cellsMap.set(id2, xmlElement);
+                }
+                if (orderArr) {
+                  const previous = item["previous"];
+                  const parent = item["parent"];
+                  let anchorId = null;
+                  let fallbackToEnd = true;
+                  if (typeof previous !== "undefined") {
+                    if (previous === "") {
+                      anchorId = "";
                       fallbackToEnd = false;
+                    } else {
+                      anchorId = previous;
+                      fallbackToEnd = true;
                     }
-                  } else {
-                    anchorId = previous;
+                  } else if (parent) {
+                    anchorId = parent;
                     fallbackToEnd = true;
                   }
-                } else if (parent) {
-                  anchorId = parent;
-                  fallbackToEnd = true;
+                  insertAfterUnique(
+                    orderArr,
+                    id2,
+                    anchorId,
+                    fallbackToEnd
+                  );
                 }
-                insertAfterUnique(
-                  orderArr,
-                  id2,
-                  anchorId,
-                  fallbackToEnd
-                );
               }
             }
             if (update.cells[DIFF_UPDATE]) {
-              Object.keys(update.cells[DIFF_UPDATE]).forEach((cid) => {
-                const updateObj = update.cells[DIFF_UPDATE][cid];
-                const cell = cellsMap.get(cid);
-                if (cell) {
-                  Object.keys(updateObj).forEach((k) => {
-                    if (k === "previous") return;
-                    cell.setAttribute(k, updateObj[k]);
-                  });
-                }
-              });
-              Object.keys(update.cells[DIFF_UPDATE]).forEach((cellId) => {
-                const updateObj = update.cells[DIFF_UPDATE][cellId];
-                const hasPrev = "previous" in updateObj;
-                const hasParent = "parent" in updateObj;
-                if (!hasPrev && !hasParent) return;
-                const prevVal = hasPrev ? updateObj.previous : void 0;
-                const parentVal = hasParent ? updateObj.parent : void 0;
-                let anchorId = null;
-                let fallbackToEnd = true;
-                if (hasPrev) {
-                  if (prevVal === "") {
-                    if (parentVal) {
-                      anchorId = parentVal;
+              if (cellsMap) {
+                Object.keys(update.cells[DIFF_UPDATE]).forEach((cid) => {
+                  const updateObj = update.cells[DIFF_UPDATE][cid];
+                  const cell = cellsMap.get(cid);
+                  if (cell) {
+                    Object.keys(updateObj).forEach((k) => {
+                      if (k === "previous") return;
+                      cell.setAttribute(k, updateObj[k]);
+                    });
+                  } else {
+                    console.warn(
+                      `[y-mxgraph] applyFilePatch: cell ${cid} not found in cellsMap, skipping update`
+                    );
+                  }
+                });
+              }
+              if (cellsMap && orderArr) {
+                const reorderEntries = Object.keys(update.cells[DIFF_UPDATE]).map((cellId) => {
+                  const updateObj = update.cells[DIFF_UPDATE][cellId];
+                  const hasPrev = "previous" in updateObj;
+                  const hasParent = "parent" in updateObj;
+                  if (!hasPrev && !hasParent) return null;
+                  const prevVal = hasPrev ? updateObj.previous : void 0;
+                  const parentVal = hasParent ? updateObj.parent : void 0;
+                  let anchorId = null;
+                  let fallbackToEnd = true;
+                  if (hasPrev) {
+                    if (prevVal === "") {
+                      anchorId = "";
+                      fallbackToEnd = false;
+                    } else if (prevVal === null || typeof prevVal === "undefined") {
+                      anchorId = null;
                       fallbackToEnd = true;
                     } else {
-                      anchorId = null;
-                      fallbackToEnd = false;
+                      anchorId = prevVal;
+                      fallbackToEnd = true;
                     }
-                  } else {
-                    anchorId = prevVal;
+                  } else if (parentVal) {
+                    anchorId = parentVal;
                     fallbackToEnd = true;
                   }
-                } else if (parentVal) {
-                  anchorId = parentVal;
-                  fallbackToEnd = true;
-                }
-                const currentIds = orderArr.toArray();
-                const currentIndex = currentIds.indexOf(cellId);
-                if (currentIndex === -1) {
-                  let newCell = cellsMap.get(cellId);
-                  if (!newCell) {
-                    newCell = new Y.XmlElement("mxCell");
-                    newCell.setAttribute("id", cellId);
-                    Object.keys(updateObj).forEach((k) => {
-                      if (k === "previous") return;
-                      newCell.setAttribute(k, updateObj[k]);
-                    });
-                    cellsMap.set(cellId, newCell);
+                  return { cellId, anchorId, fallbackToEnd, updateObj };
+                }).filter((e) => e !== null);
+                const applyReorder = (entry) => {
+                  const { cellId, anchorId, fallbackToEnd, updateObj } = entry;
+                  const currentIds = orderArr.toArray();
+                  const currentIndex = currentIds.indexOf(cellId);
+                  if (currentIndex === -1) {
+                    let newCell = cellsMap.get(cellId);
+                    if (!newCell) {
+                      newCell = new Y.XmlElement("mxCell");
+                      newCell.setAttribute("id", cellId);
+                      Object.keys(updateObj).forEach((k) => {
+                        if (k === "previous") return;
+                        newCell.setAttribute(k, updateObj[k]);
+                      });
+                      cellsMap.set(cellId, newCell);
+                    }
+                    insertAfterUnique(orderArr, cellId, anchorId, fallbackToEnd);
+                    return;
                   }
-                  insertAfterUnique(
-                    orderArr,
-                    cellId,
-                    anchorId,
-                    fallbackToEnd
-                  );
-                  return;
-                }
-                insertAfterUnique(
-                  orderArr,
-                  cellId,
-                  anchorId,
-                  fallbackToEnd
-                );
-              });
+                  insertAfterUnique(orderArr, cellId, anchorId, fallbackToEnd);
+                };
+                reorderEntries.filter((e) => e.anchorId === "" || e.anchorId === null).forEach(applyReorder);
+                reorderEntries.filter((e) => e.anchorId !== "" && e.anchorId !== null).forEach(applyReorder);
+              }
             }
           }
           if ("previous" in update) {
-            const previous = update.previous || null;
-            const orderArr = mxfile.get(
-              diagramOrderKey
-            );
-            ensureUniqueOrder(orderArr);
-            insertAfterUnique(orderArr, id, previous, false);
+            const previous = Object.prototype.hasOwnProperty.call(update, "previous") ? update.previous : null;
+            const orderArr = mxfile.get(diagramOrderKey);
+            if (orderArr) {
+              ensureUniqueOrder(orderArr);
+              insertAfterUnique(orderArr, id, previous, false);
+            }
           }
         }
       });
@@ -380,7 +415,7 @@ function initDocSnapshot(doc, resetSnapshot = false) {
       cellAttrs: /* @__PURE__ */ new Map(),
       diagramBackground: /* @__PURE__ */ new Map()
     };
-    const diagrams = diagramOrder.map((id) => diagramsMap.get(id)).filter((d) => !!d);
+    const diagrams = diagramOrder.map((id) => diagramsMap == null ? void 0 : diagramsMap.get(id)).filter((d) => !!d);
     for (const d of diagrams) {
       const did = d.get("id") || "";
       if (!did) continue;
@@ -415,7 +450,7 @@ function initDocSnapshot(doc, resetSnapshot = false) {
   }
 }
 function generatePatch(events, explicitDoc) {
-  var _a, _b, _c, _d, _e;
+  var _a, _b, _c, _d, _e, _f;
   const patch = {};
   const doc = (_b = (_a = events[0]) == null ? void 0 : _a.transaction) == null ? void 0 : _b.doc;
   if (!doc) return patch;
@@ -449,7 +484,7 @@ function generatePatch(events, explicitDoc) {
   };
   const orderIds = (_c = orderArr == null ? void 0 : orderArr.toArray()) != null ? _c : [];
   const currDiagramOrder = orderIds.length > 0 ? orderIds : diagramsMap ? Array.from(diagramsMap.keys()) : [];
-  const diagramsList = currDiagramOrder.map((id) => diagramsMap.get(id)).filter((d) => !!d);
+  const diagramsList = currDiagramOrder.map((id) => diagramsMap == null ? void 0 : diagramsMap.get(id)).filter((d) => !!d);
   const currCellsOrder = /* @__PURE__ */ new Map();
   const cellAttrMap = /* @__PURE__ */ new Map();
   const currDiagramBackground = /* @__PURE__ */ new Map();
@@ -495,7 +530,7 @@ function generatePatch(events, explicitDoc) {
       for (const id of inserted) {
         const index = currDiagramOrder.indexOf(id);
         const previous = index <= 0 ? "" : currDiagramOrder[index - 1];
-        const yDiagram = diagramsMap.get(id);
+        const yDiagram = diagramsMap == null ? void 0 : diagramsMap.get(id);
         if (!yDiagram) continue;
         const data = serializer({ diagram: serialize(yDiagram) });
         patch[DIFF_INSERT].push({ id, previous, data });
@@ -504,7 +539,8 @@ function generatePatch(events, explicitDoc) {
     }
     const prevNeighbor = (order, id) => {
       const i = order.indexOf(id);
-      return i <= 0 ? "" : order[i - 1];
+      if (i === -1) return null;
+      return i === 0 ? "" : order[i - 1];
     };
     const common = currDiagramOrder.filter((id) => prevSet.has(id) && id);
     for (const id of common) {
@@ -553,7 +589,8 @@ function generatePatch(events, explicitDoc) {
     }
     const prevNeighbor = (order, id) => {
       const i = order.indexOf(id);
-      return i <= 0 ? "" : order[i - 1];
+      if (i === -1) return null;
+      return i === 0 ? "" : order[i - 1];
     };
     const commonCells = currCells.filter((cid) => prevSet.has(cid) && cid);
     for (const cid of commonCells) {
@@ -630,7 +667,7 @@ function generatePatch(events, explicitDoc) {
     cellsPatch[DIFF_UPDATE] = cellsPatch[DIFF_UPDATE] || {};
     const cellUpdate = cellsPatch[DIFF_UPDATE][cellId] = cellsPatch[DIFF_UPDATE][cellId] || {};
     for (const key2 of Array.from(changed)) {
-      cellUpdate[key2] = el.getAttribute(key2) || "";
+      cellUpdate[key2] = (_d = el.getAttribute(key2)) != null ? _d : "";
     }
   }
   if (prevDiagramOrder) {
@@ -659,8 +696,8 @@ function generatePatch(events, explicitDoc) {
         const cellUpdate = updateBucket[cid] = updateBucket[cid] || {};
         let changed = false;
         for (const k of keys) {
-          const pv = (_d = prevAttrs[k]) != null ? _d : "";
-          const cv = (_e = currAttrs[k]) != null ? _e : "";
+          const pv = (_e = prevAttrs[k]) != null ? _e : "";
+          const cv = (_f = currAttrs[k]) != null ? _f : "";
           if (pv !== cv) {
             cellUpdate[k] = cv;
             changed = true;
@@ -1346,6 +1383,91 @@ function bindCollaborator(file, options) {
     cleanupAwareness == null ? void 0 : cleanupAwareness();
   };
 }
+function checkConsistency(doc, fileData) {
+  try {
+    const xmlFromYdoc = ydoc2xml(doc);
+    if (xmlFromYdoc === fileData) return true;
+    const diagramCountFromYdoc = (xmlFromYdoc.match(/<diagram /g) || []).length;
+    const diagramCountFromFile = (fileData.match(/<diagram /g) || []).length;
+    if (diagramCountFromYdoc !== diagramCountFromFile) return false;
+    const cellCountFromYdoc = (xmlFromYdoc.match(/<mxCell /g) || []).length;
+    const cellCountFromFile = (fileData.match(/<mxCell /g) || []).length;
+    if (cellCountFromYdoc !== cellCountFromFile) return false;
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+class ConsistencyChecker {
+  constructor(doc, getFileData, options = {}) {
+    this.doc = doc;
+    this.getFileData = getFileData;
+    this.intervalId = null;
+    this.handlers = /* @__PURE__ */ new Set();
+    this.consecutiveDriftCount = 0;
+    var _a, _b;
+    this.source = (_a = options.source) != null ? _a : "binding";
+    this.maxAutoFixAttempts = (_b = options.maxAutoFixAttempts) != null ? _b : 3;
+  }
+  /** 注册 drift 事件监听 */
+  onDrift(handler) {
+    this.handlers.add(handler);
+    return () => this.handlers.delete(handler);
+  }
+  /** 启动定期检查（毫秒间隔），0 或负数表示禁用 */
+  start(intervalMs) {
+    this.stop();
+    if (intervalMs <= 0) return;
+    this.intervalId = setInterval(() => {
+      this.check();
+    }, intervalMs);
+  }
+  /** 停止定期检查 */
+  stop() {
+    if (this.intervalId != null) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+  }
+  /**
+   * 执行一次一致性检查。
+   * @returns true = 一致，false = 存在 drift
+   */
+  check() {
+    const consistent = checkConsistency(this.doc, this.getFileData());
+    if (consistent) {
+      this.consecutiveDriftCount = 0;
+      return true;
+    }
+    this.consecutiveDriftCount++;
+    const event = {
+      timestamp: Date.now(),
+      source: this.source,
+      direction: "unknown",
+      details: `drift detected (consecutive #${this.consecutiveDriftCount})`
+    };
+    this.handlers.forEach((handler) => {
+      try {
+        handler(event);
+      } catch (e) {
+        console.warn("[y-mxgraph] drift handler error:", e);
+      }
+    });
+    return false;
+  }
+  /** 重置连续 drift 计数（forceSync 成功后调用） */
+  resetDriftCount() {
+    this.consecutiveDriftCount = 0;
+  }
+  /** 是否已超过最大自动修复次数 */
+  get shouldStopAutoFix() {
+    return this.consecutiveDriftCount >= this.maxAutoFixAttempts;
+  }
+  destroy() {
+    this.stop();
+    this.handlers.clear();
+  }
+}
 const defaultApplyFileData = (file, xml) => {
   file.ui.setFileData(xml);
 };
@@ -1457,6 +1579,7 @@ class Binding {
     this.suppressLocalApply = false;
     this.docInitialized = false;
     this.ui = null;
+    this.debouncedForceSync = null;
     const {
       doc,
       awareness,
@@ -1466,12 +1589,15 @@ class Binding {
       initialContent = "replace",
       applyFileData = defaultApplyFileData,
       disableBeforeUnload = true,
-      transformPatch
+      transformPatch,
+      syncOnOrderMismatch = false
     } = options;
     this.doc = doc;
     this.file = file;
     this.initialContentStrategy = initialContent;
     this.transformPatch = transformPatch;
+    this.applyFileData = applyFileData;
+    this.syncOnOrderMismatch = syncOnOrderMismatch;
     const ui = file.getUi();
     const graph = ui.editor.graph;
     this.mxGraphModel = graph.model;
@@ -1522,7 +1648,6 @@ class Binding {
     this.mxGraphModel.addListener("change", this.mxListener);
     this.docObserver = (events, transaction) => {
       if (transaction.local && transaction.origin === LOCAL_ORIGIN) {
-        generatePatch(events);
         return;
       }
       if (this.shouldReplaceWhenDocHasData && !transaction.local) {
@@ -1549,7 +1674,8 @@ class Binding {
         this.docInitialized = true;
       }
       const patch = generatePatch(events);
-      if (Object.keys(patch).length === 0) return;
+      const patchKeys = Object.keys(patch);
+      if (patchKeys.length === 0) return;
       this.suppressLocalApply = true;
       try {
         file.patch([patch]);
@@ -1558,6 +1684,14 @@ class Binding {
       } finally {
         this.suppressLocalApply = false;
       }
+      if (this.syncOnOrderMismatch && patch.u && this.checkOrderMismatch(patch)) {
+        console.warn("[y-mxgraph] order mismatch detected, debounced forceSync (file → ydoc)");
+        if (this.debouncedForceSync) clearTimeout(this.debouncedForceSync);
+        this.debouncedForceSync = setTimeout(() => {
+          this.debouncedForceSync = null;
+          this.forceSync("file-to-ydoc");
+        }, 300);
+      }
     };
     doc.getMap(key$1).observeDeep(this.docObserver);
     if (awareness) {
@@ -1571,6 +1705,29 @@ class Binding {
     if (undoManager) {
       this.cleanupUndoManager = bindUndoManager(doc, file, undoManager);
     }
+    const {
+      consistencyCheckInterval,
+      onDrift
+    } = options;
+    if (consistencyCheckInterval && consistencyCheckInterval > 0) {
+      this.consistencyChecker = new ConsistencyChecker(doc, () => file.data, {
+        source: "binding"
+      });
+      if (onDrift) {
+        this.consistencyChecker.onDrift(onDrift);
+      }
+      this.consistencyChecker.onDrift((event) => {
+        var _a;
+        if ((_a = this.consistencyChecker) == null ? void 0 : _a.shouldStopAutoFix) {
+          console.warn(
+            `[y-mxgraph] 连续 ${event.details} 次 drift，停止自动 forceSync`
+          );
+          return;
+        }
+        this.forceSync("ydoc-to-file");
+      });
+      this.consistencyChecker.start(consistencyCheckInterval);
+    }
   }
   /** replace 策略下，构造时 doc 为空，现在 doc 有数据时需要强制替换 */
   get shouldReplaceWhenDocHasData() {
@@ -1587,17 +1744,83 @@ class Binding {
     this.ui.editor.setStatus("");
     (_a = this.ui.currentFile) == null ? void 0 : _a.setModified(false);
   }
+  /**
+   * 强制同步 ydoc 与 file，修复检测到的不一致。
+   *
+   * @param direction - 同步方向
+   *   - `ydoc-to-file`（默认）：用 ydoc 数据覆盖 file
+   *   - `file-to-ydoc`：用 file 数据覆盖 ydoc
+   */
+  forceSync(direction = "ydoc-to-file") {
+    var _a;
+    if (direction === "ydoc-to-file") {
+      const xml = ydoc2xml(this.doc);
+      if (!xml || !xml.includes("<diagram")) return;
+      this.suppressLocalApply = true;
+      try {
+        this.applyFileData(this.file, xml);
+        this.file.setShadowPages(this.file.ui.clonePages(this.file.ui.pages));
+        initDocSnapshot(this.doc, false);
+        this.resetEditorStatus();
+      } finally {
+        this.suppressLocalApply = false;
+      }
+    } else {
+      this.doc.transact(() => {
+        xml2ydoc(this.file.data, this.doc);
+        initDocSnapshot(this.doc, false);
+      }, LOCAL_ORIGIN);
+    }
+    (_a = this.consistencyChecker) == null ? void 0 : _a.resetDriftCount();
+  }
+  checkOrderMismatch(patch) {
+    var _a;
+    if (!patch.u) return false;
+    for (const [did, update] of Object.entries(patch.u)) {
+      if (!((_a = update.cells) == null ? void 0 : _a.u)) continue;
+      for (const [cid, cellUpdate] of Object.entries(update.cells.u)) {
+        if (!("previous" in cellUpdate)) continue;
+        const mxfile = this.doc.getMap(key$1);
+        const diagramsMap = mxfile.get(key$2);
+        const diagram = diagramsMap == null ? void 0 : diagramsMap.get(did);
+        if (!diagram) continue;
+        const gm = diagram.get(key);
+        if (!gm) continue;
+        const orderArr = gm.get(mxCellOrderKey);
+        if (!orderArr) continue;
+        const ids = orderArr.toArray();
+        const idx = ids.indexOf(cid);
+        if (idx === -1) continue;
+        const expectedPrev = idx === 0 ? "" : ids[idx - 1];
+        const actualPrev = cellUpdate.previous;
+        if (expectedPrev !== actualPrev) {
+          console.log(`[y-mxgraph] order mismatch: cell=${cid}, ydoc prev=${JSON.stringify(expectedPrev)}, patch prev=${JSON.stringify(actualPrev)}`);
+          return true;
+        }
+      }
+    }
+    return false;
+  }
+  /**
+   * 手动触发一次一致性检查。
+   * @returns true = 一致，false = 存在 drift
+   */
+  checkConsistency() {
+    if (!this.consistencyChecker) return true;
+    return this.consistencyChecker.check();
+  }
   /**
    * 销毁绑定，解除所有监听器
    * @param deep - 是否深度清理（包括 awareness/undoManager），默认 false
    */
   destroy(deep = false) {
-    var _a, _b;
+    var _a, _b, _c;
     this.mxGraphModel.removeListener("change", this.mxListener);
     this.doc.getMap(key$1).unobserveDeep(this.docObserver);
+    (_a = this.consistencyChecker) == null ? void 0 : _a.destroy();
     if (deep) {
-      (_a = this.cleanupCollaborator) == null ? void 0 : _a.call(this);
-      (_b = this.cleanupUndoManager) == null ? void 0 : _b.call(this);
+      (_b = this.cleanupCollaborator) == null ? void 0 : _b.call(this);
+      (_c = this.cleanupUndoManager) == null ? void 0 : _c.call(this);
     }
   }
   /**