dsh-drawai 0.1.0

package/lib/mxfile.js

@@ -0,0 +1,1661 @@
+/* 由 tools/build.mjs 生成 —— 请勿直接编辑；改 src/ 下的源文件。 */
+/**
+ * mxfile（`.drawio`）编解码 + **无损写回** —— **宿主半边**（要 node:zlib / node:crypto）。
+ *
+ * 载体决策（2026-09）：`.drawio` 就是唯一真相，不再有 `.dshd.json` 这种自定义格式。
+ * 于是这个文件从"导入/导出的转换器"升级成"读写器"，而**写**必须满足一条硬要求：
+ *
+ *   **只改我们拥有的单元，其余原文一个字节都不动。**
+ *
+ * 为什么：drawio 的画布能力比我们大（多页、图层、分组层级、图片、HTML 标签、
+ * UserObject 自定义属性、旋转翻转、页面设置…）。我们只理解其中一个子集 ——
+ * 如果写回是"按模型重新生成整份 XML"，那么用户稿子里我们不理解的部分会在保存时
+ * **被悄悄删掉**；而"悄悄"是最糟的失败方式（用户以为在编辑，其实在删）。
+ * 所以写回做成外科手术：
+ *   · 页 1 的 `<root>` 之外（其他页、mxfile 属性、空白）**逐字节保留**；
+ *   · 单元按 id 对应：我们导入过的（节点/边）只重写 `value`/`style`/几何/端点这几处属性，
+ *     连 `<object>` 包装上的自定义属性、`<mxRectangle as="alternateBounds">` 都原样留着；
+ *   · 我们没导入的单元（两端都找不到落点的边等）原样留着，不因为我们不认识就删；
+ *   · 只有"我们导入过、而模型里已经没有了"的单元才删 —— 那才是用户真的删了它；
+ *   · 原本压缩的页体，写回后仍然压缩（保持 drawio 的形态，也保住别处的字节）。
+ *
+ * 结果是一条可断言的性质：**打开后原样保存，文件逐字节不变**（见 check-mxfile）。
+ *
+ * 另外两件必须落在文件里的事（载体是唯一真相，没有第二个地方可存）：
+ *   · `meta.pinned`（人手工摆过版面，AI 别再自动重排）→ 一个隐藏的 `<object>` 元数据单元；
+ *   · `revision` → **不用存**，直接用文件内容的指纹（`contentHash`）。这样 drawio 或别的
+ *     编辑器改过文件，指纹自然就变了，乐观锁不会因为"属性被 drawio 丢掉"而假冲突。
+ *
+ * 格式依据（都在 drawio 仓库里核实过）：
+ *   · 压缩：`Graph.compress = pako.deflateRaw(encodeURIComponent(xml))` → `btoa`；
+ *     解压是逆过程（js/grapheditor/Graph.js 的 compress / decompress）。
+ *   · 结构：`<mxfile><diagram><mxGraphModel><root>`；页面设置挂在 `mxGraphModel` 的属性上。
+ *   · 单元：`<mxCell id/value/style/parent/source/target/vertex/edge>` + `<mxGeometry as="geometry">`。
+ *   · 用户对象：`<object label="…" id="…">` —— id/label 在外层，自定义属性也挂外层
+ *     （这正是 drawio 发明它来存任意属性的原因，所以我们的元数据也挂这种单元上）。
+ *   · 容器子单元的 `<mxGeometry>` 坐标是**相对父级**的（读要累加，写要减回去）。
+ */
+import { createHash } from 'node:crypto'
+import { deflateRawSync, inflateRawSync, inflateSync } from 'node:zlib'
+// style 的"真相"只有一份（内核）：这里只借它做**语义比较**，
+// 免得"文档层规范化过的 style 串"和"文件里原样的串"逐字不同，就把没动过的单元重写一遍。
+import { DEFAULT_EDGE_STYLE, formatStyle } from './style-kernel.js'
+
+/** 画布默认页尺寸（新建文件时写进 mxGraphModel，drawio 缺省与此一致：A4 竖版 × 100 dpi）。 */
+const PAGE_W = 850
+const PAGE_H = 1100
+
+/**
+ * 元数据单元的 id。它没有 `vertex`/`edge`，所以不会被当成图形单元；
+ * 挂在图层下（不是 root 下），所以也不会被误认成图层。
+ */
+export const META_ID = 'drawai-meta'
+
+// ---- 文本与属性小工具（mxfile 的属性/文本足够用，不引入 XML 依赖）-----------
+
+/** 解码 XML 实体（含数字实体）。*/
+function decodeEntities(text) {
+  return String(text)
+    .replace(/&#x([0-9a-fA-F]+);/g, (m, hex) => String.fromCodePoint(parseInt(hex, 16)))
+    .replace(/&#(\d+);/g, (m, dec) => String.fromCodePoint(parseInt(dec, 10)))
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, '&')
+}
+
+/** 属性值转义（写回用）。*/
+function escapeAttr(text) {
+  return String(text)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}
+
+/** 从一段"标签的属性区"里取一个属性的原值（未解码）。*/
+function rawAttr(attrs, name) {
+  const match = new RegExp('\\b' + name + '\\s*=\\s*"([^"]*)"').exec(attrs)
+  return match === null ? undefined : match[1]
+}
+
+/** 取一个属性并解码实体。*/
+function attr(attrs, name) {
+  const raw = rawAttr(attrs, name)
+  return raw === undefined ? undefined : decodeEntities(raw)
+}
+
+function num(value) {
+  const n = Number(value)
+  return Number.isFinite(n) ? n : undefined
+}
+
+/** 内容指纹：revision 就是它（不落盘、不依赖属性存活）。*/
+export function contentHash(text) {
+  return createHash('sha256').update(String(text === undefined || text === null ? '' : text), 'utf8').digest('hex').slice(0, 12)
+}
+
+/**
+ * 属性区解析：把一段属性拆成有序的 {name, leadStart, start, end, value}。
+ * 保留顺序与原始空白，才能做到"没改的属性一个字节都不动"。
+ */
+function parseAttrs(text, from, to) {
+  const out = []
+  const re = /([A-Za-z_:][-A-Za-z0-9_:.]*)\s*=\s*("([^"]*)"|'([^']*)')/g
+  re.lastIndex = from
+  let match
+  while ((match = re.exec(text)) !== null) {
+    if (match.index >= to) break
+    let lead = match.index
+    while (lead > from && /\s/.test(text.charAt(lead - 1))) lead -= 1
+    out.push({
+      name: match[1],
+      leadStart: lead,
+      start: match.index,
+      end: match.index + match[0].length,
+      value: match[3] !== undefined ? match[3] : match[4],
+    })
+  }
+  return out
+}
+
+/**
+ * 在一段属性区里批量覆盖/追加/删除属性。**值必须是已转义的**，`null` 表示删掉这个键。
+ *
+ * 为什么要"批量"：同一区域连续改两个属性时，第一个属性的长度变化会让第二个属性的
+ * 偏移失效 —— 实测过：`x="40"` 改成 `x="200"` 之后，`y` 被写进了标签中间，
+ * 整份文件当场花掉。所以这里一次解析、按偏移**从右往左**改。
+ */
+function setAttrsIn(text, attrsStart, attrsEnd, pairs) {
+  const list = parseAttrs(text, attrsStart, attrsEnd)
+  const byName = {}
+  for (const entry of list) byName[entry.name] = entry
+  const edits = []
+  const missing = []
+  for (const name of Object.keys(pairs)) {
+    const value = pairs[name]
+    const found = byName[name]
+    if (value === null) {
+      if (found !== undefined) edits.push({ start: found.leadStart, end: found.end, text: '' })
+      continue
+    }
+    const rendered = name + '="' + value + '"'
+    if (found !== undefined) edits.push({ start: found.start, end: found.end, text: rendered })
+    else missing.push(rendered)
+  }
+  edits.sort((a, b) => b.start - a.start)
+  let out = text
+  // 追加放在**原位**（所有替换点之后），这样先追加也不会影响替换点的偏移。
+  if (missing.length > 0) {
+    const body = text.slice(attrsStart, attrsEnd)
+    const trimmed = body.replace(/\s+$/, '')
+    const at = attrsStart + trimmed.length
+    out = out.slice(0, at) + ' ' + missing.join(' ') + out.slice(at)
+  }
+  for (const edit of edits) out = out.slice(0, edit.start) + edit.text + out.slice(edit.end)
+  return out
+}
+
+/**
+ * 在一个单元的原文上按区域批量改写。
+ *
+ * 两条规则缺一不可（都踩过）：
+ *   1. **同一个区域的多处改动要合成一次**：`value` 与 `style` 都在 `<mxCell …>` 的属性区里，
+ *      分两次改的话，第一次的长度变化会让第二次的偏移失效，标签会被写进属性中间；
+ *   2. 不同区域**从右往左**处理：左侧偏移不会因为右侧长度变化而失效。
+ */
+function withAttrChanges(text, changes) {
+  const merged = []
+  for (const change of changes) {
+    const same = merged.filter((m) => m.attrsStart === change.attrsStart && m.attrsEnd === change.attrsEnd)[0]
+    if (same === undefined) merged.push({ attrsStart: change.attrsStart, attrsEnd: change.attrsEnd, pairs: Object.assign({}, change.pairs) })
+    else Object.assign(same.pairs, change.pairs)
+  }
+  merged.sort((a, b) => b.attrsStart - a.attrsStart)
+  let out = text
+  for (const change of merged) out = setAttrsIn(out, change.attrsStart, change.attrsEnd, change.pairs)
+  return out
+}
+
+/** 从属性区里删掉一个属性（连它前面的空白一起删，免得留下双空格）。 */
+function removeAttrIn(text, attrsStart, attrsEnd, name) {
+  return setAttrsIn(text, attrsStart, attrsEnd, { [name]: null })
+}
+
+/** 取属性区里某个属性的原值（未解码），没有就 undefined。 */
+function attrIn(text, attrsStart, attrsEnd, name) {
+  const found = parseAttrs(text, attrsStart, attrsEnd).filter((a) => a.name === name)[0]
+  return found === undefined ? undefined : found.value
+}
+
+// ---- 标签文本 ---------------------------------------------------------------
+
+/**
+ * 把 drawio 的标签文本变成"纯文本标签"。
+ *
+ * 我们按纯文本渲染标签，而 drawio 的标签常带 HTML（`html=1` + `<br>`、`<b>`…）。
+ * 所以把 `<br>` 折成空格、去掉其余标签，再解实体 —— 读起来才是人写的那句话。
+ * 代价：改过标签的单元写回时 markup 回不去（如实记在 notes 里）。
+ */
+function labelFromValue(value) {
+  if (value === undefined || value === null) return ''
+  let text = String(value)
+  if (text.indexOf('<') < 0 && text.indexOf('&') < 0) return text
+  const hadMarkup = /<[a-zA-Z/][^>]*>/.test(text)
+  text = text.replace(/<br\s*\/?>/gi, ' ').replace(/<[^>]*>/g, '')
+  text = decodeEntities(text)
+  return hadMarkup ? text.replace(/\s+/g, ' ').trim() : text
+}
+
+/** 这个标签文本里是否含 markup（用于 notes）。*/
+function hasMarkup(value) {
+  return typeof value === 'string' && /<[a-zA-Z/][^>]*>/.test(value)
+}
+
+// ---- 页体：压缩 / 解压 ------------------------------------------------------
+
+/** 解压一段 `<diagram>` 内容：未压缩直接返回，压缩的按 drawio 的算法解。 */
+function decodeDiagramBody(body) {
+  const trimmed = String(body === undefined || body === null ? '' : body).trim()
+  if (trimmed.length === 0) return ''
+  if (trimmed.charAt(0) === '<') return trimmed
+  const buffer = Buffer.from(trimmed.replace(/\s+/g, ''), 'base64')
+  let xml
+  try {
+    xml = inflateRawSync(buffer).toString('utf8')
+  } catch (error) {
+    // 少数文件用的是带 zlib 头的 deflate；再试一次，仍失败就把原因抛给调用方。
+    xml = inflateSync(buffer).toString('utf8')
+  }
+  try {
+    return decodeURIComponent(xml)
+  } catch (error) {
+    return xml
+  }
+}
+
+/** 按 drawio 的算法压一段 mxGraphModel（`Graph.compress` 的等价物）。*/
+function compressModel(modelXml) {
+  return deflateRawSync(Buffer.from(encodeURIComponent(modelXml), 'utf8')).toString('base64')
+}
+
+// ---- 扫描单元（带文本跨度，供写回做定点手术）--------------------------------
+
+/**
+ * 扫描 `[from, to)` 范围内的单元，返回**带文本跨度**的记录。
+ *
+ * `start`/`end` 是相对整份文档的绝对偏移；每个单元内部的 `attrsSpan`/`geo`/`wrapper`
+ * 是**相对该单元起点**的偏移 —— 写回时先剪出单元原文，在它上面做定点替换，
+ * 就不必再关心全局偏移。
+ */
+function scanCells(source, from, to) {
+  const cells = []
+  const re = /<(object|UserObject|mxCell)\b([^>]*?)(\/>|>)/g
+  re.lastIndex = from
+  let match
+  while ((match = re.exec(source)) !== null) {
+    if (match.index >= to) break
+    const kind = match[1]
+    const absStart = match.index
+    const outerSelfClosing = match[3] === '/>'
+    const outerAttrsStart = match.index + 1 + kind.length
+    const outerAttrsEnd = match.index + match[0].length - (outerSelfClosing ? 2 : 1)
+    let absEnd
+    const blockFrom = outerAttrsEnd + (outerSelfClosing ? 2 : 1)
+    let blockTo = blockFrom
+    if (outerSelfClosing) {
+      absEnd = outerAttrsEnd + 2
+    } else {
+      const close = source.indexOf('</' + kind + '>', blockFrom)
+      blockTo = close < 0 ? to : close
+      absEnd = close < 0 ? to : close + kind.length + 3
+    }
+
+    // 用户对象（<object>）：id/label/自定义属性在外层，里面才是 mxCell。
+    let attrsStart = outerAttrsStart
+    let attrsEnd = outerAttrsEnd
+    let cellSelfClosing = outerSelfClosing
+    let innerFrom = blockFrom
+    let innerTo = blockTo
+    let wrapper = null
+    let wrapperAttrs = null
+    if (kind !== 'mxCell') {
+      wrapperAttrs = source.slice(outerAttrsStart, outerAttrsEnd)
+      const inner = /<mxCell\b([^>]*?)(\/>|>)/.exec(source.slice(blockFrom, blockTo))
+      if (inner !== null) {
+        const innerStart = blockFrom + inner.index
+        const innerSelf = inner[2] === '/>'
+        attrsStart = innerStart + '<mxCell'.length
+        attrsEnd = innerStart + inner[0].length - (innerSelf ? 2 : 1)
+        cellSelfClosing = innerSelf
+        innerFrom = attrsEnd + (innerSelf ? 2 : 1)
+        if (innerSelf) {
+          innerTo = innerFrom
+        } else {
+          const innerClose = source.indexOf('</mxCell>', innerFrom)
+          innerTo = innerClose < 0 ? blockTo : innerClose
+        }
+      }
+      wrapper = {
+        attrsStart: outerAttrsStart - absStart,
+        attrsEnd: outerAttrsEnd - absStart,
+      }
+    }
+
+    // 几何（在单元内容区里找）
+    let geometry = null
+    let geo = null
+    const content = source.slice(innerFrom, innerTo)
+    const geoMatch = /<mxGeometry\b([^>]*?)(\/>|>)/.exec(content)
+    if (geoMatch !== null) {
+      const geoAbsStart = innerFrom + geoMatch.index
+      const geoSelf = geoMatch[2] === '/>'
+      const geoAttrsStart = geoAbsStart + '<mxGeometry'.length
+      const geoAttrsEnd = innerFrom + geoMatch.index + geoMatch[0].length - (geoSelf ? 2 : 1)
+      const geoInnerFrom = geoAttrsEnd + (geoSelf ? 2 : 1)
+      let geoInnerTo = geoInnerFrom
+      let geoAbsEnd = geoAttrsEnd + 2
+      if (!geoSelf) {
+        const geoClose = source.indexOf('</mxGeometry>', geoInnerFrom)
+        geoInnerTo = geoClose < 0 ? innerTo : geoClose
+        geoAbsEnd = geoClose < 0 ? innerTo : geoClose + '</mxGeometry>'.length
+      }
+      const geoAttrsText = source.slice(geoAttrsStart, geoAttrsEnd)
+      const geoInnerText = source.slice(geoInnerFrom, geoInnerTo)
+
+      const points = []
+      const arrayMatch = /<Array\b[^>]*as\s*=\s*"points"[^>]*>([\s\S]*?)<\/Array>/.exec(geoInnerText)
+      if (arrayMatch !== null) {
+        const pointRe = /<mxPoint\b([^>]*?)\/>/g
+        let pm
+        while ((pm = pointRe.exec(arrayMatch[1])) !== null) {
+          const x = num(attr(pm[1], 'x'))
+          const y = num(attr(pm[1], 'y'))
+          if (x !== undefined && y !== undefined) points.push({ x: x, y: y })
+        }
+      }
+      const terminal = (name) => {
+        const re2 = new RegExp('<mxPoint\\b([^>]*?)as\\s*=\\s*"' + name + '"[^>]*?/>')
+        const found = re2.exec(geoInnerText)
+        if (found === null) return null
+        const x = num(attr(found[1], 'x'))
+        const y = num(attr(found[1], 'y'))
+        return x === undefined || y === undefined ? null : { x: x, y: y }
+      }
+      // `<mxPoint as="offset"/>`：drawio 存"标签相对于那个点的残余偏移"用的。
+      // 没有 x/y 属性时按 (0,0) 处理。
+      const offsetMatch = /<mxPoint\b([^>]*?)as\s*=\s*"offset"[^>]*?\/>/.exec(geoInnerText)
+      const offset =
+        offsetMatch === null
+          ? { x: 0, y: 0 }
+          : { x: num(attr(offsetMatch[1], 'x')) === undefined ? 0 : num(attr(offsetMatch[1], 'x')), y: num(attr(offsetMatch[1], 'y')) === undefined ? 0 : num(attr(offsetMatch[1], 'y')) }
+      geometry = {
+        x: num(attr(geoAttrsText, 'x')),
+        y: num(attr(geoAttrsText, 'y')),
+        width: num(attr(geoAttrsText, 'width')),
+        height: num(attr(geoAttrsText, 'height')),
+        relative: attr(geoAttrsText, 'relative') === '1',
+        points: points,
+        sourcePoint: terminal('sourcePoint'),
+        targetPoint: terminal('targetPoint'),
+        offset: offset,
+      }
+      geo = {
+        attrsStart: geoAttrsStart - absStart,
+        attrsEnd: geoAttrsEnd - absStart,
+        selfClosing: geoSelf,
+        start: geoAbsStart - absStart,
+        end: geoAbsEnd - absStart,
+        innerFrom: geoInnerFrom - absStart,
+        innerTo: geoInnerTo - absStart,
+        innerText: geoInnerText,
+      }
+    }
+
+    const cellAttrsText = source.slice(attrsStart, attrsEnd)
+    // `<object>`/`<UserObject>` 包装的单元：内层 mxCell **不带 id**，id 在外层。
+    // 漏了这条回退的后果实测过：已有的元数据单元被当成"不存在"，于是每次保存都再追加一个，
+    // 文件里躺一串重复的 drawai-meta。
+    const innerId = attr(cellAttrsText, 'id')
+    const cellId = innerId === undefined && wrapperAttrs !== null ? attr(wrapperAttrs, 'id') : innerId
+    // 包装上的**自定义属性**（除了 id/label）就是 drawio 的"编辑数据"。
+    const data = {}
+    if (wrapperAttrs !== null) {
+      for (const entry of parseAttrs(wrapperAttrs, 0, wrapperAttrs.length)) {
+        if (entry.name === 'id' || entry.name === 'label') continue
+        data[entry.name] = decodeEntities(entry.value)
+      }
+    }
+    cells.push({
+      element: kind,
+      id: cellId,
+      label: wrapperAttrs !== null && attr(wrapperAttrs, 'label') !== undefined ? attr(wrapperAttrs, 'label') : attr(cellAttrsText, 'value'),
+      data: data,
+      style: rawAttr(cellAttrsText, 'style') === undefined ? '' : decodeEntities(rawAttr(cellAttrsText, 'style')),
+      parent: attr(cellAttrsText, 'parent'),
+      // 图层的两个状态位（drawio 就写在图层单元上）：`visible="0"` = 隐藏、`locked="1"` = 锁定。
+      visible: attr(cellAttrsText, 'visible'),
+      locked: attr(cellAttrsText, 'locked'),
+      source: attr(cellAttrsText, 'source'),
+      target: attr(cellAttrsText, 'target'),
+      vertex: attr(cellAttrsText, 'vertex') === '1',
+      edge: attr(cellAttrsText, 'edge') === '1',
+      // drawio 的**边标签单元**：它是个 vertex，但既不是形状也不是容器 ——
+      // 样式里带 `edgeLabel`，几何是 `relative="1"`（相对它所属的连线/父级定位）。
+      // 当成普通节点读进来会出两件坏事：画布上多一个鬼影框（实测：用户那份 drawio 文件里
+      // 就有一个 `value="Text"` 的 edgeLabel 单元，在画布上显示成一个写着 Text 的蓝框）；
+      // 一旦被拖动，写回会把**绝对坐标**写进一个"相对"几何里，把 drawio 里的标签偏移弄歪。
+      // 所以这类单元一律**不导入、不拥有、原样保留**（见 ownershipOf）。
+      labelCell:
+        (geometry !== null && geometry.relative === true) || /(^|;)edgeLabel[;=]/.test(rawAttr(cellAttrsText, 'style') === undefined ? '' : rawAttr(cellAttrsText, 'style')),
+      geometry: geometry,
+      // 文本跨度
+      start: absStart,
+      end: absEnd,
+      attrsSpan: { attrsStart: attrsStart - absStart, attrsEnd: attrsEnd - absStart, selfClosing: cellSelfClosing },
+      wrapper: wrapper,
+      wrapperAttrs: wrapperAttrs,
+      geo: geo,
+    })
+    re.lastIndex = absEnd
+  }
+  return cells
+}
+
+// ---- 分析：定位页 1、解出 mxGraphModel、拿到全部单元与文本跨度 ----------------
+
+/**
+ * 全文分析。**解析与写回共用同一份结构** —— 两边对"哪些单元属于我们"必须完全一致，
+ * 否则写回会把我们不认识的单元当成"用户删掉的"删掉。
+ */
+function analyzeMxfile(source) {
+  const diagrams = [...source.matchAll(/<diagram\b([^>]*?)(\/>|>)([\s\S]*?)(?:<\/diagram>|$)/g)]
+  if (diagrams.length === 0) throw new Error('这不是 mxfile：找不到 <diagram> 元素')
+  const first = diagrams[0]
+  const closed = first[0].endsWith('</diagram>')
+  const bodyEnd = first.index + first[0].length - (closed ? '</diagram>'.length : 0)
+  const bodyStart = bodyEnd - first[3].length
+  // 页体的**核心**（去掉两侧空白）：写回时只替换这一段，
+  // 否则 trim 过的 XML 会把原文里的换行/缩进一起吃掉（实测过：整份文件被压成一行）。
+  const lead = /^\s*/.exec(first[3])[0]
+  const trail = /\s*$/.exec(first[3])[0]
+  const coreStart = bodyStart + lead.length
+  const coreEnd = bodyEnd - trail.length
+  const core = first[3].slice(lead.length, first[3].length - trail.length)
+  const compressed = core.charAt(0) !== '<'
+  const modelXml = decodeDiagramBody(core)
+  const modelMatch = /<mxGraphModel\b([^>]*?)(\/>|>)/.exec(modelXml)
+  if (modelMatch === null) throw new Error('这个 <diagram> 里没有 <mxGraphModel>')
+  const rootStart = modelXml.indexOf('<root>')
+  const rootEnd = modelXml.indexOf('</root>')
+  if (rootStart < 0 || rootEnd < rootStart) throw new Error('mxGraphModel 里没有 <root>')
+  const innerFrom = rootStart + '<root>'.length
+  const innerTo = rootEnd
+  const cells = scanCells(modelXml, innerFrom, innerTo)
+
+  const byId = new Map()
+  for (const cell of cells) if (typeof cell.id === 'string') byId.set(cell.id, cell)
+  const rootCell = cells.find((c) => c.parent === undefined || c.parent === null || c.parent === '')
+  const rootId = rootCell === undefined ? undefined : rootCell.id
+  // 图层：挂在 root 下、既不是顶点也不是边、也没有几何的单元。
+  // 元数据单元挂在图层下（parent 是图层而不是 root），所以不会被误判成图层。
+  const isLayer = (cell) =>
+    cell.id !== META_ID && cell.parent === rootId && cell.vertex !== true && cell.edge !== true && cell.geometry === null
+  const layerCells = cells.filter(isLayer)
+  const layerIds = new Set(layerCells.map((c) => c.id))
+  const layerOrder = layerCells.map((c) => c.id)
+  // 图层的三个属性就是 drawio 的写法：`value` = 名字、`visible="0"` = 隐藏、`locked="1"` = 锁定。
+  // 缺省（不写属性）就是"名字为空 / 可见 / 未锁"。属性在 scanCells 里已经读好了。
+  const layers = layerCells.map((cell) => ({
+    id: String(cell.id),
+    name: typeof cell.label === 'string' ? decodeEntities(cell.label) : '',
+    visible: cell.visible !== '0',
+    locked: cell.locked === '1',
+  }))
+
+  return {
+    source: source,
+    pageCount: diagrams.length,
+    // 纸张尺寸（drawio 挂在 `mxGraphModel` 上的属性）：AI 做布局/导出建议时要看它 ——
+    // 850×1100 是 drawio 的 A4 竖版缺省，但不代表用户这份文件就是那个尺寸。
+    pageSize: readPageSize(modelXml),
+    bodyStart: coreStart,
+    bodyEnd: coreEnd,
+    compressed: compressed,
+    modelXml: modelXml,
+    rootStart: rootStart,
+    rootEnd: rootEnd,
+    innerFrom: innerFrom,
+    innerTo: innerTo,
+    cells: cells,
+    byId: byId,
+    rootId: rootId,
+    layerIds: layerIds,
+    layerOrder: layerOrder,
+    layers: layers,
+    isLayer: isLayer,
+  }
+}
+
+/**
+ * 从 `<mxGraphModel>` 的属性里读出纸张尺寸（`pageWidth`/`pageHeight`）。
+ *
+ * 读不出来（没写 / 不是数）就返回 null —— 那是"这份文件没说"，不是 850×1100；
+ * 由调用方决定要不要退回缺省（画布新建时用的就是 drawio 的 A4 竖版缺省）。
+ */
+function readPageSize(modelXml) {
+  const w = Number(rawAttr(modelXml, 'pageWidth'))
+  const h = Number(rawAttr(modelXml, 'pageHeight'))
+  if (Number.isFinite(w) === false || Number.isFinite(h) === false || w <= 0 || h <= 0) return null
+  return { w: w, h: h }
+}
+
+/**
+ * "哪些单元归我们管" —— 读与写必须用**同一套判据**。
+ * 顶点：所有非 root、非图层、非边标签的顶点（含容器与图片形状）。
+ * 边：两端至少各有一个真实落点或自由点（与 drawio 一致；两端都落空的边我们不认识，原样留着）。
+ *
+ * `labelCell`（drawio 的边标签单元）**一律不拥有** —— 不拥有才不会在"模型里没有它"时被当成
+ * 用户删除而抹掉（那是真正的数据丢失），也不会把绝对坐标写进它的相对几何里。
+ */
+function ownershipOf(info) {
+  const nodeIds = new Set()
+  const owned = new Set()
+  for (const cell of info.cells) {
+    if (cell.vertex !== true) continue
+    if (cell.id === info.rootId || info.layerIds.has(cell.id) || cell.id === META_ID) continue
+    if (cell.labelCell === true) continue
+    if (typeof cell.id === 'string') {
+      nodeIds.add(cell.id)
+      owned.add(cell.id)
+    }
+  }
+  for (const cell of info.cells) {
+    if (cell.edge !== true) continue
+    const geo = cell.geometry
+    const hasSource = typeof cell.source === 'string' && nodeIds.has(cell.source)
+    const hasTarget = typeof cell.target === 'string' && nodeIds.has(cell.target)
+    const freeSource = geo !== null && geo.sourcePoint !== null && geo.sourcePoint !== undefined
+    const freeTarget = geo !== null && geo.targetPoint !== null && geo.targetPoint !== undefined
+    if (!hasSource && !freeSource) continue
+    if (!hasTarget && !freeTarget) continue
+    if (typeof cell.id === 'string') owned.add(cell.id)
+  }
+  return { owned: owned, nodeIds: nodeIds }
+}
+
+/** 父链的偏移量之和（不包含自己）：容器子单元的坐标是相对父级的。**读**用这个。 */
+function parentOffsetOf(info, cell) {
+  let x = 0
+  let y = 0
+  let parentId = cell.parent
+  const seen = new Set()
+  while (typeof parentId === 'string' && seen.has(parentId) === false) {
+    seen.add(parentId)
+    const parent = info.byId.get(parentId)
+    if (parent === undefined || info.layerIds.has(parent.id) || parent.id === info.rootId) break
+    x += parent.geometry !== null && parent.geometry.x !== undefined ? parent.geometry.x : 0
+    y += parent.geometry !== null && parent.geometry.y !== undefined ? parent.geometry.y : 0
+    parentId = parent.parent
+  }
+  return { x: x, y: y }
+}
+
+/**
+ * 从某个单元出发，沿**文件里**的父链找它属于哪一层（读时的 `layerOf` 是同一个意思）。
+ * 写回时用来判断"模型要求的层"和"文件里这一支的层"是不是同一层。
+ */
+function layerOfParent(info, cellOrId) {
+  const first = typeof cellOrId === 'string' ? cellOrId : cellOrId === null || cellOrId === undefined ? undefined : cellOrId.id
+  let parentId = first
+  const seen = new Set()
+  while (typeof parentId === 'string' && seen.has(parentId) === false) {
+    seen.add(parentId)
+    if (info.layerIds.has(parentId)) return parentId
+    if (parentId === info.rootId) return null
+    const cell = info.byId.get(parentId)
+    if (cell === undefined) return null
+    parentId = cell.parent
+  }
+  return null
+}
+
+/**
+ * **写**回时，某个单元的"新父级 + 新父链偏移"。
+ *
+ * 与读时的 `parentOffsetOf` 有两处关键差别：
+ *   1. 画布是这次保存的真相 —— 父级自己可能也被移动了，子单元的相对坐标要按**新**的
+ *      父级位置反算（不然用户看到的画面和文件里存的对不上）；
+ *   2. 父级可能**被删了**：那就往上接到最近一个还活着的祖先，并把被删祖先的那段偏移补回去。
+ *      漏了这条，文件里会留下指向不存在单元的 `parent`（drawio 打开会丢层级）。
+ *
+ * 第三条是图层（`wantLayer`）：模型把单元放到了**另一个层**时，必须改 `parent` ——
+ * 这是"移到别的层"唯一能生效的地方（不改的话文件里它还挂在老层上，读回来 layer 照旧是老的）。
+ * 只认**已知的**层 id：不存在的层会写出悬空 parent，drawio 打开会丢层级。
+ * 注意"容器里的单元"这一支要照旧保住：模型里的 `layer` 对容器子单元来说只是"它属于哪一层"
+ * （读时沿父链得到的），并不表示它该脱离容器 —— 所以只有**层变了**才换父级。
+ *
+ * 返回的 offset 是"沿父链累加的相对坐标总量"，于是写入值 = 绝对坐标 − offset。
+ */
+function writeChainOf(info, modelAbs, deletedIds, cell, wantLayer, knownLayers) {
+  // ① 先按文件里的父链算出"本来要写到哪个父级、偏移多少"（容器层级靠这一步保住）。
+  let parentId = cell.parent
+  let offset = { x: 0, y: 0 }
+  const seen = new Set()
+  while (typeof parentId === 'string' && seen.has(parentId) === false) {
+    seen.add(parentId)
+    if (info.layerIds.has(parentId) || parentId === info.rootId) break
+    const abs = modelAbs.get(parentId)
+    // 活下来的祖先：它的相对坐标已经按"绝对 − 它自己的父链"写过，所以整条链的偏移就等于它的绝对坐标。
+    if (abs !== undefined) {
+      offset = abs
+      break
+    }
+    const parent = info.byId.get(parentId)
+    if (parent === undefined) {
+      parentId = layerOrRoot(info)
+      offset = { x: 0, y: 0 }
+      break
+    }
+    parentId = parent.parent
+  }
+  if (typeof parentId !== 'string') {
+    parentId = layerOrRoot(info)
+    offset = { x: 0, y: 0 }
+  }
+  // ② 模型显式要求的层与文件这一支的层不一致 → 换父级（单元被显式移层时它离开原容器）。
+  const want = typeof wantLayer === 'string' && wantLayer.length > 0 && knownLayers.has(wantLayer) ? wantLayer : null
+  if (want !== null && layerOfParent(info, parentId) !== want) return { parentId: want, offset: { x: 0, y: 0 } }
+  return { parentId: parentId, offset: offset }
+}
+
+function layerOrRoot(info) {
+  return info.layerOrder.length > 0 ? info.layerOrder[0] : info.rootId
+}
+
+/**
+ * 一个单元属于哪个图层：沿 parent 往上找**第一个图层**。
+ *
+ * 挂在边上的边标签单元 parent 是那条边，所以它会拿到边所在的那一层 ——
+ * 于是"隐藏某一层"能把那一层里的标签一起藏掉（否则会剩下一堆孤零零的字）。
+ *
+ * @returns 图层 id，或 null（走到 root 也没找到，理论上不该发生）
+ */
+function layerIdOf(info, cell) {
+  let parentId = cell === null || cell === undefined ? undefined : cell.parent
+  const seen = new Set()
+  while (typeof parentId === 'string' && seen.has(parentId) === false) {
+    seen.add(parentId)
+    if (info.layerIds.has(parentId)) return parentId
+    if (parentId === info.rootId) return null
+    const parent = info.byId.get(parentId)
+    if (parent === undefined) return null
+    parentId = parent.parent
+  }
+  return null
+}
+
+// ---- 解析 → 语义文档 -------------------------------------------------------
+
+/**
+ * 文件里那条边几何上的**标签位置**（drawio 的 `mxGeometry x/y` + `<mxPoint as="offset">`）。
+ *
+ * 只有 `relative="1"` 是这个语义：`x` 是沿边比例（-1..1，0 = 中点）、`y` 是垂直偏移 px、
+ * `offset` 是"取整后剩下的零头"。非 relative 的那一支是另一套算法（相对两端连线的中点），
+ * 我们**不认**这种位置 —— 返回 null 表示"这块不归我们动"，写回时原样保留。
+ *
+ * `present`：文件里到底写没写 x/y。没有（= 从没拖过，就是中点）与"拖回过中点"在语义上一样，
+ * 但字节上不同，所以写回时要能区分。
+ */
+function relativeLabelPos(geo) {
+  if (geo === null || geo === undefined || geo.relative !== true) return null
+  const x = Number(geo.x)
+  const y = Number(geo.y)
+  const off = geo.offset === null || geo.offset === undefined ? null : geo.offset
+  const offsetX = off === null ? 0 : Number(off.x) === Number(off.x) ? Number(off.x) : 0
+  const offsetY = off === null ? 0 : Number(off.y) === Number(off.y) ? Number(off.y) : 0
+  if (Number.isFinite(x) === false || Number.isFinite(y) === false) {
+    return { x: 0, y: 0, offsetX: offsetX, offsetY: offsetY, present: false }
+  }
+  return { x: x, y: y, offsetX: offsetX, offsetY: offsetY, present: true }
+}
+
+/** 模型里那条边声明的标签位置；没声明（从没拖过）返回 null = 用弧长中点。 */
+function modelLabelPos(edge) {
+  const x = Number(edge.labelX)
+  const y = Number(edge.labelY)
+  if (Number.isFinite(x) === false || Number.isFinite(y) === false) return null
+  const offsetX = Number(edge.labelOffsetX)
+  const offsetY = Number(edge.labelOffsetY)
+  return { x: x, y: y, offsetX: Number.isFinite(offsetX) ? offsetX : 0, offsetY: Number.isFinite(offsetY) ? offsetY : 0 }
+}
+
+/** 位置要不要动：模型里有就按模型写；模型里没有但文件里有（用户把它归中了）就删掉。 */
+function labelPosChanged(filePos, wantPos) {
+  if (filePos === null) return false
+  if (wantPos === null) return filePos.present === true
+  if (filePos.present === false) return true
+  return wantPos.x !== filePos.x || wantPos.y !== filePos.y || wantPos.offsetX !== filePos.offsetX || wantPos.offsetY !== filePos.offsetY
+}
+
+/** `<mxPoint as="offset">` 的值：偏移为 0 就不写这个元素（drawio 缺省也是 0）。 */
+function labelOffsetPoint(pos) {
+  if (pos === null) return null
+  if (pos.offsetX === 0 && pos.offsetY === 0) return null
+  return { x: pos.offsetX, y: pos.offsetY }
+}
+
+/**
+ * 解析 mxfile 文本 → 语义文档。
+ *
+ * @param text `.drawio` 全文
+ * @param options.existing 可选的现有文档（用来保住 meta.pinned）
+ * @returns { doc, notes, pageCount } —— notes 是给人看的损失说明（多页、分组…）
+ */
+export function parseMxfile(text, options) {
+  const notes = []
+  let source = String(text === undefined || text === null ? '' : text)
+  // 有的编辑器（记事本、某些 IDE 插件）会给 UTF-8 文件加 BOM。摘掉它更省心 ——
+  // 虽然"按内容找 <diagram>"本来就不受影响，但留着它会让文件首字符变成 U+FEFF。
+  if (source.charCodeAt(0) === 0xfeff) source = source.slice(1)
+  // UTF-16（记事本的"Unicode"）被当 UTF-8 读进来时，ASCII 之间全是空字符。
+  // 这种情况**不猜**：硬按 UTF-16 重解释，中日韩标签会变成乱码，而乱码是看不见的损失。
+  // 宁可报一句用户马上能照做的错。
+  if (source.indexOf('\u0000') >= 0) {
+    throw new Error('这个文件像是 UTF-16 编码（读进来时每两个字节夹着一个空字符）：请用 UTF-8 另存后再打开')
+  }
+  if (source.trim().length === 0) throw new Error('.drawio 文件是空的')
+
+  const info = analyzeMxfile(source)
+  const owned = ownershipOf(info)
+  const nodeIds = owned.nodeIds
+  const pageCount = info.pageCount
+
+  if (info.layerIds.size > 1) {
+    notes.push('这个文件有 ' + info.layerIds.size + ' 个图层：画布按「图层」菜单里的显示/隐藏来画；保存时图层结构照旧保留')
+  }
+
+  const nodes = []
+  let containers = 0
+  let imageShapes = 0
+  let markupLabels = 0
+  let labelCells = 0
+  for (const cell of info.cells) {
+    if (cell.vertex === true && cell.labelCell === true) labelCells += 1
+    if (cell.vertex !== true || owned.owned.has(String(cell.id)) === false) continue
+    const isContainer = info.cells.some((c) => c.parent === cell.id && c !== cell)
+    if (isContainer) containers += 1
+    if (typeof cell.style === 'string' && /(^|;)image[;=]/.test(cell.style)) imageShapes += 1
+    if (hasMarkup(cell.label)) markupLabels += 1
+    const offset = parentOffsetOf(info, cell)
+    const geo = cell.geometry
+    const node = {
+      id: String(cell.id),
+      label: labelFromValue(cell.label),
+      style: cell.style === undefined ? '' : String(cell.style),
+      x: (geo !== null && geo.x !== undefined ? geo.x : 0) + offset.x,
+      y: (geo !== null && geo.y !== undefined ? geo.y : 0) + offset.y,
+      w: geo !== null && geo.width !== undefined ? geo.width : 120,
+      h: geo !== null && geo.height !== undefined ? geo.height : 60,
+    }
+    if (cell.data !== undefined && cell.data !== null && Object.keys(cell.data).length > 0) node.data = cell.data
+    // 属于哪个图层（沿 parent 往上找第一个图层）：渲染时隐藏层要整层不画。
+    const layerId = layerIdOf(info, cell)
+    if (layerId !== null) node.layer = layerId
+    // **容器父级**：父级不是图层/root 的，说明它挂在某个容器（或别的单元）里。
+    //
+    // 为什么要报出来：画布按**绝对位置**显示（层级在文件里保留），于是"移动容器"在画布上
+    // 并不会带走子单元，删除容器则会把子单元接到还活着的祖先上 —— AI 不知道这层关系时，
+    // 这两件事都是"看起来对、其实把组弄坏了"。给一个 parent 字段，它至少能看见
+    // "这个单元在哪个容器里"，要一起动就把它们一起写进 move/duplicate 的 ids。
+    // 注意它只是**只读信息**：写回时父级由文件里的父链 + layer 决定（新单元一律挂在层下，
+    // 不往容器里塞 —— 那需要写相对坐标，而新单元写的是绝对坐标）。
+    if (typeof cell.parent === 'string' && cell.parent !== layerId && info.layerIds.has(cell.parent) === false && cell.parent !== info.rootId) {
+      node.parent = String(cell.parent)
+    }
+    nodes.push(node)
+  }
+
+  const edges = []
+  let dangling = 0
+  let kept = 0
+  for (const cell of info.cells) {
+    if (cell.edge !== true) continue
+    if (owned.owned.has(String(cell.id)) === false) {
+      kept += 1
+      continue
+    }
+    const geo = cell.geometry === null ? {} : cell.geometry
+    const hasSource = typeof cell.source === 'string' && nodeIds.has(cell.source)
+    const hasTarget = typeof cell.target === 'string' && nodeIds.has(cell.target)
+    const freeSource = geo.sourcePoint === undefined || geo.sourcePoint === null ? null : geo.sourcePoint
+    const freeTarget = geo.targetPoint === undefined || geo.targetPoint === null ? null : geo.targetPoint
+    if (!hasSource || !hasTarget) dangling += 1
+    const edge = { id: String(cell.id), style: cell.style === undefined || cell.style === '' ? '' : String(cell.style) }
+    if (hasSource) edge.from = cell.source
+    if (hasTarget) edge.to = cell.target
+    if (!hasSource && freeSource !== null) edge.sourcePoint = freeSource
+    if (!hasTarget && freeTarget !== null) edge.targetPoint = freeTarget
+    const label = labelFromValue(cell.label)
+    if (label.length > 0) edge.label = label
+    if (cell.data !== undefined && cell.data !== null && Object.keys(cell.data).length > 0) edge.data = cell.data
+    if (hasMarkup(cell.label)) markupLabels += 1
+    const points = geo.points === undefined ? [] : geo.points
+    if (points.length > 0) edge.points = points
+    // drawio 把"拖过的边标签位置"也存在**边自己的 mxGeometry** 上（`mxEdgeHandler.moveLabel`）：
+    //   x = 沿边比例（-1..1，0 = 中点）、y = 垂直偏移 px、offset = 残余偏移 px（取整后剩下的零头）。
+    // 只有 `relative="1"` 是这个语义（非 relative 的那支是"相对两端连线的中点"，另一套算法），
+    // 所以只认 relative，其余一律原样留在文件里、不当成位置。
+    const labelPos = relativeLabelPos(geo)
+    if (labelPos !== null && labelPos.present === true) {
+      edge.labelX = labelPos.x
+      edge.labelY = labelPos.y
+      if (labelPos.offsetX !== 0 || labelPos.offsetY !== 0) {
+        edge.labelOffsetX = labelPos.offsetX
+        edge.labelOffsetY = labelPos.offsetY
+      }
+    }
+    const edgeLayer = layerIdOf(info, cell)
+    if (edgeLayer !== null) edge.layer = edgeLayer
+    edges.push(edge)
+  }
+
+  if (pageCount > 1) notes.push('这个文件有 ' + pageCount + ' 页，画布只显示/编辑第 1 页（其余页保存时原样保留）')
+  if (containers > 0) notes.push(containers + ' 个分组/容器：画布按绝对位置显示，文件里的父子层级照旧保留')
+  if (imageShapes > 0) notes.push(imageShapes + ' 个图片/自定义形状按矩形显示（本画布不画图片，单元原样保留）')
+  if (markupLabels > 0) notes.push(markupLabels + ' 个 HTML 标签按纯文本显示（改标签会写成纯文本）')
+  if (dangling > 0) notes.push(dangling + ' 条边是悬空端（用 sourcePoint/targetPoint 保留）')
+  if (kept > 0) notes.push(kept + ' 条边的两端都找不到落点：不显示，但原样保留在文件里')
+
+  // drawio 的**独立边标签单元**：按它自己的几何画出来（只读 —— 画布不改它们，保存原样带回）。
+  // 位置语义与 `mxGraphView.getPoint` 一致：挂在边上的（parent 是那条边）用
+  // x = 沿边比例（0 中点、±1 两端）、y = 垂直偏移、offset = 残余偏移；
+  // 没挂在边上的（例如从别处粘过来、parent 是图层）就按它的绝对坐标显示。
+  const labels = []
+  for (const cell of info.cells) {
+    if (cell.vertex !== true || cell.labelCell !== true) continue
+    const parentCell = typeof cell.parent === 'string' ? info.byId.get(cell.parent) : undefined
+    const onEdge = parentCell !== undefined && parentCell.edge === true
+    const geo = cell.geometry === null ? {} : cell.geometry
+    const offset = geo.offset === undefined || geo.offset === null ? { x: 0, y: 0 } : geo.offset
+    const labelItem = {
+      id: String(cell.id),
+      text: labelFromValue(cell.label),
+      edgeId: onEdge ? String(cell.parent) : null,
+      x: geo.x === undefined ? 0 : geo.x,
+      y: geo.y === undefined ? 0 : geo.y,
+      offsetX: offset.x,
+      offsetY: offset.y,
+      relative: geo.relative === true,
+      style: cell.style === undefined ? '' : String(cell.style),
+    }
+    // 挂在边上的：它的层就是那条边的层（parent 是边，不是图层）。
+    const labelLayer = layerIdOf(info, cell)
+    if (labelLayer !== null) labelItem.layer = labelLayer
+    labels.push(labelItem)
+  }
+  if (labels.length > 0) {
+    const onEdges = labels.filter((l) => l.edgeId !== null).length
+    notes.push(
+      labels.length + ' 个边标签单元（drawio 的 edgeLabel）按原样显示（只读，保存时原样保留）' +
+        (onEdges < labels.length ? '：其中 ' + (labels.length - onEdges) + ' 个没挂在任何边上，按它自己的坐标显示' : ''),
+    )
+  }
+
+  const existing = options !== undefined && options.existing !== undefined && options.existing !== null ? options.existing : null
+  const metaCell = info.byId.get(META_ID)
+  const metaAttrs =
+    metaCell === undefined
+      ? undefined
+      : metaCell.wrapperAttrs !== null
+        ? metaCell.wrapperAttrs
+        : info.modelXml.slice(metaCell.start + metaCell.attrsSpan.attrsStart, metaCell.start + metaCell.attrsSpan.attrsEnd)
+  const pinned = metaCell !== undefined && attr(metaAttrs, 'drawaiPinned') === '1'
+  const doc = {
+    version: 2,
+    revision: contentHash(source),
+    meta: { pinned: pinned === true },
+    nodes: nodes,
+    edges: edges,
+    labels: labels,
+    // 图层（drawio 的写法：挂在 root 下、没有 vertex/edge 的单元）：
+    // id + 名字 + 显示/隐藏 + 锁定，顺序就是覆盖顺序（后面的压前面的）。
+    layers: info.layers,
+  }
+  // 纸张尺寸：文件里写了才带（不写就是"这份文件没说"，不是 850×1100）。
+  if (info.pageSize !== null) doc.page = { w: info.pageSize.w, h: info.pageSize.h }
+  if (existing !== null && existing.meta !== undefined && existing.meta !== null && existing.meta.pinned === true) {
+    doc.meta.pinned = true
+  }
+  return { doc: doc, notes: notes, pageCount: pageCount }
+}
+
+// ---- 单元的 XML 生成（新单元、以及从零生成一份文件时共用）--------------------
+
+/**
+ * 有数据（drawio 的"编辑数据"）时包一层 `<object>`。
+ *
+ * 为什么必须包：mxCodec 只解 mxCell 认识的字段，写在 mxCell 上的陌生属性会被 drawio
+ * 重新保存时丢掉；`<object>`/`<UserObject>` 上的自定义属性才活得下来（drawio 发明它的原因）。
+ * label 也随之移到外层 —— 与 drawio 的形态一致。
+ */
+function withDataWrapper(lines, item, indent) {
+  const data = item.data !== undefined && item.data !== null && typeof item.data === 'object' ? dataPairs(item.data) : null
+  if (data === null || Object.keys(data).length === 0) return lines.join('\n')
+  const first = lines[0]
+  // 内层那行去掉 value（label 已经在包装上），并整体再缩进一级
+  const inner = indent + '  ' + first.slice(indent.length).replace(/ value="[^"]*"/, '')
+  const rest = lines.slice(1).map((line) => indent + '  ' + line.slice(indent.length))
+  let attrs = ''
+  for (const key of Object.keys(data)) attrs += ' ' + key + '="' + data[key] + '"'
+  const label = typeof item.label === 'string' && item.label.length > 0 ? escapeAttr(item.label) : ''
+  return [indent + '<object label="' + label + '"' + attrs + ' id="' + escapeAttr(String(item.id)) + '">', inner]
+    .concat(rest)
+    .concat([indent + '</object>'])
+    .join('\n')
+}
+
+function nodeCellXml(node, parentId, indent) {
+  const style = typeof node.style === 'string' && node.style.length > 0 ? ' style="' + escapeAttr(node.style) + '"' : ''
+  const label = typeof node.label === 'string' && node.label.length > 0 ? ' value="' + escapeAttr(node.label) + '"' : ''
+  const x = Number.isFinite(Number(node.x)) ? Number(node.x) : 0
+  const y = Number.isFinite(Number(node.y)) ? Number(node.y) : 0
+  const w = Number.isFinite(Number(node.w)) ? Number(node.w) : 120
+  const h = Number.isFinite(Number(node.h)) ? Number(node.h) : 60
+  return withDataWrapper(
+    [
+      indent + '<mxCell id="' + escapeAttr(String(node.id)) + '"' + label + style + ' vertex="1" parent="' + escapeAttr(parentId) + '">',
+      indent + '  <mxGeometry x="' + x + '" y="' + y + '" width="' + w + '" height="' + h + '" as="geometry" />',
+      indent + '</mxCell>',
+    ],
+    node,
+    indent,
+  )
+}
+
+/** 边的几何内部（自由端点 + 折点 + 标签残余偏移）。缩进按 indent 缩进一级。 */
+function edgeInnerXml(edge, indent) {
+  const points = Array.isArray(edge.points) ? edge.points : []
+  const sourcePoint = edge.sourcePoint !== undefined && edge.sourcePoint !== null ? edge.sourcePoint : null
+  const targetPoint = edge.targetPoint !== undefined && edge.targetPoint !== null ? edge.targetPoint : null
+  const offset = edge.offset === undefined || edge.offset === null ? null : edge.offset
+  if (points.length === 0 && sourcePoint === null && targetPoint === null && offset === null) return ''
+  const lines = []
+  const inner = indent + '  '
+  if (sourcePoint !== null) lines.push(inner + '<mxPoint x="' + Number(sourcePoint.x) + '" y="' + Number(sourcePoint.y) + '" as="sourcePoint" />')
+  if (targetPoint !== null) lines.push(inner + '<mxPoint x="' + Number(targetPoint.x) + '" y="' + Number(targetPoint.y) + '" as="targetPoint" />')
+  if (points.length > 0) {
+    lines.push(inner + '<Array as="points">')
+    for (const point of points) lines.push(inner + '  <mxPoint x="' + Number(point.x) + '" y="' + Number(point.y) + '" />')
+    lines.push(inner + '</Array>')
+  }
+  if (offset !== null) lines.push(inner + '<mxPoint x="' + Number(offset.x) + '" y="' + Number(offset.y) + '" as="offset" />')
+  return '\n' + lines.join('\n') + '\n' + indent
+}
+
+/** 边几何的 x/y 属性（drawio 拿它存标签位置；没拖过就不写）。 */
+function labelPosAttrs(pos) {
+  return pos === null ? '' : ' x="' + Number(pos.x) + '" y="' + Number(pos.y) + '"'
+}
+
+function edgeCellXml(edge, parentId, indent) {
+  const style = typeof edge.style === 'string' && edge.style.length > 0 ? ' style="' + escapeAttr(edge.style) + '"' : ''
+  const label = typeof edge.label === 'string' && edge.label.length > 0 ? ' value="' + escapeAttr(edge.label) + '"' : ''
+  const from = typeof edge.from === 'string' ? ' source="' + escapeAttr(edge.from) + '"' : ''
+  const to = typeof edge.to === 'string' ? ' target="' + escapeAttr(edge.to) + '"' : ''
+  const pos = modelLabelPos(edge)
+  const inner = edgeInnerXml(Object.assign({}, edge, { offset: labelOffsetPoint(pos) }), indent)
+  const head = indent + '<mxCell id="' + escapeAttr(String(edge.id)) + '"' + label + style + ' edge="1" parent="' + escapeAttr(parentId) + '"' + from + to + '>'
+  const geoHead = indent + '  <mxGeometry' + labelPosAttrs(pos) + ' relative="1" as="geometry"'
+  if (inner.length === 0) {
+    return withDataWrapper([head, geoHead + ' />', indent + '</mxCell>'], edge, indent)
+  }
+  return withDataWrapper([head, geoHead + '>' + inner + '</mxGeometry>', indent + '</mxCell>'], edge, indent)
+}
+
+/**
+ * 图层单元（drawio 的写法）：挂在 root 下、**没有** vertex/edge，所以它既不是形状也不是连线。
+ * `value` = 名字、`visible="0"` = 隐藏、`locked="1"` = 锁定 —— 缺省（可见/未锁）不写属性。
+ */
+function layerCellXml(id, name, visible, locked, indent) {
+  const attrs = ['id="' + escapeAttr(id) + '"']
+  if (name.length > 0) attrs.push('value="' + escapeAttr(name) + '"')
+  if (visible === false) attrs.push('visible="0"')
+  if (locked === true) attrs.push('locked="1"')
+  attrs.push('parent="0"')
+  return indent + '<mxCell ' + attrs.join(' ') + ' />'
+}
+
+/** 元数据单元：没有 vertex/edge，所以不会显示，也不会被我们当成图形单元。 */function metaCellXml(parentId, indent, meta) {
+  const pinned = meta !== undefined && meta !== null && meta.pinned === true ? '1' : '0'
+  return [
+    indent + '<object label="" drawaiMeta="1" drawaiPinned="' + pinned + '" id="' + META_ID + '">',
+    indent + '  <mxCell parent="' + escapeAttr(parentId) + '" />',
+    indent + '</object>',
+  ].join('\n')
+}
+
+// ---- 写回：在原文件上做定点手术 ---------------------------------------------
+
+function spliceEdits(text, edits) {
+  const sorted = edits.slice().sort((a, b) => b.start - a.start || b.end - a.end)
+  let out = text
+  for (const edit of sorted) out = out.slice(0, edit.start) + edit.text + out.slice(edit.end)
+  return out
+}
+
+function pointsEqual(a, b) {
+  if (!Array.isArray(a) || !Array.isArray(b)) return false
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i += 1) {
+    if (Number(a[i].x) !== Number(b[i].x) || Number(a[i].y) !== Number(b[i].y)) return false
+  }
+  return true
+}
+
+function samePoint(a, b) {
+  const aNull = a === undefined || a === null
+  const bNull = b === undefined || b === null
+  if (aNull && bNull) return true
+  if (aNull !== bNull) return false
+  return Number(a.x) === Number(b.x) && Number(a.y) === Number(b.y)
+}
+
+/**
+ * style 是否等价 —— 写回时"没变就别动"的判据。
+ *
+ * 不能逐字比：文档层会把 style 规范化（键序、结尾分号），于是一个**没被碰过**的单元
+ * 也会因为"串长得不一样"被重写，逐字节不变的性质当场破掉（实测踩过）。
+ * 也不能只做语义比较：文件里没写 style 的连线 = drawio 的默认连线样式，
+ * 文档里显式写着默认值同样算没变。
+ */
+function stylesEqual(fileStyle, docStyle, isEdge) {
+  const a = typeof fileStyle === 'string' ? fileStyle : ''
+  const b = typeof docStyle === 'string' ? docStyle : ''
+  if (a === b) return true
+  const na = formatStyle(a)
+  const nb = formatStyle(b)
+  if (na === nb) return true
+  if (isEdge === true && na === '' && nb === formatStyle(DEFAULT_EDGE_STYLE)) return true
+  return false
+}
+
+/** 给一个还没有几何的单元补上几何（自闭合的单元要展开成开闭标签对）。 */
+function appendGeometry(text, cell, geometryXml) {
+  const attrsEnd = cell.attrsSpan.attrsEnd
+  if (cell.attrsSpan.selfClosing) {
+    // <mxCell … /> → <mxCell …>geometry</mxCell>
+    return text.slice(0, attrsEnd) + '>' + geometryXml + '</mxCell>' + text.slice(attrsEnd + 2)
+  }
+  return text.slice(0, attrsEnd + 1) + geometryXml + text.slice(attrsEnd + 1)
+}
+
+/**
+ * 重新定位单个单元的文本跨度。属性改写会让长度变化，需要**重新定位**再动结构
+ * （补几何 / 换几何内部）—— 拿旧偏移去做插入必然写错地方。
+ */
+function rescanCell(text) {
+  const cells = scanCells(text, 0, text.length)
+  return cells.length > 0 ? cells[0] : null
+}
+
+/** 数据对象 → 一组属性（转义后），id/label 不算数据。 */
+function dataPairs(data) {
+  const pairs = {}
+  for (const key of Object.keys(data)) {
+    if (key === 'id' || key === 'label') continue
+    pairs[key] = escapeAttr(String(data[key]))
+  }
+  return pairs
+}
+
+/**
+ * drawio 的"编辑数据"要落在 **`<object>` 包装**上。
+ *
+ * 为什么不能写在 mxCell 上：mxCodec 只解它认识的字段（id/value/style/parent/vertex/edge/
+ * source/target/geometry），写在 mxCell 上的陌生属性**被 drawio 重新保存时直接丢掉**。
+ * 这正是 drawio 发明 `<object>`/`<UserObject>` 包装的原因 —— 它的自定义属性才活得下来。
+ */
+function dataChangeFor(cell, data) {
+  if (cell.wrapper === null) return null
+  const span = cell.wrapper
+  const pairs = dataPairs(data)
+  // 模型里已经去掉的键要从包装上删掉（不动 id/label）
+  if (cell.wrapperAttrs !== null) {
+    for (const entry of parseAttrs(cell.wrapperAttrs, 0, cell.wrapperAttrs.length)) {
+      if (entry.name === 'id' || entry.name === 'label') continue
+      if (Object.prototype.hasOwnProperty.call(pairs, entry.name) === false) pairs[entry.name] = null
+    }
+  }
+  return { attrsStart: span.attrsStart, attrsEnd: span.attrsEnd, pairs: pairs }
+}
+
+/** 把裸 mxCell 包成 `<object>`（label 移到包装上、并带上数据），返回单元原文。 */
+function wrapAsObject(cell, text, data) {
+  const inner = setAttrsIn(text, cell.attrsSpan.attrsStart, cell.attrsSpan.attrsEnd, { value: null })
+  let attrs = ''
+  const pairs = dataPairs(data)
+  for (const key of Object.keys(pairs)) attrs += ' ' + key + '="' + pairs[key] + '"'
+  return '<object label="' + escapeAttr(labelFromValue(cell.label)) + '"' + attrs + ' id="' + escapeAttr(String(cell.id)) + '">' + inner + '</object>'
+}
+
+/** 改写一个顶点单元：标签、style、几何（几何要写回**相对父级**的坐标）。 */
+function rebuildNodeCell(info, cell, node, chain) {
+  // 单元跨度是**相对页体（mxGraphModel）**的，不是相对整份文件 —— 切错参照系会把
+  // 页面开头的几十个字符当成这个单元的原文（实测：改一个坐标把 mxGraphModel 标签搬进了单元里）。
+  let original = info.modelXml.slice(cell.start, cell.end)
+  let subject = cell
+  const data = node.data !== undefined && node.data !== null && typeof node.data === 'object' ? node.data : null
+  // 还没有包装、却有了数据 → 先包一层（drawio 的用户对象形态），再照常改。
+  // 包装会改变各处跨度，所以必须**先包、再重新定位**，否则后面的属性改写会写错位置。
+  if (data !== null && cell.wrapper === null) {
+    const wrapped = wrapAsObject(cell, original, data)
+    const fresh = rescanCell(wrapped)
+    if (fresh !== null) {
+      original = wrapped
+      subject = fresh
+    }
+  }
+  const changes = []
+  const label = typeof node.label === 'string' ? node.label : ''
+  if (label !== labelFromValue(subject.label)) {
+    const span = subject.wrapper !== null ? subject.wrapper : subject.attrsSpan
+    changes.push({
+      attrsStart: span.attrsStart,
+      attrsEnd: span.attrsEnd,
+      pairs: { [subject.wrapper !== null ? 'label' : 'value']: escapeAttr(label) },
+    })
+  }
+  const style = typeof node.style === 'string' ? node.style : ''
+  if (stylesEqual(subject.style, style, false) === false) {
+    changes.push({ attrsStart: subject.attrsSpan.attrsStart, attrsEnd: subject.attrsSpan.attrsEnd, pairs: { style: style.length > 0 ? escapeAttr(style) : null } })
+  }
+  if (data !== null) {
+    const entry = dataChangeFor(subject, data)
+    if (entry !== null) changes.push(entry)
+  }
+
+  const offset = chain.offset
+  const x = (Number.isFinite(Number(node.x)) ? Number(node.x) : 0) - offset.x
+  const y = (Number.isFinite(Number(node.y)) ? Number(node.y) : 0) - offset.y
+  const w = Number.isFinite(Number(node.w)) ? Number(node.w) : 120
+  const h = Number.isFinite(Number(node.h)) ? Number(node.h) : 60
+  // 父级换了（原来的容器被删了）也要写回，否则文件里留下悬空 parent。
+  if (typeof chain.parentId === 'string' && chain.parentId !== subject.parent) {
+    changes.push({ attrsStart: subject.attrsSpan.attrsStart, attrsEnd: subject.attrsSpan.attrsEnd, pairs: { parent: escapeAttr(chain.parentId) } })
+  }
+  const geo = subject.geometry
+  const unchanged = geo !== null && geo.x === x && geo.y === y && geo.width === w && geo.height === h
+  if (unchanged) return withAttrChanges(original, changes)
+
+  if (subject.geo !== null && subject.geo.selfClosing) {
+    // 只有属性、没有子元素：连 x/y/width/height 一起在一次批量改写里做（同一区域！）
+    const pairs = { x: String(x), y: String(y), width: String(w), height: String(h) }
+    if (attrIn(original, subject.geo.attrsStart, subject.geo.attrsEnd, 'as') === undefined) pairs.as = 'geometry'
+    changes.push({ attrsStart: subject.geo.attrsStart, attrsEnd: subject.geo.attrsEnd, pairs: pairs })
+    return withAttrChanges(original, changes)
+  }
+  if (subject.geo !== null) {
+    // 几何带子元素（例如 `<mxRectangle as="alternateBounds">`）：只改属性，子元素原样留着。
+    const pairs = { x: String(x), y: String(y), width: String(w), height: String(h) }
+    if (attrIn(original, subject.geo.attrsStart, subject.geo.attrsEnd, 'as') === undefined) pairs.as = 'geometry'
+    changes.push({ attrsStart: subject.geo.attrsStart, attrsEnd: subject.geo.attrsEnd, pairs: pairs })
+    return withAttrChanges(original, changes)
+  }
+  // 本来没有几何：先做属性改写，**重新定位**后再补几何。
+  const withAttrs = withAttrChanges(original, changes)
+  const fresh = rescanCell(withAttrs)
+  const geometry = '<mxGeometry x="' + x + '" y="' + y + '" width="' + w + '" height="' + h + '" as="geometry" />'
+  return fresh === null ? withAttrs : appendGeometry(withAttrs, fresh, geometry)
+}
+
+/** 改写一条边：标签、style、端点、折点/自由点（几何内部只在**语义**变了时才重建）。 */
+function rebuildEdgeCell(info, cell, edge, chain) {
+  const original = info.modelXml.slice(cell.start, cell.end)
+  const changes = []
+  const label = typeof edge.label === 'string' ? edge.label : ''
+  if (label !== labelFromValue(cell.label)) {
+    const span = cell.wrapper !== null ? cell.wrapper : cell.attrsSpan
+    changes.push({
+      attrsStart: span.attrsStart,
+      attrsEnd: span.attrsEnd,
+      pairs: { [cell.wrapper !== null ? 'label' : 'value']: escapeAttr(label) },
+    })
+  }
+  const style = typeof edge.style === 'string' ? edge.style : ''
+  if (stylesEqual(cell.style, style, true) === false) {
+    changes.push({ attrsStart: cell.attrsSpan.attrsStart, attrsEnd: cell.attrsSpan.attrsEnd, pairs: { style: style.length > 0 ? escapeAttr(style) : null } })
+  }
+  // 端点：只在真的换了落点时才动属性（同一区域，必须并进同一次批量改写）
+  const from = typeof edge.from === 'string' ? edge.from : undefined
+  const to = typeof edge.to === 'string' ? edge.to : undefined
+  const endpointPairs = {}
+  if (cell.source !== from) endpointPairs.source = from === undefined ? null : escapeAttr(from)
+  if (cell.target !== to) endpointPairs.target = to === undefined ? null : escapeAttr(to)
+  if (Object.keys(endpointPairs).length > 0) {
+    changes.push({ attrsStart: cell.attrsSpan.attrsStart, attrsEnd: cell.attrsSpan.attrsEnd, pairs: endpointPairs })
+  }
+
+  // 几何：折点 / 自由端点 / **标签位置**。语义相同就一个字节都不动（保住幂等与最小 diff）。
+  const geo = cell.geometry
+  const parsedPoints = geo !== null && Array.isArray(geo.points) ? geo.points : []
+  const modelPoints = Array.isArray(edge.points) ? edge.points : []
+  const parsedSource = geo === null ? null : geo.sourcePoint
+  const parsedTarget = geo === null ? null : geo.targetPoint
+  const modelSource = from === undefined && edge.sourcePoint !== undefined && edge.sourcePoint !== null ? edge.sourcePoint : null
+  const modelTarget = to === undefined && edge.targetPoint !== undefined && edge.targetPoint !== null ? edge.targetPoint : null
+  // 标签位置（drawio 的 mxGeometry x/y + offset）：模型里有就写、没有但文件里有就删（归中）。
+  const filePos = relativeLabelPos(geo)
+  const wantPos = modelLabelPos(edge)
+  if (labelPosChanged(filePos, wantPos)) {
+    changes.push({
+      attrsStart: cell.geo.attrsStart,
+      attrsEnd: cell.geo.attrsEnd,
+      pairs: { x: wantPos === null ? null : String(wantPos.x), y: wantPos === null ? null : String(wantPos.y) },
+    })
+  }
+  const parsedOffset = labelOffsetPoint(filePos)
+  const modelOffset = labelOffsetPoint(wantPos)
+  const innerUnchanged =
+    pointsEqual(parsedPoints, modelPoints) && samePoint(parsedSource, modelSource) && samePoint(parsedTarget, modelTarget) && samePoint(parsedOffset, modelOffset)
+  const text = withAttrChanges(original, changes)
+  if (innerUnchanged) return text
+
+  const fresh = rescanCell(text)
+  if (fresh === null) return text
+  const inner = edgeInnerXml({ points: modelPoints, sourcePoint: modelSource, targetPoint: modelTarget, offset: modelOffset }, '')
+  // 几何标签上的属性（x/y/relative/as…）**原样保留**：我们只往上面改 x/y（见上面的 changes），
+  // 重建时不能把它们抹掉 —— 否则"拖过标签的边"一改折点就把位置丢了。
+  const keepAttrs = fresh.geo === null ? '' : text.slice(fresh.geo.attrsStart, fresh.geo.attrsEnd)
+  const geometry = inner.length === 0 ? '<mxGeometry' + keepAttrs + ' />' : '<mxGeometry' + keepAttrs + '>' + inner + '</mxGeometry>'
+  if (fresh.geo === null) return appendGeometry(text, fresh, geometry)
+  if (fresh.geo.selfClosing) return text.slice(0, fresh.geo.start) + geometry + text.slice(fresh.geo.end)
+  return text.slice(0, fresh.geo.innerFrom) + inner + text.slice(fresh.geo.innerTo)
+}
+
+/**
+ * 算出"要把原文件改成什么样"的**编辑计划**（不改文本）。
+ *
+ * 抽出来是为了两件事：自测能直接断言"没改动时编辑数为 0"（无损的第一条不变量），
+ * 以及出问题时能看见每条编辑落在哪儿 —— 偏移错了写出来的文件会当场花掉。
+ *
+ * @returns { info, edits, dropped }
+ */
+function planDocEdits(originalText, doc) {
+  const source = String(originalText === undefined || originalText === null ? '' : originalText)
+  const info = analyzeMxfile(source)
+  const owned = ownershipOf(info).owned
+  const nodes = Array.isArray(doc.nodes) ? doc.nodes : []
+  const edges = Array.isArray(doc.edges) ? doc.edges : []
+  const nodeIds = new Set(nodes.map((n) => String(n.id)))
+  const wanted = new Map()
+  for (const node of nodes) if (node !== null && typeof node === 'object') wanted.set(String(node.id), { kind: 'node', item: node })
+  for (const edge of edges) if (edge !== null && typeof edge === 'object') wanted.set(String(edge.id), { kind: 'edge', item: edge })
+
+  /** 一条边的落点：doc 里的顶点才算真实落点，否则用自由点；两者都没有就丢掉它。 */
+  const anchorsOf = (edge) => {
+    const from = typeof edge.from === 'string' && nodeIds.has(edge.from) ? edge.from : undefined
+    const to = typeof edge.to === 'string' && nodeIds.has(edge.to) ? edge.to : undefined
+    const sourcePoint = edge.sourcePoint !== undefined && edge.sourcePoint !== null ? edge.sourcePoint : undefined
+    const targetPoint = edge.targetPoint !== undefined && edge.targetPoint !== null ? edge.targetPoint : undefined
+    if (from === undefined && sourcePoint === undefined) return null
+    if (to === undefined && targetPoint === undefined) return null
+    return Object.assign({}, edge, { from: from, to: to, sourcePoint: sourcePoint, targetPoint: targetPoint })
+  }
+
+  const dropped = []
+  const edits = []
+  // 画布上的绝对坐标：写回时容器子单元的相对坐标要按它反算。
+  const modelAbs = new Map()
+  for (const node of nodes) {
+    if (node === null || typeof node !== 'object') continue
+    modelAbs.set(String(node.id), { x: Number.isFinite(Number(node.x)) ? Number(node.x) : 0, y: Number.isFinite(Number(node.y)) ? Number(node.y) : 0 })
+  }
+  // 被删掉的单元（我们导入过、模型里没有了）。它们若是别人的父级，下面是"孤儿"，要接走。
+  const deletedIds = new Set()
+  for (const cell of info.cells) {
+    const id = String(cell.id)
+    if (owned.has(id) && wanted.get(id) === undefined) deletedIds.add(id)
+  }
+  // 已知的层 id = 文件里的层 ∪ 模型里的层（模型里可能有这次刚新建的层）。
+  const docLayers = Array.isArray(doc.layers) ? doc.layers : []
+  const knownLayers = new Set(info.layerIds)
+  for (const layer of docLayers) {
+    if (layer !== null && typeof layer === 'object' && typeof layer.id === 'string') knownLayers.add(layer.id)
+  }
+  for (const cell of info.cells) {
+    const id = String(cell.id)
+    const want = wanted.get(id)
+    if (want === undefined) {
+      // 我们导入过、而模型里没有了 → 用户真的删了它。
+      // 我们**没**导入过的（不认识的边）不是删除，原样留着。
+      if (owned.has(id)) edits.push({ start: cell.start, end: cell.end, text: '' })
+      continue
+    }
+    const chain = writeChainOf(info, modelAbs, deletedIds, cell, want.item.layer, knownLayers)
+    if (want.kind === 'edge') {
+      const anchors = anchorsOf(want.item)
+      if (anchors === null) {
+        dropped.push(id)
+        edits.push({ start: cell.start, end: cell.end, text: '' })
+        continue
+      }
+      const rebuilt = rebuildEdgeCell(info, cell, anchors, chain)
+      if (rebuilt !== info.modelXml.slice(cell.start, cell.end)) edits.push({ start: cell.start, end: cell.end, text: rebuilt })
+      continue
+    }
+    const rebuilt = rebuildNodeCell(info, cell, want.item, chain)
+    if (rebuilt !== info.modelXml.slice(cell.start, cell.end)) edits.push({ start: cell.start, end: cell.end, text: rebuilt })
+  }
+
+  // ── 顺序（z-order）：drawio 的"谁在上面"就是**单元在 root 里的先后** ──
+  //
+  // 模型里节点的先后 = 画布上的覆盖顺序，所以"置顶/置底"改的是模型数组顺序；
+  // 文件那边必须跟着改，否则重新载入（或 drawio 打开）又变回原来的层叠顺序。
+  //
+  // 只在**真的变了**的时候才动：读进来时模型的先后就是文件里的先后，
+  // 于是"打开后原样保存逐字节不变"这条性质不受影响（下面的 reorderKind 会先比对）。
+  const moveEdits = planReorder(info, edits, nodes, edges, owned)
+  for (const edit of moveEdits) edits.push(edit)
+
+  // 我们不认识的单元如果挂在被删的容器下，也要接走 —— 否则文件里留下悬空 parent。
+  // （我们不"拥有"它，所以只改 parent，不碰它的其他属性。）
+  if (deletedIds.size > 0) {
+    for (const cell of info.cells) {
+      const id = String(cell.id)
+      if (deletedIds.has(id) || wanted.get(id) !== undefined) continue
+      if (typeof cell.parent !== 'string' || deletedIds.has(cell.parent) === false) continue
+      const chain = writeChainOf(info, modelAbs, deletedIds, cell)
+      const original = info.modelXml.slice(cell.start, cell.end)
+      const rebuilt = setAttrsIn(original, cell.attrsSpan.attrsStart, cell.attrsSpan.attrsEnd, { parent: escapeAttr(chain.parentId) })
+      if (rebuilt !== original) edits.push({ start: cell.start, end: cell.end, text: rebuilt })
+    }
+  }
+
+  // 新单元：插到最后一个单元之后（parent 用**它自己那一层**，没写就用第一个图层）
+  //
+  // 缩进与插入点都**跟着这个文件走**，不硬编码：硬编码会留下多余空白，
+  // 于是"只追加了一个单元"变成"顺带改了别处的字节"，逐字节不变的性质就没了。
+  const layerId = info.layerOrder.length > 0 ? info.layerOrder[0] : info.rootId
+  const layerById = new Map()
+  for (const layer of docLayers) if (layer !== null && typeof layer === 'object' && typeof layer.id === 'string') layerById.set(layer.id, layer)
+  const parentFor = (cell) => {
+    const want = cell !== null && typeof cell === 'object' && typeof cell.layer === 'string' ? cell.layer : null
+    if (want !== null && (layerById.has(want) === true || info.layerIds.has(want) === true)) return want
+    return layerId
+  }
+  const rootLineStart = info.modelXml.lastIndexOf('\n', info.innerTo)
+  const rootIndent = rootLineStart < 0 ? '' : info.modelXml.slice(rootLineStart + 1, info.innerTo)
+  const childIndent = rootIndent + '  '
+  const additions = []
+  for (const node of nodes) {
+    if (node === null || typeof node !== 'object' || info.byId.has(String(node.id))) continue
+    additions.push(nodeCellXml(node, parentFor(node), childIndent))
+  }
+  for (const edge of edges) {
+    if (edge === null || typeof edge !== 'object' || info.byId.has(String(edge.id))) continue
+    const anchors = anchorsOf(edge)
+    if (anchors === null) {
+      dropped.push(String(edge.id))
+      continue
+    }
+    additions.push(edgeCellXml(anchors, parentFor(edge), childIndent))
+  }
+
+  // 图层：① 已存在的层，改了名字/可见/锁定就做**属性级**定点改写（不动别的字节）；
+  //       ② 模型里有、文件里没有的层 → 新建一个图层单元。
+  // 删除图层（以及层内的单元）留到 v2：那要连单元一起删，属于另一件事。
+  for (const layer of docLayers) {
+    if (layer === null || typeof layer !== 'object' || typeof layer.id !== 'string') continue
+    const cell = info.byId.get(layer.id)
+    const name = typeof layer.name === 'string' ? layer.name : ''
+    const visible = layer.visible !== false
+    const locked = layer.locked === true
+    if (cell === undefined) {
+      additions.push(layerCellXml(layer.id, String(name), visible, locked, childIndent))
+      continue
+    }
+    if (info.layerIds.has(layer.id) === false) continue
+    const original = info.modelXml.slice(cell.start, cell.end)
+    const span = cell.wrapper !== null ? cell.wrapper : cell.attrsSpan
+    const current = info.layers.filter((l) => l.id === layer.id)[0]
+    const want = { value: name, visible: visible ? null : '0', locked: locked ? '1' : null }
+    const had = current === undefined ? { name: '', visible: true, locked: false } : current
+    if (had.name === name && had.visible === visible && had.locked === locked) continue
+    const rebuilt = setAttrsIn(original, span.attrsStart, span.attrsEnd, want)
+    if (rebuilt !== original) edits.push({ start: cell.start, end: cell.end, text: rebuilt })
+  }
+
+  // 元数据单元（pin 状态）：有就更新，需要而没有就新建，不需要就删掉
+  const metaCell = info.byId.get(META_ID)
+  const wantPinned = doc.meta !== undefined && doc.meta !== null && doc.meta.pinned === true
+  if (metaCell !== undefined) {
+    if (wantPinned === false) {
+      edits.push({ start: metaCell.start, end: metaCell.end, text: '' })
+    } else {
+      const original = info.modelXml.slice(metaCell.start, metaCell.end)
+      const span = metaCell.wrapper !== null ? metaCell.wrapper : metaCell.attrsSpan
+      const rebuilt = attrIn(original, span.attrsStart, span.attrsEnd, 'drawaiPinned') === '1'
+        ? original
+        : setAttrIn(original, span.attrsStart, span.attrsEnd, 'drawaiPinned', '1')
+      if (rebuilt !== original) edits.push({ start: metaCell.start, end: metaCell.end, text: rebuilt })
+    }
+  } else if (wantPinned === true) {
+    additions.push(metaCellXml(layerId, childIndent, doc.meta))
+  }
+  if (additions.length > 0) {
+    const insertAt = rootLineStart < 0 ? info.innerTo : rootLineStart
+    edits.push({ start: insertAt, end: insertAt, text: '\n' + additions.join('\n') })
+  }
+
+  return { info: info, edits: edits, dropped: dropped }
+}
+
+/**
+ * 顺序改动 → 编辑计划（把"文件里这些单元的先后"改成模型里的先后）。
+ *
+ * 为什么不能不做：`置顶/置底`在画布上改的是模型数组顺序，而文件里单元的先后**就是**层叠顺序——
+ * 不写回去的话，重新载入或拿 drawio 打开又变回原样，用户会觉得"置顶没生效"。
+ *
+ * 做法：先算文件里"我们拥有的这一种单元"的 id 序列，和模型里的序列比；一样就**一条编辑都不发**
+ * （这条保证了"打开后原样保存逐字节不变"）。不一样时，把位置不对的单元挪到目标位置前面：
+ * 删掉原位置 + 在目标行首插入（缩进沿用目标行）。
+ *
+ * 节点与边**分开**比对：模型里节点和边是两个数组，而文件里它们可能交错排列；
+ * 拿 `[...nodes, ...edges]` 去比会把交错的文件整体重排一遍（每次保存都大改，绝对不能这么干）。
+ */
+function planReorder(info, edits, nodes, edges, owned) {
+  const out = []
+  const editedText = new Map()
+  for (const edit of edits) if (edit.end > edit.start) editedText.set(edit.start, edit.text)
+  const deleted = new Set()
+  for (const edit of edits) if (edit.end > edit.start && edit.text === '') deleted.add(edit.start)
+
+  const orderOf = (wanted) => {
+    const list = []
+    for (const cell of info.cells) {
+      if (wanted.has(String(cell.id))) list.push(cell)
+    }
+    return list
+  }
+  const lineStartOf = (offset) => {
+    const at = info.modelXml.lastIndexOf('\n', offset)
+    return at < 0 ? 0 : at + 1
+  }
+  const indentOf = (offset) => info.modelXml.slice(lineStartOf(offset), offset)
+
+  const kinds = [
+    { wanted: new Set(nodes.map((n) => String(n.id))), model: nodes.map((n) => String(n.id)) },
+    { wanted: new Set(edges.map((e) => String(e.id))), model: edges.map((e) => String(e.id)) },
+  ]
+  for (const kind of kinds) {
+    const fileCells = orderOf(kind.wanted)
+    // 只考虑"文件里有、模型里也有"的单元（新单元由 additions 负责；被删的已经没了）。
+    const current = fileCells.filter((c) => kind.model.indexOf(String(c.id)) >= 0).map((c) => String(c.id))
+    if (current.join('\u0000') === kind.model.join('\u0000')) continue
+    // 有删除/新增混在一起时顺序本来就会变，那种情况不折腾（新增在末尾、删除不影响相对顺序）。
+    if (fileCells.length !== kind.model.length) continue
+    const byId = new Map()
+    for (const cell of fileCells) byId.set(String(cell.id), cell)
+
+    // **一次插入**，而不是逐个移动：逐个"插到同一个锚点前面"，最终先后取决于 splice 的应用顺序，
+    // 实测会插反（[n1,n2,n3] 置顶 n1 得到 n3,n1,n2）。所以：
+    // 把这些单元各自删掉，再在**最早那个单元的行首**按模型顺序整体插回。
+    // 中间夹着的、不归我们管的单元不受影响（只是位置跟着挪）。
+    const texts = []
+    let firstAt = -1
+    for (const id of kind.model) {
+      const cell = byId.get(id)
+      if (cell === undefined) continue
+      texts.push(indentOf(cell.start) + (editedText.has(cell.start) ? editedText.get(cell.start) : info.modelXml.slice(cell.start, cell.end)))
+      if (deleted.has(cell.start) === false) out.push({ start: cell.start, end: cell.end, text: '' })
+      if (firstAt < 0 || cell.start < firstAt) firstAt = cell.start
+    }
+    if (firstAt < 0 || texts.length === 0) continue
+    const at = lineStartOf(firstAt)
+    out.push({ start: at, end: at, text: texts.join('\n') + '\n' })
+  }
+  void owned
+  return out
+}
+
+/**
+ * 把语义文档写回一份**已有的** mxfile 文本。
+ *
+ * 只改我们拥有的单元（见文件头），其余原文逐字节保留；原本压缩的页体写回后仍压缩。
+ *
+ * @returns { text, dropped } —— dropped 是被略过的边 id（两端都没有落点），调用方应如实上报
+ */
+export function applyDocToMxfile(originalText, doc, options) {
+  const source = String(originalText === undefined || originalText === null ? '' : originalText)
+  const plan = planDocEdits(source, doc)
+  const model = spliceEdits(plan.info.modelXml, plan.edits)
+  const bodyText = plan.info.compressed ? compressModel(model) : model
+  return {
+    text: source.slice(0, plan.info.bodyStart) + bodyText + source.slice(plan.info.bodyEnd),
+    dropped: plan.dropped,
+  }
+}
+
+// ---- 自测钩子 ---------------------------------------------------------------
+
+/**
+ * 仅供自测：暴露全文分析（页 / 图层 / 归属 / 每个单元的文本跨度）。
+ *
+ * 写回是"按偏移做定点手术"，偏移错了就会写出花掉的文件 —— 所以要能直接把跨度
+ * 拿出来断言，而不是靠"看起来对"。归属判据也一并暴露：读与写必须用同一套。
+ */
+export function __analyze(text) {
+  const info = analyzeMxfile(String(text === undefined || text === null ? '' : text))
+  const ownership = ownershipOf(info)
+  return {
+    pageCount: info.pageCount,
+    compressed: info.compressed,
+    bodyStart: info.bodyStart,
+    bodyEnd: info.bodyEnd,
+    rootId: info.rootId,
+    layerOrder: info.layerOrder,
+    innerFrom: info.innerFrom,
+    innerTo: info.innerTo,
+    owned: [...ownership.owned],
+    nodeIds: [...ownership.nodeIds],
+    cells: info.cells.map((cell) => ({
+      id: cell.id,
+      element: cell.element,
+      start: cell.start,
+      end: cell.end,
+      parent: cell.parent,
+      vertex: cell.vertex,
+      edge: cell.edge,
+      attrsSpan: cell.attrsSpan,
+      wrapper: cell.wrapper,
+      geo:
+        cell.geo === null
+          ? null
+          : {
+              attrsStart: cell.geo.attrsStart,
+              attrsEnd: cell.geo.attrsEnd,
+              selfClosing: cell.geo.selfClosing,
+              start: cell.geo.start,
+              end: cell.geo.end,
+              innerFrom: cell.geo.innerFrom,
+              innerTo: cell.geo.innerTo,
+            },
+    })),
+  }
+}
+
+/**
+ * 仅供自测：暴露**编辑计划**（每条编辑的范围与预览）。
+ * "打开后原样保存 ⇒ 编辑数为 0" 是写回无损的第一条不变量，必须能直接断言。
+ */
+export function __plan(text, doc) {
+  const plan = planDocEdits(text, doc)
+  return {
+    dropped: plan.dropped,
+    info: { bodyStart: plan.info.bodyStart, bodyEnd: plan.info.bodyEnd, innerTo: plan.info.innerTo, compressed: plan.info.compressed },
+    edits: plan.edits.map((edit) => ({
+      start: edit.start,
+      end: edit.end,
+      insert: edit.start === edit.end,
+      old: plan.info.modelXml.slice(edit.start, Math.min(edit.end, edit.start + 40)),
+      text: edit.text.slice(0, 60),
+    })),
+  }
+}
+
+// ---- 从零生成一份 mxfile（新建 / 另存为用）----------------------------------
+/**
+ * 文档 → 全新的 mxfile。默认**不压缩**（人可读、diff 友好；drawio 两种都认）。
+ *
+ * 注意：这是"从零生成"，只写模型里的东西 —— 所以只用于新建文件；
+ * 覆盖已有文件一律走 `applyDocToMxfile`（无损写回）。
+ *
+ * @returns { text, dropped }
+ */
+export function buildMxfile(doc, options) {
+  const compressed = options !== undefined && options.compressed === true
+  const pageName = options !== undefined && typeof options.name === 'string' && options.name.length > 0 ? options.name : 'Page-1'
+  const nodes = Array.isArray(doc.nodes) ? doc.nodes : []
+  const edges = Array.isArray(doc.edges) ? doc.edges : []
+  const nodeIds = new Set(nodes.map((n) => String(n.id)))
+  const dropped = []
+  const lines = []
+  // 纸张：模型里带了就照它写（读进来是什么尺寸，从零重建时还是什么尺寸），没带就用 drawio 的缺省。
+  const pageW = doc.page !== undefined && doc.page !== null && Number.isFinite(Number(doc.page.w)) && Number(doc.page.w) > 0 ? Number(doc.page.w) : PAGE_W
+  const pageH = doc.page !== undefined && doc.page !== null && Number.isFinite(Number(doc.page.h)) && Number(doc.page.h) > 0 ? Number(doc.page.h) : PAGE_H
+  lines.push('<mxfile host="dsh-drawai" agent="dsh-drawai" type="device">')
+  lines.push('  <diagram id="dsh-drawai-page-1" name="' + escapeAttr(pageName) + '">')
+  lines.push(
+    '    <mxGraphModel dx="0" dy="0" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="' +
+      pageW +
+      '" pageHeight="' +
+      pageH +
+      '" math="0" shadow="0">',
+  )
+  lines.push('      <root>')
+  lines.push('        <mxCell id="0" />')
+  // 图层：模型里给了就用它（第一层的 id 取代缺省的 "1"），没给就写缺省的 `<mxCell id="1" parent="0" />`。
+  const layers = Array.isArray(doc.layers) ? doc.layers.filter((l) => l !== null && typeof l === 'object' && typeof l.id === 'string') : []
+  for (const layer of layers) {
+    lines.push(
+      layerCellXml(
+        layer.id,
+        typeof layer.name === 'string' ? layer.name : '',
+        layer.visible !== false,
+        layer.locked === true,
+        '        ',
+      ),
+    )
+  }
+  if (layers.length === 0) lines.push('        <mxCell id="1" parent="0" />')
+  const firstLayerId = layers.length > 0 ? String(layers[0].id) : '1'
+  const parentOf = (cell) => {
+    const want = cell !== null && typeof cell === 'object' && typeof cell.layer === 'string' ? cell.layer : null
+    if (want !== null && layers.some((l) => String(l.id) === want)) return want
+    return firstLayerId
+  }
+  if (doc.meta !== undefined && doc.meta !== null && doc.meta.pinned === true) lines.push(metaCellXml(parentOf(doc.meta), '        ', doc.meta))
+  for (const node of nodes) {
+    if (node === null || typeof node !== 'object') continue
+    lines.push(nodeCellXml(node, parentOf(node), '        '))
+  }
+  for (const edge of edges) {
+    if (edge === null || typeof edge !== 'object') continue
+    const from = typeof edge.from === 'string' && nodeIds.has(edge.from) ? edge.from : undefined
+    const to = typeof edge.to === 'string' && nodeIds.has(edge.to) ? edge.to : undefined
+    const sourcePoint = edge.sourcePoint !== undefined && edge.sourcePoint !== null ? edge.sourcePoint : undefined
+    const targetPoint = edge.targetPoint !== undefined && edge.targetPoint !== null ? edge.targetPoint : undefined
+    if (from === undefined && sourcePoint === undefined) {
+      dropped.push(String(edge.id))
+      continue
+    }
+    if (to === undefined && targetPoint === undefined) {
+      dropped.push(String(edge.id))
+      continue
+    }
+    lines.push(
+      edgeCellXml(
+        Object.assign({}, edge, { from: from, to: to, sourcePoint: sourcePoint, targetPoint: targetPoint }),
+        parentOf(edge),
+        '        ',
+      ),
+    )
+  }
+  lines.push('      </root>')
+  lines.push('    </mxGraphModel>')
+  const model = lines.slice(2).join('\n')
+  const head = lines.slice(0, 2).join('\n')
+  const tail = ['  </diagram>', '</mxfile>', ''].join('\n')
+  if (!compressed) return { text: head + '\n' + model + '\n' + tail, dropped: dropped }
+  return {
+    text:
+      '<mxfile host="dsh-drawai" agent="dsh-drawai" type="device">\n  <diagram id="dsh-drawai-page-1" name="' +
+      escapeAttr(pageName) +
+      '">\n    ' +
+      compressModel(model) +
+      '\n  </diagram>\n</mxfile>\n',
+    dropped: dropped,
+  }
+}