@allbluecn/web-app 0.17.2 → 0.18.0

package/src/components/design/canvas/document/__tests__/serialize.test.ts

@@ -0,0 +1,1936 @@
+// 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 { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+
+import { registry } from "../../registry/registry"
+import {
+  docToScene,
+  leafConfigOf,
+  exportLeaferJSON,
+  isLeaferJSONPackage,
+  leaferToDoc,
+  normalizeSceneDocument,
+  parseLeaferJSON,
+  sanitizeScene,
+  trimScene,
+} from "@/design-engine/document/serialize"
+import { BOARD_NODE_ID, createBoardNode, createEmptyDoc } from "../types"
+import type { SceneDocument, SceneNode } from "../types"
+import type { ILeaf } from "leafer-editor"
+
+type MockElement = {
+  id?: string
+  children: unknown[]
+  add: ReturnType<typeof vi.fn>
+  [key: string]: unknown
+}
+
+function docWithFrame(p: Partial<SceneNode> & { id: string }): SceneDocument {
+  return {
+    version: 1,
+    meta: {},
+    nodes: [
+      createBoardNode("desktop"),
+      {
+        kind: "group",
+        type: "frame",
+        parentId: BOARD_NODE_ID,
+        x: 0,
+        y: 0,
+        width: 375,
+        height: 667,
+        style: { fill: "#ffffff" },
+        ...p,
+      },
+    ],
+  }
+}
+
+function mockCtor() {
+  return class {
+    static one = vi.fn(
+      (
+        config: Record<string, unknown> = {},
+        x = 0,
+        y = 0,
+        w = 0,
+        h = 0,
+      ): MockElement => {
+        const element: MockElement = {
+          ...config,
+          id: undefined,
+          x,
+          y,
+          width: w,
+          height: h,
+          children: [],
+          add: vi.fn(),
+        }
+        element.add = vi.fn((child: unknown) => {
+          element.children.push(child)
+        })
+        return element
+      },
+    )
+  }
+}
+
+function mockMod() {
+  return {
+    Group: mockCtor(),
+    Rect: mockCtor(),
+    Frame: mockCtor(),
+    Text: mockCtor(),
+    Ellipse: mockCtor(),
+    Line: mockCtor(),
+    Arrow: mockCtor(),
+    Pen: mockCtor(),
+    Path: mockCtor(),
+    Polygon: mockCtor(),
+    Star: mockCtor(),
+  } as unknown as typeof import("leafer-editor")
+}
+
+const mockTree = {
+  width: 1200,
+  height: 812,
+  x: 0,
+  y: 0,
+  children: [
+    { x: 10, y: 20, width: 100, height: 50, fill: "#fff", stroke: "#ccc", strokeWidth: 1, r: 4 },
+    {
+      x: 50,
+      y: 60,
+      width: 200,
+      height: 40,
+      children: [
+        { x: 0, y: 0, width: 200, height: 40, fill: "#000", r: 6, skipJSON: false },
+        {
+          x: 8,
+          y: 0,
+          width: 184,
+          height: 40,
+          text: "按钮",
+          font: { size: 14, weight: 500 },
+          fill: "#fff",
+          textAlign: "center",
+          verticalAlign: "middle",
+        },
+      ],
+    },
+    { x: 300, y: 100, width: 100, height: 100, ellipse: true },
+    { x: 400, y: 200, width: 120, height: 30, text: "hello", font: { size: 16 } },
+  ],
+}
+
+describe("leaferToDoc", () => {
+  it("把 leafer 树转成合法 SceneDocument，nodes[0] 为 board", () => {
+    const doc = leaferToDoc(mockTree as unknown as ILeaf)
+
+    expect(doc.version).toBe(1)
+    expect(doc.meta).toEqual({ device: "desktop" })
+    expect(doc.nodes[0]).toMatchObject({
+      id: BOARD_NODE_ID,
+      kind: "group",
+      type: "board",
+      parentId: null,
+      width: 1200,
+      height: 812,
+    })
+  })
+
+  it("透传 device 选项", () => {
+    const doc = leaferToDoc(mockTree as unknown as ILeaf, { device: "mobile" })
+    expect(doc.meta.device).toBe("mobile")
+  })
+
+  it("board 直接子节点数等于 desc children 数", () => {
+    const doc = leaferToDoc(mockTree as unknown as ILeaf)
+    const direct = doc.nodes.filter(
+      (n) => n.id !== BOARD_NODE_ID && n.parentId === BOARD_NODE_ID,
+    )
+    expect(direct).toHaveLength(4)
+    expect(doc.nodes).toHaveLength(7)
+  })
+
+  it("按 desc 特征映射节点 type", () => {
+    const doc = leaferToDoc(mockTree as unknown as ILeaf)
+    const byParent = doc.nodes.filter(
+      (n) => n.id !== BOARD_NODE_ID && n.parentId === BOARD_NODE_ID,
+    )
+
+    expect(byParent[0].type).toBe("rect")
+    expect(byParent[0].kind).toBe("shape")
+    expect(byParent[1].type).toBe("group")
+    expect(byParent[1].kind).toBe("group")
+    expect(byParent[2].type).toBe("ellipse")
+    expect(byParent[3].type).toBe("text")
+  })
+
+  it("优先使用 desc.tag 判定类型", () => {
+    const doc = leaferToDoc(
+      {
+        width: 100,
+        height: 100,
+        children: [{ tag: "Ellipse", x: 0, y: 0, width: 50, height: 50, fill: "#f00" }],
+      } as unknown as ILeaf,
+    )
+    expect(doc.nodes[1].type).toBe("ellipse")
+    expect(doc.nodes[1].kind).toBe("shape")
+  })
+
+  it("group 子节点 parentId 指向 group 节点 id", () => {
+    const doc = leaferToDoc(mockTree as unknown as ILeaf)
+    const group = doc.nodes.find((n) => n.type === "group" && n.id !== BOARD_NODE_ID)!
+    const children = doc.nodes.filter((n) => n.parentId === group.id)
+    expect(group.id).toBeTruthy()
+    expect(children).toHaveLength(2)
+    expect(children.map((c) => c.type).sort()).toEqual(["rect", "text"])
+  })
+
+  it("样式键进 style，内容键进 props", () => {
+    const doc = leaferToDoc(mockTree as unknown as ILeaf)
+    const rect = doc.nodes.find((n) => n.type === "rect" && n.parentId === BOARD_NODE_ID)!
+    expect(rect.style).toMatchObject({
+      fill: "#fff",
+      stroke: "#ccc",
+      strokeWidth: 1,
+    })
+    expect(rect.style).not.toHaveProperty("x")
+    expect(rect.style).not.toHaveProperty("width")
+
+    const text = doc.nodes.find(
+      (n) => n.type === "text" && n.parentId !== BOARD_NODE_ID && n.props?.text === "按钮",
+    )!
+    const textProps = text.props ?? {}
+    expect(textProps.text).toBe("按钮")
+    expect(textProps.font).toEqual({ size: 14, weight: 500 })
+    expect(text.style).toMatchObject({ fill: "#fff", textAlign: "center" })
+    expect(text.style).not.toHaveProperty("text")
+    expect(text.style).not.toHaveProperty("font")
+  })
+
+  it("效果键不回读进 style（canonical 存 node.effects，防删除效果后残留陈旧副本）", () => {
+    const doc = leaferToDoc({
+      width: 100,
+      height: 100,
+      children: [
+        {
+          id: "my-rect",
+          x: 0,
+          y: 0,
+          width: 40,
+          height: 40,
+          fill: "#fff",
+          shadow: [{ x: 2, y: 4, blur: 8, spread: 0, color: "rgba(0, 0, 0, 1)" }],
+          innerShadow: [{ x: 0, y: 2, blur: 6, spread: 1, color: "rgba(0, 0, 0, 1)" }],
+          blur: 6,
+          backgroundBlur: 4,
+        },
+      ],
+    } as unknown as ILeaf)
+    const node = doc.nodes.find((n) => n.id === "my-rect")!
+    expect(node.style).not.toHaveProperty("shadow")
+    expect(node.style).not.toHaveProperty("innerShadow")
+    expect(node.style).not.toHaveProperty("blur")
+    expect(node.style).not.toHaveProperty("backgroundBlur")
+    expect(node.style).toMatchObject({ fill: "#fff" })
+  })
+
+  it("保留 desc.id（非 leafer 自动 id）", () => {
+    const doc = leaferToDoc(
+      {
+        width: 100,
+        height: 100,
+        children: [{ id: "my-rect", x: 0, y: 0, width: 10, height: 10, fill: "#fff" }],
+      } as unknown as ILeaf,
+    )
+    expect(doc.nodes[1].id).toBe("my-rect")
+  })
+
+  it("leafer 自动 id 被替换为 n_ 序列", () => {
+    const doc = leaferToDoc(
+      {
+        width: 100,
+        height: 100,
+        children: [{ id: "1_0", x: 0, y: 0, width: 10, height: 10, fill: "#fff" }],
+      } as unknown as ILeaf,
+    )
+    expect(doc.nodes[1].id).toMatch(/^n_\d+$/)
+  })
+
+  it("子节点 editable:false 的 group 降级为 kind=component，locked 独立映射", () => {
+    const doc = leaferToDoc(
+      {
+        width: 100,
+        height: 100,
+        children: [
+          {
+            x: 0,
+            y: 0,
+            width: 50,
+            height: 40,
+            editable: true,
+            children: [
+              { x: 0, y: 0, width: 50, height: 40, fill: "#000", editable: false },
+              { x: 4, y: 0, width: 42, height: 40, text: "按钮", editable: false },
+            ],
+          },
+          { x: 60, y: 0, width: 20, height: 20, fill: "#fff", locked: true },
+          { x: 60, y: 30, width: 20, height: 20, fill: "#fff", edit: false },
+        ],
+      } as unknown as ILeaf,
+    )
+    expect(doc.nodes[1].kind).toBe("component")
+    expect(doc.nodes[1].type).toBe("group")
+    expect(doc.nodes[2].locked).toBe(true)
+    expect(doc.nodes[3].locked).toBe(true)
+    expect(doc.nodes[2].visible).toBeUndefined()
+  })
+
+  it("visible:false 映射为 visible=false，默认不写 visible", () => {
+    const doc = leaferToDoc(
+      {
+        width: 100,
+        height: 100,
+        children: [
+          { x: 0, y: 0, width: 10, height: 10, fill: "#fff", visible: false },
+          { x: 0, y: 0, width: 10, height: 10, fill: "#000" },
+        ],
+      } as unknown as ILeaf,
+    )
+    expect(doc.nodes[1].visible).toBe(false)
+    expect(doc.nodes[2].visible).toBeUndefined()
+  })
+
+  it("skipJSON 子节点被跳过", () => {
+    const doc = leaferToDoc(
+      {
+        width: 100,
+        height: 100,
+        children: [
+          { x: 0, y: 0, width: 10, height: 10, fill: "#fff", skipJSON: true },
+          { x: 0, y: 0, width: 10, height: 10, fill: "#000" },
+        ],
+      } as unknown as ILeaf,
+    )
+    expect(doc.nodes).toHaveLength(2)
+    expect(doc.nodes[1].style?.fill).toBe("#000")
+  })
+
+  it("空画板返回仅含 board 的文档", () => {
+    const doc = leaferToDoc({ width: 800, height: 600 } as unknown as ILeaf)
+    expect(doc.nodes).toHaveLength(1)
+    expect(doc.nodes[0].id).toBe(BOARD_NODE_ID)
+  })
+
+  it("真实 Leafer desc 删除 width/height 时从对象读取尺寸", () => {
+    const tree = {
+      width: 1200,
+      height: 812,
+      toJSON: () => ({ tag: "Leafer", hittable: true, fill: "#fff", children: [] }),
+    }
+    const doc = leaferToDoc(tree as unknown as ILeaf)
+    expect(doc.nodes[0]).toMatchObject({ width: 1200, height: 812 })
+    expect(doc.nodes[0].style).not.toHaveProperty("hittable")
+  })
+})
+
+describe("docToScene", () => {
+  let mod: ReturnType<typeof mockMod>
+
+  beforeEach(() => {
+    mod = mockMod()
+    registry.clear()
+  })
+
+  // factory 测试直接 registry.set 注册 mock 工厂——不清理会泄漏到后续
+  // describe（如「结构化样式投影接线」），buildElement 走工厂路径产出空壳 leaf
+  afterEach(() => {
+    registry.clear()
+  })
+
+  it("把 SceneDocument 还原为 leafer 并建立节点索引", () => {
+    const doc = leaferToDoc(mockTree as unknown as ILeaf)
+    const result = docToScene(doc, mod)
+
+    expect(result.leafer).toBeDefined()
+    expect(result.leafer.id).toBe(BOARD_NODE_ID)
+    expect(result.nodeIndex.get(BOARD_NODE_ID)).toBe(result.leafer)
+    expect(result.nodeIndex.size).toBe(doc.nodes.length)
+    for (const node of doc.nodes) {
+      expect(result.nodeIndex.get(node.id)).toBeDefined()
+    }
+  })
+
+  it("按 parentId 挂载父子关系", () => {
+    const doc = leaferToDoc(mockTree as unknown as ILeaf)
+    const result = docToScene(doc, mod)
+    const boardAdd = (result.leafer as unknown as MockElement).add
+
+    expect(boardAdd).toHaveBeenCalledTimes(4)
+    const group = doc.nodes.find((n) => n.type === "group" && n.id !== BOARD_NODE_ID)!
+    const groupEl = result.nodeIndex.get(group.id) as unknown as MockElement
+    expect(groupEl.add).toHaveBeenCalledTimes(2)
+  })
+
+  it("docToScene 不向 board 写 fill（画布背景改由 CSS --canvas-bg 驱动）", () => {
+    const mod2 = mockMod()
+    const doc = {
+      version: 1 as const,
+      meta: { background: "#ff0000" },
+      nodes: [createBoardNode("desktop")],
+    }
+    const { leafer } = docToScene(doc, mod2)
+    expect((leafer as unknown as MockElement).fill).toBeUndefined()
+  })
+
+  it("docToScene 空 board 也不写 fill", () => {
+    const mod2 = mockMod()
+    const empty = createEmptyDoc()
+    const r1 = docToScene(empty, mod2)
+    expect((r1.leafer as unknown as MockElement).fill).toBeUndefined()
+  })
+
+  it("未注册 factory 的 type 走通用形状构造", () => {
+    const mod2 = mockMod()
+    const doc = createEmptyDoc()
+    doc.nodes.push({
+      id: "pen1",
+      kind: "shape",
+      type: "pen-path",
+      parentId: BOARD_NODE_ID,
+      x: 5,
+      y: 6,
+      width: 100,
+      height: 50,
+      props: { path: "M0,0 L100,50" },
+    })
+    expect(() => docToScene(doc, mod2)).not.toThrow()
+    const pen = docToScene(doc, mockMod()).nodeIndex.get("pen1")
+    expect((pen as unknown as MockElement).path).toBe("M0,0 L100,50")
+    // pen-path 必须用 Path（可渲染 SVG path）；Pen 是笔迹录制器，构造 config 的 path 只读会抛 TypeError
+    expect(mod2.Path.one).toHaveBeenCalled()
+    expect(mod2.Pen.one).not.toHaveBeenCalled()
+  })
+
+  it("createEmptyDoc 往返不抛错", () => {
+    const result = docToScene(createEmptyDoc(), mod)
+    expect(result.leafer).toBeDefined()
+    expect(result.nodeIndex.size).toBe(1)
+  })
+
+  it("factory 存在时优先使用 registry.buildTree", () => {
+    registry.set("rect", {
+      defaults: { width: 1, height: 1 },
+      buildTree: vi.fn(() => ({ id: "factory-built", children: [] }) as unknown as ILeaf),
+    })
+    const mod2 = mockMod()
+    const doc = createEmptyDoc()
+    doc.nodes.push({
+      id: "r1",
+      kind: "shape",
+      type: "rect",
+      parentId: BOARD_NODE_ID,
+      x: 0,
+      y: 0,
+      width: 10,
+      height: 10,
+    })
+    const result = docToScene(doc, mod2)
+    expect(result.nodeIndex.get("r1")).toMatchObject({ id: "factory-built" })
+    expect(mod2.Rect.one).not.toHaveBeenCalled()
+  })
+
+})
+
+describe("sanitizeScene", () => {
+  it("循环引用不抛错且降级为合法 SceneDocument", () => {
+    const doc = createEmptyDoc()
+    const cyclic = {} as Record<string, unknown>
+    cyclic.self = cyclic
+    const input = { ...doc, nodes: [doc.nodes[0], cyclic] }
+    expect(() => sanitizeScene(input)).not.toThrow()
+    const out = sanitizeScene(input)
+    expect(out.version).toBe(1)
+    expect(Array.isArray(out.nodes)).toBe(true)
+    expect(out.nodes.length).toBeGreaterThanOrEqual(1)
+    expect(out.nodes[0].id).toBe(BOARD_NODE_ID)
+  })
+
+  it("剥离 __proto__ 原型污染", () => {
+    const polluted = JSON.parse(
+      '{"__proto__": {"isAdmin": true}, "version": 1, "nodes": []}',
+    )
+    expect(Object.keys(polluted)).toContain("__proto__")
+    expect(polluted.__proto__.isAdmin).toBe(true)
+    const out = sanitizeScene(polluted)
+    expect(Array.isArray(out.nodes)).toBe(true)
+    expect(Object.keys(out)).not.toContain("__proto__")
+    expect("isAdmin" in out).toBe(false)
+    expect(out.nodes[0].id).toBe(BOARD_NODE_ID)
+  })
+
+  it("缺失 board 时自动补 board 到 nodes[0]", () => {
+    const out = sanitizeScene({ version: 1, nodes: [] })
+    expect(out.nodes).toHaveLength(1)
+    expect(out.nodes[0]).toMatchObject({ id: BOARD_NODE_ID, type: "board", kind: "group" })
+  })
+
+  it("version 缺失时补为 1", () => {
+    const out = sanitizeScene({ nodes: [createBoardNode()] })
+    expect(out.version).toBe(1)
+  })
+
+  it("必填字段缺失时补默认值", () => {
+    const out = sanitizeScene({
+      version: 1,
+      nodes: [{ id: "n1", x: 1, style: "not-a-record", props: null }],
+    })
+    const node = out.nodes.find((n) => n.id === "n1")!
+    expect(node).toMatchObject({
+      kind: "shape",
+      type: "rect",
+      parentId: null,
+      y: 0,
+      width: 0,
+      height: 0,
+      style: {},
+      props: {},
+    })
+  })
+
+  it("丢弃无 id 且无 type 的垃圾节点", () => {
+    const doc = createEmptyDoc()
+    const out = sanitizeScene({
+      version: 1,
+      nodes: [doc.nodes[0], { foo: "bar" }, null, 42, { id: "keep", type: "rect" }],
+    })
+    expect(out.nodes.map((n) => n.id)).toEqual([BOARD_NODE_ID, "keep"])
+  })
+
+  it("重复 id 自动去重", () => {
+    const doc = createEmptyDoc()
+    const out = sanitizeScene({
+      version: 1,
+      nodes: [doc.nodes[0], { id: "dup", type: "rect" }, { id: "dup", type: "rect" }],
+    })
+    const ids = out.nodes.map((n) => n.id)
+    expect(new Set(ids).size).toBe(ids.length)
+  })
+
+  it("board 强制置顶并规范字段", () => {
+    const out = sanitizeScene({
+      version: 1,
+      nodes: [
+        { id: "other", type: "rect", parentId: null },
+        { id: BOARD_NODE_ID, kind: "shape", type: "rect", parentId: "other", x: 9, y: 9, width: 1, height: 1 },
+      ],
+    })
+    expect(out.nodes[0].id).toBe(BOARD_NODE_ID)
+    expect(out.nodes[0].kind).toBe("group")
+    expect(out.nodes[0].type).toBe("board")
+    expect(out.nodes[0].parentId).toBe(null)
+    expect(out.nodes[0].x).toBe(0)
+    expect(out.nodes[0].y).toBe(0)
+  })
+
+  it("非法输入降级为空画板", () => {
+    for (const input of [null, undefined, "x", 42, []]) {
+      const out = sanitizeScene(input)
+      expect(out.version).toBe(1)
+      expect(out.nodes).toHaveLength(1)
+      expect(out.nodes[0].id).toBe(BOARD_NODE_ID)
+    }
+  })
+})
+
+describe("trimScene", () => {
+  const fatNode = (id: string, parentId = BOARD_NODE_ID) => ({
+    id,
+    kind: "shape" as const,
+    type: "rect" as const,
+    parentId,
+    x: 0,
+    y: 0,
+    width: 100,
+    height: 50,
+    style: { fill: "#fff", data: "x".repeat(4000) },
+    props: {},
+  })
+
+  it("裁剪到 800KB 以内且优先保留靠前节点", () => {
+    const doc = createEmptyDoc()
+    doc.nodes.push(...Array.from({ length: 300 }, (_, i) => fatNode(`n${i}`)))
+    const trimmed = trimScene(doc)
+    expect(JSON.stringify(trimmed).length).toBeLessThan(800_000)
+    expect(trimmed.nodes[0].id).toBe(BOARD_NODE_ID)
+    expect(trimmed.nodes.length).toBeGreaterThan(1)
+  })
+
+  it("节点数极少时不裁剪", () => {
+    const doc = createEmptyDoc()
+    const small = fatNode("only")
+    small.style.data = "x"
+    doc.nodes.push(small)
+    expect(trimScene(doc).nodes).toHaveLength(2)
+  })
+
+  it("空节点文档仍保留 board", () => {
+    expect(trimScene({ version: 1, meta: {}, nodes: [] }).nodes).toHaveLength(1)
+  })
+
+  it("裁剪掉的父节点会让其后代回挂到 board", () => {
+    const doc = createEmptyDoc()
+    const child = fatNode("child", "parent")
+    doc.nodes.push(child)
+    doc.nodes.push(...Array.from({ length: 300 }, (_, i) => fatNode(`pad${i}`)))
+    doc.nodes.push(fatNode("parent"))
+    const trimmed = trimScene(doc)
+    const ids = new Set(trimmed.nodes.map((n) => n.id))
+    expect(ids.has("child")).toBe(true)
+    expect(ids.has("parent")).toBe(false)
+    const orphan = trimmed.nodes.find((n) => n.id === "child")!
+    expect(orphan.parentId).toBe(BOARD_NODE_ID)
+    for (const node of trimmed.nodes) {
+      expect(!node.parentId || ids.has(node.parentId)).toBe(true)
+    }
+  })
+
+  it("不修改传入文档的节点对象", () => {
+    const doc = createEmptyDoc()
+    const child = fatNode("child", "parent")
+    doc.nodes.push(child)
+    doc.nodes.push(...Array.from({ length: 300 }, (_, i) => fatNode(`pad${i}`)))
+    doc.nodes.push(fatNode("parent"))
+    const before = JSON.parse(JSON.stringify(doc))
+    trimScene(doc)
+    expect(doc).toEqual(before)
+  })
+})
+
+describe("sanitizeNode 结构化字段透传", () => {
+  const baseNode = {
+    id: "a",
+    kind: "shape",
+    type: "rect",
+    parentId: null,
+    x: 0,
+    y: 0,
+    width: 10,
+    height: 10,
+  }
+
+  it("合法结构化字段被保留", () => {
+    const doc = sanitizeScene({
+      version: 1,
+      meta: {},
+      nodes: [
+        { id: "board", kind: "group", type: "board", parentId: null, x: 0, y: 0, width: 100, height: 100 },
+        {
+          ...baseNode,
+          fills: [{ id: "p1", type: "solid", color: "#ff0000", opacity: 1, visible: true }],
+          strokes: [{ id: "s1", color: "#00ff00", opacity: 1, align: "inside", width: 2, visible: true }],
+          corners: [1, 2, 3, 4],
+          blendMode: "multiply",
+          aspectLocked: true,
+          refCorner: "br",
+          constraints: { horizontal: "center", vertical: "stretch" },
+          exports: [{ id: "x1", format: "png", scale: 2, suffix: "@2x" }],
+          effects: [{ id: "e1", type: "drop-shadow", color: "#000", offsetX: 0, offsetY: 4, blur: 8, spread: 0, visible: true }],
+        },
+      ],
+    })
+    const node = doc.nodes.find((n) => n.id === "a")
+    expect(node?.fills).toHaveLength(1)
+    // v1 旧描边（顶层 color/align）经惰性迁移为 paint 嵌套结构，align 提升为节点级
+    expect(node?.strokes?.[0].paint).toEqual({
+      id: expect.any(String),
+      type: "solid",
+      color: "#00ff00",
+      opacity: 1,
+      visible: true,
+    })
+    expect(node?.style?.strokeAlign).toBe("inside")
+    expect(node?.corners).toEqual([1, 2, 3, 4])
+    expect(node?.blendMode).toBe("multiply")
+    expect(node?.aspectLocked).toBe(true)
+    expect(node?.refCorner).toBe("br")
+    expect(node?.constraints).toEqual({ horizontal: "center", vertical: "stretch" })
+    expect(node?.exports?.[0].scale).toBe(2)
+    expect(node?.effects?.[0].type).toBe("drop-shadow")
+  })
+
+  it("非法结构化字段被剔除（防脏数据入库）", () => {
+    const doc = sanitizeScene({
+      version: 1,
+      meta: {},
+      nodes: [
+        { id: "board", kind: "group", type: "board", parentId: null, x: 0, y: 0, width: 100, height: 100 },
+        {
+          ...baseNode,
+          fills: [{ id: "bad", type: "gradient" }],
+          blendMode: 123,
+          aspectLocked: "yes",
+          corners: [1, 2],
+        },
+      ],
+    })
+    const node = doc.nodes.find((n) => n.id === "a")
+    expect(node?.fills).toBeUndefined()
+    expect(node?.blendMode).toBeUndefined()
+    expect(node?.aspectLocked).toBeUndefined()
+    expect(node?.corners).toBeUndefined()
+  })
+})
+
+describe("docToScene 结构化样式投影接线", () => {
+  it("buildElement 输出的 leaf style 含投影键", () => {
+    const modMock = mockMod()
+    const doc = sanitizeScene({
+      version: 1,
+      meta: {},
+      nodes: [
+        { id: "board", kind: "group", type: "board", parentId: null, x: 0, y: 0, width: 100, height: 100 },
+        {
+          id: "a",
+          kind: "shape",
+          type: "rect",
+          parentId: "board",
+          x: 0,
+          y: 0,
+          width: 10,
+          height: 10,
+          fills: [{ id: "p1", type: "solid", color: "#123456", opacity: 0.9, visible: true }],
+          corners: [4, 4, 4, 4],
+        },
+      ],
+    })
+    const { nodeIndex } = docToScene(doc, modMock)
+    expect(nodeIndex.size).toBe(2)
+    const leaf = nodeIndex.get("a") as unknown as Record<string, unknown>
+    // 透明度烘进色值（leafer 忽略 paint.opacity）
+    expect(leaf.fill).toEqual([{ type: "solid", color: "rgba(18, 52, 86, 0.9)", opacity: 1, visible: true }])
+    expect(leaf.cornerRadius).toBe(4)
+  })
+
+  it("非均匀 corners 原样投影为 cornerRadius 数组（回归：rect 工厂曾硬编码 4 忽略面板圆角）", () => {
+    const doc = sanitizeScene({
+      version: 1,
+      meta: {},
+      nodes: [
+        { id: "board", kind: "group", type: "board", parentId: null, x: 0, y: 0, width: 100, height: 100 },
+        {
+          id: "a",
+          kind: "shape",
+          type: "rect",
+          parentId: "board",
+          x: 0,
+          y: 0,
+          width: 100,
+          height: 60,
+          corners: [12, 4, 0, 20],
+        },
+      ],
+    })
+    const leaf = docToScene(doc, mockMod()).nodeIndex.get("a") as unknown as Record<string, unknown>
+    expect(leaf.cornerRadius).toEqual([12, 4, 0, 20])
+  })
+
+  it("不透明度与混合模式补写到 leaf（回归：面板改了不渲染却照样入库）", () => {
+    const doc = sanitizeScene({
+      version: 1,
+      meta: {},
+      nodes: [
+        { id: "board", kind: "group", type: "board", parentId: null, x: 0, y: 0, width: 100, height: 100 },
+        {
+          id: "a",
+          kind: "shape",
+          type: "rect",
+          parentId: "board",
+          x: 0,
+          y: 0,
+          width: 40,
+          height: 40,
+          style: { opacity: 0.5, scaleX: -2, scaleY: 1.5 },
+          blendMode: "multiply",
+        },
+      ],
+    })
+    const leaf = docToScene(doc, mockMod()).nodeIndex.get("a") as unknown as Record<string, unknown>
+    expect(leaf.opacity).toBe(0.5)
+    expect(leaf.blendMode).toBe("multiply")
+    expect(leaf.scaleX).toBe(-2)
+    expect(leaf.scaleY).toBe(1.5)
+  })
+
+  it("效果投影补写到 leaf（回归：面板加了阴影/模糊改了不渲染却照样入库）", () => {
+    const doc = sanitizeScene({
+      version: 1,
+      meta: {},
+      nodes: [
+        { id: "board", kind: "group", type: "board", parentId: null, x: 0, y: 0, width: 100, height: 100 },
+        {
+          id: "a",
+          kind: "shape",
+          type: "rect",
+          parentId: "board",
+          x: 0,
+          y: 0,
+          width: 40,
+          height: 40,
+          effects: [
+            { id: "e1", type: "drop-shadow", color: "#ff0000", offsetX: 2, offsetY: 4, blur: 8, spread: 0, visible: true },
+            { id: "e2", type: "inner-shadow", color: "#0000ff", offsetY: 2, blur: 6, spread: 1, visible: true },
+            { id: "e3", type: "layer-blur", blur: 6, visible: true },
+            { id: "e4", type: "background-blur", blur: 4, visible: true },
+          ],
+        },
+      ],
+    })
+    const leaf = docToScene(doc, mockMod()).nodeIndex.get("a") as unknown as Record<string, unknown>
+    expect(leaf.shadow).toEqual([{ x: 2, y: 4, blur: 8, spread: 0, color: "rgba(255, 0, 0, 1)" }])
+    expect(leaf.innerShadow).toEqual([{ x: 0, y: 2, blur: 6, spread: 1, color: "rgba(0, 0, 255, 1)" }])
+    expect(leaf.blur).toBe(6)
+    expect(leaf.backgroundBlur).toBe(4)
+  })
+
+  it("隐藏与零强度效果不写入 leaf", () => {
+    const doc = sanitizeScene({
+      version: 1,
+      meta: {},
+      nodes: [
+        { id: "board", kind: "group", type: "board", parentId: null, x: 0, y: 0, width: 100, height: 100 },
+        {
+          id: "a",
+          kind: "shape",
+          type: "rect",
+          parentId: "board",
+          x: 0,
+          y: 0,
+          width: 40,
+          height: 40,
+          effects: [
+            { id: "e1", type: "drop-shadow", color: "#ff0000", offsetX: 2, offsetY: 4, blur: 8, spread: 0, visible: false },
+            { id: "e2", type: "layer-blur", blur: 0, visible: true },
+          ],
+        },
+      ],
+    })
+    const leaf = docToScene(doc, mockMod()).nodeIndex.get("a") as unknown as Record<string, unknown>
+    expect(leaf.shadow).toBeUndefined()
+    expect(leaf.blur).toBeUndefined()
+  })
+})
+
+describe("图形 props 渲染透传（FS-2.4 白名单）", () => {
+  function docWithShape(props: Record<string, unknown>): SceneDocument {
+    return {
+      version: 1,
+      meta: {},
+      nodes: [
+        createBoardNode("desktop"),
+        {
+          id: "shape1",
+          kind: "shape",
+          type: "ellipse",
+          parentId: BOARD_NODE_ID,
+          x: 10,
+          y: 20,
+          width: 100,
+          height: 100,
+          props,
+        },
+      ],
+    }
+  }
+
+  afterEach(() => {
+    registry.clear()
+  })
+
+  it("圆环 props.innerRadius 直传渲染配置（渲染侧断言，非 doc 层 round trip）", () => {
+    const config = leafConfigOf(docWithShape({ innerRadius: 0.75 }).nodes[1])
+    expect(config.innerRadius).toBe(0.75)
+  })
+
+  it("扇形 startAngle/endAngle 直传渲染配置", () => {
+    const config = leafConfigOf(docWithShape({ startAngle: -90, endAngle: 90 }).nodes[1])
+    expect(config.startAngle).toBe(-90)
+    expect(config.endAngle).toBe(90)
+  })
+
+  it("star corners/innerRadius 直传且白名单外字段不注入 leafer config", () => {
+    const node = { ...docWithShape({ corners: 8, innerRadius: 0.5, malicious: "junk" }).nodes[1], type: "star" }
+    const config = leafConfigOf(node)
+    expect(config.corners).toBe(8)
+    expect(config.innerRadius).toBe(0.5)
+    expect(config.malicious).toBeUndefined()
+  })
+
+  it("注册工厂路径：buildElement 把图形参数补写到工厂产出的 leaf", () => {
+    registry.set("ellipse", {
+      defaults: { width: 1, height: 1 },
+      buildTree: vi.fn(() => ({ children: [] }) as unknown as ILeaf),
+    })
+    const { nodeIndex } = docToScene(docWithShape({ innerRadius: 0.75 }), mockMod())
+    const leaf = nodeIndex.get("shape1") as unknown as Record<string, unknown>
+    expect(leaf.innerRadius).toBe(0.75)
+  })
+
+  it("全量重建路径保持 node.rotation（undo/redo/loadDoc 视觉不转正）", () => {
+    registry.set("ellipse", {
+      defaults: { width: 1, height: 1 },
+      buildTree: vi.fn(() => ({ children: [] }) as unknown as ILeaf),
+    })
+    const doc = docWithShape({ innerRadius: 0.75 })
+    doc.nodes[1].rotation = 30
+    const { nodeIndex } = docToScene(doc, mockMod())
+    const leaf = nodeIndex.get("shape1") as unknown as Record<string, unknown>
+    expect(leaf.rotation).toBe(30)
+  })
+})
+
+describe("leaferToDoc preserveFrom 回读保留", () => {
+  const structured = {
+    fills: [{ id: "p1", type: "solid", color: "#abcdef", opacity: 1, visible: true }],
+    exports: [{ id: "x1", format: "png", scale: 2, suffix: "@2x" }],
+    constraints: { horizontal: "center", vertical: "min" },
+    blendMode: "screen",
+    aspectLocked: true,
+    refCorner: "br",
+    corners: [1, 2, 3, 4],
+  }
+
+  function makeTree(id: string, extra: Record<string, unknown> = {}) {
+    return {
+      toJSON: () => ({
+        children: [
+          {
+            id: "board",
+            tag: "Group",
+            x: 0,
+            y: 0,
+            width: 100,
+            height: 100,
+            children: [{ id, tag: "Rect", x: 1, y: 2, width: 10, height: 20, ...extra }],
+          },
+        ],
+      }),
+    }
+  }
+
+  const prevDoc = sanitizeScene({
+    version: 1,
+    meta: {},
+    nodes: [
+      { id: "board", kind: "group", type: "board", parentId: null, x: 0, y: 0, width: 100, height: 100 },
+      { id: "a", kind: "shape", type: "rect", parentId: "board", x: 1, y: 2, width: 10, height: 20, ...structured },
+    ],
+  })
+
+  it("带 preserveFrom 时结构化字段按 id 合并（leafer 上不存在这些键）", () => {
+    const doc = leaferToDoc(makeTree("a", { fill: "#abcdef" }) as unknown as ILeaf, {
+      device: "desktop",
+      preserveFrom: prevDoc,
+    })
+    const node = doc.nodes.find((n) => n.id === "a")
+    expect(node?.fills).toEqual(structured.fills)
+    expect(node?.exports).toEqual(structured.exports)
+    expect(node?.constraints).toEqual(structured.constraints)
+    expect(node?.blendMode).toBe("screen")
+    expect(node?.aspectLocked).toBe(true)
+    expect(node?.refCorner).toBe("br")
+    expect(node?.corners).toEqual([1, 2, 3, 4])
+  })
+
+  it("新节点（旧 doc 无同 id）不合并", () => {
+    const doc = leaferToDoc(makeTree("fresh") as unknown as ILeaf, { device: "desktop", preserveFrom: prevDoc })
+    const node = doc.nodes.find((n) => n.id === "fresh")
+    expect(node?.fills).toBeUndefined()
+    expect(node?.blendMode).toBeUndefined()
+  })
+
+  it("不带 preserveFrom 行为不变（向后兼容）", () => {
+    const doc = leaferToDoc(makeTree("a") as unknown as ILeaf, { device: "desktop" })
+    const node = doc.nodes.find((n) => n.id === "a")
+    expect(node?.fills).toBeUndefined()
+  })
+
+})
+
+describe("frame 序列化", () => {
+  let mod: ReturnType<typeof mockMod>
+
+  beforeEach(() => {
+    mod = mockMod()
+    registry.clear()
+  })
+
+  it("docToScene 将 frame 渲染为 tag=Frame、保留用户 name 的 Frame", () => {
+    const doc = docWithFrame({ id: "f1", name: "首页", x: 100, y: 50, width: 375, height: 667 })
+    const { nodeIndex } = docToScene(doc, mod)
+    const leaf = nodeIndex.get("f1") as { name?: string; fill?: string; tag?: string; editable?: boolean }
+    expect(leaf?.tag).toBe("Frame")
+    expect(leaf?.name).toBe("首页")
+    // 画板不选中仅靠 editable:false（官方模型）；hitSelf 不可关——
+    // __clipAfterFill 真值时 eachFind 会剪枝整棵子树
+    expect(leaf?.editable).toBe(false)
+    expect(leaf?.fill).toBe("#ffffff")
+  })
+
+  it("leaferToDoc 将 tag=Frame 的节点还原为 type=frame 节点（roundtrip 保留 name）", () => {
+    const doc = docWithFrame({ id: "f1", name: "首页", x: 10, y: 20, width: 390, height: 844 })
+    const { leafer } = docToScene(doc, mod)
+    const back = leaferToDoc(leafer)
+    const frame = back.nodes.find((n) => n.id === "f1")
+    expect(frame?.type).toBe("frame")
+    expect(frame?.kind).toBe("group")
+    expect(frame?.name).toBe("首页")
+    expect(frame?.x).toBe(10)
+    expect(frame?.width).toBe(390)
+    expect(frame?.style?.fill).toBe("#ffffff")
+  })
+
+  it("leaferToDoc 剥离 board 的 fill（防主题色污染入库）", () => {
+    const doc = docWithFrame({ id: "f1" })
+    const { leafer } = docToScene(doc, mod)
+    const back = leaferToDoc(leafer)
+    const board = back.nodes.find((n) => n.id === BOARD_NODE_ID)
+    expect(board?.style?.fill).toBeUndefined()
+  })
+})
+
+
+describe("官方 JSON 权威格式（R2）", () => {
+  const pkgTree = {
+    tag: "Leafer",
+    hittable: true,
+    children: [
+      {
+        tag: "Group",
+        id: BOARD_NODE_ID,
+        width: 1200,
+        height: 812,
+        children: [
+          {
+            tag: "Frame",
+            id: "frame_1",
+            name: "首页",
+            x: 80,
+            y: 60,
+            width: 390,
+            height: 844,
+            editable: false,
+          },
+          {
+            tag: "Rect",
+            id: "rect_1",
+            name: "卡片",
+            x: 500,
+            y: 120,
+            width: 320,
+            height: 180,
+            fill: [{ type: "solid", color: "#3b82f6", opacity: 1, visible: true }],
+            cornerRadius: 12,
+          },
+        ],
+      },
+    ],
+  }
+
+  it("isLeaferJSONPackage 识别新格式并拒绝旧格式/脏数据", () => {
+    expect(isLeaferJSONPackage({ format: "leafer-json", version: 1, meta: {}, tree: {} })).toBe(true)
+    expect(isLeaferJSONPackage({ version: 1, meta: {}, nodes: [] })).toBe(false)
+    expect(isLeaferJSONPackage({ format: "leafer-json", version: 2, tree: {} })).toBe(false)
+    expect(isLeaferJSONPackage(null)).toBe(false)
+    expect(isLeaferJSONPackage("x")).toBe(false)
+  })
+
+  it("parseLeaferJSON 官方树还原 SceneDocument（tag→type、嵌套→parentId）", () => {
+    const doc = parseLeaferJSON({
+      format: "leafer-json",
+      version: 1,
+      meta: { device: "desktop" },
+      tree: pkgTree,
+    })
+    expect(doc.nodes[0].id).toBe(BOARD_NODE_ID)
+    const frame = doc.nodes.find((n) => n.id === "frame_1")
+    expect(frame).toMatchObject({ type: "frame", parentId: BOARD_NODE_ID, x: 80, y: 60, width: 390, height: 844 })
+    expect(frame?.name).toBe("首页")
+    const rect = doc.nodes.find((n) => n.id === "rect_1")
+    expect(rect?.type).toBe("rect")
+    // leafer fill paint 数组原样进结构化 fills（读侧样式迁移）
+    expect(rect?.fills?.[0]).toMatchObject({ type: "solid", color: "#3b82f6" })
+    expect(rect?.corners).toEqual([12, 12, 12, 12])
+  })
+
+  it("parseLeaferJSON 回填 extensions 业务字段", () => {
+    const doc = parseLeaferJSON({
+      format: "leafer-json",
+      version: 1,
+      meta: {},
+      tree: pkgTree,
+      extensions: {
+        rect_1: {
+          props: { aiRole: "card" },
+          constraints: { horizontal: "center", vertical: "stretch" },
+        },
+      },
+    })
+    const rect = doc.nodes.find((n) => n.id === "rect_1")
+    expect(rect?.props).toEqual({ aiRole: "card" })
+    expect(rect?.constraints).toEqual({ horizontal: "center", vertical: "stretch" })
+  })
+
+  it("exportLeaferJSON 收集扩展字段并包装 meta", () => {
+    const doc = createEmptyDoc("desktop")
+    doc.nodes.push({
+      ...createBoardNode("desktop"),
+      id: "rect_x",
+      kind: "shape",
+      type: "rect",
+      parentId: BOARD_NODE_ID,
+      x: 0,
+      y: 0,
+      width: 10,
+      height: 10,
+      props: { aiRole: "btn" },
+      constraints: { horizontal: "min", vertical: "min" },
+    })
+    // mock tree：toJSON 返回官方树形态（含 zoomLayer 视图变换污染）
+    const tree = {
+      toJSON: () => ({ ...pkgTree, scaleX: 0.71, scaleY: 0.71, x: 123.45, y: -11.2 }),
+    } as unknown as ILeaf
+    const pkg = exportLeaferJSON(doc, tree)
+    // 根级视图变换必须剥离（zoomLayer 即 tree，视图状态不入库）
+    expect(pkg.tree.scaleX).toBeUndefined()
+    expect(pkg.tree.x).toBeUndefined()
+    expect(pkg.format).toBe("leafer-json")
+    expect(pkg.version).toBe(1)
+    expect(pkg.meta.device).toBe("desktop")
+    expect(pkg.tree).toEqual(pkgTree)
+    expect(pkg.extensions?.rect_x).toEqual({
+      props: { aiRole: "btn" },
+      constraints: { horizontal: "min", vertical: "min" },
+    })
+    // board 无扩展字段不进 extensions
+    expect(pkg.extensions?.board).toBeUndefined()
+  })
+
+  it("exportLeaferJSON → parseLeaferJSON 双格式 roundtrip 保真", () => {
+    const doc = createEmptyDoc("tablet")
+    doc.nodes.push({
+      ...createBoardNode("tablet"),
+      id: "rect_1",
+      kind: "shape",
+      type: "rect",
+      parentId: BOARD_NODE_ID,
+      x: 12,
+      y: 34,
+      width: 56,
+      height: 78,
+      fills: [{ id: "p1", type: "solid", color: "#123456", opacity: 0.9, visible: true }],
+      corners: [4, 8, 2, 6],
+      props: { aiHint: "hero" },
+    })
+    const tree = { toJSON: () => pkgTree } as unknown as ILeaf
+    const pkg = exportLeaferJSON(doc, tree)
+    const back = parseLeaferJSON(pkg)
+    // meta 经包装层往返
+    expect(back.meta.device).toBe("tablet")
+    // 扩展字段往返
+    const rect = back.nodes.find((n) => n.id === "rect_1")
+    expect(rect?.props).toEqual({ aiHint: "hero" })
+  })
+
+  // ===== frame.locked 序列化 round trip（任务 16 修复轮次 1）=====
+  // frame.locked 不投影 leaf（P0：locked 剪枝子树），持久化走 extensions，
+  // 读回经 extensions 回填 + sanitizeNode 不再剥离；这是锁定画板保真的主通道
+  // 显式构造 frame 节点：createBoardNode 携带 locked:true（board 语义），不可展开复用
+  const makeFrameNode = (locked?: boolean): SceneNode => ({
+    id: "frame_1",
+    kind: "group",
+    type: "frame",
+    parentId: BOARD_NODE_ID,
+    name: "首页",
+    x: 80,
+    y: 60,
+    width: 390,
+    height: 844,
+    ...(locked === undefined ? {} : { locked }),
+  })
+
+  it("锁定 frame → exportLeaferJSON → parseLeaferJSON → locked 保真（真实链路）", () => {
+    const doc = createEmptyDoc("desktop")
+    doc.nodes.push(makeFrameNode(true))
+    const tree = { toJSON: () => pkgTree } as unknown as ILeaf
+
+    // 导出：locked 仅对 frame 进 extensions（tree JSON 无法表达）
+    const pkg = exportLeaferJSON(doc, tree)
+    expect(pkg.extensions?.frame_1?.locked).toBe(true)
+
+    // 解析：extensions 回填 + sanitize 保留（不再剥离 frame 顶层 locked）
+    const back = parseLeaferJSON(pkg)
+    const frame = back.nodes.find((n) => n.id === "frame_1")
+    expect(frame?.type).toBe("frame")
+    expect(frame?.locked).toBe(true)
+  })
+
+  it("未锁定 frame round trip：extensions 无 locked 键、读回无 locked 残留", () => {
+    const doc = createEmptyDoc("desktop")
+    doc.nodes.push(makeFrameNode())
+    const tree = { toJSON: () => pkgTree } as unknown as ILeaf
+
+    const pkg = exportLeaferJSON(doc, tree)
+    // editable:false 是画板结构态，不得推导成 extensions.locked
+    expect(pkg.extensions?.frame_1).toBeUndefined()
+
+    const back = parseLeaferJSON(pkg)
+    const frame = back.nodes.find((n) => n.id === "frame_1")
+    expect(frame?.type).toBe("frame")
+    expect(frame?.locked).toBeUndefined()
+  })
+
+  it("引擎读回 preserveFrom 恢复 frame.locked；非锁定 frame 无 locked 残留", () => {
+    const frameDesc = {
+      tag: "Leafer",
+      children: [
+        {
+          tag: "Group",
+          id: BOARD_NODE_ID,
+          width: 1200,
+          height: 812,
+          children: [
+            {
+              tag: "Frame",
+              id: "frame_1",
+              name: "首页",
+              x: 80,
+              y: 60,
+              width: 390,
+              height: 844,
+              // 写侧恒 editable:false（结构态），leaf 上无 locked
+              editable: false,
+            },
+          ],
+        },
+      ],
+    }
+    const makePrev = (locked: boolean | undefined): SceneDocument => ({
+      version: 1,
+      meta: { device: "desktop" },
+      nodes: [createBoardNode("desktop"), makeFrameNode(locked)],
+    })
+
+    // 引擎读回（preserveFrom=currentDoc）：锁定态从 preserve 恢复，
+    // 不因 leaf 的 editable:false 结构态误推导
+    const lockedBack = leaferToDoc(frameDesc as unknown as ILeaf, {
+      preserveFrom: makePrev(true),
+    })
+    expect(lockedBack.nodes.find((n) => n.id === "frame_1")?.locked).toBe(true)
+
+    // 反向：未锁定 frame 读回无 locked 键残留（editable:false 不推导锁定）
+    const unlockedBack = leaferToDoc(frameDesc as unknown as ILeaf, {
+      preserveFrom: makePrev(undefined),
+    })
+    expect(unlockedBack.nodes.find((n) => n.id === "frame_1")?.locked).toBeUndefined()
+  })
+
+  // ===== ShaderPaint 序列化 round trip（任务 18，FS-7.4）=====
+  // doc.fills 经 extensions 持久化（事实源，tree 的 leafer://shader/ url 无法
+  // 承载 shaderId/props/speed）；读回时 tree fill url 以 leafer://shader/ 开头
+  // → 优先取 extensions.fills 整组恢复（含不可见层），避免 url 失效
+  const SHADER_FILLS: SceneNode["fills"] = [
+    {
+      id: "p_sha",
+      type: "shader",
+      shaderId: "mesh-gradient",
+      props: { colors: ["#ff0000", "#00ff00"], distortion: 0.5 },
+      speed: 1.5,
+      opacity: 1,
+      visible: true,
+    },
+    { id: "p_hidden", type: "solid", color: "#123456", opacity: 0.8, visible: false },
+  ]
+
+  // 写侧投影形态的 tree mock：shader 层投影为 image paint url，不可见层不投影
+  const shaderTree = {
+    tag: "Leafer",
+    children: [
+      {
+        tag: "Group",
+        id: BOARD_NODE_ID,
+        width: 1200,
+        height: 812,
+        children: [
+          {
+            tag: "Rect",
+            id: "rect_x",
+            x: 0,
+            y: 0,
+            width: 100,
+            height: 80,
+            fill: [{ type: "image", url: "leafer://shader/rect_x/p_sha", opacity: 1, visible: true }],
+          },
+        ],
+      },
+    ],
+  }
+
+  const shaderDoc = (): SceneDocument => {
+    const doc = createEmptyDoc("desktop")
+    doc.nodes.push({
+      ...createBoardNode("desktop"),
+      id: "rect_x",
+      kind: "shape",
+      type: "rect",
+      parentId: BOARD_NODE_ID,
+      x: 0,
+      y: 0,
+      width: 100,
+      height: 80,
+      fills: SHADER_FILLS,
+    })
+    return doc
+  }
+
+  it("ShaderPaint 文档 export→parse：ShaderPaint 完整恢复（shaderId/props/speed，extensions 优先）", () => {
+    const pkg = exportLeaferJSON(shaderDoc(), { toJSON: () => shaderTree } as unknown as ILeaf)
+    // extensions.fills 是事实源：整组持久化（含 tree 投影丢弃的不可见层）
+    expect(pkg.extensions?.rect_x?.fills).toEqual(SHADER_FILLS)
+
+    const back = parseLeaferJSON(pkg)
+    const rect = back.nodes.find((n) => n.id === "rect_x")
+    expect(rect?.fills?.[0]).toMatchObject({
+      id: "p_sha",
+      type: "shader",
+      shaderId: "mesh-gradient",
+      props: { colors: ["#ff0000", "#00ff00"], distortion: 0.5 },
+      speed: 1.5,
+      opacity: 1,
+      visible: true,
+    })
+    // 整组恢复：不可见层同样保真（读回不再走 tree 投影的逐条还原）
+    expect(rect?.fills?.[1]).toMatchObject({ id: "p_hidden", type: "solid", visible: false })
+  })
+
+  it("无 shader 的节点 fills 不进 extensions（体积守卫）", () => {
+    const doc = createEmptyDoc("desktop")
+    doc.nodes.push({
+      ...createBoardNode("desktop"),
+      id: "rect_plain",
+      kind: "shape",
+      type: "rect",
+      parentId: BOARD_NODE_ID,
+      x: 0,
+      y: 0,
+      width: 10,
+      height: 10,
+      fills: [{ id: "p1", type: "solid", color: "#123456", opacity: 1, visible: true }],
+    })
+    const pkg = exportLeaferJSON(doc, { toJSON: () => pkgTree } as unknown as ILeaf)
+    expect(pkg.extensions?.rect_plain?.fills).toBeUndefined()
+  })
+
+  it("tree 有 shader url 但 extensions 缺失（旧数据）→ 降级灰不丢节点", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {})
+    const back = parseLeaferJSON({
+      format: "leafer-json",
+      version: 1,
+      meta: {},
+      tree: shaderTree,
+    })
+    const rect = back.nodes.find((n) => n.id === "rect_x")
+    expect(rect?.fills?.[0]).toMatchObject({ type: "solid", color: "#9ca3af" })
+    warn.mockRestore()
+  })
+
+  it("strokes 含 shader paint 同通道持久化与恢复", () => {
+    const doc = createEmptyDoc("desktop")
+    doc.nodes.push({
+      ...createBoardNode("desktop"),
+      id: "rect_s",
+      kind: "shape",
+      type: "rect",
+      parentId: BOARD_NODE_ID,
+      x: 0,
+      y: 0,
+      width: 50,
+      height: 50,
+      strokes: [
+        {
+          id: "s1",
+          paint: {
+            id: "p_st",
+            type: "shader",
+            shaderId: "swirl",
+            props: { swirl: 0.6 },
+            speed: 0.5,
+            opacity: 1,
+            visible: true,
+          },
+          width: 2,
+          visible: true,
+        },
+      ],
+    })
+    const strokeTree = {
+      tag: "Leafer",
+      children: [
+        {
+          tag: "Group",
+          id: BOARD_NODE_ID,
+          width: 1200,
+          height: 812,
+          children: [
+            {
+              tag: "Rect",
+              id: "rect_s",
+              x: 0,
+              y: 0,
+              width: 50,
+              height: 50,
+              stroke: [{ type: "image", url: "leafer://shader/rect_s/p_st", opacity: 1, visible: true }],
+              strokeWidth: 2,
+            },
+          ],
+        },
+      ],
+    }
+    const pkg = exportLeaferJSON(doc, { toJSON: () => strokeTree } as unknown as ILeaf)
+    expect(pkg.extensions?.rect_s?.strokes?.[0]?.paint).toMatchObject({ type: "shader", shaderId: "swirl", speed: 0.5 })
+    const back = parseLeaferJSON(pkg)
+    const rect = back.nodes.find((n) => n.id === "rect_s")
+    expect(rect?.strokes?.[0]?.paint).toMatchObject({ id: "p_st", type: "shader", shaderId: "swirl", props: { swirl: 0.6 }, speed: 0.5 })
+  })
+
+  // ===== 最终审查 B1：真实 getJSON 树回放（渐变/多描边保真）=====
+  // 此前 roundtrip 测试没抓住：测试路径的 paint 带手工 id 且未走真实工厂链。
+  // 本用例的 tree 节点为修复后真实链路 getJSON() 的逐字节形态（浏览器实测
+  // dump）：leafer 已丢弃 paint 自定义 id（restorePaint 会补生成，无碍），
+  // 主题色缺省场景为 oklch 字符串（isColorString 必须放行）
+  it("真实 getJSON 树回放：线性渐变 + 多描边 parseLeaferJSON 保真（B1）", async () => {
+    const { SHADER_URL_PREFIX } = await import("../style/paints")
+    void SHADER_URL_PREFIX
+    const realTree = {
+      tag: "Leafer",
+      children: [
+        {
+          tag: "Group",
+          id: BOARD_NODE_ID,
+          width: 1200,
+          height: 812,
+          children: [
+            {
+              tag: "Rect",
+              id: "rect_grad",
+              x: 200,
+              y: 150,
+              width: 320,
+              height: 240,
+              // 浏览器真实 dump（修复后链路）：投影数组原样入树
+              fill: [
+                {
+                  type: "linear",
+                  stops: [
+                    { offset: 0, color: "#ff0000" },
+                    { offset: 1, color: "#0000ff" },
+                  ],
+                  from: { type: "percent", x: 0, y: 0 },
+                  to: { type: "percent", x: 1, y: 1 },
+                  opacity: 0.9,
+                  visible: true,
+                },
+              ],
+              stroke: [
+                { type: "solid", color: "#ffaa00", opacity: 1, visible: true },
+                { type: "solid", color: "rgba(0, 204, 136, 0.7)", opacity: 1, visible: true },
+              ],
+              strokeWidth: 2,
+            },
+            {
+              tag: "Rect",
+              id: "rect_oklch",
+              x: 600,
+              y: 150,
+              width: 100,
+              height: 80,
+              // 主题色缺省形态：工厂 fallback = getComputedStyle 产 oklch
+              fill: [{ type: "solid", color: "oklch(0.228 0.013 107.4)", opacity: 1, visible: true }],
+              stroke: "oklch(0.966 0.005 106.5)",
+              strokeWidth: 1,
+            },
+          ],
+        },
+      ],
+    }
+    const back = parseLeaferJSON({ format: "leafer-json", version: 1, meta: {}, tree: realTree })
+    const grad = back.nodes.find((n) => n.id === "rect_grad")
+    // 渐变完整恢复（stops/from/to/opacity；id 由读侧补生成——leafer 丢弃自定义 id）
+    expect(grad?.fills).toHaveLength(1)
+    expect(grad?.fills?.[0]).toMatchObject({
+      type: "linear",
+      stops: [
+        { offset: 0, color: "#ff0000" },
+        { offset: 1, color: "#0000ff" },
+      ],
+      from: { x: 0, y: 0 },
+      to: { x: 1, y: 1 },
+      opacity: 0.9,
+    })
+    expect(grad?.fills?.[0]?.id).toMatch(/^p_/)
+    // 多描边逐条恢复（不坍缩单描边）
+    expect(grad?.strokes).toHaveLength(2)
+    expect(grad?.strokes?.[0]).toMatchObject({ width: 2, paint: { type: "solid", color: "#ffaa00" } })
+    expect(grad?.strokes?.[1]?.paint).toMatchObject({ type: "solid", color: "rgba(0, 204, 136, 0.7)" })
+    // 主题 oklch 色型不降级灰（isColorString 放行）
+    const oklchNode = back.nodes.find((n) => n.id === "rect_oklch")
+    expect(oklchNode?.fills?.[0]).toMatchObject({ type: "solid", color: "oklch(0.228 0.013 107.4)" })
+    expect(oklchNode?.strokes?.[0]?.paint).toMatchObject({ color: "oklch(0.966 0.005 106.5)" })
+  })
+
+  it("normalizeSceneDocument 三分支：新格式/旧格式/脏数据", () => {
+    const fresh = normalizeSceneDocument({
+      format: "leafer-json",
+      version: 1,
+      meta: { device: "mobile" },
+      tree: pkgTree,
+    })
+    expect(fresh.meta.device).toBe("mobile")
+    expect(fresh.nodes.length).toBeGreaterThan(1)
+
+    const legacy = normalizeSceneDocument(createEmptyDoc("desktop"))
+    expect(legacy.nodes[0].id).toBe(BOARD_NODE_ID)
+
+    const fallback = normalizeSceneDocument({ garbage: true })
+    expect(fallback.nodes).toHaveLength(1)
+    expect(fallback.nodes[0].id).toBe(BOARD_NODE_ID)
+  })
+})
+
+// ===== 节点类型精确映射与旧钢笔数据迁移（FS-2.4） =====
+
+describe("节点类型精确映射与 pen-path 迁移", () => {
+  // Polygon/Star/Path 的真实 leafer leaf toJSON 自带 tag，mock 构造器补 tag
+  // 以还原该行为（docToScene 产 leaf → leaferToDoc 读回才能命中 TAG_TYPE）
+  function taggedCtor(tag: string) {
+    return class {
+      static one = vi.fn(
+        (
+          config: Record<string, unknown> = {},
+          x = 0,
+          y = 0,
+          w = 0,
+          h = 0,
+        ): MockElement => {
+          const element: MockElement = {
+            ...config,
+            tag,
+            id: undefined,
+            x,
+            y,
+            width: w,
+            height: h,
+            children: [],
+            add: vi.fn(),
+          }
+          element.add = vi.fn((child: unknown) => {
+            element.children.push(child)
+          })
+          return element
+        },
+      )
+    }
+  }
+
+  function shapeMod() {
+    return {
+      ...mockMod(),
+      Polygon: taggedCtor("Polygon"),
+      Star: taggedCtor("Star"),
+      Path: taggedCtor("Path"),
+    } as unknown as typeof import("leafer-editor")
+  }
+
+  const shapeTree = {
+    width: 400,
+    height: 300,
+    children: [
+      {
+        tag: "Polygon",
+        id: "poly_1",
+        x: 10,
+        y: 10,
+        width: 100,
+        height: 100,
+        fill: "#fff",
+        sides: 6,
+        curve: 0.5,
+      },
+      {
+        tag: "Star",
+        id: "star_1",
+        x: 130,
+        y: 10,
+        width: 100,
+        height: 100,
+        corners: 5,
+        innerRadius: 0.382,
+        cornerRadius: 6,
+      },
+      {
+        tag: "Path",
+        id: "path_1",
+        x: 250,
+        y: 10,
+        width: 100,
+        height: 50,
+        path: "M0,0 L100,50",
+        stroke: "#000",
+        strokeWidth: 2,
+      },
+    ],
+  }
+
+  it("tag Polygon/Star/Path 精确映射为 polygon/star/path（不再归一 pen-path）", () => {
+    const doc = leaferToDoc(shapeTree as unknown as ILeaf)
+    expect(doc.nodes.find((n) => n.id === "poly_1")!.type).toBe("polygon")
+    expect(doc.nodes.find((n) => n.id === "star_1")!.type).toBe("star")
+    expect(doc.nodes.find((n) => n.id === "path_1")!.type).toBe("path")
+  })
+
+  it("图形参数透传：sides/corners/innerRadius 进 style，path 进 props", () => {
+    const doc = leaferToDoc(shapeTree as unknown as ILeaf)
+    const poly = doc.nodes.find((n) => n.id === "poly_1")!
+    const star = doc.nodes.find((n) => n.id === "star_1")!
+    const path = doc.nodes.find((n) => n.id === "path_1")!
+    expect(poly.style).toMatchObject({ sides: 6, curve: 0.5 })
+    expect(star.style).toMatchObject({ corners: 5, innerRadius: 0.382, cornerRadius: 6 })
+    expect(path.props).toMatchObject({ path: "M0,0 L100,50" })
+  })
+
+  it("doc → leafer → doc round trip 不丢类型与图形参数", () => {
+    const mod = shapeMod()
+    const first = leaferToDoc(shapeTree as unknown as ILeaf)
+    const { leafer } = docToScene(first, mod)
+    expect(mod.Polygon.one).toHaveBeenCalled()
+    expect(mod.Star.one).toHaveBeenCalled()
+    expect(mod.Path.one).toHaveBeenCalled()
+    const second = leaferToDoc(leafer)
+    const poly = second.nodes.find((n) => n.id === "poly_1")!
+    const star = second.nodes.find((n) => n.id === "star_1")!
+    const path = second.nodes.find((n) => n.id === "path_1")!
+    expect(poly.type).toBe("polygon")
+    expect(poly.style).toMatchObject({ sides: 6, curve: 0.5, fill: "#fff" })
+    expect(star.type).toBe("star")
+    expect(star.style).toMatchObject({ corners: 5, innerRadius: 0.382, cornerRadius: 6 })
+    expect(path.type).toBe("path")
+    expect(path.props).toMatchObject({ path: "M0,0 L100,50" })
+    expect(path.style).toMatchObject({ stroke: "#000", strokeWidth: 2 })
+  })
+
+  it("旧 pen-path 文档读入 normalizeSceneDocument 全部迁移为 path 且 props.path 保留", () => {
+    const legacy: SceneDocument = {
+      version: 1,
+      meta: {},
+      nodes: [
+        createBoardNode("desktop"),
+        {
+          id: "pen1",
+          kind: "shape",
+          type: "pen-path",
+          parentId: BOARD_NODE_ID,
+          x: 0,
+          y: 0,
+          width: 100,
+          height: 50,
+          style: { stroke: "#000", strokeWidth: 2 },
+          props: { path: "M0,0 L100,50" },
+        },
+        {
+          id: "pen2",
+          kind: "shape",
+          type: "pen-path",
+          parentId: BOARD_NODE_ID,
+          x: 40,
+          y: 40,
+          width: 80,
+          height: 80,
+          style: { stroke: "#123456", strokeWidth: 3 },
+          props: { path: "M0,0 Q40,40 80,80" },
+        },
+      ],
+    }
+    const doc = normalizeSceneDocument(legacy)
+    for (const id of ["pen1", "pen2"]) {
+      const node = doc.nodes.find((n) => n.id === id)!
+      expect(node.type).toBe("path")
+      expect(node.props?.path).toBeTruthy()
+    }
+    expect(doc.nodes.find((n) => n.id === "pen1")!.props).toMatchObject({ path: "M0,0 L100,50" })
+    expect(doc.nodes.find((n) => n.id === "pen1")!.style).toMatchObject({
+      stroke: "#000",
+      strokeWidth: 2,
+    })
+  })
+
+  it("pen-path 迁移幂等：迁移后二次读入结果一致", () => {
+    const legacy: SceneDocument = {
+      version: 1,
+      meta: {},
+      nodes: [
+        createBoardNode("desktop"),
+        {
+          id: "pen1",
+          kind: "shape",
+          type: "pen-path",
+          parentId: BOARD_NODE_ID,
+          x: 0,
+          y: 0,
+          width: 100,
+          height: 50,
+          style: { stroke: "#000" },
+          props: { path: "M0,0 L100,50" },
+        },
+      ],
+    }
+    const once = normalizeSceneDocument(legacy)
+    const twice = normalizeSceneDocument(once)
+    expect(twice).toEqual(once)
+  })
+})
+
+// ===== FS-9 箭头插件 + 读侧对称回收（任务 13）+ fill:none 增量治理（R11） =====
+describe("FS-9 箭头 props 透传与读侧对称", () => {
+  afterEach(() => {
+    registry.clear()
+  })
+
+  const arrowTree = {
+    width: 400,
+    height: 300,
+    children: [
+      {
+        tag: "Arrow",
+        id: "arrow_1",
+        x: 10,
+        y: 10,
+        width: 100,
+        height: 0,
+        stroke: "#000",
+        strokeWidth: 2,
+        startArrow: "circle",
+        endArrow: "arrow",
+      },
+    ],
+  }
+
+  it("arrow 节点 props { startArrow, endArrow } round trip 保留", () => {
+    const doc = leaferToDoc(arrowTree as unknown as ILeaf)
+    const arrow = doc.nodes.find((n) => n.id === "arrow_1")!
+    expect(arrow.type).toBe("arrow")
+    expect(arrow.props).toMatchObject({ startArrow: "circle", endArrow: "arrow" })
+
+    // doc → leafer → doc 二次回读仍保留
+    function taggedCtor(tag: string) {
+      return class {
+        static one = vi.fn((config: Record<string, unknown> = {}, x = 0, y = 0, w = 0, h = 0) => ({
+          ...config,
+          tag,
+          id: undefined,
+          x,
+          y,
+          width: w,
+          height: h,
+          children: [],
+          add: vi.fn((child: unknown) => {
+            ;(config as { children?: unknown[] }).children?.push(child)
+          }),
+        }))
+      }
+    }
+    const mod = {
+      ...mockMod(),
+      Arrow: taggedCtor("Arrow"),
+    } as unknown as typeof import("leafer-editor")
+    const { leafer } = docToScene(doc, mod)
+    const second = leaferToDoc(leafer)
+    const arrowAgain = second.nodes.find((n) => n.id === "arrow_1")!
+    expect(arrowAgain.props).toMatchObject({ startArrow: "circle", endArrow: "arrow" })
+  })
+
+  it("startArrow/endArrow 进 SHAPE_PROP_KEYS 白名单（增量 patch 渲染配置注入）", () => {
+    const node: SceneNode = {
+      id: "a1",
+      kind: "shape",
+      type: "arrow",
+      parentId: BOARD_NODE_ID,
+      x: 0,
+      y: 0,
+      width: 100,
+      height: 0,
+      props: { startArrow: "circle", endArrow: "arrow", malicious: "junk" },
+    }
+    const config = leafConfigOf(node)
+    expect(config.startArrow).toBe("circle")
+    expect(config.endArrow).toBe("arrow")
+    expect(config.malicious).toBeUndefined()
+  })
+
+  it("回读 rotation 提升顶层 node.rotation 且不残留 style（旋转→回读→redo 不丢失）", () => {
+    const tree = {
+      width: 400,
+      height: 300,
+      children: [
+        { tag: "Rect", id: "r1", x: 0, y: 0, width: 50, height: 50, fill: "#fff", rotation: 30 },
+      ],
+    }
+    const doc = leaferToDoc(tree as unknown as ILeaf)
+    const rect = doc.nodes.find((n) => n.id === "r1")!
+    expect(rect.rotation).toBe(30)
+    expect(rect.style?.rotation).toBeUndefined()
+  })
+
+  it("doc → leafer → doc round trip 保持 node.rotation（全量重建后 redo 视觉不转正）", () => {
+    const doc: SceneDocument = {
+      version: 1,
+      meta: {},
+      nodes: [
+        createBoardNode("desktop"),
+        {
+          id: "r2",
+          kind: "shape",
+          type: "rect",
+          parentId: BOARD_NODE_ID,
+          x: 0,
+          y: 0,
+          width: 50,
+          height: 50,
+          rotation: 30,
+          style: { fill: "#fff" },
+        },
+      ],
+    }
+    const { leafer } = docToScene(doc, mockMod())
+    const second = leaferToDoc(leafer)
+    const rect = second.nodes.find((n) => n.id === "r2")!
+    expect(rect.rotation).toBe(30)
+  })
+
+  it("回读图形参数恢复 props（sides 等）且 style 保留（工厂重建双通道对称）", () => {
+    const polyTree = {
+      width: 400,
+      height: 300,
+      children: [
+        {
+          tag: "Polygon",
+          id: "poly_p",
+          x: 10,
+          y: 10,
+          width: 100,
+          height: 100,
+          sides: 6,
+          curve: 0.5,
+        },
+        {
+          tag: "Star",
+          id: "star_p",
+          x: 130,
+          y: 10,
+          width: 100,
+          height: 100,
+          corners: 5,
+          innerRadius: 0.382,
+          cornerRadius: 6,
+        },
+      ],
+    }
+    const doc = leaferToDoc(polyTree as unknown as ILeaf)
+    const poly = doc.nodes.find((n) => n.id === "poly_p")!
+    expect(poly.props).toMatchObject({ sides: 6, curve: 0.5 })
+    // style 通道保留：polygon/star 工厂全量重建消费 style 参数
+    expect(poly.style).toMatchObject({ sides: 6, curve: 0.5 })
+    const star = doc.nodes.find((n) => n.id === "star_p")!
+    expect(star.props).toMatchObject({ corners: 5, innerRadius: 0.382 })
+    // cornerRadius 不提升（node.corners 投影双源冲突），style 保留
+    expect(star.props?.cornerRadius).toBeUndefined()
+    expect(star.style).toMatchObject({ cornerRadius: 6 })
+  })
+})
+
+describe("fill:none / stroke:none 治理（R11）", () => {
+  afterEach(() => {
+    registry.clear()
+  })
+
+  it("增量 leafConfigOf：fills 清空投影 fill:none 翻译为 null（leaf.set 可清除旧填充）", () => {
+    const node: SceneNode = {
+      id: "f1",
+      kind: "shape",
+      type: "rect",
+      parentId: BOARD_NODE_ID,
+      x: 0,
+      y: 0,
+      width: 50,
+      height: 50,
+      fills: [],
+    }
+    expect(leafConfigOf(node).fill).toBeNull()
+  })
+
+  it("增量 leafConfigOf：strokes 清空投影 stroke:none 翻译为 null（旧描边可清除）", () => {
+    const node: SceneNode = {
+      id: "f2",
+      kind: "shape",
+      type: "rect",
+      parentId: BOARD_NODE_ID,
+      x: 0,
+      y: 0,
+      width: 50,
+      height: 50,
+      strokes: [],
+    }
+    expect(leafConfigOf(node).stroke).toBeNull()
+  })
+
+  it("构造路径 buildOne：style.fill=none 翻译为 null（与增量路径行为一致）", () => {
+    const doc: SceneDocument = {
+      version: 1,
+      meta: {},
+      nodes: [
+        createBoardNode("desktop"),
+        {
+          id: "f3",
+          kind: "shape",
+          type: "rect",
+          parentId: BOARD_NODE_ID,
+          x: 0,
+          y: 0,
+          width: 50,
+          height: 50,
+          style: { fill: "none", stroke: "none" },
+        },
+      ],
+    }
+    const { nodeIndex } = docToScene(doc, mockMod())
+    const leaf = nodeIndex.get("f3") as unknown as Record<string, unknown>
+    expect(leaf.fill).toBeNull()
+    expect(leaf.stroke).toBeNull()
+  })
+})