@allbluecn/web-app 0.17.2 → 0.18.0

package/src/components/design/canvas/document/frames.ts

@@ -0,0 +1,169 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { m } from "@/paraglide/messages.js"
+import { createPaint } from "./style/paints"
+import { BOARD_NODE_ID, type SceneNode } from "./types"
+
+export const FRAME_GAP = 80
+export const MAX_FRAMES_PER_ROW = 4
+
+export type FramePresetKind = "desktop" | "tablet" | "mobile" | "custom"
+
+export type FramePresetItem = {
+  name: string
+  width: number
+  height: number
+  cornerRadius?: number
+  /** 四角独立圆角 [左上, 右上, 右下, 左下]，优先于 cornerRadius */
+  corners?: [number, number, number, number]
+  /** 型号名，用于自动命名「画板 N·型号」；桌面端分辨率预设无型号 */
+  model?: string
+}
+
+/** 预设应用时的四角圆角：corners 优先，cornerRadius 展开为四角同值 */
+export function framePresetCorners(
+  item: FramePresetItem,
+): [number, number, number, number] | undefined {
+  if (item.corners) return item.corners
+  if (item.cornerRadius)
+    return [item.cornerRadius, item.cornerRadius, item.cornerRadius, item.cornerRadius]
+  return undefined
+}
+
+// 常见屏幕比例表（长边:短边），±2% 容差内就近匹配；未命中退化为 N.NN:1
+const ASPECT_RATIO_TABLE: ReadonlyArray<readonly [number, number]> = [
+  [1, 1],
+  [5, 4],
+  [4, 3],
+  [3, 2],
+  [16, 10],
+  [16, 9],
+  [19.5, 9],
+  [20, 9],
+  [21, 9],
+  [22, 9],
+  [32, 9],
+]
+
+/** 画板屏幕比例标签（长边:短边），如 16:9 / 19.5:9；非标准比例显示 1.45:1 形式 */
+export function frameAspectRatioLabel(width: number, height: number): string {
+  const long = Math.max(width, height)
+  const short = Math.min(width, height)
+  if (long <= 0 || short <= 0) return "—"
+  const ratio = long / short
+  for (const [a, b] of ASPECT_RATIO_TABLE) {
+    const standard = a / b
+    if (Math.abs(ratio - standard) / standard <= 0.02) return `${a}:${b}`
+  }
+  return `${parseFloat(ratio.toFixed(2))}:1`
+}
+
+export const FRAME_PRESETS: Record<FramePresetKind, { items: FramePresetItem[] }> = {
+  desktop: {
+    items: [
+      { name: "1920×1080", width: 1920, height: 1080 },
+      { name: "1440×900", width: 1440, height: 900 },
+      { name: "1366×768", width: 1366, height: 768 },
+      { name: "1024×768", width: 1024, height: 768 },
+    ],
+  },
+  tablet: {
+    items: [
+      { name: "iPad Pro 13″ 1032×1376", width: 1032, height: 1376, model: "iPad Pro 13" },
+      { name: "iPad Pro 11″ 834×1194", width: 834, height: 1194, model: "iPad Pro 11" },
+      { name: "iPad Air 820×1180", width: 820, height: 1180, model: "iPad Air" },
+    ],
+  },
+  mobile: {
+    // 手机画板带圆角（真机逻辑分辨率，屏幕四角圆弧）。
+    // 机型清单来自产品表格（表格_20261001.csv）：CSV 尺寸为横置写法，此处按真机
+    // 形态转为竖屏（宽<高）；Pura X 内屏（阔折叠横屏展开）与 Mate XT 三屏（展开
+    // 后横向平板）保持横向。圆角为统一值，见 CSV「屏幕圆角」列。
+    items: [
+      { name: "iPhone 18 Pro Max 440×956", width: 440, height: 956, cornerRadius: 62, model: "iPhone 18 Pro Max" },
+      { name: "iPhone Duo（外屏）466×678", width: 466, height: 678, corners: [8, 62, 62, 8], model: "iPhone Duo（外屏）" },
+      { name: "iPhone Duo（内屏）626×890", width: 890, height: 626, cornerRadius: 62, model: "iPhone Duo（内屏）" },
+      { name: "iPhone SE 375×667", width: 375, height: 667, model: "iPhone SE" },
+      { name: "Mate 90 Pro 360×800", width: 360, height: 800, cornerRadius: 20, model: "Mate 90 Pro" },
+      { name: "Mate 90 Pro Max 360×776", width: 360, height: 776, cornerRadius: 20, model: "Mate 90 Pro Max" },
+      { name: "Pura 90 Pro 360×791", width: 360, height: 791, cornerRadius: 18, model: "Pura 90 Pro" },
+      { name: "Pura 90 Pro Max 360×793", width: 360, height: 793, cornerRadius: 19, model: "Pura 90 Pro Max" },
+      { name: "Pura X（内屏）578×360", width: 578, height: 360, cornerRadius: 18, model: "Pura X（内屏）" },
+      { name: "Pura X（外屏）326×326", width: 326, height: 326, cornerRadius: 24, model: "Pura X（外屏）" },
+      { name: "HUAWEI Pura X View 744×440", width: 744, height: 440, cornerRadius: 18, model: "HUAWEI Pura X View" },
+      { name: "Mate XT（单屏）360×797", width: 360, height: 797, cornerRadius: 18, model: "Mate XT（单屏）" },
+      { name: "Mate XT（双屏）720×797", width: 720, height: 797, cornerRadius: 12, model: "Mate XT（双屏）" },
+      { name: "Mate XT（三屏）1080×797", width: 1080, height: 797, cornerRadius: 10, model: "Mate XT（三屏）" },
+      { name: "Galaxy S26 Ultra 384×832", width: 384, height: 832, cornerRadius: 20, model: "Galaxy S26 Ultra" },
+      { name: "Galaxy Z Fold8（内屏）690×844", width: 690, height: 844, cornerRadius: 10, model: "Galaxy Z Fold8（内屏）" },
+      { name: "Galaxy Z Fold8（外屏）360×569", width: 360, height: 569, cornerRadius: 18, model: "Galaxy Z Fold8（外屏）" },
+      { name: "W25 Flip（内屏）360×879", width: 360, height: 879, cornerRadius: 18, model: "W25 Flip（内屏）" },
+      { name: "W25 Flip（外屏）328×341", width: 328, height: 341, cornerRadius: 24, model: "W25 Flip（外屏）" },
+    ],
+  },
+  // 自定义画板预设：运行时从 frame-custom-presets 读取，此处仅占位保证 Record 类型完整
+  custom: { items: [] },
+}
+
+export function findNextFramePosition(
+  existingFrames: SceneNode[],
+  _newWidth: number,
+  _newHeight: number,
+): { x: number; y: number } {
+  if (existingFrames.length === 0) return { x: 0, y: 0 }
+  const baselineTolerance = 1
+  const rows = groupRows(existingFrames, baselineTolerance)
+  const lastRow = rows[rows.length - 1]
+  if (lastRow.length < MAX_FRAMES_PER_ROW) {
+    const maxX = Math.max(...lastRow.map((f) => f.x + f.width))
+    return { x: maxX + FRAME_GAP, y: lastRow[0].y }
+  }
+  const maxY = Math.max(...lastRow.map((f) => f.y + f.height))
+  const firstColX = Math.min(...rows[0].map((f) => f.x))
+  return { x: firstColX, y: maxY + FRAME_GAP }
+}
+
+function groupRows(frames: SceneNode[], tolerance: number): SceneNode[][] {
+  const sorted = [...frames].sort((a, b) => a.y - b.y)
+  const rows: SceneNode[][] = []
+  for (const f of sorted) {
+    const row = rows.find(
+      (r) => Math.abs(r[0].y - f.y) <= Math.max(...r.map((n) => n.height)) + tolerance,
+    )
+    if (row) row.push(f)
+    else rows.push([f])
+  }
+  return rows
+}
+
+// 自动命名：画板 N（预设创建带型号：画板 N·iPhone 16）；
+// N = 现有画板数 + 1，删除后可能重号，可接受
+export function nextFrameName(
+  existingFrames: readonly SceneNode[],
+  model?: string,
+): string {
+  const base = m.canvas_frameDefaultName({ count: existingFrames.length + 1 })
+  return model ? `${base}·${model}` : base
+}
+
+export function createFrameNode(
+  id: string,
+  bounds: { x: number; y: number; width: number; height: number },
+  preset?: FramePresetKind | "free",
+  name?: string,
+): SceneNode {
+  return {
+    id,
+    kind: "group",
+    type: "frame",
+    parentId: BOARD_NODE_ID,
+    name: name ?? "Frame",
+    x: bounds.x,
+    y: bounds.y,
+    width: bounds.width,
+    height: bounds.height,
+    // 默认填充走结构化 fills（画板填充面板 Fills 区的事实源），
+    // 不再写 legacy style.fill 键
+    fills: [createPaint({ color: "#ffffff" })],
+    ...(preset ? { props: { preset } } : {}),
+  }
+}

package/src/components/design/canvas/document/geometry.ts

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import { BOARD_NODE_ID, type SceneDocument, type SceneNode } from "./types"
+
+export type SceneRect = {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+const MAX_DEPTH = 64
+
+export function nodeById(doc: SceneDocument, id: string): SceneNode | undefined {
+  return doc.nodes.find((node) => node.id === id)
+}
+
+export function nodeAbsoluteRect(doc: SceneDocument, id: string): SceneRect | null {
+  const byId = new Map(doc.nodes.map((node) => [node.id, node]))
+  const node = byId.get(id)
+  if (!node || node.id === BOARD_NODE_ID || node.visible === false) return null
+
+  let x = node.x
+  let y = node.y
+  let parent: SceneNode | undefined = node.parentId ? byId.get(node.parentId) : undefined
+  let depth = 0
+  while (parent && depth < MAX_DEPTH) {
+    if (parent.visible === false) return null
+    x += parent.x
+    y += parent.y
+    parent = parent.parentId ? byId.get(parent.parentId) : undefined
+    depth += 1
+  }
+
+  return { x, y, width: node.width, height: node.height }
+}
+
+export function nodeCenter(doc: SceneDocument, id: string): SceneRect | null {
+  const rect = nodeAbsoluteRect(doc, id)
+  if (!rect) return null
+  return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2, width: 0, height: 0 }
+}

package/src/components/design/canvas/document/group.ts

@@ -0,0 +1,121 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// 编组/解组（FS-4.1，doc 级纯函数，无 leafer 依赖）：
+// - SceneNode.x/y 是父容器相对坐标，同父成员才可编组（union bounds 直接在父空间计算）
+// - 数组顺序即 z 序（靠后者在上）：建组插在最高 z 序成员之后，解组成员占回组原位置
+// - 不可变更新：函数返回新 SceneDocument，入参不被修改（SceneHistory 快照依赖此前提）
+
+import { BOARD_NODE_ID, type SceneDocument, type SceneNode } from "./types"
+
+export type GroupNodesResult = { doc: SceneDocument; groupId: string }
+
+export type UngroupNodesResult = { doc: SceneDocument; ids: string[] }
+
+// 组 id：沿用 `prefix_N` 惯例（与 pasteClipboard nextIdFor 同语义），从现有
+// group_N 最大序号续编，同批分配的 id 立即登记防止互相冲突
+function nextGroupId(nodes: readonly SceneNode[]): string {
+  const used = new Set(nodes.map((node) => node.id))
+  let max = 0
+  for (const id of used) {
+    const m = /^group_(\d+)$/.exec(id)
+    if (m) max = Math.max(max, Number(m[1]))
+  }
+  let id = `group_${max + 1}`
+  while (used.has(id)) id = `group_${++max}`
+  return id
+}
+
+// ≥2 个同父节点建组：组 bounds = 成员 union（父空间 AABB，未做旋转分解）；
+// 成员 reparent 到组（相对坐标 = 原坐标 − 组原点）；组插在最高 z 序成员之后。
+// 校验失败（单节点/跨父/含 board/含不存在 id/父缺失）返回 null
+export function groupNodes(
+  doc: SceneDocument,
+  ids: readonly string[],
+): GroupNodesResult | null {
+  const picked: SceneNode[] = []
+  const seen = new Set<string>()
+  for (const id of ids) {
+    if (seen.has(id)) continue
+    seen.add(id)
+    if (id === BOARD_NODE_ID) return null
+    const node = doc.nodes.find((candidate) => candidate.id === id)
+    if (!node) return null
+    picked.push(node)
+  }
+  if (picked.length < 2) return null
+  const parentId = picked[0].parentId
+  if (!parentId || picked.some((node) => node.parentId !== parentId)) return null
+
+  let minX = Infinity
+  let minY = Infinity
+  let maxX = -Infinity
+  let maxY = -Infinity
+  for (const node of picked) {
+    minX = Math.min(minX, node.x)
+    minY = Math.min(minY, node.y)
+    maxX = Math.max(maxX, node.x + node.width)
+    maxY = Math.max(maxY, node.y + node.height)
+  }
+  const group: SceneNode = {
+    id: nextGroupId(doc.nodes),
+    kind: "group",
+    type: "group",
+    parentId,
+    x: minX,
+    y: minY,
+    width: maxX - minX,
+    height: maxY - minY,
+  }
+
+  const memberIds = new Set(picked.map((node) => node.id))
+  const out: SceneNode[] = []
+  let insertAt = -1
+  for (const node of doc.nodes) {
+    if (memberIds.has(node.id)) {
+      out.push({ ...node, parentId: group.id, x: node.x - minX, y: node.y - minY })
+      // 组插在最高 z 序成员（数组中最后一位成员）之后
+      insertAt = out.length
+    } else {
+      out.push(node)
+    }
+  }
+  out.splice(insertAt, 0, group)
+  return { doc: { ...doc, nodes: out }, groupId: group.id }
+}
+
+// 解组：成员坐标加回组原点、parentId 还原为组的父级、占据组在数组中的原
+// 位置（z 序守恒）；返回还原的成员 id（数组顺序）。groupId 不存在 / 非
+// group 类型 / 空组返回 null
+export function ungroupNodes(
+  doc: SceneDocument,
+  groupId: string,
+): UngroupNodesResult | null {
+  const group = doc.nodes.find((node) => node.id === groupId)
+  if (!group || group.type !== "group" || group.id === BOARD_NODE_ID) return null
+  const restored: SceneNode[] = []
+  for (const node of doc.nodes) {
+    if (node.parentId !== groupId) continue
+    restored.push({
+      ...node,
+      parentId: group.parentId,
+      x: node.x + group.x,
+      y: node.y + group.y,
+    })
+  }
+  if (!restored.length) return null
+
+  const memberIds = new Set(restored.map((node) => node.id))
+  const out: SceneNode[] = []
+  for (const node of doc.nodes) {
+    if (memberIds.has(node.id)) continue
+    if (node.id === groupId) {
+      // 成员占回组的数组位置（保持相对顺序，z 序 = 组原位置）
+      out.push(...restored)
+      continue
+    }
+    out.push(node)
+  }
+  return { doc: { ...doc, nodes: out }, ids: restored.map((node) => node.id) }
+}

package/src/components/design/canvas/document/history.ts

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import type { SceneDocument } from "./types"
+
+const LIMIT = 50
+
+export class SceneHistory {
+  private past: SceneDocument[] = []
+  private future: SceneDocument[] = []
+
+  push(snapshot: SceneDocument) {
+    this.past.push(snapshot)
+    if (this.past.length > LIMIT) this.past.shift()
+    this.future = []
+  }
+
+  reset() {
+    this.past = []
+    this.future = []
+  }
+
+  undo(current: SceneDocument): SceneDocument | null {
+    const prev = this.past.pop()
+    if (!prev) return null
+    this.future.push(current)
+    return prev
+  }
+
+  redo(current: SceneDocument): SceneDocument | null {
+    const next = this.future.pop()
+    if (!next) return null
+    this.past.push(current)
+    return next
+  }
+
+  get canUndo() {
+    return this.past.length > 0
+  }
+
+  get canRedo() {
+    return this.future.length > 0
+  }
+}

package/src/components/design/canvas/document/layer-order.ts

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+import type { SceneNode } from "./types"
+
+export type LayerOrderOp = "front" | "forward" | "backward" | "back"
+
+// 同父兄弟内重排选中节点的 z 序（数组顺序即渲染层级，靠后者在上）：
+// front=置顶 forward=上移一层 backward=下移一层 back=置底；
+// 无法移动（已在边界）返回 null，调用方据此跳过 history/applyScene。
+// board 节点不参与；不同 parentId 的节点互为无关兄弟，各自仅在同组内移动。
+export function reorderNodesDoc(
+  nodes: readonly SceneNode[],
+  ids: readonly string[],
+  op: LayerOrderOp,
+): SceneNode[] | null {
+  if (!ids.length) return null
+  const groups = new Map<string, { items: SceneNode[]; indexes: number[] }>()
+  for (let i = 0; i < nodes.length; i++) {
+    const node = nodes[i]
+    const key = node.parentId ?? ""
+    let group = groups.get(key)
+    if (!group) {
+      group = { items: [], indexes: [] }
+      groups.set(key, group)
+    }
+    group.items.push(node)
+    group.indexes.push(i)
+  }
+  const out = [...nodes]
+  let changed = false
+  for (const id of ids) {
+    const node = nodes.find((item) => item.id === id)
+    if (!node) continue
+    const group = groups.get(node.parentId ?? "")
+    if (!group) continue
+    const siblings = [...group.items]
+    const at = siblings.findIndex((item) => item.id === id)
+    if (at < 0) continue
+    let to: number
+    switch (op) {
+      case "front":
+        to = siblings.length - 1
+        break
+      case "back":
+        to = 0
+        break
+      case "forward":
+        to = Math.min(at + 1, siblings.length - 1)
+        break
+      case "backward":
+      default:
+        to = Math.max(at - 1, 0)
+        break
+    }
+    if (to === at) continue
+    const [moved] = siblings.splice(at, 1)
+    siblings.splice(to, 0, moved)
+    for (let s = 0; s < siblings.length; s++) {
+      out[group.indexes[s]] = siblings[s]
+    }
+    changed = true
+  }
+  return changed ? out : null
+}

package/src/components/design/canvas/document/reconcile.ts

@@ -0,0 +1,216 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+// R1 增量更新：对比上次应用的 SceneDocument 与目标 SceneDocument，产出
+// 局部操作计划（增/删/patch/重排/标签），消除全量重建（docToScene + 清空
+// tree.children + 重挂）带来的选中丢失与事件乱序。
+// 纯函数无 leafer 依赖——应用侧在 engine（持有 tree/sky/mod）。
+
+import { projectedNode } from "./style/style-mapper"
+import { BOARD_NODE_ID, type SceneDocument, type SceneNode } from "./types"
+
+export type SceneDiffPlan = {
+  // 需新建并挂载的节点（父在 next 中，按 nodes 顺序先父后子）
+  toAdd: SceneNode[]
+  // 需从树移除的 leaf id（含后代；deleteSelectedNodes 已递归收集）
+  toRemove: string[]
+  // 保留节点中投影发生变化的：leaf.set(leafConfigOf(node)) 的目标 id
+  toPatch: string[]
+  // 兄弟顺序与 next.nodes 不一致（需按 next 顺序重排各父的孩子）
+  orderChanged: boolean
+  // board 宽高变化
+  boardSize: { width: number; height: number } | null
+  // 名称标签：新增（顶层 frame 且有 name）/ 移除 / 改名
+  labelsAdd: SceneNode[]
+  labelsRemove: string[]
+  labelsRename: { id: string; name: string }[]
+}
+
+// 影响 leaf 渲染/几何/状态的投影签名（不含 parentId——结构变化单独处理）
+function projectionOf(node: SceneNode): unknown {
+  const projected = projectedNode(node)
+  return [
+    projected.x,
+    projected.y,
+    projected.width,
+    projected.height,
+    node.rotation ?? null,
+    node.name ?? null,
+    node.visible ?? true,
+    node.locked === true,
+    projected.style ?? null,
+    node.props?.text ?? null,
+    node.props?.path ?? null,
+    node.props?.font ?? null,
+  ]
+}
+
+// 结构化字段（FS-6.1）：live 在 node 顶层、不随 patch 重建 style 引用，
+// 但均会进入投影产物（projectedNode → style.fill/stroke/cornerRadius/blendMode），
+// 引用变化即可能影响渲染——必须与 style 引用一样触发慢路径序列化比较
+function structuredRefsOf(node: SceneNode): unknown[] {
+  return [node.fills, node.strokes, node.effects, node.corners, node.blendMode]
+}
+
+// 快速路径：mergeNodePatch 对未选中节点保留原对象引用，1 万节点文档的
+// patch 只有个位数字段变化——引用级比较 O(1) 跳过绝大多数节点，
+// 慢路径（投影序列化）仅在引用不同时兜底（约束传播/对象重建场景）
+function fastSameProjection(a: SceneNode, b: SceneNode): boolean {
+  if (a === b) return true
+  if (
+    a.x !== b.x ||
+    a.y !== b.y ||
+    a.width !== b.width ||
+    a.height !== b.height ||
+    (a.rotation ?? null) !== (b.rotation ?? null) ||
+    (a.name ?? null) !== (b.name ?? null) ||
+    (a.visible ?? true) !== (b.visible ?? true) ||
+    (a.locked === true) !== (b.locked === true)
+  ) {
+    return false
+  }
+  const aStyle = a.style ?? null
+  const bStyle = b.style ?? null
+  const aStructured = structuredRefsOf(a)
+  const bStructured = structuredRefsOf(b)
+  if (aStyle !== bStyle || aStructured.some((value, i) => value !== bStructured[i])) {
+    // 引用不同才需要序列化比较（约束传播可能重建 style；fills/strokes 等
+    // 结构化 patch 只换数组引用）。投影产物是权威：内容一致的重建在此
+    // 判定为相同（不误报），内容变化判定为不同（进 toPatch → leaf.set）
+    if (JSON.stringify(projectionOf(a)) !== JSON.stringify(projectionOf(b))) return false
+  }
+  const aProps = a.props
+  const bProps = b.props
+  if (aProps !== bProps) {
+    // props 全量内容比较：除 text/path/font 外还承载 FS-2.4 图形原生参数
+    // （sides/corners/innerRadius/startArrow/endArrow 等，白名单直传 leaf
+    // config）。此前只比较 text/path/font，面板图形参数 patch 被误判
+    // 「无变化」→ 不进 toPatch → 画布不重绘（与 fills/strokes 缺陷同类）。
+    // props 为小对象且仅在引用变化时才序列化，键序漂移只多付一次幂等
+    // leaf.set，无正确性风险
+    if (JSON.stringify(aProps ?? null) !== JSON.stringify(bProps ?? null)) {
+      return false
+    }
+  }
+  return true
+}
+
+function sameProjection(a: SceneNode, b: SceneNode): boolean {
+  return fastSameProjection(a, b)
+}
+
+export function planSceneDiff(prev: SceneDocument, next: SceneDocument): SceneDiffPlan {
+  const prevById = new Map(prev.nodes.map((node) => [node.id, node]))
+  const nextById = new Map(next.nodes.map((node) => [node.id, node]))
+
+  const toAdd: SceneNode[] = []
+  const toRemove: string[] = []
+  const toPatch: string[] = []
+  const labelsAdd: SceneNode[] = []
+  const labelsRemove: string[] = []
+  const labelsRename: { id: string; name: string }[] = []
+
+  const isLabeled = (node: SceneNode): boolean =>
+    node.type === "frame" &&
+    typeof node.name === "string" &&
+    node.name.length > 0 &&
+    (node.parentId === null || node.parentId === BOARD_NODE_ID)
+
+  for (const node of next.nodes) {
+    if (node.id === BOARD_NODE_ID) continue
+    const before = prevById.get(node.id)
+    if (!before) {
+      toAdd.push(node)
+      if (isLabeled(node)) labelsAdd.push(node)
+      continue
+    }
+    if (before.parentId !== node.parentId) {
+      // 结构变化（re-parent）：leaf 引用保留，几何走 patch（doc 坐标已权威）
+      toPatch.push(node.id)
+    } else if (!sameProjection(before, node)) {
+      toPatch.push(node.id)
+    }
+    // 名称标签状态
+    const wasLabeled = isLabeled(before)
+    const nowLabeled = isLabeled(node)
+    if (wasLabeled && !nowLabeled) labelsRemove.push(node.id)
+    else if (!wasLabeled && nowLabeled) labelsAdd.push(node)
+    else if (
+      nowLabeled &&
+      before.name !== node.name &&
+      before.parentId === node.parentId
+    ) {
+      labelsRename.push({ id: node.id, name: node.name as string })
+    }
+  }
+
+  for (const node of prev.nodes) {
+    if (node.id === BOARD_NODE_ID) continue
+    if (!nextById.has(node.id)) {
+      toRemove.push(node.id)
+      if (isLabeled(node)) labelsRemove.push(node.id)
+    }
+  }
+
+  // 兄弟顺序：单次扫描建 parentId → id 序列索引（O(n)），再逐父比较
+  let orderChanged = false
+  const seqPrev = new Map<string, string[]>()
+  const seqNext = new Map<string, string[]>()
+  for (const node of prev.nodes) {
+    if (node.id === BOARD_NODE_ID) continue
+    const parentId = node.parentId ?? BOARD_NODE_ID
+    const list = seqPrev.get(parentId)
+    if (list) list.push(node.id)
+    else seqPrev.set(parentId, [node.id])
+  }
+  for (const node of next.nodes) {
+    if (node.id === BOARD_NODE_ID) continue
+    const parentId = node.parentId ?? BOARD_NODE_ID
+    const list = seqNext.get(parentId)
+    if (list) list.push(node.id)
+    else seqNext.set(parentId, [node.id])
+  }
+  for (const [parentId, nextSeq] of seqNext) {
+    if (JSON.stringify(seqPrev.get(parentId)) !== JSON.stringify(nextSeq)) {
+      orderChanged = true
+      break
+    }
+  }
+
+  // board 尺寸（board 恒为 nodes[0]）
+  const nextBoard = next.nodes[0]
+  const prevBoard = prev.nodes[0]
+  let boardSize: { width: number; height: number } | null = null
+  if (
+    nextBoard &&
+    prevBoard &&
+    (nextBoard.width !== prevBoard.width || nextBoard.height !== prevBoard.height)
+  ) {
+    boardSize = { width: nextBoard.width, height: nextBoard.height }
+  }
+
+  return {
+    toAdd,
+    toRemove,
+    toPatch,
+    orderChanged,
+    boardSize,
+    labelsAdd,
+    labelsRemove,
+    labelsRename,
+  }
+}