@allbluecn/web-app 0.17.1 → 0.18.0

package/src/design-engine/document/serialize-leafer-json.ts

@@ -0,0 +1,185 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import type { ILeaf } from "leafer-editor"
+
+import { SHADER_URL_PREFIX } from "@/components/design/canvas/document/style/paints"
+import type {
+  ExportPreset,
+  NodeConstraints,
+  NodePaint,
+  NodeStroke,
+  RefCorner,
+} from "@/components/design/canvas/document/style/paints"
+import { createEmptyDoc, isSceneDocument, type DeviceType, type SceneDocument, type SceneNode } from "@/components/design/canvas/document/types"
+import { deepCloneSafe, isRecord } from "./serialize-shared"
+import { leaferToDoc } from "./serialize-read"
+import { sanitizeScene } from "./serialize-sanitize"
+
+// ===== 官方 JSON 权威持久化格式（R2） =====
+//
+// DB 存 { format: "leafer-json", meta, tree, extensions? }：
+// - tree 是 leafer tree.toJSON() 原生产物（tag/children 嵌套树），读侧用
+//   leaferToDoc 复用既有「官方树 → SceneDocument」转换
+// - leafer toJSON 不承载自研扩展字段（实测 props/constraints 会被丢弃），
+//   业务包装字段（AI props/约束/导出预设等）放 extensions: nodeId → 字段
+// - 旧格式（SceneDocument 扁平 nodes）读时惰性迁移：normalizeSceneDocument
+//   双格式识别，保存写回新格式；历史版本/分享快照不迁移，读时兼容渲染
+
+export type SceneNodeExtensions = {
+  props?: Record<string, unknown>
+  overrides?: Record<string, unknown>
+  exports?: ExportPreset[]
+  constraints?: NodeConstraints
+  aspectLocked?: boolean
+  refCorner?: RefCorner
+  /** 用户锁定态（FS-5.3）：frame.locked 不投影 leaf，经 extensions 持久化 */
+  locked?: boolean
+  /**
+   * 结构化 fills 事实源（FS-7.4）：仅当节点含可见 shader paint 时持久化——
+   * tree 的 leafer://shader/ url 无法承载 shaderId/props/speed；整组保存
+   * 顺带保住同节点其他层的不可见投影
+   */
+  fills?: SceneNode["fills"]
+  /** 同 fills：仅当节点 strokes 含可见 shader paint 时持久化 */
+  strokes?: SceneNode["strokes"]
+}
+
+export type LeaferJSONPackage = {
+  format: "leafer-json"
+  version: 1
+  meta: { device?: DeviceType; background?: string }
+  tree: Record<string, unknown>
+  extensions?: Record<string, SceneNodeExtensions>
+}
+
+export function isLeaferJSONPackage(v: unknown): v is LeaferJSONPackage {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return false
+  const p = v as Partial<LeaferJSONPackage>
+  return p.format === "leafer-json" && p.version === 1 && !!p.tree && typeof p.tree === "object"
+}
+
+const EXTENSION_KEYS: readonly (keyof SceneNodeExtensions)[] = [
+  "props",
+  "overrides",
+  "exports",
+  "constraints",
+  "aspectLocked",
+  "refCorner",
+  "locked",
+  "fills",
+  "strokes",
+]
+
+// 节点是否含可见 shader paint（写侧 extensions.fills/strokes 的持久化门槛）：
+// 与 projectStyle 投影口径一致（可见层才产生 leafer://shader/ url）。
+// fills 传 NodePaint[]、strokes 传 NodeStroke[]（paint 嵌套一层）
+function hasVisibleShaderPaint(list: SceneNode["fills"] | SceneNode["strokes"]): boolean {
+  if (!Array.isArray(list)) return false
+  return list.some((item) => {
+    if (!item || typeof item !== "object") return false
+    const paint = "paint" in item ? (item as NodeStroke).paint : (item as unknown as NodePaint)
+    return paint?.type === "shader" && item.visible !== false && paint.visible !== false
+  })
+}
+
+// tree 投影产物中是否存在 shader url（读侧 extensions 优先恢复的判定标记，
+// FS-7.4：避免 leafer://shader/ url 失效后 ShaderPaint 结构丢失）
+function hasShaderUrlPaint(value: unknown): boolean {
+  return (
+    Array.isArray(value) &&
+    value.some((item) => {
+      if (!item || typeof item !== "object" || Array.isArray(item)) return false
+      const url = (item as { url?: unknown }).url
+      return typeof url === "string" && url.startsWith(SHADER_URL_PREFIX)
+    })
+  )
+}
+
+// 官方 JSON 权威导出：tree.toJSON() 为数据源，业务扩展字段从 SceneDocument
+// 收集进 extensions（nodeId → 字段），meta 随包装层保留。
+// ⚠ 根节点（zoomLayer）的视图变换字段（x/y/scaleX/scaleY/rotation/skewX/skewY）
+// 必须剥离：zoomLayer 即 tree，官方缩放/平移写在其属性上，不剥离会把「用户
+// 当时的视图状态」污染进持久化数据（实测 71% 缩放保存 → scaleX 0.708 入库）
+const VIEWPORT_ROOT_KEYS = new Set(["x", "y", "scaleX", "scaleY", "rotation", "skewX", "skewY"])
+
+export function exportLeaferJSON(doc: SceneDocument, tree: ILeaf): LeaferJSONPackage {
+  const raw =
+    (tree as unknown as { toJSON?: () => Record<string, unknown> }).toJSON?.() ?? {}
+  for (const key of VIEWPORT_ROOT_KEYS) delete raw[key]
+  const extensions: Record<string, SceneNodeExtensions> = {}
+  for (const node of doc.nodes) {
+    const ext: Record<string, unknown> = {}
+    for (const key of EXTENSION_KEYS) {
+      // locked 仅 frame 经 extensions 持久化：非 frame 的 locked/visible 已由
+      // leaf 属性进 tree JSON，extensions 重复收集只会放大持久化体积
+      if (key === "locked" && node.type !== "frame") continue
+      // fills/strokes 仅含可见 shader paint 时整组持久化（FS-7.4 事实源）；
+      // 无 shader 的节点 tree 投影已足够，重复收集只放大体积
+      if (key === "fills" && !hasVisibleShaderPaint(node.fills)) continue
+      if (key === "strokes" && !hasVisibleShaderPaint(node.strokes)) continue
+      const value = (node as unknown as Record<string, unknown>)[key]
+      if (value !== undefined) ext[key] = value
+    }
+    if (Object.keys(ext).length) extensions[node.id] = ext as SceneNodeExtensions
+  }
+  const pkg: LeaferJSONPackage = {
+    format: "leafer-json",
+    version: 1,
+    meta: { ...doc.meta },
+    tree: (deepCloneSafe(raw) ?? {}) as Record<string, unknown>,
+  }
+  if (Object.keys(extensions).length) pkg.extensions = extensions
+  return pkg
+}
+
+// 官方 JSON → SceneDocument（运行时业务包装）：复用 leaferToDoc 读侧
+// （其输入本就是 toJSON 产物形态），extensions 回填后统一 sanitize
+export function parseLeaferJSON(pkg: LeaferJSONPackage): SceneDocument {
+  const doc = leaferToDoc(pkg.tree as unknown as ILeaf, { device: pkg.meta?.device })
+  if (pkg.meta?.background !== undefined) doc.meta.background = pkg.meta.background
+  if (pkg.extensions) {
+    for (const node of doc.nodes) {
+      const ext = pkg.extensions[node.id]
+      if (!ext) continue
+      for (const key of EXTENSION_KEYS) {
+        const value = (ext as Record<string, unknown>)[key]
+        if (value === undefined) continue
+        // fills/strokes 是 shader 的恢复通道（FS-7.4）：tree 投影 url 以
+        // leafer://shader/ 开头时整组优先取 extensions（shaderId/props/speed
+        // 完整恢复），withField 的「已定义跳过」语义让 normalizeNode 不再逐条
+        // 还原；无 shader url 的节点不回填，维持 tree 逐条还原口径
+        if (key === "fills" && !hasShaderUrlPaint(node.style?.fill)) continue
+        if (key === "strokes" && !hasShaderUrlPaint(node.style?.stroke)) continue
+        ;(node as unknown as Record<string, unknown>)[key] = value
+      }
+    }
+  }
+  return sanitizeScene(doc)
+}
+
+// 旧钢笔类型惰性迁移（FS-2.4）：pen-path → path（Polygon/Star 独立成型后，
+// path 是唯一矢量路径类型）。挂在 normalizeSceneDocument 入口且先于 sanitize
+// 守卫执行（守卫前收口，与 P1 migrateNodePaints 同原则）：旧类型字符串先改写
+// 再进守卫链，避免旧数据被未来按类型过滤的守卫丢弃；无 pen-path 节点时原
+// 引用返回（幂等、零开销）。props.path / style 原样保留
+function migrateRawPenPathTypes(raw: unknown): unknown {
+  if (!isRecord(raw)) return raw
+  const rawNodes = raw.nodes
+  if (!Array.isArray(rawNodes)) return raw
+  let changed = false
+  const nodes = rawNodes.map((item) => {
+    if (!isRecord(item) || item.type !== "pen-path") return item
+    changed = true
+    return { ...item, type: "path" }
+  })
+  return changed ? { ...raw, nodes } : raw
+}
+
+// 读时惰性迁移统一入口：新格式（leafer-json）→ parseLeaferJSON；旧格式
+// （SceneDocument，含历史版本/分享快照/AI 生成）→ sanitizeScene；脏数据 →
+// 空文档。所有持久化读点（编辑器加载/分享页/版本回滚）必须经此收敛
+export function normalizeSceneDocument(raw: unknown): SceneDocument {
+  if (isLeaferJSONPackage(raw)) return parseLeaferJSON(raw)
+  if (isSceneDocument(raw)) return sanitizeScene(migrateRawPenPathTypes(raw))
+  return createEmptyDoc()
+}

package/src/design-engine/document/serialize-read.ts

@@ -0,0 +1,293 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import type { ILeaf } from "leafer-editor"
+
+import {
+  BOARD_NODE_ID,
+  type DeviceType,
+  type SceneDocument,
+  type SceneNode,
+  type SceneNodeKind,
+  type SceneNodeType,
+} from "@/components/design/canvas/document/types"
+import { STRUCTURED_KEYS } from "@/components/design/canvas/document/style/paints"
+import {
+  deepCloneSafe,
+  toNumber,
+  type DescNode,
+} from "./serialize-shared"
+import { SHAPE_PROP_KEYS } from "./serialize-write"
+
+export type DocSceneResult = {
+  leafer: ILeaf
+  nodeIndex: Map<string, ILeaf>
+}
+
+const STYLE_EXCLUDE = new Set([
+  "id",
+  "children",
+  "x",
+  "y",
+  "width",
+  "height",
+  "visible",
+  "lock",
+  "locked",
+  "edit",
+  "skipJSON",
+  "tag",
+  "name",
+  "className",
+  "hittable",
+  "innerId",
+  "zIndex",
+  "text",
+  "path",
+  "font",
+  // 效果投影产物：canonical 存 node.effects，读回 style 会在删除效果后残留陈旧副本
+  "shadow",
+  "innerShadow",
+  "blur",
+  "backgroundBlur",
+])
+
+const PROP_KEYS = ["text", "path", "font"] as const
+
+const TAG_TYPE: Record<string, SceneNodeType> = {
+  Leafer: "board",
+  Group: "group",
+  Box: "group",
+  Frame: "group",
+  Rect: "rect",
+  Image: "rect",
+  Canvas: "rect",
+  Ellipse: "ellipse",
+  Line: "line",
+  Arrow: "arrow",
+  Text: "text",
+  // FS-2.4 精确映射：Path/Polygon/Star 各自成型，不再归一 pen-path；
+  // Pen 是笔迹录制器（不入序列化），历史树兜底映射为 path
+  Path: "path",
+  Pen: "path",
+  Polygon: "polygon",
+  Star: "star",
+}
+
+const GROUP_TAGS = new Set(["Group", "Box", "Frame"])
+
+const AUTO_ID_RE = /^\d+(?:_\d+)*$/
+
+function inferType(desc: DescNode): { kind: SceneNodeKind; type: SceneNodeType } {
+  const tag = typeof desc.tag === "string" ? desc.tag : undefined
+  if (tag) {
+    const type = TAG_TYPE[tag]
+    if (!type) return { kind: "shape", type: "rect" }
+    if (tag === "Leafer") return { kind: "group", type: "board" }
+    if (tag === "Frame") return { kind: "group", type: "frame" }
+    if (GROUP_TAGS.has(tag)) return { kind: "group", type: "group" }
+    return { kind: "shape", type }
+  }
+  if (Array.isArray(desc.children) && desc.children.length > 0) {
+    return { kind: "group", type: "group" }
+  }
+  if (
+    desc.text !== undefined ||
+    desc.font !== undefined ||
+    desc.fontSize !== undefined ||
+    desc.fontWeight !== undefined ||
+    desc.lineHeight !== undefined ||
+    desc.fontFamily !== undefined
+  ) {
+    return { kind: "shape", type: "text" }
+  }
+  if (typeof desc.path === "string") {
+    return { kind: "shape", type: "path" }
+  }
+  if (desc.ellipse !== undefined || desc.arc !== undefined || desc.arcClockwise !== undefined) {
+    return { kind: "shape", type: "ellipse" }
+  }
+  if (desc.strokeWidth !== undefined && (desc.fill === undefined || desc.fill === null)) {
+    return { kind: "shape", type: "line" }
+  }
+  return { kind: "shape", type: "rect" }
+}
+
+function isComponentGroup(children: DescNode[]): boolean {
+  return children.some((child) => child.editable === false || child.edit === false)
+}
+
+function descToNode(
+  desc: DescNode,
+  parentId: string | null,
+  idGen: () => string,
+  preserveIndex?: Map<string, SceneNode>,
+): SceneNode {
+  // SAFETY: leafer toJSON 的 children 是无类型的任意节点描述，
+  // 已先用 Array.isArray 收窄后才断言为 DescNode[]，字段在后续读取处均做类型守卫
+  const children = Array.isArray(desc.children) ? (desc.children as DescNode[]) : []
+  const inferred = inferType(desc)
+  let kind = inferred.kind
+  const type = inferred.type
+  if (kind === "group" && isComponentGroup(children)) {
+    kind = "component"
+  }
+  const rawId = typeof desc.id === "string" && desc.id ? desc.id : undefined
+  const id = rawId && !AUTO_ID_RE.test(rawId) ? rawId : idGen()
+  const style: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(desc)) {
+    if (STYLE_EXCLUDE.has(key) || value === undefined) continue
+    style[key] = value
+  }
+  const props: Record<string, unknown> = {}
+  for (const key of PROP_KEYS) {
+    if (desc[key] !== undefined) props[key] = desc[key]
+  }
+  const node: SceneNode = {
+    id,
+    kind,
+    type,
+    parentId,
+    x: toNumber(desc.x),
+    y: toNumber(desc.y),
+    width: toNumber(desc.width),
+    height: toNumber(desc.height),
+    style,
+    props,
+  }
+  // 读侧对称回收（与写侧 node.rotation / node.props 双权威通道对应）：
+  // leafer toJSON 把 rotation 与图形原生参数放在节点描述顶层，上面的 style
+  // 收集会把它们一并落 style——若不提升，则「旋转→回读→redo」场景 rotation
+  // 丢失（buildElement 全量重建只认 node.rotation）、props 权威通道断链
+  //（面板回显缺省、增量 patch 白名单无源可写）
+  if (typeof style.rotation === "number" && Number.isFinite(style.rotation)) {
+    node.rotation = style.rotation
+    // 单一事实源：写侧投影从不经 style 传 rotation，删除避免双源漂移
+    delete style.rotation
+  }
+  // 图形参数：style → props 恢复（style 保留——polygon/star/line 工厂全量
+  // 重建消费 style 通道，双通道幂等）。cornerRadius 例外：它同时是
+  // node.corners 的投影产物（rect/ellipse 圆角联动），提升会在回读后让
+  // props.cornerRadius 成为陈旧第二源、反向覆盖后续 corners 编辑，故不提升
+  //（面板回显与工厂重建经 style 回退/直读均正确）
+  for (const key of SHAPE_PROP_KEYS) {
+    if (key === "cornerRadius") continue
+    const value = style[key]
+    if (value !== undefined && props[key] === undefined) props[key] = value
+  }
+  if (typeof desc.name === "string") node.name = desc.name
+  if (desc.visible !== undefined) node.visible = desc.visible === true
+  if (
+    desc.locked === true ||
+    desc.lock === true ||
+    desc.edit === false ||
+    desc.editable === false
+  ) {
+    node.locked = true
+  }
+  const prev = preserveIndex?.get(node.id)
+  if (prev) {
+    for (const key of STRUCTURED_KEYS) {
+      // SAFETY: prev 与 node 同为 SceneNode，STRUCTURED_KEYS 均为其可选字段，
+      // 仅类型上因索引签名缺失需经 Record 读写
+      const value = (prev as unknown as Record<string, unknown>)[key]
+      if (value !== undefined) {
+        Object.assign(node, { [key]: value })
+      }
+    }
+  }
+  if (node.type === "frame") {
+    // frame 的 editable:false 是画板结构态（写侧恒关、非用户锁定），上面的
+    // editable:false → locked 推导对 frame 全体误伤。frame.locked 不投影 leaf
+    // （P0：框选剪枝子树），锁定态只能来自 preserveFrom（引擎读回
+    // preserveFrom=currentDoc）或 extensions 回填（parseLeaferJSON）
+    node.locked = prev?.locked === true ? true : undefined
+  }
+  return node
+}
+
+function walkDesc(
+  desc: DescNode,
+  parentId: string,
+  out: SceneNode[],
+  idGen: () => string,
+  preserveIndex?: Map<string, SceneNode>,
+) {
+  const children = Array.isArray(desc.children) ? (desc.children as DescNode[]) : []
+  for (const child of children) {
+    if (!child || typeof child !== "object" || child.skipJSON === true) continue
+    const node = descToNode(child, parentId, idGen, preserveIndex)
+    out.push(node)
+    walkDesc(child, node.id, out, idGen, preserveIndex)
+  }
+}
+
+export function leaferToDoc(
+  leafer: ILeaf,
+  opts?: { device?: DeviceType; preserveFrom?: SceneDocument },
+): SceneDocument {
+  const raw =
+    typeof (leafer as { toJSON?: () => unknown }).toJSON === "function"
+      ? (leafer as { toJSON: () => unknown }).toJSON()
+      : leafer
+  const root = (deepCloneSafe(raw) ?? {}) as DescNode
+  const counter = { n: 0 }
+  const idGen = () => `n_${++counter.n}`
+  const nodes: SceneNode[] = []
+  const preserveIndex = new Map<string, SceneNode>()
+  if (opts?.preserveFrom) {
+    for (const prev of opts.preserveFrom.nodes) preserveIndex.set(prev.id, prev)
+  }
+
+  // 优先从 tree 的直接子元素中找 board（docToScene 会给 board Group 设置
+  // id=BOARD_NODE_ID）。board 作为子元素时从它读取尺寸与子树，tree 自身的
+  // 尺寸跟随容器（autoLayout），不再写入 board，避免容器尺寸污染入库。
+  const rootChildren = Array.isArray(root.children) ? (root.children as DescNode[]) : []
+  const boardDesc = rootChildren.find(
+    (child) => child && typeof child === "object" && child.id === BOARD_NODE_ID,
+  )
+
+  if (boardDesc) {
+    const board = descToNode(boardDesc, null, idGen, preserveIndex)
+    board.id = BOARD_NODE_ID
+    board.kind = "group"
+    board.type = "board"
+    board.parentId = null
+    if (board.style) delete (board.style as Record<string, unknown>).fill
+    nodes.push(board)
+    walkDesc(boardDesc, BOARD_NODE_ID, nodes, idGen, preserveIndex)
+  } else {
+    // 兼容旧结构 / 测试 mock：root 自身即 board
+    const source = leafer as { width?: number; height?: number }
+    if (root.width === undefined) root.width = source.width
+    if (root.height === undefined) root.height = source.height
+    const board = descToNode(root, null, idGen, preserveIndex)
+    board.id = BOARD_NODE_ID
+    board.kind = "group"
+    board.type = "board"
+    board.parentId = null
+    board.x = 0
+    board.y = 0
+    if (board.style) delete (board.style as Record<string, unknown>).fill
+    nodes.push(board)
+    walkDesc(root, BOARD_NODE_ID, nodes, idGen, preserveIndex)
+  }
+
+  // 翻转节点坐标规范化：Leafer 的 scaleX/scaleY 为负时绕自身左上角翻转，
+  // 视觉框为 [x-width, x]；统一转换为「doc 层 x/y = 视觉左/上边界」不变式，
+  // 使对齐/分布/属性面板等几何计算与视觉一致（与 docToScene 写侧对称）。
+  // （frame.locked 的读侧处理在 descToNode：从 preserveFrom 恢复，不再剥离——
+  // 写侧已不投影 frame.locked 到 leaf，P0 剪枝根源已消除）
+  for (const node of nodes) {
+    if (node.id === BOARD_NODE_ID) continue
+    const sx = node.style?.scaleX
+    if (typeof sx === "number" && sx < 0) node.x -= node.width
+    const sy = node.style?.scaleY
+    if (typeof sy === "number" && sy < 0) node.y -= node.height
+  }
+
+  return {
+    version: 1,
+    meta: { device: opts?.device ?? "desktop" },
+    nodes,
+  }
+}

package/src/design-engine/document/serialize-sanitize.ts

@@ -0,0 +1,144 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import { migrateNodePaints, normalizeScene } from "@/components/design/canvas/document/style/style-migrate"
+import {
+  isExportPreset,
+  isNodeConstraints,
+  isNodeEffect,
+  isNodePaint,
+  isNodeStroke,
+} from "@/components/design/canvas/document/style/paints"
+import {
+  BOARD_NODE_ID,
+  createBoardNode,
+  createEmptyDoc,
+  type SceneDocument,
+  type SceneNode,
+} from "@/components/design/canvas/document/types"
+import { deepCloneSafe, isKind, isRecord, SCENE_SOFT_LIMIT, toNumber } from "./serialize-shared"
+
+function sanitizeNode(raw: unknown, idGen: () => string, seen: Set<string>): SceneNode | null {
+  if (!isRecord(raw)) return null
+  const hasId = typeof raw.id === "string" && raw.id.length > 0
+  const hasType = typeof raw.type === "string" && raw.type.length > 0
+  if (!hasId && !hasType) return null
+  let id = hasId ? (raw.id as string) : idGen()
+  if (seen.has(id)) id = `${id}_${idGen().slice(2)}`
+  seen.add(id)
+  const style = isRecord(raw.style) ? raw.style : {}
+  const props = isRecord(raw.props) ? raw.props : {}
+  const node: SceneNode = {
+    id,
+    kind: isKind(raw.kind) ? raw.kind : "shape",
+    type: typeof raw.type === "string" && raw.type ? raw.type : "rect",
+    parentId: typeof raw.parentId === "string" ? raw.parentId : null,
+    x: toNumber(raw.x),
+    y: toNumber(raw.y),
+    width: toNumber(raw.width),
+    height: toNumber(raw.height),
+    style,
+    props,
+  }
+  if (typeof raw.name === "string") node.name = raw.name
+  if (typeof raw.rotation === "number" && Number.isFinite(raw.rotation)) node.rotation = raw.rotation
+  if (typeof raw.zIndex === "number" && Number.isFinite(raw.zIndex)) node.zIndex = raw.zIndex
+  if (typeof raw.locked === "boolean") node.locked = raw.locked
+  if (typeof raw.visible === "boolean") node.visible = raw.visible
+  // 历史数据清洗：早期实现把运行时交互状态（frame 的 editable/hitSelf/locked）
+  // roundtrip 进了 style，这些值会在 docToScene 写回 leaf，触发
+  // __clipAfterFill 子树剪枝，画板内元素全部不可选中。交互态不入 style，
+  // 加载入口统一剥离。
+  // frame 顶层 locked 不再剥离（2026-10-01 起 frame.locked 是用户锁定态，
+  // 由锁定/解锁命令写入；写侧已不投影 frame.locked 到 leaf，P0 剪枝根源消除）
+  if (node.type === "frame") {
+    delete style.editable
+    delete style.hitSelf
+    delete style.locked
+  }
+  if (isRecord(raw.overrides)) node.overrides = raw.overrides
+  if (Array.isArray(raw.fills)) {
+    const fills = raw.fills.filter(isNodePaint)
+    if (fills.length) node.fills = fills
+  }
+  if (Array.isArray(raw.strokes)) {
+    // v1 旧描边（顶层 color/align）先惰性迁移为 paint 嵌套结构（含
+    // style.strokeAlign 回填）再走守卫清洗；新结构原引用透传（幂等）
+    const migrated = migrateNodePaints({ ...node, strokes: raw.strokes })
+    const strokes = (migrated.strokes ?? []).filter(isNodeStroke)
+    if (strokes.length) node.strokes = strokes
+    if (migrated.style !== node.style) {
+      const align = migrated.style?.strokeAlign
+      if (typeof align === "string") style.strokeAlign = align
+    }
+  }
+  if (Array.isArray(raw.effects)) {
+    const effects = raw.effects.filter(isNodeEffect)
+    if (effects.length) node.effects = effects
+  }
+  if (Array.isArray(raw.exports)) {
+    const exports = raw.exports.filter(isExportPreset)
+    if (exports.length) node.exports = exports
+  }
+  if (isNodeConstraints(raw.constraints)) node.constraints = raw.constraints
+  if (
+    Array.isArray(raw.corners) &&
+    raw.corners.length === 4 &&
+    raw.corners.every((c) => typeof c === "number" && Number.isFinite(c) && c >= 0)
+  ) {
+    node.corners = raw.corners as [number, number, number, number]
+  }
+  if (typeof raw.blendMode === "string" && raw.blendMode) node.blendMode = raw.blendMode
+  if (typeof raw.aspectLocked === "boolean") node.aspectLocked = raw.aspectLocked
+  if (typeof raw.refCorner === "string" && ["tl", "tr", "bl", "br", "center"].includes(raw.refCorner)) {
+    node.refCorner = raw.refCorner as SceneNode["refCorner"]
+  }
+  return node
+}
+
+export function sanitizeScene(input: unknown): SceneDocument {
+  const src = deepCloneSafe(input)
+  if (!isRecord(src)) return createEmptyDoc()
+  const meta = isRecord(src.meta) ? (src.meta as SceneDocument["meta"]) : {}
+  const rawNodes = Array.isArray(src.nodes) ? src.nodes : []
+  const seen = new Set<string>()
+  const counter = { n: 0 }
+  const idGen = () => `n_${++counter.n}`
+  const nodes: SceneNode[] = []
+  for (const raw of rawNodes) {
+    const node = sanitizeNode(raw, idGen, seen)
+    if (node) nodes.push(node)
+  }
+  let board = nodes.find((node) => node.id === BOARD_NODE_ID)
+  if (!board) {
+    board = createBoardNode(meta.device ?? "desktop")
+    nodes.unshift(board)
+  } else {
+    board.id = BOARD_NODE_ID
+    board.kind = "group"
+    board.type = "board"
+    board.parentId = null
+    board.x = 0
+    board.y = 0
+    if (nodes[0]?.id !== BOARD_NODE_ID) {
+      nodes.splice(nodes.indexOf(board), 1)
+      nodes.unshift(board)
+    }
+  }
+  return normalizeScene({ version: 1, meta, nodes })
+}
+
+export function trimScene(doc: SceneDocument): SceneDocument {
+  const board = doc.nodes[0] ?? createBoardNode()
+  const nodes = [board, ...doc.nodes.slice(1)].map((node) => ({ ...node }))
+  while (
+    nodes.length > 1 &&
+    JSON.stringify({ version: 1, meta: doc.meta, nodes }).length > SCENE_SOFT_LIMIT
+  ) {
+    nodes.pop()
+  }
+  const kept = new Set(nodes.map((node) => node.id))
+  for (const node of nodes) {
+    if (node.parentId && !kept.has(node.parentId)) node.parentId = BOARD_NODE_ID
+  }
+  return { version: 1, meta: { ...doc.meta }, nodes }
+}

package/src/design-engine/document/serialize-shared.ts

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+// serialize 共享底层：安全克隆 / 数值与记录守卫 / 场景体积上限常量。
+// 读侧（serialize-read）、写侧（serialize-write）、sanitize、leafer-json 包装
+// 四域共用，保持无域依赖的叶子位置（避免循环 import）
+
+import type { SceneNodeKind } from "@/components/design/canvas/document/types"
+
+export const SCENE_HARD_LIMIT = 1_000_000
+export const SCENE_SOFT_LIMIT = 800_000
+
+export const DANGER_KEYS = new Set(["__proto__", "prototype", "constructor"])
+
+// 结构化克隆产物的领域类型：leafer toJSON 的合法 JSON 值
+export type ClonedDoc = Record<string, unknown> | ClonedDoc[] | string | number | boolean | null
+
+// JSON 结构化克隆的宽容入口：剔除 DANGER_KEYS，循环引用置 null
+export function deepCloneSafe(value: unknown, stack = new WeakSet<object>()): ClonedDoc {
+  if (value === null || value === undefined) return null
+  switch (typeof value) {
+    case "string":
+      return value
+    case "number":
+      return Number.isFinite(value) ? value : null
+    case "boolean":
+      return value
+    case "object":
+      break
+    default:
+      return null
+  }
+  const obj = value as object
+  if (stack.has(obj)) return null
+  stack.add(obj)
+  if (Array.isArray(obj)) {
+    const out = obj.map((item) => deepCloneSafe(item, stack))
+    stack.delete(obj)
+    return out
+  }
+  const result: Record<string, unknown> = {}
+  for (const key of Object.keys(obj)) {
+    if (DANGER_KEYS.has(key)) continue
+    result[key] = deepCloneSafe((obj as Record<string, unknown>)[key], stack)
+  }
+  stack.delete(obj)
+  return result
+}
+
+export function toNumber(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0
+}
+
+export function isKind(value: unknown): value is SceneNodeKind {
+  return value === "shape" || value === "component" || value === "group"
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+// leafer toJSON 的无类型节点描述（读侧 walkDesc / leaferToDoc 用）
+export type DescNode = Record<string, unknown> & { children?: DescNode[] }