y-mxgraph 0.1.1 → 0.1.3

package/README.md

@@ -29,6 +29,12 @@ import { Binding, LOCAL_ORIGIN } from 'y-mxgraph';
 const doc = new Y.Doc();
 
 App.main((app) => {
+  // 确保多端初始文件一致；draw.io 默认创建时 diagram id 是随机的，
+  // 若各客户端起点不同会导致协同异常。可用 generateFileTemplate 生成统一模板。
+  if (!app.currentFile.data) {
+    app.currentFile.data = Binding.generateFileTemplate('diagram-0');
+  }
+
   const binding = new Binding(app.currentFile, { doc });
 
   window.addEventListener('beforeunload', () => binding.destroy());
@@ -58,10 +64,19 @@ pnpm --filter y-mxgraph build
 pnpm --filter y-mxgraph test
 
 # Demo
+
+```bash
+# 单页模式（draw.io 直接加载在当前页面）
 pnpm --filter @y-mxgraph/demo dev
 
+# iframe 模式（父页运行 WebRTC Provider，两个 iframe 各跑一套 draw.io + y-mxgraph，通过 postMessage 同步）
+# 访问 http://localhost:5173/iframe-mode.html
+```
+
 # Docs
+
 pnpm --filter @y-mxgraph/docs dev
+
 ```
 
 ## License

package/README.zh-CN.md

@@ -29,6 +29,12 @@ import { Binding, LOCAL_ORIGIN } from 'y-mxgraph';
 const doc = new Y.Doc();
 
 App.main((app) => {
+  // 必须保证多端初始文件一致；draw.io 默认新建 diagram 时 id 是随机的，
+  // 若各客户端起点不同会导致协同异常。可用 generateFileTemplate 生成统一模板。
+  if (!app.currentFile.data) {
+    app.currentFile.data = Binding.generateFileTemplate('diagram-0');
+  }
+
   const binding = new Binding(app.currentFile, { doc });
 
   window.addEventListener('beforeunload', () => binding.destroy());

package/binding/index.d.ts

@@ -35,6 +35,22 @@ export declare class Binding {
      * @param deep - 是否深度清理（包括 awareness/undoManager），默认 false
      */
     destroy(deep?: boolean): void;
+    /**
+     * 生成标准化的 mxfile XML 模板，用于确保多端协同的数据起点一致。
+     *
+     * draw.io 每次新建 diagram 时默认生成随机 id（如 `DEMOabHTdChjKBf1yHdD`）。
+     * 如果各客户端初始化时的 diagram id 不同，Y.Doc 中的数据与本地 file.data 无法对齐，
+     * 会导致：
+     * - 后进房间的客户端出现「孤立 page」（来自本地 XML，未写入 Y.Doc）
+     * - patch 的 diff 无法正确匹配 diagram/cell id，协同失效
+     *
+     * 因此业务方应在初始化 draw.io 文件时，先用此方法生成统一起点的 XML，
+     * 再注入到 draw.io 的 currentFile 中（详见文档「接入注意事项」）。
+     *
+     * @param diagramId - diagram 的固定 id，默认 `diagram-0`
+     * @returns 最小化的 mxfile XML 字符串
+     */
+    static generateFileTemplate(diagramId?: string): string;
     /**
      * 静态工厂方法，创建 Binding 实例
      * 与 `new Binding()` 等价

package/binding/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/binding/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAOvD,OAAO,KAAK,EAAE,UAAU,EAAgB,MAAM,iBAAiB,CAAC;AAEhE,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC;IACX,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,WAAW,CAAC,EAAE,CAAC,CAAC,WAAW,CAAC;IAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,MAAM,CAAC,EACH,OAAO,GACP;QACE,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;CACP;AAED;;GAEG;AACH,qBAAa,OAAO;IAClB,wBAAwB;IACxB,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC;IACpB,6BAA6B;IAC7B,OAAO,CAAC,YAAY,CAAe;IACnC,sBAAsB;IACtB,OAAO,CAAC,kBAAkB,CAAS;IACnC,2BAA2B;IAC3B,OAAO,CAAC,UAAU,CAAa;IAC/B,oBAAoB;IACpB,OAAO,CAAC,WAAW,CAKT;IACV,gCAAgC;IAChC,OAAO,CAAC,mBAAmB,CAAC,CAAa;IACzC,yBAAyB;IACzB,OAAO,CAAC,kBAAkB,CAAC,CAAa;gBAE5B,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,qBAAqB;IAkF5D;;;OAGG;IACH,OAAO,CAAC,IAAI,UAAQ,GAAG,IAAI;IAS3B;;;OAGG;IACH,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,qBAAqB,GAAG,OAAO;CAGzE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/binding/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAOvD,OAAO,KAAK,EAAE,UAAU,EAAgB,MAAM,iBAAiB,CAAC;AAEhE,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC;IACX,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,WAAW,CAAC,EAAE,CAAC,CAAC,WAAW,CAAC;IAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,MAAM,CAAC,EACH,OAAO,GACP;QACE,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;CACP;AAED;;GAEG;AACH,qBAAa,OAAO;IAClB,wBAAwB;IACxB,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC;IACpB,6BAA6B;IAC7B,OAAO,CAAC,YAAY,CAAe;IACnC,sBAAsB;IACtB,OAAO,CAAC,kBAAkB,CAAS;IACnC,2BAA2B;IAC3B,OAAO,CAAC,UAAU,CAAa;IAC/B,oBAAoB;IACpB,OAAO,CAAC,WAAW,CAKT;IACV,gCAAgC;IAChC,OAAO,CAAC,mBAAmB,CAAC,CAAa;IACzC,yBAAyB;IACzB,OAAO,CAAC,kBAAkB,CAAC,CAAa;gBAE5B,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,qBAAqB;IAkF5D;;;OAGG;IACH,OAAO,CAAC,IAAI,UAAQ,GAAG,IAAI;IAS3B;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,oBAAoB,CAAC,SAAS,SAAc,GAAG,MAAM;IAa5D;;;OAGG;IACH,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,qBAAqB,GAAG,OAAO;CAGzE"}

package/package.json

@@ -1,7 +1,20 @@
 {
   "name": "y-mxgraph",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Yjs binding for draw.io (mxGraph) documents",
+  "keywords": [
+    "yjs",
+    "mxgraph",
+    "drawio",
+    "draw.io",
+    "crdt",
+    "collaboration",
+    "real-time",
+    "operational-transformation",
+    "diagram",
+    "graph",
+    "sync"
+  ],
   "type": "module",
   "main": "./y-mxgraph.cjs.js",
   "module": "./y-mxgraph.es.js",

package/y-mxgraph.cjs.js

@@ -1509,6 +1509,33 @@ class Binding {
       (_b = this.cleanupUndoManager) == null ? void 0 : _b.call(this);
     }
   }
+  /**
+   * 生成标准化的 mxfile XML 模板，用于确保多端协同的数据起点一致。
+   *
+   * draw.io 每次新建 diagram 时默认生成随机 id（如 `DEMOabHTdChjKBf1yHdD`）。
+   * 如果各客户端初始化时的 diagram id 不同，Y.Doc 中的数据与本地 file.data 无法对齐，
+   * 会导致：
+   * - 后进房间的客户端出现「孤立 page」（来自本地 XML，未写入 Y.Doc）
+   * - patch 的 diff 无法正确匹配 diagram/cell id，协同失效
+   *
+   * 因此业务方应在初始化 draw.io 文件时，先用此方法生成统一起点的 XML，
+   * 再注入到 draw.io 的 currentFile 中（详见文档「接入注意事项」）。
+   *
+   * @param diagramId - diagram 的固定 id，默认 `diagram-0`
+   * @returns 最小化的 mxfile XML 字符串
+   */
+  static generateFileTemplate(diagramId = "diagram-0") {
+    return `<mxfile pages="1">
+  <diagram id="${diagramId}">
+    <mxGraphModel>
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>`;
+  }
   /**
    * 静态工厂方法，创建 Binding 实例
    * 与 `new Binding()` 等价